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

sh.1p (55895B)


  1. '\" et
  2. .TH SH "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. sh
  12. \(em shell, the standard command language interpreter
  13. .SH SYNOPSIS
  14. .LP
  15. .nf
  16. sh \fB[\fR-abCefhimnuvx\fB] [\fR-o \fIoption\fB]\fR... \fB[\fR+abCefhimnuvx\fB] [\fR+o \fIoption\fB]\fR...
  17. \fB[\fIcommand_file \fB[\fIargument\fR...\fB]]\fR
  18. .P
  19. sh -c \fB[\fR-abCefhimnuvx\fB] [\fR-o \fIoption\fB]\fR... \fB[\fR+abCefhimnuvx\fB] [\fR+o \fIoption\fB]\fR...
  20. \fIcommand_string \fB[\fIcommand_name \fB[\fIargument\fR...\fB]]\fR
  21. .P
  22. sh -s \fB[\fR-abCefhimnuvx\fB] [\fR-o \fIoption\fB]\fR... \fB[\fR+abCefhimnuvx\fB] [\fR+o \fIoption\fB]\fR...
  23. \fB[\fIargument\fR...\fB]\fR
  24. .fi
  25. .SH DESCRIPTION
  26. The
  27. .IR sh
  28. utility is a command language interpreter that shall execute commands
  29. read from a command line string, the standard input, or a specified
  30. file. The application shall ensure that the commands to be executed are
  31. expressed in the language described in
  32. .IR "Chapter 2" ", " "Shell Command Language".
  33. .P
  34. Pathname expansion shall not fail due to the size of a file.
  35. .P
  36. Shell input and output redirections have an implementation-defined
  37. offset maximum that is established in the open file description.
  38. .SH OPTIONS
  39. The
  40. .IR sh
  41. utility shall conform to the Base Definitions volume of POSIX.1\(hy2017,
  42. .IR "Section 12.2" ", " "Utility Syntax Guidelines",
  43. with an extension for support of a leading
  44. <plus-sign>
  45. (\c
  46. .BR '\(pl' )
  47. as noted below.
  48. .P
  49. The
  50. .BR \-a ,
  51. .BR \-b ,
  52. .BR \-C ,
  53. .BR \-e ,
  54. .BR \-f ,
  55. .BR \-m ,
  56. .BR \-n ,
  57. .BR \-o
  58. .IR option ,
  59. .BR \-u ,
  60. .BR \-v ,
  61. and
  62. .BR \-x
  63. options are described as part of the
  64. .IR set
  65. utility in
  66. .IR "Section 2.14" ", " "Special Built-In Utilities".
  67. The option letters derived from the
  68. .IR set
  69. special built-in shall also be accepted with a leading
  70. <plus-sign>
  71. (\c
  72. .BR '\(pl' )
  73. instead of a leading
  74. <hyphen-minus>
  75. (meaning the reverse case of the option as described in this volume of POSIX.1\(hy2017).
  76. .P
  77. The following additional options shall be supported:
  78. .IP "\fB\-c\fP" 10
  79. Read commands from the
  80. .IR command_string
  81. operand. Set the value of special parameter 0 (see
  82. .IR "Section 2.5.2" ", " "Special Parameters")
  83. from the value of the
  84. .IR command_name
  85. operand and the positional parameters ($1, $2, and so on) in sequence
  86. from the remaining
  87. .IR argument
  88. operands. No commands shall be read from the standard input.
  89. .IP "\fB\-i\fP" 10
  90. Specify that the shell is
  91. .IR interactive ;
  92. see below. An implementation may treat specifying the
  93. .BR \-i
  94. option as an error if the real user ID of the calling process does not
  95. equal the effective user ID or if the real group ID does not equal the
  96. effective group ID.
  97. .IP "\fB\-s\fP" 10
  98. Read commands from the standard input.
  99. .P
  100. If there are no operands and the
  101. .BR \-c
  102. option is not specified, the
  103. .BR \-s
  104. option shall be assumed.
  105. .P
  106. If the
  107. .BR \-i
  108. option is present, or if there are no operands and the shell's standard
  109. input and standard error are attached to a terminal, the shell is
  110. considered to be
  111. .IR interactive .
  112. .SH OPERANDS
  113. The following operands shall be supported:
  114. .IP "\fR\-\fR" 10
  115. A single
  116. <hyphen-minus>
  117. shall be treated as the first operand and then ignored. If both
  118. .BR '\-'
  119. and
  120. .BR \(dq--\(dq
  121. are given as arguments, or if other operands precede the single
  122. <hyphen-minus>,
  123. the results are undefined.
  124. .IP "\fIargument\fR" 10
  125. The positional parameters ($1, $2, and so on) shall be set to
  126. .IR arguments ,
  127. if any.
  128. .IP "\fIcommand_file\fR" 10
  129. The pathname of a file containing commands. If the pathname contains
  130. one or more
  131. <slash>
  132. characters, the implementation attempts to read that file; the file need
  133. not be executable. If the pathname does not contain a
  134. <slash>
  135. character:
  136. .RS 10
  137. .IP " *" 4
  138. The implementation shall attempt to read that file from the current
  139. working directory; the file need not be executable.
  140. .IP " *" 4
  141. If the file is not in the current working directory, the implementation
  142. may perform a search for an executable file using the value of
  143. .IR PATH ,
  144. as described in
  145. .IR "Section 2.9.1.1" ", " "Command Search and Execution".
  146. .P
  147. Special parameter 0 (see
  148. .IR "Section 2.5.2" ", " "Special Parameters")
  149. shall be set to the value of
  150. .IR command_file .
  151. If
  152. .IR sh
  153. is called using a synopsis form that omits
  154. .IR command_file ,
  155. special parameter 0 shall be set to the value of the first argument
  156. passed to
  157. .IR sh
  158. from its parent (for example,
  159. .IR argv [0]
  160. for a C program), which is normally a pathname used to execute the
  161. .IR sh
  162. utility.
  163. .RE
  164. .IP "\fIcommand_name\fR" 10
  165. .br
  166. A string assigned to special parameter 0 when executing the commands in
  167. .IR command_string .
  168. If
  169. .IR command_name
  170. is not specified, special parameter 0 shall be set to the value of the
  171. first argument passed to
  172. .IR sh
  173. from its parent (for example,
  174. .IR argv [0]
  175. for a C program), which is normally a pathname used to execute the
  176. .IR sh
  177. utility.
  178. .IP "\fIcommand_string\fR" 10
  179. .br
  180. A string that shall be interpreted by the shell as one or more
  181. commands, as if the string were the argument to the
  182. \fIsystem\fR()
  183. function defined in the System Interfaces volume of POSIX.1\(hy2017. If the
  184. .IR command_string
  185. operand is an empty string,
  186. .IR sh
  187. shall exit with a zero exit status.
  188. .SH STDIN
  189. The standard input shall be used only if one of the following is true:
  190. .IP " *" 4
  191. The
  192. .BR \-s
  193. option is specified.
  194. .IP " *" 4
  195. The
  196. .BR \-c
  197. option is not specified and no operands are specified.
  198. .IP " *" 4
  199. The script executes one or more commands that require input from
  200. standard input (such as a
  201. .IR read
  202. command that does not redirect its input).
  203. .P
  204. See the INPUT FILES section.
  205. .P
  206. When the shell is using standard input and it invokes a command that
  207. also uses standard input, the shell shall ensure that the standard
  208. input file pointer points directly after the command it has read when
  209. the command begins execution. It shall not read ahead in such a manner
  210. that any characters intended to be read by the invoked command are
  211. consumed by the shell (whether interpreted by the shell or not) or that
  212. characters that are not read by the invoked command are not seen by the
  213. shell. When the command expecting to read standard input is started
  214. asynchronously by an interactive shell, it is unspecified whether
  215. characters are read by the command or interpreted by the shell.
  216. .P
  217. If the standard input to
  218. .IR sh
  219. is a FIFO or terminal device and is set to non-blocking reads, then
  220. .IR sh
  221. shall enable blocking reads on standard input. This shall remain in
  222. effect when the command completes.
  223. .SH "INPUT FILES"
  224. The input file shall be a text file, except that line lengths shall be
  225. unlimited. If the input file consists solely of zero or more blank lines
  226. and comments,
  227. .IR sh
  228. shall exit with a zero exit status.
  229. .SH "ENVIRONMENT VARIABLES"
  230. The following environment variables shall affect the execution of
  231. .IR sh :
  232. .IP "\fIENV\fP" 10
  233. This variable, when and only when an interactive shell is invoked,
  234. shall be subjected to parameter expansion (see
  235. .IR "Section 2.6.2" ", " "Parameter Expansion")
  236. by the shell, and the resulting value shall be used as a pathname of a
  237. file containing shell commands to execute in the current environment.
  238. The file need not be executable. If the expanded value of
  239. .IR ENV
  240. is not an absolute pathname, the results are unspecified.
  241. .IR ENV
  242. shall be ignored if the real and effective user IDs or real and
  243. effective group IDs of the process are different.
  244. .IP "\fIFCEDIT\fP" 10
  245. This variable, when expanded by the shell, shall determine the default
  246. value for the
  247. .BR \-e
  248. .IR editor
  249. option's
  250. .IR editor
  251. option-argument. If
  252. .IR FCEDIT
  253. is null or unset,
  254. .IR ed
  255. shall be used as the editor.
  256. .IP "\fIHISTFILE\fP" 10
  257. Determine a pathname naming a command history file. If the
  258. .IR HISTFILE
  259. variable is not set, the shell may attempt to access or create a file
  260. .BR .sh_history
  261. in the directory referred to by the
  262. .IR HOME
  263. environment variable. If the shell cannot obtain both read and
  264. write access to, or create, the history file, it shall use an
  265. unspecified mechanism that allows the history to operate properly.
  266. (References to history ``file'' in this section shall be understood to
  267. mean this unspecified mechanism in such cases.) An implementation may
  268. choose to access this variable only when initializing the history file;
  269. this initialization shall occur when
  270. .IR fc
  271. or
  272. .IR sh
  273. first attempt to retrieve entries from, or add entries to, the file, as
  274. the result of commands issued by the user, the file named by the
  275. .IR ENV
  276. variable, or implementation-defined system start-up files.
  277. Implementations may choose to disable the history list mechanism for
  278. users with appropriate privileges who do not set
  279. .IR HISTFILE ;
  280. the specific circumstances under which this occurs are
  281. implementation-defined. If more than one instance of the shell is
  282. using the same history file, it is unspecified how updates to the
  283. history file from those shells interact. As entries are deleted from
  284. the history file, they shall be deleted oldest first. It is
  285. unspecified when history file entries are physically removed from the
  286. history file.
  287. .IP "\fIHISTSIZE\fP" 10
  288. Determine a decimal number representing the limit to the number of
  289. previous commands that are accessible. If this variable is unset, an
  290. unspecified default greater than or equal to 128 shall be used. The
  291. maximum number of commands in the history list is unspecified, but
  292. shall be at least 128. An implementation may choose to access this
  293. variable only when initializing the history file, as described under
  294. .IR HISTFILE .
  295. Therefore, it is unspecified whether changes made to
  296. .IR HISTSIZE
  297. after the history file has been initialized are effective.
  298. .IP "\fIHOME\fP" 10
  299. Determine the pathname of the user's home directory. The contents of
  300. .IR HOME
  301. are used in tilde expansion as described in
  302. .IR "Section 2.6.1" ", " "Tilde Expansion".
  303. .IP "\fILANG\fP" 10
  304. Provide a default value for the internationalization variables that are
  305. unset or null. (See the Base Definitions volume of POSIX.1\(hy2017,
  306. .IR "Section 8.2" ", " "Internationalization Variables"
  307. for the precedence of internationalization variables used to determine
  308. the values of locale categories.)
  309. .IP "\fILC_ALL\fP" 10
  310. If set to a non-empty string value, override the values of all the
  311. other internationalization variables.
  312. .IP "\fILC_COLLATE\fP" 10
  313. .br
  314. Determine the behavior of range expressions, equivalence classes, and
  315. multi-character collating elements within pattern matching.
  316. .IP "\fILC_CTYPE\fP" 10
  317. Determine the locale for the interpretation of sequences of bytes of
  318. text data as characters (for example, single-byte as opposed to
  319. multi-byte characters in arguments and input files), which characters
  320. are defined as letters (character class
  321. .BR alpha ),
  322. and the behavior of character classes within pattern matching.
  323. .IP "\fILC_MESSAGES\fP" 10
  324. .br
  325. Determine the locale that should be used to affect the format and
  326. contents of diagnostic messages written to standard error.
  327. .IP "\fIMAIL\fP" 10
  328. Determine a pathname of the user's mailbox file for purposes of
  329. incoming mail notification. If this variable is set, the shell shall
  330. inform the user if the file named by the variable is created or if its
  331. modification time has changed. Informing the user shall be accomplished
  332. by writing a string of unspecified format to standard error prior to
  333. the writing of the next primary prompt string. Such check shall be
  334. performed only after the completion of the interval defined by the
  335. .IR MAILCHECK
  336. variable after the last such check. The user shall be informed only if
  337. .IR MAIL
  338. is set and
  339. .IR MAILPATH
  340. is not set.
  341. .IP "\fIMAILCHECK\fP" 10
  342. .br
  343. Establish a decimal integer value that specifies how often (in seconds)
  344. the shell shall check for the arrival of mail in the files specified by
  345. the
  346. .IR MAILPATH
  347. or
  348. .IR MAIL
  349. variables. The default value shall be 600 seconds. If set to zero,
  350. the shell shall check before issuing each primary prompt.
  351. .IP "\fIMAILPATH\fP" 10
  352. Provide a list of pathnames and optional messages separated by
  353. <colon>
  354. characters. If this variable is set, the shell shall inform the user if
  355. any of the files named by the variable are created or if any of their
  356. modification times change. (See the preceding entry for
  357. .IR MAIL
  358. for descriptions of mail arrival and user informing.) Each pathname can
  359. be followed by
  360. .BR '%'
  361. and a string that shall be subjected to parameter expansion and written
  362. to standard error when the modification time changes. If a
  363. .BR '%'
  364. character in the pathname is preceded by a
  365. <backslash>,
  366. it shall be treated as a literal
  367. .BR '%'
  368. in the pathname. The default message is unspecified.
  369. .RS 10
  370. .P
  371. The
  372. .IR MAILPATH
  373. environment variable takes precedence over the
  374. .IR MAIL
  375. variable.
  376. .RE
  377. .IP "\fINLSPATH\fP" 10
  378. Determine the location of message catalogs for the processing of
  379. .IR LC_MESSAGES .
  380. .IP "\fIPATH\fP" 10
  381. Establish a string formatted as described in the Base Definitions volume of POSIX.1\(hy2017,
  382. .IR "Chapter 8" ", " "Environment Variables",
  383. used to effect command interpretation; see
  384. .IR "Section 2.9.1.1" ", " "Command Search and Execution".
  385. .IP "\fIPWD\fP" 10
  386. This variable shall represent an absolute pathname of the current
  387. working directory. Assignments to this variable may be ignored.
  388. .SH "ASYNCHRONOUS EVENTS"
  389. The
  390. .IR sh
  391. utility shall take the standard action for all signals (see
  392. .IR "Section 1.4" ", " "Utility Description Defaults")
  393. with the following exceptions.
  394. .P
  395. If the shell is interactive, SIGINT signals received during command
  396. line editing shall be handled as described in the EXTENDED DESCRIPTION,
  397. and SIGINT signals received at other times shall be caught but no action
  398. performed.
  399. .br
  400. .P
  401. If the shell is interactive:
  402. .IP " *" 4
  403. SIGQUIT and SIGTERM signals shall be ignored.
  404. .IP " *" 4
  405. If the
  406. .BR \-m
  407. option is in effect, SIGTTIN, SIGTTOU, and SIGTSTP signals shall be
  408. ignored.
  409. .IP " *" 4
  410. If the
  411. .BR \-m
  412. option is not in effect, it is unspecified whether SIGTTIN, SIGTTOU,
  413. and SIGTSTP signals are ignored, set to the default action, or caught.
  414. If they are caught, the shell shall, in the signal-catching function,
  415. set the signal to the default action and raise the signal (after taking
  416. any appropriate steps, such as restoring terminal settings).
  417. .P
  418. The standard actions, and the actions described above for interactive
  419. shells, can be overridden by use of the
  420. .IR trap
  421. special built-in utility (see
  422. .IR "\fItrap\fR\^"
  423. and
  424. .IR "Section 2.11" ", " "Signals and Error Handling").
  425. .SH STDOUT
  426. See the STDERR section.
  427. .SH STDERR
  428. Except as otherwise stated (by the descriptions of any invoked
  429. utilities or in interactive mode), standard error shall be used
  430. only for diagnostic messages.
  431. .SH "OUTPUT FILES"
  432. None.
  433. .SH "EXTENDED DESCRIPTION"
  434. See
  435. .IR "Chapter 2" ", " "Shell Command Language".
  436. The functionality described in the rest of the EXTENDED DESCRIPTION
  437. section shall be provided on implementations that support the User
  438. Portability Utilities option
  439. (and the rest of this section is not further shaded for this option).
  440. .SS "Command History List"
  441. .P
  442. When the
  443. .IR sh
  444. utility is being used interactively, it shall maintain a list of
  445. commands previously entered from the terminal in the file named by the
  446. .IR HISTFILE
  447. environment variable. The type, size, and internal format of this file
  448. are unspecified. Multiple
  449. .IR sh
  450. processes can share access to the file for a user, if file access
  451. permissions allow this; see the description of the
  452. .IR HISTFILE
  453. environment variable.
  454. .SS "Command Line Editing"
  455. .P
  456. When
  457. .IR sh
  458. is being used interactively from a terminal, the current command and
  459. the command history (see
  460. .IR "\fIfc\fR\^")
  461. can be edited using
  462. .IR vi -mode
  463. command line editing. This mode uses commands, described below,
  464. similar to a subset of those described in the
  465. .IR vi
  466. utility. Implementations may offer other command line editing modes
  467. corresponding to other editing utilities.
  468. .P
  469. The command
  470. .IR set
  471. .BR \-o
  472. .IR vi
  473. shall enable
  474. .IR vi -mode
  475. editing and place
  476. .IR sh
  477. into
  478. .IR vi
  479. insert mode (see
  480. .IR "Command Line Editing (vi-mode)").
  481. This command also shall disable any other editing mode that the
  482. implementation may provide. The command
  483. .IR set
  484. .BR +o
  485. .IR vi
  486. disables
  487. .IR vi -mode
  488. editing.
  489. .P
  490. Certain block-mode terminals may be unable to support shell command
  491. line editing. If a terminal is unable to provide either edit mode, it
  492. need not be possible to
  493. .IR set
  494. .BR \-o
  495. .IR vi
  496. when using the shell on this terminal.
  497. .P
  498. In the following sections, the characters
  499. .IR erase ,
  500. .IR interrupt ,
  501. .IR kill ,
  502. and
  503. .IR end-of-file
  504. are those set by the
  505. .IR stty
  506. utility.
  507. .SS "Command Line Editing (vi-mode)"
  508. .P
  509. In
  510. .IR vi
  511. editing mode, there shall be a distinguished line, the edit line. All
  512. the editing operations which modify a line affect the edit line. The
  513. edit line is always the newest line in the command history buffer.
  514. .P
  515. With
  516. .IR vi -mode
  517. enabled,
  518. .IR sh
  519. can be switched between insert mode and command mode.
  520. .P
  521. When in insert mode, an entered character shall be inserted into the
  522. command line, except as noted in
  523. .IR "vi Line Editing Insert Mode".
  524. Upon entering
  525. .IR sh
  526. and after termination of the previous command,
  527. .IR sh
  528. shall be in insert mode.
  529. .P
  530. Typing an escape character shall switch
  531. .IR sh
  532. into command mode (see
  533. .IR "vi Line Editing Command Mode").
  534. In command mode, an entered character shall either invoke a defined
  535. operation, be used as part of a multi-character operation, or be
  536. treated as an error. A character that is not recognized as part of an
  537. editing command shall terminate any specific editing command and shall
  538. alert the terminal. If
  539. .IR sh
  540. receives a SIGINT signal in command mode (whether generated by typing the
  541. .IR interrupt
  542. character or by other means), it shall terminate command line editing
  543. on the current command line, reissue the prompt on the next line of the
  544. terminal, and reset the command history (see
  545. .IR "\fIfc\fR\^")
  546. so that the most recently executed command is the previous command
  547. (that is, the command that was being edited when it was interrupted is
  548. not re-entered into the history).
  549. .P
  550. In the following sections, the phrase ``move the cursor to the
  551. beginning of the word'' shall mean ``move the cursor to the first
  552. character of the current word'' and the phrase ``move the cursor to the
  553. end of the word'' shall mean ``move the cursor to the last character of
  554. the current word''. The phrase ``beginning of the command line''
  555. indicates the point between the end of the prompt string issued by the
  556. shell (or the beginning of the terminal line, if there is no prompt
  557. string) and the first character of the command text.
  558. .SS "vi Line Editing Insert Mode"
  559. .P
  560. While in insert mode, any character typed shall be inserted in the
  561. current command line, unless it is from the following set.
  562. .IP <newline> 10
  563. Execute the current command line. If the current command line is not
  564. empty, this line shall be entered into the command history (see
  565. .IR "\fIfc\fR\^").
  566. .IP "\fIerase\fR" 10
  567. Delete the character previous to the current cursor position and move
  568. the current cursor position back one character. In insert mode,
  569. characters shall be erased from both the screen and the buffer when
  570. backspacing.
  571. .IP "\fIinterrupt\fR" 10
  572. If
  573. .IR sh
  574. receives a SIGINT signal in insert mode (whether generated by typing
  575. the
  576. .IR interrupt
  577. character or by other means), it shall terminate command line editing
  578. with the same effects as described for interrupting command mode; see
  579. .IR "Command Line Editing (vi-mode)".
  580. .IP "\fIkill\fR" 10
  581. Clear all the characters from the input line.
  582. .IP "<control>\(hyV" 10
  583. Insert the next character input, even if the character is otherwise a
  584. special insert mode character.
  585. .IP "<control>\(hyW" 10
  586. Delete the characters from the one preceding the cursor to the
  587. preceding word boundary. The word boundary in this case is the closer
  588. to the cursor of either the beginning of the line or a character that
  589. is in neither the
  590. .BR blank
  591. nor
  592. .BR punct
  593. character classification of the current locale.
  594. .IP "\fIend-of-file\fR" 10
  595. Interpreted as the end of input in
  596. .IR sh .
  597. This interpretation shall occur only at the beginning of an input
  598. line. If
  599. .IR end-of-file
  600. is entered other than at the beginning of the line, the results are
  601. unspecified.
  602. .IP <ESC> 10
  603. Place
  604. .IR sh
  605. into command mode.
  606. .SS "vi Line Editing Command Mode"
  607. .P
  608. In command mode for the command line editing feature, decimal digits
  609. not beginning with 0 that precede a command letter shall be
  610. remembered. Some commands use these decimal digits as a count number
  611. that affects the operation.
  612. .P
  613. The term
  614. .IR "motion command"
  615. represents one of the commands:
  616. .sp
  617. .RS 4
  618. .nf
  619. <space> 0 b F l W \(ha $ ; E f T w | , B e h t
  620. .fi
  621. .P
  622. .RE
  623. .P
  624. If the current line is not the edit line, any command that modifies the
  625. current line shall cause the content of the current line to replace the
  626. content of the edit line, and the current line shall become the edit
  627. line. This replacement cannot be undone (see the
  628. .BR u
  629. and
  630. .BR U
  631. commands below). The modification requested shall then be performed to
  632. the edit line. When the current line is the edit line, the modification
  633. shall be done directly to the edit line.
  634. .P
  635. Any command that is preceded by
  636. .IR count
  637. shall take a count (the numeric value of any preceding decimal
  638. digits). Unless otherwise noted, this count shall cause the specified
  639. operation to repeat by the number of times specified by the count.
  640. Also unless otherwise noted, a
  641. .IR count
  642. that is out of range is considered an error condition and shall alert
  643. the terminal, but neither the cursor position, nor the command line,
  644. shall change.
  645. .P
  646. The terms
  647. .IR word
  648. and
  649. .IR bigword
  650. are used as defined in the
  651. .IR vi
  652. description. The term
  653. .IR "save buffer"
  654. corresponds to the term
  655. .IR "unnamed buffer"
  656. in
  657. .IR vi .
  658. .P
  659. The following commands shall be recognized in command mode:
  660. .IP <newline> 10
  661. Execute the current command line. If the current command line is not
  662. empty, this line shall be entered into the command history (see
  663. .IR "\fIfc\fR\^").
  664. .IP "<control>\(hyL" 10
  665. Redraw the current command line. Position the cursor at the same
  666. location on the redrawn line.
  667. .IP "\fB#\fP" 10
  668. Insert the character
  669. .BR '#'
  670. at the beginning of the current command line and treat the resulting
  671. edit line as a comment. This line shall be entered into the command
  672. history; see
  673. .IR "\fIfc\fR\^".
  674. .IP "\fB=\fP" 10
  675. Display the possible shell word expansions (see
  676. .IR "Section 2.6" ", " "Word Expansions")
  677. of the bigword at the current command line position.
  678. .RS 10
  679. .TP 10
  680. .BR Note:
  681. This does not modify the content of the current line, and therefore
  682. does not cause the current line to become the edit line.
  683. .P
  684. .P
  685. These expansions shall be displayed on subsequent terminal lines. If
  686. the bigword contains none of the characters
  687. .BR '?' ,
  688. .BR '*' ,
  689. or
  690. .BR '[' ,
  691. an
  692. <asterisk>
  693. (\c
  694. .BR '*' )
  695. shall be implicitly assumed at the end. If any directories are
  696. matched, these expansions shall have a
  697. .BR '/'
  698. character appended. After the expansion, the line shall be redrawn,
  699. the cursor repositioned at the current cursor position, and
  700. .IR sh
  701. shall be placed in command mode.
  702. .RE
  703. .IP "\fB\e\fR" 10
  704. Perform pathname expansion (see
  705. .IR "Section 2.6.6" ", " "Pathname Expansion")
  706. on the current bigword, up to the largest set of characters that can be
  707. matched uniquely. If the bigword contains none of the characters
  708. .BR '?' ,
  709. .BR '*' ,
  710. or
  711. .BR '[' ,
  712. an
  713. <asterisk>
  714. (\c
  715. .BR '*' )
  716. shall be implicitly assumed at the end. This maximal expansion then
  717. shall replace the original bigword in the command line, and the cursor
  718. shall be placed after this expansion. If the resulting bigword
  719. completely and uniquely matches a directory, a
  720. .BR '/'
  721. character shall be inserted directly after the bigword. If some other
  722. file is completely matched, a single
  723. <space>
  724. shall be inserted after the bigword. After this operation,
  725. .IR sh
  726. shall be placed in insert mode.
  727. .IP "\fB*\fR" 10
  728. Perform pathname expansion on the current bigword and insert all
  729. expansions into the command to replace the current bigword, with each
  730. expansion separated by a single
  731. <space>.
  732. If at the end of the line, the current cursor position shall be moved
  733. to the first column position following the expansions and
  734. .IR sh
  735. shall be placed in insert mode. Otherwise, the current cursor position
  736. shall be the last column position of the first character after the
  737. expansions and
  738. .IR sh
  739. shall be placed in insert mode. If the current bigword contains none
  740. of the characters
  741. .BR '?' ,
  742. .BR '*' ,
  743. or
  744. .BR '[' ,
  745. before the operation, an
  746. <asterisk>
  747. (\c
  748. .BR '*' )
  749. shall be implicitly assumed at the end.
  750. .IP "\fB@\fIletter\fR" 10
  751. Insert the value of the alias named
  752. .IR _letter .
  753. The symbol
  754. .IR letter
  755. represents a single alphabetic character from the portable character
  756. set; implementations may support additional characters as an
  757. extension. If the alias
  758. .IR _letter
  759. contains other editing commands, these commands shall be performed as
  760. part of the insertion. If no alias
  761. .IR _letter
  762. is enabled, this command shall have no effect.
  763. .IP "\fB[\fIcount\fB]~\fR" 10
  764. Convert, if the current character is a lowercase letter, to the
  765. equivalent uppercase letter and
  766. .IR "vice versa" ,
  767. as prescribed by the current locale. The current cursor position then
  768. shall be advanced by one character. If the cursor was positioned on
  769. the last character of the line, the case conversion shall occur, but
  770. the cursor shall not advance. If the
  771. .BR '\(ti'
  772. command is preceded by a
  773. .IR count ,
  774. that number of characters shall be converted, and the cursor shall be
  775. advanced to the character position after the last character converted.
  776. If the
  777. .IR count
  778. is larger than the number of characters after the cursor, this shall
  779. not be considered an error; the cursor shall advance to the last
  780. character on the line.
  781. .IP "\fB[\fIcount\fB].\fR" 10
  782. Repeat the most recent non-motion command, even if it was executed on
  783. an earlier command line. If the previous command was preceded by a
  784. .IR count ,
  785. and no count is given on the
  786. .BR '.'
  787. command, the count from the previous command shall be included as part
  788. of the repeated command. If the
  789. .BR '.'
  790. command is preceded by a
  791. .IR count ,
  792. this shall override any
  793. .IR count
  794. argument to the previous command. The
  795. .IR count
  796. specified in the
  797. .BR '.'
  798. command shall become the count for subsequent
  799. .BR '.'
  800. commands issued without a count.
  801. .IP "\fB[\fInumber\fB]v\fR" 10
  802. Invoke the
  803. .IR vi
  804. editor to edit the current command line in a temporary file. When the
  805. editor exits, the commands in the temporary file shall be executed and
  806. placed in the command history. If a
  807. .IR number
  808. is included, it specifies the command number in the command history to
  809. be edited, rather than the current command line.
  810. .IP "\fB[\fIcount\fB]l\fR\0\0\0(ell)" 10
  811. .sp -0.5v
  812. .IP "\fB[\fIcount\fB]\fR<space>" 10
  813. .br
  814. Move the current cursor position to the next character position. If
  815. the cursor was positioned on the last character of the line, the
  816. terminal shall be alerted and the cursor shall not be advanced. If the
  817. .IR count
  818. is larger than the number of characters after the cursor, this shall
  819. not be considered an error; the cursor shall advance to the last
  820. character on the line.
  821. .IP "\fB[\fIcount\fB]h\fR" 10
  822. Move the current cursor position to the
  823. .IR count th
  824. (default 1) previous character position. If the cursor was positioned
  825. on the first character of the line, the terminal shall be alerted and
  826. the cursor shall not be moved. If the count is larger than the number
  827. of characters before the cursor, this shall not be considered an error;
  828. the cursor shall move to the first character on the line.
  829. .IP "\fB[\fIcount\fB]w\fR" 10
  830. Move to the start of the next word. If the cursor was positioned on
  831. the last character of the line, the terminal shall be alerted and the
  832. cursor shall not be advanced. If the
  833. .IR count
  834. is larger than the number of words after the cursor, this shall not be
  835. considered an error; the cursor shall advance to the last character on
  836. the line.
  837. .IP "\fB[\fIcount\fB]W\fR" 10
  838. Move to the start of the next bigword. If the cursor was positioned on
  839. the last character of the line, the terminal shall be alerted and the
  840. cursor shall not be advanced. If the
  841. .IR count
  842. is larger than the number of bigwords after the cursor, this shall not
  843. be considered an error; the cursor shall advance to the last character
  844. on the line.
  845. .IP "\fB[\fIcount\fB]e\fR" 10
  846. Move to the end of the current word. If at the end of a word, move to
  847. the end of the next word. If the cursor was positioned on the last
  848. character of the line, the terminal shall be alerted and the cursor
  849. shall not be advanced. If the
  850. .IR count
  851. is larger than the number of words after the cursor, this shall not be
  852. considered an error; the cursor shall advance to the last character on
  853. the line.
  854. .IP "\fB[\fIcount\fB]E\fR" 10
  855. Move to the end of the current bigword. If at the end of a bigword,
  856. move to the end of the next bigword. If the cursor was positioned on
  857. the last character of the line, the terminal shall be alerted and the
  858. cursor shall not be advanced. If the
  859. .IR count
  860. is larger than the number of bigwords after the cursor, this shall not
  861. be considered an error; the cursor shall advance to the last character
  862. on the line.
  863. .IP "\fB[\fIcount\fB]b\fR" 10
  864. Move to the beginning of the current word. If at the beginning of a
  865. word, move to the beginning of the previous word. If the cursor was
  866. positioned on the first character of the line, the terminal shall be
  867. alerted and the cursor shall not be moved. If the
  868. .IR count
  869. is larger than the number of words preceding the cursor, this shall not
  870. be considered an error; the cursor shall return to the first character
  871. on the line.
  872. .IP "\fB[\fIcount\fB]B\fR" 10
  873. Move to the beginning of the current bigword. If at the beginning of a
  874. bigword, move to the beginning of the previous bigword. If the cursor
  875. was positioned on the first character of the line, the terminal shall
  876. be alerted and the cursor shall not be moved. If the
  877. .IR count
  878. is larger than the number of bigwords preceding the cursor, this shall
  879. not be considered an error; the cursor shall return to the first
  880. character on the line.
  881. .IP "\fB^\fR" 10
  882. Move the current cursor position to the first character on the input
  883. line that is not a
  884. <blank>.
  885. .IP "\fB$\fR" 10
  886. Move to the last character position on the current command line.
  887. .IP "\fB0\fR" 10
  888. (Zero.) Move to the first character position on the current command
  889. line.
  890. .IP "\fB[\fIcount\fB]\||\fR" 10
  891. Move to the
  892. .IR count th
  893. character position on the current command line. If no number is
  894. specified, move to the first position. The first character position
  895. shall be numbered 1. If the count is larger than the number of
  896. characters on the line, this shall not be considered an error; the
  897. cursor shall be placed on the last character on the line.
  898. .IP "\fB[\fIcount\fB]f\fIc\fR" 10
  899. Move to the first occurrence of the character
  900. .BR 'c'
  901. that occurs after the current cursor position. If the cursor was
  902. positioned on the last character of the line, the terminal shall be
  903. alerted and the cursor shall not be advanced. If the character
  904. .BR 'c'
  905. does not occur in the line after the current cursor position, the
  906. terminal shall be alerted and the cursor shall not be moved.
  907. .IP "\fB[\fIcount\fB]F\fIc\fR" 10
  908. Move to the first occurrence of the character
  909. .BR 'c'
  910. that occurs before the current cursor position. If the cursor was
  911. positioned on the first character of the line, the terminal shall be
  912. alerted and the cursor shall not be moved. If the character
  913. .BR 'c'
  914. does not occur in the line before the current cursor position, the
  915. terminal shall be alerted and the cursor shall not be moved.
  916. .IP "\fB[\fIcount\fB]t\fIc\fR" 10
  917. Move to the character before the first occurrence of the character
  918. .BR 'c'
  919. that occurs after the current cursor position. If the cursor was
  920. positioned on the last character of the line, the terminal shall be
  921. alerted and the cursor shall not be advanced. If the character
  922. .BR 'c'
  923. does not occur in the line after the current cursor position, the
  924. terminal shall be alerted and the cursor shall not be moved.
  925. .IP "\fB[\fIcount\fB]T\fIc\fR" 10
  926. Move to the character after the first occurrence of the character
  927. .BR 'c'
  928. that occurs before the current cursor position. If the cursor was
  929. positioned on the first character of the line, the terminal shall be
  930. alerted and the cursor shall not be moved. If the character
  931. .BR 'c'
  932. does not occur in the line before the current cursor position, the
  933. terminal shall be alerted and the cursor shall not be moved.
  934. .IP "\fB[\fIcount\fB];\fR" 10
  935. Repeat the most recent
  936. .BR f ,
  937. .BR F ,
  938. .BR t ,
  939. or
  940. .BR T
  941. command. Any number argument on that previous command shall be
  942. ignored. Errors are those described for the repeated command.
  943. .IP "\fB[\fIcount\fB],\fR" 10
  944. Repeat the most recent
  945. .BR f ,
  946. .BR F ,
  947. .BR t ,
  948. or
  949. .BR T
  950. command. Any number argument on that previous command shall be
  951. ignored. However, reverse the direction of that command.
  952. .IP "\fBa\fR" 10
  953. Enter insert mode after the current cursor position. Characters that
  954. are entered shall be inserted before the next character.
  955. .IP "\fBA\fR" 10
  956. Enter insert mode after the end of the current command line.
  957. .IP "\fBi\fR" 10
  958. Enter insert mode at the current cursor position. Characters that are
  959. entered shall be inserted before the current character.
  960. .IP "\fBI\fR" 10
  961. Enter insert mode at the beginning of the current command line.
  962. .IP "\fBR\fR" 10
  963. Enter insert mode, replacing characters from the command line beginning
  964. at the current cursor position.
  965. .IP "\fB[\fIcount\fB]c\fImotion\fR" 10
  966. .br
  967. Delete the characters between the current cursor position and the
  968. cursor position that would result from the specified motion
  969. command. Then enter insert mode before the first character following
  970. any deleted characters. If
  971. .IR count
  972. is specified, it shall be applied to the motion command. A
  973. .IR count
  974. shall be ignored for the following motion commands:
  975. .RS 10
  976. .sp
  977. .RS 4
  978. .nf
  979. 0 \(ha $ c
  980. .fi
  981. .P
  982. .RE
  983. .P
  984. If the motion command is the character
  985. .BR 'c' ,
  986. the current command line shall be cleared and insert mode shall be
  987. entered. If the motion command would move the current cursor position
  988. toward the beginning of the command line, the character under the
  989. current cursor position shall not be deleted. If the motion command
  990. would move the current cursor position toward the end of the command
  991. line, the character under the current cursor position shall be deleted.
  992. If the
  993. .IR count
  994. is larger than the number of characters between the current cursor
  995. position and the end of the command line toward which the motion
  996. command would move the cursor, this shall not be considered an error;
  997. all of the remaining characters in the aforementioned range shall be
  998. deleted and insert mode shall be entered. If the motion command is
  999. invalid, the terminal shall be alerted, the cursor shall not be moved,
  1000. and no text shall be deleted.
  1001. .RE
  1002. .IP "\fBC\fR" 10
  1003. Delete from the current character to the end of the line and enter
  1004. insert mode at the new end-of-line.
  1005. .IP "\fBS\fR" 10
  1006. Clear the entire edit line and enter insert mode.
  1007. .IP "\fB[\fIcount\fB]r\fIc\fR" 10
  1008. Replace the current character with the character
  1009. .BR 'c' .
  1010. With a number
  1011. .IR count ,
  1012. replace the current and the following
  1013. .IR count \-1
  1014. characters. After this command, the current cursor position shall be
  1015. on the last character that was changed. If the
  1016. .IR count
  1017. is larger than the number of characters after the cursor, this shall
  1018. not be considered an error; all of the remaining characters shall be
  1019. changed.
  1020. .IP "\fB[\fIcount\fB]_\fR" 10
  1021. Append a
  1022. <space>
  1023. after the current character position and then append the last bigword
  1024. in the previous input line after the
  1025. <space>.
  1026. Then enter insert mode after the last character just appended. With a
  1027. number
  1028. .IR count ,
  1029. append the
  1030. .IR count th
  1031. bigword in the previous line.
  1032. .IP "\fB[\fIcount\fB]x\fR" 10
  1033. Delete the character at the current cursor position and place the
  1034. deleted characters in the save buffer. If the cursor was positioned on
  1035. the last character of the line, the character shall be deleted and the
  1036. cursor position shall be moved to the previous character (the new last
  1037. character). If the
  1038. .IR count
  1039. is larger than the number of characters after the cursor, this shall
  1040. not be considered an error; all the characters from the cursor to the
  1041. end of the line shall be deleted.
  1042. .IP "\fB[\fIcount\fB]X\fR" 10
  1043. Delete the character before the current cursor position and place the
  1044. deleted characters in the save buffer. The character under the current
  1045. cursor position shall not change. If the cursor was positioned on the
  1046. first character of the line, the terminal shall be alerted, and the
  1047. .BR X
  1048. command shall have no effect. If the line contained a single
  1049. character, the
  1050. .BR X
  1051. command shall have no effect. If the line contained no characters, the
  1052. terminal shall be alerted and the cursor shall not be moved. If the
  1053. .IR count
  1054. is larger than the number of characters before the cursor, this shall
  1055. not be considered an error; all the characters from before the cursor
  1056. to the beginning of the line shall be deleted.
  1057. .IP "\fB[\fIcount\fB]d\fImotion\fR" 10
  1058. .br
  1059. Delete the characters between the current cursor position and the
  1060. character position that would result from the motion command. A number
  1061. .IR count
  1062. repeats the motion command
  1063. .IR count
  1064. times. If the motion command would move toward the beginning of the
  1065. command line, the character under the current cursor position shall not
  1066. be deleted. If the motion command is
  1067. .BR d ,
  1068. the entire current command line shall be cleared. If the
  1069. .IR count
  1070. is larger than the number of characters between the current cursor
  1071. position and the end of the command line toward which the motion
  1072. command would move the cursor, this shall not be considered an error;
  1073. all of the remaining characters in the aforementioned range shall be
  1074. deleted. The deleted characters shall be placed in the save buffer.
  1075. .IP "\fBD\fR" 10
  1076. Delete all characters from the current cursor position to the end of
  1077. the line. The deleted characters shall be placed in the save buffer.
  1078. .IP "\fB[\fIcount\fB]y\fImotion\fR" 10
  1079. .br
  1080. Yank (that is, copy) the characters from the current cursor position to
  1081. the position resulting from the motion command into the save buffer. A
  1082. number
  1083. .IR count
  1084. shall be applied to the motion command. If the motion command would
  1085. move toward the beginning of the command line, the character under the
  1086. current cursor position shall not be included in the set of yanked
  1087. characters. If the motion command is
  1088. .BR y ,
  1089. the entire current command line shall be yanked into the save buffer.
  1090. The current cursor position shall be unchanged. If the
  1091. .IR count
  1092. is larger than the number of characters between the current cursor
  1093. position and the end of the command line toward which the motion
  1094. command would move the cursor, this shall not be considered an error;
  1095. all of the remaining characters in the aforementioned range shall be
  1096. yanked.
  1097. .IP "\fBY\fR" 10
  1098. Yank the characters from the current cursor position to the end of the
  1099. line into the save buffer. The current character position shall be
  1100. unchanged.
  1101. .IP "\fB[\fIcount\fB]p\fR" 10
  1102. Put a copy of the current contents of the save buffer after the current
  1103. cursor position. The current cursor position shall be advanced to the
  1104. last character put from the save buffer. A
  1105. .IR count
  1106. shall indicate how many copies of the save buffer shall be put.
  1107. .IP "\fB[\fIcount\fB]P\fR" 10
  1108. Put a copy of the current contents of the save buffer before the
  1109. current cursor position. The current cursor position shall be moved to
  1110. the last character put from the save buffer. A
  1111. .IR count
  1112. shall indicate how many copies of the save buffer shall be put.
  1113. .IP "\fBu\fR" 10
  1114. Undo the last command that changed the edit line. This operation shall
  1115. not undo the copy of any command line to the edit line.
  1116. .IP "\fBU\fR" 10
  1117. Undo all changes made to the edit line. This operation shall not undo
  1118. the copy of any command line to the edit line.
  1119. .IP "\fB[\fIcount\fB]k\fR" 10
  1120. .sp -0.5v
  1121. .IP "\fB[\fIcount\fB]\-\fR" 10
  1122. Set the current command line to be the
  1123. .IR count th
  1124. previous command line in the shell command history. If
  1125. .IR count
  1126. is not specified, it shall default to 1. The cursor shall be positioned
  1127. on the first character of the new command. If a
  1128. .BR k
  1129. or
  1130. .BR \-
  1131. command would retreat past the maximum number of commands in effect for
  1132. this shell (affected by the
  1133. .IR HISTSIZE
  1134. environment variable), the terminal shall be alerted, and the command
  1135. shall have no effect.
  1136. .IP "\fB[\fIcount\fB]j\fR" 10
  1137. .sp -0.5v
  1138. .IP "\fB[\fIcount\fB]+\fR" 10
  1139. Set the current command line to be the
  1140. .IR count th
  1141. next command line in the shell command history. If
  1142. .IR count
  1143. is not specified, it shall default to 1. The cursor shall be positioned
  1144. on the first character of the new command. If a
  1145. .BR j
  1146. or
  1147. .BR +
  1148. command advances past the edit line, the current command line shall be
  1149. restored to the edit line and the terminal shall be alerted.
  1150. .IP "\fB[\fInumber\fB]G\fR" 10
  1151. Set the current command line to be the oldest command line stored in
  1152. the shell command history. With a number
  1153. .IR number ,
  1154. set the current command line to be the command line
  1155. .IR number
  1156. in the history. If command line
  1157. .IR number
  1158. does not exist, the terminal shall be alerted and the command line
  1159. shall not be changed.
  1160. .IP "\fB/\fIpattern\fR<newline>" 10
  1161. .br
  1162. Move backwards through the command history, searching for the specified
  1163. pattern, beginning with the previous command line. Patterns use the
  1164. pattern matching notation described in
  1165. .IR "Section 2.13" ", " "Pattern Matching Notation",
  1166. except that the
  1167. .BR '\(ha'
  1168. character shall have special meaning when it appears as the first
  1169. character of
  1170. .IR pattern .
  1171. In this case, the
  1172. .BR '\(ha'
  1173. is discarded and the characters after the
  1174. .BR '\(ha'
  1175. shall be matched only at the beginning of a line. Commands in the
  1176. command history shall be treated as strings, not as filenames. If the
  1177. pattern is not found, the current command line shall be unchanged and
  1178. the terminal shall be alerted. If it is found in a previous line, the
  1179. current command line shall be set to that line and the cursor shall be
  1180. set to the first character of the new command line.
  1181. .RS 10
  1182. .P
  1183. If
  1184. .IR pattern
  1185. is empty, the last non-empty pattern provided to
  1186. .BR /
  1187. or
  1188. .BR ?
  1189. shall be used. If there is no previous non-empty pattern, the terminal
  1190. shall be alerted and the current command line shall remain unchanged.
  1191. .RE
  1192. .IP "\fB?\fIpattern\fR<newline>" 10
  1193. .br
  1194. Move forwards through the command history, searching for the specified
  1195. pattern, beginning with the next command line. Patterns use the pattern
  1196. matching notation described in
  1197. .IR "Section 2.13" ", " "Pattern Matching Notation",
  1198. except that the
  1199. .BR '\(ha'
  1200. character shall have special meaning when it appears as the first
  1201. character of
  1202. .IR pattern .
  1203. In this case, the
  1204. .BR '\(ha'
  1205. is discarded and the characters after the
  1206. .BR '\(ha'
  1207. shall be matched only at the beginning of a line. Commands in the
  1208. command history shall be treated as strings, not as filenames. If the
  1209. pattern is not found, the current command line shall be unchanged and
  1210. the terminal shall be alerted. If it is found in a following line, the
  1211. current command line shall be set to that line and the cursor shall be
  1212. set to the fist character of the new command line.
  1213. .RS 10
  1214. .P
  1215. If
  1216. .IR pattern
  1217. is empty, the last non-empty pattern provided to
  1218. .BR /
  1219. or
  1220. .BR ?
  1221. shall be used. If there is no previous non-empty pattern, the terminal
  1222. shall be alerted and the current command line shall remain unchanged.
  1223. .RE
  1224. .IP "\fBn\fR" 10
  1225. Repeat the most recent
  1226. .BR /
  1227. or
  1228. .BR ?
  1229. command. If there is no previous
  1230. .BR /
  1231. or
  1232. .BR ? ,
  1233. the terminal shall be alerted and the current command line shall remain
  1234. unchanged.
  1235. .IP "\fBN\fR" 10
  1236. Repeat the most recent
  1237. .BR /
  1238. or
  1239. .BR ?
  1240. command, reversing the direction of the search. If there is no previous
  1241. .BR /
  1242. or
  1243. .BR ? ,
  1244. the terminal shall be alerted and the current command line shall remain
  1245. unchanged.
  1246. .SH "EXIT STATUS"
  1247. The following exit values shall be returned:
  1248. .IP "\0\0\0\00" 8
  1249. The script to be executed consisted solely of zero or more blank lines
  1250. or comments, or both.
  1251. .IP "1\(hy125" 8
  1252. A non-interactive shell detected an error other than
  1253. .IR command_file
  1254. not found or executable, including but not limited to syntax,
  1255. redirection, or variable assignment errors.
  1256. .IP "\0\0126" 8
  1257. A specified
  1258. .IR command_file
  1259. could not be executed due to an
  1260. .BR [ENOEXEC]
  1261. error (see
  1262. .IR "Section 2.9.1.1" ", " "Command Search and Execution",
  1263. item 2).
  1264. .IP "\0\0127" 8
  1265. A specified
  1266. .IR command_file
  1267. could not be found by a non-interactive shell.
  1268. .P
  1269. Otherwise, the shell shall return the exit status of the last command
  1270. it invoked or attempted to invoke (see also the
  1271. .IR exit
  1272. utility in
  1273. .IR "Section 2.14" ", " "Special Built-In Utilities").
  1274. .SH "CONSEQUENCES OF ERRORS"
  1275. See
  1276. .IR "Section 2.8.1" ", " "Consequences of Shell Errors".
  1277. .LP
  1278. .IR "The following sections are informative."
  1279. .SH "APPLICATION USAGE"
  1280. Standard input and standard error are the files that
  1281. determine whether a shell is interactive when
  1282. .BR \-i
  1283. is not specified. For example:
  1284. .sp
  1285. .RS 4
  1286. .nf
  1287. sh > file
  1288. .fi
  1289. .P
  1290. .RE
  1291. .P
  1292. and:
  1293. .sp
  1294. .RS 4
  1295. .nf
  1296. sh 2> file
  1297. .fi
  1298. .P
  1299. .RE
  1300. .P
  1301. create interactive and non-interactive shells, respectively. Although
  1302. both accept terminal input, the results of error conditions are
  1303. different, as described in
  1304. .IR "Section 2.8.1" ", " "Consequences of Shell Errors";
  1305. in the second example a redirection error encountered by a special
  1306. built-in utility aborts the shell.
  1307. .P
  1308. A conforming application must protect its first operand, if it starts
  1309. with a
  1310. <plus-sign>,
  1311. by preceding it with the
  1312. .BR \(dq--\(dq
  1313. argument that denotes the end of the options.
  1314. .P
  1315. Applications should note that the standard
  1316. .IR PATH
  1317. to the shell cannot be assumed to be either
  1318. .BR /bin/sh
  1319. or
  1320. .BR /usr/bin/sh ,
  1321. and should be determined by interrogation of the
  1322. .IR PATH
  1323. returned by
  1324. .IR getconf
  1325. .IR PATH ,
  1326. ensuring that the returned pathname is an absolute pathname and not a
  1327. shell built-in.
  1328. .P
  1329. For example, to determine the location of the standard
  1330. .IR sh
  1331. utility:
  1332. .sp
  1333. .RS 4
  1334. .nf
  1335. command -v sh
  1336. .fi
  1337. .P
  1338. .RE
  1339. .P
  1340. On some implementations this might return:
  1341. .sp
  1342. .RS 4
  1343. .nf
  1344. /usr/xpg4/bin/sh
  1345. .fi
  1346. .P
  1347. .RE
  1348. .P
  1349. Furthermore, on systems that support executable scripts (the
  1350. .BR \(dq#!\(dq
  1351. construct), it is recommended that applications using executable
  1352. scripts install them using
  1353. .IR getconf
  1354. .IR PATH
  1355. to determine the shell pathname and update the
  1356. .BR \(dq#!\(dq
  1357. script appropriately as it is being installed (for example, with
  1358. .IR sed ).
  1359. For example:
  1360. .sp
  1361. .RS 4
  1362. .nf
  1363. #
  1364. # Installation time script to install correct POSIX shell pathname
  1365. #
  1366. # Get list of paths to check
  1367. #
  1368. Sifs=$IFS
  1369. Sifs_set=${IFS+y}
  1370. IFS=:
  1371. set -- $(getconf PATH)
  1372. if [ "$Sifs_set" = y ]
  1373. then
  1374. IFS=$Sifs
  1375. else
  1376. unset IFS
  1377. fi
  1378. #
  1379. # Check each path for \(aqsh\(aq
  1380. #
  1381. for i
  1382. do
  1383. if [ -x "${i}"/sh ]
  1384. then
  1385. Pshell=${i}/sh
  1386. fi
  1387. done
  1388. #
  1389. # This is the list of scripts to update. They should be of the
  1390. # form \(aq${name}.source\(aq and will be transformed to \(aq${name}\(aq.
  1391. # Each script should begin:
  1392. #
  1393. # #!INSTALLSHELLPATH
  1394. #
  1395. scripts="a b c"
  1396. #
  1397. # Transform each script
  1398. #
  1399. for i in ${scripts}
  1400. do
  1401. sed -e "s|INSTALLSHELLPATH|${Pshell}|" < ${i}.source > ${i}
  1402. done
  1403. .fi
  1404. .P
  1405. .RE
  1406. .SH EXAMPLES
  1407. .IP " 1." 4
  1408. Execute a shell command from a string:
  1409. .RS 4
  1410. .sp
  1411. .RS 4
  1412. .nf
  1413. sh -c "cat myfile"
  1414. .fi
  1415. .P
  1416. .RE
  1417. .RE
  1418. .IP " 2." 4
  1419. Execute a shell script from a file in the current directory:
  1420. .RS 4
  1421. .sp
  1422. .RS 4
  1423. .nf
  1424. sh my_shell_cmds
  1425. .fi
  1426. .P
  1427. .RE
  1428. .RE
  1429. .SH RATIONALE
  1430. The
  1431. .IR sh
  1432. utility and the
  1433. .IR set
  1434. special built-in utility share a common set of options.
  1435. .P
  1436. The name
  1437. .IR IFS
  1438. was originally an abbreviation of ``Input Field Separators''; however,
  1439. this name is misleading as the
  1440. .IR IFS
  1441. characters are actually used as field terminators. One justification
  1442. for ignoring the contents of
  1443. .IR IFS
  1444. upon entry to the script, beyond security considerations, is to
  1445. assist possible future shell compilers. Allowing
  1446. .IR IFS
  1447. to be imported from the environment prevents many optimizations that
  1448. might otherwise be performed via dataflow analysis of the script
  1449. itself.
  1450. .P
  1451. The text in the STDIN section about non-blocking reads concerns an
  1452. instance of
  1453. .IR sh
  1454. that has been invoked, probably by a C-language program, with standard
  1455. input that has been opened using the O_NONBLOCK flag; see
  1456. \fIopen\fR()
  1457. in the System Interfaces volume of POSIX.1\(hy2017. If the shell did not reset this flag, it would
  1458. immediately terminate because no input data would be available yet and
  1459. that would be considered the same as end-of-file.
  1460. .P
  1461. The options associated with a
  1462. .IR "restricted shell"
  1463. (command name
  1464. .IR rsh
  1465. and the
  1466. .BR \-r
  1467. option) were excluded because the standard developers considered that
  1468. the implied level of security could not be achieved and they did not
  1469. want to raise false expectations.
  1470. .P
  1471. On systems that support set-user-ID scripts,
  1472. a historical trapdoor has been to link a script to the name
  1473. .BR \-i .
  1474. When it is called by a sequence such as:
  1475. .sp
  1476. .RS 4
  1477. .nf
  1478. sh -
  1479. .fi
  1480. .P
  1481. .RE
  1482. .P
  1483. or by:
  1484. .sp
  1485. .RS 4
  1486. .nf
  1487. #!\ usr/bin/sh\ -
  1488. .fi
  1489. .P
  1490. .RE
  1491. .P
  1492. the historical systems have assumed that no option letters follow.
  1493. Thus, this volume of POSIX.1\(hy2017 allows the single
  1494. <hyphen-minus>
  1495. to mark the end of the options, in addition to the use of the regular
  1496. .BR \(dq--\(dq
  1497. argument, because it was considered that the older practice was so
  1498. pervasive. An alternative approach is taken by the KornShell, where
  1499. real and effective user/group IDs must match for an interactive shell;
  1500. this behavior is specifically allowed by this volume of POSIX.1\(hy2017.
  1501. .TP 10
  1502. .BR Note:
  1503. There are other problems with set-user-ID scripts that the two
  1504. approaches described here do not resolve.
  1505. .P
  1506. .P
  1507. The initialization process for the history file can be dependent on the
  1508. system start-up files, in that they may contain commands that
  1509. effectively preempt the user's settings of
  1510. .IR HISTFILE
  1511. and
  1512. .IR HISTSIZE .
  1513. For example, function definition commands are recorded in the history
  1514. file, unless the
  1515. .IR set
  1516. .BR \-o
  1517. .IR nolog
  1518. option is set. If the system administrator includes function
  1519. definitions in some system start-up file called before the
  1520. .IR ENV
  1521. file, the history file is initialized before the user gets a chance to
  1522. influence its characteristics. In some historical shells, the history
  1523. file is initialized just after the
  1524. .IR ENV
  1525. file has been processed. Therefore, it is implementation-defined
  1526. whether changes made to
  1527. .IR HISTFILE
  1528. after the history file has been initialized are effective.
  1529. .P
  1530. The default messages for the various
  1531. .IR MAIL -related
  1532. messages are unspecified because they vary across implementations.
  1533. Typical messages are:
  1534. .sp
  1535. .RS 4
  1536. .nf
  1537. "you have mail\en"
  1538. .fi
  1539. .P
  1540. .RE
  1541. .P
  1542. or:
  1543. .sp
  1544. .RS 4
  1545. .nf
  1546. "you have new mail\en"
  1547. .fi
  1548. .P
  1549. .RE
  1550. .P
  1551. It is important that the descriptions of command line editing refer to
  1552. the same shell as that in POSIX.1\(hy2008 so that interactive users can also be
  1553. application programmers without having to deal with programmatic
  1554. differences in their two environments. It is also essential that the
  1555. utility name
  1556. .IR sh
  1557. be specified because this explicit utility name is too firmly rooted in
  1558. historical practice of application programs for it to change.
  1559. .P
  1560. Consideration was given to mandating a diagnostic message when
  1561. attempting to set
  1562. .IR vi -mode
  1563. on terminals that do not support command line editing. However, it is
  1564. not historical practice for the shell to be cognizant of all terminal
  1565. types and thus be able to detect inappropriate terminals in all cases.
  1566. Implementations are encouraged to supply diagnostics in this case
  1567. whenever possible, rather than leaving the user in a state where
  1568. editing commands work incorrectly.
  1569. .P
  1570. In early proposals, the KornShell-derived
  1571. .IR emacs
  1572. mode of command line editing was included, even though the
  1573. .IR emacs
  1574. editor itself was not. The community of
  1575. .IR emacs
  1576. proponents was adamant that the full
  1577. .IR emacs
  1578. editor not be standardized because they were concerned that an attempt
  1579. to standardize this very powerful environment would encourage vendors
  1580. to ship strictly conforming versions lacking the extensibility required
  1581. by the community. The author of the original
  1582. .IR emacs
  1583. program also expressed his desire to omit the program. Furthermore,
  1584. there were a number of historical systems that did not include
  1585. .IR emacs ,
  1586. or included it without supporting it, but there were very few that did
  1587. not include and support
  1588. .IR vi .
  1589. The shell
  1590. .IR emacs
  1591. command line editing mode was finally omitted because it became
  1592. apparent that the KornShell version and the editor being distributed
  1593. with the GNU system had diverged in some respects. The author of
  1594. .IR emacs
  1595. requested that the POSIX
  1596. .IR emacs
  1597. mode either be deleted or have a significant number of unspecified
  1598. conditions. Although the KornShell author agreed to consider changes to
  1599. bring the shell into alignment, the standard developers decided to
  1600. defer specification at that time. At the time, it was assumed that
  1601. convergence on an acceptable definition would occur for a subsequent
  1602. draft, but that has not happened, and there appears to be no impetus to
  1603. do so. In any case, implementations are free to offer additional
  1604. command line editing modes based on the exact models of editors their
  1605. users are most comfortable with.
  1606. .P
  1607. Early proposals had the following list entry in
  1608. .IR "vi Line Editing Insert Mode":
  1609. .IP "\fR\e\fR" 6
  1610. If followed by the
  1611. .IR erase
  1612. or
  1613. .IR kill
  1614. character, that character shall be inserted into the input line.
  1615. Otherwise, the
  1616. <backslash>
  1617. itself shall be inserted into the input line.
  1618. .P
  1619. However, this is not actually a feature of
  1620. .IR sh
  1621. command line editing insert mode, but one of some historical terminal
  1622. line drivers. Some conforming implementations continue to do this when
  1623. the
  1624. .IR stty
  1625. .BR iexten
  1626. flag is set.
  1627. .P
  1628. In interactive shells, SIGTERM is ignored so that
  1629. .IR "kill 0"
  1630. does not kill the shell, and SIGINT is caught so that
  1631. .IR wait
  1632. is interruptible. If the shell does not ignore SIGTTIN, SIGTTOU, and
  1633. SIGTSTP signals when it is interactive and the
  1634. .BR \-m
  1635. option is not in effect, these signals suspend the shell if it is not
  1636. a session leader. If it is a session leader, the signals are discarded
  1637. if they would stop the process, as required by the System Interfaces volume of POSIX.1\(hy2017,
  1638. .IR "Section 2.4.3" ", " "Signal Actions"
  1639. for orphaned process groups.
  1640. .SH "FUTURE DIRECTIONS"
  1641. None.
  1642. .SH "SEE ALSO"
  1643. .IR "Section 2.9.1.1" ", " "Command Search and Execution",
  1644. .IR "Chapter 2" ", " "Shell Command Language",
  1645. .IR "\fIcd\fR\^",
  1646. .IR "\fIecho\fR\^",
  1647. .IR "\fIexit\fR\^",
  1648. .IR "\fIfc\fR\^",
  1649. .IR "\fIpwd\fR\^",
  1650. .IR "invalid",
  1651. .IR "\fIset\fR\^",
  1652. .IR "\fIstty\fR\^",
  1653. .IR "\fItest\fR\^",
  1654. .IR "\fItrap\fR\^",
  1655. .IR "\fIumask\fR\^",
  1656. .IR "\fIvi\fR\^"
  1657. .P
  1658. The Base Definitions volume of POSIX.1\(hy2017,
  1659. .IR "Chapter 8" ", " "Environment Variables",
  1660. .IR "Section 12.2" ", " "Utility Syntax Guidelines"
  1661. .P
  1662. The System Interfaces volume of POSIX.1\(hy2017,
  1663. .IR "\fIdup\fR\^(\|)",
  1664. .IR "\fIexec\fR\^",
  1665. .IR "\fIexit\fR\^(\|)",
  1666. .IR "\fIfork\fR\^(\|)",
  1667. .IR "\fIopen\fR\^(\|)",
  1668. .IR "\fIpipe\fR\^(\|)",
  1669. .IR "\fIsignal\fR\^(\|)",
  1670. .IR "\fIsystem\fR\^(\|)",
  1671. .IR "\fIulimit\fR\^(\|)",
  1672. .IR "\fIumask\fR\^(\|)",
  1673. .IR "\fIwait\fR\^(\|)"
  1674. .\"
  1675. .SH COPYRIGHT
  1676. Portions of this text are reprinted and reproduced in electronic form
  1677. from IEEE Std 1003.1-2017, Standard for Information Technology
  1678. -- Portable Operating System Interface (POSIX), The Open Group Base
  1679. Specifications Issue 7, 2018 Edition,
  1680. Copyright (C) 2018 by the Institute of
  1681. Electrical and Electronics Engineers, Inc and The Open Group.
  1682. In the event of any discrepancy between this version and the original IEEE and
  1683. The Open Group Standard, the original IEEE and The Open Group Standard
  1684. is the referee document. The original Standard can be obtained online at
  1685. http://www.opengroup.org/unix/online.html .
  1686. .PP
  1687. Any typographical or formatting errors that appear
  1688. in this page are most likely
  1689. to have been introduced during the conversion of the source files to
  1690. man page format. To report such errors, see
  1691. https://www.kernel.org/doc/man-pages/reporting_bugs.html .