path: root/usr/src/man/man1/command.1

.\"
.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for
.\" permission to reproduce portions of its copyrighted documentation.
.\" Original documentation from The Open Group can be obtained online at
.\" http://www.opengroup.org/bookstore/.
.\"
.\" The Institute of Electrical and Electronics Engineers and The Open
.\" Group, have given us permission to reprint portions of their
.\" documentation.
.\"
.\" In the following statement, the phrase ``this text'' refers to portions
.\" of the system documentation.
.\"
.\" Portions of this text are reprinted and reproduced in electronic form
.\" in the SunOS Reference Manual, from IEEE Std 1003.1, 2004 Edition,
.\" Standard for Information Technology -- Portable Operating System
.\" Interface (POSIX), The Open Group Base Specifications Issue 6,
.\" Copyright (C) 2001-2004 by the Institute of Electrical and Electronics
.\" Engineers, Inc and The Open Group.  In the event of any discrepancy
.\" between these versions 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.
.\"
.\" This notice shall appear on any product containing this material.
.\"
.\" The contents of this file are subject to the terms of the
.\" Common Development and Distribution License (the "License").
.\" You may not use this file except in compliance with the License.
.\"
.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
.\" or http://www.opensolaris.org/os/licensing.
.\" See the License for the specific language governing permissions
.\" and limitations under the License.
.\"
.\" When distributing Covered Code, include this CDDL HEADER in each
.\" file and include the License file at usr/src/OPENSOLARIS.LICENSE.
.\" If applicable, add the following below this CDDL HEADER, with the
.\" fields enclosed by brackets "[]" replaced with your own identifying
.\" information: Portions Copyright [yyyy] [name of copyright owner]
.\"
.\"
.\" Copyright (c) 1992, X/Open Company Limited All Rights Reserved
.\" Portions Copyright (c) 1982-2007 AT&T Knowledge Ventures
.\" Portions Copyright (c) 2007, Sun Microsystems, Inc. All Rights Reserved
.\"
.TH COMMAND 1 "Apr 8, 2008"
.SH NAME
command \- execute a simple command
.SH SYNOPSIS
.SS "/usr/bin/command"
.LP
.nf
\fBcommand\fR [\fB-p\fR] \fIcommand_name\fR [\fIargument\fR]...
.fi

.LP
.nf
\fBcommand\fR [\fB-v\fR | \fB-V\fR] \fIcommand_name\fR
.fi

.SS "ksh93"
.LP
.nf
\fBcommand\fR [\fB-pvxV\fR] [\fIcommand_name\fR [\fIargument\fR...]]
.fi

.SH DESCRIPTION
.sp
.LP
The \fBcommand\fR utility causes the shell to treat the arguments as a simple
command, suppressing the shell function lookup.
.sp
.LP
If the \fIcommand_name\fR is the same as the name of one of the special
built-in utilities, the special properties do not occur. In every other
respect, if \fIcommand_name\fR is not the name of a function, the effect of
\fBcommand\fR (with no options) are the same as omitting \fBcommand\fR.
.sp
.LP
The \fBcommand\fR utility also provides information concerning how a command
name is interpreted by the shell. See \fB-v\fR and \fB-V\fR.
.SS "ksh93"
.sp
.LP
Without the \fB-v\fR or \fB-V\fR option, \fBcommand\fR executes
\fIcommand_name\fR with arguments specified by \fIargument\fR, suppressing the
shell function lookup that normally occurs. In addition, if \fIcommand\fR is a
special built-in command, the special properties are removed so that failures
do not cause the script that executes it to terminate.
.sp
.LP
If the \fB-v\fR or \fB-V\fR options are specified, \fBcommand\fR is equivalent
to \fBwhence\fR(1).
.SH OPTIONS
.sp
.LP
The following options are supported by \fB/usr/bin/command\fR:
.sp
.ne 2
.na
\fB\fB-p\fR\fR
.ad
.RS 6n
Performs the command search using a default value for \fBPATH\fR that is
guaranteed to find all of the standard utilities.
.RE

.sp
.ne 2
.na
\fB\fB-v\fR\fR
.ad
.RS 6n
Writes a string to standard output that indicates the path or command that is
be used by the shell, in the current shell execution environment to invoke
\fIcommand_name\fR, but does not invoke \fIcommand_name\fR.
.RS +4
.TP
.ie t \(bu
.el o
Utilities, regular built-in utilities, \fIcommand_names\fR including a slash
character, and any implementation-provided functions that are found using the
\fBPATH\fR variable is written as absolute path names.
.RE
.RS +4
.TP
.ie t \(bu
.el o
Shell functions, special built-in utilities, regular built-in utilities not
associated with a \fBPATH\fR search, and shell reserved words are written as
just their names.
.RE
.RS +4
.TP
.ie t \(bu
.el o
An alias is written as a command line that represents its alias definition.
.RE
.RS +4
.TP
.ie t \(bu
.el o
Otherwise, no output is written and the exit status reflects that the name was
not found.
.RE
.RE

.sp
.ne 2
.na
\fB\fB-V\fR\fR
.ad
.RS 6n
Writes a string to standard output that indicates how the name specified in the
\fIcommand_name\fR operand is interpreted by the shell, in the current shell
execution environment, but does not invoke \fIcommand_name\fR. Although the
format of this string is unspecified, it indicates in which of the following
categories \fIcommand_name\fR falls and include the information stated:
.RS +4
.TP
.ie t \(bu
.el o
Utilities, regular built-in utilities, and any implementation-provided
functions that are found using the \fBPATH\fR variable is identified as such
and include the absolute path name in the string.
.RE
.RS +4
.TP
.ie t \(bu
.el o
Other shell functions is identified as functions.
.RE
.RS +4
.TP
.ie t \(bu
.el o
Aliases are identified as aliases and their definitions are included in the
string.
.RE
.RS +4
.TP
.ie t \(bu
.el o
Special built-in utilities are identified as special built-in utilities.
.RE
.RS +4
.TP
.ie t \(bu
.el o
Regular built-in utilities not associated with a \fBPATH\fR search is
identified as regular built-in utilities.
.RE
.RS +4
.TP
.ie t \(bu
.el o
Shell reserved words are identified as reserved words.
.RE
.RE

.SS "ksh93"
.sp
.LP
The following options are supported by \fBksh93\fR \fBcommand\fR:
.sp
.ne 2
.na
\fB\fB-p\fR\fR
.ad
.RS 6n
Causes a default path to be searched rather than the one defined by the value
of \fBPATH\fR.
.RE

.sp
.ne 2
.na
\fB\fB-v\fR\fR
.ad
.RS 6n
Equivalent to:
.sp
.in +2
.nf
whence \fIcommand\fR [\fIargument\fR ...]
.fi
.in -2
.sp

.RE

.sp
.ne 2
.na
\fB\fB-V\fR\fR
.ad
.RS 6n
Equivalent to:
.sp
.in +2
.nf
whence -v \fIcommand\fR [\fIargument\fR ...]
.fi
.in -2
.sp

.RE

.sp
.ne 2
.na
\fB\fB-x\fR\fR
.ad
.RS 6n
If command fails because there are too many arguments, it is invoked multiple
times with a subset of the arguments on each invocation. Arguments that occur
prior to the first word that expand to multiple arguments and arguments that
occur after the last word that expands to multiple arguments are passed on each
invocation. The exit status is the maximum invocation exit status.
.RE

.SH OPERANDS
.sp
.LP
The following operands are supported:
.sp
.ne 2
.na
\fB\fIargument\fR\fR
.ad
.RS 16n
One of the strings treated as an argument to \fIcommand_name\fR.
.RE

.sp
.ne 2
.na
\fB\fIcommand_name\fR\fR
.ad
.RS 16n
The name of a utility or a special built-in utility.
.RE

.SH EXAMPLES
.LP
\fBExample 1 \fRMaking a Version of \fBcd\fR That Always Prints Out the New
Working Directory
.sp
.LP
The following example takes a version of \fBcd\fR that always prints out the
new working directory exactly once:

.sp
.in +2
.nf
cd() {
	command cd "$@" >/dev/null
	pwd
}
.fi
.in -2
.sp

.LP
\fBExample 2 \fRStarting Off a \fBsecure shell script\fR in Which the Script
Avoids Being Spoofed by Its Parent
.sp
.LP
The following example starts off a \fBsecure shell script\fR in which the
script avoids being spoofed by its parent:

.sp
.in +2
.nf
IFS='
\&'
#	The preceding value should be <space><tab><newline>.
#	Set IFS to its default value.
\eunalias -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
.in -2
.sp

.sp
.LP
At this point, given correct permissions on the directories called by
\fBPATH\fR, 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 can be present that would allow user functions to
exist when it is invoked. This capability is not specified by this document,
but it is not prohibited as an extension. For example, the \fBENV\fR variable
precedes the invocation of the script with a user startup script. Such a script
could define functions to spoof the application.

.SH ENVIRONMENT VARIABLES
.sp
.LP
See \fBenviron\fR(5) for descriptions of the following environment variables
that affect the execution of \fBcommand\fR: \fBLANG\fR, \fBLC_ALL\fR,
\fBLC_CTYPE\fR, \fBLC_MESSAGES\fR, and \fBNLSPATH\fR.
.sp
.ne 2
.na
\fB\fBPATH\fR\fR
.ad
.RS 8n
Determine the search path used during the command search, except as described
under the \fB-p\fR option.
.RE

.SH EXIT STATUS
.SS "/usr/bin/command"
.sp
.LP
When the \fB-v\fR or \fB-V\fR options are specified, the following exit values
are returned:
.sp
.ne 2
.na
\fB\fB0\fR\fR
.ad
.RS 6n
Successful completion.
.RE

.sp
.ne 2
.na
\fB\fB>0\fR\fR
.ad
.RS 6n
The \fIcommand_name\fR could not be found or an error occurred.
.RE

.sp
.LP
Otherwise, the following exit values are returned:
.sp
.ne 2
.na
\fB\fB126\fR\fR
.ad
.RS 7n
The utility specified by \fIcommand_name\fR was found but could not be invoked.
.RE

.sp
.ne 2
.na
\fB\fB127\fR\fR
.ad
.RS 7n
An error occurred in the \fBcommand\fR utility or the utility specified by
\fIcommand_name\fR could not be found.
.RE

.sp
.LP
Otherwise, the exit status of \fBcommand\fR is that of the simple command
specified by the arguments to \fBcommand\fR.
.SS "ksh93"
.sp
.LP
If \fIcommand\fR is invoked, the exit status of \fBcommand\fR is that of
\fIcommand\fR. Otherwise, it is one of the following:
.sp
.ne 2
.na
\fB\fB0\fR\fR
.ad
.RS 7n
\fIcommand_name\fR completed successfully.
.RE

.sp
.ne 2
.na
\fB\fB>0\fR\fR
.ad
.RS 7n
\fB-v\fR or \fB-V\fR has been specified and an error occurred.
.RE

.sp
.ne 2
.na
\fB\fB126\fR\fR
.ad
.RS 7n
\fIcommand_name\fR was found but could not be invoked.
.RE

.sp
.ne 2
.na
\fB\fB127\fR\fR
.ad
.RS 7n
\fIcommand_name\fR could not be found.
.RE

.SH ATTRIBUTES
.sp
.LP
See \fBattributes\fR(5) for descriptions of the following attributes:
.SS "/usr/bin/command"
.sp

.sp
.TS
box;
c | c
l | l .
ATTRIBUTE TYPE	ATTRIBUTE VALUE
_
Interface Stability	Committed
_
Standard	See \fBstandards\fR(5).
.TE

.SS "ksh93"
.sp

.sp
.TS
box;
c | c
l | l .
ATTRIBUTE TYPE	ATTRIBUTE VALUE
_
Interface Stability	Uncommitted
.TE

.SH SEE ALSO
.sp
.LP
\fBksh93\fR(1), \fBsh\fR(1), \fBtype\fR(1), \fBwhence\fR(1),
\fBattributes\fR(5), \fBenviron\fR(5), \fBstandards\fR(5)