# test

## PROLOG



           This manual page is part of the POSIX Programmer's Manual.  The
           Linux implementation of this interface may differ (consult the
           corresponding Linux manual page for details of Linux behavior), or
           the interface may not be implemented on Linux.
    


## NAME



           test — evaluate expression
    


## SYNOPSIS



           test **[**_expression_**]**
    
           [ **[**_expression_**]**]
    


## DESCRIPTION



           The _test_ utility shall evaluate the _expression_ and indicate the
           result of the evaluation by its exit status. An exit status of
           zero indicates that the expression evaluated as true and an exit
           status of 1 indicates that the expression evaluated as false.
    
           In the second form of the utility, where the utility name used is
           _[_ rather than _test_ , the application shall ensure that the closing
           square bracket is a separate argument. The _test_ and _[_ utilities
           may be implemented as a single linked utility which examines the
           basename of the zeroth command line argument to determine whether
           to behave as the _test_ or _[_ variant. Applications using the _exec_()
           family of functions to execute these utilities shall ensure that
           the argument passed in _arg0_ or _argv_[0] is **'['** when executing the _[_
           utility and has a basename of **"test"** when executing the _test_
           utility.
    


## OPTIONS



           The _test_ utility shall not recognize the **"--"** argument in the
           manner specified by Guideline 10 in the Base Definitions volume of
           POSIX.1‐2017, _Section 12.2_ , _Utility Syntax Guidelines_.
    
           No options shall be supported.
    


## OPERANDS



           The application shall ensure that all operators and elements of
           primaries are presented as separate arguments to the _test_ utility.
    
           The following primaries can be used to construct _expression_ :
    
           **-b** _pathname_
                     True if _pathname_ resolves to an existing directory entry
                     for a block special file.  False if _pathname_ cannot be
                     resolved, or if _pathname_ resolves to an existing
                     directory entry for a file that is not a block special
                     file.
    
           **-c** _pathname_
                     True if _pathname_ resolves to an existing directory entry
                     for a character special file.  False if _pathname_ cannot
                     be resolved, or if _pathname_ resolves to an existing
                     directory entry for a file that is not a character
                     special file.
    
           **-d** _pathname_
                     True if _pathname_ resolves to an existing directory entry
                     for a directory. False if _pathname_ cannot be resolved,
                     or if _pathname_ resolves to an existing directory entry
                     for a file that is not a directory.
    
           **-e** _pathname_
                     True if _pathname_ resolves to an existing directory
                     entry. False if _pathname_ cannot be resolved.
    
           **-f** _pathname_
                     True if _pathname_ resolves to an existing directory entry
                     for a regular file. False if _pathname_ cannot be
                     resolved, or if _pathname_ resolves to an existing
                     directory entry for a file that is not a regular file.
    
           **-g** _pathname_
                     True if _pathname_ resolves to an existing directory entry
                     for a file that has its set-group-ID flag set. False if
                     _pathname_ cannot be resolved, or if _pathname_ resolves to
                     an existing directory entry for a file that does not
                     have its set-group-ID flag set.
    
           **-h** _pathname_
                     True if _pathname_ resolves to an existing directory entry
                     for a symbolic link. False if _pathname_ cannot be
                     resolved, or if _pathname_ resolves to an existing
                     directory entry for a file that is not a symbolic link.
                     If the final component of _pathname_ is a symbolic link,
                     that symbolic link is not followed.
    
           **-L** _pathname_
                     True if _pathname_ resolves to an existing directory entry
                     for a symbolic link. False if _pathname_ cannot be
                     resolved, or if _pathname_ resolves to an existing
                     directory entry for a file that is not a symbolic link.
                     If the final component of _pathname_ is a symbolic link,
                     that symbolic link is not followed.
    
           **-n** _string_ True if the length of _string_ is non-zero; otherwise,
                     false.
    
           **-p** _pathname_
                     True if _pathname_ resolves to an existing directory entry
                     for a FIFO. False if _pathname_ cannot be resolved, or if
                     _pathname_ resolves to an existing directory entry for a
                     file that is not a FIFO.
    
           **-r** _pathname_
                     True if _pathname_ resolves to an existing directory entry
                     for a file for which permission to read from the file
                     will be granted, as defined in _Section 1.1.1.4_ , _File_
                     _Read_ , _Write_ , _and Creation_.  False if _pathname_ cannot be
                     resolved, or if _pathname_ resolves to an existing
                     directory entry for a file for which permission to read
                     from the file will not be granted.
    
           **-S** _pathname_
                     True if _pathname_ resolves to an existing directory entry
                     for a socket. False if _pathname_ cannot be resolved, or
                     if _pathname_ resolves to an existing directory entry for
                     a file that is not a socket.
    
           **-s** _pathname_
                     True if _pathname_ resolves to an existing directory entry
                     for a file that has a size greater than zero. False if
                     _pathname_ cannot be resolved, or if _pathname_ resolves to
                     an existing directory entry for a file that does not
                     have a size greater than zero.
    
           **-t** _file_descriptor_
                     True if file descriptor number _file_descriptor_ is open
                     and is associated with a terminal. False if
                     _file_descriptor_ is not a valid file descriptor number,
                     or if file descriptor number _file_descriptor_ is not
                     open, or if it is open but is not associated with a
                     terminal.
    
           **-u** _pathname_
                     True if _pathname_ resolves to an existing directory entry
                     for a file that has its set-user-ID flag set. False if
                     _pathname_ cannot be resolved, or if _pathname_ resolves to
                     an existing directory entry for a file that does not
                     have its set-user-ID flag set.
    
           **-w** _pathname_
                     True if _pathname_ resolves to an existing directory entry
                     for a file for which permission to write to the file
                     will be granted, as defined in _Section 1.1.1.4_ , _File_
                     _Read_ , _Write_ , _and Creation_.  False if _pathname_ cannot be
                     resolved, or if _pathname_ resolves to an existing
                     directory entry for a file for which permission to write
                     to the file will not be granted.
    
           **-x** _pathname_
                     True if _pathname_ resolves to an existing directory entry
                     for a file for which permission to execute the file (or
                     search it, if it is a directory) will be granted, as
                     defined in _Section 1.1.1.4_ , _File Read_ , _Write_ , _and_
                     _Creation_.  False if _pathname_ cannot be resolved, or if
                     _pathname_ resolves to an existing directory entry for a
                     file for which permission to execute (or search) the
                     file will not be granted.
    
           **-z** _string_ True if the length of string _string_ is zero; otherwise,
                     false.
    
           _string_    True if the string _string_ is not the null string;
                     otherwise, false.
    
           _s1_ **=**_s2_   True if the strings _s1_ and _s2_ are identical; otherwise,
                     false.
    
           _s1_ **!=**_s2_  True if the strings _s1_ and _s2_ are not identical;
                     otherwise, false.
    
           _n1_ **-eq** _n2_ True if the integers _n1_ and _n2_ are algebraically equal;
                     otherwise, false.
    
           _n1_ **-ne** _n2_ True if the integers _n1_ and _n2_ are not algebraically
                     equal; otherwise, false.
    
           _n1_ **-gt** _n2_ True if the integer _n1_ is algebraically greater than the
                     integer _n2_ ; otherwise, false.
    
           _n1_ **-ge** _n2_ True if the integer _n1_ is algebraically greater than or
                     equal to the integer _n2_ ; otherwise, false.
    
           _n1_ **-lt** _n2_ True if the integer _n1_ is algebraically less than the
                     integer _n2_ ; otherwise, false.
    
           _n1_ **-le** _n2_ True if the integer _n1_ is algebraically less than or
                     equal to the integer _n2_ ; otherwise, false.
    
           _expression1_ **-a** _expression2_
                     True if both _expression1_ and _expression2_ are true;
                     otherwise, false. The **-a** binary primary is left
                     associative. It has a higher precedence than **-o**.
    
           _expression1_ **-o** _expression2_
                     True if either _expression1_ or _expression2_ is true;
                     otherwise, false. The **-o** binary primary is left
                     associative.
    
           With the exception of the **-h** _pathname_ and **-L** _pathname_ primaries,
           if a _pathname_ argument is a symbolic link, _test_ shall evaluate the
           expression by resolving the symbolic link and using the file
           referenced by the link.
    
           These primaries can be combined with the following operators:
    
           **!**_expression_
                     True if _expression_ is false. False if _expression_ is
                     true.
    
           **(**_expression_ **)**
                     True if _expression_ is true. False if _expression_ is
                     false. The parentheses can be used to alter the normal
                     precedence and associativity.
    
           The primaries 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_.  Additional implementation-defined
           operators and _primary_operator_ s may be provided by
           implementations. They shall be of the form -_operator_ where the
           first character of _operator_ is not a digit.
    
           The algorithm for determining the precedence of the operators and
           the return value that shall be generated is based on the number of
           arguments presented to _test_.  (However, when using the **"[...]"**
           form, the <right-square-bracket> final argument shall not be
           counted in this algorithm.)
    
           In the following list, $1, $2, $3, and $4 represent the arguments
           presented to _test_ :
    
           0 arguments:
                       Exit false (1).
    
           1 argument: Exit true (0) if $1 is not null; otherwise, exit
                       false.
    
           2 arguments:
                        *  If $1 is **'!'** , exit true if $2 is null, false if $2
                           is not null.
    
                        *  If $1 is a unary primary, exit true if the unary
                           test is true, false if the unary test is false.
    
                        *  Otherwise, produce unspecified results.
    
           3 arguments:
                        *  If $2 is a binary primary, perform the binary test
                           of $1 and $3.
    
                        *  If $1 is **'!'** , negate the two-argument test of $2
                           and $3.
    
                        *  If $1 is **'('** and $3 is **')'** , perform the unary test
                           of $2.  On systems that do not support the XSI
                           option, the results are unspecified if $1 is **'('**
                           and $3 is **')'**.
    
                        *  Otherwise, produce unspecified results.
    
           4 arguments:
                        *  If $1 is **'!'** , negate the three-argument test of
                           $2, $3, and $4.
    
                        *  If $1 is **'('** and $4 is **')'** , perform the two-
                           argument test of $2 and $3.  On systems that do
                           not support the XSI option, the results are
                           unspecified if $1 is **'('** and $4 is **')'**.
    
                        *  Otherwise, the results are unspecified.
    
           >4 arguments:
                       The results are unspecified.
    
                       On XSI-conformant systems, combinations of primaries
                       and operators shall be evaluated using the precedence
                       and associativity rules described previously. In
                       addition, the string comparison binary primaries **'='**
                       and **"!="** shall have a higher precedence than any unary
                       primary.
    


## STDIN



           Not used.
    


## INPUT FILES



           None.
    


## ENVIRONMENT VARIABLES



           The following environment variables shall affect the execution of
           _test_ :
    
           _LANG_      Provide a default value for the internationalization
                     variables that are unset or null. (See the Base
                     Definitions volume of POSIX.1‐2017, _Section 8.2_ ,
                     _Internationalization Variables_ for the precedence of
                     internationalization variables used to determine the
                     values of locale categories.)
    
           _LC_ALL_    If set to a non-empty string value, override the values
                     of all the other internationalization variables.
    
           _LC_CTYPE_  Determine the locale for the interpretation of sequences
                     of bytes of text data as characters (for example,
                     single-byte as opposed to multi-byte characters in
                     arguments).
    
           _LC_MESSAGES_
                     Determine the locale that should be used to affect the
                     format and contents of diagnostic messages written to
                     standard error.
    
           _NLSPATH_   Determine the location of message catalogs for the
                     processing of _LC_MESSAGES_.
    


## ASYNCHRONOUS EVENTS



           Default.
    


## STDOUT



           Not used.
    


## STDERR



           The standard error shall be used only for diagnostic messages.
    


## OUTPUT FILES



           None.
    


## EXTENDED DESCRIPTION



           None.
    


## EXIT STATUS



           The following exit values shall be returned:
    
            0    _expression_ evaluated to true.
    
            1    _expression_ evaluated to false or _expression_ was missing.
    
           >1    An error occurred.
    


## CONSEQUENCES OF ERRORS



           Default.
    
           _The following sections are informative._
    


## APPLICATION USAGE



           The XSI extensions specifying the **-a** and **-o** binary primaries and
           the **'('** and **')'** operators have been marked obsolescent. (Many
           expressions using them are ambiguously defined by the grammar
           depending on the specific expressions being evaluated.) Scripts
           using these expressions should be converted to the forms given
           below. Even though many implementations will continue to support
           these obsolescent forms, scripts should be extremely careful when
           dealing with user-supplied input that could be confused with these
           and other primaries and operators. Unless the application
           developer knows all the cases that produce input to the script,
           invocations 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
           portability 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 note 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 even on XSI-conformant systems
           depending on the expressions specified by _expr_ 1, _expr_ 2, and _expr_ 3.
           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_ expression were used and $1
           expanded to **'!'** , **'('** , or a known unary primary. Better constructs
           are:
    
               test -n "$1"
               test -z "$1"
    
           respectively.
    
           Historical systems have also been unreliable given the common
           construct:
    
               test "$response" = "expected string"
    
           One of the following is a more reliable form:
    
               test "X$response" = "Xexpected string"
               test "expected string" = "$response"
    
           Note 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 XSI marked extensions, any
           of the three comparison forms is reliable, given any input.
           (However, note 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 greater than 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 shall
           cause a syntax error when the second **-d** 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 greater than 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"
    
           Note that none of the following examples are permitted by the
           syntax described:
    
               [-f file]
               [-f file ]
               [ -f file]
               [ -f file
               test -f file ]
    
           In the first two cases, if a utility named _[‐f_ exists, that
           utility would be invoked, and not _test_.  In the remaining cases,
           the brackets are mismatched, and the behavior is unspecified.
           However:
    
               test ! ]
    
           does have a defined meaning, and must exit with status 1.
           Similarly:
    
               test ]
    
           must exit with status 0.
    


## EXAMPLES



            1. Exit if there are not two or three arguments (two variations):
    
                   if [ $# -ne 2 ] && [ $# -ne 3 ]; then exit 1; fi
                   if [ $# -lt 2 ] || [ $# -gt 3 ]; then exit 1; fi
    
            2. Perform a _mkdir_ if a directory does not exist:
    
                   test ! -d tempdir && mkdir tempdir
    
            3. Wait for a file to become non-readable:
    
                   while test -r thefile
                   do
                       sleep 30
                   done
                   echo '"thefile" is no longer readable'
    
            4. Perform a command if the argument is one of three strings (two
               variations):
    
                   if [ "$1" = "pear" ] || [ "$1" = "grape" ] || [ "$1" = "apple" ]
                   then
                       _command_
                   fi
    
                   case "$1" in
                       pear|grape|apple) _command_ ;;
                   esac
    


## RATIONALE



           The KornShell-derived conditional command (double bracket **[[]]**)
           was removed from the shell command language description in an
           early proposal. Objections were raised that the real problem is
           misuse of the _test_ command (**[**), and putting it into the shell is
           the wrong way to fix the problem.  Instead, proper documentation
           and a new shell reserved word (**!**)  are sufficient.
    
           Tests that require multiple _test_ operations can be done at the
           shell level using individual invocations of the _test_ command and
           shell logicals, rather than using the error-prone **-o** flag of _test_.
    
           XSI-conformant systems support more than four arguments.
    
           XSI-conformant systems support the combining of primaries with the
           following constructs:
    
           _expression1_ **-a** _expression2_
                 True if both _expression1_ and _expression2_ are true.
    
           _expression1_ **-o** _expression2_
                 True if at least one of _expression1_ and _expression2_ are
                 true.
    
           **(**_expression_ **)**
                 True if _expression_ is true.
    
           In evaluating these more complex combined expressions, the
           following precedence rules are used:
    
            *  The unary primaries have higher precedence than the algebraic
               binary primaries.
    
            *  The unary primaries have lower precedence than the string
               binary primaries.
    
            *  The unary and binary primaries have higher precedence than the
               unary _string_ primary.
    
            *  The **!** operator has higher precedence than the **-a** operator,
               and the **-a** operator has higher precedence than the **-o**
               operator.
    
            *  The **-a** and **-o** operators are left associative.
    
            *  The parentheses can be used to alter the normal precedence and
               associativity.
    
           The BSD and System V versions of **-f** are not the same. The BSD
           definition was:
    
           **-f** _file_   True if _file_ exists and is not a directory.
    
           The SVID version (true if the file exists and is a regular file)
           was chosen for this volume of POSIX.1‐2017 because its use is
           consistent with the **-b** , **-c** , **-d** , and **-p** operands (_file_ exists and
           is a specific file type).
    
           The **-e** primary, possessing similar functionality to that provided
           by the C shell, was added because it provides the only way for a
           shell script to find out if a file exists without trying to open
           the file. Since implementations are allowed to add additional file
           types, a portable script cannot use:
    
               test -b foo -o -c foo -o -d foo -o -f foo -o -p foo
    
           to find out if **foo** is an existing file. On historical BSD systems,
           the existence of a file could be determined by:
    
               test -f foo -o -d foo
    
           but there was no easy way to determine that an existing file was a
           regular file. An early proposal used the KornShell **-a** primary
           (with the same meaning), but this was changed to **-e** because there
           were concerns about the high probability of humans confusing the
           **-a** primary with the **-a** binary operator.
    
           The following options were not included in this volume of
           POSIX.1‐2017, although they are provided by some implementations.
           These operands should not be used by new implementations for other
           purposes:
    
           **-k** _file_   True if _file_ exists and its sticky bit is set.
    
           **-C** _file_   True if _file_ is a contiguous file.
    
           **-V** _file_   True if _file_ is a version file.
    
           The following option was not included because it was undocumented
           in most implementations, has been removed from some
           implementations (including System V), and the functionality is
           provided by the shell (see _Section 2.6.2_ , _Parameter Expansion_.
    
           **-l** _string_ The length of the string _string_.
    
           The **-b** , **-c** , **-g** , **-p** , **-u** , and **-x** operands are derived from the SVID;
           historical BSD does not provide them. The **-k** operand is derived
           from System V; historical BSD does not provide it.
    
           On historical BSD systems, _test_ **-w** _directory_ always returned false
           because _test_ tried to open the directory for writing, which always
           fails.
    
           Some additional primaries newly invented or from the KornShell
           appeared in an early proposal as part of the conditional command
           (**[[]]**): _s1_ **> **_s2_ , _s1_ **< **_s2_ , _str_ **=**_pattern_ , _str_ **!=**_pattern_ , _f1_ **-nt**
           _f2_ , _f1_ **-ot** _f2_ , and _f1_ **-ef** _f2_.  They were not carried forward into
           the _test_ utility when the conditional command was removed from the
           shell because they have not been included in the _test_ utility
           built into historical implementations of the _sh_ utility.
    
           The **-t** _file_descriptor_ primary is shown with a mandatory argument
           because the grammar is ambiguous if it can be omitted. Historical
           implementations have allowed it to be omitted, providing a default
           of 1.
    
           It is noted that **'['** is not part of the portable filename
           character set; however, since it is required to be encoded by a
           single byte, and is part of the portable character set, the name
           of this utility forms a character string across all supported
           locales.
    


## FUTURE DIRECTIONS



           None.
    


* * *