logo

oasis-root

Compiled tree of Oasis Linux based on own branch at <https://hacktivis.me/git/oasis/> git clone https://anongit.hacktivis.me/git/oasis-root.git

command.1p (15559B)


  1. '\" et
  2. .TH COMMAND "1P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual"
  3. .\"
  4. .SH PROLOG
  5. This manual page is part of the POSIX Programmer's Manual.
  6. The Linux implementation of this interface may differ (consult
  7. the corresponding Linux manual page for details of Linux behavior),
  8. or the interface may not be implemented on Linux.
  9. .\"
  10. .SH NAME
  11. command
  12. \(em execute a simple command
  13. .SH SYNOPSIS
  14. .LP
  15. .nf
  16. command \fB[\fR-p\fB] \fIcommand_name \fB[\fIargument\fR...\fB]\fR
  17. .P
  18. command \fB[\fR-p\fB][\fR-v|-V\fB] \fIcommand_name\fR
  19. .fi
  20. .SH DESCRIPTION
  21. The
  22. .IR command
  23. utility shall cause the shell to treat the arguments as a simple
  24. command, suppressing the shell function lookup that is described in
  25. .IR "Section 2.9.1.1" ", " "Command Search and Execution",
  26. item 1b.
  27. .P
  28. If the
  29. .IR command_name
  30. is the same as the name of one of the special built-in utilities, the
  31. special properties in the enumerated list at the beginning of
  32. .IR "Section 2.14" ", " "Special Built-In Utilities"
  33. shall not occur. In every other respect, if
  34. .IR command_name
  35. is not the name of a function, the effect of
  36. .IR command
  37. (with no options) shall be the same as omitting
  38. .IR command .
  39. .P
  40. When the
  41. .BR \-v
  42. or
  43. .BR \-V
  44. option is used, the
  45. .IR command
  46. utility shall provide information concerning how a command name
  47. is interpreted by the shell.
  48. .SH OPTIONS
  49. The
  50. .IR command
  51. utility shall conform to the Base Definitions volume of POSIX.1\(hy2017,
  52. .IR "Section 12.2" ", " "Utility Syntax Guidelines".
  53. .P
  54. The following options shall be supported:
  55. .IP "\fB\-p\fP" 10
  56. Perform the command search using a default value for
  57. .IR PATH
  58. that is guaranteed to find all of the standard utilities.
  59. .IP "\fB\-v\fP" 10
  60. Write a string to standard output that indicates the pathname or command
  61. that will be used by the shell, in the current shell execution environment
  62. (see
  63. .IR "Section 2.12" ", " "Shell Execution Environment"),
  64. to invoke
  65. .IR command_name ,
  66. but do not invoke
  67. .IR command_name .
  68. .RS 10
  69. .IP " *" 4
  70. Utilities, regular built-in utilities,
  71. .IR command_name s
  72. including a
  73. <slash>
  74. character, and any implementation-defined functions that are found
  75. using the
  76. .IR PATH
  77. variable (as described in
  78. .IR "Section 2.9.1.1" ", " "Command Search and Execution"),
  79. shall be written as absolute pathnames.
  80. .IP " *" 4
  81. Shell functions, special built-in utilities, regular built-in utilities
  82. not associated with a
  83. .IR PATH
  84. search, and shell reserved words shall be written as just their names.
  85. .IP " *" 4
  86. An alias shall be written as a command line that represents its alias
  87. definition.
  88. .IP " *" 4
  89. Otherwise, no output shall be written and the exit status shall reflect
  90. that the name was not found.
  91. .RE
  92. .IP "\fB\-V\fP" 10
  93. Write a string to standard output that indicates how the name given in the
  94. .IR command_name
  95. operand will be interpreted by the shell, in the current shell
  96. execution environment (see
  97. .IR "Section 2.12" ", " "Shell Execution Environment"),
  98. but do not invoke
  99. .IR command_name .
  100. Although the format of this string is unspecified, it shall indicate in
  101. which of the following categories
  102. .IR command_name
  103. falls and shall include the information stated:
  104. .RS 10
  105. .IP " *" 4
  106. Utilities, regular built-in utilities, and any implementation-defined
  107. functions that are found using the
  108. .IR PATH
  109. variable (as described in
  110. .IR "Section 2.9.1.1" ", " "Command Search and Execution"),
  111. shall be identified as such and include the absolute pathname in the
  112. string.
  113. .IP " *" 4
  114. Other shell functions shall be identified as functions.
  115. .IP " *" 4
  116. Aliases shall be identified as aliases and their definitions
  117. included in the string.
  118. .IP " *" 4
  119. Special built-in utilities shall be identified as special built-in
  120. utilities.
  121. .IP " *" 4
  122. Regular built-in utilities not associated with a
  123. .IR PATH
  124. search shall be identified as regular built-in utilities. (The term
  125. ``regular'' need not be used.)
  126. .IP " *" 4
  127. Shell reserved words shall be identified as reserved words.
  128. .RE
  129. .SH OPERANDS
  130. The following operands shall be supported:
  131. .IP "\fIargument\fR" 10
  132. One of the strings treated as an argument to
  133. .IR command_name .
  134. .IP "\fIcommand_name\fR" 10
  135. .br
  136. The name of a utility or a special built-in utility.
  137. .SH STDIN
  138. Not used.
  139. .SH "INPUT FILES"
  140. None.
  141. .SH "ENVIRONMENT VARIABLES"
  142. The following environment variables shall affect the execution of
  143. .IR command :
  144. .IP "\fILANG\fP" 10
  145. Provide a default value for the internationalization variables that are
  146. unset or null. (See the Base Definitions volume of POSIX.1\(hy2017,
  147. .IR "Section 8.2" ", " "Internationalization Variables"
  148. for the precedence of internationalization variables used to determine
  149. the values of locale categories.)
  150. .IP "\fILC_ALL\fP" 10
  151. If set to a non-empty string value, override the values of all the
  152. other internationalization variables.
  153. .IP "\fILC_CTYPE\fP" 10
  154. Determine the locale for the interpretation of sequences of bytes of
  155. text data as characters (for example, single-byte as opposed to
  156. multi-byte characters in arguments).
  157. .IP "\fILC_MESSAGES\fP" 10
  158. .br
  159. Determine the locale that should be used to affect the format and
  160. contents of diagnostic messages written to standard error and
  161. informative messages written to standard output.
  162. .IP "\fINLSPATH\fP" 10
  163. Determine the location of message catalogs for the processing of
  164. .IR LC_MESSAGES .
  165. .IP "\fIPATH\fP" 10
  166. Determine the search path used during the command search described in
  167. .IR "Section 2.9.1.1" ", " "Command Search and Execution",
  168. except as described under the
  169. .BR \-p
  170. option.
  171. .SH "ASYNCHRONOUS EVENTS"
  172. Default.
  173. .SH STDOUT
  174. When the
  175. .BR \-v
  176. option is specified, standard output shall be formatted as:
  177. .sp
  178. .RS 4
  179. .nf
  180. "%s\en", <\fIpathname or command\fR>
  181. .fi
  182. .P
  183. .RE
  184. .P
  185. When the
  186. .BR \-V
  187. option is specified, standard output shall be formatted as:
  188. .sp
  189. .RS 4
  190. .nf
  191. "%s\en", <\fIunspecified\fR>
  192. .fi
  193. .P
  194. .RE
  195. .SH STDERR
  196. The standard error shall be used only for diagnostic messages.
  197. .SH "OUTPUT FILES"
  198. None.
  199. .SH "EXTENDED DESCRIPTION"
  200. None.
  201. .SH "EXIT STATUS"
  202. When the
  203. .BR \-v
  204. or
  205. .BR \-V
  206. options are specified, the following exit values shall be returned:
  207. .IP "\00" 6
  208. Successful completion.
  209. .IP >0 6
  210. The
  211. .IR command_name
  212. could not be found or an error occurred.
  213. .P
  214. Otherwise, the following exit values shall be returned:
  215. .IP 126 6
  216. The utility specified by
  217. .IR command_name
  218. was found but could not be invoked.
  219. .IP 127 6
  220. An error occurred in the
  221. .IR command
  222. utility or the utility specified by
  223. .IR command_name
  224. could not be found.
  225. .P
  226. Otherwise, the exit status of
  227. .IR command
  228. shall be that of the simple command specified by the arguments to
  229. .IR command .
  230. .SH "CONSEQUENCES OF ERRORS"
  231. Default.
  232. .LP
  233. .IR "The following sections are informative."
  234. .SH "APPLICATION USAGE"
  235. The order for command search allows functions to override regular
  236. built-ins and path searches. This utility is necessary to allow
  237. functions that have the same name as a utility to call the utility
  238. (instead of a recursive call to the function).
  239. .P
  240. The system default path is available using
  241. .IR getconf ;
  242. however, since
  243. .IR getconf
  244. may need to have the
  245. .IR PATH
  246. set up before it can be called itself, the following can be used:
  247. .sp
  248. .RS 4
  249. .nf
  250. command -p getconf PATH
  251. .fi
  252. .P
  253. .RE
  254. .P
  255. There are some advantages to suppressing the special characteristics of
  256. special built-ins on occasion. For example:
  257. .sp
  258. .RS 4
  259. .nf
  260. command exec > \fIunwritable-file\fR
  261. .fi
  262. .P
  263. .RE
  264. .P
  265. does not cause a non-interactive script to abort, so that the output
  266. status can be checked by the script.
  267. .P
  268. The
  269. .IR command ,
  270. .IR env ,
  271. .IR nohup ,
  272. .IR time ,
  273. and
  274. .IR xargs
  275. utilities have been specified to use exit code 127 if an error occurs
  276. so that applications can distinguish ``failure to find a utility'' from
  277. ``invoked utility exited with an error indication''. The value 127 was
  278. chosen because it is not commonly used for other meanings; most
  279. utilities use small values for ``normal error conditions'' and the
  280. values above 128 can be confused with termination due to receipt of a
  281. signal. The value 126 was chosen in a similar manner to indicate that
  282. the utility could be found, but not invoked. Some scripts produce
  283. meaningful error messages differentiating the 126 and 127 cases. The
  284. distinction between exit codes 126 and 127 is based on KornShell
  285. practice that uses 127 when all attempts to
  286. .IR exec
  287. the utility fail with
  288. .BR [ENOENT] ,
  289. and uses 126 when any attempt to
  290. .IR exec
  291. the utility fails for any other reason.
  292. .P
  293. Since the
  294. .BR \-v
  295. and
  296. .BR \-V
  297. options of
  298. .IR command
  299. produce output in relation to the current shell execution environment,
  300. .IR command
  301. is generally provided as a shell regular built-in. If it is called in a
  302. subshell or separate utility execution environment, such as one of the
  303. following:
  304. .sp
  305. .RS 4
  306. .nf
  307. (PATH=foo command -v)
  308. nohup command -v
  309. .fi
  310. .P
  311. .RE
  312. .P
  313. it does not necessarily produce correct results. For example, when
  314. called with
  315. .IR nohup
  316. or an
  317. .IR exec
  318. function, in a separate utility execution environment, most
  319. implementations are not able to identify aliases, functions, or special
  320. built-ins.
  321. .P
  322. Two types of regular built-ins could be encountered on a system and
  323. these are described separately by
  324. .IR command .
  325. The description of command search in
  326. .IR "Section 2.9.1.1" ", " "Command Search and Execution"
  327. allows for a standard utility to be implemented as a regular built-in
  328. as long as it is found in the appropriate place in a
  329. .IR PATH
  330. search. So, for example,
  331. .IR command
  332. .BR \-v
  333. .IR true
  334. might yield
  335. .BR /bin/true
  336. or some similar pathname. Other implementation-defined utilities that
  337. are not defined by this volume of POSIX.1\(hy2017 might exist only as built-ins and have no
  338. pathname associated with them. These produce output identified as
  339. (regular) built-ins. Applications encountering these are not able to
  340. count on
  341. .IR exec ing
  342. them, using them with
  343. .IR nohup ,
  344. overriding them with a different
  345. .IR PATH ,
  346. and so on.
  347. .SH EXAMPLES
  348. .IP " 1." 4
  349. Make a version of
  350. .IR cd
  351. that always prints out the new working directory exactly once:
  352. .RS 4
  353. .sp
  354. .RS 4
  355. .nf
  356. cd() {
  357. command cd "$@" >/dev/null
  358. pwd
  359. }
  360. .fi
  361. .P
  362. .RE
  363. .RE
  364. .IP " 2." 4
  365. Start off a ``secure shell script'' in which the script avoids
  366. being spoofed by its parent:
  367. .RS 4
  368. .sp
  369. .RS 4
  370. .nf
  371. IFS=\(aq
  372. \&\(aq
  373. # The preceding value should be <space><tab><newline>.
  374. # Set IFS to its default value.
  375. .P
  376. \eunalias -a
  377. # Unset all possible aliases.
  378. # Note that unalias is escaped to prevent an alias
  379. # being used for unalias.
  380. .P
  381. unset -f command
  382. # Ensure command is not a user function.
  383. .P
  384. PATH="$(command -p getconf PATH):$PATH"
  385. # Put on a reliable PATH prefix.
  386. .P
  387. # ...
  388. .fi
  389. .P
  390. .RE
  391. .P
  392. At this point, given correct permissions on the directories called by
  393. .IR PATH ,
  394. the script has the ability to ensure that any utility it calls is the
  395. intended one. It is being very cautious because it assumes that
  396. implementation extensions may be present that would allow user
  397. functions to exist when it is invoked; this capability is not specified
  398. by this volume of POSIX.1\(hy2017, but it is not prohibited as an extension. For example, the
  399. .IR ENV
  400. variable precedes the invocation of the script with a user start-up
  401. script. Such a script could define functions to spoof the application.
  402. .RE
  403. .SH RATIONALE
  404. Since
  405. .IR command
  406. is a regular built-in utility it is always found prior to the
  407. .IR PATH
  408. search.
  409. .P
  410. There is nothing in the description of
  411. .IR command
  412. that implies the command line is parsed any differently from that of
  413. any other simple command. For example:
  414. .sp
  415. .RS 4
  416. .nf
  417. command a | b ; c
  418. .fi
  419. .P
  420. .RE
  421. .P
  422. is not parsed in any special way that causes
  423. .BR '|'
  424. or
  425. .BR ';'
  426. to be treated other than a pipe operator or
  427. <semicolon>
  428. or that prevents function lookup on
  429. .BR b
  430. or
  431. .BR c .
  432. .P
  433. The
  434. .IR command
  435. utility is somewhat similar to the Eighth Edition shell
  436. .IR builtin
  437. command, but since
  438. .IR command
  439. also goes to the file system to search for utilities, the name
  440. .IR builtin
  441. would not be intuitive.
  442. .P
  443. The
  444. .IR command
  445. utility is most likely to be provided as a regular built-in. It is not
  446. listed as a special built-in
  447. for the following reasons:
  448. .IP " *" 4
  449. The removal of exportable functions made the special precedence of a
  450. special built-in unnecessary.
  451. .IP " *" 4
  452. A special built-in has special properties (see
  453. .IR "Section 2.14" ", " "Special Built-In Utilities")
  454. that were inappropriate for invoking other utilities. For example, two
  455. commands such as:
  456. .RS 4
  457. .sp
  458. .RS 4
  459. .nf
  460. date > \fIunwritable-file\fR
  461. .P
  462. command date > \fIunwritable-file\fR
  463. .fi
  464. .P
  465. .RE
  466. .P
  467. would have entirely different results; in a non-interactive script, the
  468. former would continue to execute the next command, the latter would
  469. abort. Introducing this semantic difference along with suppressing
  470. functions was seen to be non-intuitive.
  471. .RE
  472. .P
  473. The
  474. .BR \-p
  475. option is present because it is useful to be able to ensure a safe path
  476. search that finds all the standard utilities. This search might not be
  477. identical to the one that occurs through one of the
  478. .IR exec
  479. functions (as defined in the System Interfaces volume of POSIX.1\(hy2017) when
  480. .IR PATH
  481. is unset. At the very least, this feature is required to allow the
  482. script to access the correct version of
  483. .IR getconf
  484. so that the value of the default path can be accurately retrieved.
  485. .P
  486. The
  487. .IR command
  488. .BR \-v
  489. and
  490. .BR \-V
  491. options were added to satisfy requirements from users that are
  492. currently accomplished by three different historical utilities:
  493. .IR type
  494. in the System V shell,
  495. .IR whence
  496. in the KornShell, and
  497. .IR which
  498. in the C shell. Since there is no historical agreement on how and what
  499. to accomplish here, the POSIX
  500. .IR command
  501. utility was enhanced and the historical utilities were left unmodified.
  502. The C shell
  503. .IR which
  504. merely conducts a path search. The KornShell
  505. .IR whence
  506. is more elaborate\(emin addition to the categories required by POSIX,
  507. it also reports on tracked aliases, exported aliases, and undefined
  508. functions.
  509. .P
  510. The output format of
  511. .BR \-V
  512. was left mostly unspecified because human users are its only audience.
  513. Applications should not be written to care about this information; they
  514. can use the output of
  515. .BR \-v
  516. to differentiate between various types of commands, but the additional
  517. information that may be emitted by the more verbose
  518. .BR \-V
  519. is not needed and should not be arbitrarily constrained in its
  520. verbosity or localization for application parsing reasons.
  521. .SH "FUTURE DIRECTIONS"
  522. None.
  523. .SH "SEE ALSO"
  524. .IR "Section 2.9.1.1" ", " "Command Search and Execution",
  525. .IR "Section 2.12" ", " "Shell Execution Environment",
  526. .IR "Section 2.14" ", " "Special Built-In Utilities",
  527. .IR "\fIsh\fR\^",
  528. .IR "\fItype\fR\^"
  529. .P
  530. The Base Definitions volume of POSIX.1\(hy2017,
  531. .IR "Chapter 8" ", " "Environment Variables",
  532. .IR "Section 12.2" ", " "Utility Syntax Guidelines"
  533. .P
  534. The System Interfaces volume of POSIX.1\(hy2017,
  535. .IR "\fIexec\fR\^"
  536. .\"
  537. .SH COPYRIGHT
  538. Portions of this text are reprinted and reproduced in electronic form
  539. from IEEE Std 1003.1-2017, Standard for Information Technology
  540. -- Portable Operating System Interface (POSIX), The Open Group Base
  541. Specifications Issue 7, 2018 Edition,
  542. Copyright (C) 2018 by the Institute of
  543. Electrical and Electronics Engineers, Inc and The Open Group.
  544. In the event of any discrepancy between this version and the original IEEE and
  545. The Open Group Standard, the original IEEE and The Open Group Standard
  546. is the referee document. The original Standard can be obtained online at
  547. http://www.opengroup.org/unix/online.html .
  548. .PP
  549. Any typographical or formatting errors that appear
  550. in this page are most likely
  551. to have been introduced during the conversion of the source files to
  552. man page format. To report such errors, see
  553. https://www.kernel.org/doc/man-pages/reporting_bugs.html .