491 lines
19 KiB
HTML
491 lines
19 KiB
HTML
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
|
|
<html>
|
|
<head>
|
|
<meta name="generator" content="HTML Tidy, see www.w3.org">
|
|
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
|
|
<link type="text/css" rel="stylesheet" href="style.css"><!-- Generated by The Open Group's rhtm tool v1.2.1 -->
|
|
<!-- Copyright (c) 2001 The Open Group, All Rights Reserved -->
|
|
<title>command</title>
|
|
</head>
|
|
<body bgcolor="white">
|
|
<script type="text/javascript" language="JavaScript" src="../jscript/codes.js">
|
|
</script>
|
|
|
|
<basefont size="3"> <a name="command"></a> <a name="tag_04_24"></a><!-- command -->
|
|
<!--header start-->
|
|
<center><font size="2">The Open Group Base Specifications Issue 6<br>
|
|
IEEE Std 1003.1-2001<br>
|
|
Copyright © 2001 The IEEE and The Open Group, All Rights reserved.</font></center>
|
|
|
|
<!--header end-->
|
|
<hr size="2" noshade>
|
|
<h4><a name="tag_04_24_01"></a>NAME</h4>
|
|
|
|
<blockquote>command - execute a simple command</blockquote>
|
|
|
|
<h4><a name="tag_04_24_02"></a>SYNOPSIS</h4>
|
|
|
|
<blockquote class="synopsis">
|
|
<p><code><tt>command</tt> <b>[</b><tt>-p</tt><b>]</b> <i>command_name</i> <b>[</b><i>argument</i> <tt>...</tt><b>]</b><tt><br>
|
|
<br>
|
|
</tt></code></p>
|
|
|
|
<div class="box"><code><tt><sup>[<a href="javascript:open_code('UP')">UP</a>]</sup> <img src="../images/opt-start.gif" alt=
|
|
"[Option Start]" border="0"> command</tt> <b>[</b> <tt>-v | -V</tt> <b>]</b> <i>command_name</i><tt><img src=
|
|
"../images/opt-end.gif" alt="[Option End]" border="0"></tt></code></div>
|
|
|
|
<tt><br>
|
|
</tt></blockquote>
|
|
|
|
<h4><a name="tag_04_24_03"></a>DESCRIPTION</h4>
|
|
|
|
<blockquote>
|
|
<p>The <i>command</i> utility shall cause the shell to treat the arguments as a simple command, suppressing the shell function
|
|
lookup that is described in <a href="xcu_chap02.html#tag_02_09_01_01"><i>Command Search and Execution</i></a> , item 1b.</p>
|
|
|
|
<p>If the <i>command_name</i> is the same as the name of one of the special built-in utilities, the special properties in the
|
|
enumerated list at the beginning of <a href="xcu_chap02.html#tag_02_14"><i>Special Built-In Utilities</i></a> shall not occur. In
|
|
every other respect, if <i>command_name</i> is not the name of a function, the effect of <i>command</i> (with no options) shall be
|
|
the same as omitting <i>command</i>.</p>
|
|
|
|
<p>On systems supporting the User Portability Utilities option, the <i>command</i> utility also shall provide information
|
|
concerning how a command name is interpreted by the shell; see <b>-v</b> and <b>-V</b>.</p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_04_24_04"></a>OPTIONS</h4>
|
|
|
|
<blockquote>
|
|
<p>The <i>command</i> utility shall conform to the Base Definitions volume of IEEE Std 1003.1-2001, <a href=
|
|
"../basedefs/xbd_chap12.html#tag_12_02">Section 12.2, Utility Syntax Guidelines</a>.</p>
|
|
|
|
<p>The following options shall be supported:</p>
|
|
|
|
<dl compact>
|
|
<dt><b>-p</b></dt>
|
|
|
|
<dd>Perform the command search using a default value for <i>PATH</i> that is guaranteed to find all of the standard utilities.</dd>
|
|
|
|
<dt><b>-v</b></dt>
|
|
|
|
<dd>(On systems supporting the User Portability Utilities option.) Write a string to standard output that indicates the pathname or
|
|
command that will be used by the shell, in the current shell execution environment (see <a href=
|
|
"xcu_chap02.html#tag_02_12"><i>Shell Execution Environment</i></a> ), to invoke <i>command_name</i>, but do not invoke
|
|
<i>command_name</i>.
|
|
|
|
<ul>
|
|
<li>
|
|
<p>Utilities, regular built-in utilities, <i>command_name</i>s including a slash character, and any implementation-defined
|
|
functions that are found using the <i>PATH</i> variable (as described in <a href="xcu_chap02.html#tag_02_09_01_01"><i>Command
|
|
Search and Execution</i></a> ), shall be written as absolute pathnames.</p>
|
|
</li>
|
|
|
|
<li>
|
|
<p>Shell functions, special built-in utilities, regular built-in utilities not associated with a <i>PATH</i> search, and shell
|
|
reserved words shall be written as just their names.</p>
|
|
</li>
|
|
|
|
<li>
|
|
<p>An alias shall be written as a command line that represents its alias definition.</p>
|
|
</li>
|
|
|
|
<li>
|
|
<p>Otherwise, no output shall be written and the exit status shall reflect that the name was not found.</p>
|
|
</li>
|
|
</ul>
|
|
</dd>
|
|
|
|
<dt><b>-V</b></dt>
|
|
|
|
<dd>(On systems supporting the User Portability Utilities option.) Write a string to standard output that indicates how the name
|
|
given in the <i>command_name</i> operand will be interpreted by the shell, in the current shell execution environment (see <a href=
|
|
"xcu_chap02.html#tag_02_12"><i>Shell Execution Environment</i></a> ), but do not invoke <i>command_name</i>. Although the format of
|
|
this string is unspecified, it shall indicate in which of the following categories <i>command_name</i> falls and shall include the
|
|
information stated:
|
|
|
|
<ul>
|
|
<li>
|
|
<p>Utilities, regular built-in utilities, and any implementation-defined functions that are found using the <i>PATH</i> variable
|
|
(as described in <a href="xcu_chap02.html#tag_02_09_01_01"><i>Command Search and Execution</i></a> ), shall be identified as such
|
|
and include the absolute pathname in the string.</p>
|
|
</li>
|
|
|
|
<li>
|
|
<p>Other shell functions shall be identified as functions.</p>
|
|
</li>
|
|
|
|
<li>
|
|
<p>Aliases shall be identified as aliases and their definitions included in the string.</p>
|
|
</li>
|
|
|
|
<li>
|
|
<p>Special built-in utilities shall be identified as special built-in utilities.</p>
|
|
</li>
|
|
|
|
<li>
|
|
<p>Regular built-in utilities not associated with a <i>PATH</i> search shall be identified as regular built-in utilities. (The term
|
|
"regular" need not be used.)</p>
|
|
</li>
|
|
|
|
<li>
|
|
<p>Shell reserved words shall be identified as reserved words.</p>
|
|
</li>
|
|
</ul>
|
|
</dd>
|
|
</dl>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_04_24_05"></a>OPERANDS</h4>
|
|
|
|
<blockquote>
|
|
<p>The following operands shall be supported:</p>
|
|
|
|
<dl compact>
|
|
<dt><i>argument</i></dt>
|
|
|
|
<dd>One of the strings treated as an argument to <i>command_name</i>.</dd>
|
|
|
|
<dt><i>command_name</i></dt>
|
|
|
|
<dd><br>
|
|
The name of a utility or a special built-in utility.</dd>
|
|
</dl>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_04_24_06"></a>STDIN</h4>
|
|
|
|
<blockquote>
|
|
<p>Not used.</p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_04_24_07"></a>INPUT FILES</h4>
|
|
|
|
<blockquote>
|
|
<p>None.</p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_04_24_08"></a>ENVIRONMENT VARIABLES</h4>
|
|
|
|
<blockquote>
|
|
<p>The following environment variables shall affect the execution of <i>command</i>:</p>
|
|
|
|
<dl compact>
|
|
<dt><i>LANG</i></dt>
|
|
|
|
<dd>Provide a default value for the internationalization variables that are unset or null. (See the Base Definitions volume of
|
|
IEEE Std 1003.1-2001, <a href="../basedefs/xbd_chap08.html#tag_08_02">Section 8.2, Internationalization Variables</a> for
|
|
the precedence of internationalization variables used to determine the values of locale categories.)</dd>
|
|
|
|
<dt><i>LC_ALL</i></dt>
|
|
|
|
<dd>If set to a non-empty string value, override the values of all the other internationalization variables.</dd>
|
|
|
|
<dt><i>LC_CTYPE</i></dt>
|
|
|
|
<dd>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).</dd>
|
|
|
|
<dt><i>LC_MESSAGES</i></dt>
|
|
|
|
<dd>Determine the locale that should be used to affect the format and contents of diagnostic messages written to standard error and
|
|
informative messages written to standard output.</dd>
|
|
|
|
<dt><i>NLSPATH</i></dt>
|
|
|
|
<dd><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0">
|
|
Determine the location of message catalogs for the processing of <i>LC_MESSAGES .</i> <img src="../images/opt-end.gif" alt=
|
|
"[Option End]" border="0"></dd>
|
|
|
|
<dt><i>PATH</i></dt>
|
|
|
|
<dd>Determine the search path used during the command search described in <a href="xcu_chap02.html#tag_02_09_01_01"><i>Command
|
|
Search and Execution</i></a> , except as described under the <b>-p</b> option.</dd>
|
|
</dl>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_04_24_09"></a>ASYNCHRONOUS EVENTS</h4>
|
|
|
|
<blockquote>
|
|
<p>Default.</p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_04_24_10"></a>STDOUT</h4>
|
|
|
|
<blockquote>
|
|
<p>When the <b>-v</b> option is specified, standard output shall be formatted as:</p>
|
|
|
|
<pre>
|
|
<tt>"%s\n", <</tt><i>pathname or command</i><tt>>
|
|
</tt>
|
|
</pre>
|
|
|
|
<p>When the <b>-V</b> option is specified, standard output shall be formatted as:</p>
|
|
|
|
<pre>
|
|
<tt>"%s\n", <</tt><i>unspecified</i><tt>>
|
|
</tt>
|
|
</pre>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_04_24_11"></a>STDERR</h4>
|
|
|
|
<blockquote>
|
|
<p>The standard error shall be used only for diagnostic messages.</p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_04_24_12"></a>OUTPUT FILES</h4>
|
|
|
|
<blockquote>
|
|
<p>None.</p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_04_24_13"></a>EXTENDED DESCRIPTION</h4>
|
|
|
|
<blockquote>
|
|
<p>None.</p>
|
|
</blockquote>
|
|
|
|
<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> 0</dt>
|
|
|
|
<dd>Successful completion.</dd>
|
|
|
|
<dt>>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 ></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 "failure to find a utility" from "invoked utility
|
|
exited with an error indication". The value 127 was chosen because it is not commonly used for other meanings; most utilities use
|
|
small values for "normal error conditions" 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 Std 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 "$@" >/dev/null
|
|
pwd
|
|
}
|
|
</tt>
|
|
</pre>
|
|
</li>
|
|
|
|
<li>
|
|
<p>Start off a "secure shell script" in which the script avoids being spoofed by its parent:</p>
|
|
|
|
<pre>
|
|
<tt>IFS='
|
|
'
|
|
# The preceding value should be <space><tab><newline>.
|
|
# 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 Std 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 ></tt> <i>unwritable-file</i><tt><br>
|
|
command date ></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 Std 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 Std 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 ® is a registered Trademark of The Open Group.<br>
|
|
POSIX ® 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>
|
|
|