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

ksh.1 (135771B)


  1. .\" $OpenBSD: ksh.1,v 1.221 2024/09/25 06:13:01 jmc Exp $
  2. .\"
  3. .\" Public Domain
  4. .\"
  5. .Dd $Mdocdate: September 25 2024 $
  6. .Dt KSH 1
  7. .Os
  8. .Sh NAME
  9. .Nm ksh ,
  10. .Nm rksh
  11. .Nd public domain Korn shell
  12. .Sh SYNOPSIS
  13. .Nm ksh
  14. .Bk -words
  15. .Op Fl +abCefhiklmnpruvXx
  16. .Op Fl +o Ar option
  17. .Op Fl c Ar string | Fl s | Ar file Op Ar argument ...
  18. .Ek
  19. .Sh DESCRIPTION
  20. .Nm
  21. is a command interpreter intended for both interactive and shell
  22. script use.
  23. Its command language is a superset of the
  24. .Xr sh 1
  25. shell language.
  26. .Pp
  27. The options are as follows:
  28. .Bl -tag -width Ds
  29. .It Fl c Ar string
  30. .Nm
  31. will execute the command(s) contained in
  32. .Ar string .
  33. .It Fl i
  34. Interactive shell.
  35. A shell is
  36. .Dq interactive
  37. if this
  38. option is used or if both standard input and standard error are attached
  39. to a
  40. .Xr tty 4 .
  41. An interactive shell has job control enabled, ignores the
  42. .Dv SIGINT ,
  43. .Dv SIGQUIT ,
  44. and
  45. .Dv SIGTERM
  46. signals, and prints prompts before reading input (see the
  47. .Ev PS1
  48. and
  49. .Ev PS2
  50. parameters).
  51. For non-interactive shells, the
  52. .Ic trackall
  53. option is on by default (see the
  54. .Ic set
  55. command below).
  56. .It Fl l
  57. Login shell.
  58. If the basename the shell is called with (i.e. argv[0])
  59. starts with
  60. .Ql -
  61. or if this option is used,
  62. the shell is assumed to be a login shell and the shell reads and executes
  63. the contents of
  64. .Pa /etc/profile
  65. and
  66. .Pa $HOME/.profile
  67. if they exist and are readable.
  68. .It Fl p
  69. Privileged shell.
  70. A shell is
  71. .Dq privileged
  72. if this option is used
  73. or if the real user ID or group ID does not match the
  74. effective user ID or group ID (see
  75. .Xr getuid 2
  76. and
  77. .Xr getgid 2 ) .
  78. A privileged shell does not process
  79. .Pa $HOME/.profile
  80. nor the
  81. .Ev ENV
  82. parameter (see below).
  83. Instead, the file
  84. .Pa /etc/suid_profile
  85. is processed.
  86. Clearing the privileged option causes the shell to set
  87. its effective user ID (group ID) to its real user ID (group ID).
  88. .It Fl r
  89. Restricted shell.
  90. A shell is
  91. .Dq restricted
  92. if this
  93. option is used;
  94. if the basename the shell was invoked with was
  95. .Dq rksh ;
  96. or if the
  97. .Ev SHELL
  98. parameter is set to
  99. .Dq rksh .
  100. The following restrictions come into effect after the shell processes any
  101. profile and
  102. .Ev ENV
  103. files:
  104. .Pp
  105. .Bl -bullet -compact
  106. .It
  107. The
  108. .Ic cd
  109. command is disabled.
  110. .It
  111. The
  112. .Ev SHELL ,
  113. .Ev ENV ,
  114. and
  115. .Ev PATH
  116. parameters cannot be changed.
  117. .It
  118. Command names can't be specified with absolute or relative paths.
  119. .It
  120. The
  121. .Fl p
  122. option of the built-in command
  123. .Ic command
  124. can't be used.
  125. .It
  126. Redirections that create files can't be used (i.e.\&
  127. .Sq Cm > ,
  128. .Sq Cm >| ,
  129. .Sq Cm >> ,
  130. .Sq Cm <> ) .
  131. .El
  132. .It Fl s
  133. The shell reads commands from standard input; all non-option arguments
  134. are positional parameters.
  135. .El
  136. .Pp
  137. In addition to the above, the options described in the
  138. .Ic set
  139. built-in command can also be used on the command line:
  140. both
  141. .Op Fl +abCefhkmnuvXx
  142. and
  143. .Op Fl +o Ar option
  144. can be used for single letter or long options, respectively.
  145. .Pp
  146. If neither the
  147. .Fl c
  148. nor the
  149. .Fl s
  150. option is specified, the first non-option argument specifies the name
  151. of a file the shell reads commands from.
  152. If there are no non-option
  153. arguments, the shell reads commands from the standard input.
  154. The name of the shell (i.e. the contents of $0)
  155. is determined as follows: if the
  156. .Fl c
  157. option is used and there is a non-option argument, it is used as the name;
  158. if commands are being read from a file, the file is used as the name;
  159. otherwise, the basename the shell was called with (i.e. argv[0]) is used.
  160. .Pp
  161. If the
  162. .Ev ENV
  163. parameter is set when an interactive shell starts (or,
  164. in the case of login shells,
  165. after any profiles are processed), its value is subjected to parameter,
  166. command, arithmetic, and tilde
  167. .Pq Sq ~
  168. substitution and the resulting file
  169. (if any) is read and executed.
  170. In order to have an interactive (as opposed to login) shell
  171. process a startup file,
  172. .Ev ENV
  173. may be set and exported (see below) in
  174. .Pa $HOME/.profile
  175. \- future interactive shell invocations will process any file pointed to by
  176. .Ev $ENV :
  177. .Pp
  178. .Dl export ENV=$HOME/.kshrc
  179. .Pp
  180. .Pa $HOME/.kshrc
  181. is then free to specify instructions for interactive shells.
  182. For example, the global configuration file may be sourced:
  183. .Bd -literal -offset indent
  184. \&. /etc/ksh.kshrc
  185. .Ed
  186. .Pp
  187. The above strategy may be employed to keep
  188. setup procedures for login shells in
  189. .Pa $HOME/.profile
  190. and setup procedures for interactive shells in
  191. .Pa $HOME/.kshrc .
  192. Of course, since login shells are also interactive,
  193. any commands placed in
  194. .Pa $HOME/.kshrc
  195. will be executed by login shells too.
  196. .Pp
  197. The exit status of the shell is 127 if the command file specified on the
  198. command line could not be opened, or non-zero if a fatal syntax error
  199. occurred during the execution of a script.
  200. In the absence of fatal errors,
  201. the exit status is that of the last command executed, or zero, if no
  202. command is executed.
  203. .Ss Command syntax
  204. The shell begins parsing its input by breaking it into
  205. .Em words .
  206. Words, which are sequences of characters, are delimited by unquoted whitespace
  207. characters (space, tab, and newline) or meta-characters
  208. .Po
  209. .Ql < ,
  210. .Ql > ,
  211. .Ql | ,
  212. .Ql \&; ,
  213. .Ql \&( ,
  214. .Ql \&) ,
  215. and
  216. .Ql &
  217. .Pc .
  218. Aside from delimiting words, spaces and tabs are ignored, while newlines
  219. usually delimit commands.
  220. The meta-characters are used in building the following
  221. .Em tokens :
  222. .Sq Cm < ,
  223. .Sq Cm <& ,
  224. .Sq Cm << ,
  225. .Sq Cm > ,
  226. .Sq Cm >& ,
  227. .Sq Cm >> ,
  228. etc. are used to specify redirections (see
  229. .Sx Input/output redirection
  230. below);
  231. .Ql |
  232. is used to create pipelines;
  233. .Ql |&
  234. is used to create co-processes (see
  235. .Sx Co-processes
  236. below);
  237. .Ql \&;
  238. is used to separate commands;
  239. .Ql &
  240. is used to create asynchronous pipelines;
  241. .Ql &&
  242. and
  243. .Ql ||
  244. are used to specify conditional execution;
  245. .Ql ;;
  246. is used in
  247. .Ic case
  248. statements;
  249. .Ql (( .. ))
  250. is used in arithmetic expressions;
  251. and lastly,
  252. .Ql \&( .. )\&
  253. is used to create subshells.
  254. .Pp
  255. Whitespace and meta-characters can be quoted individually using a backslash
  256. .Pq Sq \e ,
  257. or in groups using double
  258. .Pq Sq \&"
  259. or single
  260. .Pq Sq '
  261. quotes.
  262. The following characters are also treated specially by the
  263. shell and must be quoted if they are to represent themselves:
  264. .Ql \e ,
  265. .Ql \&" ,
  266. .Ql ' ,
  267. .Ql # ,
  268. .Ql $ ,
  269. .Ql ` ,
  270. .Ql ~ ,
  271. .Ql { ,
  272. .Ql } ,
  273. .Ql * ,
  274. .Ql \&? ,
  275. and
  276. .Ql \&[ .
  277. The first three of these are the above mentioned quoting characters (see
  278. .Sx Quoting
  279. below);
  280. .Ql # ,
  281. if used at the beginning of a word, introduces a comment \(em everything after
  282. the
  283. .Ql #
  284. up to the nearest newline is ignored;
  285. .Ql $
  286. is used to introduce parameter, command, and arithmetic substitutions (see
  287. .Sx Substitution
  288. below);
  289. .Ql `
  290. introduces an old-style command substitution (see
  291. .Sx Substitution
  292. below);
  293. .Ql ~
  294. begins a directory expansion (see
  295. .Sx Tilde expansion
  296. below);
  297. .Ql {
  298. and
  299. .Ql }
  300. delimit
  301. .Xr csh 1 Ns -style
  302. alternations (see
  303. .Sx Brace expansion
  304. below);
  305. and finally,
  306. .Ql * ,
  307. .Ql \&? ,
  308. and
  309. .Ql \&[
  310. are used in file name generation (see
  311. .Sx File name patterns
  312. below).
  313. .Pp
  314. As words and tokens are parsed, the shell builds commands, of which there
  315. are two basic types:
  316. .Em simple-commands ,
  317. typically programs that are executed, and
  318. .Em compound-commands ,
  319. such as
  320. .Ic for
  321. and
  322. .Ic if
  323. statements, grouping constructs, and function definitions.
  324. .Pp
  325. A simple-command consists of some combination of parameter assignments
  326. (see
  327. .Sx Parameters
  328. below),
  329. input/output redirections (see
  330. .Sx Input/output redirections
  331. below),
  332. and command words; the only restriction is that parameter assignments come
  333. before any command words.
  334. The command words, if any, define the command
  335. that is to be executed and its arguments.
  336. The command may be a shell built-in command, a function,
  337. or an external command
  338. (i.e. a separate executable file that is located using the
  339. .Ev PATH
  340. parameter; see
  341. .Sx Command execution
  342. below).
  343. .Pp
  344. All command constructs have an exit status.
  345. For external commands,
  346. this is related to the status returned by
  347. .Xr wait 2
  348. (if the command could not be found, the exit status is 127; if it could not
  349. be executed, the exit status is 126).
  350. The exit status of other command
  351. constructs (built-in commands, functions, compound-commands, pipelines, lists,
  352. etc.) are all well-defined and are described where the construct is
  353. described.
  354. The exit status of a command consisting only of parameter
  355. assignments is that of the last command substitution performed during the
  356. parameter assignment or 0 if there were no command substitutions.
  357. .Pp
  358. Commands can be chained together using the
  359. .Ql |
  360. token to form pipelines, in which the standard output of each command but the
  361. last is piped (see
  362. .Xr pipe 2 )
  363. to the standard input of the following command.
  364. The exit status of a pipeline is that of its last command, unless the
  365. .Ic pipefail
  366. option is set.
  367. A pipeline may be prefixed by the
  368. .Ql \&!
  369. reserved word, which causes the exit status of the pipeline to be logically
  370. complemented: if the original status was 0, the complemented status will be 1;
  371. if the original status was not 0, the complemented status will be 0.
  372. .Pp
  373. .Em Lists
  374. of commands can be created by separating pipelines by any of the following
  375. tokens:
  376. .Ql && ,
  377. .Ql || ,
  378. .Ql & ,
  379. .Ql |& ,
  380. and
  381. .Ql \&; .
  382. The first two are for conditional execution:
  383. .Dq Ar cmd1 No && Ar cmd2
  384. executes
  385. .Ar cmd2
  386. only if the exit status of
  387. .Ar cmd1
  388. is zero;
  389. .Ql ||
  390. is the opposite \(em
  391. .Ar cmd2
  392. is executed only if the exit status of
  393. .Ar cmd1
  394. is non-zero.
  395. .Ql &&
  396. and
  397. .Ql ||
  398. have equal precedence which is higher than that of
  399. .Ql & ,
  400. .Ql |& ,
  401. and
  402. .Ql \&; ,
  403. which also have equal precedence.
  404. The
  405. .Ql &&
  406. and
  407. .Ql ||
  408. operators are
  409. .Qq left-associative .
  410. For example, both of these commands will print only
  411. .Qq bar :
  412. .Bd -literal -offset indent
  413. $ false && echo foo || echo bar
  414. $ true || echo foo && echo bar
  415. .Ed
  416. .Pp
  417. The
  418. .Ql &
  419. token causes the preceding command to be executed asynchronously; that is,
  420. the shell starts the command but does not wait for it to complete (the shell
  421. does keep track of the status of asynchronous commands; see
  422. .Sx Job control
  423. below).
  424. When an asynchronous command is started when job control is disabled
  425. (i.e. in most scripts), the command is started with signals
  426. .Dv SIGINT
  427. and
  428. .Dv SIGQUIT
  429. ignored and with input redirected from
  430. .Pa /dev/null
  431. (however, redirections specified in the asynchronous command have precedence).
  432. The
  433. .Ql |&
  434. operator starts a co-process which is a special kind of asynchronous process
  435. (see
  436. .Sx Co-processes
  437. below).
  438. A command must follow the
  439. .Ql &&
  440. and
  441. .Ql ||
  442. operators, while it need not follow
  443. .Ql & ,
  444. .Ql |& ,
  445. or
  446. .Ql \&; .
  447. The exit status of a list is that of the last command executed, with the
  448. exception of asynchronous lists, for which the exit status is 0.
  449. .Pp
  450. Compound commands are created using the following reserved words.
  451. These words
  452. are only recognized if they are unquoted and if they are used as the first
  453. word of a command (i.e. they can't be preceded by parameter assignments or
  454. redirections):
  455. .Bd -literal -offset indent
  456. case esac in until (( }
  457. do fi name while ))
  458. done for select ! [[
  459. elif function then ( ]]
  460. else if time ) {
  461. .Ed
  462. .Pp
  463. .Sy Note :
  464. Some shells (but not this one) execute control structure commands in a
  465. subshell when one or more of their file descriptors are redirected, so any
  466. environment changes inside them may fail.
  467. To be portable, the
  468. .Ic exec
  469. statement should be used instead to redirect file descriptors before the
  470. control structure.
  471. .Pp
  472. In the following compound command descriptions, command lists (denoted as
  473. .Em list )
  474. that are followed by reserved words must end with a semicolon, a newline, or
  475. a (syntactically correct) reserved word.
  476. For example, the following are all valid:
  477. .Bd -literal -offset indent
  478. $ { echo foo; echo bar; }
  479. $ { echo foo; echo bar<newline> }
  480. $ { { echo foo; echo bar; } }
  481. .Ed
  482. .Pp
  483. This is not valid:
  484. .Pp
  485. .Dl $ { echo foo; echo bar }
  486. .Bl -tag -width Ds
  487. .It Pq Ar list
  488. Execute
  489. .Ar list
  490. in a subshell.
  491. There is no implicit way to pass environment changes from a
  492. subshell back to its parent.
  493. .It { Ar list ; No }
  494. Compound construct;
  495. .Ar list
  496. is executed, but not in a subshell.
  497. Note that
  498. .Ql {
  499. and
  500. .Ql }
  501. are reserved words, not meta-characters.
  502. .It Xo Ic case Ar word Cm in
  503. .Oo Op \&(
  504. .Ar pattern
  505. .Op | Ar pattern
  506. .No ... )
  507. .Ar list No ;;\ \& Oc ... Cm esac
  508. .Xc
  509. The
  510. .Ic case
  511. statement attempts to match
  512. .Ar word
  513. against a specified
  514. .Ar pattern ;
  515. the
  516. .Ar list
  517. associated with the first successfully matched pattern is executed.
  518. Patterns used in
  519. .Ic case
  520. statements are the same as those used for file name patterns except that the
  521. restrictions regarding
  522. .Ql \&.
  523. and
  524. .Ql /
  525. are dropped.
  526. Note that any unquoted space before and after a pattern is
  527. stripped; any space within a pattern must be quoted.
  528. Both the word and the
  529. patterns are subject to parameter, command, and arithmetic substitution, as
  530. well as tilde substitution.
  531. For historical reasons, open and close braces may be used instead of
  532. .Cm in
  533. and
  534. .Cm esac
  535. e.g.\&
  536. .Ic case $foo { *) echo bar; } .
  537. The exit status of a
  538. .Ic case
  539. statement is that of the executed
  540. .Ar list ;
  541. if no
  542. .Ar list
  543. is executed, the exit status is zero.
  544. .It Xo Ic for Ar name
  545. .Op Cm in Op Ar word ... ;
  546. .Cm do Ar list ; Cm done
  547. .Xc
  548. For each
  549. .Ar word
  550. in the specified word list, the parameter
  551. .Ar name
  552. is set to the word and
  553. .Ar list
  554. is executed.
  555. If
  556. .Cm in
  557. is not used to specify a word list, the positional parameters
  558. ($1, $2, etc.)\&
  559. are used instead.
  560. For historical reasons, open and close braces may be used instead of
  561. .Cm do
  562. and
  563. .Cm done
  564. e.g.\&
  565. .Ic for i; { echo $i; } .
  566. The exit status of a
  567. .Ic for
  568. statement is the last exit status of
  569. .Ar list .
  570. If there are no items,
  571. .Ar list
  572. is not executed and the exit status is zero.
  573. .It Xo Ic if Ar list ;
  574. .Cm then Ar list ;
  575. .Oo Cm elif Ar list ;
  576. .Cm then Ar list ; Oc ...
  577. .Oo Cm else Ar list ; Oc
  578. .Cm fi
  579. .Xc
  580. If the exit status of the first
  581. .Ar list
  582. is zero, the second
  583. .Ar list
  584. is executed; otherwise, the
  585. .Ar list
  586. following the
  587. .Cm elif ,
  588. if any, is executed with similar consequences.
  589. If all the lists following the
  590. .Ic if
  591. and
  592. .Cm elif Ns s
  593. fail (i.e. exit with non-zero status), the
  594. .Ar list
  595. following the
  596. .Cm else
  597. is executed.
  598. The exit status of an
  599. .Ic if
  600. statement is that of non-conditional
  601. .Ar list
  602. that is executed; if no non-conditional
  603. .Ar list
  604. is executed, the exit status is zero.
  605. .It Xo Ic select Ar name
  606. .Oo Cm in Ar word No ... Oc ;
  607. .Cm do Ar list ; Cm done
  608. .Xc
  609. The
  610. .Ic select
  611. statement provides an automatic method of presenting the user with a menu and
  612. selecting from it.
  613. An enumerated list of the specified
  614. .Ar word Ns (s)
  615. is printed on standard error, followed by a prompt
  616. .Po
  617. .Ev PS3 :
  618. normally
  619. .Sq #?\ \&
  620. .Pc .
  621. A number corresponding to one of the enumerated words is then read from
  622. standard input,
  623. .Ar name
  624. is set to the selected word (or unset if the selection is not valid),
  625. .Ev REPLY
  626. is set to what was read (leading/trailing space is stripped), and
  627. .Ar list
  628. is executed.
  629. If a blank line (i.e. zero or more
  630. .Ev IFS
  631. characters) is entered, the menu is reprinted without executing
  632. .Ar list .
  633. .Pp
  634. When
  635. .Ar list
  636. completes, the enumerated list is printed if
  637. .Ev REPLY
  638. is
  639. .Dv NULL ,
  640. the prompt is printed, and so on.
  641. This process continues until an end-of-file
  642. is read, an interrupt is received, or a
  643. .Ic break
  644. statement is executed inside the loop.
  645. If
  646. .Dq in word ...
  647. is omitted, the positional parameters are used
  648. (i.e. $1, $2, etc.).
  649. For historical reasons, open and close braces may be used instead of
  650. .Cm do
  651. and
  652. .Cm done
  653. e.g.\&
  654. .Ic select i; { echo $i; } .
  655. The exit status of a
  656. .Ic select
  657. statement is zero if a
  658. .Ic break
  659. statement is used to exit the loop, non-zero otherwise.
  660. .It Xo Ic until Ar list ;
  661. .Cm do Ar list ;
  662. .Cm done
  663. .Xc
  664. This works like
  665. .Ic while ,
  666. except that the body is executed only while the exit status of the first
  667. .Ar list
  668. is non-zero.
  669. .It Xo Ic while Ar list ;
  670. .Cm do Ar list ;
  671. .Cm done
  672. .Xc
  673. A
  674. .Ic while
  675. is a pre-checked loop.
  676. Its body is executed as often as the exit status of the first
  677. .Ar list
  678. is zero.
  679. The exit status of a
  680. .Ic while
  681. statement is the last exit status of the
  682. .Ar list
  683. in the body of the loop; if the body is not executed, the exit status is zero.
  684. .It Xo Ic function Ar name
  685. .No { Ar list ; No }
  686. .Xc
  687. Defines the function
  688. .Ar name
  689. (see
  690. .Sx Functions
  691. below).
  692. Note that redirections specified after a function definition are
  693. performed whenever the function is executed, not when the function definition
  694. is executed.
  695. .It Ar name Ns () Ar command
  696. Mostly the same as
  697. .Ic function
  698. (see
  699. .Sx Functions
  700. below).
  701. .It Xo Ic time Op Fl p
  702. .Op Ar pipeline
  703. .Xc
  704. The
  705. .Ic time
  706. reserved word is described in the
  707. .Sx Command execution
  708. section.
  709. .It Ic (( Ar expression Cm ))
  710. The arithmetic expression
  711. .Ar expression
  712. is evaluated; equivalent to
  713. .Ic let Ar expression
  714. (see
  715. .Sx Arithmetic expressions
  716. and the
  717. .Ic let
  718. command, below).
  719. .It Ic [[ Ar expression Cm ]]
  720. Similar to the
  721. .Ic test
  722. and
  723. .Ic \&[ No ... Cm \&]
  724. commands (described later), with the following exceptions:
  725. .Bl -bullet -offset indent
  726. .It
  727. Field splitting and file name generation are not performed on arguments.
  728. .It
  729. The
  730. .Fl a
  731. .Pq AND
  732. and
  733. .Fl o
  734. .Pq OR
  735. operators are replaced with
  736. .Ql &&
  737. and
  738. .Ql || ,
  739. respectively.
  740. .It
  741. Operators (e.g.\&
  742. .Sq Fl f ,
  743. .Sq = ,
  744. .Sq \&! )
  745. must be unquoted.
  746. .It
  747. The second operand of the
  748. .Sq = ,
  749. .Sq ==
  750. and
  751. .Sq !=
  752. expressions are patterns (e.g. the comparison
  753. .Ic [[ foobar = f*r ]]
  754. succeeds).
  755. .It
  756. The
  757. .Ql <
  758. and
  759. .Ql >
  760. binary operators do not need to be quoted with the
  761. .Ql \e
  762. character.
  763. .It
  764. The single argument form of
  765. .Ic test ,
  766. which tests if the argument has a non-zero length, is not valid; explicit
  767. operators must always be used e.g. instead of
  768. .No \&[ Ar str No \&]
  769. use
  770. .No \&[[ -n Ar str No \&]] .
  771. .It
  772. Parameter, command, and arithmetic substitutions are performed as expressions
  773. are evaluated and lazy expression evaluation is used for the
  774. .Ql &&
  775. and
  776. .Ql ||
  777. operators.
  778. This means that in the following statement,
  779. .Ic $(< foo)
  780. is evaluated if and only if the file
  781. .Pa foo
  782. exists and is readable:
  783. .Bd -literal -offset indent
  784. $ [[ -r foo && $(< foo) = b*r ]]
  785. .Ed
  786. .El
  787. .El
  788. .Ss Quoting
  789. Quoting is used to prevent the shell from treating characters or words
  790. specially.
  791. There are three methods of quoting.
  792. First,
  793. .Ql \e
  794. quotes the following character, unless it is at the end of a line, in which
  795. case both the
  796. .Ql \e
  797. and the newline are stripped.
  798. Second, a single quote
  799. .Pq Sq '
  800. quotes everything up to the next single quote (this may span lines).
  801. Third, a double quote
  802. .Pq Sq \&"
  803. quotes all characters, except
  804. .Ql $ ,
  805. .Ql `
  806. and
  807. .Ql \e ,
  808. up to the next unquoted double quote.
  809. .Ql $
  810. and
  811. .Ql `
  812. inside double quotes have their usual meaning (i.e. parameter, command, or
  813. arithmetic substitution) except no field splitting is carried out on the
  814. results of double-quoted substitutions.
  815. If a
  816. .Ql \e
  817. inside a double-quoted string is followed by
  818. .Ql \e ,
  819. .Ql $ ,
  820. .Ql ` ,
  821. or
  822. .Ql \&" ,
  823. it is replaced by the second character; if it is followed by a newline, both
  824. the
  825. .Ql \e
  826. and the newline are stripped; otherwise, both the
  827. .Ql \e
  828. and the character following are unchanged.
  829. .Ss Aliases
  830. There are two types of aliases: normal command aliases and tracked aliases.
  831. Command aliases are normally used as a short hand for a long or often used
  832. command.
  833. The shell expands command aliases (i.e. substitutes the alias name
  834. for its value) when it reads the first word of a command.
  835. An expanded alias is re-processed to check for more aliases.
  836. If a command alias ends in a
  837. space or tab, the following word is also checked for alias expansion.
  838. The alias expansion process stops when a word that is not an alias is found,
  839. when a quoted word is found, or when an alias word that is currently being
  840. expanded is found.
  841. .Pp
  842. The following command aliases are defined automatically by the shell:
  843. .Pp
  844. .Bl -item -compact -offset indent
  845. .It
  846. .Ic autoload Ns ='typeset -fu'
  847. .It
  848. .Ic functions Ns ='typeset -f'
  849. .It
  850. .Ic hash Ns ='alias -t'
  851. .It
  852. .Ic history Ns ='fc -l'
  853. .It
  854. .Ic integer Ns ='typeset -i'
  855. .It
  856. .Ic local Ns ='typeset'
  857. .It
  858. .Ic login Ns ='exec login'
  859. .It
  860. .Ic nohup Ns ='nohup '
  861. .It
  862. .Ic r Ns ='fc -s'
  863. .It
  864. .Ic stop Ns ='kill -STOP'
  865. .El
  866. .Pp
  867. Tracked aliases allow the shell to remember where it found a particular
  868. command.
  869. The first time the shell does a path search for a command that is
  870. marked as a tracked alias, it saves the full path of the command.
  871. The next
  872. time the command is executed, the shell checks the saved path to see that it
  873. is still valid, and if so, avoids repeating the path search.
  874. Tracked aliases can be listed and created using
  875. .Ic alias -t .
  876. Note that changing the
  877. .Ev PATH
  878. parameter clears the saved paths for all tracked aliases.
  879. If the
  880. .Ic trackall
  881. option is set (i.e.\&
  882. .Ic set -o Ic trackall
  883. or
  884. .Ic set -h ) ,
  885. the shell tracks all commands.
  886. This option is set automatically for non-interactive shells.
  887. For interactive shells, only the following commands are
  888. automatically tracked:
  889. .Xr cat 1 ,
  890. .Xr cc 1 ,
  891. .Xr chmod 1 ,
  892. .Xr cp 1 ,
  893. .Xr date 1 ,
  894. .Xr ed 1 ,
  895. .Sy emacs ,
  896. .Xr grep 1 ,
  897. .Xr ls 1 ,
  898. .Xr mail 1 ,
  899. .Xr make 1 ,
  900. .Xr mv 1 ,
  901. .Xr pr 1 ,
  902. .Xr rm 1 ,
  903. .Xr sed 1 ,
  904. .Xr sh 1 ,
  905. .Xr vi 1 ,
  906. and
  907. .Xr who 1 .
  908. .Ss Substitution
  909. The first step the shell takes in executing a simple-command is to perform
  910. substitutions on the words of the command.
  911. There are three kinds of
  912. substitution: parameter, command, and arithmetic.
  913. Parameter substitutions,
  914. which are described in detail in the next section, take the form
  915. .Pf $ Ar name
  916. or
  917. .Pf ${ Ar ... Ns } ;
  918. command substitutions take the form
  919. .Pf $( Ar command )
  920. or
  921. .Pf ` Ar command Ns ` ;
  922. and arithmetic substitutions take the form
  923. .Pf $(( Ar expression ) ) .
  924. .Pp
  925. If a substitution appears outside of double quotes, the results of the
  926. substitution are generally subject to word or field splitting according to
  927. the current value of the
  928. .Ev IFS
  929. parameter.
  930. The
  931. .Ev IFS
  932. parameter specifies a list of characters which are used to break a string up
  933. into several words; any characters from the set space, tab, and newline that
  934. appear in the
  935. .Ev IFS
  936. characters are called
  937. .Dq IFS whitespace .
  938. Sequences of one or more
  939. .Ev IFS
  940. whitespace characters, in combination with zero or one
  941. .Pf non- Ev IFS
  942. whitespace
  943. characters, delimit a field.
  944. As a special case, leading and trailing
  945. .Ev IFS
  946. whitespace is stripped (i.e. no leading or trailing empty field is created by
  947. it); leading
  948. .Pf non- Ev IFS
  949. whitespace does create an empty field.
  950. .Pp
  951. Example: If
  952. .Ev IFS
  953. is set to
  954. .Dq <space>: ,
  955. and VAR is set to
  956. .Dq <space>A<space>:<space><space>B::D ,
  957. the substitution for $VAR results in four fields:
  958. .Sq A ,
  959. .Sq B ,
  960. .Sq
  961. (an empty field),
  962. and
  963. .Sq D .
  964. Note that if the
  965. .Ev IFS
  966. parameter is set to the
  967. .Dv NULL
  968. string, no field splitting is done; if the parameter is unset, the default
  969. value of space, tab, and newline is used.
  970. .Pp
  971. Also, note that the field splitting applies only to the immediate result of
  972. the substitution.
  973. Using the previous example, the substitution for $VAR:E
  974. results in the fields:
  975. .Sq A ,
  976. .Sq B ,
  977. .Sq ,
  978. and
  979. .Sq D:E ,
  980. not
  981. .Sq A ,
  982. .Sq B ,
  983. .Sq ,
  984. .Sq D ,
  985. and
  986. .Sq E .
  987. This behavior is POSIX compliant, but incompatible with some other shell
  988. implementations which do field splitting on the word which contained the
  989. substitution or use
  990. .Dv IFS
  991. as a general whitespace delimiter.
  992. .Pp
  993. The results of substitution are, unless otherwise specified, also subject to
  994. brace expansion and file name expansion (see the relevant sections below).
  995. .Pp
  996. A command substitution is replaced by the output generated by the specified
  997. command, which is run in a subshell.
  998. For
  999. .Pf $( Ar command )
  1000. substitutions, normal quoting rules are used when
  1001. .Ar command
  1002. is parsed; however, for the
  1003. .Pf ` Ar command Ns `
  1004. form, a
  1005. .Ql \e
  1006. followed by any of
  1007. .Ql $ ,
  1008. .Ql ` ,
  1009. or
  1010. .Ql \e
  1011. is stripped (a
  1012. .Ql \e
  1013. followed by any other character is unchanged).
  1014. As a special case in command substitutions, a command of the form
  1015. .Pf < Ar file
  1016. is interpreted to mean substitute the contents of
  1017. .Ar file .
  1018. Note that
  1019. .Ic $(< foo)
  1020. has the same effect as
  1021. .Ic $(cat foo) ,
  1022. but it is carried out more efficiently because no process is started.
  1023. .Pp
  1024. Arithmetic substitutions are replaced by the value of the specified expression.
  1025. For example, the command
  1026. .Ic echo $((2+3*4))
  1027. prints 14.
  1028. See
  1029. .Sx Arithmetic expressions
  1030. for a description of an expression.
  1031. .Ss Parameters
  1032. Parameters are shell variables; they can be assigned values and their values
  1033. can be accessed using a parameter substitution.
  1034. A parameter name is either one
  1035. of the special single punctuation or digit character parameters described
  1036. below, or a letter followed by zero or more letters or digits
  1037. .Po
  1038. .Ql _
  1039. counts as a letter
  1040. .Pc .
  1041. The latter form can be treated as arrays by appending an array index of the
  1042. form
  1043. .Op Ar expr
  1044. where
  1045. .Ar expr
  1046. is an arithmetic expression.
  1047. Parameter substitutions take the form
  1048. .Pf $ Ar name ,
  1049. .Pf ${ Ar name Ns } ,
  1050. or
  1051. .Sm off
  1052. .Pf ${ Ar name Bo Ar expr Bc }
  1053. .Sm on
  1054. where
  1055. .Ar name
  1056. is a parameter name.
  1057. If
  1058. .Ar expr
  1059. is a literal
  1060. .Ql @
  1061. then the named array is expanded using the same quoting rules as
  1062. .Ql $@ ,
  1063. while if
  1064. .Ar expr
  1065. is a literal
  1066. .Ql *
  1067. then the named array is expanded using the same quoting rules as
  1068. .Ql $* .
  1069. If substitution is performed on a parameter
  1070. (or an array parameter element)
  1071. that is not set, a null string is substituted unless the
  1072. .Ic nounset
  1073. option
  1074. .Po
  1075. .Ic set Fl o Ic nounset
  1076. or
  1077. .Ic set Fl u
  1078. .Pc
  1079. is set, in which case an error occurs.
  1080. .Pp
  1081. Parameters can be assigned values in a number of ways.
  1082. First, the shell implicitly sets some parameters like
  1083. .Ql # ,
  1084. .Ql PWD ,
  1085. and
  1086. .Ql $ ;
  1087. this is the only way the special single character parameters are set.
  1088. Second, parameters are imported from the shell's environment at startup.
  1089. Third, parameters can be assigned values on the command line: for example,
  1090. .Ic FOO=bar
  1091. sets the parameter
  1092. .Dq FOO
  1093. to
  1094. .Dq bar ;
  1095. multiple parameter assignments can be given on a single command line and they
  1096. can be followed by a simple-command, in which case the assignments are in
  1097. effect only for the duration of the command (such assignments are also
  1098. exported; see below for the implications of this).
  1099. Note that both the parameter name and the
  1100. .Ql =
  1101. must be unquoted for the shell to recognize a parameter assignment.
  1102. The fourth way of setting a parameter is with the
  1103. .Ic export ,
  1104. .Ic readonly ,
  1105. and
  1106. .Ic typeset
  1107. commands; see their descriptions in the
  1108. .Sx Command execution
  1109. section.
  1110. Fifth,
  1111. .Ic for
  1112. and
  1113. .Ic select
  1114. loops set parameters as well as the
  1115. .Ic getopts ,
  1116. .Ic read ,
  1117. and
  1118. .Ic set -A
  1119. commands.
  1120. Lastly, parameters can be assigned values using assignment operators
  1121. inside arithmetic expressions (see
  1122. .Sx Arithmetic expressions
  1123. below) or using the
  1124. .Pf ${ Ar name Ns = Ns Ar value Ns }
  1125. form of the parameter substitution (see below).
  1126. .Pp
  1127. Parameters with the export attribute (set using the
  1128. .Ic export
  1129. or
  1130. .Ic typeset Fl x
  1131. commands, or by parameter assignments followed by simple commands) are put in
  1132. the environment (see
  1133. .Xr environ 7 )
  1134. of commands run by the shell as
  1135. .Ar name Ns = Ns Ar value
  1136. pairs.
  1137. The order in which parameters appear in the environment of a command is
  1138. unspecified.
  1139. When the shell starts up, it extracts parameters and their values
  1140. from its environment and automatically sets the export attribute for those
  1141. parameters.
  1142. .Pp
  1143. Modifiers can be applied to the
  1144. .Pf ${ Ar name Ns }
  1145. form of parameter substitution:
  1146. .Bl -tag -width Ds
  1147. .Sm off
  1148. .It ${ Ar name No :- Ar word No }
  1149. .Sm on
  1150. If
  1151. .Ar name
  1152. is set and not
  1153. .Dv NULL ,
  1154. it is substituted; otherwise,
  1155. .Ar word
  1156. is substituted.
  1157. .Sm off
  1158. .It ${ Ar name No :+ Ar word No }
  1159. .Sm on
  1160. If
  1161. .Ar name
  1162. is set and not
  1163. .Dv NULL ,
  1164. .Ar word
  1165. is substituted; otherwise, nothing is substituted.
  1166. .Sm off
  1167. .It ${ Ar name No := Ar word No }
  1168. .Sm on
  1169. If
  1170. .Ar name
  1171. is set and not
  1172. .Dv NULL ,
  1173. it is substituted; otherwise, it is assigned
  1174. .Ar word
  1175. and the resulting value of
  1176. .Ar name
  1177. is substituted.
  1178. .Sm off
  1179. .It ${ Ar name No :? Ar word No }
  1180. .Sm on
  1181. If
  1182. .Ar name
  1183. is set and not
  1184. .Dv NULL ,
  1185. it is substituted; otherwise,
  1186. .Ar word
  1187. is printed on standard error (preceded by
  1188. .Ar name : )
  1189. and an error occurs (normally causing termination of a shell script, function,
  1190. or script sourced using the
  1191. .Sq Ic \&.
  1192. built-in command).
  1193. If
  1194. .Ar word
  1195. is omitted, the string
  1196. .Dq parameter null or not set
  1197. is used instead.
  1198. .El
  1199. .Pp
  1200. In the above modifiers, the
  1201. .Ql \&:
  1202. can be omitted, in which case the conditions only depend on
  1203. .Ar name
  1204. being set (as opposed to set and not
  1205. .Dv NULL ) .
  1206. If
  1207. .Ar word
  1208. is needed, parameter, command, arithmetic, and tilde substitution are performed
  1209. on it; if
  1210. .Ar word
  1211. is not needed, it is not evaluated.
  1212. .Pp
  1213. The following forms of parameter substitution can also be used:
  1214. .Pp
  1215. .Bl -tag -width Ds -compact
  1216. .It Pf ${# Ar name Ns }
  1217. The number of positional parameters if
  1218. .Ar name
  1219. is
  1220. .Ql * ,
  1221. .Ql @ ,
  1222. or not specified; otherwise the length of the string value of parameter
  1223. .Ar name .
  1224. .Pp
  1225. .It Pf ${# Ar name Ns [*]}
  1226. .It Pf ${# Ar name Ns [@]}
  1227. The number of elements in the array
  1228. .Ar name .
  1229. .Pp
  1230. .It Pf ${ Ar name Ns # Ns Ar pattern Ns }
  1231. .It Pf ${ Ar name Ns ## Ns Ar pattern Ns }
  1232. If
  1233. .Ar pattern
  1234. matches the beginning of the value of parameter
  1235. .Ar name ,
  1236. the matched text is deleted from the result of substitution.
  1237. A single
  1238. .Ql #
  1239. results in the shortest match, and two
  1240. of them result in the longest match.
  1241. .Pp
  1242. .It Pf ${ Ar name Ns % Ns Ar pattern Ns }
  1243. .It Pf ${ Ar name Ns %% Ns Ar pattern Ns }
  1244. Like ${..#..} substitution, but it deletes from the end of the value.
  1245. .El
  1246. .Pp
  1247. The following special parameters are implicitly set by the shell and cannot be
  1248. set directly using assignments:
  1249. .Bl -tag -width "1 ... 9"
  1250. .It Ev \&!
  1251. Process ID of the last background process started.
  1252. If no background processes have been started, the parameter is not set.
  1253. .It Ev \&#
  1254. The number of positional parameters ($1, $2, etc.).
  1255. .It Ev \&$
  1256. The PID of the shell, or the PID of the original shell if it is a subshell.
  1257. Do
  1258. .Em NOT
  1259. use this mechanism for generating temporary file names; see
  1260. .Xr mktemp 1
  1261. instead.
  1262. .It Ev -
  1263. The concatenation of the current single letter options (see the
  1264. .Ic set
  1265. command below for a list of options).
  1266. .It Ev \&?
  1267. The exit status of the last non-asynchronous command executed.
  1268. If the last command was killed by a signal,
  1269. .Ic $?\&
  1270. is set to 128 plus the signal number.
  1271. .It Ev 0
  1272. The name of the shell, determined as follows:
  1273. the first argument to
  1274. .Nm
  1275. if it was invoked with the
  1276. .Fl c
  1277. option and arguments were given; otherwise the
  1278. .Ar file
  1279. argument, if it was supplied;
  1280. or else the basename the shell was invoked with (i.e.\&
  1281. .Li argv[0] ) .
  1282. .Ev $0
  1283. is also set to the name of the current script or
  1284. the name of the current function, if it was defined with the
  1285. .Ic function
  1286. keyword (i.e. a Korn shell style function).
  1287. .It Ev 1 No ... Ev 9
  1288. The first nine positional parameters that were supplied to the shell, function,
  1289. or script sourced using the
  1290. .Sq Ic \&.
  1291. built-in command.
  1292. Further positional parameters may be accessed using
  1293. .Pf ${ Ar number Ns } .
  1294. .It Ev *
  1295. All positional parameters (except parameter 0) i.e. $1, $2, $3, ...
  1296. If used
  1297. outside of double quotes, parameters are separate words (which are subjected
  1298. to word splitting); if used within double quotes, parameters are separated
  1299. by the first character of the
  1300. .Ev IFS
  1301. parameter (or the empty string if
  1302. .Ev IFS
  1303. is
  1304. .Dv NULL ) .
  1305. .It Ev @
  1306. Same as
  1307. .Ic $* ,
  1308. unless it is used inside double quotes, in which case a separate word is
  1309. generated for each positional parameter.
  1310. If there are no positional parameters, no word is generated.
  1311. .Ic $@
  1312. can be used to access arguments, verbatim, without losing
  1313. .Dv NULL
  1314. arguments or splitting arguments with spaces.
  1315. .El
  1316. .Pp
  1317. The following parameters are set and/or used by the shell:
  1318. .Bl -tag -width "EXECSHELL"
  1319. .It Ev _ No (underscore)
  1320. When an external command is executed by the shell, this parameter is set in the
  1321. environment of the new process to the path of the executed command.
  1322. In interactive use, this parameter is also set in the parent shell to the last
  1323. word of the previous command.
  1324. When
  1325. .Ev MAILPATH
  1326. messages are evaluated, this parameter contains the name of the file that
  1327. changed (see the
  1328. .Ev MAILPATH
  1329. parameter, below).
  1330. .It Ev CDPATH
  1331. Search path for the
  1332. .Ic cd
  1333. built-in command.
  1334. It works the same way as
  1335. .Ev PATH
  1336. for those directories not beginning with
  1337. .Ql /
  1338. or
  1339. .Ql .\&
  1340. in
  1341. .Ic cd
  1342. commands.
  1343. Note that if
  1344. .Ev CDPATH
  1345. is set and does not contain
  1346. .Sq \&.
  1347. or an empty path, the current directory is not searched.
  1348. Also, the
  1349. .Ic cd
  1350. built-in command will display the resulting directory when a match is found
  1351. in any search path other than the empty path.
  1352. .It Ev COLUMNS
  1353. Set to the number of columns on the terminal or window.
  1354. Currently set to the
  1355. .Dq cols
  1356. value as reported by
  1357. .Xr stty 1
  1358. if that value is non-zero.
  1359. This parameter is used by the interactive line editing modes, and by the
  1360. .Ic select ,
  1361. .Ic set -o ,
  1362. and
  1363. .Ic kill -l
  1364. commands to format information columns.
  1365. .It Ev EDITOR
  1366. If the
  1367. .Ev VISUAL
  1368. parameter is not set, this parameter controls the command-line editing mode for
  1369. interactive shells.
  1370. See the
  1371. .Ev VISUAL
  1372. parameter below for how this works.
  1373. .Pp
  1374. Note:
  1375. traditionally,
  1376. .Ev EDITOR
  1377. was used to specify the name of an (old-style) line editor, such as
  1378. .Xr ed 1 ,
  1379. and
  1380. .Ev VISUAL
  1381. was used to specify a (new-style) screen editor, such as
  1382. .Xr vi 1 .
  1383. Hence if
  1384. .Ev VISUAL
  1385. is set, it overrides
  1386. .Ev EDITOR .
  1387. .It Ev ENV
  1388. If this parameter is found to be set after any profile files are executed, the
  1389. expanded value is used as a shell startup file.
  1390. It typically contains function and alias definitions.
  1391. .It Ev EXECSHELL
  1392. If set, this parameter is assumed to contain the shell that is to be used to
  1393. execute commands that
  1394. .Xr execve 2
  1395. fails to execute and which do not start with a
  1396. .Dq #! Ns Ar shell
  1397. sequence.
  1398. .It Ev FCEDIT
  1399. The editor used by the
  1400. .Ic fc
  1401. command (see below).
  1402. .It Ev FPATH
  1403. Like
  1404. .Ev PATH ,
  1405. but used when an undefined function is executed to locate the file defining the
  1406. function.
  1407. It is also searched when a command can't be found using
  1408. .Ev PATH .
  1409. See
  1410. .Sx Functions
  1411. below for more information.
  1412. .It Ev HISTCONTROL
  1413. A colon separated list of history settings.
  1414. If
  1415. .Sy ignoredups
  1416. is present, lines identical to the previous history line will not be saved.
  1417. If
  1418. .Sy ignorespace
  1419. is present, lines starting with a space will not be saved.
  1420. Unknown settings are ignored.
  1421. .It Ev HISTFILE
  1422. The name of the file used to store command history.
  1423. When assigned to, history is loaded from the specified file.
  1424. Also, several invocations of the shell
  1425. running on the same machine will share history if their
  1426. .Ev HISTFILE
  1427. parameters all point to the same file.
  1428. .Pp
  1429. .Sy Note :
  1430. If
  1431. .Ev HISTFILE
  1432. isn't set, no history file is used.
  1433. This is different from the original Korn shell, which uses
  1434. .Pa $HOME/.sh_history .
  1435. .It Ev HISTSIZE
  1436. The number of commands normally stored for history.
  1437. The default is 500.
  1438. .It Ev HOME
  1439. The default directory for the
  1440. .Ic cd
  1441. command and the value substituted for an unqualified
  1442. .Ic ~
  1443. (see
  1444. .Sx Tilde expansion
  1445. below).
  1446. .It Ev IFS
  1447. Internal field separator, used during substitution and by the
  1448. .Ic read
  1449. command, to split values into distinct arguments; normally set to space, tab,
  1450. and newline.
  1451. See
  1452. .Sx Substitution
  1453. above for details.
  1454. .Pp
  1455. .Sy Note :
  1456. This parameter is not imported from the environment when the shell is
  1457. started.
  1458. .It Ev KSH_VERSION
  1459. The version of the shell and the date the version was created (read-only).
  1460. .It Ev LINENO
  1461. The line number of the function or shell script that is currently being
  1462. executed.
  1463. .It Ev LINES
  1464. Set to the number of lines on the terminal or window.
  1465. .It Ev MAIL
  1466. If set, the user will be informed of the arrival of mail in the named file.
  1467. This parameter is ignored if the
  1468. .Ev MAILPATH
  1469. parameter is set.
  1470. .It Ev MAILCHECK
  1471. How often, in seconds, the shell will check for mail in the file(s) specified
  1472. by
  1473. .Ev MAIL
  1474. or
  1475. .Ev MAILPATH .
  1476. If set to 0, the shell checks before each prompt.
  1477. The default is 600 (10 minutes).
  1478. .It Ev MAILPATH
  1479. A list of files to be checked for mail.
  1480. The list is colon separated, and each file may be followed by a
  1481. .Ql \&?
  1482. and a message to be printed if new mail has arrived.
  1483. Command, parameter, and
  1484. arithmetic substitution is performed on the message and, during substitution,
  1485. the parameter
  1486. .Ic $_
  1487. contains the name of the file.
  1488. The default message is
  1489. .Dq you have mail in $_ .
  1490. .It Ev OLDPWD
  1491. The previous working directory.
  1492. Unset if
  1493. .Ic cd
  1494. has not successfully changed directories since the shell started, or if the
  1495. shell doesn't know where it is.
  1496. .It Ev OPTARG
  1497. When using
  1498. .Ic getopts ,
  1499. it contains the argument for a parsed option, if it requires one.
  1500. .It Ev OPTIND
  1501. The index of the next argument to be processed when using
  1502. .Ic getopts .
  1503. Assigning 1 to this parameter causes
  1504. .Ic getopts
  1505. to process arguments from the beginning the next time it is invoked.
  1506. .It Ev PATH
  1507. A colon separated list of directories that are searched when looking for
  1508. commands and files sourced using the
  1509. .Sq \&.
  1510. command (see below).
  1511. An empty string resulting from a leading or trailing
  1512. colon, or two adjacent colons, is treated as a
  1513. .Sq \&.
  1514. (the current directory).
  1515. .It Ev POSIXLY_CORRECT
  1516. If set, this parameter causes the
  1517. .Ic posix
  1518. option to be enabled.
  1519. See
  1520. .Sx POSIX mode
  1521. below.
  1522. .It Ev PPID
  1523. The process ID of the shell's parent (read-only).
  1524. .It Ev PS1
  1525. The primary prompt for interactive shells.
  1526. Parameter, command, and arithmetic
  1527. substitutions are performed,
  1528. and the prompt string can be customised using
  1529. backslash-escaped special characters.
  1530. .Pp
  1531. Note that since the command-line editors try to figure out how long the prompt
  1532. is (so they know how far it is to the edge of the screen), escape codes in
  1533. the prompt tend to mess things up.
  1534. You can tell the shell not to count certain
  1535. sequences (such as escape codes) by using the
  1536. .Sy \e[ Ns Ar ... Ns Sy \e]
  1537. substitution (see below) or by prefixing your prompt with a non-printing
  1538. character (such as control-A) followed by a carriage return and then delimiting
  1539. the escape codes with this non-printing character.
  1540. By the way, don't blame me for
  1541. this hack; it's in the original
  1542. .Nm .
  1543. .Pp
  1544. The default prompt is the first part of the hostname, followed by
  1545. .Sq $\ \&
  1546. for non-root users,
  1547. .Sq #\ \&
  1548. for root.
  1549. .Pp
  1550. The following backslash-escaped special characters can be used
  1551. to customise the prompt:
  1552. .Pp
  1553. .Bl -tag -width "\eD{format}XX" -compact
  1554. .It Sy \ea
  1555. Insert an ASCII bell character.
  1556. .It Sy \ed
  1557. The current date, in the format
  1558. .Dq Day Month Date
  1559. for example
  1560. .Dq Wed Nov 03 .
  1561. .It Sy \eD Ns Brq Ar format
  1562. The current date, with
  1563. .Ar format
  1564. converted by
  1565. .Xr strftime 3 .
  1566. The braces must be specified.
  1567. .It Sy \ee
  1568. Insert an ASCII escape character.
  1569. .It Sy \eh
  1570. The hostname, minus domain name.
  1571. .It Sy \eH
  1572. The full hostname, including domain name.
  1573. .It Sy \ej
  1574. Current number of jobs running
  1575. (see
  1576. .Sx Job control
  1577. below).
  1578. .It Sy \el
  1579. The controlling terminal.
  1580. .It Sy \en
  1581. Insert a newline character.
  1582. .It Sy \er
  1583. Insert a carriage return character.
  1584. .It Sy \es
  1585. The name of the shell.
  1586. .It Sy \et
  1587. The current time, in 24-hour HH:MM:SS format.
  1588. .It Sy \eT
  1589. The current time, in 12-hour HH:MM:SS format.
  1590. .It Sy \e@
  1591. The current time, in 12-hour HH:MM:SS AM/PM format.
  1592. .It Sy \eA
  1593. The current time, in 24-hour HH:MM format.
  1594. .It Sy \eu
  1595. The current user's username.
  1596. .It Sy \ev
  1597. The current version of
  1598. .Nm .
  1599. .It Sy \eV
  1600. Like
  1601. .Sy \ev ,
  1602. but more verbose.
  1603. .It Sy \ew
  1604. The current working directory.
  1605. .Dv $HOME
  1606. is abbreviated as
  1607. .Sq ~ .
  1608. .It Sy \eW
  1609. The basename of
  1610. the current working directory.
  1611. .Dv $HOME
  1612. is abbreviated as
  1613. .Sq ~ .
  1614. .It Sy \e!
  1615. The current history number.
  1616. An unescaped
  1617. .Sq Sy !\&
  1618. will produce the current history number too,
  1619. as per the POSIX specification.
  1620. A literal
  1621. .Ql \&!
  1622. can be put in the prompt by placing
  1623. .Sq Sy !!
  1624. in
  1625. .Ev PS1 .
  1626. .It Sy \e#
  1627. The current command number.
  1628. This could be different to the current history number,
  1629. if
  1630. .Ev HISTFILE
  1631. contains a history list from a previous session.
  1632. .It Sy \e$
  1633. The default prompt character i.e.\&
  1634. .Sq #
  1635. if the effective UID is 0,
  1636. otherwise
  1637. .Sq $ .
  1638. Since the shell interprets
  1639. .Sq $
  1640. as a special character within double quotes,
  1641. it is safer in this case to escape the backslash
  1642. than to try quoting it.
  1643. .It Sy \e Ns Ar nnn
  1644. The octal character
  1645. .Ar nnn .
  1646. .It Sy \e\e
  1647. Insert a single backslash character.
  1648. .It Sy \e[
  1649. Normally the shell keeps track of the number of characters in the prompt.
  1650. Use of this sequence turns off that count.
  1651. .It Sy \e]
  1652. Use of this sequence turns the count back on.
  1653. .El
  1654. .Pp
  1655. Note that the backslash itself may be interpreted by the shell.
  1656. Hence, to set
  1657. .Ev PS1
  1658. either escape the backslash itself,
  1659. or use double quotes.
  1660. The latter is more practical:
  1661. .Bd -literal -offset indent
  1662. PS1="\eu "
  1663. .Ed
  1664. .Pp
  1665. This is a more complex example,
  1666. which does not rely on the above backslash-escaped sequences.
  1667. It embeds the current working directory,
  1668. in reverse video,
  1669. in the prompt string:
  1670. .Bd -literal -offset indent
  1671. x=$(print \e\e001)
  1672. PS1="$x$(print \e\er)$x$(tput so)$x\e$PWD$x$(tput se)$x> "
  1673. .Ed
  1674. .It Ev PS2
  1675. Secondary prompt string, by default
  1676. .Sq >\ \& ,
  1677. used when more input is needed to complete a command.
  1678. .It Ev PS3
  1679. Prompt used by the
  1680. .Ic select
  1681. statement when reading a menu selection.
  1682. The default is
  1683. .Sq #?\ \& .
  1684. .It Ev PS4
  1685. Used to prefix commands that are printed during execution tracing (see the
  1686. .Ic set Fl x
  1687. command below).
  1688. Parameter, command, and arithmetic substitutions are performed
  1689. before it is printed.
  1690. The default is
  1691. .Sq +\ \& .
  1692. .It Ev PWD
  1693. The current working directory.
  1694. May be unset or
  1695. .Dv NULL
  1696. if the shell doesn't know where it is.
  1697. .It Ev RANDOM
  1698. A random number generator.
  1699. Every time
  1700. .Ev RANDOM
  1701. is referenced, it is assigned the next random number in the range
  1702. 0\-32767.
  1703. By default,
  1704. .Xr arc4random 3
  1705. is used to produce values.
  1706. If the variable
  1707. .Ev RANDOM
  1708. is assigned a value, the value is used as the seed to
  1709. .Xr srand_deterministic 3
  1710. and subsequent references of
  1711. .Ev RANDOM
  1712. produce a predictable sequence.
  1713. .It Ev REPLY
  1714. Default parameter for the
  1715. .Ic read
  1716. command if no names are given.
  1717. Also used in
  1718. .Ic select
  1719. loops to store the value that is read from standard input.
  1720. .It Ev SECONDS
  1721. The number of seconds since the shell started or, if the parameter has been
  1722. assigned an integer value, the number of seconds since the assignment plus the
  1723. value that was assigned.
  1724. .It Ev TERM
  1725. The user's terminal type.
  1726. If set, it will be used to determine the escape sequence used to
  1727. clear the screen.
  1728. .It Ev TMOUT
  1729. If set to a positive integer in an interactive shell, it specifies the maximum
  1730. number of seconds the shell will wait for input after printing the primary
  1731. prompt
  1732. .Pq Ev PS1 .
  1733. If the time is exceeded, the shell exits.
  1734. .It Ev TMPDIR
  1735. The directory temporary shell files are created in.
  1736. If this parameter is not
  1737. set, or does not contain the absolute path of a writable directory, temporary
  1738. files are created in
  1739. .Pa /tmp .
  1740. .It Ev VISUAL
  1741. If set, this parameter controls the command-line editing mode for interactive
  1742. shells.
  1743. If the last component of the path specified in this parameter contains
  1744. the string
  1745. .Dq vi ,
  1746. .Dq emacs ,
  1747. or
  1748. .Dq gmacs ,
  1749. the
  1750. .Xr vi 1 ,
  1751. emacs, or gmacs (Gosling emacs) editing mode is enabled, respectively.
  1752. See also the
  1753. .Ev EDITOR
  1754. parameter, above.
  1755. .El
  1756. .Ss Tilde expansion
  1757. Tilde expansion, which is done in parallel with parameter substitution, is done
  1758. on words starting with an unquoted
  1759. .Ql ~ .
  1760. The characters following the tilde, up to the first
  1761. .Ql / ,
  1762. if any, are assumed to be a login name.
  1763. If the login name is empty,
  1764. .Ql + ,
  1765. or
  1766. .Ql - ,
  1767. the value of the
  1768. .Ev HOME ,
  1769. .Ev PWD ,
  1770. or
  1771. .Ev OLDPWD
  1772. parameter is substituted, respectively.
  1773. Otherwise, the password file is
  1774. searched for the login name, and the tilde expression is substituted with the
  1775. user's home directory.
  1776. If the login name is not found in the password file or
  1777. if any quoting or parameter substitution occurs in the login name, no
  1778. substitution is performed.
  1779. .Pp
  1780. In parameter assignments
  1781. (such as those preceding a simple-command or those occurring
  1782. in the arguments of
  1783. .Ic alias ,
  1784. .Ic export ,
  1785. .Ic readonly ,
  1786. and
  1787. .Ic typeset ) ,
  1788. tilde expansion is done after any assignment
  1789. (i.e. after the equals sign)
  1790. or after an unquoted colon
  1791. .Pq Sq \&: ;
  1792. login names are also delimited by colons.
  1793. .Pp
  1794. The home directory of previously expanded login names are cached and re-used.
  1795. The
  1796. .Ic alias -d
  1797. command may be used to list, change, and add to this cache (e.g.\&
  1798. .Ic alias -d fac=/usr/local/facilities; cd ~fac/bin ) .
  1799. .Ss Brace expansion (alternation)
  1800. Brace expressions take the following form:
  1801. .Bd -unfilled -offset indent
  1802. .Sm off
  1803. .Ar prefix No { Ar str1 No ,...,
  1804. .Ar strN No } Ar suffix
  1805. .Sm on
  1806. .Ed
  1807. .Pp
  1808. The expressions are expanded to
  1809. .Ar N
  1810. words, each of which is the concatenation of
  1811. .Ar prefix ,
  1812. .Ar str Ns i ,
  1813. and
  1814. .Ar suffix
  1815. (e.g.\&
  1816. .Dq a{c,b{X,Y},d}e
  1817. expands to four words:
  1818. .Dq ace ,
  1819. .Dq abXe ,
  1820. .Dq abYe ,
  1821. and
  1822. .Dq ade ) .
  1823. As noted in the example, brace expressions can be nested and the resulting
  1824. words are not sorted.
  1825. Brace expressions must contain an unquoted comma
  1826. .Pq Sq \&,
  1827. for expansion to occur (e.g.\&
  1828. .Ic {}
  1829. and
  1830. .Ic {foo}
  1831. are not expanded).
  1832. Brace expansion is carried out after parameter substitution
  1833. and before file name generation.
  1834. .Ss File name patterns
  1835. A file name pattern is a word containing one or more unquoted
  1836. .Ql \&? ,
  1837. .Ql * ,
  1838. .Ql + ,
  1839. .Ql @ ,
  1840. or
  1841. .Ql \&!
  1842. characters or
  1843. .Dq [..]
  1844. sequences.
  1845. Once brace expansion has been performed, the shell replaces file
  1846. name patterns with the sorted names of all the files that match the pattern
  1847. (if no files match, the word is left unchanged).
  1848. The pattern elements have the following meaning:
  1849. .Bl -tag -width Ds
  1850. .It \&?
  1851. Matches any single character.
  1852. .It \&*
  1853. Matches any sequence of characters.
  1854. .It [..]
  1855. Matches any of the characters inside the brackets.
  1856. Ranges of characters can be
  1857. specified by separating two characters by a
  1858. .Ql -
  1859. (e.g.\&
  1860. .Dq [a0-9]
  1861. matches the letter
  1862. .Sq a
  1863. or any digit).
  1864. In order to represent itself, a
  1865. .Ql -
  1866. must either be quoted or the first or last character in the character list.
  1867. Similarly, a
  1868. .Ql \&]
  1869. must be quoted or the first character in the list if it is to represent itself
  1870. instead of the end of the list.
  1871. Also, a
  1872. .Ql \&!
  1873. appearing at the start of the list has special meaning (see below), so to
  1874. represent itself it must be quoted or appear later in the list.
  1875. .Pp
  1876. Within a bracket expression, the name of a
  1877. .Em character class
  1878. enclosed in
  1879. .Sq [:
  1880. and
  1881. .Sq :]
  1882. stands for the list of all characters belonging to that class.
  1883. Supported character classes:
  1884. .Bd -literal -offset indent
  1885. alnum cntrl lower space
  1886. alpha digit print upper
  1887. blank graph punct xdigit
  1888. .Ed
  1889. .Pp
  1890. These match characters using the macros specified in
  1891. .Xr isalnum 3 ,
  1892. .Xr isalpha 3 ,
  1893. and so on.
  1894. A character class may not be used as an endpoint of a range.
  1895. .It [!..]
  1896. Like [..],
  1897. except it matches any character not inside the brackets.
  1898. .Sm off
  1899. .It *( Ar pattern Ns | No ...| Ar pattern )
  1900. .Sm on
  1901. Matches any string of characters that matches zero or more occurrences of the
  1902. specified patterns.
  1903. Example: The pattern
  1904. .Ic *(foo|bar)
  1905. matches the strings
  1906. .Dq ,
  1907. .Dq foo ,
  1908. .Dq bar ,
  1909. .Dq foobarfoo ,
  1910. etc.
  1911. .Sm off
  1912. .It +( Ar pattern Ns | No ...| Ar pattern )
  1913. .Sm on
  1914. Matches any string of characters that matches one or more occurrences of the
  1915. specified patterns.
  1916. Example: The pattern
  1917. .Ic +(foo|bar)
  1918. matches the strings
  1919. .Dq foo ,
  1920. .Dq bar ,
  1921. .Dq foobar ,
  1922. etc.
  1923. .Sm off
  1924. .It ?( Ar pattern Ns | No ...| Ar pattern )
  1925. .Sm on
  1926. Matches the empty string or a string that matches one of the specified
  1927. patterns.
  1928. Example: The pattern
  1929. .Ic ?(foo|bar)
  1930. only matches the strings
  1931. .Dq ,
  1932. .Dq foo ,
  1933. and
  1934. .Dq bar .
  1935. .Sm off
  1936. .It @( Ar pattern Ns | No ...| Ar pattern )
  1937. .Sm on
  1938. Matches a string that matches one of the specified patterns.
  1939. Example: The pattern
  1940. .Ic @(foo|bar)
  1941. only matches the strings
  1942. .Dq foo
  1943. and
  1944. .Dq bar .
  1945. .Sm off
  1946. .It !( Ar pattern Ns | No ...| Ar pattern )
  1947. .Sm on
  1948. Matches any string that does not match one of the specified patterns.
  1949. Examples: The pattern
  1950. .Ic !(foo|bar)
  1951. matches all strings except
  1952. .Dq foo
  1953. and
  1954. .Dq bar ;
  1955. the pattern
  1956. .Ic !(*)
  1957. matches no strings; the pattern
  1958. .Ic !(?)*\&
  1959. matches all strings (think about it).
  1960. .El
  1961. .Pp
  1962. Unlike most shells,
  1963. .Nm ksh
  1964. never matches
  1965. .Sq \&.
  1966. and
  1967. .Sq .. .
  1968. .Pp
  1969. Note that none of the above pattern elements match either a period
  1970. .Pq Sq \&.
  1971. at the start of a file name or a slash
  1972. .Pq Sq / ,
  1973. even if they are explicitly used in a [..] sequence; also, the names
  1974. .Sq \&.
  1975. and
  1976. .Sq ..
  1977. are never matched, even by the pattern
  1978. .Sq .* .
  1979. .Pp
  1980. If the
  1981. .Ic markdirs
  1982. option is set, any directories that result from file name generation are marked
  1983. with a trailing
  1984. .Ql / .
  1985. .Ss Input/output redirection
  1986. When a command is executed, its standard input, standard output, and standard
  1987. error (file descriptors 0, 1, and 2, respectively) are normally inherited from
  1988. the shell.
  1989. Three exceptions to this are commands in pipelines, for which
  1990. standard input and/or standard output are those set up by the pipeline,
  1991. asynchronous commands created when job control is disabled, for which standard
  1992. input is initially set to be from
  1993. .Pa /dev/null ,
  1994. and commands for which any of the following redirections have been specified:
  1995. .Bl -tag -width Ds
  1996. .It Cm > Ar file
  1997. Standard output is redirected to
  1998. .Ar file .
  1999. If
  2000. .Ar file
  2001. does not exist, it is created; if it does exist, is a regular file, and the
  2002. .Ic noclobber
  2003. option is set, an error occurs; otherwise, the file is truncated.
  2004. Note that this means the command
  2005. .Ic cmd < foo > foo
  2006. will open
  2007. .Ar foo
  2008. for reading and then truncate it when it opens it for writing, before
  2009. .Ar cmd
  2010. gets a chance to actually read
  2011. .Ar foo .
  2012. .It Cm >| Ar file
  2013. Same as
  2014. .Cm > ,
  2015. except the file is truncated, even if the
  2016. .Ic noclobber
  2017. option is set.
  2018. .It Cm >> Ar file
  2019. Same as
  2020. .Cm > ,
  2021. except if
  2022. .Ar file
  2023. exists it is appended to instead of being truncated.
  2024. Also, the file is opened
  2025. in append mode, so writes always go to the end of the file (see
  2026. .Xr open 2 ) .
  2027. .It Cm < Ar file
  2028. Standard input is redirected from
  2029. .Ar file ,
  2030. which is opened for reading.
  2031. .It Cm <> Ar file
  2032. Same as
  2033. .Cm < ,
  2034. except the file is opened for reading and writing.
  2035. .It Cm << Ar marker
  2036. After reading the command line containing this kind of redirection (called a
  2037. .Dq here document ) ,
  2038. the shell copies lines from the command source into a temporary file until a
  2039. line matching
  2040. .Ar marker
  2041. is read.
  2042. When the command is executed, standard input is redirected from the
  2043. temporary file.
  2044. If
  2045. .Ar marker
  2046. contains no quoted characters, the contents of the temporary file are processed
  2047. as if enclosed in double quotes each time the command is executed, so
  2048. parameter, command, and arithmetic substitutions are performed, along with
  2049. backslash
  2050. .Pq Sq \e
  2051. escapes for
  2052. .Ql $ ,
  2053. .Ql ` ,
  2054. .Ql \e ,
  2055. and
  2056. .Ql \enewline .
  2057. If multiple here documents are used on the same command line, they are saved in
  2058. order.
  2059. .It Cm <<- Ar marker
  2060. Same as
  2061. .Cm << ,
  2062. except leading tabs are stripped from lines in the here document.
  2063. .It Cm <& Ar fd
  2064. Standard input is duplicated from file descriptor
  2065. .Ar fd .
  2066. .Ar fd
  2067. can be a single digit, indicating the number of an existing file descriptor;
  2068. the letter
  2069. .Ql p ,
  2070. indicating the file descriptor associated with the output of the current
  2071. co-process; or the character
  2072. .Ql - ,
  2073. indicating standard input is to be closed.
  2074. .It Cm >& Ar fd
  2075. Same as
  2076. .Cm <& ,
  2077. except the operation is done on standard output.
  2078. .El
  2079. .Pp
  2080. In any of the above redirections, the file descriptor that is redirected
  2081. (i.e. standard input or standard output)
  2082. can be explicitly given by preceding the
  2083. redirection with a single digit.
  2084. Parameter, command, and arithmetic
  2085. substitutions, tilde substitutions, and (if the shell is interactive)
  2086. file name generation are all performed on the
  2087. .Ar file ,
  2088. .Ar marker ,
  2089. and
  2090. .Ar fd
  2091. arguments of redirections.
  2092. Note, however, that the results of any file name
  2093. generation are only used if a single file is matched; if multiple files match,
  2094. the word with the expanded file name generation characters is used.
  2095. Note
  2096. that in restricted shells, redirections which can create files cannot be used.
  2097. .Pp
  2098. For simple-commands, redirections may appear anywhere in the command; for
  2099. compound-commands
  2100. .Po
  2101. .Ic if
  2102. statements, etc.
  2103. .Pc ,
  2104. any redirections must appear at the end.
  2105. Redirections are processed after
  2106. pipelines are created and in the order they are given, so the following
  2107. will print an error with a line number prepended to it:
  2108. .Pp
  2109. .D1 $ cat /foo/bar 2>&1 > /dev/null | cat -n
  2110. .Ss Arithmetic expressions
  2111. Integer arithmetic expressions can be used with the
  2112. .Ic let
  2113. command, inside $((..)) expressions, inside array references (e.g.\&
  2114. .Ar name Ns Bq Ar expr ) ,
  2115. as numeric arguments to the
  2116. .Ic test
  2117. command, and as the value of an assignment to an integer parameter.
  2118. .Pp
  2119. Expressions may contain alpha-numeric parameter identifiers, array references,
  2120. and integer constants and may be combined with the following C operators
  2121. (listed and grouped in increasing order of precedence):
  2122. .Pp
  2123. Unary operators:
  2124. .Bd -literal -offset indent
  2125. + - ! ~ ++ --
  2126. .Ed
  2127. .Pp
  2128. Binary operators:
  2129. .Bd -literal -offset indent
  2130. ,
  2131. = *= /= %= += -= <<= >>= &= ^= |=
  2132. ||
  2133. &&
  2134. |
  2135. ^
  2136. &
  2137. == !=
  2138. < <= >= >
  2139. << >>
  2140. + -
  2141. * / %
  2142. .Ed
  2143. .Pp
  2144. Ternary operators:
  2145. .Bd -literal -offset indent
  2146. ?: (precedence is immediately higher than assignment)
  2147. .Ed
  2148. .Pp
  2149. Grouping operators:
  2150. .Bd -literal -offset indent
  2151. ( )
  2152. .Ed
  2153. .Pp
  2154. A parameter that is NULL or unset evaluates to 0.
  2155. Integer constants may be specified with arbitrary bases using the notation
  2156. .Ar base Ns # Ns Ar number ,
  2157. where
  2158. .Ar base
  2159. is a decimal integer specifying the base, and
  2160. .Ar number
  2161. is a number in the specified base.
  2162. Additionally,
  2163. integers may be prefixed with
  2164. .Sq 0X
  2165. or
  2166. .Sq 0x
  2167. (specifying base 16)
  2168. or
  2169. .Sq 0
  2170. (base 8)
  2171. in all forms of arithmetic expressions,
  2172. except as numeric arguments to the
  2173. .Ic test
  2174. command.
  2175. .Pp
  2176. The operators are evaluated as follows:
  2177. .Bl -tag -width Ds -offset indent
  2178. .It unary +
  2179. Result is the argument (included for completeness).
  2180. .It unary -
  2181. Negation.
  2182. .It \&!
  2183. Logical NOT;
  2184. the result is 1 if argument is zero, 0 if not.
  2185. .It ~
  2186. Arithmetic (bit-wise) NOT.
  2187. .It ++
  2188. Increment; must be applied to a parameter (not a literal or other expression).
  2189. The parameter is incremented by 1.
  2190. When used as a prefix operator, the result
  2191. is the incremented value of the parameter; when used as a postfix operator, the
  2192. result is the original value of the parameter.
  2193. .It --
  2194. Similar to
  2195. .Ic ++ ,
  2196. except the parameter is decremented by 1.
  2197. .It \&,
  2198. Separates two arithmetic expressions; the left-hand side is evaluated first,
  2199. then the right.
  2200. The result is the value of the expression on the right-hand side.
  2201. .It =
  2202. Assignment; the variable on the left is set to the value on the right.
  2203. .It Xo
  2204. .No *= /= += -= <<=
  2205. .No >>= &= ^= |=
  2206. .Xc
  2207. Assignment operators.
  2208. .Sm off
  2209. .Ao Ar var Ac Xo
  2210. .Aq Ar op
  2211. .No = Aq Ar expr
  2212. .Xc
  2213. .Sm on
  2214. is the same as
  2215. .Sm off
  2216. .Ao Ar var Ac Xo
  2217. .No = Aq Ar var
  2218. .Aq Ar op
  2219. .Aq Ar expr ,
  2220. .Xc
  2221. .Sm on
  2222. with any operator precedence in
  2223. .Aq Ar expr
  2224. preserved.
  2225. For example,
  2226. .Dq var1 *= 5 + 3
  2227. is the same as specifying
  2228. .Dq var1 = var1 * (5 + 3) .
  2229. .It ||
  2230. Logical OR;
  2231. the result is 1 if either argument is non-zero, 0 if not.
  2232. The right argument is evaluated only if the left argument is zero.
  2233. .It &&
  2234. Logical AND;
  2235. the result is 1 if both arguments are non-zero, 0 if not.
  2236. The right argument is evaluated only if the left argument is non-zero.
  2237. .It |
  2238. Arithmetic (bit-wise) OR.
  2239. .It ^
  2240. Arithmetic (bit-wise) XOR
  2241. (exclusive-OR).
  2242. .It &
  2243. Arithmetic (bit-wise) AND.
  2244. .It ==
  2245. Equal; the result is 1 if both arguments are equal, 0 if not.
  2246. .It !=
  2247. Not equal; the result is 0 if both arguments are equal, 1 if not.
  2248. .It <
  2249. Less than; the result is 1 if the left argument is less than the right, 0 if
  2250. not.
  2251. .It <= >= >
  2252. Less than or equal, greater than or equal, greater than.
  2253. See
  2254. .Ic < .
  2255. .It << >>
  2256. Shift left (right); the result is the left argument with its bits shifted left
  2257. (right) by the amount given in the right argument.
  2258. .It + - * /
  2259. Addition, subtraction, multiplication, and division.
  2260. .It %
  2261. Remainder; the result is the remainder of the division of the left argument by
  2262. the right.
  2263. The sign of the result is unspecified if either argument is negative.
  2264. .It Xo
  2265. .Sm off
  2266. .Aq Ar arg1 ?
  2267. .Aq Ar arg2 :
  2268. .Aq Ar arg3
  2269. .Sm on
  2270. .Xc
  2271. If
  2272. .Aq Ar arg1
  2273. is non-zero, the result is
  2274. .Aq Ar arg2 ;
  2275. otherwise the result is
  2276. .Aq Ar arg3 .
  2277. .El
  2278. .Ss Co-processes
  2279. A co-process, which is a pipeline created with the
  2280. .Sq |&
  2281. operator, is an asynchronous process that the shell can both write to (using
  2282. .Ic print -p )
  2283. and read from (using
  2284. .Ic read -p ) .
  2285. The input and output of the co-process can also be manipulated using
  2286. .Cm >&p
  2287. and
  2288. .Cm <&p
  2289. redirections, respectively.
  2290. Once a co-process has been started, another can't
  2291. be started until the co-process exits, or until the co-process's input has been
  2292. redirected using an
  2293. .Ic exec Ar n Ns Cm >&p
  2294. redirection.
  2295. If a co-process's input is redirected in this way, the next
  2296. co-process to be started will share the output with the first co-process,
  2297. unless the output of the initial co-process has been redirected using an
  2298. .Ic exec Ar n Ns Cm <&p
  2299. redirection.
  2300. .Pp
  2301. Some notes concerning co-processes:
  2302. .Bl -bullet
  2303. .It
  2304. The only way to close the co-process's input (so the co-process reads an
  2305. end-of-file) is to redirect the input to a numbered file descriptor and then
  2306. close that file descriptor e.g.\&
  2307. .Ic exec 3>&p; exec 3>&- .
  2308. .It
  2309. In order for co-processes to share a common output, the shell must keep the
  2310. write portion of the output pipe open.
  2311. This means that end-of-file will not be
  2312. detected until all co-processes sharing the co-process's output have exited
  2313. (when they all exit, the shell closes its copy of the pipe).
  2314. This can be
  2315. avoided by redirecting the output to a numbered file descriptor (as this also
  2316. causes the shell to close its copy).
  2317. Note that this behaviour is slightly
  2318. different from the original Korn shell which closes its copy of the write
  2319. portion of the co-process output when the most recently started co-process
  2320. (instead of when all sharing co-processes) exits.
  2321. .It
  2322. .Ic print -p
  2323. will ignore
  2324. .Dv SIGPIPE
  2325. signals during writes if the signal is not being trapped or ignored; the same
  2326. is true if the co-process input has been duplicated to another file descriptor
  2327. and
  2328. .Ic print -u Ns Ar n
  2329. is used.
  2330. .El
  2331. .Ss Functions
  2332. Functions are defined using either Korn shell
  2333. .Ic function Ar function-name
  2334. syntax or the Bourne/POSIX shell
  2335. .Ar function-name Ns ()
  2336. syntax (see below for the difference between the two forms).
  2337. Functions are like
  2338. .Ic \&. Ns -scripts
  2339. (i.e. scripts sourced using the
  2340. .Sq Ic \&.
  2341. built-in command)
  2342. in that they are executed in the current environment.
  2343. However, unlike
  2344. .Ic \&. Ns -scripts,
  2345. shell arguments (i.e. positional parameters $1, $2, etc.)\&
  2346. are never visible inside them.
  2347. When the shell is determining the location of a command, functions
  2348. are searched after special built-in commands, before regular and
  2349. non-regular built-ins, and before the
  2350. .Ev PATH
  2351. is searched.
  2352. .Pp
  2353. An existing function may be deleted using
  2354. .Ic unset Fl f Ar function-name .
  2355. A list of functions can be obtained using
  2356. .Ic typeset +f
  2357. and the function definitions can be listed using
  2358. .Ic typeset -f .
  2359. The
  2360. .Ic autoload
  2361. command (which is an alias for
  2362. .Ic typeset -fu )
  2363. may be used to create undefined functions: when an undefined function is
  2364. executed, the shell searches the path specified in the
  2365. .Ev FPATH
  2366. parameter for a file with the same name as the function, which, if found, is
  2367. read and executed.
  2368. If after executing the file the named function is found to
  2369. be defined, the function is executed; otherwise, the normal command search is
  2370. continued (i.e. the shell searches the regular built-in command table and
  2371. .Ev PATH ) .
  2372. Note that if a command is not found using
  2373. .Ev PATH ,
  2374. an attempt is made to autoload a function using
  2375. .Ev FPATH
  2376. (this is an undocumented feature of the original Korn shell).
  2377. .Pp
  2378. Functions can have two attributes,
  2379. .Dq trace
  2380. and
  2381. .Dq export ,
  2382. which can be set with
  2383. .Ic typeset -ft
  2384. and
  2385. .Ic typeset -fx ,
  2386. respectively.
  2387. When a traced function is executed, the shell's
  2388. .Ic xtrace
  2389. option is turned on for the function's duration; otherwise, the
  2390. .Ic xtrace
  2391. option is turned off.
  2392. The
  2393. .Dq export
  2394. attribute of functions is currently not used.
  2395. In the original Korn shell,
  2396. exported functions are visible to shell scripts that are executed.
  2397. .Pp
  2398. Since functions are executed in the current shell environment, parameter
  2399. assignments made inside functions are visible after the function completes.
  2400. If this is not the desired effect, the
  2401. .Ic typeset
  2402. command can be used inside a function to create a local parameter.
  2403. Note that special parameters (e.g.\&
  2404. .Ic \&$$ , $! )
  2405. can't be scoped in this way.
  2406. .Pp
  2407. The exit status of a function is that of the last command executed in the
  2408. function.
  2409. A function can be made to finish immediately using the
  2410. .Ic return
  2411. command; this may also be used to explicitly specify the exit status.
  2412. .Pp
  2413. Functions defined with the
  2414. .Ic function
  2415. reserved word are treated differently in the following ways from functions
  2416. defined with the
  2417. .Ic ()
  2418. notation:
  2419. .Bl -bullet
  2420. .It
  2421. The $0 parameter is set to the name of the function
  2422. (Bourne-style functions leave $0 untouched).
  2423. .It
  2424. Parameter assignments preceding function calls are not kept in the shell
  2425. environment (executing Bourne-style functions will keep assignments).
  2426. .It
  2427. .Ev OPTIND
  2428. is saved/reset and restored on entry and exit from the function so
  2429. .Ic getopts
  2430. can be used properly both inside and outside the function (Bourne-style
  2431. functions leave
  2432. .Ev OPTIND
  2433. untouched, so using
  2434. .Ic getopts
  2435. inside a function interferes with using
  2436. .Ic getopts
  2437. outside the function).
  2438. .El
  2439. .Ss POSIX mode
  2440. The shell is intended to be POSIX compliant;
  2441. however, in some cases, POSIX behaviour is contrary either to
  2442. the original Korn shell behaviour or to user convenience.
  2443. How the shell behaves in these cases is determined by the state of the
  2444. .Ic posix
  2445. option
  2446. .Pq Ic set -o posix .
  2447. If it is on, the POSIX behaviour is followed; otherwise, it is not.
  2448. The
  2449. .Ic posix
  2450. option is set automatically when the shell starts up if the environment
  2451. contains the
  2452. .Ev POSIXLY_CORRECT
  2453. parameter.
  2454. The shell can also be compiled so that it is in POSIX mode by default;
  2455. however, this is usually not desirable.
  2456. .Pp
  2457. The following is a list of things that are affected by the state of the
  2458. .Ic posix
  2459. option:
  2460. .Bl -bullet
  2461. .It
  2462. .Ic kill -l
  2463. output.
  2464. In POSIX mode, only signal names are listed (in a single line);
  2465. in non-POSIX mode,
  2466. signal numbers, names, and descriptions are printed (in columns).
  2467. .It
  2468. .Ic echo
  2469. options.
  2470. In POSIX mode,
  2471. .Fl e
  2472. and
  2473. .Fl E
  2474. are not treated as options, but printed like other arguments;
  2475. in non-POSIX mode, these options control the interpretation
  2476. of backslash sequences.
  2477. .It
  2478. .Ic fg
  2479. exit status.
  2480. In POSIX mode, the exit status is 0 if no errors occur;
  2481. in non-POSIX mode, the exit status is that of the last foregrounded job.
  2482. .It
  2483. .Ic eval
  2484. exit status.
  2485. If
  2486. .Ic eval
  2487. gets to see an empty command (i.e.\&
  2488. .Ic eval `false` ) ,
  2489. its exit status in POSIX mode will be 0.
  2490. In non-POSIX mode,
  2491. it will be the exit status of the last command substitution that was
  2492. done in the processing of the arguments to
  2493. .Ic eval
  2494. (or 0 if there were no command substitutions).
  2495. .It
  2496. .Ic getopts .
  2497. In POSIX mode, options must start with a
  2498. .Ql - ;
  2499. in non-POSIX mode, options can start with either
  2500. .Ql -
  2501. or
  2502. .Ql + .
  2503. .It
  2504. Brace expansion (also known as alternation).
  2505. In POSIX mode, brace expansion is disabled;
  2506. in non-POSIX mode, brace expansion is enabled.
  2507. Note that
  2508. .Ic set -o posix
  2509. (or setting the
  2510. .Ev POSIXLY_CORRECT
  2511. parameter) automatically turns the
  2512. .Ic braceexpand
  2513. option off; however, it can be explicitly turned on later.
  2514. .It
  2515. .Ic set - .
  2516. In POSIX mode, this does not clear the
  2517. .Ic verbose
  2518. or
  2519. .Ic xtrace
  2520. options; in non-POSIX mode, it does.
  2521. .It
  2522. .Ic set
  2523. exit status.
  2524. In POSIX mode, the exit status of
  2525. .Ic set
  2526. is 0 if there are no errors;
  2527. in non-POSIX mode, the exit status is that of any
  2528. command substitutions performed in generating the
  2529. .Ic set
  2530. command.
  2531. For example,
  2532. .Ic set -- `false`; echo $?\&
  2533. prints 0 in POSIX mode, 1 in non-POSIX mode.
  2534. This construct is used in most shell scripts that use the old
  2535. .Xr getopt 1
  2536. command.
  2537. .It
  2538. Argument expansion of the
  2539. .Ic alias ,
  2540. .Ic export ,
  2541. .Ic readonly ,
  2542. and
  2543. .Ic typeset
  2544. commands.
  2545. In POSIX mode, normal argument expansion is done; in non-POSIX mode,
  2546. field splitting, file globbing, brace expansion, and (normal) tilde expansion
  2547. are turned off, while assignment tilde expansion is turned on.
  2548. .It
  2549. Signal specification.
  2550. In POSIX mode, signals can be specified as digits, only
  2551. if signal numbers match POSIX values
  2552. (i.e. HUP=1, INT=2, QUIT=3, ABRT=6, KILL=9, ALRM=14, and TERM=15);
  2553. in non-POSIX mode, signals can always be digits.
  2554. .It
  2555. Alias expansion.
  2556. In POSIX mode, alias expansion is only carried out when reading command words;
  2557. in non-POSIX mode, alias expansion is carried out on any
  2558. word following an alias that ended in a space.
  2559. For example, the following
  2560. .Ic for
  2561. loop uses parameter
  2562. .Sq i
  2563. in POSIX mode and
  2564. .Sq j
  2565. in non-POSIX mode:
  2566. .Bd -literal -offset indent
  2567. alias a='for ' i='j'
  2568. a i in 1 2; do echo i=$i j=$j; done
  2569. .Ed
  2570. .El
  2571. .Ss Strict Bourne shell mode
  2572. When the
  2573. .Ic sh
  2574. option is enabled (see the
  2575. .Ic set
  2576. command),
  2577. .Nm
  2578. will behave like
  2579. .Xr sh 1
  2580. in the following ways:
  2581. .Bl -bullet
  2582. .It
  2583. The parameter
  2584. .Ic $_
  2585. is not set to:
  2586. .Pp
  2587. .Bl -dash -compact
  2588. .It
  2589. the expanded alias' full program path after entering commands
  2590. that are tracked aliases
  2591. .It
  2592. the last argument on the command line after entering external
  2593. commands
  2594. .It
  2595. the file that changed when
  2596. .Ev MAILPATH
  2597. is set to monitor a mailbox
  2598. .El
  2599. .It
  2600. File descriptors are left untouched when executing
  2601. .Ic exec
  2602. with no arguments.
  2603. .It
  2604. Backslash-escaped special characters are not substituted in
  2605. .Ev PS1 .
  2606. .It
  2607. Sequences of
  2608. .Sq ((...))
  2609. are not interpreted as arithmetic expressions.
  2610. .El
  2611. .Ss Command execution
  2612. After evaluation of command-line arguments, redirections, and parameter
  2613. assignments, the type of command is determined: a special built-in, a
  2614. function, a regular built-in, or the name of a file to execute found using the
  2615. .Ev PATH
  2616. parameter.
  2617. The checks are made in the above order.
  2618. Special built-in commands differ from other commands in that the
  2619. .Ev PATH
  2620. parameter is not used to find them, an error during their execution can
  2621. cause a non-interactive shell to exit, and parameter assignments that are
  2622. specified before the command are kept after the command completes.
  2623. Just to confuse things, if the
  2624. .Ic posix
  2625. option is turned off (see the
  2626. .Ic set
  2627. command below), some special commands are very special in that no field
  2628. splitting, file globbing, brace expansion, nor tilde expansion is performed
  2629. on arguments that look like assignments.
  2630. Regular built-in commands are different only in that the
  2631. .Ev PATH
  2632. parameter is not used to find them.
  2633. .Pp
  2634. The original
  2635. .Nm ksh
  2636. and POSIX differ somewhat in which commands are considered
  2637. special or regular:
  2638. .Pp
  2639. POSIX special commands
  2640. .Pp
  2641. .Ic \&. , \&: , break , continue ,
  2642. .Ic eval , exec , exit , export ,
  2643. .Ic readonly , return , set , shift ,
  2644. .Ic times , trap , unset
  2645. .Pp
  2646. Additional
  2647. .Nm
  2648. special commands
  2649. .Pp
  2650. .Ic builtin , typeset
  2651. .Pp
  2652. Very special commands
  2653. .Pq when POSIX mode is off
  2654. .Pp
  2655. .Ic alias , readonly , set , typeset
  2656. .Pp
  2657. POSIX regular commands
  2658. .Pp
  2659. .Ic alias , bg , cd , command ,
  2660. .Ic false , fc , fg , getopts ,
  2661. .Ic jobs , kill , pwd , read ,
  2662. .Ic true , umask , unalias , wait
  2663. .Pp
  2664. Additional
  2665. .Nm
  2666. regular commands
  2667. .Pp
  2668. .Ic \&[ , echo , let ,
  2669. .Ic print , suspend , test ,
  2670. .Ic ulimit , whence
  2671. .Pp
  2672. Once the type of command has been determined, any command-line parameter
  2673. assignments are performed and exported for the duration of the command.
  2674. .Pp
  2675. The following describes the special and regular built-in commands:
  2676. .Pp
  2677. .Bl -tag -width Ds -compact
  2678. .It Ic \&. Ar file Op Ar arg ...
  2679. Execute the commands in
  2680. .Ar file
  2681. in the current environment.
  2682. The file is searched for in the directories of
  2683. .Ev PATH .
  2684. If arguments are given, the positional parameters may be used to access them
  2685. while
  2686. .Ar file
  2687. is being executed.
  2688. If no arguments are given, the positional parameters are
  2689. those of the environment the command is used in.
  2690. .Pp
  2691. .It Ic \&: Op Ar ...
  2692. The null command.
  2693. Exit status is set to zero.
  2694. .Pp
  2695. .It Xo Ic alias
  2696. .Oo Fl d | t Oo Fl r Oc |
  2697. .Cm +-x Oc
  2698. .Op Fl p
  2699. .Op Cm +
  2700. .Op Ar name Ns Oo = Ns Ar value Oc Ar ...
  2701. .Xc
  2702. Without arguments,
  2703. .Ic alias
  2704. lists all aliases.
  2705. For any name without a value, the existing alias is listed.
  2706. Any name with a value defines an alias (see
  2707. .Sx Aliases
  2708. above).
  2709. .Pp
  2710. When listing aliases, one of two formats is used.
  2711. Normally, aliases are listed as
  2712. .Ar name Ns = Ns Ar value ,
  2713. where
  2714. .Ar value
  2715. is quoted.
  2716. If options were preceded with
  2717. .Ql + ,
  2718. or a lone
  2719. .Ql +
  2720. is given on the command line, only
  2721. .Ar name
  2722. is printed.
  2723. .Pp
  2724. The
  2725. .Fl d
  2726. option causes directory aliases, which are used in tilde expansion, to be
  2727. listed or set (see
  2728. .Sx Tilde expansion
  2729. above).
  2730. .Pp
  2731. If the
  2732. .Fl p
  2733. option is used, each alias is prefixed with the string
  2734. .Dq alias\ \& .
  2735. .Pp
  2736. The
  2737. .Fl t
  2738. option indicates that tracked aliases are to be listed/set (values specified on
  2739. the command line are ignored for tracked aliases).
  2740. The
  2741. .Fl r
  2742. option indicates that all tracked aliases are to be reset.
  2743. .Pp
  2744. The
  2745. .Fl x
  2746. option sets
  2747. .Pq Ic +x No clears
  2748. the export attribute of an alias or, if no names are given, lists the aliases
  2749. with the export attribute (exporting an alias has no effect).
  2750. .Pp
  2751. .It Ic bg Op Ar job ...
  2752. Resume the specified stopped job(s) in the background.
  2753. If no jobs are specified,
  2754. .Ic %+
  2755. is assumed.
  2756. See
  2757. .Sx Job control
  2758. below for more information.
  2759. .Pp
  2760. .It Ic bind Op Fl l
  2761. The current bindings are listed.
  2762. If the
  2763. .Fl l
  2764. flag is given,
  2765. .Ic bind
  2766. instead lists the names of the functions to which keys may be bound.
  2767. See
  2768. .Sx Emacs editing mode
  2769. for more information.
  2770. .Pp
  2771. .It Xo Ic bind Op Fl m
  2772. .Ar string Ns = Ns Op Ar substitute
  2773. .Ar ...
  2774. .Xc
  2775. .It Xo Ic bind
  2776. .Ar string Ns = Ns Op Ar editing-command
  2777. .Ar ...
  2778. .Xc
  2779. In
  2780. .Sx Emacs editing mode ,
  2781. the specified editing command is bound to the given
  2782. .Ar string .
  2783. Future input of the
  2784. .Ar string
  2785. will cause the editing command to be immediately invoked.
  2786. Bindings have no effect in
  2787. .Sx Vi editing mode .
  2788. .Pp
  2789. If the
  2790. .Fl m
  2791. flag is given, the specified input
  2792. .Ar string
  2793. will afterwards be immediately replaced by the given
  2794. .Ar substitute
  2795. string, which may contain editing commands.
  2796. Control characters may be written using caret notation.
  2797. For example, ^X represents Control-X.
  2798. .Pp
  2799. If a certain character occurs as the first character of any bound
  2800. multi-character
  2801. .Ar string
  2802. sequence, that character becomes a command prefix character.
  2803. Any character sequence that starts with a command prefix character
  2804. but that is not bound to a command or substitute
  2805. is implicitly considered as bound to the
  2806. .Sq error
  2807. command.
  2808. By default, two command prefix characters exist:
  2809. Escape
  2810. .Pq ^[
  2811. and Control-X
  2812. .Pq ^X .
  2813. .Pp
  2814. The following default bindings show how the arrow keys
  2815. on an ANSI terminal or xterm are bound
  2816. (of course some escape sequences won't work out quite this nicely):
  2817. .Bd -literal -offset indent
  2818. bind '^[[A'=up-history
  2819. bind '^[[B'=down-history
  2820. bind '^[[C'=forward-char
  2821. bind '^[[D'=backward-char
  2822. .Ed
  2823. .Pp
  2824. .It Ic break Op Ar level
  2825. Exit the
  2826. .Ar level Ns th
  2827. inner-most
  2828. .Ic for ,
  2829. .Ic select ,
  2830. .Ic until ,
  2831. or
  2832. .Ic while
  2833. loop.
  2834. .Ar level
  2835. defaults to 1.
  2836. .Pp
  2837. .It Ic builtin Ar command Op Ar arg ...
  2838. Execute the built-in command
  2839. .Ar command .
  2840. .Pp
  2841. .It Xo
  2842. .Ic cd
  2843. .Op Fl LP
  2844. .Op Ar dir
  2845. .Xc
  2846. Set the working directory to
  2847. .Ar dir .
  2848. If the parameter
  2849. .Ev CDPATH
  2850. is set, it lists the search path for the directory containing
  2851. .Ar dir .
  2852. A
  2853. .Dv NULL
  2854. path or
  2855. .Ql .\&
  2856. means the current directory.
  2857. If
  2858. .Ar dir
  2859. is found in any component of the
  2860. .Ev CDPATH
  2861. search path other than the
  2862. .Dv NULL
  2863. path, the name of the new working directory will be written to standard output.
  2864. If
  2865. .Ar dir
  2866. is missing, the home directory
  2867. .Ev HOME
  2868. is used.
  2869. If
  2870. .Ar dir
  2871. is
  2872. .Ql - ,
  2873. the previous working directory is used (see the
  2874. .Ev OLDPWD
  2875. parameter).
  2876. .Pp
  2877. If the
  2878. .Fl L
  2879. option (logical path) is used or if the
  2880. .Ic physical
  2881. option isn't set (see the
  2882. .Ic set
  2883. command below), references to
  2884. .Sq ..
  2885. in
  2886. .Ar dir
  2887. are relative to the path used to get to the directory.
  2888. If the
  2889. .Fl P
  2890. option (physical path) is used or if the
  2891. .Ic physical
  2892. option is set,
  2893. .Sq ..
  2894. is relative to the filesystem directory tree.
  2895. The
  2896. .Ev PWD
  2897. and
  2898. .Ev OLDPWD
  2899. parameters are updated to reflect the current and old working directory,
  2900. respectively.
  2901. .Pp
  2902. .It Xo
  2903. .Ic cd
  2904. .Op Fl LP
  2905. .Ar old new
  2906. .Xc
  2907. The string
  2908. .Ar new
  2909. is substituted for
  2910. .Ar old
  2911. in the current directory, and the shell attempts to change to the new
  2912. directory.
  2913. .Pp
  2914. .It Xo
  2915. .Ic command
  2916. .Op Fl pVv
  2917. .Ar cmd
  2918. .Op Ar arg ...
  2919. .Xc
  2920. If neither the
  2921. .Fl v
  2922. nor
  2923. .Fl V
  2924. option is given,
  2925. .Ar cmd
  2926. is executed exactly as if
  2927. .Ic command
  2928. had not been specified, with two exceptions:
  2929. firstly,
  2930. .Ar cmd
  2931. cannot be an alias or a shell function;
  2932. and secondly, special built-in commands lose their specialness
  2933. (i.e. redirection and utility errors do not cause the shell to
  2934. exit, and command assignments are not permanent).
  2935. .Pp
  2936. If the
  2937. .Fl p
  2938. option is given, a default search path is used instead of the current value of
  2939. .Ev PATH
  2940. (the actual value of the default path is system dependent: on
  2941. POSIX-ish systems, it is the value returned by
  2942. .Ic getconf PATH ) .
  2943. Nevertheless, reserved words, aliases, shell functions, and
  2944. builtin commands are still found before external commands.
  2945. .Pp
  2946. If the
  2947. .Fl v
  2948. option is given, instead of executing
  2949. .Ar cmd ,
  2950. information about what would be executed is given (and the same is done for
  2951. .Ar arg ... ) .
  2952. For special and regular built-in commands and functions, their names are simply
  2953. printed; for aliases, a command that defines them is printed; and for commands
  2954. found by searching the
  2955. .Ev PATH
  2956. parameter, the full path of the command is printed.
  2957. If no command is found
  2958. (i.e. the path search fails), nothing is printed and
  2959. .Ic command
  2960. exits with a non-zero status.
  2961. The
  2962. .Fl V
  2963. option is like the
  2964. .Fl v
  2965. option, except it is more verbose.
  2966. .Pp
  2967. .It Ic continue Op Ar level
  2968. Jumps to the beginning of the
  2969. .Ar level Ns th
  2970. inner-most
  2971. .Ic for ,
  2972. .Ic select ,
  2973. .Ic until ,
  2974. or
  2975. .Ic while
  2976. loop.
  2977. .Ar level
  2978. defaults to 1.
  2979. .Pp
  2980. .It Xo
  2981. .Ic echo
  2982. .Op Fl Een
  2983. .Op Ar arg ...
  2984. .Xc
  2985. Prints its arguments (separated by spaces) followed by a newline, to the
  2986. standard output.
  2987. The newline is suppressed if any of the arguments contain the
  2988. backslash sequence
  2989. .Ql \ec .
  2990. See the
  2991. .Ic print
  2992. command below for a list of other backslash sequences that are recognized.
  2993. .Pp
  2994. The options are provided for compatibility with
  2995. .Bx
  2996. shell scripts.
  2997. The
  2998. .Fl n
  2999. option suppresses the trailing newline,
  3000. .Fl e
  3001. enables backslash interpretation (a no-op, since this is normally done), and
  3002. .Fl E
  3003. suppresses backslash interpretation.
  3004. If the
  3005. .Ic posix
  3006. option is set, only the first argument is treated as an option, and only
  3007. if it is exactly
  3008. .Dq -n .
  3009. .Pp
  3010. .It Ic eval Ar command ...
  3011. The arguments are concatenated (with spaces between them) to form a single
  3012. string which the shell then parses and executes in the current environment.
  3013. .Pp
  3014. .It Xo
  3015. .Ic exec
  3016. .Op Ar command Op Ar arg ...
  3017. .Xc
  3018. The command is executed without forking, replacing the shell process.
  3019. .Pp
  3020. If no command is given except for I/O redirection, the I/O redirection is
  3021. permanent and the shell is
  3022. not replaced.
  3023. Any file descriptors greater than 2 which are opened or
  3024. .Xr dup 2 Ns 'd
  3025. in this way are not made available to other executed commands (i.e. commands
  3026. that are not built-in to the shell).
  3027. Note that the Bourne shell differs here;
  3028. it does pass these file descriptors on.
  3029. .Pp
  3030. .It Ic exit Op Ar status
  3031. The shell exits with the specified exit status.
  3032. If
  3033. .Ar status
  3034. is not specified, the exit status is the current value of the
  3035. .Ic $?\&
  3036. parameter.
  3037. .Pp
  3038. .It Xo
  3039. .Ic export
  3040. .Op Fl p
  3041. .Op Ar parameter Ns Op = Ns Ar value
  3042. .Xc
  3043. Sets the export attribute of the named parameters.
  3044. Exported parameters are passed in the environment to executed commands.
  3045. If values are specified, the named parameters are also assigned.
  3046. .Pp
  3047. If no parameters are specified, the names of all parameters with the export
  3048. attribute are printed one per line, unless the
  3049. .Fl p
  3050. option is used, in which case
  3051. .Ic export
  3052. commands defining all exported parameters, including their values, are printed.
  3053. .Pp
  3054. .It Ic false
  3055. A command that exits with a non-zero status.
  3056. .Pp
  3057. .It Xo
  3058. .Ic fc
  3059. .Oo
  3060. .Fl e Ar editor |
  3061. .Fl l Op Fl n
  3062. .Oc
  3063. .Op Fl r
  3064. .Op Ar first Op Ar last
  3065. .Xc
  3066. Fix command.
  3067. .Ar first
  3068. and
  3069. .Ar last
  3070. select commands from the history.
  3071. Commands can be selected by history number
  3072. or a string specifying the most recent command starting with that string.
  3073. The
  3074. .Fl l
  3075. option lists the command on standard output, and
  3076. .Fl n
  3077. inhibits the default command numbers.
  3078. The
  3079. .Fl r
  3080. option reverses the order of the list.
  3081. Without
  3082. .Fl l ,
  3083. the selected commands are edited by the editor specified with the
  3084. .Fl e
  3085. option, or if no
  3086. .Fl e
  3087. is specified, the editor specified by the
  3088. .Ev FCEDIT
  3089. parameter (if this parameter is not set,
  3090. .Pa /bin/ed
  3091. is used), and then executed by the shell.
  3092. .Pp
  3093. .It Xo
  3094. .Ic fc Fl s
  3095. .Op Fl g
  3096. .Op Ar old Ns = Ns Ar new
  3097. .Op Ar prefix
  3098. .Xc
  3099. Re-execute the most recent command beginning with
  3100. .Ar prefix ,
  3101. or the previous command if no
  3102. .Ar prefix
  3103. is specified,
  3104. performing the optional substitution of
  3105. .Ar old
  3106. with
  3107. .Ar new .
  3108. If
  3109. .Fl g
  3110. is specified, all occurrences of
  3111. .Ar old
  3112. are replaced with
  3113. .Ar new .
  3114. The editor is not invoked when the
  3115. .Fl s
  3116. flag is used.
  3117. The obsolescent equivalent
  3118. .Dq Fl e No -
  3119. is also accepted.
  3120. This command is usually accessed with the predefined
  3121. .Ic alias r='fc -s' .
  3122. .Pp
  3123. .It Ic fg Op Ar job ...
  3124. Resume the specified job(s) in the foreground.
  3125. If no jobs are specified,
  3126. .Ic %+
  3127. is assumed.
  3128. See
  3129. .Sx Job control
  3130. below for more information.
  3131. .Pp
  3132. .It Xo
  3133. .Ic getopts
  3134. .Ar optstring name
  3135. .Op Ar arg ...
  3136. .Xc
  3137. Used by shell procedures to parse the specified arguments (or positional
  3138. parameters, if no arguments are given) and to check for legal options.
  3139. .Ar optstring
  3140. contains the option letters that
  3141. .Ic getopts
  3142. is to recognize.
  3143. If a letter is followed by a colon, the option is expected to
  3144. have an argument.
  3145. Options that do not take arguments may be grouped in a single argument.
  3146. If an option takes an argument and the option character is not the
  3147. last character of the argument it is found in, the remainder of the argument is
  3148. taken to be the option's argument; otherwise, the next argument is the option's
  3149. argument.
  3150. .Pp
  3151. Each time
  3152. .Ic getopts
  3153. is invoked, it places the next option in the shell parameter
  3154. .Ar name
  3155. and the index of the argument to be processed by the next call to
  3156. .Ic getopts
  3157. in the shell parameter
  3158. .Ev OPTIND .
  3159. If the option was introduced with a
  3160. .Ql + ,
  3161. the option placed in
  3162. .Ar name
  3163. is prefixed with a
  3164. .Ql + .
  3165. When an option requires an argument,
  3166. .Ic getopts
  3167. places it in the shell parameter
  3168. .Ev OPTARG .
  3169. .Pp
  3170. When an illegal option or a missing option argument is encountered, a question
  3171. mark or a colon is placed in
  3172. .Ar name
  3173. (indicating an illegal option or missing argument, respectively) and
  3174. .Ev OPTARG
  3175. is set to the option character that caused the problem.
  3176. Furthermore, if
  3177. .Ar optstring
  3178. does not begin with a colon, a question mark is placed in
  3179. .Ar name ,
  3180. .Ev OPTARG
  3181. is unset, and an error message is printed to standard error.
  3182. .Pp
  3183. When the end of the options is encountered,
  3184. .Ic getopts
  3185. exits with a non-zero exit status.
  3186. Options end at the first (non-option
  3187. argument) argument that does not start with a
  3188. .Ql - ,
  3189. or when a
  3190. .Ql --
  3191. argument is encountered.
  3192. .Pp
  3193. Option parsing can be reset by setting
  3194. .Ev OPTIND
  3195. to 1 (this is done automatically whenever the shell or a shell procedure is
  3196. invoked).
  3197. .Pp
  3198. Warning: Changing the value of the shell parameter
  3199. .Ev OPTIND
  3200. to a value other than 1, or parsing different sets of arguments without
  3201. resetting
  3202. .Ev OPTIND ,
  3203. may lead to unexpected results.
  3204. .Pp
  3205. The following code fragment shows how one might process the arguments
  3206. for a command that can take the option
  3207. .Fl a
  3208. and the option
  3209. .Fl o ,
  3210. which requires an argument.
  3211. .Bd -literal -offset indent
  3212. while getopts ao: name
  3213. do
  3214. case $name in
  3215. a) flag=1 ;;
  3216. o) oarg=$OPTARG ;;
  3217. ?) echo "Usage: ..."; exit 2 ;;
  3218. esac
  3219. done
  3220. shift $(($OPTIND - 1))
  3221. echo "Non-option arguments: " "$@"
  3222. .Ed
  3223. .Pp
  3224. .It Xo
  3225. .Ic hash
  3226. .Op Fl r
  3227. .Op Ar name ...
  3228. .Xc
  3229. Without arguments, any hashed executable command pathnames are listed.
  3230. The
  3231. .Fl r
  3232. option causes all hashed commands to be removed from the hash table.
  3233. Each
  3234. .Ar name
  3235. is searched as if it were a command name and added to the hash table if it is
  3236. an executable command.
  3237. .Pp
  3238. .It Xo
  3239. .Ic jobs
  3240. .Op Fl lnp
  3241. .Op Ar job ...
  3242. .Xc
  3243. Display information about the specified job(s); if no jobs are specified, all
  3244. jobs are displayed.
  3245. The
  3246. .Fl n
  3247. option causes information to be displayed only for jobs that have changed
  3248. state since the last notification.
  3249. If the
  3250. .Fl l
  3251. option is used, the process ID of each process in a job is also listed.
  3252. The
  3253. .Fl p
  3254. option causes only the process group of each job to be printed.
  3255. See
  3256. .Sx Job control
  3257. below for the format of
  3258. .Ar job
  3259. and the displayed job.
  3260. .Pp
  3261. .It Xo
  3262. .Ic kill
  3263. .Oo Fl s Ar signame |
  3264. .No - Ns Ar signum |
  3265. .No - Ns Ar signame Oc
  3266. .No { Ar job | pid | pgrp No }
  3267. .Ar ...
  3268. .Xc
  3269. Send the specified signal to the specified jobs, process IDs, or process
  3270. groups.
  3271. If no signal is specified, the
  3272. .Dv TERM
  3273. signal is sent.
  3274. If a job is specified, the signal is sent to the job's process group.
  3275. See
  3276. .Sx Job control
  3277. below for the format of
  3278. .Ar job .
  3279. .Pp
  3280. .It Xo
  3281. .Ic kill
  3282. .Fl l
  3283. .Op Ar exit-status ...
  3284. .Xc
  3285. Print the signal name corresponding to
  3286. .Ar exit-status .
  3287. If no arguments are specified, a list of all the signals, their numbers, and
  3288. a short description of them are printed.
  3289. .Pp
  3290. .It Ic let Op Ar expression ...
  3291. Each expression is evaluated (see
  3292. .Sx Arithmetic expressions
  3293. above).
  3294. If all expressions are successfully evaluated, the exit status is 0 (1)
  3295. if the last expression evaluated to non-zero (zero).
  3296. If an error occurs during
  3297. the parsing or evaluation of an expression, the exit status is greater than 1.
  3298. Since expressions may need to be quoted,
  3299. .No (( Ar expr No ))
  3300. is syntactic sugar for
  3301. .No let \&" Ns Ar expr Ns \&" .
  3302. .Pp
  3303. .It Xo
  3304. .Ic print
  3305. .Oo
  3306. .Fl nprsu Ns Oo Ar n Oc |
  3307. .Fl R Op Fl en
  3308. .Oc
  3309. .Op Ar argument ...
  3310. .Xc
  3311. .Ic print
  3312. prints its arguments on the standard output, separated by spaces and
  3313. terminated with a newline.
  3314. The
  3315. .Fl n
  3316. option suppresses the newline.
  3317. By default, certain C escapes are translated.
  3318. These include
  3319. .Ql \eb ,
  3320. .Ql \ef ,
  3321. .Ql \en ,
  3322. .Ql \er ,
  3323. .Ql \et ,
  3324. .Ql \ev ,
  3325. and
  3326. .Ql \e0###
  3327. .Po
  3328. .Ql #
  3329. is an octal digit, of which there may be 0 to 3
  3330. .Pc .
  3331. .Ql \ec
  3332. is equivalent to using the
  3333. .Fl n
  3334. option.
  3335. .Ql \e
  3336. expansion may be inhibited with the
  3337. .Fl r
  3338. option.
  3339. The
  3340. .Fl s
  3341. option prints to the history file instead of standard output; the
  3342. .Fl u
  3343. option prints to file descriptor
  3344. .Ar n
  3345. .Po
  3346. .Ar n
  3347. defaults to 1 if omitted
  3348. .Pc ;
  3349. and the
  3350. .Fl p
  3351. option prints to the co-process (see
  3352. .Sx Co-processes
  3353. above).
  3354. .Pp
  3355. The
  3356. .Fl R
  3357. option is used to emulate, to some degree, the
  3358. .Bx
  3359. .Xr echo 1
  3360. command, which does not process
  3361. .Ql \e
  3362. sequences unless the
  3363. .Fl e
  3364. option is given.
  3365. As above, the
  3366. .Fl n
  3367. option suppresses the trailing newline.
  3368. .Pp
  3369. .It Ic pwd Op Fl LP
  3370. Print the present working directory.
  3371. If the
  3372. .Fl L
  3373. option is used or if the
  3374. .Ic physical
  3375. option isn't set (see the
  3376. .Ic set
  3377. command below), the logical path is printed (i.e. the path used to
  3378. .Ic cd
  3379. to the current directory).
  3380. If the
  3381. .Fl P
  3382. option (physical path) is used or if the
  3383. .Ic physical
  3384. option is set, the path determined from the filesystem (by following
  3385. .Sq ..
  3386. directories to the root directory) is printed.
  3387. .Pp
  3388. .It Xo
  3389. .Ic read
  3390. .Op Fl prsu Ns Op Ar n
  3391. .Op Ar parameter ...
  3392. .Xc
  3393. Reads a line of input from the standard input, separates the line into fields
  3394. using the
  3395. .Ev IFS
  3396. parameter (see
  3397. .Sx Substitution
  3398. above), and assigns each field to the specified parameters.
  3399. If there are more parameters than fields, the extra parameters are set to
  3400. .Dv NULL ,
  3401. or alternatively, if there are more fields than parameters, the last parameter
  3402. is assigned the remaining fields (inclusive of any separating spaces).
  3403. If no parameters are specified, the
  3404. .Ev REPLY
  3405. parameter is used.
  3406. If the input line ends in a backslash and the
  3407. .Fl r
  3408. option was not used, the backslash and the newline are stripped and more input
  3409. is read.
  3410. If no input is read,
  3411. .Ic read
  3412. exits with a non-zero status.
  3413. .Pp
  3414. The first parameter may have a question mark and a string appended to it, in
  3415. which case the string is used as a prompt (printed to standard error before
  3416. any input is read) if the input is a
  3417. .Xr tty 4
  3418. (e.g.\&
  3419. .Ic read nfoo?'number of foos: ' ) .
  3420. .Pp
  3421. The
  3422. .Fl u Ns Ar n
  3423. and
  3424. .Fl p
  3425. options cause input to be read from file descriptor
  3426. .Ar n
  3427. .Pf ( Ar n
  3428. defaults to 0 if omitted)
  3429. or the current co-process (see
  3430. .Sx Co-processes
  3431. above for comments on this), respectively.
  3432. If the
  3433. .Fl s
  3434. option is used, input is saved to the history file.
  3435. .Pp
  3436. .It Xo
  3437. .Ic readonly
  3438. .Op Fl p
  3439. .Op Ar parameter Ns Oo = Ns Ar value Oc Ar ...
  3440. .Xc
  3441. Sets the read-only attribute of the named parameters.
  3442. If values are given,
  3443. parameters are set to them before setting the attribute.
  3444. Once a parameter is
  3445. made read-only, it cannot be unset and its value cannot be changed.
  3446. .Pp
  3447. If no parameters are specified, the names of all parameters with the read-only
  3448. attribute are printed one per line, unless the
  3449. .Fl p
  3450. option is used, in which case
  3451. .Ic readonly
  3452. commands defining all read-only parameters, including their values, are
  3453. printed.
  3454. .Pp
  3455. .It Ic return Op Ar status
  3456. Returns from a function or
  3457. .Ic .\&
  3458. script, with exit status
  3459. .Ar status .
  3460. If no
  3461. .Ar status
  3462. is given, the exit status of the last executed command is used.
  3463. If used outside of a function or
  3464. .Ic .\&
  3465. script, it has the same effect as
  3466. .Ic exit .
  3467. Note that
  3468. .Nm ksh
  3469. treats both profile and
  3470. .Ev ENV
  3471. files as
  3472. .Ic .\&
  3473. scripts, while the original Korn shell only treats profiles as
  3474. .Ic .\&
  3475. scripts.
  3476. .Pp
  3477. .It Xo
  3478. .Ic set Op Ic +-abCefhkmnpsuvXx
  3479. .Op Ic +-o Ar option
  3480. .Op Ic +-A Ar name
  3481. .Op Fl -
  3482. .Op Ar arg ...
  3483. .Xc
  3484. The
  3485. .Ic set
  3486. command can be used to set
  3487. .Pq Ic -
  3488. or clear
  3489. .Pq Ic +
  3490. shell options, set the positional parameters, or set an array parameter.
  3491. Options can be changed using the
  3492. .Cm +-o Ar option
  3493. syntax, where
  3494. .Ar option
  3495. is the long name of an option, or using the
  3496. .Cm +- Ns Ar letter
  3497. syntax, where
  3498. .Ar letter
  3499. is the option's single letter name (not all options have a single letter name).
  3500. The following table lists both option letters (if they exist) and long names
  3501. along with a description of what the option does:
  3502. .Bl -tag -width 15n
  3503. .It Fl A Ar name
  3504. Sets the elements of the array parameter
  3505. .Ar name
  3506. to
  3507. .Ar arg ...
  3508. If
  3509. .Fl A
  3510. is used, the array is reset (i.e. emptied) first; if
  3511. .Ic +A
  3512. is used, the first N elements are set (where N is the number of arguments);
  3513. the rest are left untouched.
  3514. .It Fl a | Ic allexport
  3515. All new parameters are created with the export attribute.
  3516. .It Fl b | Ic notify
  3517. Print job notification messages asynchronously, instead of just before the
  3518. prompt.
  3519. Only used if job control is enabled
  3520. .Pq Fl m .
  3521. .It Fl C | Ic noclobber
  3522. Prevent
  3523. .Cm >
  3524. redirection from overwriting existing files.
  3525. Instead,
  3526. .Cm >|
  3527. must be used to force an overwrite.
  3528. .It Fl e | Ic errexit
  3529. Exit (after executing the
  3530. .Dv ERR
  3531. trap) as soon as an error occurs or a command fails (i.e. exits with a
  3532. non-zero status).
  3533. This does not apply to commands whose exit status is
  3534. explicitly tested by a shell construct such as
  3535. .Ic if ,
  3536. .Ic until ,
  3537. .Ic while ,
  3538. or
  3539. .Ic !\&
  3540. statements.
  3541. For
  3542. .Ic &&
  3543. or
  3544. .Ic || ,
  3545. only the status of the last command is tested.
  3546. .It Fl f | Ic noglob
  3547. Do not expand file name patterns.
  3548. .It Fl h | Ic trackall
  3549. Create tracked aliases for all executed commands (see
  3550. .Sx Aliases
  3551. above).
  3552. Enabled by default for non-interactive shells.
  3553. .It Fl k | Ic keyword
  3554. Parameter assignments are recognized anywhere in a command.
  3555. .It Fl m | Ic monitor
  3556. Enable job control (default for interactive shells).
  3557. .It Fl n | Ic noexec
  3558. Do not execute any commands.
  3559. Useful for checking the syntax of scripts
  3560. (ignored if interactive).
  3561. .It Fl p | Ic privileged
  3562. The shell is a privileged shell.
  3563. It is set automatically if, when the shell starts,
  3564. the real UID or GID does not match
  3565. the effective UID (EUID) or GID (EGID), respectively.
  3566. See above for a description of what this means.
  3567. .It Fl s | Ic stdin
  3568. If used when the shell is invoked, commands are read from standard input.
  3569. Set automatically if the shell is invoked with no arguments.
  3570. .Pp
  3571. When
  3572. .Fl s
  3573. is used with the
  3574. .Ic set
  3575. command it causes the specified arguments to be sorted before assigning them to
  3576. the positional parameters (or to array
  3577. .Ar name ,
  3578. if
  3579. .Fl A
  3580. is used).
  3581. .It Fl u | Ic nounset
  3582. Referencing of an unset parameter is treated as an error, unless one of the
  3583. .Ql - ,
  3584. .Ql + ,
  3585. or
  3586. .Ql =
  3587. modifiers is used.
  3588. .It Fl v | Ic verbose
  3589. Write shell input to standard error as it is read.
  3590. .It Fl X | Ic markdirs
  3591. Mark directories with a trailing
  3592. .Ql /
  3593. during file name generation.
  3594. .It Fl x | Ic xtrace
  3595. Print commands and parameter assignments when they are executed, preceded by
  3596. the value of
  3597. .Ev PS4 .
  3598. .It Ic bgnice
  3599. Background jobs are run with lower priority.
  3600. .It Ic braceexpand
  3601. Enable brace expansion (a.k.a. alternation).
  3602. .It Ic csh-history
  3603. Enables a subset of
  3604. .Xr csh 1 Ns -style
  3605. history editing using the
  3606. .Ql !\&
  3607. character.
  3608. .It Ic emacs
  3609. Enable BRL emacs-like command-line editing (interactive shells only); see
  3610. .Sx Emacs editing mode .
  3611. .It Ic gmacs
  3612. Enable gmacs-like command-line editing (interactive shells only).
  3613. Currently identical to emacs editing except that transpose (^T) acts slightly
  3614. differently.
  3615. .It Ic ignoreeof
  3616. The shell will not (easily) exit when end-of-file is read;
  3617. .Ic exit
  3618. must be used.
  3619. To avoid infinite loops, the shell will exit if
  3620. .Dv EOF
  3621. is read 13 times in a row.
  3622. .It Ic interactive
  3623. The shell is an interactive shell.
  3624. This option can only be used when the shell is invoked.
  3625. See above for a description of what this means.
  3626. .It Ic login
  3627. The shell is a login shell.
  3628. This option can only be used when the shell is invoked.
  3629. See above for a description of what this means.
  3630. .It Ic nohup
  3631. Do not kill running jobs with a
  3632. .Dv SIGHUP
  3633. signal when a login shell exits.
  3634. Currently set by default;
  3635. this is different from the original Korn shell (which
  3636. doesn't have this option, but does send the
  3637. .Dv SIGHUP
  3638. signal).
  3639. .It Ic nolog
  3640. No effect.
  3641. In the original Korn shell, this prevents function definitions from
  3642. being stored in the history file.
  3643. .It Ic physical
  3644. Causes the
  3645. .Ic cd
  3646. and
  3647. .Ic pwd
  3648. commands to use
  3649. .Dq physical
  3650. (i.e. the filesystem's)
  3651. .Sq ..
  3652. directories instead of
  3653. .Dq logical
  3654. directories (i.e. the shell handles
  3655. .Sq .. ,
  3656. which allows the user to be oblivious of symbolic links to directories).
  3657. Clear by default.
  3658. Note that setting this option does not affect the current value of the
  3659. .Ev PWD
  3660. parameter; only the
  3661. .Ic cd
  3662. command changes
  3663. .Ev PWD .
  3664. See the
  3665. .Ic cd
  3666. and
  3667. .Ic pwd
  3668. commands above for more details.
  3669. .It Ic pipefail
  3670. The exit status of a pipeline is the exit status of the rightmost
  3671. command in the pipeline that doesn't return 0, or 0 if all commands
  3672. returned a 0 exit status.
  3673. .It Ic posix
  3674. Enable POSIX mode.
  3675. See
  3676. .Sx POSIX mode
  3677. above.
  3678. .It Ic restricted
  3679. The shell is a restricted shell.
  3680. This option can only be used when the shell is invoked.
  3681. See above for a description of what this means.
  3682. .It Ic sh
  3683. Enable strict Bourne shell mode (see
  3684. .Sx Strict Bourne shell mode
  3685. above).
  3686. .It Ic vi
  3687. Enable
  3688. .Xr vi 1 Ns -like
  3689. command-line editing (interactive shells only).
  3690. .It Ic vi-esccomplete
  3691. In vi command-line editing, do command and file name completion when escape
  3692. (^[) is entered in command mode.
  3693. .It Ic vi-show8
  3694. Prefix characters with the eighth bit set with
  3695. .Sq M- .
  3696. If this option is not set, characters in the range 128\-160 are printed as is,
  3697. which may cause problems.
  3698. .It Ic vi-tabcomplete
  3699. In vi command-line editing, do command and file name completion when tab (^I)
  3700. is entered in insert mode.
  3701. This is the default.
  3702. .It Ic viraw
  3703. No effect.
  3704. In the original Korn shell, unless
  3705. .Ic viraw
  3706. was set, the vi command-line mode would let the
  3707. .Xr tty 4
  3708. driver do the work until ESC (^[) was entered.
  3709. .Nm ksh
  3710. is always in viraw mode.
  3711. .El
  3712. .Pp
  3713. These options can also be used upon invocation of the shell.
  3714. The current set of
  3715. options (with single letter names) can be found in the parameter
  3716. .Sq $- .
  3717. .Ic set Fl o
  3718. with no option name will list all the options and whether each is on or off;
  3719. .Ic set +o
  3720. will print the current shell options in a form that
  3721. can be reinput to the shell to achieve the same option settings.
  3722. .Pp
  3723. Remaining arguments, if any, are positional parameters and are assigned, in
  3724. order, to the positional parameters (i.e. $1, $2, etc.).
  3725. If options end with
  3726. .Ql --
  3727. and there are no remaining arguments, all positional parameters are cleared.
  3728. If no options or arguments are given, the values of all names are printed.
  3729. For unknown historical reasons, a lone
  3730. .Ql -
  3731. option is treated specially \- it clears both the
  3732. .Fl x
  3733. and
  3734. .Fl v
  3735. options.
  3736. .Pp
  3737. .It Ic shift Op Ar number
  3738. The positional parameters
  3739. .Ar number Ns +1 ,
  3740. .Ar number Ns +2 ,
  3741. etc. are renamed to
  3742. .Sq 1 ,
  3743. .Sq 2 ,
  3744. etc.
  3745. .Ar number
  3746. defaults to 1.
  3747. .Pp
  3748. .It Ic suspend
  3749. Stops the shell as if it had received the suspend character from
  3750. the terminal.
  3751. It is not possible to suspend a login shell unless the parent process
  3752. is a member of the same terminal session but is a member of a different
  3753. process group.
  3754. As a general rule, if the shell was started by another shell or via
  3755. .Xr su 1 ,
  3756. it can be suspended.
  3757. .Pp
  3758. .It Ic test Ar expression
  3759. .It Ic \&[ Ar expression Ic \&]
  3760. .Ic test
  3761. evaluates the
  3762. .Ar expression
  3763. and returns zero status if true, 1 if false, or greater than 1 if there
  3764. was an error.
  3765. It is normally used as the condition command of
  3766. .Ic if
  3767. and
  3768. .Ic while
  3769. statements.
  3770. Symbolic links are followed for all
  3771. .Ar file
  3772. expressions except
  3773. .Fl h
  3774. and
  3775. .Fl L .
  3776. .Pp
  3777. The following basic expressions are available:
  3778. .Bl -tag -width 17n
  3779. .It Fl a Ar file
  3780. .Ar file
  3781. exists.
  3782. .It Fl b Ar file
  3783. .Ar file
  3784. is a block special device.
  3785. .It Fl c Ar file
  3786. .Ar file
  3787. is a character special device.
  3788. .It Fl d Ar file
  3789. .Ar file
  3790. is a directory.
  3791. .It Fl e Ar file
  3792. .Ar file
  3793. exists.
  3794. .It Fl f Ar file
  3795. .Ar file
  3796. is a regular file.
  3797. .It Fl G Ar file
  3798. .Ar file Ns 's
  3799. group is the shell's effective group ID.
  3800. .It Fl g Ar file
  3801. .Ar file Ns 's
  3802. mode has the setgid bit set.
  3803. .It Fl h Ar file
  3804. .Ar file
  3805. is a symbolic link.
  3806. .It Fl k Ar file
  3807. .Ar file Ns 's
  3808. mode has the
  3809. .Xr sticky 8
  3810. bit set.
  3811. .It Fl L Ar file
  3812. .Ar file
  3813. is a symbolic link.
  3814. .It Fl O Ar file
  3815. .Ar file Ns 's
  3816. owner is the shell's effective user ID.
  3817. .It Fl o Ar option
  3818. Shell
  3819. .Ar option
  3820. is set (see the
  3821. .Ic set
  3822. command above for a list of options).
  3823. As a non-standard extension, if the option starts with a
  3824. .Ql \&! ,
  3825. the test is negated; the test always fails if
  3826. .Ar option
  3827. doesn't exist (so [ -o foo -o -o !foo ] returns true if and only if option
  3828. .Ar foo
  3829. exists).
  3830. .It Fl p Ar file
  3831. .Ar file
  3832. is a named pipe.
  3833. .It Fl r Ar file
  3834. .Ar file
  3835. exists and is readable.
  3836. .It Fl S Ar file
  3837. .Ar file
  3838. is a
  3839. .Xr unix 4 Ns -domain
  3840. socket.
  3841. .It Fl s Ar file
  3842. .Ar file
  3843. is not empty.
  3844. .It Fl t Ar fd
  3845. File descriptor
  3846. .Ar fd
  3847. is a
  3848. .Xr tty 4
  3849. device.
  3850. .It Fl u Ar file
  3851. .Ar file Ns 's
  3852. mode has the setuid bit set.
  3853. .It Fl w Ar file
  3854. .Ar file
  3855. exists and is writable.
  3856. .It Fl x Ar file
  3857. .Ar file
  3858. exists and is executable.
  3859. .It Ar file1 Fl nt Ar file2
  3860. .Ar file1
  3861. is newer than
  3862. .Ar file2
  3863. or
  3864. .Ar file1
  3865. exists and
  3866. .Ar file2
  3867. does not.
  3868. .It Ar file1 Fl ot Ar file2
  3869. .Ar file1
  3870. is older than
  3871. .Ar file2
  3872. or
  3873. .Ar file2
  3874. exists and
  3875. .Ar file1
  3876. does not.
  3877. .It Ar file1 Fl ef Ar file2
  3878. .Ar file1
  3879. is the same file as
  3880. .Ar file2 .
  3881. .It Ar string
  3882. .Ar string
  3883. has non-zero length.
  3884. .It Fl n Ar string
  3885. .Ar string
  3886. is not empty.
  3887. .It Fl z Ar string
  3888. .Ar string
  3889. is empty.
  3890. .It Ar string No = Ar string
  3891. Strings are equal.
  3892. .It Ar string No == Ar string
  3893. Strings are equal.
  3894. .It Ar string No != Ar string
  3895. Strings are not equal.
  3896. .It Ar string No > Ar string
  3897. Strings compare greater than based on the ASCII value of their characters.
  3898. .It Ar string No < Ar string
  3899. Strings compare less than based on the ASCII value of their characters.
  3900. .It Ar number Fl eq Ar number
  3901. Numbers compare equal.
  3902. .It Ar number Fl ne Ar number
  3903. Numbers compare not equal.
  3904. .It Ar number Fl ge Ar number
  3905. Numbers compare greater than or equal.
  3906. .It Ar number Fl gt Ar number
  3907. Numbers compare greater than.
  3908. .It Ar number Fl le Ar number
  3909. Numbers compare less than or equal.
  3910. .It Ar number Fl \&lt Ar number
  3911. Numbers compare less than.
  3912. .El
  3913. .Pp
  3914. The above basic expressions, in which unary operators have precedence over
  3915. binary operators, may be combined with the following operators (listed in
  3916. increasing order of precedence):
  3917. .Bd -literal -offset indent
  3918. expr -o expr Logical OR.
  3919. expr -a expr Logical AND.
  3920. ! expr Logical NOT.
  3921. ( expr ) Grouping.
  3922. .Ed
  3923. .Pp
  3924. On operating systems not supporting
  3925. .Pa /dev/fd/ Ns Ar n
  3926. devices (where
  3927. .Ar n
  3928. is a file descriptor number), the
  3929. .Ic test
  3930. command will attempt to fake it for all tests that operate on files (except the
  3931. .Fl e
  3932. test).
  3933. For example,
  3934. [ -w /dev/fd/2 ] tests if file descriptor 2 is writable.
  3935. .Pp
  3936. Note that some special rules are applied (courtesy of POSIX)
  3937. if the number of
  3938. arguments to
  3939. .Ic test
  3940. or
  3941. .Ic \&[ ... \&]
  3942. is less than five: if leading
  3943. .Ql \&!
  3944. arguments can be stripped such that only one argument remains then a string
  3945. length test is performed (again, even if the argument is a unary operator); if
  3946. leading
  3947. .Ql \&!
  3948. arguments can be stripped such that three arguments remain and the second
  3949. argument is a binary operator, then the binary operation is performed (even
  3950. if the first argument is a unary operator, including an unstripped
  3951. .Ql \&! ) .
  3952. .Pp
  3953. .Sy Note :
  3954. A common mistake is to use
  3955. .Dq if \&[ $foo = bar \&]
  3956. which fails if parameter
  3957. .Dq foo
  3958. is
  3959. .Dv NULL
  3960. or unset, if it has embedded spaces (i.e.\&
  3961. .Ev IFS
  3962. characters), or if it is a unary operator like
  3963. .Sq \&!
  3964. or
  3965. .Sq Fl n .
  3966. Use tests like
  3967. .Dq if \&[ \&"X$foo\&" = Xbar \&]
  3968. instead.
  3969. .Pp
  3970. .It Xo
  3971. .Ic time
  3972. .Op Fl p
  3973. .Op Ar pipeline
  3974. .Xc
  3975. If a
  3976. .Ar pipeline
  3977. is given, the times used to execute the pipeline are reported.
  3978. If no pipeline
  3979. is given, then the user and system time used by the shell itself, and all the
  3980. commands it has run since it was started, are reported.
  3981. The times reported are the real time (elapsed time from start to finish),
  3982. the user CPU time (time spent running in user mode), and the system CPU time
  3983. (time spent running in kernel mode).
  3984. Times are reported to standard error; the format of the output is:
  3985. .Pp
  3986. .Dl "0m0.00s real 0m0.00s user 0m0.00s system"
  3987. .Pp
  3988. If the
  3989. .Fl p
  3990. option is given, the output is slightly longer:
  3991. .Bd -literal -offset indent
  3992. real 0.00
  3993. user 0.00
  3994. sys 0.00
  3995. .Ed
  3996. .Pp
  3997. It is an error to specify the
  3998. .Fl p
  3999. option unless
  4000. .Ar pipeline
  4001. is a simple command.
  4002. .Pp
  4003. Simple redirections of standard error do not affect the output of the
  4004. .Ic time
  4005. command:
  4006. .Pp
  4007. .Dl $ time sleep 1 2> afile
  4008. .Dl $ { time sleep 1; } 2> afile
  4009. .Pp
  4010. Times for the first command do not go to
  4011. .Dq afile ,
  4012. but those of the second command do.
  4013. .Pp
  4014. .It Ic times
  4015. Print the accumulated user and system times used both by the shell
  4016. and by processes that the shell started which have exited.
  4017. The format of the output is:
  4018. .Bd -literal -offset indent
  4019. 0m0.00s 0m0.00s
  4020. 0m0.00s 0m0.00s
  4021. .Ed
  4022. .Pp
  4023. .It Ic trap Op Ar handler signal ...
  4024. Sets a trap handler that is to be executed when any of the specified signals are
  4025. received.
  4026. .Ar handler
  4027. is either a
  4028. .Dv NULL
  4029. string, indicating the signals are to be ignored, a minus sign
  4030. .Pq Sq - ,
  4031. indicating that the default action is to be taken for the signals (see
  4032. .Xr signal 3 ) ,
  4033. or a string containing shell commands to be evaluated and executed at the first
  4034. opportunity (i.e. when the current command completes, or before printing the
  4035. next
  4036. .Ev PS1
  4037. prompt) after receipt of one of the signals.
  4038. .Ar signal
  4039. is the name of a signal (e.g.\&
  4040. .Dv PIPE
  4041. or
  4042. .Dv ALRM )
  4043. or the number of the signal (see the
  4044. .Ic kill -l
  4045. command above).
  4046. .Pp
  4047. There are two special signals:
  4048. .Dv EXIT
  4049. (also known as 0), which is executed when the shell is about to exit, and
  4050. .Dv ERR ,
  4051. which is executed after an error occurs (an error is something that would cause
  4052. the shell to exit if the
  4053. .Fl e
  4054. or
  4055. .Ic errexit
  4056. option were set \- see the
  4057. .Ic set
  4058. command above).
  4059. .Dv EXIT
  4060. handlers are executed in the environment of the last executed command.
  4061. Note
  4062. that for non-interactive shells, the trap handler cannot be changed for signals
  4063. that were ignored when the shell started.
  4064. .Pp
  4065. With no arguments,
  4066. .Ic trap
  4067. lists, as a series of
  4068. .Ic trap
  4069. commands, the current state of the traps that have been set since the shell
  4070. started.
  4071. Note that the output of
  4072. .Ic trap
  4073. cannot be usefully piped to another process (an artifact of the fact that
  4074. traps are cleared when subprocesses are created).
  4075. .Pp
  4076. The original Korn shell's
  4077. .Dv DEBUG
  4078. trap and the handling of
  4079. .Dv ERR
  4080. and
  4081. .Dv EXIT
  4082. traps in functions are not yet implemented.
  4083. .Pp
  4084. .It Ic true
  4085. A command that exits with a zero value.
  4086. .Pp
  4087. .It Ic type
  4088. Short form of
  4089. .Ic command Fl V
  4090. (see above).
  4091. .Pp
  4092. .It Xo
  4093. .Ic typeset
  4094. .Oo
  4095. .Op Ic +-lprtUux
  4096. .Op Fl L Ns Op Ar n
  4097. .Op Fl R Ns Op Ar n
  4098. .Op Fl Z Ns Op Ar n
  4099. .Op Fl i Ns Op Ar n
  4100. .No \&| Fl f Op Fl tux
  4101. .Oc
  4102. .Op Ar name Ns Oo = Ns Ar value Oc Ar ...
  4103. .Xc
  4104. Display or set parameter attributes.
  4105. With no
  4106. .Ar name
  4107. arguments, parameter attributes are displayed; if no options are used, the
  4108. current attributes of all parameters are printed as
  4109. .Ic typeset
  4110. commands; if an option is given (or
  4111. .Ql -
  4112. with no option letter), all parameters and their values with the specified
  4113. attributes are printed; if options are introduced with
  4114. .Ql + ,
  4115. parameter values are not printed.
  4116. .Pp
  4117. If
  4118. .Ar name
  4119. arguments are given, the attributes of the named parameters are set
  4120. .Pq Ic -
  4121. or cleared
  4122. .Pq Ic + .
  4123. Values for parameters may optionally be specified.
  4124. If
  4125. .Ic typeset
  4126. is used inside a function, any newly created parameters are local to the
  4127. function.
  4128. .Pp
  4129. When
  4130. .Fl f
  4131. is used,
  4132. .Ic typeset
  4133. operates on the attributes of functions.
  4134. As with parameters, if no
  4135. .Ar name
  4136. arguments are given,
  4137. functions are listed with their values (i.e. definitions) unless
  4138. options are introduced with
  4139. .Ql + ,
  4140. in which case only the function names are reported.
  4141. .Bl -tag -width Ds
  4142. .It Fl f
  4143. Function mode.
  4144. Display or set functions and their attributes, instead of parameters.
  4145. .It Fl i Ns Op Ar n
  4146. Integer attribute.
  4147. .Ar n
  4148. specifies the base to use when displaying the integer (if not specified, the
  4149. base given in the first assignment is used).
  4150. Parameters with this attribute may
  4151. be assigned values containing arithmetic expressions.
  4152. .It Fl L Ns Op Ar n
  4153. Left justify attribute.
  4154. .Ar n
  4155. specifies the field width.
  4156. If
  4157. .Ar n
  4158. is not specified, the current width of a parameter (or the width of its first
  4159. assigned value) is used.
  4160. Leading whitespace (and zeros, if used with the
  4161. .Fl Z
  4162. option) is stripped.
  4163. If necessary, values are either truncated or space padded
  4164. to fit the field width.
  4165. .It Fl l
  4166. Lower case attribute.
  4167. All upper case characters in values are converted to lower case.
  4168. (In the original Korn shell, this parameter meant
  4169. .Dq long integer
  4170. when used with the
  4171. .Fl i
  4172. option.)
  4173. .It Fl p
  4174. Print complete
  4175. .Ic typeset
  4176. commands that can be used to re-create the attributes (but not the values) of
  4177. parameters.
  4178. This is the default action (option exists for ksh93 compatibility).
  4179. .It Fl R Ns Op Ar n
  4180. Right justify attribute.
  4181. .Ar n
  4182. specifies the field width.
  4183. If
  4184. .Ar n
  4185. is not specified, the current width of a parameter (or the width of its first
  4186. assigned value) is used.
  4187. Trailing whitespace is stripped.
  4188. If necessary, values are either stripped of leading characters or space
  4189. padded to make them fit the field width.
  4190. .It Fl r
  4191. Read-only attribute.
  4192. Parameters with this attribute may not be assigned to or unset.
  4193. Once this attribute is set, it cannot be turned off.
  4194. .It Fl t
  4195. Tag attribute.
  4196. Has no meaning to the shell; provided for application use.
  4197. .Pp
  4198. For functions,
  4199. .Fl t
  4200. is the trace attribute.
  4201. When functions with the trace attribute are executed, the
  4202. .Ic xtrace
  4203. .Pq Fl x
  4204. shell option is temporarily turned on.
  4205. .It Fl U
  4206. Unsigned integer attribute.
  4207. Integers are printed as unsigned values (only
  4208. useful when combined with the
  4209. .Fl i
  4210. option).
  4211. This option is not in the original Korn shell.
  4212. .It Fl u
  4213. Upper case attribute.
  4214. All lower case characters in values are converted to upper case.
  4215. (In the original Korn shell, this parameter meant
  4216. .Dq unsigned integer
  4217. when used with the
  4218. .Fl i
  4219. option, which meant upper case letters would never be used for bases greater
  4220. than 10.
  4221. See the
  4222. .Fl U
  4223. option.)
  4224. .Pp
  4225. For functions,
  4226. .Fl u
  4227. is the undefined attribute.
  4228. See
  4229. .Sx Functions
  4230. above for the implications of this.
  4231. .It Fl x
  4232. Export attribute.
  4233. Parameters (or functions) are placed in the environment of
  4234. any executed commands.
  4235. Exported functions are not yet implemented.
  4236. .It Fl Z Ns Op Ar n
  4237. Zero fill attribute.
  4238. If not combined with
  4239. .Fl L ,
  4240. this is the same as
  4241. .Fl R ,
  4242. except zero padding is used instead of space padding.
  4243. .El
  4244. .Pp
  4245. .It Xo
  4246. .Ic ulimit
  4247. .Op Fl acdfHlmnpSst Op Ar value
  4248. .Ar ...
  4249. .Xc
  4250. Display or set process limits.
  4251. If no options are used, the file size limit
  4252. .Pq Fl f
  4253. is assumed.
  4254. .Ar value ,
  4255. if specified, may be either an arithmetic expression starting with a
  4256. number or the word
  4257. .Dq unlimited .
  4258. The limits affect the shell and any processes created by the shell after a
  4259. limit is imposed; limits may not be increased once they are set.
  4260. .Bl -tag -width 5n
  4261. .It Fl a
  4262. Display all limits; unless
  4263. .Fl H
  4264. is used, soft limits are displayed.
  4265. .It Fl c Ar n
  4266. Impose a size limit of
  4267. .Ar n
  4268. blocks on the size of core dumps.
  4269. .It Fl d Ar n
  4270. Impose a size limit of
  4271. .Ar n
  4272. kilobytes on the size of the data area.
  4273. .It Fl f Ar n
  4274. Impose a size limit of
  4275. .Ar n
  4276. blocks on files written by the shell and its child processes (files of any
  4277. size may be read).
  4278. .It Fl H
  4279. Set the hard limit only (the default is to set both hard and soft limits).
  4280. .It Fl l Ar n
  4281. Impose a limit of
  4282. .Ar n
  4283. kilobytes on the amount of locked (wired) physical memory.
  4284. .It Fl m Ar n
  4285. Impose a limit of
  4286. .Ar n
  4287. kilobytes on the amount of physical memory used.
  4288. This limit is not enforced.
  4289. .It Fl n Ar n
  4290. Impose a limit of
  4291. .Ar n
  4292. file descriptors that can be open at once.
  4293. .It Fl p Ar n
  4294. Impose a limit of
  4295. .Ar n
  4296. processes that can be run by the user at any one time.
  4297. .It Fl S
  4298. Set the soft limit only (the default is to set both hard and soft limits).
  4299. .It Fl s Ar n
  4300. Impose a size limit of
  4301. .Ar n
  4302. kilobytes on the size of the stack area.
  4303. .It Fl t Ar n
  4304. Impose a time limit of
  4305. .Ar n
  4306. CPU seconds spent in user mode to be used by each process.
  4307. .\".It Fl v Ar n
  4308. .\"Impose a limit of
  4309. .\"Ar n
  4310. .\"kilobytes on the amount of virtual memory used.
  4311. .El
  4312. .Pp
  4313. As far as
  4314. .Ic ulimit
  4315. is concerned, a block is 512 bytes.
  4316. .Pp
  4317. .It Xo
  4318. .Ic umask
  4319. .Op Fl S
  4320. .Op Ar mask
  4321. .Xc
  4322. Display or set the file permission creation mask, or umask (see
  4323. .Xr umask 2 ) .
  4324. If the
  4325. .Fl S
  4326. option is used, the mask displayed or set is symbolic; otherwise, it is an
  4327. octal number.
  4328. .Pp
  4329. Symbolic masks are like those used by
  4330. .Xr chmod 1 .
  4331. When used, they describe what permissions may be made available (as opposed to
  4332. octal masks in which a set bit means the corresponding bit is to be cleared).
  4333. For example,
  4334. .Dq ug=rwx,o=
  4335. sets the mask so files will not be readable, writable, or executable by
  4336. .Dq others ,
  4337. and is equivalent (on most systems) to the octal mask
  4338. .Dq 007 .
  4339. .Pp
  4340. .It Xo
  4341. .Ic unalias
  4342. .Op Fl adt
  4343. .Op Ar name ...
  4344. .Xc
  4345. The aliases for the given names are removed.
  4346. If the
  4347. .Fl a
  4348. option is used, all aliases are removed.
  4349. If the
  4350. .Fl t
  4351. or
  4352. .Fl d
  4353. options are used, the indicated operations are carried out on tracked or
  4354. directory aliases, respectively.
  4355. .Pp
  4356. .It Xo
  4357. .Ic unset
  4358. .Op Fl fv
  4359. .Ar parameter ...
  4360. .Xc
  4361. Unset the named parameters
  4362. .Po
  4363. .Fl v ,
  4364. the default
  4365. .Pc
  4366. or functions
  4367. .Pq Fl f .
  4368. The exit status is non-zero if any of the parameters have the read-only
  4369. attribute set, zero otherwise.
  4370. .Pp
  4371. .It Ic wait Op Ar job ...
  4372. Wait for the specified job(s) to finish.
  4373. The exit status of
  4374. .Ic wait
  4375. is that of the last specified job; if the last job is killed by a signal, the
  4376. exit status is 128 + the number of the signal (see
  4377. .Ic kill -l Ar exit-status
  4378. above); if the last specified job can't be found (because it never existed, or
  4379. had already finished), the exit status of
  4380. .Ic wait
  4381. is 127.
  4382. See
  4383. .Sx Job control
  4384. below for the format of
  4385. .Ar job .
  4386. .Ic wait
  4387. will return if a signal for which a trap has been set is received, or if a
  4388. .Dv SIGHUP ,
  4389. .Dv SIGINT ,
  4390. or
  4391. .Dv SIGQUIT
  4392. signal is received.
  4393. .Pp
  4394. If no jobs are specified,
  4395. .Ic wait
  4396. waits for all currently running jobs (if any) to finish and exits with a zero
  4397. status.
  4398. If job monitoring is enabled, the completion status of jobs is printed
  4399. (this is not the case when jobs are explicitly specified).
  4400. .Pp
  4401. .It Xo
  4402. .Ic whence
  4403. .Op Fl pv
  4404. .Op Ar name ...
  4405. .Xc
  4406. For each
  4407. .Ar name ,
  4408. the type of command is listed (reserved word, built-in, alias,
  4409. function, tracked alias, or executable).
  4410. If the
  4411. .Fl p
  4412. option is used, a path search is performed even if
  4413. .Ar name
  4414. is a reserved word, alias, etc.
  4415. Without the
  4416. .Fl v
  4417. option,
  4418. .Ic whence
  4419. is similar to
  4420. .Ic command Fl v
  4421. except that
  4422. .Ic whence
  4423. won't print aliases as alias commands.
  4424. With the
  4425. .Fl v
  4426. option,
  4427. .Ic whence
  4428. is the same as
  4429. .Ic command Fl V .
  4430. Note that for
  4431. .Ic whence ,
  4432. the
  4433. .Fl p
  4434. option does not affect the search path used, as it does for
  4435. .Ic command .
  4436. If the type of one or more of the names could not be determined, the exit
  4437. status is non-zero.
  4438. .El
  4439. .Ss Job control
  4440. Job control refers to the shell's ability to monitor and control jobs, which
  4441. are processes or groups of processes created for commands or pipelines.
  4442. At a minimum, the shell keeps track of the status of the background (i.e.\&
  4443. asynchronous) jobs that currently exist; this information can be displayed
  4444. using the
  4445. .Ic jobs
  4446. commands.
  4447. If job control is fully enabled (using
  4448. .Ic set -m
  4449. or
  4450. .Ic set -o monitor ) ,
  4451. as it is for interactive shells, the processes of a job are placed in their
  4452. own process group.
  4453. Foreground jobs can be stopped by typing the suspend
  4454. character from the terminal (normally ^Z), jobs can be restarted in either the
  4455. foreground or background using the
  4456. .Ic fg
  4457. and
  4458. .Ic bg
  4459. commands, and the state of the terminal is saved or restored when a foreground
  4460. job is stopped or restarted, respectively.
  4461. .Pp
  4462. Note that only commands that create processes (e.g. asynchronous commands,
  4463. subshell commands, and non-built-in, non-function commands) can be stopped;
  4464. commands like
  4465. .Ic read
  4466. cannot be.
  4467. .Pp
  4468. When a job is created, it is assigned a job number.
  4469. For interactive shells, this number is printed inside
  4470. .Dq [..] ,
  4471. followed by the process IDs of the processes in the job when an asynchronous
  4472. command is run.
  4473. A job may be referred to in the
  4474. .Ic bg ,
  4475. .Ic fg ,
  4476. .Ic jobs ,
  4477. .Ic kill ,
  4478. and
  4479. .Ic wait
  4480. commands either by the process ID of the last process in the command pipeline
  4481. (as stored in the
  4482. .Ic $!\&
  4483. parameter) or by prefixing the job number with a percent
  4484. sign
  4485. .Pq Sq % .
  4486. Other percent sequences can also be used to refer to jobs:
  4487. .Bl -tag -width "%+ | %% | %XX"
  4488. .It %+ | %% | %
  4489. The most recently stopped job or, if there are no stopped jobs, the oldest
  4490. running job.
  4491. .It %-
  4492. The job that would be the
  4493. .Ic %+
  4494. job if the latter did not exist.
  4495. .It % Ns Ar n
  4496. The job with job number
  4497. .Ar n .
  4498. .It %? Ns Ar string
  4499. The job with its command containing the string
  4500. .Ar string
  4501. (an error occurs if multiple jobs are matched).
  4502. .It % Ns Ar string
  4503. The job with its command starting with the string
  4504. .Ar string
  4505. (an error occurs if multiple jobs are matched).
  4506. .El
  4507. .Pp
  4508. When a job changes state (e.g. a background job finishes or foreground job is
  4509. stopped), the shell prints the following status information:
  4510. .Pp
  4511. .D1 [ Ns Ar number ] Ar flag status command
  4512. .Pp
  4513. where...
  4514. .Bl -tag -width "command"
  4515. .It Ar number
  4516. is the job number of the job;
  4517. .It Ar flag
  4518. is the
  4519. .Ql +
  4520. or
  4521. .Ql -
  4522. character if the job is the
  4523. .Ic %+
  4524. or
  4525. .Ic %-
  4526. job, respectively, or space if it is neither;
  4527. .It Ar status
  4528. indicates the current state of the job and can be:
  4529. .Bl -tag -width "RunningXX"
  4530. .It Done Op Ar number
  4531. The job exited.
  4532. .Ar number
  4533. is the exit status of the job, which is omitted if the status is zero.
  4534. .It Running
  4535. The job has neither stopped nor exited (note that running does not necessarily
  4536. mean consuming CPU time \-
  4537. the process could be blocked waiting for some event).
  4538. .It Stopped Op Ar signal
  4539. The job was stopped by the indicated
  4540. .Ar signal
  4541. (if no signal is given, the job was stopped by
  4542. .Dv SIGTSTP ) .
  4543. .It Ar signal-description Op Dq core dumped
  4544. The job was killed by a signal (e.g. memory fault, hangup); use
  4545. .Ic kill -l
  4546. for a list of signal descriptions.
  4547. The
  4548. .Dq core dumped
  4549. message indicates the process created a core file.
  4550. .El
  4551. .It Ar command
  4552. is the command that created the process.
  4553. If there are multiple processes in
  4554. the job, each process will have a line showing its
  4555. .Ar command
  4556. and possibly its
  4557. .Ar status ,
  4558. if it is different from the status of the previous process.
  4559. .El
  4560. .Pp
  4561. When an attempt is made to exit the shell while there are jobs in the stopped
  4562. state, the shell warns the user that there are stopped jobs and does not exit.
  4563. If another attempt is immediately made to exit the shell, the stopped jobs are
  4564. sent a
  4565. .Dv SIGHUP
  4566. signal and the shell exits.
  4567. Similarly, if the
  4568. .Ic nohup
  4569. option is not set and there are running jobs when an attempt is made to exit
  4570. a login shell, the shell warns the user and does not exit.
  4571. If another attempt
  4572. is immediately made to exit the shell, the running jobs are sent a
  4573. .Dv SIGHUP
  4574. signal and the shell exits.
  4575. .Ss Interactive input line editing
  4576. The shell supports three modes of reading command lines from a
  4577. .Xr tty 4
  4578. in an interactive session, controlled by the
  4579. .Ic emacs ,
  4580. .Ic gmacs ,
  4581. and
  4582. .Ic vi
  4583. options (at most one of these can be set at once).
  4584. The default is
  4585. .Ic emacs .
  4586. Editing modes can be set explicitly using the
  4587. .Ic set
  4588. built-in, or implicitly via the
  4589. .Ev EDITOR
  4590. and
  4591. .Ev VISUAL
  4592. environment variables.
  4593. If none of these options are enabled,
  4594. the shell simply reads lines using the normal
  4595. .Xr tty 4
  4596. driver.
  4597. If the
  4598. .Ic emacs
  4599. or
  4600. .Ic gmacs
  4601. option is set, the shell allows emacs-like editing of the command; similarly,
  4602. if the
  4603. .Ic vi
  4604. option is set, the shell allows vi-like editing of the command.
  4605. These modes are described in detail in the following sections.
  4606. .Pp
  4607. In these editing modes, if a line is longer than the screen width (see the
  4608. .Ev COLUMNS
  4609. parameter),
  4610. a
  4611. .Ql > ,
  4612. .Ql + ,
  4613. or
  4614. .Ql <
  4615. character is displayed in the last column indicating that there are more
  4616. characters after, before and after, or before the current position,
  4617. respectively.
  4618. The line is scrolled horizontally as necessary.
  4619. .Ss Emacs editing mode
  4620. When the
  4621. .Ic emacs
  4622. option is set, interactive input line editing is enabled.
  4623. Warning: This mode is
  4624. slightly different from the emacs mode in the original Korn shell.
  4625. In this mode, various editing commands
  4626. (typically bound to one or more control characters) cause immediate actions
  4627. without waiting for a newline.
  4628. Several editing commands are bound to particular
  4629. control characters when the shell is invoked; these bindings can be changed
  4630. using the
  4631. .Ic bind
  4632. command.
  4633. .Pp
  4634. The following is a list of available editing commands.
  4635. Each description starts with the name of the command,
  4636. suffixed with a colon;
  4637. an
  4638. .Op Ar n
  4639. (if the command can be prefixed with a count); and any keys the command is
  4640. bound to by default, written using caret notation
  4641. e.g. the ASCII ESC character is written as ^[.
  4642. ^[A-Z] sequences are not case sensitive.
  4643. A count prefix for a command is entered using the sequence
  4644. .Pf ^[ Ar n ,
  4645. where
  4646. .Ar n
  4647. is a sequence of 1 or more digits.
  4648. Unless otherwise specified, if a count is
  4649. omitted, it defaults to 1.
  4650. .Pp
  4651. Note that editing command names are used only with the
  4652. .Ic bind
  4653. command.
  4654. Furthermore, many editing commands are useful only on terminals with
  4655. a visible cursor.
  4656. The default bindings were chosen to resemble corresponding
  4657. Emacs key bindings.
  4658. The user's
  4659. .Xr tty 4
  4660. characters (e.g.\&
  4661. .Dv ERASE )
  4662. are bound to
  4663. reasonable substitutes and override the default bindings.
  4664. .Bl -tag -width Ds
  4665. .It abort: ^C, ^G
  4666. Useful as a response to a request for a
  4667. .Ic search-history
  4668. pattern in order to abort the search.
  4669. .It auto-insert: Op Ar n
  4670. Simply causes the character to appear as literal input.
  4671. Most ordinary characters are bound to this.
  4672. .It Xo backward-char:
  4673. .Op Ar n
  4674. .No ^B , ^X^D
  4675. .Xc
  4676. Moves the cursor backward
  4677. .Ar n
  4678. characters.
  4679. .It Xo backward-word:
  4680. .Op Ar n
  4681. .No ^[b
  4682. .Xc
  4683. Moves the cursor backward to the beginning of the word; words consist of
  4684. alphanumerics, underscore
  4685. .Pq Sq _ ,
  4686. and dollar sign
  4687. .Pq Sq $
  4688. characters.
  4689. .It beginning-of-history: ^[<
  4690. Moves to the beginning of the history.
  4691. .It beginning-of-line: ^A
  4692. Moves the cursor to the beginning of the edited input line.
  4693. .It Xo capitalize-word:
  4694. .Op Ar n
  4695. .No ^[C , ^[c
  4696. .Xc
  4697. Uppercase the first character in the next
  4698. .Ar n
  4699. words, leaving the cursor past the end of the last word.
  4700. .It clear-screen: ^L
  4701. Clears the screen if the
  4702. .Ev TERM
  4703. parameter is set and the terminal supports clearing the screen, then
  4704. reprints the prompt string and the current input line.
  4705. .It comment: ^[#
  4706. If the current line does not begin with a comment character, one is added at
  4707. the beginning of the line and the line is entered (as if return had been
  4708. pressed); otherwise, the existing comment characters are removed and the cursor
  4709. is placed at the beginning of the line.
  4710. .It complete: ^[^[
  4711. Automatically completes as much as is unique of the command name or the file
  4712. name containing the cursor.
  4713. If the entire remaining command or file name is
  4714. unique, a space is printed after its completion, unless it is a directory name
  4715. in which case
  4716. .Ql /
  4717. is appended.
  4718. If there is no command or file name with the current partial word
  4719. as its prefix, a bell character is output (usually causing a beep to be
  4720. sounded).
  4721. .Pp
  4722. Custom completions may be configured by creating an array named
  4723. .Ql complete_command ,
  4724. optionally suffixed with an argument number to complete only for a single
  4725. argument.
  4726. So defining an array named
  4727. .Ql complete_kill
  4728. provides possible completions for any argument to the
  4729. .Xr kill 1
  4730. command, but
  4731. .Ql complete_kill_1
  4732. only completes the first argument.
  4733. For example, the following command makes
  4734. .Nm
  4735. offer a selection of signal names for the first argument to
  4736. .Xr kill 1 :
  4737. .Pp
  4738. .Dl set -A complete_kill_1 -- -9 -HUP -INFO -KILL -TERM
  4739. .It complete-command: ^X^[
  4740. Automatically completes as much as is unique of the command name having the
  4741. partial word up to the cursor as its prefix, as in the
  4742. .Ic complete
  4743. command above.
  4744. .It complete-file: ^[^X
  4745. Automatically completes as much as is unique of the file name having the
  4746. partial word up to the cursor as its prefix, as in the
  4747. .Ic complete
  4748. command described above.
  4749. .It complete-list: ^I, ^[=
  4750. Complete as much as is possible of the current word,
  4751. and list the possible completions for it.
  4752. If only one completion is possible,
  4753. match as in the
  4754. .Ic complete
  4755. command above.
  4756. .It Xo delete-char-backward:
  4757. .Op Ar n
  4758. .No ERASE , ^? , ^H
  4759. .Xc
  4760. Deletes
  4761. .Ar n
  4762. characters before the cursor.
  4763. .It Xo delete-char-forward:
  4764. .Op Ar n
  4765. .No Delete
  4766. .Xc
  4767. Deletes
  4768. .Ar n
  4769. characters after the cursor.
  4770. .It Xo delete-word-backward:
  4771. .Op Ar n
  4772. .No WERASE , ^[ERASE , ^W, ^[^? , ^[^H , ^[h
  4773. .Xc
  4774. Deletes
  4775. .Ar n
  4776. words before the cursor.
  4777. .It Xo delete-word-forward:
  4778. .Op Ar n
  4779. .No ^[d
  4780. .Xc
  4781. Deletes
  4782. .Ar n
  4783. words after the cursor.
  4784. .It Xo down-history:
  4785. .Op Ar n
  4786. .No ^N , ^XB
  4787. .Xc
  4788. Scrolls the history buffer forward
  4789. .Ar n
  4790. lines (later).
  4791. Each input line originally starts just after the last entry
  4792. in the history buffer, so
  4793. .Ic down-history
  4794. is not useful until either
  4795. .Ic search-history
  4796. or
  4797. .Ic up-history
  4798. has been performed.
  4799. .It Xo downcase-word:
  4800. .Op Ar n
  4801. .No ^[L , ^[l
  4802. .Xc
  4803. Lowercases the next
  4804. .Ar n
  4805. words.
  4806. .It end-of-history: ^[>
  4807. Moves to the end of the history.
  4808. .It end-of-line: ^E
  4809. Moves the cursor to the end of the input line.
  4810. .It eot: ^_
  4811. Acts as an end-of-file; this is useful because edit-mode input disables
  4812. normal terminal input canonicalization.
  4813. .It Xo eot-or-delete:
  4814. .Op Ar n
  4815. .No ^D
  4816. .Xc
  4817. Acts as
  4818. .Ic eot
  4819. if alone on a line; otherwise acts as
  4820. .Ic delete-char-forward .
  4821. .It error:
  4822. Error (ring the bell).
  4823. .It exchange-point-and-mark: ^X^X
  4824. Places the cursor where the mark is and sets the mark to where the cursor was.
  4825. .It expand-file: ^[*
  4826. Appends a
  4827. .Ql *
  4828. to the current word and replaces the word with the result of performing file
  4829. globbing on the word.
  4830. If no files match the pattern, the bell is rung.
  4831. .It Xo forward-char:
  4832. .Op Ar n
  4833. .No ^F , ^XC
  4834. .Xc
  4835. Moves the cursor forward
  4836. .Ar n
  4837. characters.
  4838. .It Xo forward-word:
  4839. .Op Ar n
  4840. .No ^[f
  4841. .Xc
  4842. Moves the cursor forward to the end of the
  4843. .Ar n Ns th
  4844. word.
  4845. .It Xo goto-history:
  4846. .Op Ar n
  4847. .No ^[g
  4848. .Xc
  4849. Goes to history number
  4850. .Ar n .
  4851. .It kill-line: KILL
  4852. Deletes the entire input line.
  4853. .It Xo kill-to-eol:
  4854. .Op Ar n
  4855. .No ^K
  4856. .Xc
  4857. Deletes the input from the cursor to the end of the line if
  4858. .Ar n
  4859. is not specified; otherwise deletes characters between the cursor and column
  4860. .Ar n .
  4861. .It list: ^[?
  4862. Prints a sorted, columnated list of command names or file names (if any) that
  4863. can complete the partial word containing the cursor.
  4864. Directory names have
  4865. .Ql /
  4866. appended to them.
  4867. .It list-command: ^X?
  4868. Prints a sorted, columnated list of command names (if any) that can complete
  4869. the partial word containing the cursor.
  4870. .It list-file: ^X^Y
  4871. Prints a sorted, columnated list of file names (if any) that can complete the
  4872. partial word containing the cursor.
  4873. File type indicators are appended as described under
  4874. .Ic list
  4875. above.
  4876. .It newline: ^J , ^M
  4877. Causes the current input line to be processed by the shell.
  4878. The current cursor position may be anywhere on the line.
  4879. .It newline-and-next: ^O
  4880. Causes the current input line to be processed by the shell, and the next line
  4881. from history becomes the current line.
  4882. This is only useful after an
  4883. .Ic up-history
  4884. or
  4885. .Ic search-history .
  4886. .It no-op: QUIT
  4887. This does nothing.
  4888. .It Xo prev-hist-word:
  4889. .Op Ar n
  4890. .No ^[. , ^[_
  4891. .Xc
  4892. The last
  4893. .Pq Ar n Ns th
  4894. word of the previous command is inserted at the cursor.
  4895. .It quote: ^^
  4896. The following character is taken literally rather than as an editing command.
  4897. .It redraw:
  4898. Reprints the prompt string and the current input line.
  4899. .It Xo search-character-backward:
  4900. .Op Ar n
  4901. .No ^[^]
  4902. .Xc
  4903. Search backward in the current line for the
  4904. .Ar n Ns th
  4905. occurrence of the next character typed.
  4906. .It Xo search-character-forward:
  4907. .Op Ar n
  4908. .No ^]
  4909. .Xc
  4910. Search forward in the current line for the
  4911. .Ar n Ns th
  4912. occurrence of the next character typed.
  4913. .It search-history: ^R
  4914. Enter incremental search mode.
  4915. The internal history list is searched
  4916. backwards for commands matching the input.
  4917. An initial
  4918. .Ql ^
  4919. in the search string anchors the search.
  4920. The abort key will leave search mode.
  4921. Other commands will be executed after leaving search mode.
  4922. Successive
  4923. .Ic search-history
  4924. commands continue searching backward to the next previous occurrence of the
  4925. pattern.
  4926. The history buffer retains only a finite number of lines; the oldest
  4927. are discarded as necessary.
  4928. .It set-mark-command: ^[ Ns Aq space
  4929. Set the mark at the cursor position.
  4930. .It transpose-chars: ^T
  4931. If at the end of line, or if the
  4932. .Ic gmacs
  4933. option is set, this exchanges the two previous characters; otherwise, it
  4934. exchanges the previous and current characters and moves the cursor one
  4935. character to the right.
  4936. .It Xo up-history:
  4937. .Op Ar n
  4938. .No ^P , ^XA
  4939. .Xc
  4940. Scrolls the history buffer backward
  4941. .Ar n
  4942. lines (earlier).
  4943. .It Xo upcase-word:
  4944. .Op Ar n
  4945. .No ^[U , ^[u
  4946. .Xc
  4947. Uppercase the next
  4948. .Ar n
  4949. words.
  4950. .It quote: ^V
  4951. Synonym for ^^.
  4952. .It yank: ^Y
  4953. Inserts the most recently killed text string at the current cursor position.
  4954. .It yank-pop: ^[y
  4955. Immediately after a
  4956. .Ic yank ,
  4957. replaces the inserted text string with the next previously killed text string.
  4958. .El
  4959. .Pp
  4960. The following editing commands lack default bindings but can be used with the
  4961. .Ic bind
  4962. command:
  4963. .Bl -tag -width Ds
  4964. .It kill-region
  4965. Deletes the input between the cursor and the mark.
  4966. .El
  4967. .Ss Vi editing mode
  4968. The vi command-line editor in
  4969. .Nm
  4970. has basically the same commands as the
  4971. .Xr vi 1
  4972. editor with the following exceptions:
  4973. .Bl -bullet
  4974. .It
  4975. You start out in insert mode.
  4976. .It
  4977. There are file name and command completion commands:
  4978. =, \e, *, ^X, ^E, ^F, and, optionally,
  4979. .Aq tab
  4980. and
  4981. .Aq esc .
  4982. .It
  4983. The
  4984. .Ic _
  4985. command is different (in
  4986. .Nm
  4987. it is the last argument command; in
  4988. .Xr vi 1
  4989. it goes to the start of the current line).
  4990. .It
  4991. The
  4992. .Ic /
  4993. and
  4994. .Ic G
  4995. commands move in the opposite direction to the
  4996. .Ic j
  4997. command.
  4998. .It
  4999. Commands which don't make sense in a single line editor are not available
  5000. (e.g. screen movement commands and
  5001. .Xr ex 1 Ns -style
  5002. colon
  5003. .Pq Ic \&:
  5004. commands).
  5005. .El
  5006. .Pp
  5007. Note that the ^X stands for control-X; also
  5008. .Aq esc ,
  5009. .Aq space ,
  5010. and
  5011. .Aq tab
  5012. are used for escape, space, and tab, respectively (no kidding).
  5013. .Pp
  5014. Like
  5015. .Xr vi 1 ,
  5016. there are two modes:
  5017. .Dq insert
  5018. mode and
  5019. .Dq command
  5020. mode.
  5021. In insert mode, most characters are simply put in the buffer at the
  5022. current cursor position as they are typed; however, some characters are
  5023. treated specially.
  5024. In particular, the following characters are taken from current
  5025. .Xr tty 4
  5026. settings
  5027. (see
  5028. .Xr stty 1 )
  5029. and have their usual meaning (normal values are in parentheses): kill (^U),
  5030. erase (^?), werase (^W), eof (^D), intr (^C), and quit (^\e).
  5031. In addition to
  5032. the above, the following characters are also treated specially in insert mode:
  5033. .Bl -tag -width 10n
  5034. .It ^E
  5035. Command and file name enumeration (see below).
  5036. .It ^F
  5037. Command and file name completion (see below).
  5038. If used twice in a row, the
  5039. list of possible completions is displayed; if used a third time, the completion
  5040. is undone.
  5041. .It ^H
  5042. Erases previous character.
  5043. .It ^J | ^M
  5044. End of line.
  5045. The current line is read, parsed, and executed by the shell.
  5046. .It ^L
  5047. Clear the screen (if possible) and redraw the current line.
  5048. See the
  5049. .Em clear-screen
  5050. command in
  5051. .Sx Emacs editing mode
  5052. for more information.
  5053. .It ^R
  5054. Redraw the current line.
  5055. .It ^V
  5056. Literal next.
  5057. The next character typed is not treated specially (can be used
  5058. to insert the characters being described here).
  5059. .It ^X
  5060. Command and file name expansion (see below).
  5061. .It Aq esc
  5062. Puts the editor in command mode (see below).
  5063. .It Aq tab
  5064. Optional file name and command completion (see
  5065. .Ic ^F
  5066. above), enabled with
  5067. .Ic set -o vi-tabcomplete .
  5068. .El
  5069. .Pp
  5070. In command mode, each character is interpreted as a command.
  5071. Characters that
  5072. don't correspond to commands, are illegal combinations of commands, or are
  5073. commands that can't be carried out, all cause beeps.
  5074. In the following command descriptions, an
  5075. .Op Ar n
  5076. indicates the command may be prefixed by a number (e.g.\&
  5077. .Ic 10l
  5078. moves right 10 characters); if no number prefix is used,
  5079. .Ar n
  5080. is assumed to be 1 unless otherwise specified.
  5081. The term
  5082. .Dq current position
  5083. refers to the position between the cursor and the character preceding the
  5084. cursor.
  5085. A
  5086. .Dq word
  5087. is a sequence of letters, digits, and underscore characters or a sequence of
  5088. non-letter, non-digit, non-underscore, and non-whitespace characters (e.g.\&
  5089. .Dq ab2*&^
  5090. contains two words) and a
  5091. .Dq big-word
  5092. is a sequence of non-whitespace characters.
  5093. .Pp
  5094. Special
  5095. .Nm
  5096. vi commands:
  5097. .Pp
  5098. The following commands are not in, or are different from, the normal vi file
  5099. editor:
  5100. .Bl -tag -width 10n
  5101. .It Xo
  5102. .Oo Ar n Oc Ns _
  5103. .Xc
  5104. Insert a space followed by the
  5105. .Ar n Ns th
  5106. big-word from the last command in the history at the current position and enter
  5107. insert mode; if
  5108. .Ar n
  5109. is not specified, the last word is inserted.
  5110. .It #
  5111. Insert the comment character
  5112. .Pq Sq #
  5113. at the start of the current line and return the line to the shell (equivalent
  5114. to
  5115. .Ic I#^J ) .
  5116. .It Xo
  5117. .Oo Ar n Oc Ns g
  5118. .Xc
  5119. Like
  5120. .Ic G ,
  5121. except if
  5122. .Ar n
  5123. is not specified, it goes to the most recent remembered line.
  5124. .It Xo
  5125. .Oo Ar n Oc Ns v
  5126. .Xc
  5127. Edit line
  5128. .Ar n
  5129. using the
  5130. .Xr vi 1
  5131. editor; if
  5132. .Ar n
  5133. is not specified, the current line is edited.
  5134. The actual command executed is
  5135. .Ic fc -e ${VISUAL:-${EDITOR:-vi}} Ar n .
  5136. .It * and ^X
  5137. Command or file name expansion is applied to the current big-word (with an
  5138. appended
  5139. .Ql *
  5140. if the word contains no file globbing characters) \- the big-word is replaced
  5141. with the resulting words.
  5142. If the current big-word is the first on the line
  5143. or follows one of the characters
  5144. .Ql \&; ,
  5145. .Ql | ,
  5146. .Ql & ,
  5147. .Ql \&( ,
  5148. or
  5149. .Ql \&) ,
  5150. and does not contain a slash
  5151. .Pq Sq / ,
  5152. then command expansion is done; otherwise file name expansion is done.
  5153. Command expansion will match the big-word against all aliases, functions, and
  5154. built-in commands as well as any executable files found by searching the
  5155. directories in the
  5156. .Ev PATH
  5157. parameter.
  5158. File name expansion matches the big-word against the files in the
  5159. current directory.
  5160. After expansion, the cursor is placed just past the last
  5161. word and the editor is in insert mode.
  5162. .It Xo
  5163. .Oo Ar n Oc Ns \e ,
  5164. .Oo Ar n Oc Ns ^F ,
  5165. .Oo Ar n Oc Ns Aq tab ,
  5166. .No and
  5167. .Oo Ar n Oc Ns Aq esc
  5168. .Xc
  5169. Command/file name completion.
  5170. Replace the current big-word with the
  5171. longest unique match obtained after performing command and file name expansion.
  5172. .Aq tab
  5173. is only recognized if the
  5174. .Ic vi-tabcomplete
  5175. option is set, while
  5176. .Aq esc
  5177. is only recognized if the
  5178. .Ic vi-esccomplete
  5179. option is set (see
  5180. .Ic set -o ) .
  5181. If
  5182. .Ar n
  5183. is specified, the
  5184. .Ar n Ns th
  5185. possible completion is selected (as reported by the command/file name
  5186. enumeration command).
  5187. .It = and ^E
  5188. Command/file name enumeration.
  5189. List all the commands or files that match the current big-word.
  5190. .It @ Ns Ar c
  5191. Macro expansion.
  5192. Execute the commands found in the alias
  5193. .No _ Ns Ar c .
  5194. .El
  5195. .Pp
  5196. Intra-line movement commands:
  5197. .Bl -tag -width Ds
  5198. .It Xo
  5199. .Oo Ar n Oc Ns h and
  5200. .Oo Ar n Oc Ns ^H
  5201. .Xc
  5202. Move left
  5203. .Ar n
  5204. characters.
  5205. .It Xo
  5206. .Oo Ar n Oc Ns l and
  5207. .Oo Ar n Oc Ns Aq space
  5208. .Xc
  5209. Move right
  5210. .Ar n
  5211. characters.
  5212. .It 0
  5213. Move to column 0.
  5214. .It ^
  5215. Move to the first non-whitespace character.
  5216. .It Xo
  5217. .Oo Ar n Oc Ns |
  5218. .Xc
  5219. Move to column
  5220. .Ar n .
  5221. .It $
  5222. Move to the last character.
  5223. .It Xo
  5224. .Oo Ar n Oc Ns b
  5225. .Xc
  5226. Move back
  5227. .Ar n
  5228. words.
  5229. .It Xo
  5230. .Oo Ar n Oc Ns B
  5231. .Xc
  5232. Move back
  5233. .Ar n
  5234. big-words.
  5235. .It Xo
  5236. .Oo Ar n Oc Ns e
  5237. .Xc
  5238. Move forward to the end of the word,
  5239. .Ar n
  5240. times.
  5241. .It Xo
  5242. .Oo Ar n Oc Ns E
  5243. .Xc
  5244. Move forward to the end of the big-word,
  5245. .Ar n
  5246. times.
  5247. .It Xo
  5248. .Oo Ar n Oc Ns w
  5249. .Xc
  5250. Move forward
  5251. .Ar n
  5252. words.
  5253. .It Xo
  5254. .Oo Ar n Oc Ns W
  5255. .Xc
  5256. Move forward
  5257. .Ar n
  5258. big-words.
  5259. .It %
  5260. Find match.
  5261. The editor looks forward for the nearest parenthesis, bracket, or
  5262. brace and then moves the cursor to the matching parenthesis, bracket, or brace.
  5263. .It Xo
  5264. .Oo Ar n Oc Ns f Ns Ar c
  5265. .Xc
  5266. Move forward to the
  5267. .Ar n Ns th
  5268. occurrence of the character
  5269. .Ar c .
  5270. .It Xo
  5271. .Oo Ar n Oc Ns F Ns Ar c
  5272. .Xc
  5273. Move backward to the
  5274. .Ar n Ns th
  5275. occurrence of the character
  5276. .Ar c .
  5277. .It Xo
  5278. .Oo Ar n Oc Ns t Ns Ar c
  5279. .Xc
  5280. Move forward to just before the
  5281. .Ar n Ns th
  5282. occurrence of the character
  5283. .Ar c .
  5284. .It Xo
  5285. .Oo Ar n Oc Ns T Ns Ar c
  5286. .Xc
  5287. Move backward to just before the
  5288. .Ar n Ns th
  5289. occurrence of the character
  5290. .Ar c .
  5291. .It Xo
  5292. .Oo Ar n Oc Ns \&;
  5293. .Xc
  5294. Repeats the last
  5295. .Ic f , F , t ,
  5296. or
  5297. .Ic T
  5298. command.
  5299. .It Xo
  5300. .Oo Ar n Oc Ns \&,
  5301. .Xc
  5302. Repeats the last
  5303. .Ic f , F , t ,
  5304. or
  5305. .Ic T
  5306. command, but moves in the opposite direction.
  5307. .El
  5308. .Pp
  5309. Inter-line movement commands:
  5310. .Bl -tag -width Ds
  5311. .It Xo
  5312. .Oo Ar n Oc Ns j ,
  5313. .Oo Ar n Oc Ns + ,
  5314. .No and
  5315. .Oo Ar n Oc Ns ^N
  5316. .Xc
  5317. Move to the
  5318. .Ar n Ns th
  5319. next line in the history.
  5320. .It Xo
  5321. .Oo Ar n Oc Ns k ,
  5322. .Oo Ar n Oc Ns - ,
  5323. .No and
  5324. .Oo Ar n Oc Ns ^P
  5325. .Xc
  5326. Move to the
  5327. .Ar n Ns th
  5328. previous line in the history.
  5329. .It Xo
  5330. .Oo Ar n Oc Ns G
  5331. .Xc
  5332. Move to line
  5333. .Ar n
  5334. in the history; if
  5335. .Ar n
  5336. is not specified, the number of the first remembered line is used.
  5337. .It Xo
  5338. .Oo Ar n Oc Ns g
  5339. .Xc
  5340. Like
  5341. .Ic G ,
  5342. except if
  5343. .Ar n
  5344. is not specified, it goes to the most recent remembered line.
  5345. .It Xo
  5346. .Oo Ar n Oc Ns / Ns Ar string
  5347. .Xc
  5348. Search backward through the history for the
  5349. .Ar n Ns th
  5350. line containing
  5351. .Ar string ;
  5352. if
  5353. .Ar string
  5354. starts with
  5355. .Ql ^ ,
  5356. the remainder of the string must appear at the start of the history line for
  5357. it to match.
  5358. .It Xo
  5359. .Oo Ar n Oc Ns \&? Ns Ar string
  5360. .Xc
  5361. Same as
  5362. .Ic / ,
  5363. except it searches forward through the history.
  5364. .It Xo
  5365. .Oo Ar n Oc Ns n
  5366. .Xc
  5367. Search for the
  5368. .Ar n Ns th
  5369. occurrence of the last search string;
  5370. the direction of the search is the same as the last search.
  5371. .It Xo
  5372. .Oo Ar n Oc Ns N
  5373. .Xc
  5374. Search for the
  5375. .Ar n Ns th
  5376. occurrence of the last search string;
  5377. the direction of the search is the opposite of the last search.
  5378. .El
  5379. .Pp
  5380. Edit commands
  5381. .Bl -tag -width Ds
  5382. .It Xo
  5383. .Oo Ar n Oc Ns a
  5384. .Xc
  5385. Append text
  5386. .Ar n
  5387. times; goes into insert mode just after the current position.
  5388. The append is
  5389. only replicated if command mode is re-entered i.e.\&
  5390. .Aq esc
  5391. is used.
  5392. .It Xo
  5393. .Oo Ar n Oc Ns A
  5394. .Xc
  5395. Same as
  5396. .Ic a ,
  5397. except it appends at the end of the line.
  5398. .It Xo
  5399. .Oo Ar n Oc Ns i
  5400. .Xc
  5401. Insert text
  5402. .Ar n
  5403. times; goes into insert mode at the current position.
  5404. The insertion is only
  5405. replicated if command mode is re-entered i.e.\&
  5406. .Aq esc
  5407. is used.
  5408. .It Xo
  5409. .Oo Ar n Oc Ns I
  5410. .Xc
  5411. Same as
  5412. .Ic i ,
  5413. except the insertion is done just before the first non-blank character.
  5414. .It Xo
  5415. .Oo Ar n Oc Ns s
  5416. .Xc
  5417. Substitute the next
  5418. .Ar n
  5419. characters (i.e. delete the characters and go into insert mode).
  5420. .It S
  5421. Substitute whole line.
  5422. All characters from the first non-blank character to the
  5423. end of the line are deleted and insert mode is entered.
  5424. .It Xo
  5425. .Oo Ar n Oc Ns c Ns Ar move-cmd
  5426. .Xc
  5427. Change from the current position to the position resulting from
  5428. .Ar n move-cmd Ns s
  5429. (i.e. delete the indicated region and go into insert mode); if
  5430. .Ar move-cmd
  5431. is
  5432. .Ic c ,
  5433. the line starting from the first non-blank character is changed.
  5434. .It C
  5435. Change from the current position to the end of the line (i.e. delete to the
  5436. end of the line and go into insert mode).
  5437. .It Xo
  5438. .Oo Ar n Oc Ns x
  5439. .Xc
  5440. Delete the next
  5441. .Ar n
  5442. characters.
  5443. .It Xo
  5444. .Oo Ar n Oc Ns X
  5445. .Xc
  5446. Delete the previous
  5447. .Ar n
  5448. characters.
  5449. .It D
  5450. Delete to the end of the line.
  5451. .It Xo
  5452. .Oo Ar n Oc Ns d Ns Ar move-cmd
  5453. .Xc
  5454. Delete from the current position to the position resulting from
  5455. .Ar n move-cmd Ns s ;
  5456. .Ar move-cmd
  5457. is a movement command (see above) or
  5458. .Ic d ,
  5459. in which case the current line is deleted.
  5460. .It Xo
  5461. .Oo Ar n Oc Ns r Ns Ar c
  5462. .Xc
  5463. Replace the next
  5464. .Ar n
  5465. characters with the character
  5466. .Ar c .
  5467. .It Xo
  5468. .Oo Ar n Oc Ns R
  5469. .Xc
  5470. Replace.
  5471. Enter insert mode but overwrite existing characters instead of
  5472. inserting before existing characters.
  5473. The replacement is repeated
  5474. .Ar n
  5475. times.
  5476. .It Xo
  5477. .Oo Ar n Oc Ns ~
  5478. .Xc
  5479. Change the case of the next
  5480. .Ar n
  5481. characters.
  5482. .It Xo
  5483. .Oo Ar n Oc Ns y Ns Ar move-cmd
  5484. .Xc
  5485. Yank from the current position to the position resulting from
  5486. .Ar n move-cmd Ns s
  5487. into the yank buffer; if
  5488. .Ar move-cmd
  5489. is
  5490. .Ic y ,
  5491. the whole line is yanked.
  5492. .It Y
  5493. Yank from the current position to the end of the line.
  5494. .It Xo
  5495. .Oo Ar n Oc Ns p
  5496. .Xc
  5497. Paste the contents of the yank buffer just after the current position,
  5498. .Ar n
  5499. times.
  5500. .It Xo
  5501. .Oo Ar n Oc Ns P
  5502. .Xc
  5503. Same as
  5504. .Ic p ,
  5505. except the buffer is pasted at the current position.
  5506. .El
  5507. .Pp
  5508. Miscellaneous vi commands
  5509. .Bl -tag -width Ds
  5510. .It ^J and ^M
  5511. The current line is read, parsed, and executed by the shell.
  5512. .It ^L
  5513. Clear the screen (if possible) and redraw the current line.
  5514. .It ^R
  5515. Redraw the current line.
  5516. .It Xo
  5517. .Oo Ar n Oc Ns \&.
  5518. .Xc
  5519. Redo the last edit command
  5520. .Ar n
  5521. times.
  5522. .It u
  5523. Undo the last edit command.
  5524. .It U
  5525. Undo all changes that have been made to the current line.
  5526. .It Ar intr No and Ar quit
  5527. The interrupt and quit terminal characters cause the current line to be
  5528. deleted and a new prompt to be printed.
  5529. .El
  5530. .Sh FILES
  5531. .Bl -tag -width "/etc/suid_profileXX" -compact
  5532. .It Pa ~/.profile
  5533. User's login profile.
  5534. .It Pa /etc/ksh.kshrc
  5535. Global configuration file.
  5536. Not sourced by default.
  5537. .It Pa /etc/profile
  5538. System login profile.
  5539. .It Pa /etc/shells
  5540. Shell database.
  5541. .It Pa /etc/suid_profile
  5542. Privileged shell profile.
  5543. .El
  5544. .Sh SEE ALSO
  5545. .Xr csh 1 ,
  5546. .Xr ed 1 ,
  5547. .Xr mg 1 ,
  5548. .Xr sh 1 ,
  5549. .Xr stty 1 ,
  5550. .Xr vi 1 ,
  5551. .Xr shells 5 ,
  5552. .Xr environ 7 ,
  5553. .Xr script 7
  5554. .Rs
  5555. .%A S. R. Bourne
  5556. .%T The UNIX Shell
  5557. .%J Bell System Technical Journal
  5558. .%V 57:6
  5559. .%P pp. 1971-1990
  5560. .%D 1978
  5561. .Re
  5562. .Rs
  5563. .\" 4.4BSD USD:3
  5564. .%A S. R. Bourne
  5565. .%T \&An Introduction to the UNIX Shell
  5566. .%I AT&T Bell Laboratories
  5567. .%R Computing Science Technical Report
  5568. .%N 70
  5569. .%D 1978
  5570. .Re
  5571. .Rs
  5572. .%A Morris Bolsky
  5573. .%A David Korn
  5574. .%B The KornShell Command and Programming Language
  5575. .%D First Edition 1989
  5576. .%I Prentice Hall
  5577. .%O ISBN 0135169720
  5578. .\" The second edition of the above book (1995) is about ksh93,
  5579. .\" but the OpenBSD ksh is a descendant from ksh88 via pdksh.
  5580. .Re
  5581. .Rs
  5582. .%A Stephen G. Kochan
  5583. .%A Patrick H. Wood
  5584. .%B UNIX Shell Programming, 3rd Edition
  5585. .%D 2003
  5586. .%I Sams
  5587. .%O ISBN 0672324903
  5588. .Re
  5589. .Rs
  5590. .%A IEEE Inc.
  5591. .%D 1993
  5592. .%O ISBN 1-55937-266-9
  5593. .%T IEEE Standard for Information Technology \- Portable Operating \
  5594. System Interface (POSIX) \- Part 2: Shell and Utilities
  5595. .Re
  5596. .Sh VERSION
  5597. This page documents version @(#)PD KSH v5.2.14 99/07/13.2 of the public
  5598. domain Korn shell.
  5599. .Sh AUTHORS
  5600. .An -nosplit
  5601. This shell is based on the public domain 7th edition Bourne shell clone by
  5602. .An Charles Forsyth
  5603. and parts of the BRL shell by
  5604. .An Doug A. Gwyn ,
  5605. .An Doug Kingston ,
  5606. .An Ron Natalie ,
  5607. .An Arnold Robbins ,
  5608. .An Lou Salkind ,
  5609. and others.
  5610. The first release of
  5611. .Nm pdksh
  5612. was created by
  5613. .An Eric Gisin ,
  5614. and it was subsequently maintained by
  5615. .An John R. MacMillan Aq Mt change!john@sq.sq.com ,
  5616. .An Simon J. Gerraty Aq Mt sjg@zen.void.oz.au ,
  5617. and
  5618. .An Michael Rendell Aq Mt michael@cs.mun.ca .
  5619. The
  5620. .Pa CONTRIBUTORS
  5621. file in the source distribution contains a more complete list of people and
  5622. their part in the shell's development.
  5623. .Sh BUGS
  5624. .Pf $( Ar command )
  5625. expressions are currently parsed by finding the closest matching (unquoted)
  5626. parenthesis.
  5627. Thus constructs inside
  5628. .Pf $( Ar command )
  5629. may produce an error.
  5630. For example, the parenthesis in
  5631. .Ql x);;
  5632. is interpreted as the closing parenthesis in
  5633. .Ql $(case x in x);; *);; esac) .