bin/expr/expr.1

   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
  40 The
  41 .Nm
  42 utility evaluates
  43 .Ar expression
  44 and writes the result on standard output.
  45 .Pp
  46 All operators are separate arguments to the
  47 .Nm
  48 utility.
  49 Characters special to the command interpreter must be escaped.
  50 .Pp
  51 Operators are listed below in order of increasing precedence.
  52 Operators with equal precedence are grouped within { } symbols.
  53 .Bl -tag -width indent
  54 .It Ar expr1 Li \&| Ar expr2
  55 Returns the evaluation of
  56 .Ar expr1
  57 if it is neither an empty string nor zero;
  58 otherwise, returns the evaluation of
  59 .Ar expr2 .
  60 .It Ar expr1 Li \*[Am] Ar expr2
  61 Returns the evaluation of
  62 .Ar expr1
  63 if neither expression evaluates to an empty string or zero;
  64 otherwise, returns zero.
  65 .It Ar expr1 Li "{=, \*[Gt], \*[Ge], \*[Lt], \*[Le], !=}" Ar expr2
  66 Returns the results of integer comparison if both arguments are integers;
  67 otherwise, returns the results of string comparison using the locale-specific
  68 collation sequence.
  69 The result of each comparison is 1 if the specified relation is true,
  70 or 0 if the relation is false.
  71 .It Ar expr1 Li "{+, -}" Ar expr2
  72 Returns the results of addition or subtraction of integer-valued arguments.
  73 .It Ar expr1 Li "{*, /, %}" Ar expr2
  74 Returns the results of multiplication, integer division, or remainder of integer-valued arguments.
  75 .It Ar expr1 Li \&: Ar expr2
  76 The
  77 .Dq \&:
  78 operator matches
  79 .Ar expr1
  80 against
  81 .Ar expr2 ,
  82 which must be a regular expression.
  83 The regular expression is anchored
  84 to the beginning of the string with an implicit
  85 .Dq ^ .
  86 .Pp
  87 If the match succeeds and the pattern contains at least one regular
  88 expression subexpression
  89 .Dq "\e(...\e)" ,
  90 the string corresponding to
  91 .Dq "\e1"
  92 is returned;
  93 otherwise the matching operator returns the number of characters matched.
  94 If the match fails and the pattern contains a regular expression subexpression
  95 the null string is returned;
  96 otherwise 0.
  97 .It "( " Ar expr No " )"
  98 Parentheses are used for grouping in the usual manner.
  99 .El
 100 .Pp
 101 Additionally, the following keywords are recognized:
 102 .Bl -tag -width indent
 103 .It length Ar expr
 104 Returns the length of the specified string in bytes.
 105 .El
 106 .Pp
 107 Operator precedence (from highest to lowest):
 108 .Bl -enum -compact -offset indent
 109 .It
 110 parentheses
 111 .It
 112 length
 113 .It
 114 .Dq \&:
 115 .It
 116 .Dq "*" ,
 117 .Dq "/" ,
 118 and
 119 .Dq "%"
 120 .It
 121 .Dq "+"
 122 and
 123 .Dq "-"
 124 .It
 125 compare operators
 126 .It
 127 .Dq \*[Am]
 128 .It
 129 .Dq \&|
 130 .El
 131 .Sh EXIT STATUS
 132 The
 133 .Nm
 134 utility exits with one of the following values:
 135 .Bl -tag -width Ds -compact
 136 .It 0
 137 the expression is neither an empty string nor 0.
 138 .It 1
 139 the expression is an empty string or 0.
 140 .It 2
 141 the expression is invalid.
 142 .It \*[Gt]2
 143 an error occurred (such as memory allocation failure).
 144 .El
 145 .Sh EXAMPLES
 146 .Bl -enum
 147 .It
 148 The following example adds one to variable
 149 .Dq a :
 150 .Dl a=`expr $a + 1`
 151 .It
 152 The following example returns zero, due to subtraction having higher precedence
 153 than the
 154 .Dq \*[Am]
 155 operator:
 156 .Dl expr 1 '\*[Am]' 1 - 1
 157 .It
 158 The following example returns the filename portion of a pathname stored
 159 in variable
 160 .Dq a :
 161 .Dl expr "/$a" Li : '.*/\e(.*\e)'
 162 .It
 163 The following example returns the number of characters in variable
 164 .Dq a :
 165 .Dl expr $a Li : '.*'
 166 .El
 167 .Sh COMPATIBILITY
 168 This implementation of
 169 .Nm
 170 internally uses 64 bit representation of integers and checks for
 171 over- and underflows.
 172 It also treats
 173 .Dq /
 174 (the division mark) and option
 175 .Dq --
 176 correctly depending upon context.
 177 .Pp
 178 .Nm
 179 on other systems (including
 180 .Nx
 181 up to and including
 182 .Nx 1.5 )
 183 might not be so graceful.
 184 Arithmetic results might be arbitrarily
 185 limited on such systems, most commonly to 32 bit quantities.
 186 This means such
 187 .Nm
 188 can only process values between -2147483648 and +2147483647.
 189 .Pp
 190 On other systems,
 191 .Nm
 192 might also not work correctly for regular expressions where
 193 either side contains
 194 .Dq /
 195 (a single forward slash), like this:
 196 .Bd -literal -offset indent
 197 expr / : '.*/\e(.*\e)'
 198 .Ed
 199 .Pp
 200 If this is the case, you might use
 201 .Dq //
 202 (a double forward slash)
 203 to avoid confusion with the division operator:
 204 .Bd -literal -offset indent
 205 expr "//$a" : '.*/\e(.*\e)'
 206 .Ed
 207 .Pp
 208 According to
 209 .St -p1003.2 ,
 210 .Nm
 211 has to recognize special option
 212 .Dq -- ,
 213 treat it as a delimiter to mark the end of command
 214 line options, and ignore it.
 215 Some
 216 .Nm
 217 implementations do not recognize it at all; others
 218 might ignore it even in cases where doing so results in syntax
 219 error.
 220 There should be same result for both following examples,
 221 but it might not always be:
 222 .Bl -enum -compact -offset indent
 223 .It
 224 expr -- : .
 225 .It
 226 expr -- -- : .
 227 .El
 228 Although
 229 .Nx
 230 .Nm
 231 handles both cases correctly, you should not depend on this behavior
 232 for portability reasons and avoid passing a bare
 233 .Dq --
 234 as the first
 235 argument.
 236 .Sh STANDARDS
 237 The
 238 .Nm
 239 utility conforms to
 240 .St -p1003.2 .
 241 The
 242 .Ar length
 243 keyword is an extension for compatibility with GNU
 244 .Nm .
 245 .Sh HISTORY
 246 An
 247 .Nm
 248 utility first appeared in the Programmer's Workbench (PWB/UNIX).
 249 A public domain version of
 250 .Nm
 251 written by
 252 .An Pace Willisson
 253 .Aq pace@blitz.com
 254 appeared in
 255 .Bx 386 0.1 .
 256 .Sh AUTHORS
 257 Initial implementation by
 258 .An Pace Willisson Aq Mt pace@blitz.com
 259 was largely rewritten by
 260 .An -nosplit
 261 .An J.T. Conklin Aq Mt jtc@NetBSD.org .
 262 It was rewritten again for
 263 .Nx 1.6
 264 by
 265 .An -nosplit
 266 .An Jaromir Dolecek Aq Mt jdolecek@NetBSD.org .
 267 .Sh NOTES
 268 The empty string
 269 .Do Dc
 270 cannot be matched with the intuitive:
 271 .Bd -literal -offset indent
 272 expr '' : '$'
 273 .Ed
 274 .Pp
 275 The reason is that the returned number of matched characters (zero)
 276 is indistinguishable from a failed match, so this returns failure.
 277 To match the empty string, use something like:
 278 .Bd -literal -offset indent
 279 expr x'' : 'x$'
 280 .Ed