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