Illustrated UNIX System V/BSD: Module 135 test

Module 135
test

DESCRIPTION

The internal test command is used to evaluate conditional expressions. The test command evaluates the expression and, if it is true, returns a 0 return code; if the expression is false, the return code is 1. The test command is primarily used to make a conditional decision in a shell script. The following features are provided:

* Return code used by shell constructs; if, until, and while.

* Evaluates conditional (true or false) expressions.

* Returns an exit status equal to 0 if condition is true.

* Returns an exit status greater than 0 if condition is false.

* Evaluates file permissions and types.

* Evaluates numerical expressions.

* Evaluates string expressions.

There are internal versions of test in the csh and ksh and an external version in /bin/test. This module explains the ksh version and the common BSD /bin/test version.

COMMAND FORMAT

Following is the general format of the test command.

     test expr
     [ expr ]

The brackets ([]) are an alternative to the test syntax. You must place blanks before and after the first bracket and before the second one. Thus the following two syntaxes are equivalent:

     if test -f file
     if [ -f file ]

EXPRESSIONS

The test command has primary expressions (operators) that perform one specific conditional check. These primary expressions can be combined using operators. The following three sections cover the primary expressions used to test files, strings, and numbers.

Testing on files

These primitives can be used to test the state, type, or permissions of a file. The file may be a constant or variable.

NOTE:
If a file does not exist or the condition is false, test returns an exist status of nonzero. If the condition is true, test returns an exit status of 0.

Expression	Description


-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.
-f file	True if file exists and is a regular file.
-g file	True if file exists and has the set-group-ID bit set.
-k file	True if file exists and has the sticky bit set.
-p file	True if file exists and is a pipe.
-r file@LIST2=	True if file exists and is readable.
-s file	True if file exists and has a size greater than 0 bytes.
-t [fds]	True if the open file defined by file descriptor "fds" is a tty(default fds=1).
-u file	True if file exists and has the set-user-ID bit set.
-w file	True if file exists and is writable.
-x file	True if file exists and is executable.

Korn Shell Extensions
-L file	True if file exists and is a symbolic link.
file1 -nt file2	True if file1 is newer than file2.
file1 -ot file2	True if file1 is older than file2.
file1 -ef file2	True if file1 has the same device and inode number as file2.

If file is of the form /dev/fd/n, where n is an integer, the test is applied to the open file whose descriptor number is n.

BSD (Berkeley)
Only the following file testing options exist in BSD versions.
-L file	True if file exists and is a soft link.
-d file	True if file exists and is a directory.
-f file	True if file exists and is a regular file.
-r file	True if file exists and is readable.
-s file	True if file exists and has a size greater than 0 bytes.
-t [fds]	True if the open file defined by file descriptor "fds" is a tty(default fds=1).
-w file	True if file exists and is writable.

NOTE:
It is advisable to enclose string variables within double quotes. This ensures that test will work even if the variable is unset or null.

Testing on strings

The following primitives can be used to test the condition of strings. The sX values may be a constant or a variable. The double quotes around the sX values are not necessary but are advisable.

Expression	Description


-z "s1"	True if length of string s1 is zero.
"s1" = "s2"	True if strings s1 and s2 are equal(match).
"s1" != "s2"	True if strings s1 and s2 are NOT equal.
"s1"	True if s1 exists; is not a null string.
The = and != operators have higher precedence than the -b through -z operators.

BSD (Berkeley)
BSD supports all of these options.

Testing on numbers

The following primitives can be used to test the condition of two numbers. The double quotes around the sX values are not necessary but are advisable.

Expression	Description


n1 -eq n2	True if n1 and n2 are equal.
n1 -ne n2	True if n1 and n2 are NOT equal.
n1 -gt n2	True if n1 is greater than n2.
n1 -ge n2	True if n1 is greater than or equal to n2.
n1 -lt n2	True if n1 is less than n2.
n1 -le n2	True if n1 is less than or equal to n2.

BSD (Berkeley)
BSD supports all of these options.

OPERATORS

The following operators may be placed between expressions, except for the parentheses, which are placed around expressions for grouping.

Expression	Description


! expr	Unary negation operator. Unary means it only negates one expression, the one immediately following it. To negate multiple expressions enclose them in parentheses. For example,
		`[ ! -w myfile ]`
	returns true if myfile does not exists or is not writable. While
		`[ ! $ -r myfile -a -w myfile $ ]`
	returns true if myfile does not exist or is not readable and writable.
expr -a expr@T2=Binary and operator. Binary means it operates on two expressions, the one before and the one after the -a. The result is true if both expressions are true. If one or both expressions are false, then the result of the test is false. For example,
		`[ -r myfile -a -s myfile ]`
	returns true if you can read myfile and it is not empty.
expr -o expr	Binary or operator. The result is true if one or both of the expressions are true. If both expressions are false, then the result of the test is false. For instance,
		`[ "$ANS" = "Y" -o "$ANS" = "X" ]`
	returns true if the value of $ANS equals Y or X.
( expr )	Expression grouping parentheses. You may need to group expressions when using operators to force the correct interpretation of the operators. The test command evaluates with the following precedence, from high to low:
		`(!), !, -a, -o`
	For example,
		`[ ! -r myfile -a -x myfile ]`
	returns true if myfile is not readable and is executable. Whereas,
		`[ ! $ -r myfile -a -x myfile $ ]`
	returns true if myfile is not readable, not writable, or both.

BSD (Berkeley)

BSD supports all of these operators.

FURTHER DISCUSSION

The test command is normally used in shell scripts to test expressions and return an exit status to the if, until, and while constructs.

When using variables in the test command you should always surround the variable with double quotes unless they are being compared as numbers. For instance, if you had the variable FILE, you would type

     if [ "${FILE}" = "myfile" ]

This syntax will prevent the test command from aborting if the variable is not set or has a NULL value.

DIAGNOSTICS AND BUGS

If you own a file and test for a condition of -r, -w, or -x, you may not receive the correct results. If the file permissions are not set in the owner field for the condition being tested, the result of the test will be false. In short, the test command looks at the permissions that relate to you using the file.

RELATED COMMANDS

Refer to the ksh command described in Module 71.

RETURN CODES

The test command returns a 0 if the expressions evaluated were true. If the expressions where false then a 1 is returned.

APPLICATIONS

You can use test in shell scripts to test for file permissions and to compare the values of variables. Normally, you use test in conjunction with the programming constructs of the shell. For example,

     cj> while [ -n "$*" ]
     do
      echo $1
      shift
     done

would test for the existence of parameters. When no more parameters existed the loop would exit because test returns a false (return code 1) value.

TYPICAL OPERATION

In this activity you use the test command to make sure a file is readable before you try to read it. Begin at the shell prompt.

1. Create the following shell script using an editor or by using the cat command. To use cat, type cat > mycat and press Return. Then type each line of text followed by a Return. Press Ctrl-D after you have finished typing all of the code.

  cj> cat > mycat
  if [ -r "$1" ]
  then
    cat $1
  else
    echo "You Do Not Have Read Permission for $1"
  fi
  ^D


C Shell
	`cj> cat > mycat` `#1/bin/csh test -r $1` `if ( $status == 0 ) then`
		`cat $1`
	`else`
		`echo "You Do Not Have Read Permission for $1"`
	`endif` `^D`

2. Now change the modes so you can execute your new mycat command by typing chmod 755 mycat and pressing Return.

3. To test your new shell script command, type mycat xyz and press Return. Notice the echo message should return. The script does not handle this correctly. It should test for the existence of the file, then check if it is readable.

4. Now try it with a filename that exists. Type mycat /etc/passwd and press Return. The password file should be displayed on your screen.

5. Turn to Module 141 to continue the learning sequence.

Table of Contents