Return to expr.1 CVS log

Up to [cvs.NetBSD.org] / src / bin / expr

Annotation of src/bin/expr/expr.1, Revision 1.22

1.22    ! grant       1: .\"    $NetBSD: expr.1,v 1.21 2002/09/25 15:18:39 wiz Exp $
1.8       cgd         2: .\"
1.22    ! grant       3: .\" Written by J.T. Conklin <jtc@NetBSD.org>.
1.9       jtc         4: .\" Public domain.
1.1       jtc         5: .\"
1.14      jdolecek    6: .Dd September 18, 2000
1.1       jtc         7: .Dt EXPR 1
                      8: .Os
                      9: .Sh NAME
                     10: .Nm expr
                     11: .Nd evaluate expression
                     12: .Sh SYNOPSIS
1.10      enami      13: .Nm
1.1       jtc        14: .Ar expression
                     15: .Sh DESCRIPTION
                     16: The
1.10      enami      17: .Nm
1.16      jdolecek   18: utility evaluates
1.1       jtc        19: .Ar expression
                     20: and writes the result on standard output.
                     21: .Pp
                     22: All operators are separate arguments to the
1.10      enami      23: .Nm
1.1       jtc        24: utility.
                     25: Characters special to the command interpreter must be escaped.
                     26: .Pp
1.6       jtc        27: Operators are listed below in order of increasing precedence.
                     28: Operators with equal precedence are grouped within { } symbols.
1.1       jtc        29: .Bl -tag -width indent
                     30: .It Ar expr1 Li | Ar expr2
1.16      jdolecek   31: Returns the evaluation of
                     32: .Ar expr1
1.1       jtc        33: if it is neither an empty string nor zero;
                     34: otherwise, returns the evaluation of
                     35: .Ar expr2 .
1.19      ross       36: .It Ar expr1 Li \*[Am] Ar expr2
1.1       jtc        37: Returns the evaluation of
                     38: .Ar expr1
                     39: if neither expression evaluates to an empty string or zero;
                     40: otherwise, returns zero.
1.19      ross       41: .It Ar expr1 Li "{=, \*[Gt], \*[Ge], \*[Lt], \*[Le], !=}" Ar expr2
1.16      jdolecek   42: Returns the results of integer comparison if both arguments are integers;
1.3       jtc        43: otherwise, returns the results of string comparison using the locale-specific
                     44: collation sequence.
1.1       jtc        45: The result of each comparison is 1 if the specified relation is true,
                     46: or 0 if the relation is false.
                     47: .It Ar expr1 Li "{+, -}" Ar expr2
                     48: Returns the results of addition or subtraction of integer-valued arguments.
                     49: .It Ar expr1 Li "{*, /, %}" Ar expr2
                     50: Returns the results of multiplication, integer division, or remainder of integer-valued arguments.
                     51: .It Ar expr1 Li : Ar expr2
1.16      jdolecek   52: The
1.17      wiz        53: .Dq \&:
1.16      jdolecek   54: operator matches
                     55: .Ar expr1
                     56: against
1.1       jtc        57: .Ar expr2 ,
1.21      wiz        58: which must be a regular expression.
                     59: The regular expression is anchored
1.16      jdolecek   60: to the beginning of  the string with an implicit
1.5       jtc        61: .Dq ^ .
1.1       jtc        62: .Pp
1.5       jtc        63: If the match succeeds and the pattern contains at least one regular
1.16      jdolecek   64: expression subexpression
                     65: .Dq "\e(...\e)" ,
                     66: the string corresponding to
1.1       jtc        67: .Dq "\e1"
                     68: is returned;
1.16      jdolecek   69: otherwise the matching operator returns the number of characters matched.
1.5       jtc        70: If the match fails and the pattern contains a regular expression subexpression
                     71: the null string is returned;
                     72: otherwise 0.
1.15      jdolecek   73: .It Ar "( " expr Li " )"
                     74: Parentheses are used for grouping in the usual manner.
1.1       jtc        75: .El
                     76: .Pp
1.15      jdolecek   77: Operator precedence (from highest to lowest):
                     78: .Bl -enum -compact -offset indent
                     79: .It
                     80: parentheses
                     81: .It
1.17      wiz        82: .Dq \&:
1.16      jdolecek   83: .It
                     84: .Dq "*" ,
                     85: .Dq "/" ,
                     86: and
                     87: .Dq "%"
                     88: .It
                     89: .Dq "+"
                     90: and
                     91: .Dq "-"
                     92: .It
                     93: compare operators
1.15      jdolecek   94: .It
1.19      ross       95: .Dq \*[Am]
1.15      jdolecek   96: .It
                     97: .Dq \Z'\*[tty-rn]'|
                     98: .El
1.18      wiz        99: .Sh EXIT STATUS
                    100: The
                    101: .Nm
                    102: utility exits with one of the following values:
                    103: .Bl -tag -width Ds -compact
                    104: .It 0
                    105: the expression is neither an empty string nor 0.
                    106: .It 1
                    107: the expression is an empty string or 0.
                    108: .It 2
                    109: the expression is invalid.
1.19      ross      110: .It \*[Gt]2
1.18      wiz       111: an error occurred (such as memory allocation failure).
                    112: .El
1.1       jtc       113: .Sh EXAMPLES
                    114: .Bl -enum
1.15      jdolecek  115: .It
1.1       jtc       116: The following example adds one to the variable a.
                    117: .Dl a=`expr $a + 1`
                    118: .It
1.15      jdolecek  119: The following example returns zero, due to deduction having higher precendence
1.19      ross      120: than '\*[Am]' operator.
                    121: .Dl expr 1 '\*[Am]' 1 - 1
1.15      jdolecek  122: .It
1.1       jtc       123: The following example returns the filename portion of a pathname stored
1.14      jdolecek  124: in variable a.
                    125: .Dl expr "/$a" Li : '.*/\e(.*\e)'
1.1       jtc       126: .It
                    127: The following example returns the number of characters in variable a.
                    128: .Dl expr $a Li : '.*'
                    129: .El
                    130: .Sh STANDARDS
                    131: The
1.10      enami     132: .Nm
1.4       jtc       133: utility conforms to
                    134: .St -p1003.2 .
1.18      wiz       135: .Sh AUTHORS
1.14      jdolecek  136: Original implementation was written by
1.22    ! grant     137: .An J.T. Conklin
        !           138: .Aq jtc@NetBSD.org .
1.20      pooka     139: It was rewritten for
1.14      jdolecek  140: .Nx 1.6
                    141: by
1.22    ! grant     142: .An Jaromir Dolecek
        !           143: .Aq jdolecek@NetBSD.org .
1.15      jdolecek  144: .Sh COMPATIBILITY
1.14      jdolecek  145: This implementation of
                    146: .Nm
                    147: internally uses 64 bit represenation of integers and checks for
1.21      wiz       148: over- and underflows.
                    149: It also treats / (division mark) and
1.15      jdolecek  150: option '--' correctly depending upon context.
1.14      jdolecek  151: .Pp
                    152: .Nm
                    153: on other systems (including
                    154: .Nx
                    155: up to and including
                    156: .Nx 1.5 )
1.21      wiz       157: might be not so graceful.
                    158: Arithmetic results might be arbitrarily
1.14      jdolecek  159: limited on such systems, most commonly to 32 bit quantities.
                    160: This means such
                    161: .Nm
                    162: can only process values between -2147483648 and +2147483647.
                    163: .Pp
                    164: On other systems,
                    165: .Nm
                    166: might also not work correctly for regular expressions where
                    167: either side contains single forward slash, like this:
                    168: .Bd -literal -offset indent
                    169: expr / : '.*/\e(.*\e)'
                    170: .Ed
                    171: .Pp
                    172: If this is the case, you might use // (double forward slash)
                    173: to avoid abiquity with the division operator:
                    174: .Bd -literal -offset indent
                    175: expr "//$a" : '.*/\e(.*\e)'
                    176: .Ed
1.15      jdolecek  177: .Pp
                    178: According to
                    179: .St -p1003.2 ,
                    180: .Nm
                    181: has to recognize special option '--', treat it as an end of command
                    182: line options and ignore it.
                    183: Some
                    184: .Nm
                    185: implementations don't recognize it at all, others
                    186: might ignore it even in cases where doing so results in syntax
1.21      wiz       187: error.
                    188: There should be same result for both following examples,
1.15      jdolecek  189: but it might not always be:
                    190: .Bl -enum -compact -offset indent
                    191: .It
                    192: expr -- : .
                    193: .It
                    194: expr -- -- : .
                    195: .El
                    196: Althrough
                    197: .Nx
                    198: .Nm
                    199: handles both cases correctly, you should not depend on this behaviour
                    200: for portability reasons and avoid passing bare '--' as first
                    201: argument.