test(1) test(1)
NAME
test, [ - test conditions
SYNOPSIS
test expression
[ expression ]
[[ expression ]]
DESCRIPTION
The utility test or the shell built-in [ is used to check whether
specific conditions are satisfied. Such conditions may be:
- file attributes,
- characteristics and comparisons of strings, and
- algebraic comparisons of integers.
Conditions can be negated and several conditions may be combined with
one another.
test returns the following results:
- Exit status 0 (true) if the condition is satisfied.
- Exit status 1 (false) if the condition is not satisfied or was not
fully defined. A false exit status is also returned if you do not
specify a condition.
Depending on the exit status, you can execute various commands, ter-
minate loops, etc.
Along with the /usr/bin/test command, there are also built-in test
commands in the shell.
- The following alternative format exists for the built-in test com-
mand in the Bourne shell sh. It has the same effect.
[ expression ]
The square brackets must be specified, as must the blank, before or
after expression. The shell executes the built-in sh command test
in this case as well.
- The following alternative format exists for the built-in test com-
mand in the Korn shell ksh. It has the same effect.
[ expression ] or [[ expression ]]
Page 1 Reliant UNIX 5.44 Printed 11/98
test(1) test(1)
The square brackets must be specified, as must the blank, before or
after expression. There are additional options for expression in
the Korn shell [see ksh(1), CONDITIONAL EXPRESSIONS].
OPERANDS
expression
One or more primary expressions which may be combined (see Com-
bining conditions).
test checks the following conditions:
File attributes
-r file
True if file exists and you have read permission.
-w file
True if file exists and you have write permission.
-x file
True if file exists and you have execute permission.
-f file
True if file exists and is a regular file.
-d file
True if file exists and is a directory.
-h file
True if file exists and is a symbolic link. Normally symbolic
links are followed by all other conditions.
-c file
True if file exists and is a character special file.
-b file
True if file exists and is a block special file.
-p file
True if file exists and is a named pipe (FIFO).
-u file
True if file exists and its set-user-id bit is set.
-g file
True if file exists and its set-group-id bit is set.
-k file
True if file exists and its sticky bit is set.
-s file
True if file exists and is not empty.
Page 2 Reliant UNIX 5.44 Printed 11/98
test(1) test(1)
-t filedescr
True if the filedescr is associated with a terminal.
filedescr
The following may be entered for filedescr:
0 for standard input
1 for standard output
2 for standard error.
file Name of the file or directory whose attributes are to be tested.
Relative or absolute path names may also be specified.
If you use shell metacharacters in the file names, test only
checks the first file that matches this name.
If you specify the null string for file, i.e. a pair of single
quotes '' or double quotes "", test interprets file as the name
of your current directory.
If you do not specify file, test issues an error message and ter-
minates with exit status 1.
A shell parameter may also be specified for file. This parameter
should always be enclosed in double quotes "...". If the corre-
sponding shell variable has not been defined, the null string
will be passed as an argument to test. The quotes thus guarantee
that test is always supplied an argument during parameter substi-
tution.
Characteristics and comparisons of strings
Any arbitrary sequence of characters may be specified as a string.
Blanks and tabs included in the string must be escaped. If the string
is to be protected from interpretation by the shell, the relevant
metacharacters can be escaped by preceding them with a backslash \ or
by enclosing the entire string within single or double quotes.
The null string can be specified by a pair of consecutive double
quotes or single quotes. If you do not specify a string, test issues
an error message and terminates with exit status 1.
A shell parameter may also be specified as a string. This parameter
should always be enclosed in double quotes. If the corresponding shell
variable has not been defined, the null string will be passed as an
argument to test. The double quotes thus guarantee that test is always
supplied an argument during parameter substitution.
Page 3 Reliant UNIX 5.44 Printed 11/98
test(1) test(1)
[-n] string
True if the specified string is not the null string, i.e. has a
non-zero length.
This option allows you to test whether there is a value assigned
to a shell variable. The corresponding shell parameter must be
enclosed within double quotes.
-n not specified:
The meaning is the same as above, but the condition is easier to
read if -n is specified.
-z string
True if the specified string is the null string, i.e. has a
length of zero.
This enables you to test whether there is no value assigned to a
shell variable. The corresponding shell parameter must be
enclosed within double quotes.
string1 = string2
True if the two strings are identical. The blanks before and
after the equals sign are mandatory, since test expects this
character as an independent argument. If you are comparing shell
parameters, they should be enclosed within double quotes.
string1 != string2
True if the two specified strings are not identical. The blanks
surrounding the != (not equal to) sign are required, since test
expects this character as an independent argument. If shell
parameters are being compared, they must be quoted.
string
True if string is not the null string.
Algebraic comparison of integers
Integers can either be specified directly or as values of shell vari-
ables. There is no limit to the size of integer values you can
specify, nor to the size of values you can define for a shell vari-
able.
If you specify a shell parameter as a number, you should always
enclose it within double quotes "...". This ensures that test receives
the null string as an argument if the corresponding shell variable has
not been defined. Quoting thus guarantees that an argument will be
supplied to test when parameter substitution is performed.
Page 4 Reliant UNIX 5.44 Printed 11/98
test(1) test(1)
int1 op int2
The two integers int1 and int2 are algebraically compared by test
on the basis of the operator specified in op.
test expects operators as independent arguments; they must there-
fore be given between two blanks.
op can be any of the following:
-eq True if the two integers are algebraically equal.
-ne True if the two integers are algebraically not equal.
-ge True if int1 is algebraically greater than or equal to int2.
-gt True if int1 is algebraically greater than int2.
-le True if int1 is algebraically less than or equal to int2.
-lt True if int1 is algebraically less than int2.
Negating conditions
! condition
True if the specified condition is not satisfied. The exclamation
mark must be followed by a blank.
Example:
$ ! -r file
test returns an exit status of 0 (i.e. true) if you are not per-
mitted to read the specified file.
Combining conditions
Primary conditions can be linked with one another to form a compound
expression. The condition itself can also be negated.
Since the corresponding relational operators are expected as indepen-
dent arguments by test, they must be enclosed by one blank on either
side.
The find command searches directories for files that satisfy given
conditions. Conditions for test are combined in a similar way.
The following operators can be used to combine conditions:
condition -a condition
Logical AND operator, i.e true if all conditions combined in this
way are satisfied. Each -a operator must be preceded and followed
by a blank.
Page 5 Reliant UNIX 5.44 Printed 11/98
test(1) test(1)
condition -o condition
Logical OR operator, i.e true if at least one of the conditions
is satisfied. Each -o operator must be preceded and followed by a
blank.
\( compexpr \)
compexpr represents a compound expression comprising two or more
arbitrarily grouped conditions. The operator that precedes condi-
tions grouped within parentheses applies to the whole compound
expression (i.e. all conditions) and not just to the condition
that immediately follows it.
As the shell has its own interpretation of parentheses, they
should be escaped with a backslash when used within test. Each
operator and expression in the compound expression compexpr must
be separated from one another by blanks.
Example:
$ ! \( -r file -o -w file \)
|
OR
The expression within parentheses is true if you have read or
write permission for the specified file. The negation operator
(!) negates the whole expression. Thus, if you have neither read
nor write permission for the specified file, test will return an
exit status of zero (true).
Precedence of operators
The order of precedence for operators used with test is as follows:
Parentheses over negation over AND over OR.
The conditions within parentheses in the preceding example are thus
evaluated first and then negated.
EXIT STATUS
0 If the specified expression is true
1 If the specified condition is false, a condition is not fully
specified, or no condition has been given.
>1 Error
ERROR MESSAGES
test: argument expected
This error message is issued if you have failed to specify a condition
fully, i.e. if a file, string, or number is missing in the specifica-
tion.
Page 6 Reliant UNIX 5.44 Printed 11/98
test(1) test(1)
Shell parameters must therefore always be enclosed within double
quotes. Otherwise, an argument will be missing whenever the corre-
sponding shell variable is undefined.
EXAMPLES
Example 1:
The following shell script tests whether the specified positional
parameter is the name of a file or of a directory.
if test -f "$1" # or: if [ -f "$1" ]
then
echo $1 is a file
elif test -d "$1" # or: elif [ -d "$1" ]
then
echo $1 is a directory
fi
Since the $1 positional parameter has been quoted, test substitutes
the current directory for it if you call the shell script without
further arguments.
If the quotes were omitted in this case, test would terminate with an
error message.
Example 2:
The following script makes use of the operator -gt to test whether the
first file specified in the command line, i.e. $1, contains more lines
than the one specified after it ($2):
if [ `wc -l "$1"` -gt `wc -l "$2"` ]
then echo $1 contains more lines than $2
fi
The wc -l command counts and outputs the number of lines in each of
the two files. The shell substitutes the specification in the back-
quotes for the appropriate number of lines.
Page 7 Reliant UNIX 5.44 Printed 11/98
test(1) test(1)
Example 3:
A test is to be performed to check whether a value has been assigned
to the shell variable TAPE. This can be done in various ways:
(a) if [ ! -z "$TAPE" ]
then echo a value is assigned to the TAPE variable
else ....
fi
(b) if [ -n "$TAPE" ]
then echo a value is assigned to the TAPE
else ....
fi
The -n is optional and may be dropped.
The shell parameter $TAPE is enclosed within double quotes to prevent
test from issuing an error message in case no value has been assigned
to the corresponding variable.
NOTES
test exists both as an external command (/usr/bin/test) and as a
built-in shell command, both in the Korn shell ksh(1) as well as in
the Bourne shell sh(1). The shell generates a new process to execute
/usr/bin/test.
Some differences in behavior may occur when using test, depending on
which shell is being used. The possible differences are not described
specifically.
SEE ALSO
find(1), ksh(1), sh(1).
Page 8 Reliant UNIX 5.44 Printed 11/98