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