1.\" $NetBSD: expr.1,v 1.28 2004/04/23 13:28:58 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 April 20, 2004 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 No " )" 105Parentheses are used for grouping in the usual manner. 106.El 107.Pp 108Additionally, the following keywords are recognized: 109.Bl -tag -width indent 110.It length Ar expr 111Returns the length of the specified string in bytes. 112.El 113.Pp 114Operator precedence (from highest to lowest): 115.Bl -enum -compact -offset indent 116.It 117parentheses 118.It 119length 120.It 121.Dq \&: 122.It 123.Dq "*" , 124.Dq "/" , 125and 126.Dq "%" 127.It 128.Dq "+" 129and 130.Dq "-" 131.It 132compare operators 133.It 134.Dq \*[Am] 135.It 136.Dq \Z'\*[tty-rn]'| 137.El 138.Sh EXIT STATUS 139The 140.Nm 141utility exits with one of the following values: 142.Bl -tag -width Ds -compact 143.It 0 144the expression is neither an empty string nor 0. 145.It 1 146the expression is an empty string or 0. 147.It 2 148the expression is invalid. 149.It \*[Gt]2 150an error occurred (such as memory allocation failure). 151.El 152.Sh EXAMPLES 153.Bl -enum 154.It 155The following example adds one to the variable a. 156.Dl a=`expr $a + 1` 157.It 158The following example returns zero, due to deduction having higher precedence 159than '\*[Am]' operator. 160.Dl expr 1 '\*[Am]' 1 - 1 161.It 162The following example returns the filename portion of a pathname stored 163in variable a. 164.Dl expr "/$a" Li : '.*/\e(.*\e)' 165.It 166The following example returns the number of characters in variable a. 167.Dl expr $a Li : '.*' 168.El 169.Sh STANDARDS 170The 171.Nm 172utility conforms to 173.St -p1003.2 . 174The 175.Ar length 176keyword is an extension for compatibility with GNU 177.Nm . 178.Sh AUTHORS 179Original implementation was written by 180.An J.T. Conklin 181.Aq jtc@NetBSD.org . 182It was rewritten for 183.Nx 1.6 184by 185.An Jaromir Dolecek 186.Aq jdolecek@NetBSD.org . 187.Sh NOTES 188The empty string 189.Dq 190cannot be matched with the intuitive: 191.Bd -literal -offset indent 192expr '' : '$' 193.Ed 194.Pp 195The reason is that the returned number of matched characters (zero) 196is indistinguishable from a failed match, so this returns failure. 197To match the empty string, use something like: 198.Bd -literal -offset indent 199expr x'' : 'x$' 200.Ed 201.Sh COMPATIBILITY 202This implementation of 203.Nm 204internally uses 64 bit representation of integers and checks for 205over- and underflows. 206It also treats / (division mark) and 207option '--' correctly depending upon context. 208.Pp 209.Nm 210on other systems (including 211.Nx 212up to and including 213.Nx 1.5 ) 214might not be so graceful. 215Arithmetic results might be arbitrarily 216limited on such systems, most commonly to 32 bit quantities. 217This means such 218.Nm 219can only process values between -2147483648 and +2147483647. 220.Pp 221On other systems, 222.Nm 223might also not work correctly for regular expressions where 224either side contains single forward slash, like this: 225.Bd -literal -offset indent 226expr / : '.*/\e(.*\e)' 227.Ed 228.Pp 229If this is the case, you might use // (double forward slash) 230to avoid confusion with the division operator: 231.Bd -literal -offset indent 232expr "//$a" : '.*/\e(.*\e)' 233.Ed 234.Pp 235According to 236.St -p1003.2 , 237.Nm 238has to recognize special option '--', treat it as an end of command 239line options and ignore it. 240Some 241.Nm 242implementations don't recognize it at all, others 243might ignore it even in cases where doing so results in syntax 244error. 245There should be same result for both following examples, 246but it might not always be: 247.Bl -enum -compact -offset indent 248.It 249expr -- : . 250.It 251expr -- -- : . 252.El 253Although 254.Nx 255.Nm 256handles both cases correctly, you should not depend on this behavior 257for portability reasons and avoid passing bare '--' as first 258argument. 259