1.\" $NetBSD: expr.1,v 1.36 2016/08/23 20:34:23 sevan 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 August 23, 2016 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 variable 149.Dq a : 150.Dl a=`expr $a + 1` 151.It 152The following example returns zero, due to subtraction having higher precedence 153than the 154.Dq \*[Am] 155operator: 156.Dl expr 1 '\*[Am]' 1 - 1 157.It 158The following example returns the filename portion of a pathname stored 159in variable 160.Dq a : 161.Dl expr "/$a" Li : '.*/\e(.*\e)' 162.It 163The following example returns the number of characters in variable 164.Dq a : 165.Dl expr $a Li : '.*' 166.El 167.Sh COMPATIBILITY 168This implementation of 169.Nm 170internally uses 64 bit representation of integers and checks for 171over- and underflows. 172It also treats 173.Dq / 174(the division mark) and option 175.Dq -- 176correctly depending upon context. 177.Pp 178.Nm 179on other systems (including 180.Nx 181up to and including 182.Nx 1.5 ) 183might not be so graceful. 184Arithmetic results might be arbitrarily 185limited on such systems, most commonly to 32 bit quantities. 186This means such 187.Nm 188can only process values between -2147483648 and +2147483647. 189.Pp 190On other systems, 191.Nm 192might also not work correctly for regular expressions where 193either side contains 194.Dq / 195(a single forward slash), like this: 196.Bd -literal -offset indent 197expr / : '.*/\e(.*\e)' 198.Ed 199.Pp 200If this is the case, you might use 201.Dq // 202(a double forward slash) 203to avoid confusion with the division operator: 204.Bd -literal -offset indent 205expr "//$a" : '.*/\e(.*\e)' 206.Ed 207.Pp 208According to 209.St -p1003.2 , 210.Nm 211has to recognize special option 212.Dq -- , 213treat it as a delimiter to mark the end of command 214line options, and ignore it. 215Some 216.Nm 217implementations do not recognize it at all; others 218might ignore it even in cases where doing so results in syntax 219error. 220There should be same result for both following examples, 221but it might not always be: 222.Bl -enum -compact -offset indent 223.It 224expr -- : . 225.It 226expr -- -- : . 227.El 228Although 229.Nx 230.Nm 231handles both cases correctly, you should not depend on this behavior 232for portability reasons and avoid passing a bare 233.Dq -- 234as the first 235argument. 236.Sh STANDARDS 237The 238.Nm 239utility conforms to 240.St -p1003.2 . 241The 242.Ar length 243keyword is an extension for compatibility with GNU 244.Nm . 245.Sh HISTORY 246An 247.Nm 248utility first appeared in the Programmer's Workbench (PWB/UNIX). 249A public domain version of 250.Nm 251written by 252.An Pace Willisson 253.Aq pace@blitz.com 254appeared in 255.Bx 386 0.1 . 256.Sh AUTHORS 257Initial implementation by 258.An Pace Willisson Aq Mt pace@blitz.com 259was largely rewritten by 260.An -nosplit 261.An J.T. Conklin Aq Mt jtc@NetBSD.org . 262It was rewritten again for 263.Nx 1.6 264by 265.An -nosplit 266.An Jaromir Dolecek Aq Mt jdolecek@NetBSD.org . 267.Sh NOTES 268The empty string 269.Do Dc 270cannot be matched with the intuitive: 271.Bd -literal -offset indent 272expr '' : '$' 273.Ed 274.Pp 275The reason is that the returned number of matched characters (zero) 276is indistinguishable from a failed match, so this returns failure. 277To match the empty string, use something like: 278.Bd -literal -offset indent 279expr x'' : 'x$' 280.Ed 281