1COMMAND(1P)                POSIX Programmer's Manual               COMMAND(1P)
2
3
4

PROLOG

6       This  manual  page is part of the POSIX Programmer's Manual.  The Linux
7       implementation of this interface may differ (consult the  corresponding
8       Linux  manual page for details of Linux behavior), or the interface may
9       not be implemented on Linux.
10

NAME

12       command — execute a simple command
13

SYNOPSIS

15       command [-p] command_name [argument...]
16
17       command [-p][-v|-V] command_name
18

DESCRIPTION

20       The command utility shall cause the shell to treat the arguments  as  a
21       simple command, suppressing the shell function lookup that is described
22       in Section 2.9.1.1, Command Search and Execution, item 1b.
23
24       If the command_name is the same as the  name  of  one  of  the  special
25       built-in  utilities,  the  special properties in the enumerated list at
26       the beginning of Section 2.14, Special  Built-In  Utilities  shall  not
27       occur.  In  every  other  respect, if command_name is not the name of a
28       function, the effect of command (with no options) shall be the same  as
29       omitting command.
30
31       When  the  -v  or  -V option is used, the command utility shall provide
32       information concerning how a command name is interpreted by the shell.
33

OPTIONS

35       The command utility shall conform to the  Base  Definitions  volume  of
36       POSIX.1‐2017, Section 12.2, Utility Syntax Guidelines.
37
38       The following options shall be supported:
39
40       -p        Perform  the  command  search  using a default value for PATH
41                 that is guaranteed to find all of the standard utilities.
42
43       -v        Write a string to standard output that indicates the pathname
44                 or  command  that  will  be used by the shell, in the current
45                 shell execution environment (see Section 2.12,  Shell  Execu‐
46                 tion  Environment), to invoke command_name, but do not invoke
47                 command_name.
48
49                  *  Utilities,  regular  built-in  utilities,   command_names
50                     including  a  <slash>  character, and any implementation-
51                     defined functions that are found using the PATH  variable
52                     (as described in Section 2.9.1.1, Command Search and Exe‐
53                     cution), shall be written as absolute pathnames.
54
55                  *  Shell  functions,  special  built-in  utilities,  regular
56                     built-in utilities not associated with a PATH search, and
57                     shell reserved words  shall  be  written  as  just  their
58                     names.
59
60                  *  An  alias  shall be written as a command line that repre‐
61                     sents its alias definition.
62
63                  *  Otherwise, no output shall be written and the exit status
64                     shall reflect that the name was not found.
65
66       -V        Write a string to standard output that indicates how the name
67                 given in the command_name operand will be interpreted by  the
68                 shell,  in  the current shell execution environment (see Sec‐
69                 tion 2.12, Shell Execution Environment), but  do  not  invoke
70                 command_name.  Although the format of this string is unspeci‐
71                 fied, it shall indicate in which of the following  categories
72                 command_name falls and shall include the information stated:
73
74                  *  Utilities,  regular built-in utilities, and any implemen‐
75                     tation-defined functions that are found  using  the  PATH
76                     variable (as described in Section 2.9.1.1, Command Search
77                     and Execution), shall be identified as such  and  include
78                     the absolute pathname in the string.
79
80                  *  Other shell functions shall be identified as functions.
81
82                  *  Aliases  shall be identified as aliases and their defini‐
83                     tions included in the string.
84
85                  *  Special built-in utilities shall be identified as special
86                     built-in utilities.
87
88                  *  Regular  built-in  utilities  not  associated with a PATH
89                     search shall be identified as regular built-in utilities.
90                     (The term ``regular'' need not be used.)
91
92                  *  Shell  reserved  words  shall  be  identified as reserved
93                     words.
94

OPERANDS

96       The following operands shall be supported:
97
98       argument  One of the strings treated as an argument to command_name.
99
100       command_name
101                 The name of a utility or a special built-in utility.
102

STDIN

104       Not used.
105

INPUT FILES

107       None.
108

ENVIRONMENT VARIABLES

110       The following environment variables shall affect the execution of  com‐
111       mand:
112
113       LANG      Provide  a  default  value for the internationalization vari‐
114                 ables that are unset or null. (See the Base Definitions  vol‐
115                 ume  of POSIX.1‐2017, Section 8.2, Internationalization Vari‐
116                 ables for the precedence  of  internationalization  variables
117                 used to determine the values of locale categories.)
118
119       LC_ALL    If  set  to  a non-empty string value, override the values of
120                 all the other internationalization variables.
121
122       LC_CTYPE  Determine the locale for the interpretation of  sequences  of
123                 bytes of text data as characters (for example, single-byte as
124                 opposed to multi-byte characters in arguments).
125
126       LC_MESSAGES
127                 Determine the locale that should be used to affect the format
128                 and contents of diagnostic messages written to standard error
129                 and informative messages written to standard output.
130
131       NLSPATH   Determine the location of message catalogs for the processing
132                 of LC_MESSAGES.
133
134       PATH      Determine  the  search  path  used  during the command search
135                 described in Section 2.9.1.1, Command Search  and  Execution,
136                 except as described under the -p option.
137

ASYNCHRONOUS EVENTS

139       Default.
140

STDOUT

142       When the -v option is specified, standard output shall be formatted as:
143
144
145           "%s\n", <pathname or command>
146
147       When the -V option is specified, standard output shall be formatted as:
148
149
150           "%s\n", <unspecified>
151

STDERR

153       The standard error shall be used only for diagnostic messages.
154

OUTPUT FILES

156       None.
157

EXTENDED DESCRIPTION

159       None.
160

EXIT STATUS

162       When  the  -v  or  -V  options are specified, the following exit values
163       shall be returned:
164
165        0    Successful completion.
166
167       >0    The command_name could not be found or an error occurred.
168
169       Otherwise, the following exit values shall be returned:
170
171       126   The utility specified by command_name was found but could not  be
172             invoked.
173
174       127   An error occurred in the command utility or the utility specified
175             by command_name could not be found.
176
177       Otherwise, the exit status of command shall be that of the simple  com‐
178       mand specified by the arguments to command.
179

CONSEQUENCES OF ERRORS

181       Default.
182
183       The following sections are informative.
184

APPLICATION USAGE

186       The  order  for  command  search  allows  functions to override regular
187       built-ins and path searches. This utility is necessary to  allow  func‐
188       tions that have the same name as a utility to call the utility (instead
189       of a recursive call to the function).
190
191       The system default path is available using getconf; however, since get‐
192       conf  may  need to have the PATH set up before it can be called itself,
193       the following can be used:
194
195
196           command -p getconf PATH
197
198       There are some advantages to suppressing the special characteristics of
199       special built-ins on occasion. For example:
200
201
202           command exec > unwritable-file
203
204       does  not  cause  a non-interactive script to abort, so that the output
205       status can be checked by the script.
206
207       The command, env, nohup, time, and xargs utilities have been  specified
208       to  use  exit code 127 if an error occurs so that applications can dis‐
209       tinguish ``failure to find a utility'' from  ``invoked  utility  exited
210       with  an error indication''. The value 127 was chosen because it is not
211       commonly used for other meanings; most utilities use small  values  for
212       ``normal  error  conditions''  and the values above 128 can be confused
213       with termination due to receipt of a signal. The value 126  was  chosen
214       in  a  similar  manner to indicate that the utility could be found, but
215       not invoked. Some scripts produce meaningful error messages differenti‐
216       ating the 126 and 127 cases. The distinction between exit codes 126 and
217       127 is based on KornShell practice that uses 127 when all  attempts  to
218       exec  the  utility fail with [ENOENT], and uses 126 when any attempt to
219       exec the utility fails for any other reason.
220
221       Since the -v and -V options of command produce output  in  relation  to
222       the  current shell execution environment, command is generally provided
223       as a shell regular built-in. If it is called in a subshell or  separate
224       utility execution environment, such as one of the following:
225
226
227           (PATH=foo command -v)
228            nohup command -v
229
230       it  does  not  necessarily  produce  correct results. For example, when
231       called with nohup or an exec function, in a separate utility  execution
232       environment,  most  implementations  are  not able to identify aliases,
233       functions, or special built-ins.
234
235       Two types of regular built-ins could be encountered  on  a  system  and
236       these  are described separately by command.  The description of command
237       search in Section 2.9.1.1, Command Search and Execution  allows  for  a
238       standard  utility to be implemented as a regular built-in as long as it
239       is found in the appropriate place in a PATH search.  So,  for  example,
240       command  -v  true might yield /bin/true or some similar pathname. Other
241       implementation-defined utilities that are not defined by this volume of
242       POSIX.1‐2017 might exist only as built-ins and have no pathname associ‐
243       ated with them. These produce output identified as (regular) built-ins.
244       Applications  encountering these are not able to count on execing them,
245       using them with nohup, overriding them with a different  PATH,  and  so
246       on.
247

EXAMPLES

249        1. Make  a version of cd that always prints out the new working direc‐
250           tory exactly once:
251
252
253               cd() {
254                   command cd "$@" >/dev/null
255                   pwd
256               }
257
258        2. Start off a ``secure shell script''  in  which  the  script  avoids
259           being spoofed by its parent:
260
261
262               IFS='
263               '
264               #    The preceding value should be <space><tab><newline>.
265               #    Set IFS to its default value.
266
267               \unalias -a
268               #    Unset all possible aliases.
269               #    Note that unalias is escaped to prevent an alias
270               #    being used for unalias.
271
272               unset -f command
273               #    Ensure command is not a user function.
274
275               PATH="$(command -p getconf PATH):$PATH"
276               #    Put on a reliable PATH prefix.
277
278               #    ...
279
280           At  this point, given correct permissions on the directories called
281           by PATH, the script has the ability to ensure that any  utility  it
282           calls  is  the  intended  one. It is being very cautious because it
283           assumes that implementation extensions may be  present  that  would
284           allow  user  functions to exist when it is invoked; this capability
285           is not specified by this volume of POSIX.1‐2017, but it is not pro‐
286           hibited as an extension. For example, the ENV variable precedes the
287           invocation of the script with a user start-up script. Such a script
288           could define functions to spoof the application.
289

RATIONALE

291       Since command is a regular built-in utility it is always found prior to
292       the PATH search.
293
294       There is nothing in the description of command that implies the command
295       line  is  parsed any differently from that of any other simple command.
296       For example:
297
298
299           command a | b ; c
300
301       is not parsed in any special way that causes '|' or ';' to  be  treated
302       other  than  a  pipe  operator or <semicolon> or that prevents function
303       lookup on b or c.
304
305       The command utility is somewhat similar to  the  Eighth  Edition  shell
306       builtin  command,  but  since  command  also goes to the file system to
307       search for utilities, the name builtin would not be intuitive.
308
309       The command utility is most likely to be provided as a  regular  built-
310       in. It is not listed as a special built-in for the following reasons:
311
312        *  The  removal of exportable functions made the special precedence of
313           a special built-in unnecessary.
314
315        *  A special built-in has special properties (see Section  2.14,  Spe‐
316           cial Built-In Utilities) that were inappropriate for invoking other
317           utilities. For example, two commands such as:
318
319
320               date > unwritable-file
321
322               command date > unwritable-file
323
324           would have entirely different results; in a non-interactive script,
325           the  former  would continue to execute the next command, the latter
326           would abort. Introducing this semantic difference along  with  sup‐
327           pressing functions was seen to be non-intuitive.
328
329       The  -p  option  is present because it is useful to be able to ensure a
330       safe path search that finds all the  standard  utilities.  This  search
331       might  not  be identical to the one that occurs through one of the exec
332       functions (as defined in the System Interfaces volume of  POSIX.1‐2017)
333       when  PATH  is  unset.  At  the very least, this feature is required to
334       allow the script to access the correct version of getconf so  that  the
335       value of the default path can be accurately retrieved.
336
337       The  command  -v and -V options were added to satisfy requirements from
338       users that are currently accomplished  by  three  different  historical
339       utilities:  type  in  the  System V shell, whence in the KornShell, and
340       which in the C shell. Since there is no historical agreement on how and
341       what to accomplish here, the POSIX command utility was enhanced and the
342       historical utilities were left unmodified.  The C  shell  which  merely
343       conducts a path search. The KornShell whence is more elaborate—in addi‐
344       tion to the categories required by POSIX, it also  reports  on  tracked
345       aliases, exported aliases, and undefined functions.
346
347       The output format of -V was left mostly unspecified because human users
348       are its only audience.  Applications should  not  be  written  to  care
349       about  this information; they can use the output of -v to differentiate
350       between various types of commands, but the additional information  that
351       may  be  emitted by the more verbose -V is not needed and should not be
352       arbitrarily constrained in its verbosity or localization  for  applica‐
353       tion parsing reasons.
354

FUTURE DIRECTIONS

356       None.
357

SEE ALSO

359       Section 2.9.1.1, Command Search and Execution, Section 2.12, Shell Exe‐
360       cution Environment, Section 2.14, Special Built-In Utilities, sh, type
361
362       The Base Definitions volume of  POSIX.1‐2017,  Chapter  8,  Environment
363       Variables, Section 12.2, Utility Syntax Guidelines
364
365       The System Interfaces volume of POSIX.1‐2017, exec
366
368       Portions  of  this text are reprinted and reproduced in electronic form
369       from IEEE Std 1003.1-2017, Standard for Information Technology --  Por‐
370       table  Operating System Interface (POSIX), The Open Group Base Specifi‐
371       cations Issue 7, 2018 Edition, Copyright (C) 2018 by the  Institute  of
372       Electrical  and  Electronics Engineers, Inc and The Open Group.  In the
373       event of any discrepancy between this version and the original IEEE and
374       The  Open Group Standard, the original IEEE and The Open Group Standard
375       is the referee document. The original Standard can be  obtained  online
376       at http://www.opengroup.org/unix/online.html .
377
378       Any  typographical  or  formatting  errors that appear in this page are
379       most likely to have been introduced during the conversion of the source
380       files  to  man page format. To report such errors, see https://www.ker
381       nel.org/doc/man-pages/reporting_bugs.html .
382
383
384
385IEEE/The Open Group                  2017                          COMMAND(1P)
Impressum