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