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 July 12, 2004 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.Vt 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.Vt 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 124The 125.Nm 126utility makes no lexical distinction between arguments which may be 127operators and arguments which may be operands. 128An operand which is lexically identical to an operator will be considered a 129syntax error. 130See the examples below for a work-around. 131.Pp 132The syntax of the 133.Nm 134command in general is historic and inconvenient. 135New applications are advised to use shell arithmetic rather than 136.Nm . 137.Ss Compatibility with previous implementations 138Unless 139.Fx 1404.x 141compatibility is enabled, this version of 142.Nm 143adheres to the 144.Tn POSIX 145Utility Syntax Guidelines, which require that a leading argument beginning 146with a minus sign be considered an option to the program. 147The standard 148.Fl Fl 149syntax may be used to prevent this interpretation. 150However, many historic implementations of 151.Nm , 152including the one in previous versions of 153.Fx , 154will not permit this syntax. 155See the examples below for portable ways to guarantee the correct 156interpretation. 157The 158.Xr check_utility_compat 3 159function (with a 160.Fa utility 161argument of 162.Dq Li expr ) 163is used to determine whether compatibility mode should be enabled. 164This feature is intended for use as a transition and debugging aid, when 165.Nm 166is used in complex scripts which cannot easily be recast to avoid the 167non-portable usage. 168Enabling compatibility mode 169also implicitly enables the 170.Fl e 171option, since this matches the historic behavior of 172.Nm 173in 174.Fx . 175For historical reasons, defining the environment variable 176.Ev EXPR_COMPAT 177also enables compatibility mode. 178.Sh ENVIRONMENT 179.Bl -tag -width ".Ev EXPR_COMPAT" 180.It Ev EXPR_COMPAT 181If set, enables compatibility mode. 182.El 183.Sh EXAMPLES 184.Bl -bullet 185.It 186The following example (in 187.Xr sh 1 188syntax) adds one to the variable 189.Va a : 190.Dl "a=$(expr $a + 1)" 191.It 192This will fail if the value of 193.Va a 194is a negative number. 195To protect negative values of 196.Va a 197from being interpreted as options to the 198.Nm 199command, one might rearrange the expression: 200.Dl "a=$(expr 1 + $a)" 201.It 202More generally, parenthesize possibly-negative values: 203.Dl "a=$(expr \e( $a \e) + 1)" 204.It 205This example prints the filename portion of a pathname stored 206in variable 207.Va a . 208Since 209.Va a 210might represent the path 211.Pa / , 212it is necessary to prevent it from being interpreted as the division operator. 213The 214.Li // 215characters resolve this ambiguity. 216.Dl "expr \*q//$a\*q \&: '.*/\e(.*\e)'" 217.El 218.Pp 219The following examples output the number of characters in variable 220.Va a . 221Again, if 222.Va a 223might begin with a hyphen, it is necessary to prevent it from being 224interpreted as an option to 225.Nm . 226.Bl -bullet 227.It 228If the 229.Nm 230command conforms to 231.St -p1003.1-2001 , 232this is simple: 233.Dl "expr -- \*q$a\*q \&: \*q.*\*q" 234.It 235For portability to older systems, however, a more complicated command 236is required: 237.Dl "expr \e( \*qX$a\*q \&: \*q.*\*q \e) - 1" 238.El 239.Sh DIAGNOSTICS 240The 241.Nm 242utility exits with one of the following values: 243.Bl -tag -width indent -compact 244.It 0 245the expression is neither an empty string nor 0. 246.It 1 247the expression is an empty string or 0. 248.It 2 249the expression is invalid. 250.El 251.Sh SEE ALSO 252.Xr sh 1 , 253.Xr test 1 , 254.Xr check_utility_compat 3 255.Sh STANDARDS 256The 257.Nm 258utility conforms to 259.St -p1003.1-2001 , 260provided that compatibility mode is not enabled. 261The 262.Fl e 263flag is an extension. 264