test.html

IEEE 1003.1-2003, Single Unix Specification v3

<dd><i>expression</i> evaluated to false or <i>expression</i> was missing.</dd>

<dt>&gt;1</dt>

<dd>An error occurred.</dd>
</dl>
</blockquote>

<h4><a name="tag_04_140_15"></a>CONSEQUENCES OF ERRORS</h4>

<blockquote>
<p>Default.</p>
</blockquote>

<hr>
<div class="box"><em>The following sections are informative.</em></div>

<h4><a name="tag_04_140_16"></a>APPLICATION USAGE</h4>

<blockquote>
<p>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, invocations like:</p>

<pre>
<tt>test "$1" -a "$2"
</tt>
</pre>

<p>should be written as:</p>

<pre>
<tt>test "$1" &amp;&amp; test "$2"
</tt>
</pre>

<p>to avoid problems if a user supplied values such as $1 set to <tt>'!'</tt> and $2 set to the null string. That is, in cases
where maximal portability is of concern, replace:</p>

<pre>
<tt>test expr1 -a expr2
</tt>
</pre>

<p>with:</p>

<pre>
<tt>test expr1 &amp;&amp; test expr2
</tt>
</pre>

<p>and replace:</p>

<pre>
<tt>test expr1 -o expr2
</tt>
</pre>

<p>with:</p>

<pre>
<tt>test expr1 || test expr2
</tt>
</pre>

<p>but note that, in <i>test</i>, <b>-a</b> has higher precedence than <b>-o</b> while <tt>"&amp;&amp;"</tt> and <tt>"||"</tt> have
equal precedence in the shell.</p>

<p>Parentheses or braces can be used in the shell command language to effect grouping.</p>

<p>Parentheses must be escaped when using <a href="../utilities/sh.html"><i>sh</i></a>; for example:</p>

<pre>
<tt>test \( expr1 -a expr2 \) -o expr3
</tt>
</pre>

<p>This command is not always portable outside XSI-conformant systems. The following form can be used instead:</p>

<pre>
<tt>( test expr1 &amp;&amp; test expr2 ) || test expr3
</tt>
</pre>

<p>The two commands:</p>

<pre>
<tt>test "$1"
test ! "$1"
</tt>
</pre>

<p>could not be used reliably on some historical systems. Unexpected results would occur if such a <i>string</i> expression were
used and $1 expanded to <tt>'!'</tt> , <tt>'('</tt> , or a known unary primary. Better constructs are:</p>

<pre>
<tt>test -n "$1"
test -z "$1"
</tt>
</pre>

respectively. 

<p>Historical systems have also been unreliable given the common construct:</p>

<pre>
<tt>test "$response" = "expected string"
</tt>
</pre>

<p>One of the following is a more reliable form:</p>

<pre>
<tt>test "X$response" = "Xexpected string"
test "expected string" = "$response"
</tt>
</pre>

<p>Note that the second form assumes that <i>expected string</i> could not be confused with any unary primary. If <i>expected
string</i> starts with <tt>'-'</tt> , <tt>'('</tt> , <tt>'!'</tt> , or even <tt>'='</tt> , 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.)</p>

<p>Because the string comparison binary primaries, <tt>'='</tt> and <tt>"!="</tt> , 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:</p>

<pre>
<tt>test -d $1 -o -d $2
</tt>
</pre>

<p>If $1 evaluates to a possible directory name of <tt>'='</tt> , the first three arguments are considered a string comparison,
which shall cause a syntax error when the second <b>-d</b> is encountered. One of the following forms prevents this; the second is
preferred:</p>

<pre>
<tt>test \( -d "$1" \) -o \( -d "$2" \)
test -d "$1" || test -d "$2"
</tt>
</pre>

<p>Also in the greater than 4 argument case:</p>

<pre>
<tt>test "$1" = "bat" -a "$2" = "ball"
</tt>
</pre>

<p>syntax errors occur if $1 evaluates to <tt>'('</tt> or <tt>'!'</tt> . One of the following forms prevents this; the third is
preferred:</p>

<pre>
<tt>test "X$1" = "Xbat" -a "X$2" = "Xball"
test "$1" = "bat" &amp;&amp; test "$2" = "ball"
test "X$1" = "Xbat" &amp;&amp; test "X$2" = "Xball"
</tt>
</pre>
</blockquote>

<h4><a name="tag_04_140_17"></a>EXAMPLES</h4>

<blockquote>
<ol>
<li>
<p>Exit if there are not two or three arguments (two variations):</p>

<pre>
<tt>if [ $# -ne 2 -a $# -ne 3 ]; then exit 1; fi
if [ $# -lt 2 -o $# -gt 3 ]; then exit 1; fi
</tt>
</pre>
</li>

<li>
<p>Perform a <a href="../utilities/mkdir.html"><i>mkdir</i></a> if a directory does not exist:</p>

<pre>
<tt>test ! -d tempdir &amp;&amp; mkdir tempdir
</tt>
</pre>
</li>

<li>
<p>Wait for a file to become non-readable:</p>

<pre>
<tt>while test -r thefile
do
    sleep 30
done
echo '"thefile" is no longer readable'
</tt>
</pre>
</li>

<li>
<p>Perform a command if the argument is one of three strings (two variations):</p>

<pre>
<tt>if [ "$1" = "pear" ] || [ "$1" = "grape" ] || [ "$1" = "apple" ]
then
   </tt> <i>command</i><tt>
fi
<br>
case "$1" in
    pear|grape|apple)</tt> <i>command</i> <tt>;;
esac
</tt>
</pre>
</li>
</ol>
</blockquote>

<h4><a name="tag_04_140_18"></a>RATIONALE</h4>

<blockquote>
<p>The KornShell-derived conditional command (double bracket <b>[[]]</b>) was removed from the shell command language description
in an early proposal. Objections were raised that the real problem is misuse of the <i>test</i> command ( <b>[</b>), and putting it
into the shell is the wrong way to fix the problem. Instead, proper documentation and a new shell reserved word ( <b>!</b>) are
sufficient.</p>

<p>Tests that require multiple <i>test</i> operations can be done at the shell level using individual invocations of the
<i>test</i> command and shell logicals, rather than using the error-prone <b>-o</b> flag of <i>test</i>.</p>

<p>XSI-conformant systems support more than four arguments.</p>

<p>XSI-conformant systems support the combining of primaries with the following constructs:</p>

<dl compact>
<dt><i>expression1</i> <b>-a</b> <i>expression2</i></dt>

<dd><br>
True if both <i>expression1</i> and <i>expression2</i> are true.</dd>

<dt><i>expression1</i> <b>-o</b> <i>expression2</i></dt>

<dd><br>
True if at least one of <i>expression1</i> and <i>expression2</i> are true.</dd>

<dt><b>(</b> <i>expression</i> <b>)</b></dt>

<dd><br>
True if <i>expression</i> is true.</dd>
</dl>

<p>In evaluating these more complex combined expressions, the following precedence rules are used:</p>

<ul>
<li>
<p>The unary primaries have higher precedence than the algebraic binary primaries.</p>
</li>

<li>
<p>The unary primaries have lower precedence than the string binary primaries.</p>
</li>

<li>
<p>The unary and binary primaries have higher precedence than the unary <i>string</i> primary.</p>
</li>

<li>
<p>The <b>!</b> operator has higher precedence than the <b>-a</b> operator, and the <b>-a</b> operator has higher precedence than
the <b>-o</b> operator.</p>
</li>

<li>
<p>The <b>-a</b> and <b>-o</b> operators are left associative.</p>
</li>

<li>
<p>The parentheses can be used to alter the normal precedence and associativity.</p>
</li>
</ul>

<p>The BSD and System V versions of <b>-f</b> are not the same. The BSD definition was:</p>

<dl compact>
<dt><b>-f&nbsp;</b> <i>file</i></dt>

<dd>True if <i>file</i> exists and is not a directory.</dd>
</dl>

<p>The SVID version (true if the file exists and is a regular file) was chosen for this volume of IEEE&nbsp;Std&nbsp;1003.1-2001
because its use is consistent with the <b>-b</b>, <b>-c</b>, <b>-d</b>, and <b>-p</b> operands ( <i>file</i> exists and is a
specific file type).</p>

<p>The <b>-e</b> 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:</p>

<pre>
<tt>test -b foo -o -c foo -o -d foo -o -f foo -o -p foo
</tt>
</pre>

<p>to find out if <b>foo</b> is an existing file. On historical BSD systems, the existence of a file could be determined by:</p>

<pre>
<tt>test -f foo -o -d foo
</tt>
</pre>

<p>but there was no easy way to determine that an existing file was a regular file. An early proposal used the KornShell <b>-a</b>
primary (with the same meaning), but this was changed to <b>-e</b> because there were concerns about the high probability of humans
confusing the <b>-a</b> primary with the <b>-a</b> binary operator.</p>

<p>The following options were not included in this volume of IEEE&nbsp;Std&nbsp;1003.1-2001, although they are provided by some
implementations. These operands should not be used by new implementations for other purposes:</p>

<dl compact>
<dt><b>-k&nbsp;</b> <i>file</i></dt>

<dd>True if <i>file</i> exists and its sticky bit is set.</dd>

<dt><b>-C&nbsp;</b> <i>file</i></dt>

<dd>True if <i>file</i> is a contiguous file.</dd>

<dt><b>-V&nbsp;</b> <i>file</i></dt>

<dd>True if <i>file</i> is a version file.</dd>
</dl>

<p>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 <a href=
"xcu_chap02.html#tag_02_06_02"><i>Parameter Expansion</i></a> .</p>

<dl compact>
<dt><b>-l&nbsp;</b> <i>string</i></dt>

<dd>The length of the string <i>string</i>.</dd>
</dl>

<p>The <b>-b</b>, <b>-c</b>, <b>-g</b>, <b>-p</b>, <b>-u</b>, and <b>-x</b> operands are derived from the SVID; historical BSD does
not provide them. The <b>-k</b> operand is derived from System V; historical BSD does not provide it.</p>

<p>On historical BSD systems, <i>test</i> <b>-w</b> <i>directory</i> always returned false because <i>test</i> tried to open the
directory for writing, which always fails.</p>

<p>Some additional primaries newly invented or from the KornShell appeared in an early proposal as part of the conditional command
( <b>[[]]</b>): <i>s1</i> <b>&gt;</b> <i>s2</i>, <i>s1</i> <b>&lt;</b> <i>s2</i>, <i>str</i> <b>=</b> <i>pattern</i>, <i>str</i>
<b>!=</b> <i>pattern</i>, <i>f1</i> <b>-nt</b> <i>f2</i>, <i>f1</i> <b>-ot</b> <i>f2</i>, and <i>f1</i> <b>-ef</b> <i>f2</i>. They
were not carried forward into the <i>test</i> utility when the conditional command was removed from the shell because they have not
been included in the <i>test</i> utility built into historical implementations of the <a href="../utilities/sh.html"><i>sh</i></a>
utility.</p>

<p>The <b>-t</b> <i>file_descriptor</i> 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.</p>
</blockquote>

<h4><a name="tag_04_140_19"></a>FUTURE DIRECTIONS</h4>

<blockquote>
<p>None.</p>
</blockquote>

<h4><a name="tag_04_140_20"></a>SEE ALSO</h4>

<blockquote>
<p><a href="xcu_chap01.html#tag_01_07_01_04"><i>File Read, Write, and Creation</i></a> , <a href="find.html"><i>find</i></a></p>
</blockquote>

<h4><a name="tag_04_140_21"></a>CHANGE HISTORY</h4>

<blockquote>
<p>First released in Issue 2.</p>
</blockquote>

<h4><a name="tag_04_140_22"></a>Issue 5</h4>

<blockquote>
<p>The FUTURE DIRECTIONS section is added.</p>
</blockquote>

<h4><a name="tag_04_140_23"></a>Issue 6</h4>

<blockquote>
<p>The <b>-h</b> operand is added for symbolic links, and access permission requirements are clarified for the <b>-r</b>,
<b>-w</b>, and <b>-x</b> operands to align with the IEEE&nbsp;P1003.2b draft standard.</p>

<p>The normative text is reworded to avoid use of the term &quot;must&quot; for application requirements.</p>

<p>The <b>-L</b> and <b>-S</b> operands are added for symbolic links and sockets.</p>

<p>IEEE&nbsp;Std 1003.1-2001/Cor&nbsp;1-2002, item XCU/TC1/D6/38 is applied, adding XSI margin marking and shading to a line in the
OPERANDS section referring to the use of parentheses as arguments to the <i>test</i> utility.</p>
</blockquote>

<div class="box"><em>End of informative text.</em></div>

<hr>
<hr size="2" noshade>
<center><font size="2"><!--footer start-->
UNIX &reg; is a registered Trademark of The Open Group.<br>
POSIX &reg; is a registered Trademark of The IEEE.<br>
[ <a href="../mindex.html">Main Index</a> | <a href="../basedefs/contents.html">XBD</a> | <a href=
"../utilities/contents.html">XCU</a> | <a href="../functions/contents.html">XSH</a> | <a href="../xrat/contents.html">XRAT</a>
]</font></center>

<!--footer end-->
<hr size="2" noshade>
</body>
</html>