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 October 5, 2016 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 compatibility 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 Bro =, >, >=, <, <=, != Brc 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 Bro +, - Brc Ar expr2 100Return the results of addition or subtraction of integer-valued arguments. 101.It Ar expr1 Bro *, /, % Brc 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. 180In addition, empty operands 181have an implied value of zero in numeric context. 182For historical reasons, defining the environment variable 183.Ev EXPR_COMPAT 184also enables backwards compatibility mode. 185.Sh ENVIRONMENT 186.Bl -tag -width ".Ev EXPR_COMPAT" 187.It Ev EXPR_COMPAT 188If set, enables backwards compatibility mode. 189.El 190.Sh EXIT STATUS 191The 192.Nm 193utility exits with one of the following values: 194.Bl -tag -width indent -compact 195.It 0 196the expression is neither an empty string nor 0. 197.It 1 198the expression is an empty string or 0. 199.It 2 200the expression is invalid. 201.El 202.Sh EXAMPLES 203.Bl -bullet 204.It 205The following example (in 206.Xr sh 1 207syntax) adds one to the variable 208.Va a : 209.Dl "a=$(expr $a + 1)" 210.It 211This will fail if the value of 212.Va a 213is a negative number. 214To protect negative values of 215.Va a 216from being interpreted as options to the 217.Nm 218command, one might rearrange the expression: 219.Dl "a=$(expr 1 + $a)" 220.It 221More generally, parenthesize possibly-negative values: 222.Dl "a=$(expr \e( $a \e) + 1)" 223.It 224With shell arithmetic, no escaping is required: 225.Dl "a=$((a + 1))" 226.It 227This example prints the filename portion of a pathname stored 228in variable 229.Va a . 230Since 231.Va a 232might represent the path 233.Pa / , 234it is necessary to prevent it from being interpreted as the division operator. 235The 236.Li // 237characters resolve this ambiguity. 238.Dl "expr \*q//$a\*q \&: '.*/\e(.*\e)'" 239.It 240With modern 241.Xr sh 1 242syntax, 243.Dl "\*q${a##*/}\*q" 244expands to the same value. 245.El 246.Pp 247The following examples output the number of characters in variable 248.Va a . 249Again, if 250.Va a 251might begin with a hyphen, it is necessary to prevent it from being 252interpreted as an option to 253.Nm , 254and 255.Va a 256might be interpreted as an operator. 257.Bl -bullet 258.It 259To deal with all of this, a complicated command 260is required: 261.Dl "expr \e( \*qX$a\*q \&: \*q.*\*q \e) - 1" 262.It 263With modern 264.Xr sh 1 265syntax, this can be done much more easily: 266.Dl "${#a}" 267expands 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 274The 275.Nm 276utility conforms to 277.St -p1003.1-2008 , 278provided that backwards compatibility mode is not enabled. 279.Pp 280Backwards compatibility mode performs less strict checks of numeric arguments: 281.Bl -bullet 282.It 283An empty operand string is interpreted as 0. 284.El 285.Bl -bullet 286.It 287Leading white space and/or a plus sign before an otherwise valid positive 288numeric operand are allowed and will be ignored. 289.El 290.Pp 291The extended arithmetic range and overflow checks do not conflict with 292POSIX's requirement that arithmetic be done using signed longs, since 293they only make a difference to the result in cases where using signed 294longs would give undefined behavior. 295.Pp 296According to the 297.Tn POSIX 298standard, the use of string arguments 299.Va length , 300.Va substr , 301.Va index , 302or 303.Va match 304produces undefined results. 305In this version of 306.Nm , 307these arguments are treated just as their respective string values. 308.Pp 309The 310.Fl e 311flag is an extension. 312.Sh HISTORY 313An 314.Nm 315utility first appeared in the Programmer's Workbench (PWB/UNIX). 316A public domain version of 317.Nm 318written by 319.An Pace Willisson Aq Mt pace@blitz.com 320appeared in 321.Bx 386 0.1 . 322.Sh AUTHORS 323Initial implementation by 324.An Pace Willisson Aq Mt pace@blitz.com 325was largely rewritten by 326.An -nosplit 327.An J.T. Conklin Aq Mt jtc@FreeBSD.org . 328