path: root/man1p/command.1p

.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved 
.TH "COMMAND" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual"
.\" command 
.SH NAME
command \- execute a simple command
.SH SYNOPSIS
.LP
\fBcommand\fP \fB[\fP\fB-p\fP\fB]\fP \fIcommand_name\fP \fB[\fP\fIargument\fP
\fB\&...\fP\fB]\fP\fB
.br
.sp
\fP
.LP
\fBcommand\fP \fB[\fP \fB-v | -V\fP \fB]\fP \fIcommand_name\fP\fB\fP
\fB
.br
\fP
.SH DESCRIPTION
.LP
The \fIcommand\fP utility shall cause the shell to treat the arguments
as a simple command, suppressing the shell function
lookup that is described in \fICommand Search and Execution\fP , item
1b.
.LP
If the \fIcommand_name\fP 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 \fISpecial Built-In Utilities\fP
shall not occur. In
every other respect, if \fIcommand_name\fP is not the name of a function,
the effect of \fIcommand\fP (with no options) shall be
the same as omitting \fIcommand\fP.
.LP
On systems supporting the User Portability Utilities option, the \fIcommand\fP
utility also shall provide information
concerning how a command name is interpreted by the shell; see \fB-v\fP
and \fB-V\fP.
.SH OPTIONS
.LP
The \fIcommand\fP utility shall conform to the Base Definitions volume
of IEEE\ Std\ 1003.1-2001, Section 12.2, Utility Syntax Guidelines.
.LP
The following options shall be supported:
.TP 7
\fB-p\fP
Perform the command search using a default value for \fIPATH\fP that
is guaranteed to find all of the standard utilities.
.TP 7
\fB-v\fP
(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 \fIShell Execution Environment\fP ), to invoke \fIcommand_name\fP,
but do not invoke
\fIcommand_name\fP. 
.RS
.IP " *" 3
Utilities, regular built-in utilities, \fIcommand_name\fPs including
a slash character, and any implementation-defined
functions that are found using the \fIPATH\fP variable (as described
in \fICommand
Search and Execution\fP ), shall be written as absolute pathnames.
.LP
.IP " *" 3
Shell functions, special built-in utilities, regular built-in utilities
not associated with a \fIPATH\fP search, and shell
reserved words shall be written as just their names.
.LP
.IP " *" 3
An alias shall be written as a command line that represents its alias
definition.
.LP
.IP " *" 3
Otherwise, no output shall be written and the exit status shall reflect
that the name was not found.
.LP
.RE
.TP 7
\fB-V\fP
(On systems supporting the User Portability Utilities option.) Write
a string to standard output that indicates how the name
given in the \fIcommand_name\fP operand will be interpreted by the
shell, in the current shell execution environment (see \fIShell Execution
Environment\fP ), but do not invoke \fIcommand_name\fP. Although the
format of
this string is unspecified, it shall indicate in which of the following
categories \fIcommand_name\fP falls and shall include the
information stated: 
.RS
.IP " *" 3
Utilities, regular built-in utilities, and any implementation-defined
functions that are found using the \fIPATH\fP variable
(as described in \fICommand Search and Execution\fP ), shall be identified
as such
and include the absolute pathname in the string.
.LP
.IP " *" 3
Other shell functions shall be identified as functions.
.LP
.IP " *" 3
Aliases shall be identified as aliases and their definitions included
in the string.
.LP
.IP " *" 3
Special built-in utilities shall be identified as special built-in
utilities.
.LP
.IP " *" 3
Regular built-in utilities not associated with a \fIPATH\fP search
shall be identified as regular built-in utilities. (The term
"regular" need not be used.)
.LP
.IP " *" 3
Shell reserved words shall be identified as reserved words.
.LP
.RE
.sp
.SH OPERANDS
.LP
The following operands shall be supported:
.TP 7
\fIargument\fP
One of the strings treated as an argument to \fIcommand_name\fP.
.TP 7
\fIcommand_name\fP
.sp
The name of a utility or a special built-in utility.
.sp
.SH STDIN
.LP
Not used.
.SH INPUT FILES
.LP
None.
.SH ENVIRONMENT VARIABLES
.LP
The following environment variables shall affect the execution of
\fIcommand\fP:
.TP 7
\fILANG\fP
Provide a default value for the internationalization variables that
are unset or null. (See the Base Definitions volume of
IEEE\ Std\ 1003.1-2001, Section 8.2, Internationalization Variables
for
the precedence of internationalization variables used to determine
the values of locale categories.)
.TP 7
\fILC_ALL\fP
If set to a non-empty string value, override the values of all the
other internationalization variables.
.TP 7
\fILC_CTYPE\fP
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).
.TP 7
\fILC_MESSAGES\fP
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.
.TP 7
\fINLSPATH\fP
Determine the location of message catalogs for the processing of \fILC_MESSAGES
\&.\fP 
.TP 7
\fIPATH\fP
Determine the search path used during the command search described
in \fICommand
Search and Execution\fP , except as described under the \fB-p\fP option.
.sp
.SH ASYNCHRONOUS EVENTS
.LP
Default.
.SH STDOUT
.LP
When the \fB-v\fP option is specified, standard output shall be formatted
as:
.sp
.RS
.nf

\fB"%s\\n", <\fP\fIpathname or command\fP\fB>
\fP
.fi
.RE
.LP
When the \fB-V\fP option is specified, standard output shall be formatted
as:
.sp
.RS
.nf

\fB"%s\\n", <\fP\fIunspecified\fP\fB>
\fP
.fi
.RE
.SH STDERR
.LP
The standard error shall be used only for diagnostic messages.
.SH OUTPUT FILES
.LP
None.
.SH EXTENDED DESCRIPTION
.LP
None.
.SH EXIT STATUS
.LP
When the \fB-v\fP or \fB-V\fP options are specified, the following
exit values shall be returned:
.TP 7
\ 0
Successful completion.
.TP 7
>0
The \fIcommand_name\fP could not be found or an error occurred.
.sp
.LP
Otherwise, the following exit values shall be returned:
.TP 7
126
The utility specified by \fIcommand_name\fP was found but could not
be invoked.
.TP 7
127
An error occurred in the \fIcommand\fP utility or the utility specified
by \fIcommand_name\fP could not be found.
.sp
.LP
Otherwise, the exit status of \fIcommand\fP shall be that of the simple
command specified by the arguments to
\fIcommand\fP.
.SH CONSEQUENCES OF ERRORS
.LP
Default.
.LP
\fIThe following sections are informative.\fP
.SH APPLICATION USAGE
.LP
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).
.LP
The system default path is available using \fIgetconf\fP; however,
since \fIgetconf\fP may need to have the \fIPATH\fP set up before
it can be called itself, the
following can be used:
.sp
.RS
.nf

\fBcommand -p getconf _CS_PATH
\fP
.fi
.RE
.LP
There are some advantages to suppressing the special characteristics
of special built-ins on occasion. For example:
.sp
.RS
.nf

\fBcommand exec >\fP \fIunwritable-file\fP
.fi
.RE
.LP
does not cause a non-interactive script to abort, so that the output
status can be checked by the script.
.LP
The \fIcommand\fP, \fIenv\fP, \fInohup\fP, \fItime\fP, and \fIxargs\fP
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 \fIexec\fP the
utility fail with [ENOENT], and uses 126 when any attempt to
\fIexec\fP the utility fails for any other reason.
.LP
Since the \fB-v\fP and \fB-V\fP options of \fIcommand\fP produce output
in relation to the current shell execution
environment, \fIcommand\fP 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:
.sp
.RS
.nf

\fB(PATH=foo command -v)
 nohup command -v
\fP
.fi
.RE
.LP
it does not necessarily produce correct results. For example, when
called with \fInohup\fP or an \fIexec\fP function, in a separate utility
execution environment, most
implementations are not able to identify aliases, functions, or special
built-ins.
.LP
Two types of regular built-ins could be encountered on a system and
these are described separately by \fIcommand\fP. The
description of command search in \fICommand Search and Execution\fP
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 \fIPATH\fP search.
So, for example, \fIcommand\fP \fB-v\fP \fItrue\fP might yield \fB/bin/true\fP
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 \fIexec\fPing them, using
them with \fInohup\fP, overriding them with a different \fIPATH ,\fP
and so on.
.SH EXAMPLES
.IP " 1." 4
Make a version of \fIcd\fP that always prints out the new working
directory exactly
once:
.sp
.RS
.nf

\fBcd() {
    command cd "$@" >/dev/null
    pwd
}
\fP
.fi
.RE
.LP
.IP " 2." 4
Start off a "secure shell script" in which the script avoids being
spoofed by its parent:
.sp
.RS
.nf

\fBIFS='
'
#    The preceding value should be <space><tab><newline>.
#    Set IFS to its default value.
.sp

\\unalias -a
#    Unset all possible aliases.
#    Note that unalias is escaped to prevent an alias
#    being used for unalias.
.sp

unset -f command
#    Ensure command is not a user function.
.sp

PATH="$(command -p getconf _CS_PATH):$PATH"
#    Put on a reliable PATH prefix.
.sp

#    ...
\fP
.fi
.RE
.LP
At this point, given correct permissions on the directories called
by \fIPATH ,\fP 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 \fIENV\fP variable precedes the
invocation of the script with a user start-up script. Such a script
could define functions to spoof the application.
.LP
.SH RATIONALE
.LP
Since \fIcommand\fP is a regular built-in utility it is always found
prior to the \fIPATH\fP search.
.LP
There is nothing in the description of \fIcommand\fP that implies
the command line is parsed any differently from that of any
other simple command. For example:
.sp
.RS
.nf

\fBcommand a | b ; c
\fP
.fi
.RE
.LP
is not parsed in any special way that causes \fB'|'\fP or \fB';'\fP
to be treated other than a pipe operator or semicolon
or that prevents function lookup on \fBb\fP or \fBc\fP.
.LP
The \fIcommand\fP utility is somewhat similar to the Eighth Edition
shell \fIbuiltin\fP command, but since \fIcommand\fP also
goes to the file system to search for utilities, the name \fIbuiltin\fP
would not be intuitive.
.LP
The \fIcommand\fP 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:
.IP " *" 3
The removal of exportable functions made the special precedence of
a special built-in unnecessary.
.LP
.IP " *" 3
A special built-in has special properties (see \fISpecial Built-In
Utilities\fP ) that
were inappropriate for invoking other utilities. For example, two
commands such as:
.sp
.RS
.nf

\fBdate >\fP \fIunwritable-file\fP\fB
.br

command date >\fP \fIunwritable-file\fP
.fi
.RE
.LP
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.
.LP
.LP
The \fB-p\fP 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 \fIexec\fP functions (as defined in the
System Interfaces volume of IEEE\ Std\ 1003.1-2001) when \fIPATH\fP
is unset. At the very least, this feature is required
to allow the script to access the correct version of \fIgetconf\fP
so that the value of
the default path can be accurately retrieved.
.LP
The \fIcommand\fP \fB-v\fP and \fB-V\fP options were added to satisfy
requirements from users that are currently accomplished
by three different historical utilities: \fItype\fP in the System
V shell, \fIwhence\fP in
the KornShell, and \fIwhich\fP in the C shell. Since there is no historical
agreement on how and what to accomplish here, the
POSIX \fIcommand\fP utility was enhanced and the historical utilities
were left unmodified. The C shell \fIwhich\fP merely
conducts a path search. The KornShell \fIwhence\fP is more elaborate-in
addition to the categories required by POSIX, it also
reports on tracked aliases, exported aliases, and undefined functions.
.LP
The output format of \fB-V\fP 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
\fB-v\fP to differentiate between various types of commands,
but the additional information that may be emitted by the more verbose
\fB-V\fP is not needed and should not be arbitrarily
constrained in its verbosity or localization for application parsing
reasons.
.SH FUTURE DIRECTIONS
.LP
None.
.SH SEE ALSO
.LP
\fICommand Search and Execution\fP , \fIShell
Execution Environment\fP , \fISpecial Built-In Utilities\fP , \fIsh\fP
, \fItype\fP , the System Interfaces volume of IEEE\ Std\ 1003.1-2001,
\fIexec\fP
.SH COPYRIGHT
Portions of this text are reprinted and reproduced in electronic form
from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
-- Portable Operating System Interface (POSIX), The Open Group Base
Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of
Electrical and Electronics Engineers, Inc and The Open Group. In the
event of any discrepancy between this version and the original IEEE and
The Open Group Standard, the original IEEE and The Open Group Standard
is the referee document. The original Standard can be obtained online at
http://www.opengroup.org/unix/online.html .