| blob | 6fa040869389529e1b113a05e222ca11fe41c846 |
1 .\"
2 .\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for
3 .\" permission to reproduce portions of its copyrighted documentation.
4 .\" Original documentation from The Open Group can be obtained online at
5 .\" http://www.opengroup.org/bookstore/.
6 .\"
7 .\" The Institute of Electrical and Electronics Engineers and The Open
8 .\" Group, have given us permission to reprint portions of their
9 .\" documentation.
10 .\"
11 .\" In the following statement, the phrase ``this text'' refers to portions
12 .\" of the system documentation.
13 .\"
14 .\" Portions of this text are reprinted and reproduced in electronic form
15 .\" in the SunOS Reference Manual, from IEEE Std 1003.1, 2004 Edition,
16 .\" Standard for Information Technology -- Portable Operating System
17 .\" Interface (POSIX), The Open Group Base Specifications Issue 6,
18 .\" Copyright (C) 2001-2004 by the Institute of Electrical and Electronics
19 .\" Engineers, Inc and The Open Group. In the event of any discrepancy
20 .\" between these versions and the original IEEE and The Open Group
21 .\" Standard, the original IEEE and The Open Group Standard is the referee
22 .\" document. The original Standard can be obtained online at
23 .\" http://www.opengroup.org/unix/online.html.
24 .\"
25 .\" This notice shall appear on any product containing this material.
26 .\"
27 .\" The contents of this file are subject to the terms of the
28 .\" Common Development and Distribution License (the "License").
29 .\" You may not use this file except in compliance with the License.
30 .\"
31 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
32 .\" or http://www.opensolaris.org/os/licensing.
33 .\" See the License for the specific language governing permissions
34 .\" and limitations under the License.
35 .\"
36 .\" When distributing Covered Code, include this CDDL HEADER in each
37 .\" file and include the License file at usr/src/OPENSOLARIS.LICENSE.
38 .\" If applicable, add the following below this CDDL HEADER, with the
39 .\" fields enclosed by brackets "[]" replaced with your own identifying
40 .\" information: Portions Copyright [yyyy] [name of copyright owner]
41 .\"
42 .\"
43 .\" Copyright 1989 AT&T
44 .\" Portions Copyright (c) 1992, X/Open Company Limited. All Rights Reserved.
45 .\" Copyright (c) 2003, Sun Microsystems, Inc. All Rights Reserved
46 .\"
47 .TH EXPR 1 "Aug 29, 2003"
48 .SH NAME
49 expr \- evaluate arguments as an expression
50 .SH SYNOPSIS
51 .LP
52 .nf
53 \fB/usr/bin/expr\fR \fIargument\fR...
54 .fi
56 .LP
57 .nf
58 \fB/usr/xpg4/bin/expr\fR \fIargument\fR...
59 .fi
61 .LP
62 .nf
63 \fB/usr/xpg6/bin/expr\fR \fIargument\fR...
64 .fi
66 .SH DESCRIPTION
67 .SS "/usr/bin/expr, /usr/xpg4/bin/expr"
68 .sp
69 .LP
70 The \fBexpr\fR utility evaluates the expression and writes the result to
71 standard output. The character \fB0\fR is written to indicate a zero value and
72 nothing is written to indicate a null string.
73 .SS "/usr/xpg6/bin/expr"
74 .sp
75 .LP
76 The \fBexpr\fR utility evaluates the expression and writes the result to
77 standard output followed by a NEWLINE. If there is no result from \fBexpr\fR
78 processing, a NEWLINE is written to standard output.
79 .SH OPERANDS
80 .sp
81 .LP
82 The \fIargument\fR operand is evaluated as an expression. Terms of the
83 expression must be separated by blanks. Characters special to the shell must be
84 escaped (see \fBsh\fR(1)). Strings containing blanks or other special
85 characters should be quoted. The length of the expression is limited to
86 \fBLINE_MAX\fR (2048 characters).
87 .sp
88 .LP
89 The operators and keywords are listed below. The list is in order of increasing
90 precedence, with equal precedence operators grouped within \fB{\|}\fR symbols.
91 All of the operators are left-associative.
92 .sp
93 .ne 2
94 .na
95 \fB\fIexpr\fR \fB\e|\fR \fIexpr\fR\fR
96 .ad
97 .sp .6
98 .RS 4n
99 Returns the evaluation of the first \fIexpr\fR if it is neither \fINULL\fR nor
100 \fB0\fR; otherwise, returns the evaluation of the second \fIexpr\fR if it is
101 not \fINULL\fR; otherwise, \fB0\fR.
102 .RE
104 .sp
105 .ne 2
106 .na
107 \fB\fIexpr\fR \fB\e&\fR \fIexpr\fR\fR
108 .ad
109 .sp .6
110 .RS 4n
111 Returns the first \fIexpr\fR if neither \fIexpr\fR is \fINULL\fR or \fB0\fR,
112 otherwise returns \fB0\fR.
113 .RE
115 .sp
116 .ne 2
117 .na
118 \fB\fIexpr\fR{ \fB=\fR, \fB\e>\fR, \fB\e>=\fR, \fB\e<\fR, \fB\e<=\fR, \fB!=\fR}
119 \fIexpr\fR\fR
120 .ad
121 .sp .6
122 .RS 4n
123 Returns the result of an integer comparison if both arguments are integers,
124 otherwise returns the result of a string comparison using the locale-specific
125 coalition sequence. The result of each comparison will be \fB1\fR if the
126 specified relationship is \fBTRUE\fR, \fB0\fR if the relationship is
127 \fBFALSE\fR.
128 .RE
130 .sp
131 .ne 2
132 .na
133 \fB\fIexpr \fR{ \fB+\fR, \fB\(mi \fR} \fIexpr\fR\fR
134 .ad
135 .sp .6
136 .RS 4n
137 Addition or subtraction of integer-valued arguments.
138 .RE
140 .sp
141 .ne 2
142 .na
143 \fB\fIexpr \fR{ \fB\e*\fR, \fB/\fR, \fB%\fR} \fIexpr\fR\fR
144 .ad
145 .sp .6
146 .RS 4n
147 Multiplication, division, or remainder of the integer-valued arguments.
148 .RE
150 .sp
151 .ne 2
152 .na
153 \fB\fIexpr\fR \fB:\fR \fIexpr\fR\fR
154 .ad
155 .sp .6
156 .RS 4n
157 The matching operator \fB:\fR (colon) compares the first argument with the
158 second argument, which must be an internationalized basic regular expression
159 (BRE), except that all patterns are anchored to the beginning of the string.
160 That is, only sequences starting at the first character of a string are matched
161 by the regular expression. See \fBregex\fR(5) and NOTES. Normally, the
162 \fB/usr/bin/expr\fR matching operator returns the number of bytes matched and
163 the \fB/usr/xpg4/bin/expr\fR matching operator returns the number of characters
164 matched (\fB0\fR on failure). If the second argument contains at least one BRE
165 sub-expression [\e(...\e)], the matching operator returns the string
166 corresponding to \e1.
167 .RE
169 .sp
170 .ne 2
171 .na
172 \fB\fIinteger\fR \fR
173 .ad
174 .sp .6
175 .RS 4n
176 An argument consisting only of an (optional) unary minus followed by digits.
177 .RE
179 .sp
180 .ne 2
181 .na
182 \fB\fIstring\fR \fR
183 .ad
184 .sp .6
185 .RS 4n
186 A string argument that cannot be identified as an \fIinteger\fR argument or as
187 one of the expression operator symbols.
188 .RE
190 .SS "Compatibility Operators (x86 only)"
191 .sp
192 .LP
193 The following operators are included for compatibility with INTERACTIVE UNIX
194 System only and are not intended to be used by non- INTERACTIVE UNIX System
195 scripts:
196 .sp
197 .ne 2
198 .na
199 \fB\fBindex\fR \fIstring character-list\fR\fR
200 .ad
201 .sp .6
202 .RS 4n
203 Report the first position in which any one of the bytes in \fIcharacter-list\fR
204 matches a byte in \fIstring\fR.
205 .RE
207 .sp
208 .ne 2
209 .na
210 \fB\fBlength\fR \fIstring\fR\fR
211 .ad
212 .sp .6
213 .RS 4n
214 Return the length (that is, the number of bytes) of \fIstring\fR.
215 .RE
217 .sp
218 .ne 2
219 .na
220 \fB\fBsubstr\fR \fIstring integer-1 integer-2\fR\fR
221 .ad
222 .sp .6
223 .RS 4n
224 Extract the substring of \fIstring\fR starting at position \fIinteger-1\fR and
225 of length \fIinteger-2\fR bytes. If \fIinteger-1\fR has a value greater than
226 the number of bytes in \fIstring\fR, \fBexpr\fR returns a null string. If you
227 try to extract more bytes than there are in string, \fBexpr\fR returns all the
228 remaining bytes from \fIstring\fR. Results are unspecified if either
229 \fIinteger-1\fR or \fIinteger-2\fR is a negative value.
230 .RE
232 .SH EXAMPLES
233 .LP
234 \fBExample 1 \fRAdding an integer to a shell variable
235 .sp
236 .LP
237 Add 1 to the shell variable \fBa\fR:
239 .sp
240 .in +2
241 .nf
242 example$ \fBa=`expr\| $a\| +\| 1`\fR
243 .fi
244 .in -2
245 .sp
247 .LP
248 \fBExample 2 \fRReturning a path name segment
249 .sp
250 .LP
251 The following example emulates \fBbasename\fR(1), returning the last segment of
252 the path name \fB$a\fR. For \fB$a\fR equal to either \fB/usr/abc/file\fR or
253 just \fBfile\fR, the example returns \fBfile\fR. (Watch out for \fB/\fR alone
254 as an argument: \fBexpr\fR takes it as the division operator. See NOTES below.)
256 .sp
257 .in +2
258 .nf
259 example$ \fBexpr $a : '.*/\e(.*\e)' \e| $a\fR
260 .fi
261 .in -2
262 .sp
264 .LP
265 \fBExample 3 \fRUsing // characters to simplify the expression
266 .sp
267 .LP
268 Here is a better version of the previous example. The addition of the \fB//\fR
269 characters eliminates any ambiguity about the division operator and simplifies
270 the whole expression.
272 .sp
273 .in +2
274 .nf
275 example$ \fBexpr //$a : '.*/\e(.*\e)'\fR
276 .fi
277 .in -2
278 .sp
280 .SS "/usr/bin/expr"
281 .LP
282 \fBExample 4 \fRReturning the number of bytes in a variable
283 .sp
284 .in +2
285 .nf
286 example$ \fBexpr "$VAR" : '.*'\fR
287 .fi
288 .in -2
289 .sp
291 .SS "/usr/xpg4/bin/expr"
292 .LP
293 \fBExample 5 \fRReturning the number of characters in a variable
294 .sp
295 .in +2
296 .nf
297 example$ \fBexpr "$VAR" : '.*'\fR
298 .fi
299 .in -2
300 .sp
302 .SH ENVIRONMENT VARIABLES
303 .sp
304 .LP
305 See \fBenviron\fR(5) for descriptions of the following environment variables
306 that affect the execution of \fBexpr\fR: \fBLANG\fR, \fBLC_ALL\fR,
307 \fBLC_COLLATE\fR, \fBLC_CTYPE\fR, \fBLC_MESSAGES\fR, and \fBNLSPATH\fR.
308 .SH EXIT STATUS
309 .sp
310 .LP
311 As a side effect of expression evaluation, \fBexpr\fR returns the following
312 exit values:
313 .sp
314 .ne 2
315 .na
316 \fB\fB0\fR \fR
317 .ad
318 .RS 7n
319 If the expression is neither \fINULL\fR nor \fB0\fR.
320 .RE
322 .sp
323 .ne 2
324 .na
325 \fB\fB1\fR \fR
326 .ad
327 .RS 7n
328 If the expression is either \fINULL\fR or \fB0\fR.
329 .RE
331 .sp
332 .ne 2
333 .na
334 \fB\fB2\fR \fR
335 .ad
336 .RS 7n
337 For invalid expressions.
338 .RE
340 .sp
341 .ne 2
342 .na
343 \fB\fB>2\fR \fR
344 .ad
345 .RS 7n
346 An error occurred.
347 .RE
349 .SH ATTRIBUTES
350 .sp
351 .LP
352 See \fBattributes\fR(5) for descriptions of the following attributes:
353 .sp
355 .sp
356 .TS
357 box;
358 c | c
359 l | l .
360 ATTRIBUTE TYPE ATTRIBUTE VALUE
361 _
362 CSI enabled
363 _
364 Interface Stability Standard
365 .TE
367 .SH SEE ALSO
368 .sp
369 .LP
370 \fBbasename\fR(1), \fBed\fR(1), \fBsh\fR(1), \fBIntro\fR(3),
371 \fBattributes\fR(5), \fBenviron\fR(5), \fBregex\fR(5), \fBstandards\fR(5)
372 .SH DIAGNOSTICS
373 .sp
374 .ne 2
375 .na
376 \fB\fBsyntax error\fR\fR
377 .ad
378 .RS 24n
379 Operator and operand errors.
380 .RE
382 .sp
383 .ne 2
384 .na
385 \fB\fBnon-numeric argument\fR\fR
386 .ad
387 .RS 24n
388 Arithmetic is attempted on such a string.
389 .RE
391 .SH NOTES
392 .sp
393 .LP
394 After argument processing by the shell, \fBexpr\fR cannot tell the difference
395 between an operator and an operand except by the value. If \fB$a\fR is an
396 \fB=\fR, the command:
397 .sp
398 .in +2
399 .nf
400 example$ \fBexpr $a = '='\fR
401 .fi
402 .in -2
403 .sp
405 .sp
406 .LP
407 looks like:
408 .sp
409 .in +2
410 .nf
411 example$ \fBexpr = = =\fR
412 .fi
413 .in -2
414 .sp
416 .sp
417 .LP
418 as the arguments are passed to \fBexpr\fR (and they are all taken as the
419 \fB=\fR operator). The following works:
420 .sp
421 .in +2
422 .nf
423 example$ \fBexpr X$a = X=\fR
424 .fi
425 .in -2
426 .sp
428 .SS "Regular Expressions"
429 .sp
430 .LP
431 Unlike some previous versions, \fBexpr\fR uses Internationalized Basic Regular
432 Expressions for all system-provided locales. Internationalized Regular
433 Expressions are explained on the \fBregex\fR(5) manual page.