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 July 12, 2004
  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.
  54 .Pp
  55 Arithmetic operations are performed using signed integer math.
  56 If the
  57 .Fl e
  58 flag is specified, arithmetic uses the C
  59 .Vt intmax_t
  60 data type (the largest integral type available), and
  61 .Nm
  62 will detect arithmetic overflow and return an error indication.
  63 If a numeric operand is specified which is so large as to overflow
  64 conversion to an integer, it is parsed as a string instead.
  65 If
  66 .Fl e
  67 is not specified, arithmetic operations and parsing of integer
  68 arguments will overflow silently according to the rules of the C
  69 standard, using the
  70 .Vt long
  71 data type.
  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 .Bl -tag -width indent
  77 .It Ar expr1 Li | Ar expr2
  78 Return the evaluation of
  79 .Ar expr1
  80 if it is neither an empty string nor zero;
  81 otherwise, returns the evaluation of
  82 .Ar expr2 .
  83 .It Ar expr1 Li & Ar expr2
  84 Return the evaluation of
  85 .Ar expr1
  86 if neither expression evaluates to an empty string or zero;
  87 otherwise, returns zero.
  88 .It Ar expr1 Li "{=, >, >=, <, <=, !=}" Ar expr2
  89 Return the results of integer comparison if both arguments are integers;
  90 otherwise, returns the results of string comparison using the locale-specific
  91 collation sequence.
  92 The result of each comparison is 1 if the specified relation is true,
  93 or 0 if the relation is false.
  94 .It Ar expr1 Li "{+, -}" Ar expr2
  95 Return the results of addition or subtraction of integer-valued arguments.
  96 .It Ar expr1 Li "{*, /, %}" Ar expr2
  97 Return the results of multiplication, integer division, or remainder of integer-valued arguments.
  98 .It Ar expr1 Li : Ar expr2
  99 The
 100 .Dq \&:
 101 operator matches
 102 .Ar expr1
 103 against
 104 .Ar expr2 ,
 105 which must be a basic regular expression.
 106 The regular expression is anchored
 107 to the beginning of the string with an implicit
 108 .Dq ^ .
 109 .Pp
 110 If the match succeeds and the pattern contains at least one regular
 111 expression subexpression
 112 .Dq "\e(...\e)" ,
 113 the string corresponding to
 114 .Dq "\e1"
 115 is returned;
 116 otherwise the matching operator returns the number of characters matched.
 117 If the match fails and the pattern contains a regular expression subexpression
 118 the null string is returned;
 119 otherwise 0.
 120 .El
 121 .Pp
 122 Parentheses are used for grouping in the usual manner.
 123 .Pp
 124 The
 125 .Nm
 126 utility makes no lexical distinction between arguments which may be
 127 operators and arguments which may be operands.
 128 An operand which is lexically identical to an operator will be considered a
 129 syntax error.
 130 See the examples below for a work-around.
 131 .Pp
 132 The syntax of the
 133 .Nm
 134 command in general is historic and inconvenient.
 135 New applications are advised to use shell arithmetic rather than
 136 .Nm .
 137 .Ss Compatibility with previous implementations
 138 Unless
 139 .Fx
 140 4.x
 141 compatibility is enabled, this version of
 142 .Nm
 143 adheres to the
 144 .Tn POSIX
 145 Utility Syntax Guidelines, which require that a leading argument beginning
 146 with a minus sign be considered an option to the program.
 147 The standard
 148 .Fl Fl
 149 syntax may be used to prevent this interpretation.
 150 However, many historic implementations of
 151 .Nm ,
 152 including the one in previous versions of
 153 .Fx ,
 154 will not permit this syntax.
 155 See the examples below for portable ways to guarantee the correct
 156 interpretation.
 157 The
 158 .Xr check_utility_compat 3
 159 function (with a
 160 .Fa utility
 161 argument of
 162 .Dq Li expr )
 163 is used to determine whether compatibility mode should be enabled.
 164 This feature is intended for use as a transition and debugging aid, when
 165 .Nm
 166 is used in complex scripts which cannot easily be recast to avoid the
 167 non-portable usage.
 168 Enabling compatibility mode
 169 also implicitly enables the
 170 .Fl e
 171 option, since this matches the historic behavior of
 172 .Nm
 173 in
 174 .Fx .
 175 For historical reasons, defining the environment variable
 176 .Ev EXPR_COMPAT
 177 also enables compatibility mode.
 178 .Sh ENVIRONMENT
 179 .Bl -tag -width ".Ev EXPR_COMPAT"
 180 .It Ev EXPR_COMPAT
 181 If set, enables compatibility mode.
 182 .El
 183 .Sh EXIT STATUS
 184 The
 185 .Nm
 186 utility exits with one of the following values:
 187 .Bl -tag -width indent -compact
 188 .It 0
 189 the expression is neither an empty string nor 0.
 190 .It 1
 191 the expression is an empty string or 0.
 192 .It 2
 193 the expression is invalid.
 194 .El
 195 .Sh EXAMPLES
 196 .Bl -bullet
 197 .It
 198 The following example (in
 199 .Xr sh 1
 200 syntax) adds one to the variable
 201 .Va a :
 202 .Dl "a=$(expr $a + 1)"
 203 .It
 204 This will fail if the value of
 205 .Va a
 206 is a negative number.
 207 To protect negative values of
 208 .Va a
 209 from being interpreted as options to the
 210 .Nm
 211 command, one might rearrange the expression:
 212 .Dl "a=$(expr 1 + $a)"
 213 .It
 214 More generally, parenthesize possibly-negative values:
 215 .Dl "a=$(expr \e( $a \e) + 1)"
 216 .It
 217 This example prints the filename portion of a pathname stored
 218 in variable
 219 .Va a .
 220 Since
 221 .Va a
 222 might represent the path
 223 .Pa / ,
 224 it is necessary to prevent it from being interpreted as the division operator.
 225 The
 226 .Li //
 227 characters resolve this ambiguity.
 228 .Dl "expr \*q//$a\*q \&: '.*/\e(.*\e)'"
 229 .El
 230 .Pp
 231 The following examples output the number of characters in variable
 232 .Va a .
 233 Again, if
 234 .Va a
 235 might begin with a hyphen, it is necessary to prevent it from being
 236 interpreted as an option to
 237 .Nm .
 238 .Bl -bullet
 239 .It
 240 If the
 241 .Nm
 242 command conforms to
 243 .St -p1003.1-2001 ,
 244 this is simple:
 245 .Dl "expr -- \*q$a\*q \&: \*q.*\*q"
 246 .It
 247 For portability to older systems, however, a more complicated command
 248 is required:
 249 .Dl "expr \e( \*qX$a\*q \&: \*q.*\*q \e) - 1"
 250 .El
 251 .Sh SEE ALSO
 252 .Xr sh 1 ,
 253 .Xr test 1 ,
 254 .Xr check_utility_compat 3
 255 .Sh STANDARDS
 256 The
 257 .Nm
 258 utility conforms to
 259 .St -p1003.1-2001 ,
 260 provided that compatibility mode is not enabled.
 261 The
 262 .Fl e
 263 flag is an extension.