mirror of https://github.com/mkerrisk/man-pages
485 lines
15 KiB
Groff
485 lines
15 KiB
Groff
.\" 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 .
|