te
Copyright (c) 2009, Sun Microsystems, Inc. All Rights Reserved
Copyright 1992, X/Open Company Limited All Rights Reserved
Copyright 1989 AT&T
Portions Copyright (c) 1982-2007 AT&T Knowledge Ventures
Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at http://www.opengroup.org/bookstore/.
The Institute of Electrical and Electronics Engineers and The Open Group, have given us permission to reprint portions of their documentation. In the following statement, the phrase "this text" refers to portions of the system documentation. Portions of this text
are reprinted and reproduced in electronic form in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical
and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions 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.
This notice shall appear on any product containing this material.
The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.
See the License for the specific language governing permissions and limitations under the License. When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with
the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
test - evaluate condition(s)

/usr/bin/test [condition]

[ [condition] ]

test [condition]

[ [condition] ]

test [condition]

[ [condition] ]

test [condition]

[ [condition] ]

test [condition]

[ [condition] ]

The test utility evaluates the condition and indicates the result of the evaluation by its exit status. An exit status of zero indicates that the condition evaluated as true and an exit status of 1 indicates that the condition evaluated as false.

In the first form of the utility shown using the SYNOPSIS:

test [condition]

the square brackets denote that condition is an optional operand and are not to be entered on the command line.

In the second form of the utility shown using the SYNOPSIS:

[ [ condition ] ]

the first open square bracket, [, is the required utility name. condition is optional, as denoted by the inner pair of square brackets. The final close square bracket, ], is a required operand.

See largefile(5) for the description of the behavior of test when encountering files greater than or equal to 2 Gbyte (2^31 bytes).

The test and [ utilities evaluate the condition condition and, if its value is true, set exit status to 0. Otherwise, a non-zero (false) exit status is set. test and [ also set a non-zero exit status if there are no arguments. When permissions are tested, the effective user ID of the process is used.

All operators, flags, and brackets (brackets used as shown in the last SYNOPSIS line) must be separate arguments to these commands. Normally these arguments are separated by spaces.

The primaries listed below with two elements of the form:

-primary_operator primary_operand

are known as unary primaries. The primaries with three elements in either of the two forms:

primary_operand -primary_operator primary_operand
primary_operand primary_operator primary_operand

are known as binary primaries.

If any file operands except for -h and -L primaries refer to symbolic links, the symbolic link is expanded and the test is performed on the resulting file.

If you test a file you own (the -r -w or -x tests), but the permission tested does not have the owner bit set, a non-zero (false) exit status is returned even though the file can have the group or other bit set for that permission.

The = and != primaries have a higher precedence than the unary primaries. The = and != primaries always expect arguments; therefore, = and != cannot be used as an argument to the unary primaries.

The following primaries can be used to construct condition:

-a file

-b file

-c file

-d file

-e file

-f file

-g file

-G file

-h file

-k file

-L file

-n string

-o option

-O file

-p file

-r file

-s file

-S file

-t [file_descriptor]

-u file

-w file

-x file

-z string

file1 -nt file2

file1 -ot file2

file1 -ef file2

string

string1 = string2

string1 != string2

n1 -eq n2

n1 -ne n2

n1 -gt n2

n1 -ge n2

n1 -lt n2

n1 -le n2

condition1 -a condition2

condition1 -o condition2

These primaries can be combined with the following operators:

! condition

( condition )

The algorithm for determining the precedence of the operators and the return value that is generated is based on the number of arguments presented to test. (However, when using the [...] form, the right-bracket final argument is not counted in this algorithm.)

In the following list, $1, $2, $3 and $4 represent the arguments presented to test as a condition, condition1, or condition2.

0 arguments:

1 argument:

2 arguments:

3 arguments:

4 arguments:

Scripts should be careful when dealing with user-supplied input that could be confused with primaries and operators. Unless the application writer knows all the cases that produce input to the script, invocations like test "$1" -a "$2" should be written as test "$1" && test "$2" to avoid problems if a user supplied values such as $1 set to ! and $2 set to the null string. That is, in cases where maximal portability is of concern, replace test expr1 -a expr2 with test expr1 && test expr2, and replace test expr1 -o expr2 with test expr1 || test expr2. But notice that, in test, -a has higher precedence than -o, while && and || have equal precedence in the shell.

Parentheses or braces can be used in the shell command language to effect grouping.

Parentheses must be escaped when using sh. For example:

test \e( expr1 -a expr2 \e) -o expr3

This command is not always portable outside XSI-conformant systems. The following form can be used instead:

( test expr1 && test expr2 ) || test expr3

The two commands:

test "$1"
test ! "$1"

could not be used reliably on some historical systems. Unexpected results would occur if such a string condition were used and $1 expanded to !, (, or a known unary primary. Better constructs are, respectively,

test -n "$1"
test -z "$1"

Historical systems have also been unreliable given the common construct:

test "$response" = "expected string"

One of the following is a more reliable form:

test "X$response" = "Xexpected string"
test "expected string" = "$response"

The second form assumes that expected string could not be confused with any unary primary. If expected string starts with -, (, ! or even =, the first form should be used instead. Using the preceding rules without the marked extensions, any of the three comparison forms is reliable, given any input. (However, observe that the strings are quoted in all cases.)

Because the string comparison binary primaries, = and !=, have a higher precedence than any unary primary in the >4 argument case, unexpected results can occur if arguments are not properly prepared. For example, in

test -d $1 -o -d $2

If $1 evaluates to a possible directory name of =, the first three arguments are considered a string comparison, which causes a syntax error when the second -d is encountered. is encountered. One of the following forms prevents this; the second is preferred:

test \e( -d "$1" \e) -o \e( -d "$2" \e)
test -d "$1" || test -d "$2"

Also in the >4 argument case:

test "$1" = "bat" -a "$2" = "ball"

Syntax errors occur if $1 evaluates to ( or !. One of the following forms prevents this; the third is preferred:

test "X$1" = "Xbat" -a "X$2" = "Xball"
test "$1" = "bat" && test "$2" = "ball"
test "X$1" = "Xbat" && test "X$2" = "Xball"

In the if command examples, three conditions are tested, and if all three evaluate as true or successful, then their validities are written to the screen. The three tests are:

Example 1 Using /usr/bin/test

Perform a mkdir if a directory does not exist:

test ! -d tempdir && mkdir tempdir

Wait for a file to become non-readable:

while test -r thefile
do
 sleep 30
done
echo'"thefile" is no longer readable'

Perform a command if the argument is one of three strings (two variations), using the open bracket version [ of the test command:

if [ "$1" = "pear" ] || [ "$1" = "grape" ] || [ "$1" = "apple" ]
then
 command
fi
case "$1" in
 pear|grape|apple) command;;
esac

Example 2 Using /usr/bin/test for the -e option

If one really wants to use the -e option in sh, use /usr/bin/test, as in the following:

if [ ! -h $PKG_INSTALL_ROOT$rLink ] && /usr/bin/test -e
$PKG_INSTALL_ROOT/usr/bin/$rFile ; then
 ln -s $rFile $PKG_INSTALL_ROOT$rLink
fi

The two forms of the test built-in follow the Bourne shell's if example.

Example 3 Using the sh built-in

ZERO=0 ONE=1 TWO=2 ROOT=root

if [ $ONE -gt $ZERO ]

[ $TWO -eq 2 ]

grep $ROOT /etc/passwd >&1 > /dev/null # discard output

then

 echo "$ONE is greater than 0, $TWO equals 2, and $ROOT is" \e
 "a user-name in the password file"

else

 echo "At least one of the three test conditions is false" 
fi

Example 4 Using the test built-in

Examples of the test built-in:

test \(gagrep $ROOT /etc/passwd >&1 /dev/null\(ga # discard output 

echo $? # test for success
[ \(gagrep nosuchname /etc/passwd >&1 /dev/null\(ga ]

echo $? # test for failure

Example 5 Using the csh built-in

@ ZERO = 0; @ ONE = 1; @ TWO = 2; set ROOT = root
grep $ROOT /etc/passwd >&1 /dev/null # discard output 
 # $status must be tested for immediately following grep 
if ( "$status" == "0" && $ONE > $ZERO && $TWO == 2 ) then
 echo "$ONE is greater than 0, $TWO equals 2, and $ROOT is" \e
 "a user-name in the password file"
 endif

Example 6 Using the ksh/ksh93 built-in

ZERO=0 ONE=1 TWO=$((ONE+ONE)) ROOT=root 
if ((ONE > ZERO)) # arithmetical comparison
 [[ $TWO = 2 ]] # string comparison
 [ \(gagrep $ROOT /etc/passwd >&1 /dev/null\(ga ] # discard output 
then 
 echo "$ONE is greater than 0, $TWO equals 2, and $ROOT is" \e
 "a user-name in the password file"

else
 echo "At least one of the three test conditions is false"
fi

See environ(5) for descriptions of the following environment variables that affect the execution of test: LANG, LC_ALL, LC_CTYPE, LC_MESSAGES, and NLSPATH.

The following exit values are returned:

0

1

>1

See attributes(5) for descriptions of the following attributes:

ATTRIBUTE TYPE	ATTRIBUTE VALUE
Interface Stability	Committed
Standard	See standards(5).

ATTRIBUTE TYPE	ATTRIBUTE VALUE
Interface Stability	Uncommitted

csh(1), ksh(1), ksh93(1), sh(1), test(1B), attributes(5), environ(5), largefile(5), standards(5)

The not-a-directory alternative to the -f option is a transition aid for BSD applications and may not be supported in future releases.

Use arithmetic expressions such as

$(( x > 3.1 )) #

instead of

$ /usr/bin/test "$x" -gt 3.1 # )

when comparing two floating-point variables or a constant and a floating-point variable to prevent rounding errors (caused by the base16 to base10 transformation) to affect the result. Additionally the built-in arithmetic support in XPG4 sh, ksh and ksh93 is significantly faster because it does not require the explicit transformation to strings for each comparison.