command.html

IEEE 1003.1-2003, Single Unix Specification v3

<h4><a name="tag_04_24_14"></a>EXIT STATUS</h4>

<blockquote>
<p>When the <b>-v</b> or <b>-V</b> options are specified, the following exit values shall be returned:</p>

<dl compact>
<dt>&nbsp;0</dt>

<dd>Successful completion.</dd>

<dt>&gt;0</dt>

<dd>The <i>command_name</i> could not be found or an error occurred.</dd>
</dl>

<p>Otherwise, the following exit values shall be returned:</p>

<dl compact>
<dt>126</dt>

<dd>The utility specified by <i>command_name</i> was found but could not be invoked.</dd>

<dt>127</dt>

<dd>An error occurred in the <i>command</i> utility or the utility specified by <i>command_name</i> could not be found.</dd>
</dl>

<p>Otherwise, the exit status of <i>command</i> shall be that of the simple command specified by the arguments to
<i>command</i>.</p>
</blockquote>

<h4><a name="tag_04_24_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_24_16"></a>APPLICATION USAGE</h4>

<blockquote>
<p>The order for command search allows functions to override regular built-ins and path searches. This utility is necessary to
allow functions that have the same name as a utility to call the utility (instead of a recursive call to the function).</p>

<p>The system default path is available using <a href="../utilities/getconf.html"><i>getconf</i></a>; however, since <a href=
"../utilities/getconf.html"><i>getconf</i></a> may need to have the <i>PATH</i> set up before it can be called itself, the
following can be used:</p>

<pre>
<tt>command -p getconf _CS_PATH
</tt>
</pre>

<p>There are some advantages to suppressing the special characteristics of special built-ins on occasion. For example:</p>

<pre>
<tt>command exec &gt;</tt> <i>unwritable-file</i>
</pre>

<p>does not cause a non-interactive script to abort, so that the output status can be checked by the script.</p>

<p>The <i>command</i>, <a href="../utilities/env.html"><i>env</i></a>, <a href="../utilities/nohup.html"><i>nohup</i></a>, <a href=
"../utilities/time.html"><i>time</i></a>, and <a href="../utilities/xargs.html"><i>xargs</i></a> utilities have been specified to
use exit code 127 if an error occurs so that applications can distinguish &quot;failure to find a utility&quot; from &quot;invoked utility
exited with an error indication&quot;. The value 127 was chosen because it is not commonly used for other meanings; most utilities use
small values for &quot;normal error conditions&quot; and the values above 128 can be confused with termination due to receipt of a signal.
The value 126 was chosen in a similar manner to indicate that the utility could be found, but not invoked. Some scripts produce
meaningful error messages differentiating the 126 and 127 cases. The distinction between exit codes 126 and 127 is based on
KornShell practice that uses 127 when all attempts to <i>exec</i> the utility fail with [ENOENT], and uses 126 when any attempt to
<i>exec</i> the utility fails for any other reason.</p>

<p>Since the <b>-v</b> and <b>-V</b> options of <i>command</i> produce output in relation to the current shell execution
environment, <i>command</i> is generally provided as a shell regular built-in. If it is called in a subshell or separate utility
execution environment, such as one of the following:</p>

<pre>
<tt>(PATH=foo command -v)
 nohup command -v
</tt>
</pre>

<p>it does not necessarily produce correct results. For example, when called with <a href=
"../utilities/nohup.html"><i>nohup</i></a> or an <i>exec</i> function, in a separate utility execution environment, most
implementations are not able to identify aliases, functions, or special built-ins.</p>

<p>Two types of regular built-ins could be encountered on a system and these are described separately by <i>command</i>. The
description of command search in <a href="xcu_chap02.html#tag_02_09_01_01"><i>Command Search and Execution</i></a> allows for a
standard utility to be implemented as a regular built-in as long as it is found in the appropriate place in a <i>PATH</i> search.
So, for example, <i>command</i> <b>-v</b> <i>true</i> might yield <b>/bin/true</b> or some similar pathname. Other
implementation-defined utilities that are not defined by this volume of IEEE&nbsp;Std&nbsp;1003.1-2001 might exist only as
built-ins and have no pathname associated with them. These produce output identified as (regular) built-ins. Applications
encountering these are not able to count on <i>exec</i>ing them, using them with <a href=
"../utilities/nohup.html"><i>nohup</i></a>, overriding them with a different <i>PATH ,</i> and so on.</p>
</blockquote>

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

<blockquote>
<ol>
<li>
<p>Make a version of <a href="../utilities/cd.html"><i>cd</i></a> that always prints out the new working directory exactly
once:</p>

<pre>
<tt>cd() {
    command cd "$@" &gt;/dev/null
    pwd
}
</tt>
</pre>
</li>

<li>
<p>Start off a &quot;secure shell script&quot; in which the script avoids being spoofed by its parent:</p>

<pre>
<tt>IFS='
'
#    The preceding value should be &lt;space&gt;&lt;tab&gt;&lt;newline&gt;.
#    Set IFS to its default value.
<br>
\unalias -a
#    Unset all possible aliases.
#    Note that unalias is escaped to prevent an alias
#    being used for unalias.
<br>
unset -f command
#    Ensure command is not a user function.
<br>
PATH="$(command -p getconf _CS_PATH):$PATH"
#    Put on a reliable PATH prefix.
<br>
#    ...
</tt>
</pre>

<p>At this point, given correct permissions on the directories called by <i>PATH ,</i> the script has the ability to ensure that
any utility it calls is the intended one. It is being very cautious because it assumes that implementation extensions may be
present that would allow user functions to exist when it is invoked; this capability is not specified by this volume of
IEEE&nbsp;Std&nbsp;1003.1-2001, but it is not prohibited as an extension. For example, the <i>ENV</i> variable precedes the
invocation of the script with a user start-up script. Such a script could define functions to spoof the application.</p>
</li>
</ol>
</blockquote>

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

<blockquote>
<p>Since <i>command</i> is a regular built-in utility it is always found prior to the <i>PATH</i> search.</p>

<p>There is nothing in the description of <i>command</i> that implies the command line is parsed any differently from that of any
other simple command. For example:</p>

<pre>
<tt>command a | b ; c
</tt>
</pre>

<p>is not parsed in any special way that causes <tt>'|'</tt> or <tt>';'</tt> to be treated other than a pipe operator or semicolon
or that prevents function lookup on <b>b</b> or <b>c</b>.</p>

<p>The <i>command</i> utility is somewhat similar to the Eighth Edition shell <i>builtin</i> command, but since <i>command</i> also
goes to the file system to search for utilities, the name <i>builtin</i> would not be intuitive.</p>

<p>The <i>command</i> utility is most likely to be provided as a regular built-in. It is not listed as a special built-in for the
following reasons:</p>

<ul>
<li>
<p>The removal of exportable functions made the special precedence of a special built-in unnecessary.</p>
</li>

<li>
<p>A special built-in has special properties (see <a href="xcu_chap02.html#tag_02_14"><i>Special Built-In Utilities</i></a> ) that
were inappropriate for invoking other utilities. For example, two commands such as:</p>

<pre>
<tt>date &gt;</tt> <i>unwritable-file</i><tt><br>
command date &gt;</tt> <i>unwritable-file</i>
</pre>

<p>would have entirely different results; in a non-interactive script, the former would continue to execute the next command, the
latter would abort. Introducing this semantic difference along with suppressing functions was seen to be non-intuitive.</p>
</li>
</ul>

<p>The <b>-p</b> option is present because it is useful to be able to ensure a safe path search that finds all the standard
utilities. This search might not be identical to the one that occurs through one of the <i>exec</i> functions (as defined in the
System Interfaces volume of IEEE&nbsp;Std&nbsp;1003.1-2001) when <i>PATH</i> is unset. At the very least, this feature is required
to allow the script to access the correct version of <a href="../utilities/getconf.html"><i>getconf</i></a> so that the value of
the default path can be accurately retrieved.</p>

<p>The <i>command</i> <b>-v</b> and <b>-V</b> options were added to satisfy requirements from users that are currently accomplished
by three different historical utilities: <a href="../utilities/type.html"><i>type</i></a> in the System V shell, <i>whence</i> in
the KornShell, and <i>which</i> in the C shell. Since there is no historical agreement on how and what to accomplish here, the
POSIX <i>command</i> utility was enhanced and the historical utilities were left unmodified. The C shell <i>which</i> merely
conducts a path search. The KornShell <i>whence</i> is more elaborate-in addition to the categories required by POSIX, it also
reports on tracked aliases, exported aliases, and undefined functions.</p>

<p>The output format of <b>-V</b> was left mostly unspecified because human users are its only audience. Applications should not be
written to care about this information; they can use the output of <b>-v</b> to differentiate between various types of commands,
but the additional information that may be emitted by the more verbose <b>-V</b> is not needed and should not be arbitrarily
constrained in its verbosity or localization for application parsing reasons.</p>
</blockquote>

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

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

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

<blockquote>
<p><a href="xcu_chap02.html#tag_02_09_01_01"><i>Command Search and Execution</i></a> , <a href="xcu_chap02.html#tag_02_12"><i>Shell
Execution Environment</i></a> , <a href="xcu_chap02.html#tag_02_14"><i>Special Built-In Utilities</i></a> , <a href=
"sh.html"><i>sh</i></a> , <a href="type.html"><i>type</i></a> , the System Interfaces volume of IEEE&nbsp;Std&nbsp;1003.1-2001,
<i>exec</i></p>
</blockquote>

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

<blockquote>
<p>First released in Issue 4.</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>