test(C)

test -- test conditions

Syntax

test expr

[ expr ]

Description

The test command evaluates the expression expr, and if its value is true, returns a zero (true) exit status; otherwise, test returns a non-zero exit status if there are no arguments. The following primitives are used to construct expr:

-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.
-f file: True if file exists and is a regular file.
-g file: True if file exists and its set-group-ID bit is set.
-h file: True if file exists and is a symbolic link. With all other primitives (except -L file), the symbolic links are followed. This primitive is identical to -L.
-H file: True if file exists and is a semaphore.
-k file: True if file exists and its sticky bit is set.
-L file: True if file exists and is a symbolic link. With all other primitives (except -h file), the symbolic links are followed by default. This primitive is identical to -h.
-M file: True if file exists and is shared memory.
-n s1: True if the length of string s1 is non-zero.
-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.
-t [fildes]: True if the open file whose file descriptor number is fildes (1 by default) is associated with a terminal device.
-u file: True if file exists and its set-user-ID bit is set.
-w file: True if file exists and is writable. This indicates that the write flag is set on; the file will not be writable on read-only filesystems.
-x file: True if file exists and is executable. This indicates that the execute flag is set on; if file is a directory, it can be searched.
-z s1: True if the length of string s1 is zero.
n1 -eq n2: True if the integers n1 and n2 are algebraically equal.
n1 -ne n2: True if the integers n1 and n2 are not algebraically equal.
n1 -gt n2: True if the integer n1 is algebraically greater than the integer n2.
n1 -ge n2: True if the integer n1 is algebraically greater than or equal to the integer n2.
n1 -lt n2: True if the integer n1 is algebraically less than the integer n2.
n1 -le n2: True if the integer n1 is algebraically less than or equal to the integer n2.
s1: True if s1 is not the null string.
s1 = s2: True if strings s1 and s2 are identical.
s1 != s2: True if strings s1 and s2 are not identical.

These primaries may be combined with the following operators:

!: unary negation operator;
! expr is true if expr is false, and ! expr is false if expr is true.
-a: binary AND operator;
expr1 -a expr2 is true only if both expr1 and expr2 are true.
-o: binary OR operator (-a has higher precedence than -o);
expr1 -o expr2 is true if either expr1 or expr2 is true.
(expr): True if expr is true. The parentheses can be used to alter the normal precedence and associativity.

Notice that all the operators and flags are separate arguments to test. Notice also, that parentheses are meaningful to the shell and, therefore, must be escaped.

Exit values

test returns 0 if expr evaluates to true; it returns 1 if expr evaluates to false or expr is missing; a value greater than 1 means an error occurred.

Examples

In the following examples, the [ ] form of the test command is used, and the shell script may be used with either sh or ksh.

Test if a file does not exist. In this example, the file .profile is copied from a template file if it does not exist in the user's home directory:

   if  [  !  -f  $HOME/.profile  ]
   then
   	echo ".profile file does not exist - copy from elsewhere"
   	cp  /usr/elsewhere/.profile  $HOME/.profile
   fi

Test whether a file exists and has zero size. This could be used to see if an overnight tape backup reported any errors to a file. The AND -a and negation ! operators are both used in this example:

   FILE=/tmp/backup_err
   if  [  -f  $FILE  -a  !  -s  $FILE  ]
   then
   	echo "The backup produced no errors"
   fi

Note that the test would not work correctly if only the operator combination ! -s were used. This would return true if the file did not exist or had zero size.

Test whether a variable has been defined. This example uses the test in a while loop which exits when a value has been entered:

   while  [  -z  "$VAL"  ]
   do
   	echo  -n  "Input value: "
   	read  VAL
   done

Note that double quotes around $VAL are necessary for the test to work. If the variable VAL is not defined, the expression "$VAL" evaluates to an empty string. If the expression were used without quotes, it would evaluate to nothing at all, and test would report an error.

Test the numeric value of a variable. Here the value of VAL is checked to see if it lies in a particular range:

   if  [  $VAL  -lt  0  -o  $VAL  -gt  7  ]
   then
   	echo  -n  "Value must be in the range 0 to 7"
   fi

Test whether the previous command succeeded. This example tests the result of having tried to change directory to /tmp/mirage:

   DIR=/tmp/mirage
   cd $DIR
   if  [  $?  -ne  0  ]
   then
   	echo  -n  "Could not change directory to $DIR"
   fi

Limitations

In the form of the command that uses [ ] rather than the word test, each of the square brackets must be surrounded by blank space. If this is not done, the command will not be interpreted correctly.

A version of test is built into sh(C), ksh(C). For details, refer to the appropriate section.

Standards conformance

test is conformant with:

ISO/IEC DIS 99452:1992, Information technology Portable Operating System Interface (POSIX) Part 2: Shell and Utilities (IEEE Std 1003.21992);
AT&T SVID Issue 2;
X/Open CAE Specification, Commands and Utilities, Issue 4, 1992.