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 March 22, 2002 34.Dt EXPR 1 35.Os 36.Sh NAME 37.Nm expr 38.Nd evaluate expression 39.Sh SYNOPSIS 40.Nm 41.Op Fl \&- 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. 53.Pp 54Arithmetic operations are performed using signed integer math, 55in the largest integral type available in the C language. The 56.Nm 57utility will detect arithmetic overflow and division by zero, and 58returns with an exit status of 2 in those cases. If a numeric operand 59is specified which is so large as to overflow conversion to an integer, 60it is parsed as a string instead. All numeric operands are interpreted 61in base 10. 62.Pp 63Operators are listed below in order of increasing precedence; all 64are left-associative. 65Operators with equal precedence are grouped within { } symbols. 66.Bl -tag -width indent 67.It Ar expr1 Li | Ar expr2 68Return the evaluation of 69.Ar expr1 70if it is neither an empty string nor zero; 71otherwise, returns the evaluation of 72.Ar expr2 . 73.It Ar expr1 Li & Ar expr2 74Return the evaluation of 75.Ar expr1 76if neither expression evaluates to an empty string or zero; 77otherwise, returns zero. 78.It Ar expr1 Li "{=, >, >=, <, <=, !=}" Ar expr2 79Return the results of integer comparison if both arguments are integers; 80otherwise, returns the results of string comparison using the locale-specific 81collation sequence. 82The result of each comparison is 1 if the specified relation is true, 83or 0 if the relation is false. 84.It Ar expr1 Li "{+, -}" Ar expr2 85Return the results of addition or subtraction of integer-valued arguments. 86.It Ar expr1 Li "{*, /, %}" Ar expr2 87Return the results of multiplication, integer division, or remainder of integer-valued arguments. 88.It Ar expr1 Li : Ar expr2 89The 90.Dq \&: 91operator matches 92.Ar expr1 93against 94.Ar expr2 , 95which must be a basic regular expression. 96The regular expression is anchored 97to the beginning of the string with an implicit 98.Dq ^ . 99.Pp 100If the match succeeds and the pattern contains at least one regular 101expression subexpression 102.Dq "\e(...\e)" , 103the string corresponding to 104.Dq "\e1" 105is returned; 106otherwise the matching operator returns the number of characters matched. 107If the match fails and the pattern contains a regular expression subexpression 108the null string is returned; 109otherwise 0. 110.El 111.Pp 112Parentheses are used for grouping in the usual manner. 113.Pp 114This version of 115.Nm 116adheres to the 117.Tn POSIX 118Utility Syntax Guidelines, which require that a leading argument beginning 119with a minus sign be considered an option to the program. 120The standard 121.Ql \&-- 122syntax may be used to prevent this interpretation. 123However, many historic implementations of 124.Nm , 125including the one in previous versions of 126.Fx , 127will not permit this syntax. 128See the examples below for portable ways to guarantee the correct 129interpretation. 130.Pp 131The 132.Nm 133utility makes no lexical distinction between arguments which may be 134operators and arguments which may be operands. 135An operand which is lexically identical to an operator will be considered a 136syntax error. 137See the examples below for a work-around. 138.Pp 139The syntax of the 140.Nm 141command in general is historic and inconvenient. 142New applications are advised to use shell arithmetic rather than 143.Nm . 144.Sh EXAMPLES 145.Bl -bullet 146.It 147The following example (in 148.Xr sh 1 149syntax) adds one to the variable 150.Va a : 151.Dl a=$(expr $a + 1) 152.It 153This will fail if the value of 154.Va a 155is a negative number. 156To protect negative values of 157.Va a 158from being interpreted as options to the 159.Nm 160command, one might rearrange the expression: 161.Dl a=$(expr 1 + $a) 162.It 163More generally, parenthesize possibly-negative values: 164.Dl a=$(expr \e( $a \e) + 1) 165.It 166The following example prints the filename portion of a pathname stored 167in variable 168.Va a . 169Since 170.Va a 171might represent the path 172.Pa / , 173it is necessary to prevent it from being interpreted as the division operator. 174The 175.Li // 176characters resolve this ambiguity. 177.Dl expr \*q//$a\*q \&: '.*/\e(.*\e)' 178.El 179.Pp 180The following examples output the number of characters in variable 181.Va a . 182Again, if 183.Va a 184might begin with a hyphen, it is necessary to prevent it from being 185interpreted as an option to 186.Nm . 187.Bl -bullet 188.It 189If the 190.Nm 191command conforms to 192.St -p1003.1-2001 , 193this is simple: 194.Dl expr -- \*q$a\*q \&: \*q.*\*q 195.It 196For portability to older systems, however, a more complicated command 197is required: 198.Dl expr \e( \*qX$a\*q \&: \*q.*\*q \e) - 1 199.El 200.Sh DIAGNOSTICS 201The 202.Nm 203utility exits with one of the following values: 204.Bl -tag -width indent -compact 205.It 0 206the expression is neither an empty string nor 0. 207.It 1 208the expression is an empty string or 0. 209.It 2 210the expression is invalid. 211.El 212.Sh SEE ALSO 213.Xr sh 1 , 214.Xr test 1 215.Sh STANDARDS 216The 217.Nm 218utility conforms to 219.St -p1003.1-2001 . 220.Tn POSIX 221does not specify whether arithmetic overflow is detected, nor does it specify 222the possible range of integer arguments to 223.Nm , 224so a portable application must assume that the range is small and that 225overflow may not be detected. 226