unixdev.net


Switch to SpeakEasy.net DSL

The Modular Manual Browser

Home Page
Manual: (SunOS-5.10)
Page:
Section:
Apropos / Subsearch:
optional field

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
       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
       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.
                               Alternatively,  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 algebraical-
                               ly 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
       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"


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


       tab()    allbox;    cw(2.750000i)|     cw(2.750000i)     lw(2.750000i)|
       lw(2.750000i).    ATTRIBUTE   TYPEATTRIBUTE  VALUE  AvailabilitySUNWcsu
       Interface StabilityStandard


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)