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 February 25, 2012
  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 compatibility 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.
 180 In addition, empty operands
 181 have an implied value of zero in numeric context.
 182 For historical reasons, defining the environment variable
 183 .Ev EXPR_COMPAT
 184 also enables backwards compatibility mode.
 185 .Sh ENVIRONMENT
 186 .Bl -tag -width ".Ev EXPR_COMPAT"
 187 .It Ev EXPR_COMPAT
 188 If set, enables backwards compatibility mode.
 189 .El
 190 .Sh EXIT STATUS
 191 The
 192 .Nm
 193 utility exits with one of the following values:
 194 .Bl -tag -width indent -compact
 195 .It 0
 196 the expression is neither an empty string nor 0.
 197 .It 1
 198 the expression is an empty string or 0.
 199 .It 2
 200 the expression is invalid.
 201 .El
 202 .Sh EXAMPLES
 203 .Bl -bullet
 204 .It
 205 The following example (in
 206 .Xr sh 1
 207 syntax) adds one to the variable
 208 .Va a :
 209 .Dl "a=$(expr $a + 1)"
 210 .It
 211 This will fail if the value of
 212 .Va a
 213 is a negative number.
 214 To protect negative values of
 215 .Va a
 216 from being interpreted as options to the
 217 .Nm
 218 command, one might rearrange the expression:
 219 .Dl "a=$(expr 1 + $a)"
 220 .It
 221 More generally, parenthesize possibly-negative values:
 222 .Dl "a=$(expr \e( $a \e) + 1)"
 223 .It
 224 With shell arithmetic, no escaping is required:
 225 .Dl "a=$((a + 1))"
 226 .It
 227 This example prints the filename portion of a pathname stored
 228 in variable
 229 .Va a .
 230 Since
 231 .Va a
 232 might represent the path
 233 .Pa / ,
 234 it is necessary to prevent it from being interpreted as the division operator.
 235 The
 236 .Li //
 237 characters resolve this ambiguity.
 238 .Dl "expr \*q//$a\*q \&: '.*/\e(.*\e)'"
 239 .It
 240 With modern
 241 .Xr sh 1
 242 syntax,
 243 .Dl "\*q${a##*/}\*q"
 244 expands to the same value.
 245 .El
 246 .Pp
 247 The following examples output the number of characters in variable
 248 .Va a .
 249 Again, if
 250 .Va a
 251 might begin with a hyphen, it is necessary to prevent it from being
 252 interpreted as an option to
 253 .Nm ,
 254 and
 255 .Va a
 256 might be interpreted as an operator.
 257 .Bl -bullet
 258 .It
 259 To deal with all of this, a complicated command
 260 is required:
 261 .Dl "expr \e( \*qX$a\*q \&: \*q.*\*q \e) - 1"
 262 .It
 263 With modern
 264 .Xr sh 1
 265 syntax, this can be done much more easily:
 266 .Dl "${#a}"
 267 expands to the required number.
 268 .El
 269 .Sh SEE ALSO
 270 .Xr sh 1 ,
 271 .Xr test 1 ,
 272 .Xr check_utility_compat 3
 273 .Sh STANDARDS
 274 The
 275 .Nm
 276 utility conforms to
 277 .St -p1003.1-2008 ,
 278 provided that backwards compatibility mode is not enabled.
 279 .Pp
 280 Backwards compatibility mode performs less strict checks of numeric arguments:
 281 .Bl -bullet
 282 .It
 283 An empty operand string is interpreted as 0.
 284 .El
 285 .Bl -bullet
 286 .It
 287 Leading white space and/or a plus sign before an otherwise valid positive
 288 numeric operand are allowed and will be ignored.
 289 .El
 290 .Pp
 291 The extended arithmetic range and overflow checks do not conflict with
 292 POSIX's requirement that arithmetic be done using signed longs, since
 293 they only make a difference to the result in cases where using signed
 294 longs would give undefined behavior.
 295 .Pp
 296 According to the
 297 .Tn POSIX
 298 standard, the use of string arguments
 299 .Va length ,
 300 .Va substr ,
 301 .Va index ,
 302 or
 303 .Va match
 304 produces undefined results.
 305 In this version of
 306 .Nm ,
 307 these arguments are treated just as their respective string values.
 308 .Pp
 309 The
 310 .Fl e
 311 flag is an extension.