test(C)                       06 January 1993                        test(C)


 Name

    test - test conditions

 Syntax

    test expr

    [ expr ]

 Description

    The test command evaluates the expression expr, and if its value is true,
    returns a zero (true) exit status; otherwise, test returns a non-zero
    exit status if there are no arguments. The following primitives are used
    to construct expr:

    -r file   True if file exists and is readable.

    -w file   True if file exists and is writable.

    -x file   True if file exists and is executable.

    -f file   True if file exists and is a regular file.

    -d file   True if file exists and is a directory.

    -h file   True if file exists and is a symbolic link.  With all other
              primitives (except -L file), the symbolic links are followed.
              This primitive is identical to -L.

    -c file   True if file exists and is a character special file.

    -b file   True if file exists and is a block special file.

    -u file   True if file exists and its set-user-ID bit is set.

    -g file   True if file exists and its set-group-ID bit is set.

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

    -s file   True if file exists and has a size greater than zero.

    -t [fildes]
              True if the open file whose file descriptor number is fildes (1
              by default) is associated with a terminal device.

    -z s1     True if the length of string s1 is zero.

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

    -L file   True if file exists and is a symbolic link.  With all other
              primitives (except -h file), the symbolic links are followed by
              default. This primitive is identical to -h.

    s1=s2     True if strings s1 and s2 are identical.

    s1!=s2    True if strings s1 and s2 are not identical.

    s1        True if s1 is not the null string.

    n1 -eq n2 True if the integers n1 and n2 are algebraically equal.  Any of
              the comparisons -ne, -gt, -ge, -lt, and -le may be used in
              place of -eq.

    These primaries may be combined with the following operators:

    !         Unary negation operator

    -a        Binary AND operator

    -o        Binary OR operator  (-a has higher precedence than -o)

    (expr)    Parentheses for grouping

    Notice that all the operators and flags are separate arguments to test.
    Notice also, that parentheses are meaningful to the shell and, therefore,
    must be escaped.

 Notes

    In the form of the command that uses [ ] rather than the word test, each
    of the square brackets must be surrounded by blank space. If this is not
    done, the command will not be interpreted correctly.

    A version of test is built into sh(C) and ksh(C).  For details, refer to
    the appropriate section.

 Examples

    In the following examples, the [ ] form of the test command is used, and
    the shell script may be used with either sh or ksh.

    Test if a file does not exist. In this example, the file .profile is
    copied from a template file if it does not exist in the user's home
    directory:

       if  [  !  -f  $HOME/.profile  ]
       then
               echo ".profile file does not exist - copy from elsewhere"
               cp  /usr/elsewhere/.profile  $HOME/.profile
       fi

    Test whether a file exists and has zero size. This could be used to see
    if an overnight tape backup reported any errors to a file. The AND -a and
    negation ! operators are both used in this example:

       FILE=/tmp/backup_err
       if  [  -f  $FILE  -a  !  -s  $FILE  ]
       then
               echo "The backup produced no errors"
       fi

    Note that the test would not work correctly if only the operator combina-
    tion ! -s were used. This would return true if the file did not exist or
    had zero size.

    Test whether a variable has been defined. This example uses the test in a
    while loop which exits when a value has been entered:

       while  [  -z  "$VAL"  ]
       do
               echo  -n  "Input value: "
               read  VAL
       done

    Note that double quotes around $VAL are necessary for the test to work.
    If the variable VAL is not defined, the expression "$VAL" evaluates to an
    empty string. If the expression were used without quotes, it would evalu-
    ate to nothing at all, and test would report an error.

    Test the numeric value of a variable. Here the value of VAL is checked to
    see if it lies in a particular range:

       if  [  $VAL  -lt  0  -o  $VAL  -gt  7  ]
       then
               echo  -n  "Value must be in the range 0 to 7"
       fi

    Test whether the previous command succeeded. This example tests the
    result of having tried to change directory to /tmp/mirage:

       DIR=/tmp/mirage
       cd $DIR
       if  [  $?  -ne  0  ]
       then
               echo  -n  "Could not change directory to $DIR"
       fi

 See also

    find(C) and sh(C).

 Standards conformance

    test is conformant with:

    AT&T SVID Issue 2;
    and X/Open Portability Guide, Issue 3, 1989.