Test (Unix)

{{short description|Command-line utility}} {{Lowercase title}} {{Infobox software | name = test | logo = | screenshot = | screenshot size = | caption = | developer = Various open-source and commercial developers | released = | other_names = [ | latest release version = | latest release date = | programming language = C | operating system = Unix, Unix-like, Plan 9, IBM i | platform = Cross-platform | genre = Command | license = coreutils: GPLv3+<br />Plan 9: MIT License | website = }} '''test''' is a command-line utility found in Unix, Plan 9, and Unix-like operating systems that evaluates conditional expressions. '''test''' was turned into a shell builtin command in 1981 with UNIX System III and at the same time made available under the alternate name '''['''.<ref>http://www.in-ulm.de/~mascheck/bourne/#system3 {{Webarchive|url=https://web.archive.org/web/20190504035047/https://www.in-ulm.de/~mascheck/bourne/PWB/#system3 |date=2019-05-04 }} Bourne Shell changes with System III</ref>

==Overview== The <code>test</code> command in Unix evaluates the <code>expression</code> parameter. In most recent shell implementations, it is a shell builtin, even though the external version still exists. In the second form of the command, the <code>[ ]</code> (brackets) must be surrounded by blank spaces (this is because <code>[</code> is a program and POSIX compatible shells require a space between the program name and its arguments). One must test explicitly for file names in the C shell. File-name substitution (globbing) causes the shell script to exit.

The <code>test</code> command is not to be confused with the <code>[[</code> reserved word that was introduced with ksh88. The latter is not a command but part of the ksh88 syntax and does not apply file-name substitution to glob expressions.

The version of <code>test</code> bundled in GNU coreutils was written by Kevin Braunsdorf and Matthew Bradburn.<ref>{{Cite web |url=https://manpages.debian.org/buster/coreutils/test.1.en.html |title=test(1) — coreutils — Debian buster — Debian Manpages |access-date=2020-07-12 |archive-date=2020-07-12 |archive-url=https://web.archive.org/web/20200712145342/https://manpages.debian.org/buster/coreutils/test.1.en.html |url-status=live }}</ref> The command is available as a separate package for Microsoft Windows as part of the UnxUtils collection of native Win32 ports of common GNU Unix-like utilities.<ref>{{Cite web|url=https://unxutils.sourceforge.net/|title=Native Win32 ports of some GNU utilities|website=unxutils.sourceforge.net|access-date=2025-08-11|archive-date=2006-02-09|archive-url=https://web.archive.org/web/20060209022842/http://unxutils.sourceforge.net/|url-status=live}}</ref> The {{Mono|test}} command has also been ported to the IBM i operating system.<ref>{{cite web |title=IBM System i Version 7.2 Programming Qshell |language=en |author=IBM |website=IBM |author-link=IBM |url=https://www.ibm.com/support/knowledgecenter/ssw_ibm_i_74/rzahz/rzahzpdf.pdf?view=kc |access-date=2020-09-05 |archive-date=2020-09-18 |archive-url=https://web.archive.org/web/20200918130823/https://www.ibm.com/support/knowledgecenter/ssw_ibm_i_74/rzahz/rzahzpdf.pdf?view=kc |url-status=live }}</ref>

==Syntax== <code>test ''expression''</code> or <code>[ ''expression'' ]</code>

===Arguments=== The following arguments are used to construct this parameter. All arguments return <code>True</code> if the object (file or string) exists, and the condition specified is true.

{| class="wikitable" |- ! Argument ! Returns <code>True</code> if the file |- | -b || is a block special file |- | -c || is a character special file |- | -d || is a directory |- | -e || exists |- | -f || is a regular file |- | -g || has the Set Group ID bit set |- | -h || is a symbolic link |- | -k || has the sticky bit set |- | -L || is a symbolic link |- | -p || is a named pipe (FIFO) |- | -r || is readable by the current process |- | -s || has a size greater than 0 |- | -t || FileDescriptor is open and associated with a terminal |- | -u || has the Set User ID bit set |- | -w || has the write flag is on |- | -x || has execute flag on |} For the <code>-x</code> argument, if the specified file exists and is a directory, the <code>True</code> exit value indicates that the current process has permission to change <code>cd</code> into the directory.

====Non standard Korn Shell extensions==== file1 '''-nt''' file2 - file1 is newer than file2 file1 '''-ot''' file2 - file1 is older than file2 file1 '''-ef''' file2 - file1 is another name for file2 - (symbolic link or hard link)

====String arguments==== In Perl, these sections are reversed: <code>eq</code> is a string operator and <code>==</code> is a numerical operator, and so on for the others.

'''-n''' String1 - the length of the String1 variable is nonzero '''-z''' String1 - the length of the String1 variable is 0 (zero) String1 '''=''' String2 - String1 and String2 variables are identical String1 '''!=''' String2 - String1 and String2 variables are not identical String1 - true if String1 variable is not a null string

====Number arguments==== Integer1 '''-eq''' Integer2 - Integer1 and Integer2 variables are algebraically equal '''-ne''' - not equal '''-gt''' - greater than '''-ge''' - greater or equal '''-lt''' - less than '''-le''' - less or equal

====Operators==== <code>test</code> arguments can be combined with the following operators: '''!''' - Unary negation operator '''-a''' - Binary AND operator '''-o''' - Binary OR operator (the <code>-a</code> operator has higher precedence than the <code>-o</code> operator) '''$Expression$''' - Parentheses for grouping must be escaped with a backslash <code>\</code>

The <code>-a</code> and <code>-o</code> operators, along with parentheses for grouping, are XSI extensions<ref>{{Cite web |url=http://www.opengroup.org/onlinepubs/009695399/utilities/test.html |title=IEEE Std 1003.1, 2004, documentation for <code>test</code> |access-date=2006-11-08 |archive-date=2008-07-08 |archive-url=https://web.archive.org/web/20080708224750/http://www.opengroup.org/onlinepubs/009695399/utilities/test.html |url-status=live }}</ref> and are therefore not portable. In portable shell scripts, the same effect may be achieved by connecting multiple invocations of <code>test</code> together with the <code>&&</code> and <code>||</code> operators and parentheses.

===Exit status=== This command returns the following exit values:

'''0''' - The Expression parameter is true '''1''' - The Expression parameter is false or missing '''>1''' - An error occurred

==Examples== 1. To test whether a file is nonexistent or empty, type: <syntaxhighlight lang="bash"> if test ! -s "$1" then echo $1 does not exist or is empty. fi </syntaxhighlight> If the file specified by the first positional parameter to the shell procedure, $1, does not exist or is of size 0, the test command displays the message. If $1 exists and has a size greater than 0, the test command displays nothing.

Note: There must be a space between the -s function and the file name.

The quotation marks around $1 ensure that the test works properly even if the value of $1 is a null string. If the quotation marks are omitted and $1 is the empty string, the test command displays the error message:

test: argument expected.

2. To do a complex comparison, type: <syntaxhighlight lang="bash"> if [ "$#" -lt 2 ] || ! [ -e "$1" ] then exit fi </syntaxhighlight> If the shell procedure is given fewer than two positional parameters or the file specified by $1 does not exist, then the shell procedure exits. The special shell variable $# represents the number of positional parameters entered on the command line that starts this shell procedure.

==See also== * List of POSIX commands * Unix shell * find (Unix)

==References== {{Reflist}}

==Further reading== * {{cite book|last1=Robbins |first1=Arnold |author2=Nelson H. F. Beebe |title=Classic Shell Scripting: Hidden Commands that Unlock the Power of Unix |chapter-url=https://books.google.com/books?id=jO-iKwPRX0QC&pg=PA146 |date=2005 |publisher=O'Reilly Media, Inc. |isbn=978-0-596-55526-9 |pages=120–128 |chapter=6.2.4 The test Command}} * {{cite web |author=Ian Shields |date=20 February 2007 |title=Linux tip: Bash test and comparison functions |work=IBM DeveloperWorks |url=https://www.ibm.com/developerworks/library/l-bash-test/ }} * {{cite book |author=William Shotts |date=2013 |title=The Linux Command Line |chapter=27 – Flow Control: Branching With if |pages=381–390 |publisher=No Starch Press |isbn=978-1-59327-389-7 |url=http://linuxcommand.org/tlcl.php }} (free download)

==External links== {{Wikibooks|Guide to Unix|Commands}} * {{man|cu|test|SUS}} * {{man|1|test|die.net}} * {{man|1|test|Plan 9}}

Category:Unix SUS2008 utilities Category:Plan 9 commands Category:IBM i Qshell commands Category:Conditional constructs