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