TEST man page on SmartOS

Man page or keyword search:  
man Server   16655 pages
apropos Keyword Search (all sections)
Output format
SmartOS logo
[printable version]

TEST(1)								       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.	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
       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  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 spe‐
				   cial 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−direc‐
				   tory).  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 num‐
				   ber is file_descriptor is open and is asso‐
				   ciated  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 algebrai‐
				   cally  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 alge‐
				   braically 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 inte‐
				   ger, floating point or floating-point  con‐
				   stant  (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 asso‐
				   ciative 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	 asso‐
				   ciative.

       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 pre‐
       sented 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 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
       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  con‐
       struct:

	 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 with‐
       out the marked extensions, any of the three comparison forms  is	 reli‐
       able, 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 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

       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 exam‐
       ple.

       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(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:

   /usr/bin/test, csh, ksh, sh
       ┌────────────────────┬───────────────────┐
       │  ATTRIBUTE TYPE    │  ATTRIBUTE VALUE	│
       ├────────────────────┼───────────────────┤
       │Interface Stability │ Committed		│
       ├────────────────────┼───────────────────┤
       │Standard	    │ See standards(5). │
       └────────────────────┴───────────────────┘

   ksh93
       ┌────────────────────┬─────────────────┐
       │  ATTRIBUTE TYPE    │ ATTRIBUTE VALUE │
       ├────────────────────┼─────────────────┤
       │Interface Stability │ Uncommitted     │
       └────────────────────┴─────────────────┘

SEE ALSO
       csh(1), ksh(1), ksh93(1), sh(1), test(1B),  attributes(5),  environ(5),
       largefile(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.

   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	float‐
       ing-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.

				 Aug 11, 2009			       TEST(1)
[top]

List of man pages available for SmartOS

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net