Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
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] ]

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.	condi-
       tion 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 en-
       countering 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  ei-
       ther 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
       will  be	 returned even though the file may have	the group or other bit
       set for that permission.

       The = and != primaries have a higher precedence	than  the  unary  pri-
       maries.	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.  Al-
			       ternatively,   if   /usr/bin/sh	users  specify
			       /usr/ucb	before /usr/bin	in their PATH environ-
			       ment  variable,	then  test will	return true if
			       file exists and is (not-a-directory).  The  csh
			       test  and  [ built-ins always use this alterna-
			       tive 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	avail-
			       able 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. (Not	avail-
			       able in csh or sh.)

       -O file		       True if file exists and is owned	by the	effec-
			       tive user ID of this process. (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. (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  will
			       indicate	 only  that  the write flag is on. The
			       file will not be	writable on a  read-only  file
			       system even if this test	indicates true.

       -x file		       True  if	 file  exists  and is executable. True
			       will indicate 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.
			       (Not available in sh.)

       file1 -ot file2	       True  if	 file1 exists and is older than	file2.
			       (Not available in sh.)

       file1 -ef file2	       True if file1 and file2 exist and refer to  the
			       same file. (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 integers n1 and  n2	are  algebrai-
			       cally equal.

       n1 -ne n2	       True if the integers n1 and n2 are not algebra-
			       ically 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.

       condition1 -a condition2True 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 condition2True  if	 either	 condition1  or	 condition2 is
			       true. The -o binary primary  is	left  associa-
			       tive.

       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. Notice also that 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 will be generated is based on the number of arguments
       presented  to  test.  (However,	when  using the	[...] form, the	right-
       bracket final argument will not be counted in this algorithm.)

       In the following	list, $1, $2, $3 and $4	represent the  arguments  pre-
       sented 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,  invoca-
       tions  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	porta-
       bility 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 ef-
       fect 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 re-
       sults 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 con-
       struct:

       test "$response"	= "expected string"

       One of the following is a more reliable form:

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

       Notice that 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  ar-
       guments 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 will occur if $1 evaluates to ( or !. One	of the follow-
       ing 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	varia-
       tions), 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

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

       Example 2: 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 3: 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 4: 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 5: Using	the ksh	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

   Using -e option in sh
       Example 6: 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

ENVIRONMENT VARIABLES
       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.

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
       See attributes(5) for descriptions of the following attributes:

       +-----------------------------+-----------------------------+
       |      ATTRIBUTE	TYPE	     |	    ATTRIBUTE VALUE	   |
       +-----------------------------+-----------------------------+
       |Availability		     |SUNWcsu			   |
       +-----------------------------+-----------------------------+
       |Interface Stability	     |Standard			   |
       +-----------------------------+-----------------------------+

SEE ALSO
       csh(1),	ksh(1),	 sh(1),	 test(1B),  attributes(5),  environ(5),	large-
       file(5),	standards(5)

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.

SunOS 5.10			  23 Aug 2002			       test(1)

NAME | SYNOPSIS | DESCRIPTION | OPERANDS | USAGE | EXAMPLES | ENVIRONMENT VARIABLES | EXIT STATUS | ATTRIBUTES | SEE ALSO | NOTES

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=test&sektion=1&manpath=SunOS+5.10>

home | help