command(1) command(1)
NAME
command - execute a simple command
SYNOPSIS
command [-p] commandname [argument ...]
command [ -v | -V ] commandname
DESCRIPTION
The command utility causes the shell to treat the arguments as a simple
command, suppressing the shell function lookup.
If the commandname is the same as the name of one of the special built-
in utilities, the special properties in the enumerated list below (See
SPECIAL BUILT-IN PROPERTIES) will not occur. In every other respect, if
commandname is not the name of a function, the effect of command will be
the same as omitting command.
The command utility also provides information concerning how a command
name will be interpreted by the shell; see -v and -V.
OPTIONS
The command utility supports the XBD specification, Utility Syntax
Guidelines.
The following options are supported:
-p Perform the command search using a default value for PATH that is
guaranteed to find all of the standard utilities.
-v 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, to invoke commandname.
Utilities, regular built-in utilities, command_names including a
slash character, and any implementation-dependent functions that
are found using the PATH variable will be written as absolute
pathnames.
Shell functions, special built-in utilities, regular built-in
utilities not associated with a PATH search, and shell reserved
words will be written as just their names.
An alias will be written as a command line that represents its
alias definition.
Otherwise, no output will be written and the exit status will
reflect that the name was not found.
-V Write a string to standard output that indicates how the name given
in the commandname operand will be interpreted by the shell, in the
current shell execution environment. Although the format of this
string is unspecified, it will indicate in which of the following
Page 1
command(1) command(1)
categories commandname falls and include the information stated:
Utilities, regular built-in utilities, and any implementation-
dependent functions that are found using the PATH variable will
be identified as such and include the absolute pathname in the
string.
Other shell functions will be identified as functions.
Aliases will be identified as aliases and their definitions will
be included in the string.
Special built-in utilities will be identified as special built-in
utilities.
Regular built-in utilities not associated with a PATH search will
be identified as regular built-in utilities. (The term "regular"
need not be used.)
Shell reserved words will be identified as reserved words.
OPERANDS
The following operands are supported:
argument One of the strings treated as an argument to commandname.
commandname The name of a utility or a special built-in utility.
ENVIRONMENT VARIABLES
The following environment variables affect the execution of command:
PATH Determine the search path used during the command search
described in Command Search and Execution, except as described
under the -p option.
STDOUT
When the -v option is specified, standard output is formatted as:
"%s\n", <pathname or command>
When the -V option is specified, standard output is formatted as:
"%s\n", <unspecified>
EXIT STATUS
When the -v or -V options are specified, the following exit values are
returned:
0 Successful completion.
Page 2
command(1) command(1)
>0 The commandname could not be found or an error occurred.
Otherwise, the following exit values are returned:
126 The utility specified by commandname was found but could not be
invoked.
127 An error occurred in the command utility or the utility specified
by commandname could not be found.
Otherwise, the exit status of command will be that of the simple command
specified by the arguments to command.
APPLICATION USAGE
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).
The system default path is available using getconf; however, since
getconf may need to have the PATH set up before it can be called itself,
the following can be used:
command -p getconf _CS_PATH
There are some advantages to suppressing the special characteristics of
special built-ins on occasion. For example:
command exec > unwritable-file
will not cause a non-interactive script to abort, so that the output
status can be checked by the script.
The command, env, nohup, time and xargs 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 exec the utility fail with
[ENOENT], and uses 126 when any attempt to exec the utility fails for any
other reason.
Since the -v and -V options of command produce output in relation to the
current shell execution environment, command 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:
Page 3
command(1) command(1)
(PATH=foo command -v) nohup command -v
it will not necessarily produce correct results. For example, when called
with nohup or an exec function, in a separate utility execution
environment, most implementations will not be able to identify aliases,
functions or special built-ins.
Two types of regular built-ins could be encountered on a system and these
are described separately by command. The description of command search in
Command Search and Execution 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 PATH search. So, for example, command -v true
might yield /bin/true or some similar pathname. Other implementation-
dependent utilities that are not defined by this specification might
exist only as built-ins and have no pathname associated with them. These
will produce output identified as (regular) built-ins. Applications
encountering these will not be able to count on execing them, using them
with nohup, overriding them with a different PATH, and so on.
EXAMPLES
1. Make a version of cd that always prints out the new working directory
exactly once:
cd() { command cd "$@" >/dev/null pwd }
2. Start off a "secure shell script" in which the script avoids being
spoofed by its parent:
IFS='
'
# The preceding value should be <space><tab><newline>.
# Set IFS to its default value.
\unalias -a
# Unset all possible aliases.
# Note that unalias is escaped to prevent an alias
# being used for unalias.
unset -f command
# Ensure command is not a user function.
PATH="$(command -p getconf _CS_PATH):$PATH"
# Put on a reliable PATH prefix.
# ...
At this point, given correct permissions on the directories called by
PATH, 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
specification, but it is not prohibited as an extension. For example, the
Page 4
command(1) command(1)
ENV variable precedes the invocation of the script with a user startup
script. Such a script could define functions to spoof the application.
SPECIAL BUILT-IN PROPERTIES
A syntax error in a special built-in utility may cause a shell executing
that utility to abort, while a syntax error in a regular built-in utility
will not cause a shell executing that utility to abort. If a special
built-in utility encountering a syntax error does not abort the shell,
its exit value will be non-zero.
Variable assignments specified with special built-in utilities will
remain in effect after the built-in completes; this is not the case with
a regular built-in or other utility.
SEE ALSO
sh(1), type(1).
Page 5