diff options
Diffstat (limited to 'man-pages-posix-2017/man1p/command.1p')
| -rw-r--r-- | man-pages-posix-2017/man1p/command.1p | 562 |
1 files changed, 562 insertions, 0 deletions
diff --git a/man-pages-posix-2017/man1p/command.1p b/man-pages-posix-2017/man1p/command.1p new file mode 100644 index 0000000..1246443 --- /dev/null +++ b/man-pages-posix-2017/man1p/command.1p @@ -0,0 +1,562 @@ +'\" et +.TH COMMAND "1P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.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 +\(em execute a simple command +.SH SYNOPSIS +.LP +.nf +command \fB[\fR-p\fB] \fIcommand_name \fB[\fIargument\fR...\fB]\fR +.P +command \fB[\fR-p\fB][\fR-v|-V\fB] \fIcommand_name\fR +.fi +.SH DESCRIPTION +The +.IR command +utility shall cause the shell to treat the arguments as a simple +command, suppressing the shell function lookup that is described in +.IR "Section 2.9.1.1" ", " "Command Search and Execution", +item 1b. +.P +If the +.IR command_name +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 +.IR "Section 2.14" ", " "Special Built-In Utilities" +shall not occur. In every other respect, if +.IR command_name +is not the name of a function, the effect of +.IR command +(with no options) shall be the same as omitting +.IR command . +.P +When the +.BR \-v +or +.BR \-V +option is used, the +.IR command +utility shall provide information concerning how a command name +is interpreted by the shell. +.SH OPTIONS +The +.IR command +utility shall conform to the Base Definitions volume of POSIX.1\(hy2017, +.IR "Section 12.2" ", " "Utility Syntax Guidelines". +.P +The following options shall be supported: +.IP "\fB\-p\fP" 10 +Perform the command search using a default value for +.IR PATH +that is guaranteed to find all of the standard utilities. +.IP "\fB\-v\fP" 10 +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 +.IR "Section 2.12" ", " "Shell Execution Environment"), +to invoke +.IR command_name , +but do not invoke +.IR command_name . +.RS 10 +.IP " *" 4 +Utilities, regular built-in utilities, +.IR command_name s +including a +<slash> +character, and any implementation-defined functions that are found +using the +.IR PATH +variable (as described in +.IR "Section 2.9.1.1" ", " "Command Search and Execution"), +shall be written as absolute pathnames. +.IP " *" 4 +Shell functions, special built-in utilities, regular built-in utilities +not associated with a +.IR PATH +search, and shell reserved words shall be written as just their names. +.IP " *" 4 +An alias shall be written as a command line that represents its alias +definition. +.IP " *" 4 +Otherwise, no output shall be written and the exit status shall reflect +that the name was not found. +.RE +.IP "\fB\-V\fP" 10 +Write a string to standard output that indicates how the name given in the +.IR command_name +operand will be interpreted by the shell, in the current shell +execution environment (see +.IR "Section 2.12" ", " "Shell Execution Environment"), +but do not invoke +.IR command_name . +Although the format of this string is unspecified, it shall indicate in +which of the following categories +.IR command_name +falls and shall include the information stated: +.RS 10 +.IP " *" 4 +Utilities, regular built-in utilities, and any implementation-defined +functions that are found using the +.IR PATH +variable (as described in +.IR "Section 2.9.1.1" ", " "Command Search and Execution"), +shall be identified as such and include the absolute pathname in the +string. +.IP " *" 4 +Other shell functions shall be identified as functions. +.IP " *" 4 +Aliases shall be identified as aliases and their definitions +included in the string. +.IP " *" 4 +Special built-in utilities shall be identified as special built-in +utilities. +.IP " *" 4 +Regular built-in utilities not associated with a +.IR PATH +search shall be identified as regular built-in utilities. (The term +``regular'' need not be used.) +.IP " *" 4 +Shell reserved words shall be identified as reserved words. +.RE +.SH OPERANDS +The following operands shall be supported: +.IP "\fIargument\fR" 10 +One of the strings treated as an argument to +.IR command_name . +.IP "\fIcommand_name\fR" 10 +.br +The name of a utility or a special built-in utility. +.SH STDIN +Not used. +.SH "INPUT FILES" +None. +.SH "ENVIRONMENT VARIABLES" +The following environment variables shall affect the execution of +.IR command : +.IP "\fILANG\fP" 10 +Provide a default value for the internationalization variables that are +unset or null. (See the Base Definitions volume of POSIX.1\(hy2017, +.IR "Section 8.2" ", " "Internationalization Variables" +for the precedence of internationalization variables used to determine +the values of locale categories.) +.IP "\fILC_ALL\fP" 10 +If set to a non-empty string value, override the values of all the +other internationalization variables. +.IP "\fILC_CTYPE\fP" 10 +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). +.IP "\fILC_MESSAGES\fP" 10 +.br +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. +.IP "\fINLSPATH\fP" 10 +Determine the location of message catalogs for the processing of +.IR LC_MESSAGES . +.IP "\fIPATH\fP" 10 +Determine the search path used during the command search described in +.IR "Section 2.9.1.1" ", " "Command Search and Execution", +except as described under the +.BR \-p +option. +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +When the +.BR \-v +option is specified, standard output shall be formatted as: +.sp +.RS 4 +.nf + +"%s\en", <\fIpathname or command\fR> +.fi +.P +.RE +.P +When the +.BR \-V +option is specified, standard output shall be formatted as: +.sp +.RS 4 +.nf + +"%s\en", <\fIunspecified\fR> +.fi +.P +.RE +.SH STDERR +The standard error shall be used only for diagnostic messages. +.SH "OUTPUT FILES" +None. +.SH "EXTENDED DESCRIPTION" +None. +.SH "EXIT STATUS" +When the +.BR \-v +or +.BR \-V +options are specified, the following exit values shall be returned: +.IP "\00" 6 +Successful completion. +.IP >0 6 +The +.IR command_name +could not be found or an error occurred. +.P +Otherwise, the following exit values shall be returned: +.IP 126 6 +The utility specified by +.IR command_name +was found but could not be invoked. +.IP 127 6 +An error occurred in the +.IR command +utility or the utility specified by +.IR command_name +could not be found. +.P +Otherwise, the exit status of +.IR command +shall be that of the simple command specified by the arguments to +.IR command . +.SH "CONSEQUENCES OF ERRORS" +Default. +.LP +.IR "The following sections are informative." +.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). +.P +The system default path is available using +.IR getconf ; +however, since +.IR getconf +may need to have the +.IR PATH +set up before it can be called itself, the following can be used: +.sp +.RS 4 +.nf + +command -p getconf PATH +.fi +.P +.RE +.P +There are some advantages to suppressing the special characteristics of +special built-ins on occasion. For example: +.sp +.RS 4 +.nf + +command exec > \fIunwritable-file\fR +.fi +.P +.RE +.P +does not cause a non-interactive script to abort, so that the output +status can be checked by the script. +.P +The +.IR command , +.IR env , +.IR nohup , +.IR time , +and +.IR 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 +.IR exec +the utility fail with +.BR [ENOENT] , +and uses 126 when any attempt to +.IR exec +the utility fails for any other reason. +.P +Since the +.BR \-v +and +.BR \-V +options of +.IR command +produce output in relation to the current shell execution environment, +.IR 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: +.sp +.RS 4 +.nf + +(PATH=foo command -v) + nohup command -v +.fi +.P +.RE +.P +it does not necessarily produce correct results. For example, when +called with +.IR nohup +or an +.IR exec +function, in a separate utility execution environment, most +implementations are not able to identify aliases, functions, or special +built-ins. +.P +Two types of regular built-ins could be encountered on a system and +these are described separately by +.IR command . +The description of command search in +.IR "Section 2.9.1.1" ", " "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 +.IR PATH +search. So, for example, +.IR command +.BR \-v +.IR true +might yield +.BR /bin/true +or some similar pathname. Other implementation-defined utilities that +are not defined by this volume of POSIX.1\(hy2017 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 +.IR exec ing +them, using them with +.IR nohup , +overriding them with a different +.IR PATH , +and so on. +.SH EXAMPLES +.IP " 1." 4 +Make a version of +.IR cd +that always prints out the new working directory exactly once: +.RS 4 +.sp +.RS 4 +.nf + +cd() { + command cd "$@" >/dev/null + pwd +} +.fi +.P +.RE +.RE +.IP " 2." 4 +Start off a ``secure shell script'' in which the script avoids +being spoofed by its parent: +.RS 4 +.sp +.RS 4 +.nf + +IFS=\(aq +\&\(aq +# The preceding value should be <space><tab><newline>. +# Set IFS to its default value. +.P +\eunalias -a +# Unset all possible aliases. +# Note that unalias is escaped to prevent an alias +# being used for unalias. +.P +unset -f command +# Ensure command is not a user function. +.P +PATH="$(command -p getconf PATH):$PATH" +# Put on a reliable PATH prefix. +.P +# ... +.fi +.P +.RE +.P +At this point, given correct permissions on the directories called by +.IR 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 volume of POSIX.1\(hy2017, but it is not prohibited as an extension. For example, the +.IR ENV +variable precedes the invocation of the script with a user start-up +script. Such a script could define functions to spoof the application. +.RE +.SH RATIONALE +Since +.IR command +is a regular built-in utility it is always found prior to the +.IR PATH +search. +.P +There is nothing in the description of +.IR command +that implies the command line is parsed any differently from that of +any other simple command. For example: +.sp +.RS 4 +.nf + +command a | b ; c +.fi +.P +.RE +.P +is not parsed in any special way that causes +.BR '|' +or +.BR ';' +to be treated other than a pipe operator or +<semicolon> +or that prevents function lookup on +.BR b +or +.BR c . +.P +The +.IR command +utility is somewhat similar to the Eighth Edition shell +.IR builtin +command, but since +.IR command +also goes to the file system to search for utilities, the name +.IR builtin +would not be intuitive. +.P +The +.IR command +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 " *" 4 +The removal of exportable functions made the special precedence of a +special built-in unnecessary. +.IP " *" 4 +A special built-in has special properties (see +.IR "Section 2.14" ", " "Special Built-In Utilities") +that were inappropriate for invoking other utilities. For example, two +commands such as: +.RS 4 +.sp +.RS 4 +.nf + +date > \fIunwritable-file\fR +.P +command date > \fIunwritable-file\fR +.fi +.P +.RE +.P +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. +.RE +.P +The +.BR \-p +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 +.IR exec +functions (as defined in the System Interfaces volume of POSIX.1\(hy2017) when +.IR PATH +is unset. At the very least, this feature is required to allow the +script to access the correct version of +.IR getconf +so that the value of the default path can be accurately retrieved. +.P +The +.IR command +.BR \-v +and +.BR \-V +options were added to satisfy requirements from users that are +currently accomplished by three different historical utilities: +.IR type +in the System V shell, +.IR whence +in the KornShell, and +.IR which +in the C shell. Since there is no historical agreement on how and what +to accomplish here, the POSIX +.IR command +utility was enhanced and the historical utilities were left unmodified. +The C shell +.IR which +merely conducts a path search. The KornShell +.IR whence +is more elaborate\(emin addition to the categories required by POSIX, +it also reports on tracked aliases, exported aliases, and undefined +functions. +.P +The output format of +.BR \-V +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 +.BR \-v +to differentiate between various types of commands, but the additional +information that may be emitted by the more verbose +.BR \-V +is not needed and should not be arbitrarily constrained in its +verbosity or localization for application parsing reasons. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "Section 2.9.1.1" ", " "Command Search and Execution", +.IR "Section 2.12" ", " "Shell Execution Environment", +.IR "Section 2.14" ", " "Special Built-In Utilities", +.IR "\fIsh\fR\^", +.IR "\fItype\fR\^" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "Chapter 8" ", " "Environment Variables", +.IR "Section 12.2" ", " "Utility Syntax Guidelines" +.P +The System Interfaces volume of POSIX.1\(hy2017, +.IR "\fIexec\fR\^" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 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 . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . |