Unix‎ > ‎Solaris‎ > ‎Solaris man pages‎ > ‎1‎ > ‎

test


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. condition 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 permis-
     sions 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  ele-
     ments 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 will be returned  even  though  the
     file  may  have  the group or other bit set for that permis-
     sion.

     The = and != primaries have a  higher  precedence  than  the
     unary  primaries. The = and != primaries always expect argu-
     ments; 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 charac-
                             ter special file.



     -d file                 True if file exists and is a  direc-
                             tory.



     -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 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 available in sh.)



     -h file                 True if file exists and  is  a  sym-
                             bolic link.



     -k file                 True if  file  exists  and  has  its
                             sticky bit set.



     -L file                 True if file exists and  is  a  sym-
                             bolic link.


     -n string               True if  the  length  of  string  is
                             non-zero.



     -o option               True if option named option  is  on.
                             (Not available in csh or sh.)



     -O file                 True if file exists and is owned  by
                             the  effective  user ID of this pro-
                             cess. (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 descrip-
                             tor  number  is  file_descriptor  is
                             open and is associated with a termi-
                             nal.   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  execut-
                             able.  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 avail-
                             able 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
                             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  algebrai-
                             cally greater than the integer n2.



     n1 -ge n2               True if the integer n1 is  algebrai-
                             cally  greater  than or equal to the
                             integer n2.



     n1 -lt n2               True if the integer n1 is  algebrai-
                             cally less than the integer n2.



     n1 -le n2               True if the integer n1 is  algebrai-
                             cally  less  than  or  equal  to the
                             integer n2.



     condition1 -a condition2True if both condition1  and  condi-
                             tion2  are  true. The -a binary pri-
                             mary is  left  associative  and  has
                             higher precedence than the -o binary
                             primary.



     condition1 -o condition2True if either condition1 or  condi-
                             tion2 is true. The -o binary primary
                             is left associative.




     These primaries can be combined with  the  following  opera-
     tors:

     ! 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  opera-
     tors 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 argu-
     ments  presented to test as a condition, condition1, or con-
     dition2.

     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  unspeci-
                          fied.




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  pro-
     duce input to the script, invocations like test "$1" -a "$2"
     should be written as test "$1" && test "$2" to  avoid  prob-
     lems  if  a  user supplied values such as $1 set to ! and $2
     set to the null string. That is, in cases where maximal por-
     tability  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. Unex-
     pected  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  com-
     mon construct:

     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  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 will 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  variations),  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 example.

     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 miss-
              ing.



     >1       An error occurred.



ATTRIBUTES
     See attributes(5) for descriptions of the  following  attri-
     butes:

     ____________________________________________________________
    |       ATTRIBUTE TYPE        |       ATTRIBUTE VALUE       |
    |_____________________________|_____________________________|
    | Availability                | SUNWcsu                     |
    |_____________________________|_____________________________|
    | Interface Stability         | Standard                    |
    |_____________________________|_____________________________|


SEE ALSO
     csh(1), ksh(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  tran-
     sition  aid for BSD applications and may not be supported in
     future releases.










Man pages from Solaris 10 Update 8. See docs.sun.com and www.oracle.com for further documentation and Solaris information.
Comments