16. Conditions

This section describes commands that are primarily useful for their exit status, rather than their output. Thus, they are often used as the condition of shell if statements, or as the last command in a pipeline.

16.1 false: Do nothing, unsuccessfully		Do nothing, unsuccessfully.
16.2 true: Do nothing, successfully		Do nothing, successfully.
16.3 test: Check file types and compare values		Check file types and compare values.
16.4 expr: Evaluate expressions		Evaluate expressions.

16.1 false: Do nothing, unsuccessfully

false does nothing except return an exit status of 1, meaning failure. It can be used as a place holder in shell scripts where an unsuccessful command is needed.

By default, false honors the `--help' and `--version' options. However, that is contrary to POSIX, so when the environment variable POSIXLY_CORRECT is set, false ignores all command line arguments, including `--help' and `--version'.

This version of false is implemented as a C program, and is thus more secure and faster than a shell script implementation, and may safely be used as a dummy shell for the purpose of disabling accounts.

16.2 true: Do nothing, successfully

true does nothing except return an exit status of 0, meaning success. It can be used as a place holder in shell scripts where a successful command is needed, although the shell built-in command : (colon) may do the same thing faster. In most modern shells, true is a built-in command, so when you use `true' in a script, you're probably using the built-in command, not the one documented here.

By default, true honors the `--help' and `--version' options. However, that is contrary to POSIX, so when the environment variable POSIXLY_CORRECT is set, true ignores all command line arguments, including `--help' and `--version'.

This version of true is implemented as a C program, and is thus more secure and faster than a shell script implementation, and may safely be used as a dummy shell for the purpose of disabling accounts.

16.3 test: Check file types and compare values

test returns a status of 0 (true) or 1 (false) depending on the evaluation of the conditional expression expr. Each part of the expression must be a separate argument.

test has file status checks, string operators, and numeric comparison operators.

Because most shells have a built-in command by the same name, using the unadorned command name in a script or interactively may get you different functionality than that described here.

Besides the options below, test accepts a lone `--help' or `--version'. See section 2. Common options. A single non-option argument is also allowed: test returns true if the argument is not null.

16.3.1 File type tests		-[bcdfhLpSt]
16.3.2 Access permission tests		-[gkruwxOG]
16.3.3 File characteristic tests		-e -s -nt -ot -ef
16.3.4 String tests		-z -n = !=
16.3.5 Numeric tests		-eq -ne -lt -le -gt -ge
16.3.6 Connectives for test		! -a -o

16.3.1 File type tests

These options test for particular types of files. (Everything's a file, but not all files are the same!)

`-b file'

True if file exists and is a block special device.

`-c file'

True if file exists and is a character special device.

`-d file'

True if file exists and is a directory.

`-f file'

True if file exists and is a regular file.

`-h file'

`-L file'

True if file exists and is a symbolic link.

`-p file'

True if file exists and is a named pipe.

`-S file'

True if file exists and is a socket.

`-t [fd]'

True if fd is opened on a terminal. If fd is omitted, it defaults to 1 (standard output).

16.3.2 Access permission tests

These options test for particular access permissions.

`-g file'

True if file exists and has its set-group-id bit set.

`-k file'

True if file has its sticky bit set.

`-r file'

True if file exists and is readable.

`-u file'

True if file exists and has its set-user-id bit set.

`-w file'

True if file exists and is writable.

`-x file'

True if file exists and is executable.

`-O file'

True if file exists and is owned by the current effective user id.

`-G file'

True if file exists and is owned by the current effective group id.

16.3.3 File characteristic tests

These options test other file characteristics.

`-e file'

True if file exists.

`-s file'

True if file exists and has a size greater than zero.

`file1 -nt file2'

True if file1 is newer (according to modification date) than file2, or if file1 exists and file2 does not.

`file1 -ot file2'

True if file1 is older (according to modification date) than file2, or if file2 exists and file1 does not.

`file1 -ef file2'

True if file1 and file2 have the same device and inode numbers, i.e., if they are hard links to each other.

16.3.4 String tests

These options test string characteristics. Strings are not quoted for test, though you may need to quote them to protect characters with special meaning to the shell, e.g., spaces.

`-z string'

True if the length of string is zero.

`-n string'

`string'

True if the length of string is nonzero.

`string1 = string2'

True if the strings are equal.

`string1 != string2'

True if the strings are not equal.

16.3.5 Numeric tests

Numeric relationals. The arguments must be entirely numeric (possibly negative), or the special expression -l string, which evaluates to the length of string.

`arg1 -eq arg2'

`arg1 -ne arg2'

`arg1 -lt arg2'

`arg1 -le arg2'

`arg1 -gt arg2'

`arg1 -ge arg2'

These arithmetic binary operators return true if arg1 is equal, not-equal, less-than, less-than-or-equal, greater-than, or greater-than-or-equal than arg2, respectively.

For example:

test -1 -gt -2 && echo yes => yes test -l abc -gt 1 && echo yes => yes test 0x100 -eq 1 error--> test: integer expression expected before -eq

16.3.6 Connectives for test

The usual logical connectives.

`! expr'

True if expr is false.

`expr1 -a expr2'

True if both expr1 and expr2 are true.

`expr1 -o expr2'

True if either expr1 or expr2 is true.

16.4 expr: Evaluate expressions

expr evaluates an expression and writes the result on standard output. Each token of the expression must be a separate argument.

Operands are either numbers or strings. expr converts anything appearing in an operand position to an integer or a string depending on the operation being applied to it.

Strings are not quoted for expr itself, though you may need to quote them to protect characters with special meaning to the shell, e.g., spaces.

Operators may be given as infix symbols or prefix keywords. Parentheses may be used for grouping in the usual manner (you must quote parentheses to avoid the shell evaluating them, however).

Exit status:

0 if the expression is neither null nor 0, 1 if the expression is null or 0, 2 for invalid expressions.

16.4.1 String expressions		+ : match substr index length
16.4.2 Numeric expressions		+ - * / %
16.4.3 Relations for expr		| & < <= = == != >= >
16.4.4 Examples of using expr		Examples.

16.4.1 String expressions

expr supports pattern matching and other string operators. These have lower precedence than both the numeric and relational operators (in the next sections).

`string : regex'

Perform pattern matching. The arguments are converted to strings and the second is considered to be a (basic, a la GNU grep) regular expression, with a ^ implicitly prepended. The first argument is then matched against this regular expression.

If the match succeeds and regex uses `\(' and `\)', the : expression returns the part of string that matched the subexpression; otherwise, it returns the number of characters matched.

If the match fails, the : operator returns the null string if `\(' and `\)' are used in regex, otherwise 0.

Only the first `\( ... \)' pair is relevant to the return value; additional pairs are meaningful only for grouping the regular expression operators.

In the regular expression, \+, \?, and \| are operators which respectively match one or more, zero or one, or separate alternatives. SunOS and other expr's treat these as regular characters. (POSIX allows either behavior.) See section `Regular Expression Library' in Regex, for details of regular expression syntax. Some examples are in 16.4.4 Examples of using expr.

`match string regex'

An alternative way to do pattern matching. This is the same as `string : regex'.

`substr string position length'

Returns the substring of string beginning at position with length at most length. If either position or length is negative, zero, or non-numeric, returns the null string.

`index string charset'

Returns the first position in string where the first character in charset was found. If no character in charset is found in string, return 0.

`length string'

Returns the length of string.

`+ token'

Interpret token as a string, even if it is a keyword like match or an operator like /. This makes it possible to test expr length + "$x" or expr + "$x" : '.*/\(.\)' and have it do the right thing even if the value of $x happens to be (for example) / or index. This operator is a GNU extension. Portable shell scripts should use " $token" : ' \(.*\)' instead of + "$token".

To make expr interpret keywords as strings, you must use the quote operator.

16.4.2 Numeric expressions

expr supports the usual numeric operators, in order of increasing precedence. The string operators (previous section) have lower precedence, the connectives (next section) have higher.

`+ -'

Addition and subtraction. Both arguments are converted to numbers; an error occurs if this cannot be done.

`* / %'

Multiplication, division, remainder. Both arguments are converted to numbers; an error occurs if this cannot be done.

16.4.3 Relations for expr

expr supports the usual logical connectives and relations. These are higher precedence than either the string or numeric operators (previous sections). Here is the list, lowest-precedence operator first.

`|'

Returns its first argument if that is neither null nor 0, otherwise its second argument.

`&'

Return its first argument if neither argument is null or 0, otherwise 0.

`< <= = == != >= >'

Compare the arguments and return 1 if the relation is true, 0 otherwise. == is a synonym for =. expr first tries to convert both arguments to numbers and do a numeric comparison; if either conversion fails, it does a lexicographic comparison using the character collating sequence specified by the LC_COLLATE locale.

16.4.4 Examples of using expr

Here are a few examples, including quoting for shell metacharacters.

To add 1 to the shell variable foo, in Bourne-compatible shells:

foo=`expr $foo + 1`

To print the non-directory part of the file name stored in $fname, which need not contain a /.

expr $fname : '.*/\(.*\)' '|' $fname

An example showing that \+ is an operator:

expr aaa : 'a\+' => 3

expr abc : 'a\(.\)c' => b expr index abcdef cz => 3 expr index index a error--> expr: syntax error expr index quote index a => 0