1.\" $NetBSD: expr.1,v 1.25 2003/12/21 11:18:25 wiz Exp $ 2.\" 3.\" Copyright (c) 2000,2003 The NetBSD Foundation, Inc. 4.\" All rights reserved. 5.\" 6.\" This code is derived from software contributed to The NetBSD Foundation 7.\" by J.T. Conklin <jtc@NetBSD.org> and Jaromir Dolecek <jdolecek@NetBSD.org>. 8.\" 9.\" Redistribution and use in source and binary forms, with or without 10.\" modification, are permitted provided that the following conditions 11.\" are met: 12.\" 1. Redistributions of source code must retain the above copyright 13.\" notice, this list of conditions and the following disclaimer. 14.\" 2. Redistributions in binary form must reproduce the above copyright 15.\" notice, this list of conditions and the following disclaimer in the 16.\" documentation and/or other materials provided with the distribution. 17.\" 3. All advertising materials mentioning features or use of this software 18.\" must display the following acknowledgement: 19.\" This product includes software developed by the NetBSD 20.\" Foundation, Inc. and its contributors. 21.\" 4. Neither the name of The NetBSD Foundation nor the names of its 22.\" contributors may be used to endorse or promote products derived 23.\" from this software without specific prior written permission. 24.\" 25.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS 26.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 27.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 28.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS 29.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 30.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 31.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 32.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 33.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 34.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 35.\" POSSIBILITY OF SUCH DAMAGE. 36.\" 37.Dd December 21, 2003 38.Dt EXPR 1 39.Os 40.Sh NAME 41.Nm expr 42.Nd evaluate expression 43.Sh SYNOPSIS 44.Nm 45.Ar expression 46.Sh DESCRIPTION 47The 48.Nm 49utility evaluates 50.Ar expression 51and writes the result on standard output. 52.Pp 53All operators are separate arguments to the 54.Nm 55utility. 56Characters special to the command interpreter must be escaped. 57.Pp 58Operators are listed below in order of increasing precedence. 59Operators with equal precedence are grouped within { } symbols. 60.Bl -tag -width indent 61.It Ar expr1 Li | Ar expr2 62Returns the evaluation of 63.Ar expr1 64if it is neither an empty string nor zero; 65otherwise, returns the evaluation of 66.Ar expr2 . 67.It Ar expr1 Li \*[Am] Ar expr2 68Returns the evaluation of 69.Ar expr1 70if neither expression evaluates to an empty string or zero; 71otherwise, returns zero. 72.It Ar expr1 Li "{=, \*[Gt], \*[Ge], \*[Lt], \*[Le], !=}" Ar expr2 73Returns the results of integer comparison if both arguments are integers; 74otherwise, returns the results of string comparison using the locale-specific 75collation sequence. 76The result of each comparison is 1 if the specified relation is true, 77or 0 if the relation is false. 78.It Ar expr1 Li "{+, -}" Ar expr2 79Returns the results of addition or subtraction of integer-valued arguments. 80.It Ar expr1 Li "{*, /, %}" Ar expr2 81Returns the results of multiplication, integer division, or remainder of integer-valued arguments. 82.It Ar expr1 Li : Ar expr2 83The 84.Dq \&: 85operator matches 86.Ar expr1 87against 88.Ar expr2 , 89which must be a regular expression. 90The regular expression is anchored 91to the beginning of the string with an implicit 92.Dq ^ . 93.Pp 94If the match succeeds and the pattern contains at least one regular 95expression subexpression 96.Dq "\e(...\e)" , 97the string corresponding to 98.Dq "\e1" 99is returned; 100otherwise the matching operator returns the number of characters matched. 101If the match fails and the pattern contains a regular expression subexpression 102the null string is returned; 103otherwise 0. 104.It Ar "( " expr Li " )" 105Parentheses are used for grouping in the usual manner. 106.El 107.Pp 108Operator precedence (from highest to lowest): 109.Bl -enum -compact -offset indent 110.It 111parentheses 112.It 113.Dq \&: 114.It 115.Dq "*" , 116.Dq "/" , 117and 118.Dq "%" 119.It 120.Dq "+" 121and 122.Dq "-" 123.It 124compare operators 125.It 126.Dq \*[Am] 127.It 128.Dq \Z'\*[tty-rn]'| 129.El 130.Sh EXIT STATUS 131The 132.Nm 133utility exits with one of the following values: 134.Bl -tag -width Ds -compact 135.It 0 136the expression is neither an empty string nor 0. 137.It 1 138the expression is an empty string or 0. 139.It 2 140the expression is invalid. 141.It \*[Gt]2 142an error occurred (such as memory allocation failure). 143.El 144.Sh EXAMPLES 145.Bl -enum 146.It 147The following example adds one to the variable a. 148.Dl a=`expr $a + 1` 149.It 150The following example returns zero, due to deduction having higher precedence 151than '\*[Am]' operator. 152.Dl expr 1 '\*[Am]' 1 - 1 153.It 154The following example returns the filename portion of a pathname stored 155in variable a. 156.Dl expr "/$a" Li : '.*/\e(.*\e)' 157.It 158The following example returns the number of characters in variable a. 159.Dl expr $a Li : '.*' 160.El 161.Sh STANDARDS 162The 163.Nm 164utility conforms to 165.St -p1003.2 . 166.Sh AUTHORS 167Original implementation was written by 168.An J.T. Conklin 169.Aq jtc@NetBSD.org . 170It was rewritten for 171.Nx 1.6 172by 173.An Jaromir Dolecek 174.Aq jdolecek@NetBSD.org . 175.Sh NOTES 176The empty string 177.Dq 178cannot be matched with the intuitive: 179.Bd -literal -offset indent 180expr '' : '$' 181.Ed 182.Pp 183The reason is that the returned number of matched characters (zero) 184is indistinguishable from a failed match, so this returns failure. 185To match the empty string, use something like: 186.Bd -literal -offset indent 187expr x'' : 'x$' 188.Ed 189.Sh COMPATIBILITY 190This implementation of 191.Nm 192internally uses 64 bit representation of integers and checks for 193over- and underflows. 194It also treats / (division mark) and 195option '--' correctly depending upon context. 196.Pp 197.Nm 198on other systems (including 199.Nx 200up to and including 201.Nx 1.5 ) 202might be not so graceful. 203Arithmetic results might be arbitrarily 204limited on such systems, most commonly to 32 bit quantities. 205This means such 206.Nm 207can only process values between -2147483648 and +2147483647. 208.Pp 209On other systems, 210.Nm 211might also not work correctly for regular expressions where 212either side contains single forward slash, like this: 213.Bd -literal -offset indent 214expr / : '.*/\e(.*\e)' 215.Ed 216.Pp 217If this is the case, you might use // (double forward slash) 218to avoid confusion with the division operator: 219.Bd -literal -offset indent 220expr "//$a" : '.*/\e(.*\e)' 221.Ed 222.Pp 223According to 224.St -p1003.2 , 225.Nm 226has to recognize special option '--', treat it as an end of command 227line options and ignore it. 228Some 229.Nm 230implementations don't recognize it at all, others 231might ignore it even in cases where doing so results in syntax 232error. 233There should be same result for both following examples, 234but it might not always be: 235.Bl -enum -compact -offset indent 236.It 237expr -- : . 238.It 239expr -- -- : . 240.El 241Although 242.Nx 243.Nm 244handles both cases correctly, you should not depend on this behavior 245for portability reasons and avoid passing bare '--' as first 246argument. 247