bin/expr/expr.1

   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 September 9, 2010
  34 .Dt EXPR 1
  35 .Os
  36 .Sh NAME
  37 .Nm expr
  38 .Nd evaluate expression
  39 .Sh SYNOPSIS
  40 .Nm
  41 .Op Fl e
  42 .Ar expression
  43 .Sh DESCRIPTION
  44 The
  45 .Nm
  46 utility evaluates
  47 .Ar expression
  48 and writes the result on standard output.
  49 .Pp
  50 All operators and operands must be passed as separate arguments.
  51 Several of the operators have special meaning to command interpreters
  52 and must therefore be quoted appropriately.
  53 All integer operands are interpreted in base 10 and must consist of only
  54 an optional leading minus sign followed by one or more digits (unless
  55 less strict parsing has been enabled for backwards compatibilty with
  56 prior versions of
  57 .Nm
  58 in
  59 .Fx ) .
  60 .Pp
  61 Arithmetic operations are performed using signed integer math with a
  62 range according to the C
  63 .Vt intmax_t
  64 data type (the largest signed integral type available).
  65 All conversions and operations are checked for overflow.
  66 Overflow results in program termination with an error message on stdout
  67 and with an error status.
  68 .Pp
  69 The
  70 .Fl e
  71 option enables backwards compatible behaviour as detailed below.
  72 .Pp
  73 Operators are listed below in order of increasing precedence; all
  74 are left-associative.
  75 Operators with equal precedence are grouped within symbols
  76 .Ql {
  77 and
  78 .Ql } .
  79 .Bl -tag -width indent
  80 .It Ar expr1 Li | Ar expr2
  81 Return the evaluation of
  82 .Ar expr1
  83 if it is neither an empty string nor zero;
  84 otherwise, returns the evaluation of
  85 .Ar expr2
  86 if it is not an empty string;
  87 otherwise, returns zero.
  88 .It Ar expr1 Li & Ar expr2
  89 Return the evaluation of
  90 .Ar expr1
  91 if neither expression evaluates to an empty string or zero;
  92 otherwise, returns zero.
  93 .It Ar expr1 Li "{=, >, >=, <, <=, !=}" Ar expr2
  94 Return the results of integer comparison if both arguments are integers;
  95 otherwise, returns the results of string comparison using the locale-specific
  96 collation sequence.
  97 The result of each comparison is 1 if the specified relation is true,
  98 or 0 if the relation is false.
  99 .It Ar expr1 Li "{+, -}" Ar expr2
 100 Return the results of addition or subtraction of integer-valued arguments.
 101 .It Ar expr1 Li "{*, /, %}" Ar expr2
 102 Return the results of multiplication, integer division, or remainder of integer-valued arguments.
 103 .It Ar expr1 Li : Ar expr2
 104 The
 105 .Dq Li \&:
 106 operator matches
 107 .Ar expr1
 108 against
 109 .Ar expr2 ,
 110 which must be a basic regular expression.
 111 The regular expression is anchored
 112 to the beginning of the string with an implicit
 113 .Dq Li ^ .
 114 .Pp
 115 If the match succeeds and the pattern contains at least one regular
 116 expression subexpression
 117 .Dq Li "\e(...\e)" ,
 118 the string corresponding to
 119 .Dq Li \e1
 120 is returned;
 121 otherwise the matching operator returns the number of characters matched.
 122 If the match fails and the pattern contains a regular expression subexpression
 123 the null string is returned;
 124 otherwise 0.
 125 .El
 126 .Pp
 127 Parentheses are used for grouping in the usual manner.
 128 .Pp
 129 The
 130 .Nm
 131 utility makes no lexical distinction between arguments which may be
 132 operators and arguments which may be operands.
 133 An operand which is lexically identical to an operator will be considered a
 134 syntax error.
 135 See the examples below for a work-around.
 136 .Pp
 137 The syntax of the
 138 .Nm
 139 command in general is historic and inconvenient.
 140 New applications are advised to use shell arithmetic rather than
 141 .Nm .
 142 .Ss Compatibility with previous implementations
 143 Unless
 144 .Fx
 145 4.x
 146 compatibility is enabled, this version of
 147 .Nm
 148 adheres to the
 149 .Tn POSIX
 150 Utility Syntax Guidelines, which require that a leading argument beginning
 151 with a minus sign be considered an option to the program.
 152 The standard
 153 .Fl Fl
 154 syntax may be used to prevent this interpretation.
 155 However, many historic implementations of
 156 .Nm ,
 157 including the one in previous versions of
 158 .Fx ,
 159 will not permit this syntax.
 160 See the examples below for portable ways to guarantee the correct
 161 interpretation.
 162 The
 163 .Xr check_utility_compat 3
 164 function (with a
 165 .Fa utility
 166 argument of
 167 .Dq Li expr )
 168 is used to determine whether backwards compatibility mode should be enabled.
 169 This feature is intended for use as a transition and debugging aid, when
 170 .Nm
 171 is used in complex scripts which cannot easily be recast to avoid the
 172 non-portable usage.
 173 Enabling backwards compatibility mode also implicitly enables the
 174 .Fl e
 175 option, since this matches the historic behavior of
 176 .Nm
 177 in
 178 .Fx . This option makes number parsing less strict and permits leading
 179 white space and an optional leading plus sign. In addition, empty operands
 180 have an implied value of zero in numeric context.
 181 For historical reasons, defining the environment variable
 182 .Ev EXPR_COMPAT
 183 also enables backwards compatibility mode.
 184 .Sh ENVIRONMENT
 185 .Bl -tag -width ".Ev EXPR_COMPAT"
 186 .It Ev EXPR_COMPAT
 187 If set, enables backwards compatibility mode.
 188 .El
 189 .Sh EXIT STATUS
 190 The
 191 .Nm
 192 utility exits with one of the following values:
 193 .Bl -tag -width indent -compact
 194 .It 0
 195 the expression is neither an empty string nor 0.
 196 .It 1
 197 the expression is an empty string or 0.
 198 .It 2
 199 the expression is invalid.
 200 .El
 201 .Sh EXAMPLES
 202 .Bl -bullet
 203 .It
 204 The following example (in
 205 .Xr sh 1
 206 syntax) adds one to the variable
 207 .Va a :
 208 .Dl "a=$(expr $a + 1)"
 209 .It
 210 This will fail if the value of
 211 .Va a
 212 is a negative number.
 213 To protect negative values of
 214 .Va a
 215 from being interpreted as options to the
 216 .Nm
 217 command, one might rearrange the expression:
 218 .Dl "a=$(expr 1 + $a)"
 219 .It
 220 More generally, parenthesize possibly-negative values:
 221 .Dl "a=$(expr \e( $a \e) + 1)"
 222 .It
 223 With shell arithmetic, no escaping is required:
 224 .Dl "a=$((a + 1))"
 225 .It
 226 This example prints the filename portion of a pathname stored
 227 in variable
 228 .Va a .
 229 Since
 230 .Va a
 231 might represent the path
 232 .Pa / ,
 233 it is necessary to prevent it from being interpreted as the division operator.
 234 The
 235 .Li //
 236 characters resolve this ambiguity.
 237 .Dl "expr \*q//$a\*q \&: '.*/\e(.*\e)'"
 238 .It
 239 With modern
 240 .Xr sh 1
 241 syntax,
 242 .Dl "\*q${a##*/}\*q"
 243 expands to the same value.
 244 .El
 245 .Pp
 246 The following examples output the number of characters in variable
 247 .Va a .
 248 Again, if
 249 .Va a
 250 might begin with a hyphen, it is necessary to prevent it from being
 251 interpreted as an option to
 252 .Nm ,
 253 and
 254 .Va a
 255 might be interpreted as an operator.
 256 .Bl -bullet
 257 .It
 258 To deal with all of this, a complicated command
 259 is required:
 260 .Dl "expr \e( \*qX$a\*q \&: \*q.*\*q \e) - 1"
 261 .It
 262 With modern
 263 .Xr sh 1
 264 syntax, this can be done much more easily:
 265 .Dl "${#a}"
 266 expands to the required number.
 267 .El
 268 .Sh SEE ALSO
 269 .Xr sh 1 ,
 270 .Xr test 1 ,
 271 .Xr check_utility_compat 3
 272 .Sh STANDARDS
 273 The
 274 .Nm
 275 utility conforms to
 276 .St -p1003.1-2008 ,
 277 provided that backwards compatibility mode is not enabled.
 278 .Pp
 279 Backwards compatibility mode performs less strict checks of numeric arguments:
 280 .Bl -bullet
 281 .It
 282 An empty operand string is interpreted as 0.
 283 .El
 284 .Bl -bullet
 285 .It
 286 Leading white space and/or a plus sign before an otherwise valid positive
 287 numberic operand are allowed and will be ignored.
 288 .El
 289 .Pp
 290 The extended arithmetic range and overflow checks do not conflict with
 291 POSIX's requirement that arithmetic be done using signed longs, since
 292 they only make a difference to the result in cases where using signed
 293 longs would give undefined behavior.
 294 .Pp
 295 According to the
 296 .Tn POSIX
 297 standard, the use of string arguments
 298 .Va length ,
 299 .Va substr ,
 300 .Va index ,
 301 or
 302 .Va match
 303 produces undefined results. In this version of
 304 .Nm ,
 305 these arguments are treated just as their respective string values.
 306 .Pp
 307 The
 308 .Fl e
 309 flag is an extension.