Return to expr.1 CVS log

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

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

1.31.4.1! yamt        1: .\"    $NetBSD: expr.1,v 1.31 2011/03/23 18:10:25 dholland Exp $
1.8       cgd         2: .\"
1.24      jdolecek    3: .\" Copyright (c) 2000,2003 The NetBSD Foundation, Inc.
                      4: .\" All rights reserved.
1.1       jtc         5: .\"
1.24      jdolecek    6: .\" This code is derived from software contributed to The NetBSD Foundation
                      7: .\" by J.T. Conklin <jtc@NetBSD.org> and Jaromir Dolecek <jdolecek@NetBSD.org>.
                      8: .\"
                      9: .\" Redistribution and use in source and binary forms, with or without
                     10: .\" modification, are permitted provided that the following conditions
                     11: .\" are met:
                     12: .\" 1. Redistributions of source code must retain the above copyright
                     13: .\"    notice, this list of conditions and the following disclaimer.
                     14: .\" 2. Redistributions in binary form must reproduce the above copyright
                     15: .\"    notice, this list of conditions and the following disclaimer in the
                     16: .\"    documentation and/or other materials provided with the distribution.
                     17: .\"
                     18: .\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
                     19: .\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
                     20: .\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
                     21: .\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
                     22: .\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
                     23: .\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
                     24: .\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
                     25: .\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
                     26: .\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
                     27: .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
                     28: .\" POSSIBILITY OF SUCH DAMAGE.
                     29: .\"
1.27      wiz        30: .Dd April 20, 2004
1.1       jtc        31: .Dt EXPR 1
                     32: .Os
                     33: .Sh NAME
                     34: .Nm expr
                     35: .Nd evaluate expression
                     36: .Sh SYNOPSIS
1.10      enami      37: .Nm
1.1       jtc        38: .Ar expression
                     39: .Sh DESCRIPTION
                     40: The
1.10      enami      41: .Nm
1.16      jdolecek   42: utility evaluates
1.1       jtc        43: .Ar expression
                     44: and writes the result on standard output.
                     45: .Pp
                     46: All operators are separate arguments to the
1.10      enami      47: .Nm
1.1       jtc        48: utility.
                     49: Characters special to the command interpreter must be escaped.
                     50: .Pp
1.6       jtc        51: Operators are listed below in order of increasing precedence.
                     52: Operators with equal precedence are grouped within { } symbols.
1.1       jtc        53: .Bl -tag -width indent
1.30      joerg      54: .It Ar expr1 Li \&| Ar expr2
1.16      jdolecek   55: Returns the evaluation of
                     56: .Ar expr1
1.1       jtc        57: if it is neither an empty string nor zero;
                     58: otherwise, returns the evaluation of
                     59: .Ar expr2 .
1.19      ross       60: .It Ar expr1 Li \*[Am] Ar expr2
1.1       jtc        61: Returns the evaluation of
                     62: .Ar expr1
                     63: if neither expression evaluates to an empty string or zero;
                     64: otherwise, returns zero.
1.19      ross       65: .It Ar expr1 Li "{=, \*[Gt], \*[Ge], \*[Lt], \*[Le], !=}" Ar expr2
1.16      jdolecek   66: Returns the results of integer comparison if both arguments are integers;
1.3       jtc        67: otherwise, returns the results of string comparison using the locale-specific
                     68: collation sequence.
1.1       jtc        69: The result of each comparison is 1 if the specified relation is true,
                     70: or 0 if the relation is false.
                     71: .It Ar expr1 Li "{+, -}" Ar expr2
                     72: Returns the results of addition or subtraction of integer-valued arguments.
                     73: .It Ar expr1 Li "{*, /, %}" Ar expr2
                     74: Returns the results of multiplication, integer division, or remainder of integer-valued arguments.
1.30      joerg      75: .It Ar expr1 Li \&: Ar expr2
1.16      jdolecek   76: The
1.17      wiz        77: .Dq \&:
1.16      jdolecek   78: operator matches
                     79: .Ar expr1
                     80: against
1.1       jtc        81: .Ar expr2 ,
1.21      wiz        82: which must be a regular expression.
                     83: The regular expression is anchored
1.31.4.1! yamt       84: to the beginning of the string with an implicit
1.5       jtc        85: .Dq ^ .
1.1       jtc        86: .Pp
1.5       jtc        87: If the match succeeds and the pattern contains at least one regular
1.16      jdolecek   88: expression subexpression
                     89: .Dq "\e(...\e)" ,
                     90: the string corresponding to
1.1       jtc        91: .Dq "\e1"
                     92: is returned;
1.16      jdolecek   93: otherwise the matching operator returns the number of characters matched.
1.5       jtc        94: If the match fails and the pattern contains a regular expression subexpression
                     95: the null string is returned;
                     96: otherwise 0.
1.27      wiz        97: .It "( " Ar expr No " )"
1.15      jdolecek   98: Parentheses are used for grouping in the usual manner.
1.1       jtc        99: .El
                    100: .Pp
1.27      wiz       101: Additionally, the following keywords are recognized:
1.26      jdolecek  102: .Bl -tag -width indent
1.30      joerg     103: .It length Ar expr
1.27      wiz       104: Returns the length of the specified string in bytes.
1.26      jdolecek  105: .El
                    106: .Pp
1.15      jdolecek  107: Operator precedence (from highest to lowest):
                    108: .Bl -enum -compact -offset indent
                    109: .It
                    110: parentheses
                    111: .It
1.26      jdolecek  112: length
                    113: .It
1.17      wiz       114: .Dq \&:
1.16      jdolecek  115: .It
                    116: .Dq "*" ,
                    117: .Dq "/" ,
                    118: and
                    119: .Dq "%"
                    120: .It
                    121: .Dq "+"
                    122: and
                    123: .Dq "-"
                    124: .It
                    125: compare operators
1.15      jdolecek  126: .It
1.19      ross      127: .Dq \*[Am]
1.15      jdolecek  128: .It
1.30      joerg     129: .Dq \&|
1.15      jdolecek  130: .El
1.18      wiz       131: .Sh EXIT STATUS
                    132: The
                    133: .Nm
                    134: utility exits with one of the following values:
                    135: .Bl -tag -width Ds -compact
                    136: .It 0
                    137: the expression is neither an empty string nor 0.
                    138: .It 1
                    139: the expression is an empty string or 0.
                    140: .It 2
                    141: the expression is invalid.
1.19      ross      142: .It \*[Gt]2
1.18      wiz       143: an error occurred (such as memory allocation failure).
                    144: .El
1.1       jtc       145: .Sh EXAMPLES
                    146: .Bl -enum
1.15      jdolecek  147: .It
1.1       jtc       148: The following example adds one to the variable a.
                    149: .Dl a=`expr $a + 1`
                    150: .It
1.31      dholland  151: The following example returns zero, due to subtraction having higher precedence
1.19      ross      152: than '\*[Am]' operator.
                    153: .Dl expr 1 '\*[Am]' 1 - 1
1.15      jdolecek  154: .It
1.1       jtc       155: The following example returns the filename portion of a pathname stored
1.14      jdolecek  156: in variable a.
                    157: .Dl expr "/$a" Li : '.*/\e(.*\e)'
1.1       jtc       158: .It
                    159: The following example returns the number of characters in variable a.
                    160: .Dl expr $a Li : '.*'
                    161: .El
1.15      jdolecek  162: .Sh COMPATIBILITY
1.14      jdolecek  163: This implementation of
                    164: .Nm
1.23      perry     165: internally uses 64 bit representation of integers and checks for
1.21      wiz       166: over- and underflows.
                    167: It also treats / (division mark) and
1.15      jdolecek  168: option '--' correctly depending upon context.
1.14      jdolecek  169: .Pp
                    170: .Nm
                    171: on other systems (including
                    172: .Nx
                    173: up to and including
                    174: .Nx 1.5 )
1.28      wiz       175: might not be so graceful.
1.21      wiz       176: Arithmetic results might be arbitrarily
1.14      jdolecek  177: limited on such systems, most commonly to 32 bit quantities.
                    178: This means such
                    179: .Nm
                    180: can only process values between -2147483648 and +2147483647.
                    181: .Pp
                    182: On other systems,
                    183: .Nm
                    184: might also not work correctly for regular expressions where
                    185: either side contains single forward slash, like this:
                    186: .Bd -literal -offset indent
                    187: expr / : '.*/\e(.*\e)'
                    188: .Ed
                    189: .Pp
                    190: If this is the case, you might use // (double forward slash)
1.23      perry     191: to avoid confusion with the division operator:
1.14      jdolecek  192: .Bd -literal -offset indent
                    193: expr "//$a" : '.*/\e(.*\e)'
                    194: .Ed
1.15      jdolecek  195: .Pp
                    196: According to
                    197: .St -p1003.2 ,
                    198: .Nm
                    199: has to recognize special option '--', treat it as an end of command
                    200: line options and ignore it.
                    201: Some
                    202: .Nm
                    203: implementations don't recognize it at all, others
                    204: might ignore it even in cases where doing so results in syntax
1.21      wiz       205: error.
                    206: There should be same result for both following examples,
1.15      jdolecek  207: but it might not always be:
                    208: .Bl -enum -compact -offset indent
                    209: .It
                    210: expr -- : .
                    211: .It
                    212: expr -- -- : .
                    213: .El
1.23      perry     214: Although
1.15      jdolecek  215: .Nx
                    216: .Nm
1.23      perry     217: handles both cases correctly, you should not depend on this behavior
1.15      jdolecek  218: for portability reasons and avoid passing bare '--' as first
                    219: argument.
1.30      joerg     220: .Sh STANDARDS
                    221: The
                    222: .Nm
                    223: utility conforms to
                    224: .St -p1003.2 .
                    225: The
                    226: .Ar length
                    227: keyword is an extension for compatibility with GNU
                    228: .Nm .
                    229: .Sh AUTHORS
                    230: Original implementation was written by
                    231: .An J.T. Conklin
                    232: .Aq jtc@NetBSD.org .
                    233: It was rewritten for
                    234: .Nx 1.6
                    235: by
                    236: .An Jaromir Dolecek
                    237: .Aq jdolecek@NetBSD.org .
                    238: .Sh NOTES
                    239: The empty string
                    240: .Do Dc
                    241: cannot be matched with the intuitive:
                    242: .Bd -literal -offset indent
                    243: expr '' : '$'
                    244: .Ed
                    245: .Pp
                    246: The reason is that the returned number of matched characters (zero)
                    247: is indistinguishable from a failed match, so this returns failure.
                    248: To match the empty string, use something like:
                    249: .Bd -literal -offset indent
                    250: expr x'' : 'x$'
                    251: .Ed