'\"macro stdmacro
.if n .pH g1.command @(#)command	30.2 of 12/25/85
.nr X
.if \nX=0 .ds x} command 1 "Essential Utilities" "\&"
.if \nX=1 .ds x} command 1 "Essential Utilities"
.if \nX=2 .ds x} command 1 "" "\&"
.if \nX=3 .ds x} command "" "" "\&"
.ds OK [\|
.ds CK \|]
.TH \*(x}
.SH NAME
\f3command\f1 - execute a simple command
.SH SYNOPSIS
.nf
\f3command\f1 [\f3-p\f1] \f3command_name\f1 [\f3argument\f1 ...]
\f3command\f1 [ \f3-v\f1 | \f3-V\f1 ] \f3command_name\f1
.SH DESCRIPTION
The \f3command\f1 utility causes the shell to treat the arguments as a simple
command, suppressing the shell function lookup.
.PP
If the \f3command_name\f1 is the same as the name of one of the special
built-in utilities, the special properties in the enumerated list below
(See \f3SPECIAL BUILT-IN PROPERTIES\f1) will not occur. In every
other respect, if \f3command_name\f1 is not the name of a function, the
effect of \f3command\f1 will be the same as omitting \f3command\f1.
.PP
The \f3command\f1 utility also provides information concerning how a command
name will be interpreted by the shell; see \f3-v\f1 and \f3-V\f1.
.SH OPTIONS
The \f3command\f1 utility supports the XBD specification, Utility Syntax
Guidelines.
.PP
The following options are supported:
.TP 4
\f3-p\f1 
Perform the command search using a default value for \f3PATH\f1 that is
guaranteed to find all of the standard utilities.
.TP 4
\f3-v\f1 
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 \f3command_name\f1.
.TP 8
\ 
Utilities, regular built-in utilities, command_names including a slash
character, and any implementation-dependent functions that are found
using the \f3PATH\f1 variable will be written as absolute pathnames.
.TP 8
\ 
Shell functions, special built-in utilities, regular built-in utilities
not associated with a \f3PATH\f1 search, and shell reserved words will be
written as just their names.
.TP 8
\ 
An alias will be written as a command line that represents its alias
definition.
.TP 8
\ 
Otherwise, no output will be written and the exit status will reflect
that the name was not found.
.TP 4
\f3-V\f1
Write a string to standard output that indicates how the name given
in the \f3command_name\f1 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 categories \f3command_name\f1 falls and include the
information stated:
.TP 8
\ 
Utilities, regular built-in utilities, and any implementation-dependent
functions that are found using the \f3PATH\f1 variable
will be identified as such and include
the absolute pathname in the string.
.TP 8
\ 
Other shell functions will be identified as functions.
.TP 8
\ 
Aliases will be identified as aliases and their definitions will be
included in the string.
.TP 8
\ 
Special built-in utilities will be identified as special built-in
utilities.
.TP 8
\ 
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.)
.TP 8
\ 
Shell reserved words will be identified as reserved words.
.SH OPERANDS
The following operands are supported:
.TP 15
\f3argument\f1
One of the strings treated as an argument to \f3command_name\f1.
.TP 15
\f3command_name\f1
The name of a utility or a special built-in utility.
.SH ENVIRONMENT VARIABLES
The following environment variables affect the execution of command:
.TP 8
\f3PATH\f1
Determine the search path used during the command search described
in Command Search and Execution, except as described under the \f3-p\f1
option.
.SH STDOUT
When the \f3-v\f1 option is specified, standard output is formatted as:
.IP
"%s\\n", <pathname or command>
.PP
When the \f3-V\f1 option is specified, standard output is formatted as:
.IP
"%s\\n", <unspecified>
.SH EXIT STATUS
When the \f3-v\f1 or \f3-V\f1 options are specified, the following exit values are
returned:
.TP 6
0
Successful completion.
.TP 6
>0
The \f3command_name\f1 could not be found or an error occurred.
.PP
Otherwise, the following exit values are returned:
.TP 6
126
The utility specified by \f3command_name\f1 was found but could not be
invoked.
.TP 6
127
An error occurred in the \f3command\f1 utility or the utility specified by
\f3command_name\f1 could not be found.
.PP
Otherwise, the exit status of \f3command\f1 will be that of the simple
command specified by the arguments to \f3command\f1.
.SH 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).
.PP
The system default path is available using \f3getconf\f1; however, since
\f3getconf\f1 may need to have the \f3PATH\f1 set up before it can be called
itself, the following can be used:
.IP
command -p getconf _CS_PATH
.PP
There are some advantages to suppressing the special characteristics of
special built-ins on occasion. For example:
.IP
command exec > unwritable-file
.PP
will not cause a non-interactive script to abort, so that the output
status can be checked by the script.
.PP
The \f3command\f1, \f3env\f1, \f3nohup\f1, \f3time\f1 and \f3xargs\f1 utilities 
have been specified
to use exit code \f3127\f1 if an error occurs so that applications can
distinguish "failure to find a utility" from "invoked utility exited
with an error indication".  The value \f3127\f1 was chosen because it is not
commonly used for other meanings; most utilities use small values for
"normal error conditions" and the values above \f3128\f1 can be confused with
termination due to receipt of a signal. The value \f3126\f1 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 \f3126\f1 and \f3127\f1 cases. The distinction between exit
codes \f3126\f1 and \f3127\f1 is based on KornShell practice that uses \f3127\f1 when all
attempts to exec the utility fail with [\f3ENOENT\f1], and uses \f3126\f1 when any
attempt to exec the utility fails for any other reason.
.PP
Since the \f3-v\f1 and \f3-V\f1 options of \f3command\f1 produce output in relation to
the current shell execution environment, \f3command\f1 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:
.IP
(PATH=foo command -v) nohup command -v
.PP
it will not necessarily produce correct results. For example, when
called with \f3nohup\f1 or an \f3exec\f1 function, in a separate utility execution
environment, most implementations will not be able to identify aliases,
functions or special built-ins.
.PP
Two types of regular built-ins could be encountered on a system and
these are described separately by \f3command\f1. 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 \f3PATH\f1 search. So, for example, \f3command -v true\f1
might yield \f3/bin/true\f1 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
\f3PATH\f1, and so on.
.SH EXAMPLES
.TP 4
1.
Make a version of \f3cd\f1 that always prints out the new working directory
exactly once:
.IP
cd() { command cd "$@" >/dev/null pwd }
.TP 4
2. 
Start off a "secure shell script" in which the script avoids being
spoofed by its parent:
.IP
.nf
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.
#    ...
.fi
.PP
At this point, given correct permissions on the directories called by
\f3PATH\f1, 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 \f3ENV\f1 variable precedes the invocation of the script with a
user startup script. Such a script could define functions to spoof the
application.
.SH 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.
.PP
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.
.SH SEE ALSO
\f3 
sh(1), 
type(1).
\f1