1.\" -*- nroff -*- 2.\" 3.\" Copyright (c) 1993 Winning Strategies, Inc. 4.\" All rights reserved. 5.\" 6.\" Redistribution and use in source and binary forms, with or without 7.\" modification, are permitted provided that the following conditions 8.\" are met: 9.\" 1. Redistributions of source code must retain the above copyright 10.\" notice, this list of conditions and the following disclaimer. 11.\" 2. Redistributions in binary form must reproduce the above copyright 12.\" notice, this list of conditions and the following disclaimer in the 13.\" documentation and/or other materials provided with the distribution. 14.\" 3. All advertising materials mentioning features or use of this software 15.\" must display the following acknowledgement: 16.\" This product includes software developed by Winning Strategies, Inc. 17.\" 4. The name of the author may not be used to endorse or promote products 18.\" derived from this software without specific prior written permission 19.\" 20.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR 21.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES 22.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. 23.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, 24.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT 25.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, 26.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY 27.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 28.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF 29.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 30.\" 31.\" $FreeBSD$ 32.\" 33.Dd May 10, 2002 34.Dt EXPR 1 35.Os 36.Sh NAME 37.Nm expr 38.Nd evaluate expression 39.Sh SYNOPSIS 40.Nm 41.Op Fl e 42.Ar expression 43.Sh DESCRIPTION 44The 45.Nm 46utility evaluates 47.Ar expression 48and writes the result on standard output. 49.Pp 50All operators and operands must be passed as separate arguments. 51Several of the operators have special meaning to command interpreters 52and must therefore be quoted appropriately. 53All integer operands are interpreted in base 10. 54.Pp 55Arithmetic operations are performed using signed integer math. 56If the 57.Fl e 58flag is specified, arithmetic uses the C 59.Ql intmax_t 60data type (the largest integral type available), and 61.Nm 62will detect arithmetic overflow and return an error indication. 63If a numeric operand is specified which is so large as to overflow 64conversion to an integer, it is parsed as a string instead. 65If 66.Fl e 67is not specified, arithmetic operations and parsing of integer 68arguments will overflow silently according to the rules of the C 69standard, using the 70.Ql long 71data type. 72.Pp 73Operators are listed below in order of increasing precedence; all 74are left-associative. 75Operators with equal precedence are grouped within { } symbols. 76.Bl -tag -width indent 77.It Ar expr1 Li | Ar expr2 78Return the evaluation of 79.Ar expr1 80if it is neither an empty string nor zero; 81otherwise, returns the evaluation of 82.Ar expr2 . 83.It Ar expr1 Li & Ar expr2 84Return the evaluation of 85.Ar expr1 86if neither expression evaluates to an empty string or zero; 87otherwise, returns zero. 88.It Ar expr1 Li "{=, >, >=, <, <=, !=}" Ar expr2 89Return the results of integer comparison if both arguments are integers; 90otherwise, returns the results of string comparison using the locale-specific 91collation sequence. 92The result of each comparison is 1 if the specified relation is true, 93or 0 if the relation is false. 94.It Ar expr1 Li "{+, -}" Ar expr2 95Return the results of addition or subtraction of integer-valued arguments. 96.It Ar expr1 Li "{*, /, %}" Ar expr2 97Return the results of multiplication, integer division, or remainder of integer-valued arguments. 98.It Ar expr1 Li : Ar expr2 99The 100.Dq \&: 101operator matches 102.Ar expr1 103against 104.Ar expr2 , 105which must be a basic regular expression. 106The regular expression is anchored 107to the beginning of the string with an implicit 108.Dq ^ . 109.Pp 110If the match succeeds and the pattern contains at least one regular 111expression subexpression 112.Dq "\e(...\e)" , 113the string corresponding to 114.Dq "\e1" 115is returned; 116otherwise the matching operator returns the number of characters matched. 117If the match fails and the pattern contains a regular expression subexpression 118the null string is returned; 119otherwise 0. 120.El 121.Pp 122Parentheses are used for grouping in the usual manner. 123.Pp 124Unless the 125.Ev EXPR_COMPAT 126variable is defined in the process environment, this version of 127.Nm 128adheres to the 129.Tn POSIX 130Utility Syntax Guidelines, which require that a leading argument beginning 131with a minus sign be considered an option to the program. 132The standard 133.Ql \&-- 134syntax may be used to prevent this interpretation. 135However, many historic implementations of 136.Nm , 137including the one in previous versions of 138.Fx , 139will not permit this syntax. 140See the examples below for portable ways to guarantee the correct 141interpretation. 142The 143.Ev EXPR_COMPAT 144variable is intended for use as a transition and debugging aid, when 145.Nm 146is used in complex scripts which cannot easily be recast to avoid the 147non-portable usage. 148Defining 149.Ev EXPR_COMPAT 150also implicitly enables the 151.Fl e 152option, since this matches the historic behavior of 153.Nm 154in 155.Fx . 156.Pp 157The 158.Nm 159utility makes no lexical distinction between arguments which may be 160operators and arguments which may be operands. 161An operand which is lexically identical to an operator will be considered a 162syntax error. 163See the examples below for a work-around. 164.Pp 165The syntax of the 166.Nm 167command in general is historic and inconvenient. 168New applications are advised to use shell arithmetic rather than 169.Nm . 170.Sh ENVIRONMENT 171.Bl -tag -compact -width EXPR_COMPAT 172.It Ev EXPR_COMPAT 173If set, 174.Nm 175will emulate historic 176.Nm 177implementations which did not obey the Utility Syntax Guidelines. 178Implies 179.Fl e . 180.El 181.Sh EXAMPLES 182.Bl -bullet 183.It 184The following example (in 185.Xr sh 1 186syntax) adds one to the variable 187.Va a : 188.Dl a=$(expr $a + 1) 189.It 190This will fail if the value of 191.Va a 192is a negative number. 193To protect negative values of 194.Va a 195from being interpreted as options to the 196.Nm 197command, one might rearrange the expression: 198.Dl a=$(expr 1 + $a) 199.It 200More generally, parenthesize possibly-negative values: 201.Dl a=$(expr \e( $a \e) + 1) 202.It 203This example prints the filename portion of a pathname stored 204in variable 205.Va a . 206Since 207.Va a 208might represent the path 209.Pa / , 210it is necessary to prevent it from being interpreted as the division operator. 211The 212.Li // 213characters resolve this ambiguity. 214.Dl expr \*q//$a\*q \&: '.*/\e(.*\e)' 215.El 216.Pp 217The following examples output the number of characters in variable 218.Va a . 219Again, if 220.Va a 221might begin with a hyphen, it is necessary to prevent it from being 222interpreted as an option to 223.Nm . 224.Bl -bullet 225.It 226If the 227.Nm 228command conforms to 229.St -p1003.1-2001 , 230this is simple: 231.Dl expr -- \*q$a\*q \&: \*q.*\*q 232.It 233For portability to older systems, however, a more complicated command 234is required: 235.Dl expr \e( \*qX$a\*q \&: \*q.*\*q \e) - 1 236.El 237.Sh DIAGNOSTICS 238The 239.Nm 240utility exits with one of the following values: 241.Bl -tag -width indent -compact 242.It 0 243the expression is neither an empty string nor 0. 244.It 1 245the expression is an empty string or 0. 246.It 2 247the expression is invalid. 248.El 249.Sh SEE ALSO 250.Xr sh 1 , 251.Xr test 1 252.Sh STANDARDS 253The 254.Nm 255utility conforms to 256.St -p1003.1-2001 , 257provided that the 258.Ev EXPR_COMPAT 259environment variable is not defined. 260The 261.Fl e 262flag is an extension. 263