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 September 9, 2010 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 and must consist of only 54an optional leading minus sign followed by one or more digits (unless 55less strict parsing has been enabled for backwards compatibilty with 56prior versions of 57.Nm 58in 59.Fx ) . 60.Pp 61Arithmetic operations are performed using signed integer math with a 62range according to the C 63.Vt intmax_t 64data type (the largest signed integral type available). 65All conversions and operations are checked for overflow. 66Overflow results in program termination with an error message on stdout 67and with an error status. 68.Pp 69The 70.Fl e 71option enables backwards compatible behaviour as detailed below. 72.Pp 73Operators are listed below in order of increasing precedence; all 74are left-associative. 75Operators with equal precedence are grouped within symbols 76.Ql { 77and 78.Ql } . 79.Bl -tag -width indent 80.It Ar expr1 Li | Ar expr2 81Return the evaluation of 82.Ar expr1 83if it is neither an empty string nor zero; 84otherwise, returns the evaluation of 85.Ar expr2 86if it is not an empty string; 87otherwise, returns zero. 88.It Ar expr1 Li & Ar expr2 89Return the evaluation of 90.Ar expr1 91if neither expression evaluates to an empty string or zero; 92otherwise, returns zero. 93.It Ar expr1 Li "{=, >, >=, <, <=, !=}" Ar expr2 94Return the results of integer comparison if both arguments are integers; 95otherwise, returns the results of string comparison using the locale-specific 96collation sequence. 97The result of each comparison is 1 if the specified relation is true, 98or 0 if the relation is false. 99.It Ar expr1 Li "{+, -}" Ar expr2 100Return the results of addition or subtraction of integer-valued arguments. 101.It Ar expr1 Li "{*, /, %}" Ar expr2 102Return the results of multiplication, integer division, or remainder of integer-valued arguments. 103.It Ar expr1 Li : Ar expr2 104The 105.Dq Li \&: 106operator matches 107.Ar expr1 108against 109.Ar expr2 , 110which must be a basic regular expression. 111The regular expression is anchored 112to the beginning of the string with an implicit 113.Dq Li ^ . 114.Pp 115If the match succeeds and the pattern contains at least one regular 116expression subexpression 117.Dq Li "\e(...\e)" , 118the string corresponding to 119.Dq Li \e1 120is returned; 121otherwise the matching operator returns the number of characters matched. 122If the match fails and the pattern contains a regular expression subexpression 123the null string is returned; 124otherwise 0. 125.El 126.Pp 127Parentheses are used for grouping in the usual manner. 128.Pp 129The 130.Nm 131utility makes no lexical distinction between arguments which may be 132operators and arguments which may be operands. 133An operand which is lexically identical to an operator will be considered a 134syntax error. 135See the examples below for a work-around. 136.Pp 137The syntax of the 138.Nm 139command in general is historic and inconvenient. 140New applications are advised to use shell arithmetic rather than 141.Nm . 142.Ss Compatibility with previous implementations 143Unless 144.Fx 1454.x 146compatibility is enabled, this version of 147.Nm 148adheres to the 149.Tn POSIX 150Utility Syntax Guidelines, which require that a leading argument beginning 151with a minus sign be considered an option to the program. 152The standard 153.Fl Fl 154syntax may be used to prevent this interpretation. 155However, many historic implementations of 156.Nm , 157including the one in previous versions of 158.Fx , 159will not permit this syntax. 160See the examples below for portable ways to guarantee the correct 161interpretation. 162The 163.Xr check_utility_compat 3 164function (with a 165.Fa utility 166argument of 167.Dq Li expr ) 168is used to determine whether backwards compatibility mode should be enabled. 169This feature is intended for use as a transition and debugging aid, when 170.Nm 171is used in complex scripts which cannot easily be recast to avoid the 172non-portable usage. 173Enabling backwards compatibility mode also implicitly enables the 174.Fl e 175option, since this matches the historic behavior of 176.Nm 177in 178.Fx . This option makes number parsing less strict and permits leading 179white space and an optional leading plus sign. In addition, empty operands 180have an implied value of zero in numeric context. 181For historical reasons, defining the environment variable 182.Ev EXPR_COMPAT 183also enables backwards compatibility mode. 184.Sh ENVIRONMENT 185.Bl -tag -width ".Ev EXPR_COMPAT" 186.It Ev EXPR_COMPAT 187If set, enables backwards compatibility mode. 188.El 189.Sh EXIT STATUS 190The 191.Nm 192utility exits with one of the following values: 193.Bl -tag -width indent -compact 194.It 0 195the expression is neither an empty string nor 0. 196.It 1 197the expression is an empty string or 0. 198.It 2 199the expression is invalid. 200.El 201.Sh EXAMPLES 202.Bl -bullet 203.It 204The following example (in 205.Xr sh 1 206syntax) adds one to the variable 207.Va a : 208.Dl "a=$(expr $a + 1)" 209.It 210This will fail if the value of 211.Va a 212is a negative number. 213To protect negative values of 214.Va a 215from being interpreted as options to the 216.Nm 217command, one might rearrange the expression: 218.Dl "a=$(expr 1 + $a)" 219.It 220More generally, parenthesize possibly-negative values: 221.Dl "a=$(expr \e( $a \e) + 1)" 222.It 223With shell arithmetic, no escaping is required: 224.Dl "a=$((a + 1))" 225.It 226This example prints the filename portion of a pathname stored 227in variable 228.Va a . 229Since 230.Va a 231might represent the path 232.Pa / , 233it is necessary to prevent it from being interpreted as the division operator. 234The 235.Li // 236characters resolve this ambiguity. 237.Dl "expr \*q//$a\*q \&: '.*/\e(.*\e)'" 238.It 239With modern 240.Xr sh 1 241syntax, 242.Dl "\*q${a##*/}\*q" 243expands to the same value. 244.El 245.Pp 246The following examples output the number of characters in variable 247.Va a . 248Again, if 249.Va a 250might begin with a hyphen, it is necessary to prevent it from being 251interpreted as an option to 252.Nm , 253and 254.Va a 255might be interpreted as an operator. 256.Bl -bullet 257.It 258To deal with all of this, a complicated command 259is required: 260.Dl "expr \e( \*qX$a\*q \&: \*q.*\*q \e) - 1" 261.It 262With modern 263.Xr sh 1 264syntax, this can be done much more easily: 265.Dl "${#a}" 266expands to the required number. 267.El 268.Sh SEE ALSO 269.Xr sh 1 , 270.Xr test 1 , 271.Xr check_utility_compat 3 272.Sh STANDARDS 273The 274.Nm 275utility conforms to 276.St -p1003.1-2008 , 277provided that backwards compatibility mode is not enabled. 278.Pp 279Backwards compatibility mode performs less strict checks of numeric arguments: 280.Bl -bullet 281.It 282An empty operand string is interpreted as 0. 283.El 284.Bl -bullet 285.It 286Leading white space and/or a plus sign before an otherwise valid positive 287numberic operand are allowed and will be ignored. 288.El 289.Pp 290The extended arithmetic range and overflow checks do not conflict with 291POSIX's requirement that arithmetic be done using signed longs, since 292they only make a difference to the result in cases where using signed 293longs would give undefined behavior. 294.Pp 295According to the 296.Tn POSIX 297standard, the use of string arguments 298.Va length , 299.Va substr , 300.Va index , 301or 302.Va match 303produces undefined results. In this version of 304.Nm , 305these arguments are treated just as their respective string values. 306.Pp 307The 308.Fl e 309flag is an extension. 310