test.1 (8311B)
- .\" SPDX-License-Identifier: BSD-3-Clause
- .\"-
- .\" Copyright (c) 1991, 1993
- .\" The Regents of the University of California. All rights reserved.
- .\"
- .\" This code is derived from software contributed to Berkeley by
- .\" the Institute of Electrical and Electronics Engineers, Inc.
- .\"
- .\" Redistribution and use in source and binary forms, with or without
- .\" modification, are permitted provided that the following conditions
- .\" are met:
- .\" 1. Redistributions of source code must retain the above copyright
- .\" notice, this list of conditions and the following disclaimer.
- .\" 2. Redistributions in binary form must reproduce the above copyright
- .\" notice, this list of conditions and the following disclaimer in the
- .\" documentation and/or other materials provided with the distribution.
- .\" 3. Neither the name of the University nor the names of its contributors
- .\" may be used to endorse or promote products derived from this software
- .\" without specific prior written permission.
- .\"
- .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
- .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
- .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
- .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
- .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
- .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
- .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
- .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
- .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
- .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
- .\" SUCH DAMAGE.
- .\"
- .Dd October 5, 2016
- .Dt TEST 1
- .Os
- .Sh NAME
- .Nm test ,
- .Nm \&[
- .Nd condition evaluation utility
- .Sh SYNOPSIS
- .Nm
- .Ar expression
- .Nm \&[
- .Ar expression Cm \&]
- .Sh DESCRIPTION
- The
- .Nm
- utility evaluates the expression and, if it evaluates
- to true, returns a zero (true) exit status; otherwise
- it returns 1 (false).
- If there is no expression,
- .Nm
- also
- returns 1 (false).
- .Pp
- All operators and flags are separate arguments to the
- .Nm
- utility.
- .Pp
- When checking
- .Ar file ,
- one should consider TOCTOU race-conditions.
- Avoiding the issue altogether with directly using
- .Ar file
- instead is strongly recommended.
- .Pp
- The following primaries are used to construct expression:
- .Bl -tag -width Ar
- .It Fl b Ar file
- True if
- .Ar file
- exists and is a block special
- file.
- .It Fl c Ar file
- True if
- .Ar file
- exists and is a character
- special file.
- .It Fl d Ar file
- True if
- .Ar file
- exists and is a directory.
- .It Fl e Ar file
- True if
- .Ar file
- exists (regardless of type).
- .It Ar file1 Fl ef Ar file2
- True if
- .Ar file1
- and
- .Ar file2
- exist and refer to the same file.
- .It Fl f Ar file
- True if
- .Ar file
- exists and is a regular file.
- .It Fl g Ar file
- True if
- .Ar file
- exists and its set group ID flag
- is set.
- .It Fl h Ar file
- True if
- .Ar file
- exists and is a symbolic link.
- This operator is retained for compatibility with previous versions of
- this program.
- Do not rely on its existence; use
- .Fl L
- instead.
- .It Fl L Ar file
- True if
- .Ar file
- exists and is a symbolic link.
- .It Fl k Ar file
- True if
- .Ar file
- exists and its sticky bit is set.
- .It Fl n Ar string
- True if the length of
- .Ar string
- is nonzero.
- .It Ar file1 Fl nt Ar file2
- True if
- .Ar file1
- exists and is newer than
- .Ar file2 .
- .It Ar file1 Fl ot Ar file2
- True if
- .Ar file1
- exists and is older than
- .Ar file2 .
- .It Fl p Ar file
- True if
- .Ar file
- is a named pipe
- .Pq Tn FIFO .
- .It Fl r Ar file
- True if
- .Ar file
- exists and is readable.
- .It Fl S Ar file
- True if
- .Ar file
- exists and is a socket.
- .It Fl s Ar file
- True if
- .Ar file
- exists and has a size greater
- than zero.
- .It Fl t Ar file_descriptor
- True if the file whose file descriptor number
- is
- .Ar file_descriptor
- is open and is associated with a terminal.
- .It Fl u Ar file
- True if
- .Ar file
- exists and its set user ID flag
- is set.
- .It Fl w Ar file
- True if
- .Ar 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.
- .It Fl x Ar file
- True if
- .Ar file
- exists and is executable.
- True
- indicates only that the execute flag is on.
- If
- .Ar file
- is a directory, true indicates that
- .Ar file
- can be searched.
- .It Fl z Ar string
- True if the length of
- .Ar string
- is zero.
- .It Fl O Ar file
- True if
- .Ar file
- exists and its owner matches the effective user id of this process.
- .It Fl G Ar file
- True if
- .Ar file
- exists and its group matches the effective group id of this process.
- .It Ar string
- True if
- .Ar string
- is not the null
- string.
- .It Ar s1 Cm = Ar s2
- True if the strings
- .Ar s1
- and
- .Ar s2
- are identical.
- .It Ar s1 Cm != Ar s2
- True if the strings
- .Ar s1
- and
- .Ar s2
- are not identical.
- .It Ar s1 Cm < Ar s2
- True if string
- .Ar s1
- comes before
- .Ar s2
- based on the binary value of their characters.
- .It Ar s1 Cm > Ar s2
- True if string
- .Ar s1
- comes after
- .Ar s2
- based on the binary value of their characters.
- .It Ar n1 Fl eq Ar n2
- True if the integers
- .Ar n1
- and
- .Ar n2
- are algebraically
- equal.
- .It Ar n1 Fl ne Ar n2
- True if the integers
- .Ar n1
- and
- .Ar n2
- are not
- algebraically equal.
- .It Ar n1 Fl gt Ar n2
- True if the integer
- .Ar n1
- is algebraically
- greater than the integer
- .Ar n2 .
- .It Ar n1 Fl ge Ar n2
- True if the integer
- .Ar n1
- is algebraically
- greater than or equal to the integer
- .Ar n2 .
- .It Ar n1 Fl lt Ar n2
- True if the integer
- .Ar n1
- is algebraically less
- than the integer
- .Ar n2 .
- .It Ar n1 Fl le Ar n2
- True if the integer
- .Ar n1
- is algebraically less
- than or equal to the integer
- .Ar n2 .
- .El
- .Pp
- If
- .Ar file
- is a symbolic link,
- .Nm
- will fully dereference it and then evaluate the expression
- against the file referenced, except for the
- .Fl h
- and
- .Fl L
- primaries.
- .Pp
- These primaries can be combined with the following operators:
- .Bl -tag -width Ar
- .It Cm \&! Ar expression
- True if
- .Ar expression
- is false.
- .It Ar expression1 Fl a Ar expression2
- True if both
- .Ar expression1
- and
- .Ar expression2
- are true.
- .It Ar expression1 Fl o Ar expression2
- True if either
- .Ar expression1
- or
- .Ar expression2
- are true.
- .It Cm \&( Ar expression Cm \&)
- True if expression is true.
- .El
- .Pp
- The
- .Fl a
- operator has higher precedence than the
- .Fl o
- operator.
- .Pp
- Some shells may provide a builtin
- .Nm
- command which is similar or identical to this utility.
- Consult the
- .Xr builtin 1
- manual page.
- .Sh GRAMMAR AMBIGUITY
- The
- .Nm
- grammar is inherently ambiguous.
- In order to assure a degree of consistency,
- the cases described in the
- .St -p1003.2 ,
- section D11.2/4.62.4, standard
- are evaluated consistently according to the rules specified in the
- standards document.
- All other cases are subject to the ambiguity in the
- command semantics.
- .Pp
- In particular, only expressions containing
- .Fl a ,
- .Fl o ,
- .Cm \&(
- or
- .Cm \&)
- can be ambiguous.
- .Sh EXIT STATUS
- The
- .Nm
- utility exits with one of the following values:
- .Bl -tag -width indent
- .It 0
- expression evaluated to true.
- .It 1
- expression evaluated to false or expression was
- missing.
- .It >1
- An error occurred.
- .El
- .Sh EXAMPLES
- Implement
- .Li test FILE1 -nt FILE2
- using only
- .Tn POSIX
- functionality:
- .Pp
- .Dl test -n \&"$(find -L -- FILE1 -prune -newer FILE2 2>/dev/null)\&"
- .Pp
- This can be modified using non-standard
- .Xr find 1
- primaries like
- .Cm -newerca
- to compare other timestamps.
- .Sh COMPATIBILITY
- For compatibility with some other implementations,
- the
- .Cm =
- primary can be substituted with
- .Cm ==
- with the same meaning.
- .Sh SEE ALSO
- .Xr builtin 1 ,
- .Xr expr 1 ,
- .Xr find 1 ,
- .Xr sh 1 ,
- .Xr stat 1 ,
- .Xr symlink 7
- .Sh STANDARDS
- .Nm
- should be compliant with the
- IEEE Std 1003.1-2024 (“POSIX.1”)
- specification.
- .Pp
- The primaries
- .Cm == ,
- .Fl G ,
- and
- .Fl O
- are extensions.
- The
- .Fl a ,
- .Fl o
- binary primaries, and
- .Ql \&(
- and
- .Ql \&)
- operators are kept for backward compatibility but should be taken as deprecated.
- .Sh HISTORY
- A
- .Nm
- utility appeared in
- .At v7 .
- .Sh BUGS
- Both sides are always evaluated in
- .Fl a
- and
- .Fl o .
- For instance, the writable status of
- .Pa file
- will be tested by the following command even though the former expression
- indicated false, which results in a gratuitous access to the file system:
- .Dl "[ -z abc -a -w file ]"
- To avoid this, write
- .Dl "[ -z abc ] && [ -w file ]"