expr.1p (12259B)
- '\" et
- .TH EXPR "1P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual"
- .\"
- .SH PROLOG
- This manual page is part of the POSIX Programmer's Manual.
- The Linux implementation of this interface may differ (consult
- the corresponding Linux manual page for details of Linux behavior),
- or the interface may not be implemented on Linux.
- .\"
- .SH NAME
- expr
- \(em evaluate arguments as an expression
- .SH SYNOPSIS
- .LP
- .nf
- expr \fIoperand\fR...
- .fi
- .SH DESCRIPTION
- The
- .IR expr
- utility shall evaluate an expression and write the result to standard
- output.
- .SH OPTIONS
- None.
- .SH OPERANDS
- The single expression evaluated by
- .IR expr
- shall be formed from the
- .IR operand
- operands, as described in the EXTENDED DESCRIPTION section. The
- application shall ensure that each of the expression operator symbols:
- .sp
- .RS 4
- .nf
- ( ) | & = > >= < <= != + - * / % :
- .fi
- .P
- .RE
- .P
- and the symbols
- .IR integer
- and
- .IR string
- in the table are provided as separate arguments to
- .IR expr .
- .SH STDIN
- Not used.
- .SH "INPUT FILES"
- None.
- .SH "ENVIRONMENT VARIABLES"
- The following environment variables shall affect the execution of
- .IR expr :
- .IP "\fILANG\fP" 10
- Provide a default value for the internationalization variables that are
- unset or null. (See the Base Definitions volume of POSIX.1\(hy2017,
- .IR "Section 8.2" ", " "Internationalization Variables"
- for the precedence of internationalization variables used to determine
- the values of locale categories.)
- .IP "\fILC_ALL\fP" 10
- If set to a non-empty string value, override the values of all the
- other internationalization variables.
- .IP "\fILC_COLLATE\fP" 10
- .br
- Determine the locale for the behavior of ranges, equivalence classes,
- and multi-character collating elements within regular expressions and
- by the string comparison operators.
- .IP "\fILC_CTYPE\fP" 10
- Determine the locale for the interpretation of sequences of bytes of
- text data as characters (for example, single-byte as opposed to
- multi-byte characters in arguments) and the behavior of character
- classes within regular expressions.
- .IP "\fILC_MESSAGES\fP" 10
- .br
- Determine the locale that should be used to affect the format and
- contents of diagnostic messages written to standard error.
- .IP "\fINLSPATH\fP" 10
- Determine the location of message catalogs for the processing of
- .IR LC_MESSAGES .
- .SH "ASYNCHRONOUS EVENTS"
- Default.
- .SH STDOUT
- The
- .IR expr
- utility shall evaluate the expression and write the result, followed by
- a
- <newline>,
- to standard output.
- .SH STDERR
- The standard error shall be used only for diagnostic messages.
- .SH "OUTPUT FILES"
- None.
- .SH "EXTENDED DESCRIPTION"
- The formation of the expression to be evaluated is shown in the
- following table. The symbols
- .IR expr ,
- .IR expr1 ,
- and
- .IR expr2
- represent expressions formed from
- .IR integer
- and
- .IR string
- symbols and the expression operator symbols (all separate arguments) by
- recursive application of the constructs described in the table. The
- expressions are listed in order of decreasing precedence, with
- equal-precedence operators grouped between horizontal lines. All of
- the operators shall be left-associative.
- .TS
- center tab(@) box;
- cB | cB
- l | lw(4i).
- Expression@Description
- _
- \fIinteger\fP@T{
- An argument consisting only of an (optional) unary minus followed
- by digits.
- T}
- \fIstring\fP@T{
- A string argument; see below.
- T}
- _
- (\ \fIexpr\fR\ )@T{
- Grouping symbols. Any expression can be placed within parentheses.
- Parentheses can be nested to a depth of
- {EXPR_NEST_MAX}.
- T}
- _
- \fIexpr1\fP\ :\ \fIexpr2\fP@T{
- Matching expression; see below.
- T}
- _
- \fIexpr1\fP\ *\ \fIexpr2\fP@T{
- Multiplication of decimal integer-valued arguments.
- T}
- \fIexpr1\fP\ /\ \fIexpr2\fP@T{
- Integer division of decimal integer-valued arguments, producing
- an integer result.
- T}
- \fIexpr1\fP\ %\ \fIexpr2\fP@T{
- Remainder of integer division of decimal integer-valued arguments.
- T}
- _
- \fIexpr1\fP\ +\ \fIexpr2\fP@T{
- Addition of decimal integer-valued arguments.
- T}
- \fIexpr1\fP\ \-\ \fIexpr2\fP@T{
- Subtraction of decimal integer-valued arguments.
- T}
- _
- @T{
- Returns the result of a decimal integer comparison if both arguments
- are integers; otherwise, returns the result of a string comparison
- using the locale-specific collation sequence. The result of each
- comparison is 1 if the specified relationship is true, or 0 if the
- relationship is false.
- T}
- \fIexpr1\fP\ =\ \fIexpr2\fR@Equal.
- \fIexpr1\fP\ >\ \fIexpr2\fR@Greater than.
- \fIexpr1\fP\ >=\ \fIexpr2\fR@Greater than or equal.
- \fIexpr1\fP\ <\ \fIexpr2\fR@Less than.
- \fIexpr1\fP\ <=\ \fIexpr2\fR@Less than or equal.
- \fIexpr1\fP\ !=\ \fIexpr2\fR@Not equal.
- _
- \fIexpr1\fP\ &\ \fIexpr2\fP@T{
- Returns the evaluation of
- .IR expr1
- if neither expression evaluates to null or zero; otherwise, returns zero.
- T}
- _
- \fIexpr1\fP\ |\ \fIexpr2\fP@T{
- Returns the evaluation of
- .IR expr1
- if it is neither null nor zero; otherwise, returns the evaluation of
- .IR expr2
- if it is not null; otherwise, zero.
- T}
- .TE
- .SS "Matching Expression"
- .P
- The
- .BR ':'
- matching operator shall compare the string resulting from the
- evaluation of
- .IR expr1
- with the regular expression pattern resulting from the evaluation of
- .IR expr2 .
- Regular expression syntax shall be that defined in the Base Definitions volume of POSIX.1\(hy2017,
- .IR "Section 9.3" ", " "Basic Regular Expressions",
- except that all patterns are anchored to the beginning of the string (that
- is, only sequences starting at the first character of a string are matched
- by the regular expression) and, therefore, it is unspecified whether
- .BR '\(ha'
- is a special character in that context. Usually, the matching operator
- shall return a string representing the number of characters matched (\c
- .BR '0'
- on failure). Alternatively, if the pattern contains at least one
- regular expression subexpression
- .BR \(dq[\e(...\e)]\(dq ,
- the string matched by the back-reference expression
- .BR \(dq\e1\(dq
- shall be returned. If the back-reference expression
- .BR \(dq\e1\(dq
- does not match, then the null string shall be returned.
- .SS "Identification as Integer or String"
- .P
- An argument or the value of a subexpression that consists only of an
- optional unary minus followed by digits is a candidate for treatment
- as an integer if it is used as the left argument to the
- .IR |
- operator or as either argument to any of the following operators:
- .IR "& = > >= < <= != + - * / %" .
- Otherwise, the argument or subexpression value shall be treated as a string.
- .P
- The use of string arguments
- .BR length ,
- .BR substr ,
- .BR index ,
- or
- .BR match
- produces unspecified results.
- .SH "EXIT STATUS"
- The following exit values shall be returned:
- .IP "\00" 6
- The
- .IR expression
- evaluates to neither null nor zero.
- .IP "\01" 6
- The
- .IR expression
- evaluates to null or zero.
- .IP "\02" 6
- Invalid
- .IR expression .
- .IP >2 6
- An error occurred.
- .SH "CONSEQUENCES OF ERRORS"
- Default.
- .LP
- .IR "The following sections are informative."
- .SH "APPLICATION USAGE"
- The
- .IR expr
- utility has a rather difficult syntax:
- .IP " *" 4
- Many of the operators are also shell control operators or reserved
- words, so they have to be escaped on the command line.
- .IP " *" 4
- Each part of the expression is composed of separate arguments, so
- liberal usage of
- <blank>
- characters is required. For example:
- .TS
- center tab(@) box;
- cB | cB
- lf5 | lf5.
- Invalid@Valid
- _
- \fIexpr\fR 1+2@\fIexpr\fR 1 + 2
- \fIexpr\fR "1 + 2"@\fIexpr\fR 1 + 2
- \fIexpr\fR 1 + (2 * 3)@\fIexpr\fR 1 + \e( 2 \e* 3 \e)\fR
- .TE
- .P
- In many cases, the arithmetic and string features provided as part of
- the shell command language are easier to use than their equivalents in
- .IR expr .
- Newly written scripts should avoid
- .IR expr
- in favor of the new features within the shell; see
- .IR "Section 2.5" ", " "Parameters and Variables"
- and
- .IR "Section 2.6.4" ", " "Arithmetic Expansion".
- .P
- After argument processing by the shell,
- .IR expr
- is not required to be able to tell the difference between an operator
- and an operand except by the value. If
- .BR \(dq$a\(dq
- is
- .BR '=' ,
- the command:
- .sp
- .RS 4
- .nf
- expr "$a" = \(aq=\(aq
- .fi
- .P
- .RE
- .P
- looks like:
- .sp
- .RS 4
- .nf
- expr = = =
- .fi
- .P
- .RE
- .P
- as the arguments are passed to
- .IR expr
- (and they all may be taken as the
- .BR '='
- operator). The following works reliably:
- .sp
- .RS 4
- .nf
- expr "X$a" = X=
- .fi
- .P
- .RE
- .P
- Also note that this volume of POSIX.1\(hy2017 permits implementations to extend utilities. The
- .IR expr
- utility permits the integer arguments to be preceded with a unary
- minus. This means that an integer argument could look like an option.
- Therefore, the conforming application must employ the
- .BR \(dq--\(dq
- construct of Guideline 10 of the Base Definitions volume of POSIX.1\(hy2017,
- .IR "Section 12.2" ", " "Utility Syntax Guidelines"
- to protect its operands if there is any chance the first operand might
- be a negative integer (or any string with a leading minus).
- .P
- For testing string equality the
- .IR test
- utility is preferred over
- .IR expr ,
- as it is usually implemented as a shell built-in. However, the
- functionality is not quite the same because the
- .IR expr
- .IR =
- and
- .IR !=
- operators check whether strings collate equally, whereas
- .IR test
- checks whether they are identical. Therefore, they can produce
- different results in locales where the collation sequence does not
- have a total ordering of all characters (see the Base Definitions volume of POSIX.1\(hy2017,
- .IR "Section 7.3.2" ", " "LC_COLLATE").
- .br
- .SH EXAMPLES
- The following command:
- .sp
- .RS 4
- .nf
- a=$(expr "$a" + 1)
- .fi
- .P
- .RE
- .P
- adds 1 to the variable
- .IR a .
- .P
- The following command, for
- .BR \(dq$a\(dq
- equal to either
- .BR /usr/abc/file
- or just
- .BR file :
- .sp
- .RS 4
- .nf
- expr $a : \(aq.*/\e(.*\e)\(aq \e| $a
- .fi
- .P
- .RE
- .P
- returns the last segment of a pathname (that is,
- .BR file ).
- Applications should avoid the character
- .BR '/'
- used alone as an argument;
- .IR expr
- may interpret it as the division operator.
- .P
- The following command:
- .sp
- .RS 4
- .nf
- expr "//$a" : \(aq.*/\e(.*\e)\(aq
- .fi
- .P
- .RE
- .P
- is a better representation of the previous example. The addition of
- the
- .BR \(dq//\(dq
- characters eliminates any ambiguity about the division operator and
- simplifies the whole expression. Also note that pathnames may contain
- characters contained in the
- .IR IFS
- variable and should be quoted to avoid having
- .BR \(dq$a\(dq
- expand into multiple arguments.
- .P
- The following command:
- .sp
- .RS 4
- .nf
- expr "X$VAR" : \(aq.*\(aq - 1
- .fi
- .P
- .RE
- .P
- returns the number of characters in
- .IR VAR .
- .SH RATIONALE
- In an early proposal, EREs were used in the matching expression syntax.
- This was changed to BREs to avoid breaking historical applications.
- .P
- The use of a leading
- <circumflex>
- in the BRE is unspecified because many historical implementations have
- treated it as a special character, despite their system documentation. For
- example:
- .sp
- .RS 4
- .nf
- expr foo : \(hafoo expr \(hafoo : \(hafoo
- .fi
- .P
- .RE
- .P
- return 3 and 0, respectively, on those systems; their documentation
- would imply the reverse. Thus, the anchoring condition is left
- unspecified to avoid breaking historical scripts relying on this
- undocumented feature.
- .SH "FUTURE DIRECTIONS"
- None.
- .SH "SEE ALSO"
- .IR "Section 2.5" ", " "Parameters and Variables",
- .IR "Section 2.6.4" ", " "Arithmetic Expansion"
- .P
- The Base Definitions volume of POSIX.1\(hy2017,
- .IR "Section 7.3.2" ", " "LC_COLLATE",
- .IR "Chapter 8" ", " "Environment Variables",
- .IR "Section 9.3" ", " "Basic Regular Expressions",
- .IR "Section 12.2" ", " "Utility Syntax Guidelines"
- .\"
- .SH COPYRIGHT
- Portions of this text are reprinted and reproduced in electronic form
- from IEEE Std 1003.1-2017, Standard for Information Technology
- -- Portable Operating System Interface (POSIX), The Open Group Base
- Specifications Issue 7, 2018 Edition,
- Copyright (C) 2018 by the Institute of
- Electrical and Electronics Engineers, Inc and The Open Group.
- In the event of any discrepancy between this version and the original IEEE and
- The Open Group Standard, the original IEEE and The Open Group Standard
- is the referee document. The original Standard can be obtained online at
- http://www.opengroup.org/unix/online.html .
- .PP
- Any typographical or formatting errors that appear
- in this page are most likely
- to have been introduced during the conversion of the source files to
- man page format. To report such errors, see
- https://www.kernel.org/doc/man-pages/reporting_bugs.html .