Tribblix: manual page: test.1

TEST(1) User Commands TEST(1)

NAME

test - evaluate condition(s)

SYNOPSIS

/usr/bin/test [condition]

[ [condition] ]

sh
test [condition]

[ [condition] ]

csh
test [condition]

[ [condition] ]

ksh
test [condition]

[ [condition] ]

ksh93
test [condition]

[ [condition] ]

DESCRIPTION

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(7) 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.

OPERANDS

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
True if file exists. (Not available in
sh.)

-b file
True if file exists and is a block
special file.

-c file
True if file exists and is a character
special file.

-d file
True if file exists and is a directory.

-e file
True if file exists. (Not available in
sh.)

-f file
True if file exists and is a regular
file. Alternatively, if /usr/bin/sh users
specify /usr/ucb before /usr/bin in their
PATH environment variable, then test
returns true if file exists and is
(not-a-directory). The csh test and [
built-ins always use this alternative
behavior.

-g file
True if file exists and its set group ID
flag is set.

-G file
True if file exists and its group matches
the effective group ID of this process.
(Not available in sh.)

-h file
True if file exists and is a symbolic
link.

-k file
True if file exists and has its sticky
bit set.

-L file
True if file exists and is a symbolic
link.

-n string
True if the length of string is non-zero.

-o option
True if option named option is on. This
option is not available in csh or sh.

-O file
True if file exists and is owned by the
effective user ID of this process. This
option is not available in sh.

-p file
True if file is a named pipe (FIFO).

-r file
True if file exists and is readable.

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

-S file
True if file exists and is a socket. This
option is not available in sh.

-t [file_descriptor]
True if the file whose file descriptor
number is file_descriptor is open and is
associated with a terminal. If
file_descriptor is not specified, 1 is
used as a default value.

-u file
True if file exists and its set-user-ID
flag is set.

-w file
True if file exists and is writable. True
indicates only that the write flag is on.
The file is not writable on a read-only
file system even if this test indicates
true.

-x file
True if file exists and is executable.
True indicates only that the execute flag
is on. If file is a directory, true
indicates that file can be searched.

-z string
True if the length of string string is
zero.

file1 -nt file2
True if file1 exists and is newer than
file2. This option is not available in
sh.

file1 -ot file2
True if file1 exists and is older than
file2. This option is not available in
sh.

file1 -ef file2
True if file1 and file2 exist and refer
to the same file. This option is not
available in sh.

string
True if the string string is not the null
string.

string1 = string2
True if the strings string1 and string2
are identical.

string1 != string2
True if the strings string1 and string2
are not identical.

n1 -eq n2
True if the numbers n1 and n2 are
algebraically equal. A number may be
integer, floating point or floating-point
constant (such as [+/-]Inf, [+/-]NaN) in
any format specified by C99/XPG6/SUS.

n1 -ne n2
True if the numbers n1 and n2 are not
algebraically equal. A number may be
integer, floating point or floating-point
constant (such as [+/-]Inf, [+/-]NaN) in
any format specified by C99/XPG6/SUS.

n1 -gt n2
True if the number n1 is algebraically
greater than the number n2. A number may
be integer, floating point or floating-
point constant (such as [+/-]Inf,
[+/-]NaN) in any format specified by
C99/XPG6/SUS.

n1 -ge n2
True if the number n1 is algebraically
greater than or equal to the number n2. A
number may be integer, floating point or
floating-point constant (such as
[+/-]Inf, [+/-]NaN) in any format
specified by C99/XPG6/SUS.

n1 -lt n2
True if the number n1 is algebraically
less than the number n2. A number may be
integer, floating point or floating-point
constant (such as [+/-]Inf, [+/-]NaN) in
any format specified by C99/XPG6/SUS.

n1 -le n2
True if the number n1 is algebraically
less than or equal to the number n2. A
number may be integer, floating point or
floating-point constant (such as
[+/-]Inf, [+/-]NaN) in any format
specified by C99/XPG6/SUS.

condition1 -a condition2
True if both condition1 and condition2
are true. The -a binary primary is left
associative and has higher precedence
than the -o binary primary.

condition1 -o condition2
True if either condition1 or condition2
is true. The -o binary primary is left
associative.

These primaries can be combined with the following operators:

! condition
True if condition is false.

( condition )
True if condition is true. The parentheses ( ) can
be used to alter the normal precedence and
associativity. The parentheses are meaningful to the
shell and, therefore, must be quoted.

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:
Exit false (1).

1 argument:
Exit true (0) if $1 is not null. Otherwise, exit
false.

2 arguments:

o If $1 is !, exit true if $2 is null, false
if $2 is not null.

o If $1 is a unary primary, exit true if the
unary test is true, false if the unary
test is false.

o Otherwise, produce unspecified results.

3 arguments:

o If $2 is a binary primary, perform the
binary test of $1 and $3.

o If $1 is !, negate the two-argument test
of $2 and $3.

o Otherwise, produce unspecified results.

4 arguments:

o If $1 is !, negate the three-argument test
of $2, $3, and $4.

o Otherwise, the results are unspecified.

USAGE

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 $ expr1 -a expr2 $ -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 $ -d "$1" $ -o $ -d "$2" $
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"

EXAMPLES

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:

o if a variable set to 1 is greater than 0,

o if a variable set to 2 is equal to 2, and

o if the word root is included in the text file /etc/passwd.

/usr/bin/test

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 test built-in
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" \
"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 `grep $ROOT /etc/passwd >&1 /dev/null` # discard output

echo $? # test for success
[ `grep nosuchname /etc/passwd >&1 /dev/null` ]

echo $? # test for failure

csh

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" \
"a user-name in the password file"
endif

ksh

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
[ `grep $ROOT /etc/passwd >&1 /dev/null` ] # discard output
then
echo "$ONE is greater than 0, $TWO equals 2, and $ROOT is" \
"a user-name in the password file"

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

ENVIRONMENT VARIABLES

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

EXIT STATUS

The following exit values are returned:

0
condition evaluated to true.

1
condition evaluated to false or condition was missing.

>1
An error occurred.

ATTRIBUTES

NOTES

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

XPG4 sh, ksh, ksh93
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.

August 11, 2009 TEST(1)