logo

oasis-root

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

sh.1 (53031B)


  1. .\" $OpenBSD: sh.1,v 1.158 2024/03/06 06:26:22 jmc Exp $
  2. .\"
  3. .\" Copyright (c) 2015 Jason McIntyre <jmc@openbsd.org>
  4. .\"
  5. .\" Permission to use, copy, modify, and distribute this software for any
  6. .\" purpose with or without fee is hereby granted, provided that the above
  7. .\" copyright notice and this permission notice appear in all copies.
  8. .\"
  9. .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
  10. .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
  11. .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
  12. .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
  13. .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
  14. .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
  15. .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
  16. .\"
  17. .Dd $Mdocdate: March 6 2024 $
  18. .Dt SH 1
  19. .Os
  20. .Sh NAME
  21. .Nm sh
  22. .Nd command language interpreter
  23. .Sh SYNOPSIS
  24. .Nm sh
  25. .Op Fl abCefhimnuvx
  26. .Op Fl o Ar option
  27. .Op Fl c Ar string | Fl s | Ar file
  28. .Sh DESCRIPTION
  29. The
  30. .Nm
  31. utility is a
  32. .Em command language interpreter :
  33. it reads one or more commands,
  34. either from the command line or from a file
  35. (a shell script),
  36. and then sets about executing those commands.
  37. Thus it is the
  38. main interface between the user and the operating system.
  39. .Pp
  40. This version of
  41. .Nm
  42. is actually
  43. .Nm ksh
  44. in disguise.
  45. As such, it also supports the features described in
  46. .Xr ksh 1 .
  47. This manual page describes only the parts
  48. relevant to a POSIX compliant
  49. .Nm .
  50. If portability is a concern,
  51. use only those features described in this page.
  52. .Pp
  53. The shell receives input as follows:
  54. .Pp
  55. .Bl -tag -width "-c stringXXX" -offset indent -compact
  56. .It Fl c Ar string
  57. Read commands from
  58. .Ar string .
  59. .It Fl s
  60. Read commands from standard input
  61. (the default).
  62. .It Ar file
  63. Read commands from
  64. .Ar file .
  65. .El
  66. .Pp
  67. The options below can be specified with a
  68. .Sq Cm +
  69. rather than
  70. .Sq Fl ,
  71. meaning to unset the option.
  72. They can also be set or unset using the
  73. .Ic set
  74. command.
  75. Some options have equivalent long names,
  76. indicated at the start of the description,
  77. which can be used with the
  78. .Fl o
  79. option.
  80. .Bl -tag -width Ds
  81. .It Fl a
  82. Allexport.
  83. Variable assignments are exported to all child processes
  84. of the running shell.
  85. If the assignment precedes a command it does not persist
  86. after that command has finished running,
  87. unless the command is a special builtin
  88. or one of the builtins
  89. .Ic getopts
  90. or
  91. .Ic read
  92. makes the assignment.
  93. .It Fl b
  94. Notify.
  95. The user is given notice asynchronously when background jobs complete.
  96. .It Fl C
  97. Noclobber.
  98. Do not permit the redirection operator
  99. .Pq Sq >
  100. to clobber (overwrite) existing files.
  101. .It Fl e
  102. Errexit.
  103. Exit the shell immediately should an error occur or a command fail.
  104. For pipelines and
  105. .Cm &&
  106. and
  107. .Cm ||
  108. constructs, only exit if the last component fails.
  109. Errexit is ignored for
  110. .Ic while ,
  111. .Ic until ,
  112. .Ic if ,
  113. and
  114. .Ic elif
  115. lists and pipelines beginning
  116. .Sq !\& .
  117. .It Fl f
  118. Noglob.
  119. Do not expand file name patterns.
  120. .It Fl h
  121. When a utility is first executed,
  122. hash (record) its location
  123. so that future invocations do not need to search for it.
  124. .It Fl i
  125. Enable behaviour convenient for an interactive shell.
  126. This option is set by default
  127. if the session is attached to a terminal.
  128. .It Fl m
  129. Monitor.
  130. Fully enable job control:
  131. enable the
  132. .Ic bg
  133. and
  134. .Ic fg
  135. builtins;
  136. report completion status when jobs finish;
  137. report when a foreground process stops;
  138. and report when a job changes status.
  139. The processes of a job share their own process group.
  140. This option is set by default for interactive shells.
  141. .It Fl n
  142. Noexec.
  143. Read commands but do not execute them \(en
  144. useful for checking syntax errors in scripts.
  145. This option is ignored for interactive shells.
  146. .It Fl o Ar option
  147. Specify an option by its long name.
  148. Those described below have no equivalent option letter:
  149. .Pp
  150. .Bl -tag -width "ignoreeof" -offset 3n -compact
  151. .It ignoreeof
  152. Ignore an end-of-file
  153. .Pq Sq ^D .
  154. EOF normally logs a user out,
  155. so setting this can prevent accidental logouts
  156. (the user will need to explicitly use the
  157. .Ic exit
  158. command).
  159. .It nolog
  160. Do not enter function definitions into command history.
  161. .It posix
  162. Enable POSIX mode
  163. (see
  164. .Sx STANDARDS ) .
  165. .It vi
  166. Enable
  167. .Xr vi 1
  168. command line editing.
  169. .El
  170. .It Fl u
  171. Nounset.
  172. If a command references an unset parameter,
  173. write an error to standard output instead of executing the command.
  174. This option is ignored for the special parameters
  175. .Sq *
  176. and
  177. .Sq @ .
  178. If the shell is not interactive,
  179. immediately exit.
  180. .It Fl v
  181. Verbose.
  182. Write input to standard error after reading it.
  183. .It Fl x
  184. Xtrace.
  185. Write a trace for each command to standard error after expanding it,
  186. and before executing it.
  187. .El
  188. .Sh BUILTINS
  189. The shell has a number of
  190. .Em built-ins
  191. available:
  192. utilities that are included as part of the shell.
  193. The shell does not need to search for them
  194. and can execute them directly.
  195. .Pp
  196. A number of built-ins are special in that
  197. a syntax error can cause a running shell to abort,
  198. and, after the built-in completes,
  199. variable assignments remain in the current environment.
  200. The following built-ins are special:
  201. .Ic .\& , :\& , break , continue ,
  202. .Ic eval , exec , exit , export ,
  203. .Ic readonly , return , set , shift ,
  204. .Ic times , trap ,
  205. and
  206. .Ic unset .
  207. .Pp
  208. The built-ins available to
  209. .Nm
  210. are listed below.
  211. Unless otherwise indicated,
  212. they exit 0 on success,
  213. and >0 if an error occurs.
  214. .Bl -tag -width 2n
  215. .It Ic .\& Ar file
  216. Execute the commands in
  217. .Ar file ,
  218. in the current environment.
  219. The actual file need not be executable,
  220. and its location is determined by searching
  221. .Ev PATH
  222. if there are no slashes in the filename.
  223. The exit status is that of the last command returned,
  224. or zero if no commands were executed.
  225. If no readable file can be found,
  226. a non-interactive shell will abort;
  227. an interactive shell writes an error message
  228. and returns a non-zero exit status.
  229. .It Ic :\& Op Ar arg ...
  230. The
  231. .Ic :\&
  232. command does nothing \(en
  233. it is a placeholder for when a command is required.
  234. Its exit status is always zero.
  235. .It Ic alias Op Ar name Ns Oo = Ns Ar value Oc Ar ...
  236. Define an alias
  237. .Ar name
  238. to
  239. .Ar value ;
  240. when the shell encounters a command name that is an alias,
  241. its value is substituted.
  242. If
  243. .Ar value
  244. ends in a blank,
  245. the next word is checked for alias substitution too.
  246. If only a
  247. .Ar name
  248. is specified,
  249. display the value of that alias;
  250. if no arguments are given,
  251. list all aliases and their values.
  252. Aliases are visible in the current environment and that of subshells,
  253. but not by the parent process of the current shell
  254. or by utilities invoked by it.
  255. .It Ic bg Op Ar id ...
  256. Select a job by
  257. .Ar id
  258. (see the
  259. .Ic jobs
  260. command, below)
  261. to run in the background.
  262. The default job is
  263. .Qq %+ .
  264. .It Ic break Op Ar n
  265. Exit from the innermost
  266. .Ic for , while ,
  267. or
  268. .Ic until
  269. loop,
  270. or from loop level
  271. .Ar n .
  272. .It Ic cd Oo Fl L | P Oc Op Ar dir
  273. Change the current working directory to
  274. .Ar dir ,
  275. or
  276. .Ev $HOME
  277. by default.
  278. If
  279. .Ar dir
  280. is set to
  281. .Sq - ,
  282. change to the previous working directory and
  283. print the (now current) working directory.
  284. If
  285. .Ar dir
  286. does not begin with a slash or dot,
  287. .Ev CDPATH
  288. is searched for the directory.
  289. .Pp
  290. The options to the
  291. .Ic cd
  292. command are as follows:
  293. .Pp
  294. .Bl -tag -width Ds -offset 3n -compact
  295. .It Fl L
  296. Do not resolve symbolic links before processing
  297. .Qq ..
  298. components.
  299. .It Fl P
  300. Resolve symbolic links before processing
  301. .Qq ..
  302. components.
  303. .El
  304. .It Ic command Oo Fl p | V | v Oc Ar command Op Ar arg ...
  305. Invoke
  306. .Ar command
  307. (and any optional arguments),
  308. overriding any functions with the same name,
  309. and without any of the properties that special built-ins have.
  310. .Pp
  311. The options to
  312. .Ic command
  313. are as follows:
  314. .Pp
  315. .Bl -tag -width Ds -offset 3n -compact
  316. .It Fl p
  317. Use a default value for
  318. .Ev PATH
  319. to search for the command.
  320. .It Fl V
  321. Do not invoke
  322. .Ar command ,
  323. but identify how the shell will interpret it
  324. (such as a function or special built-in).
  325. .It Fl v
  326. Do not invoke
  327. .Ar command ,
  328. but identify the pathname the shell will use to run it.
  329. For aliases, a command to define that alias is printed.
  330. For shell reserved words, shell functions, and built-in utilities,
  331. just the name is printed.
  332. .El
  333. .Pp
  334. The exit status is that of
  335. .Ar command ,
  336. or 126 if
  337. .Ar command
  338. could not be invoked,
  339. or 127 if an error occurred in
  340. .Ic command
  341. itself or
  342. .Ar command
  343. could not be found.
  344. If the options
  345. .Fl V
  346. or
  347. .Fl v
  348. are given,
  349. the exit status is 0 on success,
  350. or >0 if an error occurs.
  351. .It Ic continue Op Ar n
  352. Go directly to the next iteration of the innermost
  353. .Ic for , while ,
  354. or
  355. .Ic until
  356. loop,
  357. or from loop level
  358. .Ar n .
  359. .It Ic eval Op Ar arg ...
  360. Concatenate the arguments given
  361. and interpret them as a command.
  362. The exit status is that of the resulting command,
  363. zero if no arguments are given,
  364. or >0 if the resulting command could not be correctly parsed.
  365. .It Ic exec Op Ar command Op Ar arg ...
  366. Replace the shell with
  367. .Ar command
  368. (and any optional arguments),
  369. without creating a new process.
  370. The exit status is that of
  371. .Ar command ,
  372. or 126 if
  373. .Ar command
  374. could not be invoked,
  375. or 127 if
  376. .Ar command
  377. could not be found.
  378. If no command is given but a redirection happens,
  379. the exit status is 1\(en125;
  380. otherwise
  381. .Ic exec
  382. returns 0.
  383. .It Ic exit Op Ar n
  384. Exit the shell with exit status
  385. .Ar n ,
  386. or that of the last command executed.
  387. .It Ic export Oo Fl p Oc Ar name Ns Oo = Ns Ar value Oc Ar ...
  388. Make the variable
  389. .Ar name
  390. visible to subsequently run commands,
  391. optionally setting it to
  392. .Ar value .
  393. .Pp
  394. The options to the
  395. .Ic export
  396. command are as follows:
  397. .Pp
  398. .Bl -tag -width Ds -offset 3n -compact
  399. .It Fl p
  400. List all exported variables in a manner that can be reinput to the shell.
  401. .El
  402. .It Ic false
  403. Return a false (non-zero) value.
  404. .It Xo
  405. .Ic fc
  406. .Op Fl lnr
  407. .Op Fl e Ar editor
  408. .Op Fl s Op Ar old Ns = Ns Ar new
  409. .Op Ar first Op Ar last
  410. .Xc
  411. Edit commands from command history using
  412. .Xr ed 1 .
  413. After editing,
  414. the new commands are executed by the shell.
  415. .Pp
  416. The options to the
  417. .Ic fc
  418. command are as follows:
  419. .Pp
  420. .Bl -tag -width "-s [old=new]" -offset 3n -compact
  421. .It Fl e Ar editor
  422. Edit commands using
  423. .Ar editor .
  424. See also
  425. .Ev FCEDIT .
  426. .It Fl l
  427. List the command history.
  428. .It Fl ln
  429. List the command history without command numbers.
  430. .It Fl r
  431. Edit or list
  432. .Pq Fl lr
  433. commands in reverse order.
  434. .It Fl s Op Ar old Ns = Ns Ar new
  435. Reexecute a single command
  436. without invoking an editor.
  437. The first occurrence of the string
  438. .Ar old
  439. in the command is replaced by
  440. .Ar new .
  441. .El
  442. .Pp
  443. A range of commands can be specified,
  444. .Ar first
  445. to
  446. .Ar last .
  447. Their format can be numerical,
  448. to select by command number;
  449. .Sq - Ns Ar n ,
  450. to select a command executed that number of commands previous;
  451. or a string which matches the beginning of the command.
  452. If no range is given,
  453. the last command in command history is edited,
  454. or reexecuted
  455. .Pq Fl s ,
  456. or the previous 16 commands in command history are listed
  457. .Pq Fl l .
  458. If
  459. .Ar first
  460. is newer than
  461. .Ar last ,
  462. commands are processed in reverse order
  463. (as if
  464. .Fl r
  465. had been given);
  466. if either are out of range,
  467. the oldest or newest values are used.
  468. .It Ic fg Op Ar id ...
  469. Select a job by
  470. .Ar id
  471. (see the
  472. .Ic jobs
  473. command, below)
  474. to run in the foreground.
  475. The default job is
  476. .Qq %+ .
  477. .It Ic getopts Ar optstring name Op Ar arg ...
  478. When invoked,
  479. .Ic getopts
  480. processes the positional parameters
  481. (or any
  482. .Ar arg
  483. passed to it)
  484. as a list of options and option arguments.
  485. .Ic getopts
  486. sets the variable
  487. .Ar name
  488. to the option found,
  489. .Ev OPTARG
  490. to its argument,
  491. and
  492. .Ev OPTIND
  493. to the index of the next variable to be processed.
  494. .Pp
  495. The string
  496. .Ar optstring
  497. contains a list of acceptable options;
  498. a colon following an option indicates it requires an argument.
  499. If an option not recognised by
  500. .Ar optstring
  501. is found,
  502. .Ar name
  503. is set to
  504. .Sq ?\& ;
  505. if the first character of
  506. .Ar optstring
  507. is a colon,
  508. .Ev OPTARG
  509. is set to the unsupported option,
  510. otherwise an error message is displayed.
  511. .Pp
  512. The following code fragment shows how one might process the arguments
  513. for a command that can take the option
  514. .Fl a
  515. and the option
  516. .Fl o ,
  517. which requires an argument.
  518. .Bd -literal -offset indent
  519. while getopts ao: name
  520. do
  521. case $name in
  522. a) flag=1 ;;
  523. o) oarg=$OPTARG ;;
  524. ?) echo "Usage: ..."; exit 2 ;;
  525. esac
  526. done
  527. shift $(($OPTIND - 1))
  528. echo "Non-option arguments: " "$@"
  529. .Ed
  530. .It Ic hash Op Fl r | Ar utility
  531. Add
  532. .Ar utility
  533. to the hash list
  534. or remove
  535. .Pq Fl r
  536. all utilities from the hash list.
  537. Without arguments, show the utilities currently hashed.
  538. .It Ic jobs Oo Fl l | p Oc Op Ar id ...
  539. Display the status of all jobs in the current shell environment,
  540. or those selected by
  541. .Ar id .
  542. .Pp
  543. The options to the
  544. .Ic jobs
  545. command are as follows:
  546. .Pp
  547. .Bl -tag -width Ds -offset 3n -compact
  548. .It Fl l
  549. Additionally display the process group ID.
  550. .It Fl p
  551. Display only the process group ID.
  552. .El
  553. .Pp
  554. Job
  555. .Ar id
  556. can be selected in one of the following ways:
  557. .Pp
  558. .Bl -tag -width "%?string" -offset 3n -compact
  559. .It %%
  560. The current job.
  561. .It %+
  562. The current job.
  563. .It %-
  564. The previous job.
  565. .It % Ns Ar n
  566. Job number
  567. .Ar n .
  568. .It % Ns Ar string
  569. Job with command matching
  570. .Ar string .
  571. .It %? Ns Ar string
  572. Job with command containing
  573. .Ar string .
  574. .El
  575. .It Xo
  576. .Ic kill
  577. .Op Fl l Op Ar signal
  578. .Op Fl s Ar signal
  579. .Oo Fl Ar signal Oc Ar pid ...
  580. .Xc
  581. Send a signal,
  582. by default
  583. .Dv SIGTERM ,
  584. to the process with ID
  585. .Ar pid .
  586. .Pp
  587. The options to the
  588. .Ic kill
  589. command are as follows:
  590. .Pp
  591. .Bl -tag -width "-l [signal]" -offset 3n -compact
  592. .It Fl l Op Ar signal
  593. List all supported signals,
  594. or the signal name corresponding to
  595. .Ar signal
  596. number or the exit status of a command killed by a signal.
  597. .It Fl s Ar signal
  598. Send the process
  599. .Ar signal
  600. name.
  601. .It Fl Ar signal
  602. Send the process
  603. .Ar signal
  604. name or number.
  605. .It Ar pid
  606. A process ID,
  607. process group ID,
  608. or a job ID (see
  609. .Ic jobs ,
  610. above).
  611. The process ID 0 signals all processes in the current process group.
  612. .El
  613. .Pp
  614. The supported signal numbers are:
  615. .Pp
  616. .Bl -tag -width Ds -offset 3n -compact
  617. .It " 0"
  618. Do not signal a process,
  619. but determine whether an ID exists.
  620. .It " 1"
  621. .Dv SIGHUP :
  622. Terminal line hangup.
  623. .It " 2"
  624. .Dv SIGINT :
  625. Interrupt a program.
  626. .It " 3"
  627. .Dv SIGQUIT :
  628. Quit a program.
  629. .It " 6"
  630. .Dv SIGABRT :
  631. Call
  632. .Xr abort 3 .
  633. .It " 9"
  634. .Dv SIGKILL :
  635. Kill a program.
  636. Cannot be caught or ignored.
  637. .It "14"
  638. .Dv SIGALRM :
  639. Real-time timer expired.
  640. .It "15"
  641. .Dv SIGTERM :
  642. Software termination signal.
  643. .El
  644. .It Ic pwd Op Fl L | P
  645. Print the current working directory.
  646. .Pp
  647. The options to the
  648. .Ic pwd
  649. command are as follows:
  650. .Pp
  651. .Bl -tag -width Ds -offset 3n -compact
  652. .It Fl L
  653. Print the logical path to the current working directory
  654. i.e. display symbolic links followed.
  655. .It Fl P
  656. Print the physical path to the current working directory
  657. i.e. display symbolic links resolved.
  658. .El
  659. .Pp
  660. If both options are given,
  661. the last specified is used;
  662. if none are given,
  663. the default is
  664. .Fl L .
  665. .It Ic read Oo Fl r Oc Ar name ...
  666. Read a line from standard input.
  667. The line is split into fields,
  668. with each field assigned to a variable,
  669. .Ar name ,
  670. in turn
  671. (first field assigned to first variable, and so on).
  672. If there are more fields than variables,
  673. the last variable will contain all the remaining fields.
  674. If there are more variables than fields,
  675. the remaining variables are set to empty strings.
  676. A backslash in the input line causes the shell to prompt for further input.
  677. .Pp
  678. The options to the
  679. .Ic read
  680. command are as follows:
  681. .Pp
  682. .Bl -tag -width Ds -offset 3n -compact
  683. .It Fl r
  684. Ignore backslash sequences.
  685. .El
  686. .It Ic readonly Oo Fl p Oc Ar name Ns Op = Ns Ar value
  687. Mark variable
  688. .Ar name
  689. as readonly,
  690. and optionally set it to
  691. .Ar value .
  692. Readonly variables cannot be later assigned values or unset.
  693. .Pp
  694. The options to the
  695. .Ic readonly
  696. command are as follows:
  697. .Pp
  698. .Bl -tag -width Ds -offset 3n -compact
  699. .It Fl p
  700. Display the names and values of all readonly variables
  701. in a manner which can be reinput to the shell.
  702. .El
  703. .It Ic return Op Ar n
  704. Exit the current function or
  705. .Ic .\&
  706. script with exit status
  707. .Ar n ,
  708. or that of the last command executed.
  709. .It Xo
  710. .Ic set
  711. .Op Fl abCefhmnuvx
  712. .Op Fl o Op Ar option
  713. .Op Ar arg ...
  714. .Xc
  715. Set options and positional parameters.
  716. Without options or arguments,
  717. display the names and values of all shell variables.
  718. .Pp
  719. The options are described in the options description
  720. at the beginning of this manual.
  721. The sequence
  722. .Ql set -o
  723. displays the current option settings;
  724. the sequence
  725. .Ql set +o
  726. displays,
  727. in a format suitable to be reinput to the shell,
  728. a command suitable to achieve the current option settings.
  729. .Pp
  730. Any arguments are assigned to the positional parameters,
  731. with the special parameter
  732. .Sq #
  733. set to the number of positional parameters.
  734. The sequence
  735. .Ql set --
  736. indicates an end to option processing
  737. (i.e. only arguments follow);
  738. .Ql set --
  739. by itself unsets all positional parameters
  740. and sets
  741. .Sq #
  742. to zero.
  743. .It Ic shift Op Ar n
  744. Shift the positional parameters
  745. .Ar n
  746. times
  747. (by default once).
  748. Parameter 1 takes the value of parameter
  749. .Sq 1+ Ns Ar n ,
  750. parameter 2 takes
  751. .Sq 2+ Ns Ar n ,
  752. and so on.
  753. Parameters
  754. .Sq #
  755. down to
  756. .Sq Po #\(mi Ns Ar n Pc Ns +1
  757. are unset and
  758. .Sq #
  759. is updated to the new number of positional parameters.
  760. If
  761. .Ar n
  762. is 0,
  763. no change occurs.
  764. .It Ic times
  765. Display accumulated process times for the shell (user and system)
  766. and all child processes (user and system).
  767. .It Ic trap Op Ar action signal ...
  768. Perform
  769. .Ar action
  770. whenever
  771. .Ar signal
  772. is caught.
  773. Without arguments,
  774. display a list of all traps and actions,
  775. in a format suitable to be reinput to the shell.
  776. .Pp
  777. If
  778. .Ar action
  779. is
  780. .Sq -
  781. or an integer,
  782. reset
  783. .Ar signal
  784. to its default value;
  785. if it is empty
  786. .Pq Qq ,
  787. ignore
  788. .Ar signal .
  789. If
  790. .Ar signal
  791. is
  792. .Qq EXIT
  793. or 0,
  794. perform
  795. .Ar action
  796. when the shell exits;
  797. otherwise
  798. .Ar signal
  799. should be a signal name
  800. (without the SIG prefix)
  801. or number.
  802. .It Ic true
  803. Return a true (zero) value.
  804. .It Ic type Ar command ...
  805. For each
  806. .Ar command ,
  807. show how the shell would interpret it.
  808. .It Ic ulimit Op Fl f Ar n
  809. Limit the maximum size of a file that can be created to
  810. .Ar n
  811. blocks.
  812. Without arguments,
  813. display the current file size limit.
  814. .It Ic umask Oo Fl S Oc Op Ar mask
  815. Set the file mode creation mask to
  816. .Ar mask .
  817. The creation mask determines the default permissions
  818. a newly created file or directory will have.
  819. If
  820. .Ar mask
  821. is not specified,
  822. display the current creation mask.
  823. .Pp
  824. The options to the
  825. .Ic umask
  826. command are as follows:
  827. .Pp
  828. .Bl -tag -width Ds -offset 3n -compact
  829. .It Fl S
  830. Display symbolic output.
  831. .El
  832. .Pp
  833. See
  834. .Xr chmod 1
  835. for the format of
  836. .Ar mask .
  837. .It Ic unalias Oo Fl a Oc Ar name ...
  838. Remove the alias definition of alias
  839. .Ar name .
  840. .Pp
  841. The options to the
  842. .Ic unalias
  843. command are as follows:
  844. .Pp
  845. .Bl -tag -width Ds -offset 3n -compact
  846. .It Fl a
  847. Remove all alias definitions.
  848. .El
  849. .It Ic unset Oo Fl fv Oc Ar name ...
  850. Unset variable or function
  851. .Ar name .
  852. .Pp
  853. The options to the
  854. .Ic unset
  855. command are as follows:
  856. .Pp
  857. .Bl -tag -width Ds -offset 3n -compact
  858. .It Fl f
  859. Treat
  860. .Ar name
  861. as a function.
  862. .It Fl v
  863. Treat
  864. .Ar name
  865. as a variable (the default).
  866. .El
  867. .It Ic wait Op Ar pid ...
  868. Wait until all the processes specified by process or job ID
  869. .Ar pid
  870. have terminated.
  871. If no
  872. .Ar pid
  873. is specified,
  874. wait until all processes have terminated.
  875. The exit status is 0 on success,
  876. 1\(en126 if an error occurs,
  877. or 127 if
  878. .Ar pid
  879. was unknown.
  880. .El
  881. .Sh COMMAND HISTORY AND COMMAND LINE EDITING
  882. When a shell is interactive,
  883. it keeps a record of commands run in a
  884. .Em command history ,
  885. either internally in memory or in a file,
  886. as determined by
  887. .Dv HISTFILE .
  888. When
  889. .Cm vi
  890. command line editing mode is enabled
  891. .Pq set -o vi ,
  892. the command line and all the commands in command history
  893. can be edited using commands similar to those of
  894. .Xr vi 1 .
  895. .Pp
  896. There are two modes,
  897. .Em interactive
  898. and
  899. .Em command .
  900. The shell starts in interactive mode.
  901. In this mode text is entered normally.
  902. A
  903. .Aq newline
  904. executes the current command line.
  905. The command line, unless empty, is entered into command history.
  906. The
  907. .Aq ESC
  908. key is used to enter command mode,
  909. where commands similar to those used by
  910. .Xr vi 1
  911. are available.
  912. A Ctrl-L sequence
  913. .Pq ^L
  914. can be used in this mode to
  915. redraw the current command line.
  916. .Pp
  917. Where noted,
  918. some commands may be preceded by a numerical
  919. .Ar count ,
  920. which causes the command to be repeated that number of times.
  921. The term
  922. .Em word
  923. is used to denote a sequence of letters, digits, or underscores;
  924. .Em bigword
  925. denotes a sequence of whitespace delineated characters.
  926. .Pp
  927. The commands for command mode:
  928. .Bl -tag -width "<newline>"
  929. .It Ic =
  930. Display the possible shell word expansion.
  931. .It Ic \e
  932. Perform pathname expansion on the current word,
  933. matching the largest possible unique expansion,
  934. then enter insert mode.
  935. .It Ic *
  936. Perform pathname expansion on the current word,
  937. substituting every possible expansion,
  938. then enter insert mode.
  939. .It Ic @ Ns Ar c
  940. Perform the commands defined by the alias
  941. .No _ Ns Ar c ,
  942. where
  943. .Ar c
  944. is a single letter alphabetical character.
  945. .It Oo Ar count Oc Ns Ic ~
  946. Convert the character from lowercase to upper or vice versa.
  947. .It Oo Ar count Oc Ns Ic .\&
  948. Repeat the most recent non-motion command.
  949. If no
  950. .Ar count
  951. is given, use that of the repeated command,
  952. if any.
  953. .It Oo Ar n Oc Ns Ic v
  954. Use
  955. .Xr vi 1
  956. to edit command number
  957. .Ar n
  958. in command history,
  959. or the current command if none given.
  960. .It Xo
  961. .Oo Ar count Oc Ns Ic l ,
  962. .Oo Ar count Oc Ns Aq space
  963. .Xc
  964. Move right.
  965. .It Oo Ar count Oc Ns Ic h
  966. Move left.
  967. .It Oo Ar count Oc Ns Ic w
  968. Move to the start of the next word.
  969. .It Oo Ar count Oc Ns Ic W
  970. Move to the start of the next big word.
  971. .It Oo Ar count Oc Ns Ic e
  972. Move to the end of the current word,
  973. or the end of the next word if the cursor is currently
  974. at the end of a word.
  975. .It Oo Ar count Oc Ns Ic E
  976. Move to the end of the current bigword,
  977. or the end of the next bigword if the cursor is currently
  978. at the end of a bigword.
  979. .It Oo Ar count Oc Ns Ic b
  980. Move to the start of the current word,
  981. or the start of the next word if the cursor is currently
  982. at the start of a word.
  983. .It Oo Ar count Oc Ns Ic B
  984. Move to the start of the current bigword,
  985. or the start of the next bigword if the cursor is currently
  986. at the start of a bigword.
  987. .It Ic ^
  988. Move to the first non-blank character.
  989. .It Ic $
  990. Move to the end of the current line.
  991. .It Ic 0
  992. Move to the beginning of the current line.
  993. .It Oo Ar count Oc Ns Ic |\&
  994. Move to the beginning of the current line
  995. or the character position specified by
  996. .Ar count .
  997. .It Oo Ar count Oc Ns Ic f Ns Ar c
  998. Move to the next instance of the
  999. character
  1000. .Ar c .
  1001. .It Oo Ar count Oc Ns Ic F Ns Ar c
  1002. Move to the last instance of the
  1003. character
  1004. .Ar c .
  1005. .It Oo Ar count Oc Ns Ic t Ns Ar c
  1006. Move to the character before the next instance of the
  1007. character
  1008. .Ar c .
  1009. .It Oo Ar count Oc Ns Ic T Ns Ar c
  1010. Move to the character after the last instance of the
  1011. character
  1012. .Ar c .
  1013. .It Oo Ar count Oc Ns Ic ;\&
  1014. Repeat the last
  1015. .Ic f , F , t ,
  1016. or
  1017. .Ic T
  1018. command.
  1019. Ignore any
  1020. .Ar count
  1021. specified with the last command.
  1022. .It Oo Ar count Oc Ns Ic ,\&
  1023. Repeat the last
  1024. .Ic f , F , t ,
  1025. or
  1026. .Ic T
  1027. command,
  1028. but in the opposite direction.
  1029. Ignore any
  1030. .Ar count
  1031. specified with the last command.
  1032. .It Ic a
  1033. Enter insert mode after the current cursor position.
  1034. .It Ic A
  1035. Enter insert mode after the end of the current line.
  1036. .It Ic i
  1037. Enter insert mode at the current cursor position.
  1038. .It Ic I
  1039. Enter insert mode at the beginning of the current line.
  1040. .It Ic R
  1041. Enter insert mode at the current cursor position,
  1042. replacing any characters thereafter.
  1043. .It Oo Ar count Oc Ns Ic c Ns Ar motion
  1044. Delete the characters between the cursor and the motion command specified,
  1045. then enter insert mode.
  1046. A special motion command,
  1047. .Ic c ,
  1048. may be used to delete the entire line.
  1049. The
  1050. .Ar count
  1051. argument is ignored for the commands
  1052. .Ic 0 , ^ , $ ,
  1053. and
  1054. .Ic c .
  1055. If the motion moves towards the beginning of the line,
  1056. the character under the cursor is not deleted;
  1057. if it moves towards the end of the line,
  1058. it is deleted.
  1059. .It Ic C
  1060. Delete the characters between the cursor and the line end,
  1061. then enter insert mode.
  1062. .It Ic S
  1063. Clear the entire line,
  1064. then enter insert mode.
  1065. .It Oo Ar count Oc Ns Ic r
  1066. Replace the character under the cursor with the next typed character.
  1067. With a
  1068. .Ar count ,
  1069. replace the current character
  1070. and the corresponding number of following characters.
  1071. .It Oo Ar count Oc Ns Ic _
  1072. After the cursor,
  1073. append a
  1074. .Aq space
  1075. and the
  1076. .Ar count Ns th
  1077. bigword (by default the last entered)
  1078. from the previous input line,
  1079. then enter insert mode.
  1080. .It Oo Ar count Oc Ns Ic x
  1081. Delete the character under the cursor,
  1082. placing it in the save buffer.
  1083. .It Oo Ar count Oc Ns Ic X
  1084. Delete the character before the cursor,
  1085. placing it in the save buffer.
  1086. .It Oo Ar count Oc Ns Ic d Ns Ar motion
  1087. Delete the characters between the cursor and the motion command specified,
  1088. placing them in the save buffer.
  1089. A special motion command,
  1090. .Ic d ,
  1091. may be used to delete the entire line.
  1092. If the motion moves towards the beginning of the line,
  1093. the character under the cursor is not deleted.
  1094. .It Oo Ar count Oc Ns Ic D
  1095. Delete the characters between the cursor and the line end,
  1096. placing them in the save buffer.
  1097. .It Oo Ar count Oc Ns Ic y Ns Ar motion
  1098. Yank (copy) the characters between the cursor and the motion command specified,
  1099. placing them in the save buffer.
  1100. A special motion command,
  1101. .Ic y ,
  1102. may be used to yank the entire line.
  1103. If the motion moves towards the beginning of the line,
  1104. the character under the cursor is not yanked.
  1105. .It Oo Ar count Oc Ns Ic Y
  1106. Yank (copy) the characters between the cursor and the line end,
  1107. placing them in the save buffer.
  1108. .It Oo Ar count Oc Ns Ic p
  1109. Paste the contents of the save buffer after the cursor.
  1110. .It Oo Ar count Oc Ns Ic P
  1111. Paste the contents of the save buffer before the cursor.
  1112. .It Oo Ar count Oc Ns Ic u
  1113. Undo the last change to the edit line.
  1114. .It Oo Ar count Oc Ns Ic U
  1115. Undo all changes to the edit line.
  1116. .It Xo
  1117. .Oo Ar count Oc Ns Ic k ,
  1118. .Oo Ar count Oc Ns Ic -\&
  1119. .Xc
  1120. Replace the current command line with the previous entry in history.
  1121. .It Xo
  1122. .Oo Ar count Oc Ns Ic j ,
  1123. .Oo Ar count Oc Ns Ic +\&
  1124. .Xc
  1125. Replace the current command line with the next entry in history.
  1126. .It Oo Ar n Oc Ns Ic G
  1127. Replace the current command line with command number
  1128. .Ar n
  1129. in command history,
  1130. or the oldest command if none given.
  1131. .It / Ns Ar pattern
  1132. Moving backwards through history,
  1133. replace the current command line with the first that matches
  1134. .Ar pattern .
  1135. A
  1136. .Sq ^
  1137. at the beginning of the pattern searches only for entries beginning with
  1138. .Ar pattern .
  1139. An empty pattern matches the last search.
  1140. .It ? Ns Ar pattern
  1141. As above,
  1142. but searching forwards.
  1143. .It Ic n
  1144. Repeat the most recent pattern search.
  1145. .It Ic N
  1146. Repeat the most recent pattern search,
  1147. but in the opposite direction.
  1148. .El
  1149. .Sh SHELL GRAMMAR
  1150. The shell reads its input as described above.
  1151. After that it follows a fairly simple chain of operations
  1152. to parse that input:
  1153. .Bl -dash
  1154. .It
  1155. The shell breaks the input into
  1156. .Em words
  1157. and
  1158. .Em operators .
  1159. Words are the command text the user wishes run;
  1160. operators are special characters which describe
  1161. how the shell should interact with the commands.
  1162. .It
  1163. The shell
  1164. .Em expands
  1165. the command text according to the rules of expansion.
  1166. .It
  1167. Words are subject to
  1168. .Em field splitting ,
  1169. where the command text is separated into commands
  1170. and arguments to commands.
  1171. .It
  1172. The shell performs any
  1173. .Em redirection .
  1174. .It
  1175. The shell runs the commands.
  1176. Argument names are assigned to
  1177. .Em positional parameters ,
  1178. with the command name itself assigned parameter 0.
  1179. .It
  1180. If the command is not being run in the background,
  1181. the shell waits for it to complete
  1182. and collects its exit status.
  1183. .El
  1184. .Ss Quoting
  1185. Some characters have special meaning to the shell and need
  1186. .Em quoting
  1187. if the user wants to indicate to the shell not to interpret them as such.
  1188. The following characters need quoting if their literal meaning is desired:
  1189. .Bd -literal -offset indent
  1190. | & ; < > ( ) $ \` \e " \(aq <space> <tab> <newline>
  1191. * ? [ # ~ = %
  1192. .Ed
  1193. .Pp
  1194. A backslash
  1195. .Pq \e
  1196. can be used to quote any character except a newline.
  1197. If a newline follows a backslash the shell removes them both,
  1198. effectively making the following line part of the current one.
  1199. .Pp
  1200. A group of characters can be enclosed within single quotes
  1201. .Pq \(aq
  1202. to quote every character within the quotes.
  1203. .Pp
  1204. A group of characters can be enclosed within double quotes
  1205. .Pq \&"
  1206. to quote every character within the quotes
  1207. except a backquote
  1208. .Pq \`
  1209. or a dollar sign
  1210. .Pq $ ,
  1211. both of which retain their special meaning.
  1212. A backslash
  1213. .Pq \e
  1214. within double quotes retains its special meaning,
  1215. but only when followed by a backquote, dollar sign,
  1216. double quote, newline, or another backslash.
  1217. An at sign
  1218. .Pq @
  1219. within double quotes has a special meaning
  1220. (see
  1221. .Sx SPECIAL PARAMETERS ,
  1222. below).
  1223. .Pp
  1224. Similarly command words need to be quoted
  1225. if they are not to be interpreted as such.
  1226. .Ss Expansion
  1227. Shell
  1228. .Em variables
  1229. are arbitrary names assigned values using the
  1230. .Sq =
  1231. operator;
  1232. the values can be retrieved using the syntax
  1233. .No $ Ns Ar variable .
  1234. Shell
  1235. .Em parameters
  1236. are variable names,
  1237. numbers,
  1238. or any of the characters listed in
  1239. .Sx SPECIAL PARAMETERS .
  1240. .Pp
  1241. The shell is able to
  1242. .Em expand
  1243. certain elements of its syntax,
  1244. allowing for a more concise notation
  1245. and providing a convenience to the user.
  1246. .Pp
  1247. Firstly, tilde expansion occurs on words beginning with the
  1248. .Sq ~
  1249. character.
  1250. Any characters following the tilde,
  1251. up to the next colon, slash, or blank,
  1252. are taken as a login name
  1253. and substituted with that user's home directory,
  1254. as defined in
  1255. .Xr passwd 5 .
  1256. A tilde by itself is expanded to the contents of the variable
  1257. .Ev HOME .
  1258. This notation can be used in variable assignments,
  1259. in the assignment half,
  1260. immediately after the equals sign or a colon,
  1261. up to the next slash or colon, if any.
  1262. .Pp
  1263. .Dl PATH=~alice:~bob/jobs
  1264. .Pp
  1265. Parameter expansion happens after tildes have been expanded,
  1266. with the value of the parameter being substituted.
  1267. The basic format is:
  1268. .Pp
  1269. .D1 $ Ns Brq Ar parameter
  1270. .Pp
  1271. The braces are optional
  1272. except for positional parameters 10 and higher,
  1273. or where the parameter name is followed by other characters
  1274. that would prevent it from being expanded.
  1275. If parameter expansion occurs within double quotes,
  1276. neither pathname expansion nor field splitting happens afterwards.
  1277. .Pp
  1278. Some special forms of parameter expansion are available.
  1279. In the formats below,
  1280. .Ar word
  1281. itself is subject to expansion,
  1282. and, if omitted,
  1283. the empty string is used.
  1284. If the colon is omitted,
  1285. .Ar word
  1286. is substituted only if
  1287. .Ar parameter
  1288. is unset (not if it is empty).
  1289. .Bl -tag -width Ds
  1290. .It $ Ns Brq Ar parameter Ns :- Ns Op Ar word
  1291. Substitute
  1292. .Ar parameter .
  1293. If
  1294. .Ar parameter
  1295. is unset or empty,
  1296. substitute
  1297. .Ar word .
  1298. .It $ Ns Brq Ar parameter Ns := Ns Op Ar word
  1299. Substitute
  1300. .Ar parameter .
  1301. If
  1302. .Ar parameter
  1303. is unset or empty,
  1304. first assign the value of
  1305. .Ar word
  1306. to
  1307. .Ar parameter .
  1308. .It $ Ns Brq Ar parameter Ns :? Ns Op Ar word
  1309. Substitute
  1310. .Ar parameter .
  1311. If
  1312. .Ar parameter
  1313. is unset or empty,
  1314. the result of the expansion of
  1315. .Ar word
  1316. is written to standard error
  1317. and the shell exits with a non-zero exit status.
  1318. If
  1319. .Ar word
  1320. is omitted,
  1321. the string
  1322. .Qq parameter null or not set
  1323. is used.
  1324. .It $ Ns Brq Ar parameter Ns :+ Ns Op Ar word
  1325. Substitute
  1326. .Ar word .
  1327. If
  1328. .Ar parameter
  1329. is unset or empty,
  1330. substitute the empty string.
  1331. .It $ Ns Brq # Ns Ar parameter
  1332. The length, in characters, of
  1333. .Ar parameter .
  1334. .It $ Ns Brq Ar parameter Ns % Ns Op Ar word
  1335. Substitute
  1336. .Ar parameter ,
  1337. deleting the smallest possible suffix matching
  1338. .Ar word .
  1339. .It $ Ns Brq Ar parameter Ns %% Ns Op Ar word
  1340. Substitute
  1341. .Ar parameter ,
  1342. deleting the largest possible suffix matching
  1343. .Ar word .
  1344. .It $ Ns Brq Ar parameter Ns # Ns Op Ar word
  1345. Substitute
  1346. .Ar parameter ,
  1347. deleting the smallest possible prefix matching
  1348. .Ar word .
  1349. .It $ Ns Brq Ar parameter Ns ## Ns Op Ar word
  1350. Substitute
  1351. .Ar parameter ,
  1352. deleting the largest possible prefix matching
  1353. .Ar word .
  1354. .El
  1355. .Pp
  1356. Command expansion has a command executed in a subshell
  1357. and the results output in its place.
  1358. The basic format is:
  1359. .Pp
  1360. .D1 $ Ns Pq Ar command
  1361. or
  1362. .D1 \` Ns Ar command Ns \`
  1363. .Pp
  1364. The results are subject to field splitting and pathname expansion;
  1365. no other form of expansion happens.
  1366. If
  1367. .Ar command
  1368. is contained within double quotes,
  1369. field splitting does not happen either.
  1370. Within backquotes,
  1371. a backslash is treated literally unless it follows
  1372. a dollar sign, backquote, or another backslash.
  1373. Commands can be nested,
  1374. though the backquoted version requires backslashes before the backquotes.
  1375. If
  1376. .Ar command
  1377. is run in a subshell in the bracketed version,
  1378. the syntax is identical to that of arithmetic expansion.
  1379. In that case the shell attempts arithmetic expansion first,
  1380. then attempts command substitution if that fails.
  1381. Or a non-ambiguous version can be used:
  1382. .Pp
  1383. .D1 "$( (" Ns Ar command Ns ") )"
  1384. .Pp
  1385. Arithmetic expansion works similarly,
  1386. with an arithmetic expression being evaluated and substituted.
  1387. The format is:
  1388. .Pp
  1389. .D1 $ Ns Pq Pq Ar expression
  1390. .Pp
  1391. Where
  1392. .Ar expression
  1393. is an integer or parameter name,
  1394. optionally combined with any of the operators described below,
  1395. listed and grouped according to precedence:
  1396. .Bl -tag -width Ds
  1397. .It ()\&
  1398. Operators within brackets have highest precedence.
  1399. Compare 3+2*4, which is 11,
  1400. since multiplication has higher precedence than addition,
  1401. and (3+2)*4, which is 20.
  1402. .It + - ~ !\&
  1403. Unary plus
  1404. (indicates a positive value; integers are positive by default),
  1405. unary minus (indicates a negative value),
  1406. bitwise NOT,
  1407. and logical NOT
  1408. (the result is 1 if the argument is zero, or 0 otherwise), respectively.
  1409. .It * / %
  1410. Multiplication, division, and modulus (remainder), respectively.
  1411. .It + -
  1412. Addition and subtraction, respectively.
  1413. .It << >>
  1414. Shift left or right, respectively.
  1415. .It < <= > >=
  1416. Less than, less than or equal to,
  1417. greater than, and greater than or equal to, respectively.
  1418. The result is 1 if true, or 0 otherwise.
  1419. .It == !=
  1420. Equal (the result is 1 if both arguments are equal, and 0 otherwise)
  1421. and not equal (the result is 0 if both arguments are equal, and 1 otherwise),
  1422. respectively.
  1423. .It &
  1424. Bitwise AND.
  1425. .It ^
  1426. Bitwise exclusive OR.
  1427. .It |
  1428. Bitwise inclusive OR.
  1429. .It &&
  1430. Logical AND.
  1431. The result is 1 if both arguments are non-zero, or 0 otherwise.
  1432. .It ||
  1433. Logical OR.
  1434. The result is 1 if either argument is non-zero, or 0 otherwise.
  1435. .It Ar expression ? Ns Ar expr1 : Ns Ar expr2
  1436. The result is
  1437. .Ar expr1
  1438. if
  1439. .Ar expression
  1440. is non-zero,
  1441. or
  1442. .Ar expr2
  1443. otherwise.
  1444. .It = *= /= %= += -= <<= >>= &= ^= |=
  1445. Assignment.
  1446. The notation
  1447. .Ar var Ns *= Ns Ar expression
  1448. is equivalent to
  1449. .Ar var Ns = Ns Ar var Ns * Ns Ar expression .
  1450. .El
  1451. .Pp
  1452. After the various types of expansion listed above have been carried out,
  1453. the shell subjects everything that did not occur in double quotes to
  1454. .Em field splitting ,
  1455. where words are broken up according to the value of the
  1456. .Ev IFS
  1457. variable.
  1458. Each character of
  1459. .Ev IFS
  1460. is used to split fields;
  1461. any
  1462. .Ev IFS
  1463. characters at the beginning and end of input are ignored.
  1464. If
  1465. .Ev IFS
  1466. is unset, the default value consisting of
  1467. .Aq space ,
  1468. .Aq tab
  1469. and
  1470. .Aq newline
  1471. is used; if the value of
  1472. .Ev IFS
  1473. is empty, no field splitting is performed.
  1474. .Pp
  1475. After field splitting,
  1476. the shell matches filename patterns.
  1477. .Bl -tag -width Ds
  1478. .It ?
  1479. A question mark matches any single character.
  1480. .It *
  1481. An asterisk matches multiple characters.
  1482. .It [..]
  1483. Matches any character enclosed in the brackets.
  1484. The sense is negated if the first character is
  1485. .Sq !\& .
  1486. A closing bracket can be included in the list of characters to match
  1487. by listing it as the first character after the opening bracket
  1488. or by quoting it.
  1489. Similarly a
  1490. .Sq -
  1491. should be specified last or quoted so that the shell does not think
  1492. it is a character range (see below).
  1493. .It [[: Ns Ar class Ns :]]
  1494. Matches any character in the following character classes:
  1495. .Bd -literal -offset indent
  1496. alnum alpha blank cntrl
  1497. digit graph lower print
  1498. punct space upper xdigit
  1499. .Ed
  1500. .It Bq Ar x Ns - Ns Ar y
  1501. Matches any character in the range between
  1502. .Ar x
  1503. and
  1504. .Ar y ,
  1505. inclusive.
  1506. .El
  1507. .Pp
  1508. Slashes and full stops do not match the patterns above
  1509. because of their use as path and filename characters.
  1510. .Ss Redirection
  1511. Redirection is used to open, close, or otherwise manipulate files,
  1512. using redirection operators in combination with numerical
  1513. .Em file descriptors .
  1514. A minimum of ten (0\-9) descriptors are supported;
  1515. by convention
  1516. standard input is file descriptor 0,
  1517. standard output file descriptor 1,
  1518. and standard error file descriptor 2.
  1519. In the examples given below,
  1520. .Ar n
  1521. represents a numerical file descriptor.
  1522. The target for redirection is
  1523. .Ar file
  1524. and it is subject to all forms of expansion as listed above,
  1525. except pathname expansion.
  1526. If any part of the file descriptor or redirection operator is quoted,
  1527. they are not recognised.
  1528. .Bl -tag -width Ds
  1529. .It Oo Ar n Oc Ns < Ns Ar file
  1530. Open
  1531. .Ar file
  1532. for reading on file descriptor
  1533. .Ar n ,
  1534. by default standard input.
  1535. .It Oo Ar n Oc Ns > Ns Ar file
  1536. Write to
  1537. .Ar file
  1538. with file descriptor
  1539. .Ar n ,
  1540. by default standard output.
  1541. If
  1542. .Ar file
  1543. does not exist,
  1544. create it;
  1545. if it does exist,
  1546. truncate it to be empty before beginning to write to it.
  1547. .It Oo Ar n Oc Ns >| Ns Ar file
  1548. As above, but forces clobbering
  1549. (see the
  1550. .Fl C
  1551. option).
  1552. .It Oo Ar n Oc Ns >> Ns Ar file
  1553. Append to
  1554. .Ar file
  1555. with file descriptor
  1556. .Ar n ,
  1557. by default standard output.
  1558. If
  1559. .Ar file
  1560. does not exist,
  1561. create it.
  1562. .It Oo Ar n Oc Ns <<
  1563. This form of redirection,
  1564. called a
  1565. .Em here document ,
  1566. is used to copy a block of lines
  1567. to a temporary file until a line matching
  1568. .Ar delimiter
  1569. is read.
  1570. When the command is executed, standard input is redirected from the
  1571. temporary file to file descriptor
  1572. .Ar n ,
  1573. or standard input by default.
  1574. The basic format is:
  1575. .Bd -unfilled -offset indent
  1576. .Oo Ar n Oc Ns << Ns Ar delimiter
  1577. text
  1578. text
  1579. \&...
  1580. .Ar delimiter
  1581. .Ed
  1582. .Pp
  1583. Provided
  1584. .Ar delimiter
  1585. doesn't contain any quoted characters,
  1586. parameter, command, and arithmetic expansions are performed on
  1587. the text block,
  1588. and backslashes escape the special meaning of
  1589. .Sq $ ,
  1590. .Sq \` ,
  1591. and
  1592. .Sq \e .
  1593. If multiple here documents are used on the same command line,
  1594. they are saved and processed in order.
  1595. .It Oo Ar n Oc Ns <<-
  1596. Same as
  1597. .Ic << ,
  1598. except leading tabs are stripped from lines in
  1599. .Ar block .
  1600. .It Oo Ar n Oc Ns <& Ns Ar file
  1601. Make file descriptor
  1602. .Ar n ,
  1603. by default standard input,
  1604. a copy of the file descriptor denoted by
  1605. .Ar file .
  1606. If
  1607. .Ar file
  1608. is
  1609. .Sq - ,
  1610. close file descriptor
  1611. .Ar n
  1612. or standard input.
  1613. .It Oo Ar n Oc Ns >& Ns Ar file
  1614. Make file descriptor
  1615. .Ar n ,
  1616. by default standard output,
  1617. a copy of the file descriptor denoted by
  1618. .Ar file .
  1619. If
  1620. .Ar file
  1621. is
  1622. .Sq - ,
  1623. close file descriptor
  1624. .Ar n
  1625. or standard output.
  1626. .It Oo Ar n Oc Ns <> Ns Ar file
  1627. Open
  1628. .Ar file
  1629. for reading and writing on file descriptor
  1630. .Ar n ,
  1631. by default standard input.
  1632. If
  1633. .Ar file
  1634. does not exist,
  1635. create it.
  1636. .El
  1637. .Sh COMMANDS
  1638. The shell first expands
  1639. any words that are not variable assignments or redirections,
  1640. with the first field being the command name
  1641. and any successive fields arguments to that command.
  1642. It sets up redirections, if any,
  1643. and then expands variable assignments, if any.
  1644. It then attempts to run the command.
  1645. .Pp
  1646. Firstly, it determines whether the command name contains any slashes.
  1647. If it does not, and the shell implements the command as a special built-in,
  1648. it then invokes the built-in.
  1649. If not, but it is a non POSIX standard command,
  1650. implemented as a shell function,
  1651. it then invokes that.
  1652. If not, but it is one of the commands
  1653. .Ic alias , bg , cd , command ,
  1654. .Ic false , fc , fg , getopts ,
  1655. .Ic jobs , kill , newgrp , pwd ,
  1656. .Ic read , true , umask , unalias ,
  1657. or
  1658. .Ic wait ,
  1659. it then invokes that.
  1660. .Pp
  1661. Failing that, the value of
  1662. .Ev PATH
  1663. is used to search for the command.
  1664. If it finds a match,
  1665. and it is a POSIX standard command,
  1666. implemented as a built-in or function,
  1667. it then invokes it.
  1668. Otherwise
  1669. it attempts to execute the command in an environment separate from the shell.
  1670. If it is unable to execute the command,
  1671. it tries to run it as a shell script.
  1672. .Pp
  1673. Finally, if the command name does contain a slash,
  1674. and it finds a match in
  1675. .Ev PATH ,
  1676. it attempts to execute the command in an environment separate from the shell.
  1677. If it is unable to execute the command,
  1678. it tries to run it as a shell script.
  1679. .Pp
  1680. A series of one or more commands separated by
  1681. .Sq ;\&
  1682. constitute a
  1683. .Em sequential list ,
  1684. where commands are executed in the order given.
  1685. The exit status of a sequential list is that of the last command executed.
  1686. The format for a sequential list is:
  1687. .Pp
  1688. .D1 Ar command No \&; Op Ar command ...
  1689. .Pp
  1690. A series of one or more commands separated by
  1691. .Sq &
  1692. constitute an
  1693. .Em asynchronous list ,
  1694. where the shell executes the command in a subshell
  1695. and runs the next command without waiting for the previous one to finish.
  1696. The exit status of an asynchronous list is always zero.
  1697. The format for an asynchronous list is:
  1698. .Pp
  1699. .D1 Ar command No & Op Ar command ...
  1700. .Pp
  1701. A series of commands separated by
  1702. .Sq |
  1703. constitute a
  1704. .Em pipeline ,
  1705. where the output of one command
  1706. is used as input for the next command.
  1707. The exit status of a pipeline is that of the last command;
  1708. if a pipeline begins
  1709. .Sq !\&
  1710. the exit status is inverted.
  1711. The format for a pipeline is:
  1712. .Pp
  1713. .D1 Oo !\& Oc Ar command | command Op | Ar ...
  1714. .Pp
  1715. A series of commands separated by
  1716. .Sq &&
  1717. constitute an
  1718. .Em AND list ,
  1719. where a command is only executed if the exit status of the previous command was
  1720. zero.
  1721. The exit status of an AND list is that of the last command.
  1722. The format for an AND list is:
  1723. .Pp
  1724. .D1 Ar command No && Ar command Op && Ar ...
  1725. .Pp
  1726. A series of commands separated by
  1727. .Sq ||
  1728. constitute an
  1729. .Em OR list ,
  1730. where a command is only executed if the exit status of the previous command was
  1731. non-zero.
  1732. The exit status of an OR list is that of the last command.
  1733. The format for an OR list is:
  1734. .Pp
  1735. .D1 Ar command No || Ar command Op || Ar ...
  1736. .Pp
  1737. A series of commands separated by
  1738. .Sq &&
  1739. and
  1740. .Sq ||
  1741. constitute an
  1742. .Em AND-OR list ,
  1743. where
  1744. .Sq &&
  1745. and
  1746. .Sq ||
  1747. have equal precedence and are evaluated in the order they are given.
  1748. The AND-OR list can be terminated with
  1749. .Sq ;\&
  1750. or
  1751. .Sq &
  1752. to have them execute sequentially or asynchronously, respectively.
  1753. .Pp
  1754. Command lists,
  1755. as described above,
  1756. can be enclosed within
  1757. .Sq ()
  1758. to have them executed in a subshell,
  1759. or within
  1760. .Sq {}
  1761. to have them executed in the current environment:
  1762. .Pp
  1763. .D1 Pq Ar command ...
  1764. .D1 Brq \& Ar command ... ; No \&
  1765. .Pp
  1766. Any redirections specified after the closing bracket apply to all commands
  1767. within the brackets.
  1768. An operator such as
  1769. .Sq ;\&
  1770. or a newline are needed to terminate a command list within curly braces.
  1771. .Pp
  1772. The shell has grammatical constructs
  1773. which allow it to work its way (loop) through lists
  1774. or evaluate things conditionally.
  1775. .Pp
  1776. A
  1777. .Em for loop
  1778. executes a series of commands for each item in a list.
  1779. Its format is:
  1780. .Bd -unfilled -offset indent
  1781. .No for Ar name Op in Op Ar word ...
  1782. do
  1783. .No " " Ar command
  1784. .No " " Ar ...
  1785. done
  1786. .Ed
  1787. .Pp
  1788. Firstly
  1789. .Ar word ...
  1790. is expanded to generate a list of items.
  1791. The variable
  1792. .Ar name
  1793. is set to each item, in turn,
  1794. and the commands are executed for each item.
  1795. The construct
  1796. .Qq in word ...
  1797. can be omitted,
  1798. which is equivalent to: in \&"$@\&".
  1799. The exit status is that of the last command executed.
  1800. If there are no items,
  1801. .Ar command
  1802. is not executed and the exit status is zero.
  1803. .Pp
  1804. A
  1805. .Em while loop
  1806. continuously executes a set of commands
  1807. as long as the command or command list being tested in
  1808. .Ar condition
  1809. has a zero exit status.
  1810. Its format is:
  1811. .Bd -unfilled -offset indent
  1812. .No while Ar condition
  1813. do
  1814. .No " " Ar command
  1815. .No " " Ar ...
  1816. done
  1817. .Ed
  1818. .Pp
  1819. Multiple commands may be given by grouping them in lists,
  1820. as described above,
  1821. or by separating them with newlines.
  1822. The exit status is zero if the commands after
  1823. .Qq do
  1824. were never executed
  1825. or otherwise the exit status of the last command executed.
  1826. .Pp
  1827. An
  1828. .Em until loop
  1829. continuously executes a set of commands
  1830. as long as the command or command list being tested in
  1831. .Ar condition
  1832. has a non-zero exit status.
  1833. Its format is:
  1834. .Bd -unfilled -offset indent
  1835. .No until Ar condition
  1836. do
  1837. .No " " Ar command
  1838. .No " " Ar ...
  1839. done
  1840. .Ed
  1841. .Pp
  1842. Multiple commands may be given by grouping them in lists,
  1843. as described above,
  1844. or by separating them with newlines.
  1845. The exit status is zero if the commands after
  1846. .Qq do
  1847. were never executed
  1848. or otherwise the exit status is that of the last command executed.
  1849. .Pp
  1850. A
  1851. .Em case conditional
  1852. is used to run commands whenever a pattern is matched.
  1853. Its format is:
  1854. .Bd -unfilled -offset indent
  1855. .No case Ar word No in
  1856. .No " " Po Ar pattern Oo | Ar pattern ... Oc Pc Ar command Ns ;;
  1857. .No " " Ar ...
  1858. esac
  1859. .Ed
  1860. .Pp
  1861. In this case
  1862. .Ar pattern
  1863. is matched against the string resulting from the expansion of
  1864. .Ar word .
  1865. Multiple commands may be given by grouping them in lists,
  1866. as described above,
  1867. or by separating them with newlines.
  1868. The initial
  1869. .Sq (\&
  1870. is optional,
  1871. as is the terminating
  1872. .Sq ;;
  1873. for the final command.
  1874. The exit status is zero if no patterns are matched
  1875. or otherwise the exit status of the last command executed.
  1876. .Pp
  1877. An
  1878. .Em if conditional
  1879. is used to execute commands depending on the exit status of the command or
  1880. command list being tested.
  1881. Its format is:
  1882. .Bd -unfilled -offset indent
  1883. .No if Ar conditional
  1884. then
  1885. .No " " Ar command
  1886. .No " " Ar ...
  1887. .No elif Ar conditional
  1888. then
  1889. .No " " Ar command
  1890. .No " " Ar ...
  1891. .No else
  1892. .No " " Ar command
  1893. .No " " Ar ...
  1894. fi
  1895. .Ed
  1896. .Pp
  1897. Firstly the command(s) following
  1898. .Qq if
  1899. is executed;
  1900. if its exit status is zero,
  1901. the commands in the
  1902. .Qq then
  1903. block are executed and the conditional completes.
  1904. Otherwise the commands in the
  1905. .Qq elif
  1906. block are executed;
  1907. if the exit status is zero,
  1908. the commands in the
  1909. .Qq then
  1910. block are executed and the conditional completes.
  1911. Otherwise the next
  1912. .Qq elif
  1913. block, if any, is tried.
  1914. If nothing from an
  1915. .Qq if
  1916. or
  1917. .Qq elif
  1918. block returns zero,
  1919. the commands in the
  1920. .Qq else
  1921. block are run and the conditional completes.
  1922. The
  1923. .Qq elif
  1924. and
  1925. .Qq else
  1926. blocks are optional.
  1927. .Pp
  1928. Multiple commands may be given by grouping them in lists,
  1929. as described above,
  1930. or by separating them with newlines.
  1931. The exit status is zero if nothing is executed from an
  1932. .Qq if
  1933. or
  1934. .Qq elif
  1935. block
  1936. or otherwise the exit status of the last command executed.
  1937. .Pp
  1938. Functions allow the user to define a group of commands,
  1939. executed whenever the function is invoked.
  1940. Its format is:
  1941. .Bd -unfilled -offset indent
  1942. .Ar function Ns () Ar command-list
  1943. .Ed
  1944. .Pp
  1945. The above simply defines a function;
  1946. nothing is executed until the function is invoked.
  1947. Commands may specify redirections
  1948. and positional parameters are changed,
  1949. for the duration of the function,
  1950. to those passed to it.
  1951. The special parameter
  1952. .Sq #
  1953. is temporarily changed too,
  1954. though
  1955. .Sq 0
  1956. is not.
  1957. After the function finishes,
  1958. the positional parameters and
  1959. .Sq #
  1960. are restored to their original values.
  1961. The exit status of a function definition is 0 if successful
  1962. or >0 otherwise.
  1963. The exit status of a function is that of the last command
  1964. executed by the function.
  1965. .Sh SPECIAL PARAMETERS
  1966. Some parameters have special meaning to the shell
  1967. and are listed below.
  1968. .Bl -tag -width Ds
  1969. .It 0
  1970. The name of the shell or shell script.
  1971. .It 1 ... n
  1972. The
  1973. .Em positional parameters .
  1974. These parameters are set when a shell, shell script,
  1975. or shell function is invoked.
  1976. Each argument passed to a shell or shell script
  1977. is assigned a positional parameter,
  1978. starting at 1,
  1979. and assigned sequentially.
  1980. When a shell function is invoked,
  1981. any arguments passed to it are temporarily reassigned to the
  1982. positional parameters;
  1983. when the function completes,
  1984. the values are restored.
  1985. Positional parameters 10 and above should be enclosed in {}.
  1986. Positional parameters can be reassigned using the
  1987. .Ic set
  1988. command.
  1989. .It @
  1990. All positional parameters.
  1991. Within double quotes,
  1992. each parameter is output as a separate field.
  1993. The resulting list completely matches what was passed to the shell.
  1994. So "1 2" "3" is output as two parameters, "1 2" and "3".
  1995. .It *
  1996. All positional parameters.
  1997. Within double quotes,
  1998. all parameters are output as one field,
  1999. separated by the first character of
  2000. .Ev IFS
  2001. (by default a space).
  2002. The resulting list of words is amalgamated,
  2003. losing the sense of how they were passed to the shell.
  2004. So "1 2" "3" is output as one parameter, "1 2 3".
  2005. .It #
  2006. The number of positional parameters.
  2007. .It ?
  2008. The exit status of the most recent command.
  2009. .It -
  2010. The current shell options.
  2011. .It $
  2012. The process ID of the current shell.
  2013. Subshells have the same PID as the current shell.
  2014. .It !
  2015. The process ID of the most recent background command.
  2016. .El
  2017. .Sh ENVIRONMENT
  2018. The following environment variables affect the execution of
  2019. .Nm :
  2020. .Bl -tag -width "POSIXLY_CORRECT"
  2021. .It Ev CDPATH
  2022. Colon separated list of directories used by the
  2023. .Ic cd
  2024. command.
  2025. If unset or empty,
  2026. the current working directory is used.
  2027. .It Ev ENV
  2028. Pathname to a file containing commands to be executed
  2029. when an interactive shell is started.
  2030. .It Ev FCEDIT
  2031. Editor for the
  2032. .Ic fc
  2033. builtin.
  2034. The default is
  2035. .Xr ed 1 .
  2036. .It Ev HISTFILE
  2037. Pathname to a file to be used to record command history.
  2038. The default is to not write command history to a file.
  2039. .It Ev HISTSIZE
  2040. The maximum number of commands stored in history.
  2041. The default is 500.
  2042. .It Ev HOME
  2043. Pathname to a user's home directory.
  2044. .It Ev IFS
  2045. A list of characters to be used for field splitting.
  2046. .It Ev LINENO
  2047. The current line number in a script or function,
  2048. starting at 1.
  2049. This variable should not be set by users.
  2050. .It Ev MAIL
  2051. Pathname to a user's mailbox file.
  2052. If set,
  2053. .Nm
  2054. reports the arrival of new mail
  2055. (ascertained by checking a file's modification time)
  2056. every
  2057. .Ev MAILCHECK
  2058. seconds.
  2059. .Ev MAIL
  2060. is overridden by
  2061. .Ev MAILPATH .
  2062. .It Ev MAILCHECK
  2063. How often,
  2064. in seconds,
  2065. to check for new mail in either
  2066. .Ev MAIL
  2067. or
  2068. .Ev MAILPATH .
  2069. The default is 600 (10 minutes).
  2070. If set to 0,
  2071. check before issuing each prompt.
  2072. .It Ev MAILPATH
  2073. Pathname to a colon separated list of mailboxes.
  2074. If set,
  2075. .Nm
  2076. reports the arrival of new mail
  2077. (ascertained by checking a file's modification time)
  2078. every
  2079. .Ev MAILCHECK
  2080. seconds.
  2081. The default notification message
  2082. .Pq Qq you have mail in $_
  2083. can be changed per mailbox by appending
  2084. .No % Ns Ar message
  2085. to a pathname.
  2086. .Ev MAILPATH
  2087. overrides
  2088. .Ev MAIL .
  2089. .It Ev OLDPWD
  2090. Pathname to the previous working directory.
  2091. .It Ev OPTARG
  2092. An option argument for the
  2093. .Ic getopts
  2094. command.
  2095. .It Ev OPTIND
  2096. An index to the next option for the
  2097. .Ic getopts
  2098. command.
  2099. .It Ev PATH
  2100. Pathname to a colon separated list of directories
  2101. used to search for the location of executable files.
  2102. A pathname of
  2103. .Sq .\&
  2104. represents the current working directory.
  2105. The default value of
  2106. .Ev PATH
  2107. on
  2108. .Ox
  2109. is:
  2110. .Bd -literal -offset 2n
  2111. /usr/bin:/bin:/usr/sbin:/sbin:/usr/X11R6/bin:/usr/local/bin:/usr/local/sbin
  2112. .Ed
  2113. .It Ev POSIXLY_CORRECT
  2114. Enable POSIX mode
  2115. (see
  2116. .Sx STANDARDS ) .
  2117. .It Ev PPID
  2118. The shell's parent process ID.
  2119. Subshells have the same
  2120. .Ev PPID
  2121. as the current shell.
  2122. .It Ev PS1
  2123. User prompt displayed every time an interactive shell
  2124. is ready to read a command.
  2125. A
  2126. .Sq !\&
  2127. in the prompt is expanded to the number of the next command in history
  2128. to be typed.
  2129. .It Ev PS2
  2130. Newline prompt displayed in an interactive shell
  2131. when a newline has been entered
  2132. before the command line completes.
  2133. The default value is
  2134. .Sq >\ \& .
  2135. .It Ev PS4
  2136. Trace prompt displayed in an interactive shell
  2137. before each command is traced
  2138. (see the
  2139. .Fl x
  2140. option).
  2141. The default is
  2142. .Sq +\ \& .
  2143. .It Ev PWD
  2144. The absolute pathname to the current working directory.
  2145. .El
  2146. .Sh ASYNCHRONOUS EVENTS
  2147. The following signals affect the execution of
  2148. .Nm :
  2149. .Bl -tag -width "SIGQUITXXX"
  2150. .It Dv SIGINT
  2151. If a shell is interactive
  2152. and in command line editing mode,
  2153. editing is terminated on the current line
  2154. and the command being edited is not entered into command history.
  2155. Otherwise the signal is caught
  2156. but no action is taken.
  2157. .It Dv SIGQUIT
  2158. Ignored if a shell is interactive.
  2159. .It Dv SIGTERM
  2160. Ignored if a shell is interactive.
  2161. .It Dv SIGTSTP
  2162. Ignored if a shell is interactive
  2163. and the
  2164. .Ic monitor
  2165. option
  2166. .Pq Fl m
  2167. is set.
  2168. .It Dv SIGTTIN
  2169. Ignored if a shell is interactive
  2170. and the
  2171. .Ic monitor
  2172. option
  2173. .Pq Fl m
  2174. is set.
  2175. .It Dv SIGTTOU
  2176. Ignored if a shell is interactive
  2177. and the
  2178. .Ic monitor
  2179. option
  2180. .Pq Fl m
  2181. is set.
  2182. .El
  2183. .Sh EXIT STATUS
  2184. The
  2185. .Nm
  2186. utility exits with one of:
  2187. .Bl -tag -width "1-125"
  2188. .It 0
  2189. The script being executed contained only blank lines or comments.
  2190. .It 1\(en125
  2191. A non-interactive shell detected an error other than
  2192. .Ar file
  2193. not found.
  2194. .It 126
  2195. A command was found but was not executable.
  2196. .It 127
  2197. A non-interactive shell returned
  2198. .Ar file
  2199. not found.
  2200. .El
  2201. .Pp
  2202. Otherwise
  2203. .Nm
  2204. returns the exit status of the last command it invoked.
  2205. .Sh SEE ALSO
  2206. .Xr csh 1 ,
  2207. .Xr ed 1 ,
  2208. .Xr ksh 1 ,
  2209. .Xr vi 1 ,
  2210. .Xr script 7
  2211. .Sh STANDARDS
  2212. The
  2213. .Nm
  2214. utility is compliant with the
  2215. .St -p1003.1-2008
  2216. specification,
  2217. except where noted below:
  2218. .Bl -dash
  2219. .It
  2220. The flag
  2221. .Op Fl h
  2222. is documented by POSIX as hashing
  2223. .Qq utilities invoked by functions as those functions are defined ;
  2224. this implementation hashes utilities after first invocation
  2225. (and functions be damned).
  2226. .It
  2227. POSIX says mail notifications via
  2228. .Ev MAIL
  2229. and
  2230. .Ev MAILPATH
  2231. should happen if a file is created,
  2232. as well as if its modification time changes.
  2233. This implementation of
  2234. .Nm
  2235. does not provide notification when these files are created.
  2236. .It
  2237. The built-in
  2238. .Ic newgrp
  2239. is unsupported.
  2240. .It
  2241. The
  2242. .Ic break
  2243. and
  2244. .Ic continue
  2245. built-ins should exit/return from the outermost loop if the argument
  2246. .Ar n
  2247. is greater than the level of loops.
  2248. .It
  2249. The default value for the
  2250. .Ev PS1
  2251. user prompt contains the machine's hostname,
  2252. followed by
  2253. .Sq $\ \&
  2254. for normal users and
  2255. .Sq #\ \&
  2256. for root;
  2257. POSIX does not include the hostname.
  2258. .El
  2259. .Pp
  2260. Enabling POSIX mode changes some behaviour to make
  2261. .Nm
  2262. adhere more strictly to the
  2263. .St -p1003.1-2008
  2264. specification.