| blob | 19ebf1e9e1481c284a2a124008394f4e1c178a81 |
1 .\" $NetBSD: expr.1,v 1.28 2004/04/23 13:28:58 wiz Exp $
2 .\"
3 .\" Copyright (c) 2000,2003 The NetBSD Foundation, Inc.
4 .\" All rights reserved.
5 .\"
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 .\"
30 .Dd April 20, 2004
31 .Dt EXPR 1
32 .Os
33 .Sh NAME
34 .Nm expr
35 .Nd evaluate expression
36 .Sh SYNOPSIS
37 .Nm
38 .Ar expression
39 .Sh DESCRIPTION
40 The
41 .Nm
42 utility evaluates
43 .Ar expression
44 and writes the result on standard output.
45 .Pp
46 All operators are separate arguments to the
47 .Nm
48 utility.
49 Characters special to the command interpreter must be escaped.
50 .Pp
51 Operators are listed below in order of increasing precedence.
52 Operators with equal precedence are grouped within { } symbols.
53 .Bl -tag -width indent
54 .It Ar expr1 Li | Ar expr2
55 Returns the evaluation of
56 .Ar expr1
57 if it is neither an empty string nor zero;
58 otherwise, returns the evaluation of
59 .Ar expr2 .
60 .It Ar expr1 Li \*[Am] Ar expr2
61 Returns the evaluation of
62 .Ar expr1
63 if neither expression evaluates to an empty string or zero;
64 otherwise, returns zero.
65 .It Ar expr1 Li "{=, \*[Gt], \*[Ge], \*[Lt], \*[Le], !=}" Ar expr2
66 Returns the results of integer comparison if both arguments are integers;
67 otherwise, returns the results of string comparison using the locale-specific
68 collation sequence.
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.
75 .It Ar expr1 Li : Ar expr2
76 The
77 .Dq \&:
78 operator matches
79 .Ar expr1
80 against
81 .Ar expr2 ,
82 which must be a regular expression.
83 The regular expression is anchored
84 to the beginning of the string with an implicit
85 .Dq ^ .
86 .Pp
87 If the match succeeds and the pattern contains at least one regular
88 expression subexpression
89 .Dq "\e(...\e)" ,
90 the string corresponding to
91 .Dq "\e1"
92 is returned;
93 otherwise the matching operator returns the number of characters matched.
94 If the match fails and the pattern contains a regular expression subexpression
95 the null string is returned;
96 otherwise 0.
97 .It "( " Ar expr No " )"
98 Parentheses are used for grouping in the usual manner.
99 .El
100 .Pp
101 Additionally, the following keywords are recognized:
102 .Bl -tag -width indent
103 .It length Ar expr
104 Returns the length of the specified string in bytes.
105 .El
106 .Pp
107 Operator precedence (from highest to lowest):
108 .Bl -enum -compact -offset indent
109 .It
110 parentheses
111 .It
112 length
113 .It
114 .Dq \&:
115 .It
116 .Dq "*" ,
117 .Dq "/" ,
118 and
119 .Dq "%"
120 .It
121 .Dq "+"
122 and
123 .Dq "-"
124 .It
125 compare operators
126 .It
127 .Dq \*[Am]
128 .It
129 .Dq \Z'\*[tty-rn]'|
130 .El
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.
142 .It \*[Gt]2
143 an error occurred (such as memory allocation failure).
144 .El
145 .Sh EXAMPLES
146 .Bl -enum
147 .It
148 The following example adds one to the variable a.
149 .Dl a=`expr $a + 1`
150 .It
151 The following example returns zero, due to deduction having higher precedence
152 than '\*[Am]' operator.
153 .Dl expr 1 '\*[Am]' 1 - 1
154 .It
155 The following example returns the filename portion of a pathname stored
156 in variable a.
157 .Dl expr "/$a" Li : '.*/\e(.*\e)'
158 .It
159 The following example returns the number of characters in variable a.
160 .Dl expr $a Li : '.*'
161 .El
162 .Sh STANDARDS
163 The
164 .Nm
165 utility conforms to
166 .St -p1003.2 .
167 The
168 .Ar length
169 keyword is an extension for compatibility with GNU
170 .Nm .
171 .Sh AUTHORS
172 Original implementation was written by
173 .An J.T. Conklin
174 .Aq jtc@NetBSD.org .
175 It was rewritten for
176 .Nx 1.6
177 by
178 .An Jaromir Dolecek
179 .Aq jdolecek@NetBSD.org .
180 .Sh NOTES
181 The empty string
182 .Dq
183 cannot be matched with the intuitive:
184 .Bd -literal -offset indent
185 expr '' : '$'
186 .Ed
187 .Pp
188 The reason is that the returned number of matched characters (zero)
189 is indistinguishable from a failed match, so this returns failure.
190 To match the empty string, use something like:
191 .Bd -literal -offset indent
192 expr x'' : 'x$'
193 .Ed
194 .Sh COMPATIBILITY
195 This implementation of
196 .Nm
197 internally uses 64 bit representation of integers and checks for
198 over- and underflows.
199 It also treats / (division mark) and
200 option '--' correctly depending upon context.
201 .Pp
202 .Nm
203 on other systems (including
204 .Nx
205 up to and including
206 .Nx 1.5 )
207 might not be so graceful.
208 Arithmetic results might be arbitrarily
209 limited on such systems, most commonly to 32 bit quantities.
210 This means such
211 .Nm
212 can only process values between -2147483648 and +2147483647.
213 .Pp
214 On other systems,
215 .Nm
216 might also not work correctly for regular expressions where
217 either side contains single forward slash, like this:
218 .Bd -literal -offset indent
219 expr / : '.*/\e(.*\e)'
220 .Ed
221 .Pp
222 If this is the case, you might use // (double forward slash)
223 to avoid confusion with the division operator:
224 .Bd -literal -offset indent
225 expr "//$a" : '.*/\e(.*\e)'
226 .Ed
227 .Pp
228 According to
229 .St -p1003.2 ,
230 .Nm
231 has to recognize special option '--', treat it as an end of command
232 line options and ignore it.
233 Some
234 .Nm
235 implementations don't recognize it at all, others
236 might ignore it even in cases where doing so results in syntax
237 error.
238 There should be same result for both following examples,
239 but it might not always be:
240 .Bl -enum -compact -offset indent
241 .It
242 expr -- : .
243 .It
244 expr -- -- : .
245 .El
246 Although
247 .Nx
248 .Nm
249 handles both cases correctly, you should not depend on this behavior
250 for portability reasons and avoid passing bare '--' as first
251 argument.