diff options
Diffstat (limited to 'man-pages-posix-2003/man1p/command.1p')
| -rw-r--r-- | man-pages-posix-2003/man1p/command.1p | 489 |
1 files changed, 489 insertions, 0 deletions
diff --git a/man-pages-posix-2003/man1p/command.1p b/man-pages-posix-2003/man1p/command.1p new file mode 100644 index 0000000..15bd65d --- /dev/null +++ b/man-pages-posix-2003/man1p/command.1p @@ -0,0 +1,489 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "COMMAND" 1P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" command +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.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 . |