initial population

1 files changed, 4549 insertions, 0 deletions

diff --git a/bin/sh/sh.1 b/bin/sh/sh.1
new file mode 100644
index 0000000..4630689
--- /dev/null
+++ b/bin/sh/sh.1
@@ -0,0 +1,4549 @@
+.\"	$NetBSD: sh.1,v 1.217 2019/01/21 14:09:24 kre Exp $
+.\" Copyright (c) 1991, 1993
+.\"	The Regents of the University of California.  All rights reserved.
+.\"
+.\" This code is derived from software contributed to Berkeley by
+.\" Kenneth Almquist.
+.\"
+.\" Redistribution and use in source and binary forms, with or without
+.\" modification, are permitted provided that the following conditions
+.\" are met:
+.\" 1. Redistributions of source code must retain the above copyright
+.\"    notice, this list of conditions and the following disclaimer.
+.\" 2. Redistributions in binary form must reproduce the above copyright
+.\"    notice, this list of conditions and the following disclaimer in the
+.\"    documentation and/or other materials provided with the distribution.
+.\" 3. Neither the name of the University nor the names of its contributors
+.\"    may be used to endorse or promote products derived from this software
+.\"    without specific prior written permission.
+.\"
+.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
+.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
+.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
+.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
+.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
+.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
+.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
+.\" SUCH DAMAGE.
+.\"
+.\"	@(#)sh.1	8.6 (Berkeley) 5/4/95
+.\"
+.Dd December 12, 2018
+.Dt SH 1
+.\" everything except c o and s (keep them ordered)
+.ds flags abCEeFfhIiLmnpquVvXx
+.Os
+.Sh NAME
+.Nm sh
+.Nd command interpreter (shell)
+.Sh SYNOPSIS
+.Nm
+.Bk -words
+.Op Fl \*[flags]
+.Op Cm +\*[flags]
+.Ek
+.Bk -words
+.Op Fl o Ar option_name
+.Op Cm +o Ar option_name
+.Ek
+.Bk -words
+.Op Ar command_file Op Ar argument ...
+.Ek
+.Nm
+.Fl c
+.Bk -words
+.Op Fl s
+.Op Fl \*[flags]
+.Op Cm +\*[flags]
+.Ek
+.Bk -words
+.Op Fl o Ar option_name
+.Op Cm +o Ar option_name
+.Ek
+.Bk -words
+.Ar command_string
+.Op Ar command_name Op Ar argument ...
+.Ek
+.Nm
+.Fl s
+.Bk -words
+.Op Fl \*[flags]
+.Op Cm +\*[flags]
+.Ek
+.Bk -words
+.Op Fl o Ar option_name
+.Op Cm +o Ar option_name
+.Ek
+.Bk -words
+.Op Ar argument ...
+.Ek
+.Sh DESCRIPTION
+.Nm
+is the standard command interpreter for the system.
+The current version of
+.Nm
+is in the process of being changed to conform more closely to the
+POSIX 1003.2 and 1003.2a specifications for the shell.
+This version has many
+features which make it appear similar in some respects to the Korn shell,
+but it is not a Korn shell clone (see
+.Xr ksh 1 ) .
+This man page is not intended
+to be a tutorial or a complete specification of the shell.
+.Ss Overview
+The shell is a command that reads lines from either a file or the
+terminal, interprets them, and generally executes other commands.
+A shell is the program that is running when a user logs into the system.
+(Users can select which shell is executed for them at login with the
+.Xr chsh 1
+command).
+The shell implements a language that has flow control
+constructs, a macro facility that provides a variety of features in
+addition to data storage, along with built in history and line editing
+capabilities.
+It incorporates many features to aid interactive use and
+has the advantage that the interpretative language is common to both
+interactive and non-interactive use (shell scripts).
+That is, commands
+can be typed directly to the running shell or can be put into a file and
+the file can be executed directly by the shell.
+.Ss Invocation
+If no arguments are present and if the standard input,
+and standard error output, of the shell
+are connected to a terminal (or terminals, or if the
+.Fl i
+flag is set),
+and the
+.Fl c
+option is not present, the shell is considered an interactive shell.
+An interactive shell generally prompts before each command and handles
+programming and command errors differently (as described below).
+When first starting,
+the shell inspects argument 0, and if it begins with a dash
+.Sq - ,
+the shell is also considered
+a login shell.
+This is normally done automatically by the system
+when the user first logs in.
+A login shell first reads commands
+from the files
+.Pa /etc/profile
+and
+.Pa .profile
+in the user's home directory
+.Pq \&$HOME ,
+if they exist.
+If the environment variable
+.Ev ENV
+is set on entry to a shell,
+or is set in the
+.Pa .profile
+of a login shell,
+and either the shell is interactive, or the
+.Cm posix
+option is not set,
+the shell then performs parameter and arithmetic
+expansion on the value of
+.Ev ENV ,
+(these are described later)
+and then reads commands from the file name that results.
+If
+.Ev ENV
+contains a command substitution, or one of the
+other expansions fails, or if there are no expansions
+to expand, the value of
+.Ev ENV
+is used as the file name.
+.Pp
+Therefore, a user should place commands that are to be executed only at
+login time in the
+.Pa .profile
+file, and commands that are executed for every shell inside the
+.Ev ENV
+file.
+To set the
+.Ev ENV
+variable to some file, place the following line in your
+.Pa .profile
+of your home directory
+.Pp
+.Dl ENV=$HOME/.shinit; export ENV
+.Pp
+substituting for
+.Dq .shinit
+any filename you wish.
+Since the
+.Ev ENV
+file can be read for every invocation of the shell, including shell scripts
+and non-interactive shells, the following paradigm is useful for
+restricting commands in the
+.Ev ENV
+file to interactive invocations.
+Place commands within the
+.Dq Ic case
+and
+.Dq Ic esac
+below (these commands are described later):
+.Bd -literal -offset indent
+case $- in *i*)
+        # commands for interactive use only
+        ...
+esac
+.Ed
+.Pp
+If command line arguments besides the options have been specified, and
+neither
+.Fl c
+nor
+.Fl s
+was given, then the shell treats the first argument
+as the name of a file from which to read commands (a shell script).
+This also becomes
+.Li $0
+and the remaining arguments are set as the
+positional parameters of the shell
+.Li ( $1 , $2 ,
+etc).
+Otherwise, if
+.Fl c
+was given, then the first argument, which must exist,
+is taken to be a string of
+.Nm
+commands to execute.
+Then if any additional arguments follow the command string,
+those arguments become
+.Li $0 , $1 ,
+\&...
+Otherwise, if additional arguments were given
+(which implies that
+.Fl s
+was set)
+those arguments become
+.Li $1 , $2 ,
+\&...
+If
+.Li $0
+has not been set by the preceding processing, it
+will be set to
+.Va argv\^ Ns [ 0 ]
+as passed to the shell, which will
+usually be the name of the shell itself.
+If
+.Fl s
+was given, or if neither
+.Fl c
+nor any additional (non-option) arguments were present,
+the shell reads commands from its standard input.
+.\"
+.\"
+.Ss Argument List Processing
+.\"
+Currently, all of the single letter options that can meaningfully
+be set using the
+.Ic set
+built-in, have a corresponding name
+that can be used as an argument to the
+.Fl o
+option.
+The
+.Ic set Fl o
+name is provided next to the single letter option in
+the description below.
+Some options have only a long name, they are described after
+the flag options, they are used with
+.Fl o
+or
+.Cm +o
+only, either on the command line, or with the
+.Ic set
+built-in command.
+Other options described are for the command line only.
+Specifying a dash
+.Dq Cm \-
+turns the option on, while using a plus
+.Dq Cm +
+disables the option.
+The following options can be set from the command line and,
+unless otherwise stated, with the
+.Ic set
+built-in (described later).
+.\"
+.\" strlen("quietprofile") == strlen("local_lineno"): pick the latter
+.\" to give the indent as the _ in local_lineno, and the fi ligature in
+.\" quietprofile combine to make "local_lineno' slightly wider when printed
+.\" (in italics) in a variable width font.
+.Bl -tag -width ".Fl L Em local_lineno" -offset indent
+.\"
+.It Fl a Em allexport
+Automatically export any variable to which a value is assigned
+while this flag is set, unless the variable has been marked as
+not for export.
+.It Fl b Em notify
+Enable asynchronous notification of background job completion.
+(Not implemented.)
+.It Fl C Em noclobber
+Don't overwrite existing files with
+.Dq > .
+.It Fl c
+Read commands from the
+.Ar command_string
+operand instead of, or in addition to, from the standard input.
+Special parameter
+.Dv 0 \" $0	(comments like this for searching sources only)
+will be set from the
+.Ar command_name
+operand if given, and the positional parameters
+.Dv ( 1 , 2 ,
+etc.)
+set from the remaining argument operands, if any.
+.Fl c
+is only available at invocation, it cannot be
+.Ic set ,
+and there is no form using
+.Dq Cm \&+ .
+.It Fl E Em emacs
+Enable the built-in emacs style
+command line editor (disables
+.Fl V
+if it has been set).
+(See the
+.Sx Command Line Editing
+section below.)
+.It Fl e Em errexit
+If not interactive, exit immediately if any untested command fails.
+If interactive, and an untested command fails,
+cease all processing of the current command and return to
+prompt for a new command.
+The exit status of a command is considered to be
+explicitly tested if the command is used to control an
+.Ic if ,
+.Ic elif ,
+.Ic while ,
+or
+.Ic until ,
+or if the command is the left hand operand of an
+.Dq &&
+or
+.Dq ||
+operator,
+or if it is a pipeline (or simple command) preceded by the
+.Dq \&!
+operator.
+With pipelines, only the status of the entire pipeline
+(indicated by the last command it contains)
+is tested when
+.Fl e
+is set to determine if the shell should exit.
+.It Fl F Em fork
+Cause the shell to always use
+.Xr fork 2
+instead of attempting
+.Xr vfork 2
+when it needs to create a new process.
+This should normally have no visible effect,
+but can slow execution.
+The
+.Nm
+can be compiled to always use
+.Xr fork 2
+in which case altering the
+.Fl F
+flag has no effect.
+.It Fl f Em noglob
+Disable pathname expansion.
+.It Fl h Em trackall
+Functions defined while this option is set will have paths bound to
+commands to be executed by the function at the time of the definition.
+When off when a function is defined,
+the file system is searched for commands each time the function is invoked.
+(Not implemented.)
+.It Fl I Em ignoreeof
+Ignore EOFs from input when interactive.
+(After a large number of consecutive EOFs the shell will exit anyway.)
+.It Fl i Em interactive
+Force the shell to behave interactively.
+.It Fl L Em local_lineno
+When set, before a function is defined,
+causes the variable
+.Dv LINENO
+when used within the function,
+to refer to the line number defined such that
+first line of the function is line 1.
+When reset,
+.Dv LINENO
+in a function refers to the line number within the file
+within which the definition of the function occurs.
+This option defaults to
+.Dq on
+in this shell.
+For more details see the section
+.Sx LINENO
+below.
+.It Fl m Em monitor
+Turn on job control (set automatically when interactive).
+.It Fl n Em noexec
+Read and parse commands, but do not execute them.
+This is useful for checking the syntax of shell scripts.
+If
+.Fl n
+becomes set in an interactive shell, it will automatically be
+cleared just before the next time the command line prompt
+.Pq Ev PS1
+is written.
+.It Fl p Em nopriv
+Do not attempt to reset effective UID if it does not match UID.
+This is not set by default to help avoid incorrect usage by setuid
+root programs via
+.Xr system 3
+or
+.Xr popen 3 .
+.It Fl q Em quietprofile
+If the
+.Fl v
+or
+.Fl x
+options have been set, do not apply them when reading
+initialization files, these being
+.Pa /etc/profile ,
+.Pa .profile ,
+and the file specified by the
+.Ev ENV
+environment variable.
+.It Fl s Em stdin
+Read commands from standard input (set automatically if
+neither
+.Fl c
+nor file arguments are present).
+If after processing a command_string with the
+.Fl c
+option, the shell has not exited, and the
+.Fl s
+option is set, it will continue reading more commands from standard input.
+This option has no effect when set or reset after the shell has
+already started reading from the command_file, or from standard input.
+Note that the
+.Fl s
+flag being set does not cause the shell to be interactive.
+.It Fl u Em nounset
+Write a message to standard error when attempting to obtain a
+value from a variable that is not set,
+and if the shell is not interactive, exit immediately.
+For interactive shells, instead return immediately to the command prompt
+and read the next command.
+Note that expansions (described later, see
+.Sx Word Expansions
+below) using the
+.Sq \&+ ,
+.Sq \&\- ,
+.Sq \&= ,
+or
+.Sq \&?
+operators test if the variable is set, before attempting to
+obtain its value, and hence are unaffected by
+.Fl u .
+.It Fl V Em vi
+Enable the built-in
+.Xr vi 1
+command line editor (disables
+.Fl E
+if it has been set).
+(See the
+.Sx Command Line Editing
+section below.)
+.It Fl v Em verbose
+The shell writes its input to standard error as it is read.
+Useful for debugging.
+.It Fl X Em xlock
+Cause output from the
+.Ic xtrace
+.Pq Fl x
+option to be sent to standard error as it exists when the
+.Fl X
+option is enabled (regardless of its previous state.)
+For example:
+.Bd -literal -compact
+        set -X 2>/tmp/trace-file
+.Ed
+will arrange for tracing output to be sent to the file named,
+instead of wherever it was previously being sent,
+until the X option is set again, or cleared.
+.Pp
+Each change (set or clear) to
+.Fl X
+is also performed upon
+.Fl x ,
+but not the converse.
+.It Fl x Em xtrace
+Write each command to standard error (preceded by the expanded value of
+.Li $PS4 )
+before it is executed.
+Unless
+.Fl X
+is set,
+.Dq "standard error"
+means that which existed immediately before any redirections to
+be applied to the command are performed.
+Useful for debugging.
+.It "\ \ " Em cdprint
+Make an interactive shell always print the new directory name when
+changed by the
+.Ic cd
+command.
+In a non-interactive shell this option has no effect.
+.It "\ \ " Em nolog
+Prevent the entry of function definitions into the command history (see
+.Ic fc
+in the
+.Sx Built-ins
+section.)
+(Not implemented.)
+.It "\ \ " Em pipefail
+If set when a pipeline is created,
+the way the exit status of the pipeline is determined
+is altered.
+See
+.Sx Pipelines
+below for the details.
+.It "\ \ " Em posix
+Enables closer adherence to the POSIX shell standard.
+This option will default set at shell startup if the
+environment variable
+.Ev POSIXLY_CORRECT
+is present.
+That can be overridden (set or reset) by the
+.Fl o
+option on the command line.
+Currently this option controls whether (!posix) or not (posix)
+the file given by the
+.Ev ENV
+variable is read at startup by a non-interactive shell.
+It also controls whether file descriptors greater than 2
+opened using the
+.Ic exec
+built-in command are passed on to utilities executed
+.Dq ( yes
+in posix mode),
+whether a colon (:) terminates the user name in tilde (~) expansions
+other than in assignment statements
+.Dq ( no
+in posix mode),
+the format of the output of the
+.Ic kill Fl l
+command, where posix mode causes the names of the signals
+be separated by either a single space or newline, and where otherwise
+sufficient spaces are inserted to generate nice looking columns,
+and whether the shell treats
+an empty brace-list compound statement as a syntax error
+(expected by POSIX) or permits it.
+Such statements
+.Dq "{\ }"
+can be useful when defining dummy functions.
+Lastly, in posix mode, only one
+.Dq \&!
+is permitted before a pipeline.
+.It "\ \ " Em promptcmds
+Allows command substitutions (as well as parameter
+and arithmetic expansions, which are always performed)
+upon the prompt strings
+.Ev PS1 ,
+.Ev PS2 ,
+and
+.Ev PS4
+each time, before they are output.
+This option should not be set until after the prompts
+have been set (or verified) to avoid accidentally importing
+unwanted command substitutions from the environment.
+.It "\ \ " Em tabcomplete
+Enables filename completion in the command line editor.
+Typing a tab character will extend the current input word to match a
+filename.
+If more than one filename matches it is only extended to be the common prefix.
+Typing a second tab character will list all the matching names.
+One of the editing modes, either
+.Fl E
+or
+.Fl V ,
+must be enabled for this to work.
+.El
+.Ss Lexical Structure
+The shell reads input in terms of lines from a file and breaks it up into
+words at whitespace (blanks and tabs), and at certain sequences of
+characters that are special to the shell called
+.Dq operators .
+There are two types of operators: control operators and redirection
+operators (their meaning is discussed later).
+The following is a list of operators:
+.Bl -ohang -offset indent
+.It "Control operators:"
+.Dl &  &&  \&(  \&)  \&;  ;; ;& \&| || <newline>
+.It "Redirection operators:"
+.Dl <  >  >|  <<  >>  <&  >&  <<-  <>
+.El
+.Ss Quoting
+Quoting is used to remove the special meaning of certain characters or
+words to the shell, such as operators, whitespace, or keywords.
+There are four types of quoting:
+matched single quotes,
+matched double quotes,
+backslash,
+and
+dollar preceding matched single quotes (enhanced C style strings.)
+.Ss Backslash
+An unquoted backslash preserves the literal meaning of the following
+character, with the exception of
+.Aq newline .
+An unquoted backslash preceding a
+.Aq newline
+is treated as a line continuation, the two characters are simply removed.
+.Ss Single Quotes
+Enclosing characters in single quotes preserves the literal meaning of all
+the characters (except single quotes, making it impossible to put
+single quotes in a single-quoted string).
+.Ss Double Quotes
+Enclosing characters within double quotes preserves the literal
+meaning of all characters except dollar sign
+.Pq Li \&$ ,
+backquote
+.Pq Li \&` ,
+and backslash
+.Pq Li \e .
+The backslash inside double quotes is historically weird, and serves to
+quote only the following characters (and these not in all contexts):
+.Dl $  `  \*q  \e  <newline> ,
+where a backslash newline is a line continuation as above.
+Otherwise it remains literal.
+.\"
+.\"
+.Ss Dollar Single Quotes ( Li \&$'...' )
+.\"
+.Bd -filled -offset indent
+.Bf Em
+Note: this form of quoting is still somewhat experimental,
+and yet to be included in the POSIX standard.
+This implementation is based upon the current proposals for
+standardization, and is subject to change should the eventual
+adopted text differ.
+.Ef
+.Ed
+.Pp
+Enclosing characters in a matched pair of single quotes, with the
+first immediately preceded by an unquoted dollar sign
+.Pq Li \&$
+provides a quoting mechanism similar to single quotes, except
+that within the sequence of characters, any backslash
+.Pq Li \e ,
+is an escape character, which causes the following character to
+be treated specially.
+Only a subset of the characters that can occur in the string
+are defined after a backslash, others are reserved for future
+definition, and currently generate a syntax error if used.
+The escape sequences are modeled after the similar sequences
+in strings in the C programming language, with some extensions.
+.Pp
+The following characters are treated literally when following
+the escape character (backslash):
+.Dl \e \&' \(dq
+The sequence
+.Dq Li \e\e
+allows the escape character (backslash) to appear in the string literally.
+.Dq Li \e'
+allows a single quote character into the string, such an
+escaped single quote does not terminate the quoted string.
+.Dq Li \e\(dq
+is for compatibility with C strings, the double quote has
+no special meaning in a shell C-style string,
+and does not need to be escaped, but may be.
+.Pp
+A newline following the escape character is treated as a line continuation,
+like the same sequence in a double quoted string,
+or when not quoted \(en
+the two characters, the backslash escape and the newline,
+are removed from the input string.
+.Pp
+The following characters, when escaped, are converted in a
+manner similar to the way they would be in a string in the C language:
+.Dl a b e f n r t v
+An escaped
+.Sq a
+generates an alert (or
+.Sq BEL )
+character, that is, control-G, or 0x07.
+In a similar way,
+.Sq b
+is backspace (0x08),
+.Sq e
+(an extension to C) is escape (0x1B),
+.Sq f
+is form feed (0x0C),
+.Sq n
+is newline (or line feed, 0x0A),
+.Sq r
+is return (0x0D),
+.Sq t
+is horizontal tab (0x09),
+and
+.Sq v
+is vertical tab (0x13).
+.Pp
+In addition to those there are 5 forms that need additional
+data, which is obtained from the subsequent characters.
+An escape
+.Pq Li \e
+followed by one, two or three, octal digits
+.Po So 0 Sc Ns \&.. Ns So 7 Sc Ns Pc
+is processed to form an 8 bit character value.
+If only one or two digits are present, the following
+character must be something other than an octal digit.
+It is safest to always use all 3 digits, with leading
+zeros if needed.
+If all three digits are present, the first must be one of
+.So 0 Sc Ns \&.. Ns So 3 Sc .
+.Pp
+An escape followed by
+.Sq x
+(lower case only) can be followed by one or two
+hexadecimal digits
+.Po So 0 Sc Ns \&.. Ns So 9 Sc , So A Sc Ns \&.. Ns So F Sc , or So a Sc Ns \&.. Ns So f Sc . Pc
+As with octal, if only one hex digit is present, the following
+character must be something other than a hex digit,
+so always giving 2 hex digits is best.
+However, unlike octal, it is unspecified in the standard
+how many hex digits can be consumed.
+This
+.Nm
+takes at most two, but other shells will continue consuming
+characters as long as they remain valid hex digits.
+Consequently, users should ensure that the character
+following the hex escape sequence is something other than
+a hex digit.
+One way to achieve this is to end the
+.Li $'...'
+string immediately
+after the final hex digit, and then, immediately start
+another, so
+.Dl \&$'\ex33'$'4...'
+always gives the character with value 0x33
+.Pq Sq 3 ,
+followed by the character
+.Sq 4 ,
+whereas
+.Dl \&$'\ex334'
+in some other shells would be the hex value 0x334 (10, or more, bits).
+.Pp
+There are two escape sequences beginning with
+.Sq Li \eu
+or
+.Sq Li \eU .
+The former is followed by from 1 to 4 hex digits, the latter by
+from 1 to 8 hex digits.
+Leading zeros can be used to pad the sequences to the maximum
+permitted length, to avoid any possible ambiguity problem with
+the following character, and because there are some shells that
+insist on exactly 4 (or 8) hex digits.
+These sequences are evaluated to form the value of a Unicode code
+point, which is then encoded into UTF-8 form, and entered into the
+string.
+(The code point should be converted to the appropriate
+code point value for the corresponding character in the character
+set given by the current locale, or perhaps the locale in use
+when the shell was started, but is not... currently.)
+Not all values that are possible to write are valid, values that
+specify (known) invalid Unicode code points will be rejected, or
+simply produce
+.Sq \&? .
+.Pp
+Lastly, as another addition to what is available in C, the escape
+character (backslash), followed by
+.Sq c
+(lower case only) followed by one additional character, which must
+be an alphabetic character (a letter), or one of the following:
+.Dl \&@ \&[ \&\e \&] \&^ \&_ \&?
+Other than
+.Sq Li \ec?
+the value obtained is the least significant 5 bits of the
+ASCII value of the character following the
+.Sq Li \ec
+escape sequence.
+That is what is commonly known as the
+.Dq control
+character obtained from the given character.
+The escape sequence
+.Sq Li \ec?
+yields the ASCII DEL character (0x7F).
+Note that to obtain the ASCII FS character (0x1C) this way,
+.Pq "that is control-\e"
+the trailing
+.Sq Li \e
+must be escaped itself, and so for this one case, the full
+escape sequence is
+.Dq Li \ec\e\e .
+The sequence
+.Dq Li \ec\e Ns Ar X\^
+where
+.Sq Ar X\^
+is some character other than
+.Sq Li \e
+is reserved for future use, its meaning is unspecified.
+In this
+.Nm
+an error is generated.
+.Pp
+If any of the preceding escape sequences generate the value
+.Sq \e0
+(a NUL character) that character, and all that follow in the same
+.Li $'...'
+string, are omitted from the resulting word.
+.Pp
+After the
+.Li $'...'
+string has had any included escape sequences
+converted, it is treated as if it had been a single quoted string.
+.\"
+.\"
+.Ss Reserved Words
+.\"
+Reserved words are words that have special meaning to the
+shell and are recognized at the beginning of a line and
+after a control operator.
+The following are reserved words:
+.Bl -column while while while while -offset indent
+.It Ic \&! Ta Ic \&{ Ta Ic \&} Ta Ic case
+.It Ic do Ta Ic done Ta Ic elif Ta Ic else
+.It Ic esac Ta Ic fi Ta Ic for Ta Ic if
+.It Ic in Ta Ic then Ta Ic until Ta Ic while
+.El
+.Pp
+Their meanings are discussed later.
+.\"
+.\"
+.Ss Aliases
+.\"
+An alias is a name and corresponding value set using the
+.Ic alias
+built-in command.
+Whenever a reserved word (see above) may occur,
+and after checking for reserved words, the shell
+checks the word to see if it matches an alias.
+If it does, it replaces it in the input stream with its value.
+For example, if there is an alias called
+.Dq lf
+with the value
+.Dq "ls -F" ,
+then the input:
+.Pp
+.Dl lf foobar Aq return
+.Pp
+would become
+.Pp
+.Dl ls -F foobar Aq return
+.Pp
+Aliases provide a convenient way for naive users to create shorthands for
+commands without having to learn how to create functions with arguments.
+They can also be used to create lexically obscure code.
+This use is strongly discouraged.
+.\"
+.Ss Commands
+.\"
+The shell interprets the words it reads according to a language, the
+specification of which is outside the scope of this man page (refer to the
+BNF in the POSIX 1003.2 document).
+Essentially though, a line is read and if the first
+word of the line (or after a control operator) is not a reserved word,
+then the shell has recognized a simple command.
+Otherwise, a complex
+command or some other special construct may have been recognized.
+.\"
+.\"
+.Ss Simple Commands
+.\"
+If a simple command has been recognized, the shell performs
+the following actions:
+.Bl -enum -offset indent
+.It
+Leading words of the form
+.Dq Ar name Ns Li = Ns Ar value
+are stripped off, the value is expanded, as described below,
+and the results are assigned to the environment of the simple command.
+Redirection operators and their arguments (as described below) are
+stripped off and saved for processing in step 3 below.
+.It
+The remaining words are expanded as described in the
+.Sx Word Expansions
+section below.
+The first remaining word is considered the command name and the
+command is located.
+Any remaining words are considered the arguments of the command.
+If no command name resulted, then the
+.Dq Ar name Ns Li = Ns Ar value
+variable assignments recognized in item 1 affect the current shell.
+.It
+Redirections are performed, from first to last, in the order given,
+as described in the next section.
+.El
+.\"
+.\"
+.Ss Redirections
+.\"
+Redirections are used to change where a command reads its input or sends
+its output.
+In general, redirections open, close, or duplicate an
+existing reference to a file.
+The overall format used for redirection is:
+.Pp
+.Dl Oo Ar n Oc Ns Va redir-op Ar file
+.Pp
+where
+.Va redir-op
+is one of the redirection operators mentioned previously.
+The following is a list of the possible redirections.
+The
+.Op Ar n
+is an optional number, as in
+.Sq Li 3
+(not
+.Li [3] ) ,
+that refers to a file descriptor.
+If present it must occur immediately before the redirection
+operator, with no intervening white space, and becomes a
+part of that operator.
+.Bl -tag -width aaabsfiles -offset indent
+.It Oo Ar n Oc Ns Ic > Ar file
+Redirect standard output (or
+.Ar n )
+to
+.Ar file .
+.It Oo Ar n Oc Ns Ic >| Ar file
+The same, but override the
+.Fl C
+option.
+.It Oo Ar n Oc Ns Ic >> Ar file
+Append standard output (or
+.Ar n )
+to
+.Ar file .
+.It Oo Ar n Oc Ns Ic < Ar file
+Redirect standard input (or
+.Ar n )
+from
+.Ar file .
+.It Oo Ar n1 Oc Ns Ic <& Ns Ar n2
+Duplicate standard input (or
+.Ar n1 )
+from file descriptor
+.Ar n2 .
+.Ar n2
+is expanded if not a digit string, the result must be a number.
+.It Oo Ar n Oc Ns Ic <&-
+Close standard input (or
+.Ar n ) .
+.It Oo Ar n1 Oc Ns Ic >& Ns Ar n2
+Duplicate standard output (or
+.Ar n1 )
+to
+.Ar n2 .
+.It Oo Ar n Oc Ns Ic >&-
+Close standard output (or
+.Ar n ) .
+.It Oo Ar n Oc Ns Ic <> Ar file
+Open
+.Ar file
+for reading and writing on standard input (or
+.Ar n ) .
+.El
+.Pp
+The following redirection is often called a
+.Dq here-document .
+.Bd -unfilled -offset indent
+.Oo Ar n Oc Ns Ic << Ar delimiter
+.Li \&... here-doc-text ...
+.Ar delimiter
+.Ed
+.Pp
+The
+.Dq here-doc-text
+starts immediately after the next unquoted newline character following
+the here-document redirection operator.
+If there is more than one here-document redirection on the same
+line, then the text for the first (from left to right) is read
+first, and subsequent here-doc-text for later here-document redirections
+follows immediately after, until all such redirections have been
+processed.
+.Pp
+All the text on successive lines up to the delimiter,
+which must appear on a line by itself, with nothing other
+than an immediately following newline, is
+saved away and made available to the command on standard input, or file
+descriptor n if it is specified.
+If the delimiter as specified on the initial line is
+quoted, then the here-doc-text is treated literally; otherwise, the text is
+treated much like a double quoted string, except that
+.Sq Li \(dq
+characters have no special meaning, and are not escaped by
+.Sq Li \&\e ,
+and is subjected to parameter expansion, command substitution, and arithmetic
+expansion as described in the
+.Sx Word Expansions
+section below.
+If the operator is
+.Ic <<-
+instead of
+.Ic << ,
+then leading tabs in all lines in the here-doc-text, including before the
+end delimiter, are stripped.
+If the delimiter is not quoted, lines in here-doc-text that end with
+an unquoted
+.Li \e
+are joined to the following line, the
+.Li \e
+and following
+newline are simply removed while reading the here-document,
+which thus guarantees
+that neither of those lines can be the end delimiter.
+.Pp
+It is a syntax error for the end of the input file (or string) to be
+reached before the delimiter is encountered.
+.\"
+.\"
+.Ss Search and Execution
+.\"
+There are three types of commands: shell functions, built-in commands, and
+normal programs \(em and the command is searched for (by name) in that order.
+A command that contains a slash
+.Sq \&/
+in its name is always a normal program.
+They each are executed in a different way.
+.Pp
+When a shell function is executed, all of the shell positional parameters
+(note: excluding
+.Li 0 , \" $0
+which is a special, not positional, parameter, and remains unchanged)
+are set to the arguments of the shell function.
+The variables which are explicitly placed in the environment of
+the command (by placing assignments to them before the function name) are
+made local to the function and are set to the values given,
+and exported for the benefit of programs executed with the function.
+Then the command given in the function definition is executed.
+The positional parameters, and local variables, are restored to
+their original values when the command completes.
+This all occurs within the current shell, and the function
+can alter variables, or other settings, of the shell, but
+not the positional parameters nor their related special parameters.
+.Pp
+Shell built-ins are executed internally to the shell, without spawning a
+new process.
+.Pp
+Otherwise, if the command name doesn't match a function or built-in, the
+command is searched for as a normal program in the file system (as
+described in the next section).
+When a normal program is executed, the shell runs the program,
+passing the arguments and the environment to the program.
+If the program is not a normal executable file, and if it does
+not begin with the
+.Dq magic number
+whose ASCII representation is
+.Dq Li "#!" ,
+so
+.Xr execve 2
+returns
+.Er ENOEXEC
+then) the shell will interpret the program in a sub-shell.
+The child shell will reinitialize itself in this case,
+so that the effect will be as if a
+new shell had been invoked to handle the ad-hoc shell script, except that
+the location of hashed commands located in the parent shell will be
+remembered by the child.
+.Pp
+Note that previous versions of this document and the source code itself
+misleadingly and sporadically refer to a shell script without a magic
+number as a
+.Dq shell procedure .
+.\"
+.\"
+.Ss Path Search
+.\"
+When locating a command, the shell first looks to see if it has a shell
+function by that name.
+Then it looks for a built-in command by that name.
+If a built-in command is not found, one of two things happen:
+.Bl -enum
+.It
+Command names containing a slash are simply executed without performing
+any searches.
+.It
+Otherwise, the shell searches each entry in
+.Ev PATH
+in turn for the command.
+The value of the
+.Ev PATH
+variable should be a series of entries separated by colons.
+Each entry consists of a directory name.
+The current directory may be indicated
+implicitly by an empty directory name, or explicitly by a single period.
+If a directory searched contains an executable file with the same
+name as the command given,
+the search terminates, and that program is executed.
+.El
+.Ss Command Exit Status
+Each command has an exit status that can influence the behavior
+of other shell commands.
+The paradigm is that a command exits
+with zero in normal cases, or to indicate success,
+and non-zero for failure,
+error, or a false indication.
+The man page for each command
+should indicate the various exit codes and what they mean.
+Additionally, the built-in commands return exit codes, as does
+an executed shell function.
+.Pp
+If a command consists entirely of variable assignments then the
+exit status of the command is that of the last command substitution
+if any, otherwise 0.
+.Pp
+If redirections are present, and any fail to be correctly performed,
+any command present is not executed, and an exit status of 2
+is returned.
+.Ss Complex Commands
+Complex commands are combinations of simple commands with control
+operators or reserved words, together creating a larger complex command.
+Overall, a shell program is a:
+.Bl -tag -width XpipelineX
+.It list
+Which is a sequence of one or more AND-OR lists.
+.It "AND-OR list"
+is a sequence of one or more pipelines.
+.It pipeline
+is a sequence of one or more commands.
+.It command
+is one of a simple command, a compound command, or a function definition.
+.It "simple command"
+has been explained above, and is the basic building block.
+.It "compound command"
+provides mechanisms to group lists to achieve different effects.
+.It "function definition"
+allows new simple commands to be created as groupings of existing commands.
+.El
+.Pp
+Unless otherwise stated, the exit status of a list
+is that of the last simple command executed by the list.
+.\"
+.\"
+.Ss Pipelines
+.\"
+A pipeline is a sequence of one or more commands separated
+by the control operator
+.Sq Ic \(ba ,
+and optionally preceded by the
+.Dq Ic \&!
+reserved word.
+Note that
+.Sq Ic \(ba
+is an operator, and so is recognized anywhere it appears unquoted,
+it does not require surrounding white space or other syntax elements.
+On the other hand
+.Dq Ic \&!
+being a reserved word, must be separated from adjacent words by
+white space (or other operators, perhaps redirects) and is only
+recognized as the reserved word when it appears in a command word
+position (such as at the beginning of a pipeline.)
+.Pp
+The standard output of all but
+the last command in the sequence is connected to the standard input
+of the next command.
+The standard output of the last
+command is inherited from the shell, as usual,
+as is the standard input of the first command.
+.Pp
+The format for a pipeline is:
+.Pp
+.Dl [!] command1 Op Li \&| command2 No ...
+.Pp
+The standard output of command1 is connected to the standard input of
+command2.
+The standard input, standard output, or both of each command is
+considered to be assigned by the pipeline before any redirection specified
+by redirection operators that are part of the command are performed.
+.Pp
+If the pipeline is not in the background (discussed later), the shell
+waits for all commands to complete.
+.Pp
+The commands in a pipeline can either be simple commands,
+or one of the compound commands described below.
+The simplest case of a pipeline is a single simple command.
+.Pp
+If the
+.Ic pipefail
+option was set when a pipeline was started,
+the pipeline status is the status of
+the last (lexically last, i.e.: rightmost) command in the
+pipeline to exit with non-zero exit status, or zero, if,
+and only if, all commands in the pipeline exited with a status of zero.
+If the
+.Ic pipefail
+option was not set, which is the default state,
+the pipeline status is the exit
+status of the last (rightmost) command in the pipeline,
+and the exit status of any other commands in the pipeline is ignored.
+.Pp
+If the reserved word
+.Dq Ic \&!
+precedes the pipeline, the exit status
+becomes the logical NOT of the pipeline status as determined above.
+That is, if the pipeline status is zero, the exit status is 1;
+if the pipeline status is other than zero, the exit status is zero.
+If there is no
+.Dq Ic \&!
+reserved word, the pipeline status becomes the exit status.
+.Pp
+Because pipeline assignment of standard input or standard output or both
+takes place before redirection, it can be modified by redirection.
+For example:
+.Pp
+.Dl $ command1 2>&1 \&| command2
+.Pp
+sends both the standard output and standard error of command1
+to the standard input of command2.
+.Pp
+Note that unlike some other shells, each process in the pipeline is a
+child of the invoking shell (unless it is a shell built-in, in which case
+it executes in the current shell \(em but any effect it has on the
+environment is wiped).
+.Pp
+A pipeline is a simple case of an AND-OR-list (described below.)
+A
+.Li \&;
+or
+.Aq newline
+terminator causes the preceding pipeline, or more generally,
+the preceding AND-OR-list to be executed sequentially;
+that is, the shell executes the commands, and waits for them
+to finish before proceeding to following commands.
+An
+.Li \&&
+terminator causes asynchronous (background) execution
+of the preceding AND-OR-list (see the next paragraph below).
+The exit status of an asynchronous AND-OR-list is zero.
+The actual status of the commands,
+after they have completed,
+can be obtained using the
+.Ic wait
+built-in command described later.
+.\"
+.\"
+.Ss Background Commands \(em Ic \&&
+.\"
+If a command, pipeline, or AND-OR-list
+is terminated by the control operator ampersand
+.Pq Li \&& ,
+the
+shell executes the command asynchronously \(em that is, the shell does not
+wait for the command to finish before executing the next command.
+.Pp
+The format for running a command in background is:
+.Pp
+.Dl command1 & Op Li command2 & No ...
+.Pp
+If the shell is not interactive, the standard input of an asynchronous
+command is set to
+.Pa /dev/null .
+The process identifier of the most recent command started in the
+background can be obtained from the value of the special parameter
+.Dq Dv \&! \" $!
+(see
+.Sx Special Parameters )
+provided it is accessed before the next asynchronous command is started.
+.\"
+.\"
+.Ss Lists \(em Generally Speaking
+.\"
+A list is a sequence of one or more commands separated by newlines,
+semicolons, or ampersands, and optionally terminated by one of these three
+characters.
+A shell program, which includes the commands given to an
+interactive shell, is a list.
+Each command in such a list is executed when it is fully parsed.
+Another use of a list is as a complete-command,
+which is parsed in its entirety, and then later the commands in
+the list are executed only if there were no parsing errors.
+.Pp
+The commands in a list are executed in the order they are written.
+If command is followed by an ampersand, the shell starts the
+command and immediately proceeds to the next command; otherwise it waits
+for the command to terminate before proceeding to the next one.
+A newline is equivalent to a
+.Sq Li \&;
+when no other operator is present, and the command being input
+could syntactically correctly be terminated at the point where
+the newline is encountered, otherwise it is just whitespace.
+.\"
+.\"
+.Ss AND-OR Lists (Short-Circuit List Operators)
+.\"
+.Dq Li \&&&
+and
+.Dq Li \&||
+are AND-OR list operators.
+After executing the commands that precede the
+.Dq Li \&&&
+the subsequent command is executed
+if and only if the exit status of the preceding command(s) is zero.
+.Dq Li \&||
+is similar, but executes the subsequent command if and only if the exit status
+of the preceding command is nonzero.
+If a command is not executed, the exit status remains unchanged
+and the following AND-OR list operator (if any) uses that status.
+.Dq Li \&&&
+and
+.Dq Li \&||
+both have the same priority.
+Note that these operators are left-associative, so
+.Dl true || echo bar && echo baz
+writes
+.Dq baz
+and nothing else.
+This is not the way it works in C.
+.\"
+.\"
+.Ss Flow-Control Constructs \(em Ic if , while , until , for , case
+.\"
+These commands are instances of compound commands.
+The syntax of the
+.Ic if
+command is
+.Bd -literal -offset indent
+.Ic if Ar list
+.Ic then Ar list
+.Ic [ elif Ar list
+.Ic then  Ar list ] No ...
+.Ic [ else Ar list ]
+.Ic fi
+.Ed
+.Pp
+The first list is executed, and if the exit status of that list is zero,
+the list following the
+.Ic then
+is executed.
+Otherwise the list after an
+.Ic elif
+(if any) is executed and the process repeats.
+When no more
+.Ic elif
+reserved words, and accompanying lists, appear,
+the list after the
+.Ic else
+reserved word, if any, is executed.
+.Pp
+The syntax of the
+.Ic while
+command is
+.Bd -literal -offset indent
+.Ic while Ar list
+.Ic do Ar list
+.Ic done
+.Ed
+.Pp
+The two lists are executed repeatedly while the exit status of the
+first list is zero.
+The
+.Ic until
+command is similar, but has the word
+.Ic until
+in place of
+.Ic while ,
+which causes it to repeat until the exit status of the first list is zero.
+.Pp
+The syntax of the
+.Ic for
+command is
+.Bd -literal -offset indent
+.Ic for Ar variable Op Ic in Ar word No ...
+.Ic do Ar list
+.Ic done
+.Ed
+.Pp
+The words are expanded, or
+.Li \*q$@\*q
+if
+.Ic in
+(and the following words) is not present,
+and then the list is executed repeatedly with the
+variable set to each word in turn.
+If
+.Ic in
+appears after the variable, but no words are
+present, the list is not executed, and the exit status is zero.
+.Ic do
+and
+.Ic done
+may be replaced with
+.Sq Ic \&{
+and
+.Sq Ic \&} ,
+but doing so is non-standard and not recommended.
+.Pp
+The syntax of the
+.Ic break
+and
+.Ic continue
+commands is
+.Bd -literal -offset indent
+.Ic break Op Ar num
+.Ic continue Op Ar num
+.Ed
+.Pp
+.Ic break
+terminates the
+.Ar num
+innermost
+.Ic for , while ,
+or
+.Ic until
+loops.
+.Ic continue
+breaks execution of the
+.Ar num\^ Ns -1
+innermost
+.Ic for , while ,
+or
+.Ic until
+loops, and then continues with the next iteration of the enclosing loop.
+These are implemented as special built-in commands.
+The parameter
+.Ar num ,
+if given, must be an unsigned positive integer (greater than zero).
+If not given, 1 is used.
+.Pp
+The syntax of the
+.Ic case
+command is
+.Bd -literal -offset indent
+.Ic case Ar word Ic in
+.Oo Ic \&( Oc  Ar pattern Ns Ic \&) Oo Ar list Oc Ic \&;&
+.Oo Ic \&( Oc  Ar pattern Ns Ic \&) Oo Ar list Oc Ic \&;;
+.No \&...
+.Ic esac
+.Ed
+.Pp
+The pattern can actually be one or more patterns (see
+.Sx Shell Patterns
+described later), separated by
+.Dq \(or
+characters.
+.Pp
+.Ar word
+is expanded and matched against each
+.Ar pattern
+in turn,
+from first to last,
+with each pattern being expanded just before the match is attempted.
+When a match is found, pattern comparisons cease, and the associated
+.Ar list ,
+if given,
+is evaluated.
+If the list is terminated with
+.Dq Ic \&;&
+execution then falls through to the following list, if any,
+without evaluating its pattern, or attempting a match.
+When a list terminated with
+.Dq Ic \&;;
+has been executed, or when
+.Ic esac
+is reached, execution of the
+.Ic case
+statement is complete.
+The exit status is that of the last command executed
+from the last list evaluated, if any, or zero otherwise.
+.\"
+.\"
+.Ss Grouping Commands Together
+.\"
+Commands may be grouped by writing either
+.Dl Ic \&( Ns Ar list Ns Ic \&)
+or
+.Dl Ic \&{ Ar list Ns Ic \&; \&}
+These also form compound commands.
+.Pp
+Note that while parentheses are operators, and do not require
+any extra syntax, braces are reserved words, so the opening brace
+must be followed by white space (or some other operator), and the
+closing brace must occur in a position where a new command word might
+otherwise appear.
+.Pp
+The first of these executes the commands in a sub-shell.
+Built-in commands grouped into a
+.Li \&( Ns Ar list Ns \&)
+will not affect the current shell.
+The second form does not fork another shell so is slightly more efficient,
+and allows for commands which do affect the current shell.
+Grouping commands together this way allows you to redirect
+their output as though they were one program:
+.Bd -literal -offset indent
+{ echo -n \*qhello \*q ; echo \*qworld\*q ; } > greeting
+.Ed
+.Pp
+Note that
+.Dq Ic }
+must follow a control operator (here,
+.Dq Ic \&; )
+so that it is recognized as a reserved word and not as another command argument.
+.\"
+.\"
+.Ss Functions
+.\"
+The syntax of a function definition is
+.Pp
+.Dl Ar name Ns Ic \&() Ar command Op Ar redirect No ...
+.Pp
+A function definition is an executable statement; when executed it
+installs a function named name and returns an exit status of zero.
+The command is normally a list enclosed between
+.Dq {
+and
+.Dq } .
+The standard syntax also allows the command to be any of the other
+compound commands, including a sub-shell, all of which are supported.
+As an extension, this shell also allows a simple command
+(or even another function definition) to be
+used, though users should be aware this is non-standard syntax.
+This means that
+.Dl l() ls \*q$@\*q
+works to make
+.Dq l
+an alternative name for the
+.Ic ls
+command.
+.Pp
+If the optional redirect, (see
+.Sx Redirections ) ,
+which may be of any of the normal forms,
+is given, it is applied each time the
+function is called.
+This means that a simple
+.Dq Hello World
+function might be written (in the extended syntax) as:
+.Bd -literal -offset indent
+hello() cat <<EOF
+Hello World!
+EOF
+.Ed
+.Pp
+To be correctly standards conforming this should be re-written as:
+.Bd -literal -offset indent
+hello() { cat; } <<EOF
+Hello World!
+EOF
+.Ed
+.Pp
+Note the distinction between those forms, and
+.Bd -literal -offset indent
+hello() { cat <<EOF
+Hello World!
+EOF
+\&}
+.Ed
+.Pp
+which reads and processes the here-document
+each time the shell executes the function, and which applies
+that input only to the cat command, not to any other commands
+that might appear in the function.
+.Pp
+Variables may be declared to be local to a function by using the
+.Ic local
+command.
+This should usually appear as the first statement of a function,
+though
+.Ic local
+is an executable command which can be used anywhere in a function.
+See
+.Sx Built-ins
+below for its definition.
+.Pp
+The function completes after having executed
+.Ar command
+with exit status set to the status returned by
+.Ar command .
+If
+.Ar command
+is a compound-command
+it can use the
+.Ic return
+command (see
+.Sx Built-ins
+below)
+to finish before completing all of
+.Ar command .
+.Ss Variables and Parameters
+The shell maintains a set of parameters.
+A parameter denoted by a name is called a variable.
+When starting up, the shell turns all the environment
+variables into shell variables, and exports them.
+New variables can be set using the form
+.Pp
+.Dl Ar name Ns Li = Ns Ar value
+.Pp
+Variables set by the user must have a name consisting solely of
+alphabetics, numerics, and underscores \(em the first of which must not be
+numeric.
+A parameter can also be denoted by a number or a special
+character as explained below.
+.Ss Positional Parameters
+A positional parameter is a parameter denoted by a number (n > 0).
+The shell sets these initially to the values of its command line arguments
+that follow the name of the shell script.
+The
+.Ic set
+built-in can also be used to set or reset them, and
+.Ic shift
+can be used to manipulate the list.
+.Pp
+To refer to the 10th (and later) positional parameters,
+the form
+.Li \&${ Ns Ar n Ns Li \&}
+must be used.
+Without the braces, a digit following
+.Dq $
+can only refer to one of the first 9 positional parameters,
+or the special parameter
+.Dv 0 . \" $0
+The word
+.Dq Li $10
+is treated identically to
+.Dq Li ${1}0 .
+.\"
+.\"
+.Ss Special Parameters
+.\"
+A special parameter is a parameter denoted by one of the following special
+characters.
+The value of the parameter is listed next to its character.
+.Bl -tag -width thinhyphena
+.It Dv *
+Expands to the positional parameters, starting from one.
+When the
+expansion occurs within a double-quoted string it expands to a single
+field with the value of each parameter separated by the first character of
+the
+.Ev IFS
+variable, or by a
+.Aq space
+if
+.Ev IFS
+is unset.
+.It Dv @ \" $@
+Expands to the positional parameters, starting from one.
+When the expansion occurs within double quotes, each positional
+parameter expands as a separate argument.
+If there are no positional parameters, the
+expansion of @ generates zero arguments, even when
+.Dv $@
+is double-quoted.
+What this basically means, for example, is
+if
+.Li $1
+is
+.Dq abc
+and
+.Li $2
+is
+.Dq def\ ghi ,
+then
+.Li \*q$@\*q
+expands to
+the two arguments:
+.Pp
+.Sm off
+.Dl \*q abc \*q \  \*q def\ ghi \*q
+.Sm on
+.It Dv #
+Expands to the number of positional parameters.
+.It Dv \&?
+Expands to the exit status of the most recent pipeline.
+.It Dv \- No (hyphen, or minus)
+Expands to the current option flags (the single-letter
+option names concatenated into a string) as specified on
+invocation, by the set built-in command, or implicitly
+by the shell.
+.It Dv $
+Expands to the process ID of the invoked shell.
+A sub-shell retains the same value of
+.Dv $
+as its parent.
+.It Dv \&!
+Expands to the process ID of the most recent background
+command executed from the current shell.
+For a pipeline, the process ID is that of the last command in the pipeline.
+If no background commands have yet been started by the shell, then
+.Dq Dv \&!
+will be unset.
+Once set, the value of
+.Dq Dv \&!
+will be retained until another background command is started.
+.It Dv 0 No (zero) \" $0
+Expands to the name of the shell or shell script.
+.El
+.\"
+.\"
+.Ss Word Expansions
+.\"
+This section describes the various expansions that are performed on words.
+Not all expansions are performed on every word, as explained later.
+.Pp
+Tilde expansions, parameter expansions, command substitutions, arithmetic
+expansions, and quote removals that occur within a single word expand to a
+single field.
+It is only field splitting or pathname expansion that can
+create multiple fields from a single word.
+The single exception to this
+rule is the expansion of the special parameter
+.Dv @ \" $@
+within double quotes, as was described above.
+.Pp
+The order of word expansion is:
+.Bl -enum
+.It
+Tilde Expansion, Parameter Expansion, Command Substitution,
+Arithmetic Expansion (these all occur at the same time).
+.It
+Field Splitting is performed on fields
+generated by step (1) unless the
+.Ev IFS
+variable is null.
+.It
+Pathname Expansion (unless set
+.Fl f
+is in effect).
+.It
+Quote Removal.
+.El
+.Pp
+The $ character is used to introduce parameter expansion, command
+substitution, or arithmetic evaluation.
+.Ss Tilde Expansion (substituting a user's home directory)
+A word beginning with an unquoted tilde character (~) is
+subjected to tilde expansion.
+Provided all of the subsequent characters in the word are unquoted
+up to an unquoted slash (/)
+or when in an assignment or not in posix mode, an unquoted colon (:),
+or if neither of those appear, the end of the word,
+they are treated as a user name
+and are replaced with the pathname of the named user's home directory.
+If the user name is missing (as in
+.Pa ~/foobar ) ,
+the tilde is replaced with the value of the
+.Dv HOME
+variable (the current user's home directory).
+.Pp
+In variable assignments,
+an unquoted tilde immediately after the assignment operator (=), and
+each unquoted tilde immediately after an unquoted colon in the value
+to be assigned is also subject to tilde expansion as just stated.
+.\"
+.\"
+.Ss Parameter Expansion
+.\"
+The format for parameter expansion is as follows:
+.Pp
+.Dl ${ Ns Ar expression Ns Li }
+.Pp
+where
+.Ar expression
+consists of all characters until the matching
+.Sq Li } .
+Any
+.Sq Li }
+escaped by a backslash or within a quoted string, and characters in
+embedded arithmetic expansions, command substitutions, and variable
+expansions, are not examined in determining the matching
+.Sq Li } .
+.Pp
+The simplest form for parameter expansion is:
+.Pp
+.Dl ${ Ns Ar parameter Ns Li }
+.Pp
+The value, if any, of
+.Ar parameter
+is substituted.
+.Pp
+The parameter name or symbol can be enclosed in braces,
+which are optional in this simple case,
+except for positional parameters with more than one digit or
+when parameter is followed by a character that could be interpreted as
+part of the name.
+If a parameter expansion occurs inside double quotes:
+.Bl -enum
+.It
+pathname expansion is not performed on the results of the expansion;
+.It
+field splitting is not performed on the results of the
+expansion, with the exception of the special rules for
+.Dv @ . \" $@
+.El
+.Pp
+In addition, a parameter expansion where braces are used,
+can be modified by using one of the following formats.
+If the
+.Sq Ic \&:
+is omitted in the following modifiers, then the test in the expansion
+applies only to unset parameters, not null ones.
+.Bl -tag -width aaparameterwordaaaaa
+.It Li ${ Ns Ar parameter Ns Ic :- Ns Ar word Ns Li }
+.Sy Use Default Values.
+If
+.Ar parameter
+is unset or null, the expansion of
+.Ar word
+is substituted; otherwise, the value of
+.Ar parameter
+is substituted.
+.It Li ${ Ns Ar parameter Ns Ic := Ns Ar word Ns Li }
+.Sy Assign Default Values.
+If
+.Ar parameter
+is unset or null, the expansion of
+.Ar word
+is assigned to
+.Ar parameter .
+In all cases, the final value of
+.Ar parameter
+is substituted.
+Only variables, not positional parameters or special
+parameters, can be assigned in this way.
+.It Li ${ Ns Ar parameter Ns Ic :? Ns Oo Ar word\^ Oc Ns Li }
+.Sy Indicate Error if Null or Unset.
+If
+.Ar parameter
+is unset or null, the expansion of
+.Ar word
+(or a message indicating it is unset if
+.Ar word
+is omitted)
+is written to standard error and a non-interactive shell exits with
+a nonzero exit status.
+An interactive shell will not exit, but any associated command(s) will
+not be executed.
+If the
+.Ar parameter
+is set, its value is substituted.
+.It Li ${ Ns Ar parameter Ns Ic :+ Ns Ar word Ns Li }
+.Sy Use Alternative Value.
+If
+.Ar parameter
+is unset or null, null is substituted;
+otherwise, the expansion of
+.Ar word
+is substituted.
+The value of
+.Ar parameter
+.Em is not used
+in this expansion.
+.It Li ${ Ns Ic # Ns Ar parameter Ns Li }
+.Sy String Length.
+The length in characters of the value of
+.Ar parameter .
+.El
+.Pp
+The following four varieties of parameter expansion provide for substring
+processing.
+In each case, pattern matching notation (see
+.Sx Shell Patterns ) ,
+rather than regular expression notation, is used to evaluate the patterns.
+If parameter is
+.Dv *
+or
+.Dv @ , \" $@
+the result of the expansion is unspecified.
+Enclosing the full parameter expansion string in double quotes does not
+cause the following four varieties of pattern characters to be quoted,
+whereas quoting characters within the braces has this effect.
+.Bl -tag -width aaparameterwordaaaaa
+.It Li ${ Ns Ar parameter Ns Ic % Ns Ar word Ns Li }
+.Sy Remove Smallest Suffix Pattern.
+The
+.Ar word
+is expanded to produce a pattern.
+The parameter expansion then results in
+.Ar parameter ,
+with the
+smallest portion of the suffix matched by the pattern deleted.
+If the
+.Ar word
+is to start with a
+.Sq Li \&%
+character, it must be quoted.
+.It Li ${ Ns Ar parameter Ns Ic %% Ns Ar word Ns Li }
+.Sy Remove Largest Suffix Pattern.
+The
+.Ar word
+is expanded to produce a pattern.
+The parameter expansion then results in
+.Ar parameter ,
+with the largest
+portion of the suffix matched by the pattern deleted.
+The
+.Dq Ic %%
+pattern operator only produces different results from the
+.Dq Ic \&%
+operator when the pattern contains at least one unquoted
+.Sq Li \&* .
+.It Li ${ Ns Ar parameter Ns Ic \&# Ns Ar word Ns Li }
+.Sy Remove Smallest Prefix Pattern.
+The
+.Ar word
+is expanded to produce a pattern.
+The parameter expansion then results in
+.Ar parameter ,
+with the
+smallest portion of the prefix matched by the pattern deleted.
+If the
+.Ar word
+is to start with a
+.Sq Li \&#
+character, it must be quoted.
+.It Li ${ Ns Ar parameter Ns Ic \&## Ns Ar word Ns Li }
+.Sy Remove Largest Prefix Pattern.
+The
+.Ar word
+is expanded to produce a pattern.
+The parameter expansion then results in
+.Ar parameter ,
+with the largest
+portion of the prefix matched by the pattern deleted.
+This has the same relationship with the
+.Dq Ic \&#
+pattern operator as
+.Dq Ic %%
+has with
+.Dq Ic \&% .
+.El
+.\"
+.\"
+.Ss Command Substitution
+.\"
+Command substitution allows the output of a command to be substituted in
+place of the command (and surrounding syntax).
+Command substitution occurs when a word contains
+a command list enclosed as follows:
+.Pp
+.Dl Ic $( Ns Ar list Ns Ic \&)
+.Pp
+or the older
+.Pq Dq backquoted
+version, which is best avoided:
+.Pp
+.Dl Ic \&` Ns Ar list Ns Ns Ic \&`
+.Pp
+See the section
+.Sx Complex Commands
+above for the definition of
+.Ic list .
+.Pp
+The shell expands the command substitution by executing the
+.Ar list
+in a sub-shell environment and replacing the command substitution with the
+standard output of the
+.Ar list
+after removing any sequence of one or more
+.Ao newline Ac Ns s
+from the end of the substitution.
+(Embedded
+.Ao newline Ac Ns s
+before
+the end of the output are not removed; however, during field splitting,
+they may be used to separate fields
+.Pq "as spaces usually are"
+depending on the value of
+.Ev IFS
+and any quoting that is in effect.)
+.Pp
+Note that if a command substitution includes commands
+to be run in the background,
+the sub-shell running those commands
+will only wait for them to complete if an appropriate
+.Ic wait
+command is included in the command list.
+However, the shell in which the result of the command substitution
+will be used will wait for both the sub-shell to exit and for the
+file descriptor that was initially standard output for the command
+substitution sub-shell to be closed.
+In some circumstances this might not happen until all processes
+started by the command substitution have finished.
+.\" While the exit of the sub-shell closes its standard output,
+.\" any background process left running may still
+.\" have that file descriptor open.
+.\" This includes yet another sub-shell which might have been
+.\" (almost invisibly) created to wait for some other command to complete,
+.\" and even where the background command has had its
+.\" standard output redirected or closed,
+.\" the waiting sub-shell may still have it open.
+.\" Thus there is no guarantee that the result of a command substitution
+.\" will be available in the shell which is to use it before all of
+.\" the commands started by the command substitution have completed,
+.\" though careful coding can often avoid delays beyond the termination
+.\" of the command substitution sub-shell.
+.\" .Pp
+.\" For example, assuming a script were to contain the following
+.\" code (which could be done better other ways, attempting
+.\" this kind of trickery is not recommended):
+.\" .Bd -literal -offset indent
+.\" if [ "$( printf "Ready? " >&2; read ans; printf "${ans}";
+.\"    { sleep 120 >/dev/null && kill $$ >/dev/null 2>&1; }& )" = go ]
+.\" then
+.\" 	printf Working...
+.\" 	# more code
+.\" fi
+.\" .Ed
+.\" .Pp
+.\" the
+.\" .Dq Working...
+.\" output will not be printed, and code that follows will never be executed.
+.\" Nor will anything later in the script
+.\" .Po
+.\" unless
+.\" .Dv SIGTERM
+.\" is trapped or ignored
+.\" .Pc .
+.\" .Pp
+.\" The intent is to prompt the user, wait for the user to
+.\" answer, then if the answer was
+.\" .Dq go
+.\" do the appropriate work, but set a 2 minute time limit
+.\" on completing that work.
+.\" If the work is not done by then, kill the shell doing it.
+.\" .Pp
+.\" It will usually not work as written, as while the 2 minute
+.\" .Sq sleep
+.\" has its standard output redirected, as does the
+.\" .Sq kill
+.\" that follows (which also redirects standard error,
+.\" so the user would not see an error if the work were
+.\" completed and there was no parent process left to kill);
+.\" the sub-shell waiting for the
+.\" .Sq sleep
+.\" to finish successfully, so it can start the
+.\" .Sq kill ,
+.\" does not.
+.\" It waits, with standard output still open,
+.\" for the 2 minutes until the sleep is done,
+.\" even though the kill is not going to need that file descriptor,
+.\" and there is nothing else which could.
+.\" The command substitution does not complete until after
+.\" the kill has executed and the background sub-shell
+.\" finishes \(en at which time the shell running it is
+.\" presumably dead.
+.\" .Pp
+.\" Rewriting the background sub-shell part of that as
+.\" .Dl "{ sleep 120 && kill $$ 2>&1; } >/dev/null &"
+.\" would allow this
+.\" .Nm
+.\" to perform as expected, but that is not guaranteed,
+.\" not all shells would behave as planned.
+.\" It is advised to avoid starting background processes
+.\" from within a command substitution.
+.\"
+.\"
+.Ss Arithmetic Expansion
+.\"
+Arithmetic expansion provides a mechanism for evaluating an arithmetic
+expression and substituting its value.
+The format for arithmetic expansion is as follows:
+.Pp
+.Dl Ic $(( Ns Ar expression Ns Ic \&))
+.Pp
+The expression in an arithmetic expansion is treated as if it were in
+double quotes, except that a double quote character inside the expression
+is just a normal character (it quotes nothing.)
+The shell expands all tokens in the expression for parameter expansion,
+command substitution, and quote removal (the only quoting character is
+the backslash
+.Sq \&\e ,
+and only when followed by another
+.Sq \&\e ,
+a dollar sign
+.Sq \&$ ,
+a backquote
+.Sq \&`
+or a newline.)
+.Pp
+Next, the shell evaluates the expanded result as an arithmetic expression
+and substitutes the calculated value of that expression.
+.Pp
+Arithmetic expressions use a syntax similar to that
+of the C language, and are evaluated using the
+.Ql intmax_t
+data type (this is an extension to POSIX, which requires only
+.Ql long
+arithmetic.)
+Shell variables may be referenced by name inside an arithmetic
+expression, without needing a
+.Dq \&$
+sign.
+Variables that are not set, or which have an empty (null string) value,
+used this way evaluate as zero (that is,
+.Dq x
+in arithmetic, as an R-Value, is evaluated as
+.Dq ${x:-0} )
+unless the
+.Nm
+.Fl u
+flag is set, in which case a reference to an unset variable is an error.
+Note that unset variables used in the ${var} form expand to a null
+string, which might result in syntax errors.
+Referencing the value of a variable which is not numeric is an error.
+.Pp
+All of the C expression operators applicable to integers are supported,
+and operate as they would in a C expression.
+Use white space, or parentheses, to disambiguate confusing syntax,
+otherwise, as in C, the longest sequence of consecutive characters
+which make a valid token (operator, variable name, or number) is taken
+to be that token, even if the token designated cannot be used
+and a different interpretation could produce a successful parse.
+This means, as an example, that
+.Dq a+++++b
+is parsed as the gibberish sequence
+.Dq "a ++ ++ + b" ,
+rather than as the valid alternative
+.Dq "a ++ + ++ b" .
+Similarly, separate the
+.Sq \&,
+operator from numbers with white space to avoid the possibility
+of confusion with the decimal indicator in some locales (though
+fractional, or floating-point, numbers are not supported in this
+implementation.)
+.Pp
+It should not be necessary to state that the C operators which
+operate on, or produce, pointer types, are not supported.
+Those include unary
+.Dq \&*
+and
+.Dq \&&
+and the struct and array referencing binary operators:
+.Dq \&. ,
+.Dq \&->
+and
+.Dq \&[ .
+.\"
+.\"
+.Ss White Space Splitting (Field Splitting)
+.\"
+After parameter expansion, command substitution, and
+arithmetic expansion the shell scans the results of
+expansions and substitutions that did not occur in double quotes,
+and
+.Dq Li $@
+even if it did,
+for field splitting and multiple fields can result.
+.Pp
+The shell treats each character of the
+.Ev IFS
+as a delimiter and uses the delimiters to split the results of parameter
+expansion and command substitution into fields.
+.Pp
+Non-whitespace characters in
+.Ev IFS
+are treated strictly as parameter separators.
+So adjacent non-whitespace
+.Ev IFS
+characters will produce empty parameters.
+On the other hand, any sequence of whitespace
+characters that occur in
+.Ev IFS
+(known as
+.Ev IFS
+whitespace)
+can occur, leading and trailing
+.Ev IFS
+whitespace, and any
+.Ev IFS
+whitespace surrounding a non whitespace
+.Ev IFS
+delimiter, is removed.
+Any sequence of
+.Ev IFS
+whitespace characters without a non-whitespace
+.Ev IFS
+delimiter acts as a single field separator.
+.Pp
+If
+.Ev IFS
+is unset it is assumed to contain space, tab, and newline,
+all of which are
+.Ev IFS
+whitespace characters.
+If
+.Ev IFS
+is set to a null string, there are no delimiters,
+and no field splitting occurs.
+.Ss Pathname Expansion (File Name Generation)
+Unless the
+.Fl f
+flag is set, file name generation is performed after word splitting is
+complete.
+Each word is viewed as a series of patterns, separated by slashes.
+The process of expansion replaces the word with the names of all
+existing files whose names can be formed by replacing each pattern with a
+string that matches the specified pattern.
+There are two restrictions on
+this: first, a pattern cannot match a string containing a slash, and
+second, a pattern cannot match a string starting with a period unless the
+first character of the pattern is a period.
+The next section describes the
+patterns used for both Pathname Expansion and the
+.Ic case
+command.
+.Ss Shell Patterns
+A pattern consists of normal characters, which match themselves,
+and meta-characters.
+The meta-characters are
+.Dq \&! ,
+.Dq * ,
+.Dq \&? ,
+and
+.Dq \&[ .
+These characters lose their special meanings if they are quoted.
+When command or variable substitution is performed
+and the dollar sign or backquotes are not double-quoted,
+the value of the variable or the output of
+the command is scanned for these characters and they are turned into
+meta-characters.
+.Pp
+An asterisk
+.Pq Dq *
+matches any string of characters.
+A question mark
+.Pq Dq \&?
+matches any single character.
+A left bracket
+.Pq Dq \&[
+introduces a character class.
+The end of the character class is indicated by a right bracket
+.Pq Dq \&] ;
+if this
+.Dq \&]
+is missing then the
+.Dq \&[
+matches a
+.Dq \&[
+rather than introducing a character class.
+A character class matches any of the characters between the square brackets.
+A named class of characters (see
+.Xr wctype 3 )
+may be specified by surrounding the name with
+.Pq Dq [:
+and
+.Pq Dq :] .
+For example,
+.Pq Dq [[:alpha:]]
+is a shell pattern that matches a single letter.
+A range of characters may be specified using a minus sign
+.Pq Dq \(mi .
+The character class may be complemented
+by making an exclamation mark
+.Pq Dq \&!
+the first character of the character class.
+.Pp
+To include a
+.Dq \&]
+in a character class, make it the first character listed (after the
+.Dq \&! ,
+if any).
+To include a
+.Dq \(mi ,
+make it the first (after !) or last character listed.
+If both
+.Dq \&]
+and
+.Dq \(mi
+are to be included, the
+.Dq \&]
+must be first (after !)
+and the
+.Dq \(mi
+last, in the character class.
+.\"
+.\"
+.Ss Built-ins
+.\"
+This section lists the built-in commands which are built-in because they
+need to perform some operation that can't be performed by a separate
+process.
+Or just because they traditionally are.
+In addition to these, there are several other commands that may
+be built in for efficiency (e.g.
+.Xr printf 1 ,
+.Xr echo 1 ,
+.Xr test 1 ,
+etc).
+.Bl -tag -width 5n
+.It Ic \&: Op Ar arg ...
+A null command that returns a 0 (true) exit value.
+Any arguments or redirects are evaluated, then ignored.
+.\"
+.It Ic \&. Ar file
+The dot command reads and executes the commands from the specified
+.Ar file
+in the current shell environment.
+The file does not need to be executable and is looked up from the directories
+listed in the
+.Ev PATH
+variable if its name does not contain a directory separator
+.Pq Sq / .
+The
+.Ic return
+command (see below)
+can be used for a premature return from the sourced file.
+.Pp
+The POSIX standard has been unclear on how loop control keywords (break
+and continue) behave across a dot command boundary.
+This implementation allows them to control loops surrounding the dot command,
+but obviously such behavior should not be relied on.
+It is now permitted by the standard, but not required.
+.\"
+.It Ic alias Op Ar name Ns Op Li = Ns Ar string ...
+If
+.Ar name Ns Li = Ns Ar string
+is specified, the shell defines the alias
+.Ar name
+with value
+.Ar string .
+If just
+.Ar name
+is specified, the value of the alias
+.Ar name
+is printed.
+With no arguments, the
+.Ic alias
+built-in prints the
+names and values of all defined aliases (see
+.Ic unalias ) .
+.\"
+.It Ic bg Op Ar job ...
+Continue the specified jobs (or the current job if no
+jobs are given) in the background.
+.\"
+.It Ic command Oo Fl pVv Oc Ar command Op Ar arg ...
+Execute the specified command but ignore shell functions when searching
+for it.
+(This is useful when you
+have a shell function with the same name as a command.)
+.Bl -tag -width 5n
+.It Fl p
+search for command using a
+.Ev PATH
+that guarantees to find all the standard utilities.
+.It Fl V
+Do not execute the command but
+search for the command and print the resolution of the
+command search.
+This is the same as the
+.Ic type
+built-in.
+.It Fl v
+Do not execute the command but
+search for the command and print the absolute pathname
+of utilities, the name for built-ins or the expansion of aliases.
+.El
+.\"
+.It Ic cd Oo Fl P Oc Op Ar directory Op Ar replace
+Switch to the specified directory (default
+.Ev $HOME ) .
+If
+.Ar replace
+is specified, then the new directory name is generated by replacing
+the first occurrence of the string
+.Ar directory
+in the current directory name with
+.Ar replace .
+Otherwise if
+.Ar directory
+is
+.Sq Li - ,
+then the current working directory is changed to the previous current
+working directory as set in
+.Ev OLDPWD .
+Otherwise if an entry for
+.Ev CDPATH
+appears in the environment of the
+.Ic cd
+command or the shell variable
+.Ev CDPATH
+is set and the directory name does not begin with a slash,
+and its first (or only) component isn't dot or dot dot,
+then the directories listed in
+.Ev CDPATH
+will be searched for the specified directory.
+The format of
+.Ev CDPATH
+is the same as that of
+.Ev PATH .
+.Pp
+The
+.Fl P
+option instructs the shell to update
+.Ev PWD
+with the specified physical directory path and change to that directory.
+This is the default.
+.Pp
+When the directory changes, the variable
+.Ev OLDPWD
+is set to the working directory before the change.
+.Pp
+Some shells also support a
+.Fl L
+option, which instructs the shell to update
+.Ev PWD
+with the logical path and to change the current directory
+accordingly.
+This is not supported.
+.Pp
+In an interactive shell, the
+.Ic cd
+command will print out the name of the
+directory that it actually switched to if this is different from the name
+that the user gave,
+or always if the
+.Cm cdprint
+option is set.
+The destination may be different either because the
+.Ev CDPATH
+mechanism was used
+.\" or because a symbolic link was crossed.
+or if the
+.Ar replace
+argument was used.
+.\"
+.It Ic eval Ar string ...
+Concatenate all the arguments with spaces.
+Then re-parse and execute the command.
+.\"
+.It Ic exec Op Ar command Op Ar arg ...
+Unless
+.Ar command
+is omitted, the shell process is replaced with the
+specified program (which must be a real program, not a shell built-in or
+function).
+Any redirections on the
+.Ic exec
+command are marked as permanent, so that they are not undone when the
+.Ic exec
+command finishes.
+When the
+.Cm posix
+option is not set,
+file descriptors created via such redirections are marked close-on-exec
+(see
+.Xr open 2
+.Dv O_CLOEXEC
+or
+.Xr fcntl 2
+.Dv F_SETFD /
+.Dv FD_CLOEXEC ) ,
+unless the descriptors refer to the standard input,
+output, or error (file descriptors 0, 1, 2).
+Traditionally Bourne-like shells
+(except
+.Xr ksh 1 ) ,
+made those file descriptors available to exec'ed processes.
+To be assured the close-on-exec setting is off,
+redirect the descriptor to (or from) itself,
+either when invoking a command for which the descriptor is wanted open,
+or by using
+.Ic exec
+(perhaps the same
+.Ic exec
+as opened it, after the open)
+to leave the descriptor open in the shell
+and pass it to all commands invoked subsequently.
+Alternatively, see the
+.Ic fdflags
+command below, which can set, or clear, this, and other,
+file descriptor flags.
+.\"
+.It Ic exit Op Ar exitstatus
+Terminate the shell process.
+If
+.Ar exitstatus
+is given it is used as the exit status of the shell; otherwise the
+exit status of the preceding command (the current value of $?) is used.
+.\"
+.It Ic export Oo Fl nx Oc Ar name Ns Oo =value Oc ...
+.It Ic export Oo Fl x Oc Oo Fl p Oo Ar name ... Oc Oc
+.It Ic export Fl q Oo Fl x Oc Ar name ...
+With no options,
+but one or more names,
+the specified names are exported so that they will appear in the
+environment of subsequent commands.
+With
+.Fl n
+the specified names are un-exported.
+Variables can also be un-exported using the
+.Ic unset
+built in command.
+With
+.Fl x
+(exclude) the specified names are marked not to be exported,
+and any that had been exported, will be un-exported.
+Later attempts to export the variable will be refused.
+Note this does not prevent explicitly exporting a variable
+to a single command, script or function by preceding that
+command invocation by a variable assignment to that variable,
+provided the variable is not also read-only.
+That is
+.Bd -literal -offset indent
+export -x FOO # FOO will now not be exported by default
+export FOO    # this command will fail (non-fatally)
+FOO=some_value my_command
+.Ed
+.Pp
+still passes the value
+.Pq Li FOO=some_value
+to
+.Li my_command
+through the environment.
+.Pp
+The shell allows the value of a variable to be set at the
+same time it is exported (or unexported, etc) by writing
+.Pp
+.Dl export [-nx] name=value
+.Pp
+With no arguments the export command lists the names of all
+set exported variables,
+or if
+.Fl x
+was given, all set variables marked not for export.
+With the
+.Fl p
+option specified, the output will be formatted suitably for
+non-interactive use, and unset variables are included.
+When
+.Fl p
+is given, variable names, but not values, may also be
+given, in which case output is limited to the variables named.
+.Pp
+With
+.Fl q
+and a list of variable names, the
+.Ic export
+command will exit with status 0 if all the named
+variables have been marked for export, or 1 if
+any are not so marked.
+If
+.Fl x
+is also given,
+the test is instead for variables marked not to be exported.
+.Pp
+Other than with
+.Fl q ,
+the
+.Ic export
+built-in exits with status 0,
+unless an attempt is made to export a variable which has
+been marked as unavailable for export,
+in which cases it exits with status 1.
+In all cases if
+an invalid option, or option combination, is given,
+or an invalid variable name is present,
+.Ic export
+will write a message to the standard error output,
+and exit with a non-zero status.
+A non-interactive shell will terminate.
+.Pp
+Note that there is no restriction upon exporting,
+or un-exporting, read-only variables.
+The no-export flag can be reset by unsetting the variable
+and creating it again \(en provided the variable is not also read-only.
+.\"
+.It Ic fc Oo Fl e Ar editor Oc Op Ar first Op Ar last
+.It Ic fc Fl l Oo Fl nr Oc Op Ar first Op Ar last
+.It Ic fc Fl s Oo Ar old=new Oc Op Ar first
+The
+.Ic fc
+built-in lists, or edits and re-executes, commands previously entered
+to an interactive shell.
+.Bl -tag -width 5n
+.It Fl e Ar editor
+Use the editor named by
+.Ar editor
+to edit the commands.
+The
+.Ar editor
+string is a command name, subject to search via the
+.Ev PATH
+variable.
+The value in the
+.Ev FCEDIT
+variable is used as a default when
+.Fl e
+is not specified.
+If
+.Ev FCEDIT
+is null or unset, the value of the
+.Ev EDITOR
+variable is used.
+If
+.Ev EDITOR
+is null or unset,
+.Xr ed 1
+is used as the editor.
+.It Fl l No (ell)
+List the commands rather than invoking an editor on them.
+The commands are written in the sequence indicated by
+the first and last operands, as affected by
+.Fl r ,
+with each command preceded by the command number.
+.It Fl n
+Suppress command numbers when listing with
+.Fl l .
+.It Fl r
+Reverse the order of the commands listed (with
+.Fl l )
+or edited (with neither
+.Fl l
+nor
+.Fl s ) .
+.It Fl s
+Re-execute the command without invoking an editor.
+.It Ar first
+.It Ar last
+Select the commands to list or edit.
+The number of previous commands that
+can be accessed are determined by the value of the
+.Ev HISTSIZE
+variable.
+The value of
+.Ar first
+or
+.Ar last
+or both are one of the following:
+.Bl -tag -width 5n
+.It Oo Cm + Oc Ns Ar number
+A positive number representing a command number; command numbers can be
+displayed with the
+.Fl l
+option.
+.It Cm \- Ns Ar number
+A negative decimal number representing the command that was executed
+number of commands previously.
+For example, \-1 is the immediately previous command.
+.El
+.It Ar string
+A string indicating the most recently entered command that begins with
+that string.
+If the
+.Ar old Ns Li = Ns Ar new
+operand is not also specified with
+.Fl s ,
+the string form of the first operand cannot contain an embedded equal sign.
+.El
+.Pp
+The following environment variables affect the execution of
+.Ic fc :
+.Bl -tag -width HISTSIZE
+.It Ev FCEDIT
+Name of the editor to use.
+.It Ev HISTSIZE
+The number of previous commands that are accessible.
+.El
+.\"
+.It Ic fg Op Ar job
+Move the specified job or the current job to the foreground.
+A foreground job can interact with the user via standard input,
+and receive signals from the terminal.
+.\"
+.It Ic fdflags Oo Fl v Oc Op Ar fd ...
+.It Ic fdflags Oo Fl v Oc Fl s Ar flags fd Op ...
+Get or set file descriptor flags.
+The
+.Fl v
+argument enables verbose printing, printing flags that are also off, and
+the flags of the file descriptor being set after setting.
+The
+.Fl s
+flag interprets the
+.Ar flags
+argument as a comma separated list of file descriptor flags, each preceded
+with a
+.Dq \(pl
+or a
+.Dq \(mi
+indicating to set or clear the respective flag.
+Valid flags are:
+.Cm append ,
+.Cm async ,
+.Cm sync ,
+.Cm nonblock ,
+.Cm fsync ,
+.Cm dsync ,
+.Cm rsync ,
+.Cm direct ,
+.Cm nosigpipe ,
+and
+.Cm cloexec .
+Unique abbreviations of these names, of at least 2 characters,
+may be used on input.
+See
+.Xr fcntl 2
+and
+.Xr open 2
+for more information.
+.\"
+.It Ic getopts Ar optstring var
+The POSIX
+.Ic getopts
+command, not to be confused with the
+Bell Labs\[en]derived
+.Xr getopt 1 .
+.Pp
+The first argument should be a series of letters, each of which may be
+optionally followed by a colon to indicate that the option requires an
+argument.
+The variable specified is set to the parsed option.
+.Pp
+The
+.Ic getopts
+command deprecates the older
+.Xr getopt 1
+utility due to its handling of arguments containing whitespace.
+.Pp
+The
+.Ic getopts
+built-in may be used to obtain options and their arguments
+from a list of parameters.
+When invoked,
+.Ic getopts
+places the value of the next option from the option string in the list in
+the shell variable specified by
+.Ar var
+and its index in the shell variable
+.Ev OPTIND .
+When the shell is invoked,
+.Ev OPTIND
+is initialized to 1.
+For each option that requires an argument, the
+.Ic getopts
+built-in will place it in the shell variable
+.Ev OPTARG .
+If an option is not allowed for in the
+.Ar optstring ,
+then
+.Ev OPTARG
+will be unset.
+.Pp
+.Ar optstring
+is a string of recognized option letters (see
+.Xr getopt 3 ) .
+If a letter is followed by a colon, the option is expected to have an
+argument which may or may not be separated from it by whitespace.
+If an option character is not found where expected,
+.Ic getopts
+will set the variable
+.Ar var
+to a
+.Sq Li \&? ;
+.Ic getopts
+will then unset
+.Ev OPTARG
+and write output to standard error.
+By specifying a colon as the first character of
+.Ar optstring
+all errors will be ignored.
+.Pp
+A nonzero value is returned when the last option is reached.
+If there are no remaining arguments,
+.Ic getopts
+will set
+.Ar var
+to the special option,
+.Dq Li \-\- ,
+otherwise, it will set
+.Ar var
+to
+.Sq Li \&? .
+.Pp
+The following code fragment shows how one might process the arguments
+for a command that can take the options
+.Fl a
+and
+.Fl b ,
+and the option
+.Fl c ,
+which requires an argument.
+.Bd -literal -offset indent
+while getopts abc: f
+do
+	case $f in
+	a | b)	flag=$f;;
+	c)	carg=$OPTARG;;
+	\e?)	echo $USAGE; exit 1;;
+	esac
+done
+shift $((OPTIND - 1))
+.Ed
+.Pp
+This code will accept any of the following as equivalent:
+.Bd -literal -offset indent
+cmd \-acarg file file
+cmd \-a \-c arg file file
+cmd \-carg -a file file
+cmd \-a \-carg \-\- file file
+.Ed
+.\"
+.It Ic hash Oo Fl rv Oc Op Ar command ...
+The shell maintains a hash table which remembers the
+locations of commands.
+With no arguments whatsoever,
+the
+.Ic hash
+command prints out the contents of this table.
+Entries which have not been looked at since the last
+.Ic cd
+command are marked with an asterisk; it is possible for these entries
+to be invalid.
+.Pp
+With arguments, the
+.Ic hash
+command removes the specified commands from the hash table (unless
+they are functions) and then locates them.
+With the
+.Fl v
+option, hash prints the locations of the commands as it finds them.
+The
+.Fl r
+option causes the hash command to delete all the entries in the hash table
+except for functions.
+.\"
+.It Ic inputrc Ar file
+Read the
+.Ar file
+to set key bindings as defined by
+.Xr editrc 5 .
+.\"
+.It Ic jobid Oo Fl g Ns \&| Ns Fl j Ns \&| Ns Fl p Oc  Op Ar job
+With no flags, print the process identifiers of the processes in the job.
+If the
+.Ar job
+argument is omitted, the current job is used.
+Any of the ways to select a job may be used for
+.Ar job ,
+including the
+.Sq Li \&%
+forms, or the process id of the job leader
+.Po
+.Dq Li \&$!
+if the job was created in the background.
+.Pc
+.Pp
+If one of the flags is given, then instead of the list of
+process identifiers, the
+.Ic jobid
+command prints:
+.Bl -tag -width ".Fl g"
+.It Fl g
+the process group, if one was created for this job,
+or nothing otherwise (the job is in the same process
+group as the shell.)
+.It Fl j
+the job identifier (using
+.Dq Li \&% Ns Ar n
+notation, where
+.Ar n
+is a number) is printed.
+.It Fl p
+only the process id of the process group leader is printed.
+.El
+.Pp
+These flags are mutually exclusive.
+.Pp
+.Ic jobid
+exits with status 2 if there is an argument error,
+status 1, if with
+.Fl g
+the job had no separate process group,
+or with
+.Fl p
+there is no process group leader (should not happen),
+and otherwise exits with status 0.
+.\"
+.It Ic jobs Oo Fl l Ns \&| Ns Fl p Oc Op Ar job ...
+Without
+.Ar job
+arguments,
+this command lists out all the background processes
+which are children of the current shell process.
+With
+.Ar job
+arguments, the listed jobs are shown instead.
+Without flags, the output contains the job
+identifier (see
+.Sx Job Control
+below), an indicator character if the job is the current or previous job,
+the current status of the job (running, suspended, or terminated successfully,
+unsuccessfully, or by a signal)
+and a (usually abbreviated) command string.
+.Pp
+With the
+.Fl l
+flag the output is in a longer form, with the process identifiers
+of each process (run from the top level, as in a pipeline), and the
+status of each process, rather than the job status.
+.Pp
+With the
+.Fl p
+flag, the output contains only the process identifier of the lead
+process.
+.Pp
+In an interactive shell, each job shown as completed in the output
+from the jobs command is implicitly waited for, and is removed from
+the jobs table, never to be seen again.
+In an interactive shell, when a background job terminates, the
+.Ic jobs
+command (with that job as an argument) is implicitly run just
+before outputting the next PS1 command prompt, after the job
+terminated.
+This indicates that the job finished, shows its status,
+and cleans up the job table entry for that job.
+Non-interactive shells need to execute
+.Ic wait
+commands to clean up terminated background jobs.
+.\"
+.It Ic local Oo Fl INx Oc Oo Ar variable | \- Oc ...
+Define local variables for a function.
+Local variables have their attributes, and values,
+as they were before the
+.Ic local
+declaration, restored when the function terminates.
+.Pp
+With the
+.Fl N
+flag, variables made local, are unset initially inside
+the function.
+Unless the
+.Fl x
+flag is also given, such variables are also unexported.
+The
+.Fl I
+flag, which is the default in this shell, causes
+the initial value and exported attribute
+of local variables
+to be inherited from the variable
+with the same name in the surrounding
+scope, if there is one.
+If there is not, the variable is initially unset,
+and not exported.
+The
+.Fl N
+and
+.Fl I
+flags are mutually exclusive, if both are given, the last specified applies.
+The read-only and unexportable attributes are always
+inherited, if a variable with the same name already exists.
+.Pp
+The
+.Fl x
+flag (lower case) causes the local variable to be exported,
+while the function runs, unless it has the unexportable attribute.
+This can also be accomplished by using the
+.Ic export
+command, giving the same
+.Ar variable
+names, after the
+.Ic local
+command.
+.Pp
+Making an existing read-only variable local is possible,
+but pointless.
+If an attempt is made to assign an initial value to such
+a variable, the
+.Ic local
+command fails, as does any later attempted assignment.
+If the
+.Ic readonly
+command is applied to a variable that has been declared local,
+the variable cannot be (further) modified within the function,
+or any other functions it calls, however when the function returns,
+the previous status (and value) of the variable is returned.
+.Pp
+Values may be given to local variables on the
+.Ic local
+command line in a similar fashion as used for
+.Ic export
+and
+.Ic readonly .
+These values are assigned immediately after the initialization
+described above.
+Note that any variable references on the command line will have
+been expanded before
+.Ic local
+is executed, so expressions like
+.Pp
+.Dl "local -N X=${X}"
+.Pp
+are well defined, first $X is expanded, and then the command run is
+.Pp
+.Dl "local -N X=old-value-of-X"
+.Pp
+After arranging to preserve the old value and attributes, of
+.Dv X
+.Dq ( old-value-of X )
+.Ic local
+unsets
+.Dv X ,
+unexports it, and then assigns the
+.Dq old-value-of-X
+to
+.Ev X .
+.Pp
+The shell uses dynamic scoping, so that if you make the variable
+.Dv x
+local to
+function
+.Dv f ,
+which then calls function
+.Dv g ,
+references to the variable
+.Dv x
+made inside
+.Dv g
+will refer to the variable
+.Dv x
+declared inside
+.Dv f ,
+not to the global variable named
+.Dv x .
+.Pp
+Another way to view this, is as if the shell just has one flat, global,
+namespace, in which all variables exist.
+The
+.Ic local
+command conceptually copies the variable(s) named to unnamed temporary
+variables, and when the function ends, copies them back again.
+All references to the variables reference the same global variables,
+but while the function is active, after the
+.Ic local
+command has run, the values and attributes of the variables might
+be altered, and later, when the function completes, be restored.
+.Pp
+Note that the positional parameters
+.Dv 1 ,  \" $1
+.Dv 2 ,  \" $2
+\&... (see
+.Sx Positional Parameters ) ,
+and the special parameters
+.Dv \&# , \" $#
+.Dv \&*   \" $*
+and
+.Dv \&@   \" $@
+(see
+.Sx Special Parameters ) ,
+are always made local in all functions, and are reset inside the
+function to represent the options and arguments passed to the function.
+Note that
+.Li $0
+however retains the value it had outside the function,
+as do all the other special parameters.
+.Pp
+The only special parameter that can optionally be made local is
+.Dq Li \- .
+Making
+.Dq Li \-
+local causes any shell options that are changed via the set command inside the
+function to be restored to their original values when the function
+returns.
+If
+.Fl X
+option is altered after
+.Dq Li \-
+has been made local, then when the function returns, the previous
+destination for
+.Cm xtrace
+output (as of the time of the
+.Ic local
+command) will also be restored.
+If any of the shell's magic variables
+(those which return a value which may vary without
+the variable being explicitly altered,
+e.g.:
+.Dv SECONDS
+or
+.Dv HOSTNAME )
+are made local in a function,
+they will lose their special properties when set
+within the function, including by the
+.Ic local
+command itself
+(if not to be set in the function, there is little point
+in making a variable local)
+but those properties will be restored when the function returns.
+.Pp
+It is an error to use
+.Ic local
+outside the scope of a function definition.
+When used inside a function, it exits with status 0,
+unless an undefined option is used, or an attempt is made to
+assign a value to a read-only variable.
+.Pp
+Note that either
+.Fl I
+or
+.Fl N
+should always be used, or variables made local should always
+be given a value, or explicitly unset, as the default behavior
+(inheriting the earlier value, or starting unset after
+.Ic local )
+differs amongst shell implementations.
+Using
+.Dq Li local \&\-
+is an extension not implemented by most shells.
+.Pp
+See the section
+.Sx LINENO
+below for details of the effects of making the variable
+.Dv LINENO
+local.
+.\"
+.It Ic pwd Op Fl \&LP
+Print the current directory.
+If
+.Fl L
+is specified the cached value (initially set from
+.Ev PWD )
+is checked to see if it refers to the current directory; if it does
+the value is printed.
+Otherwise the current directory name is found using
+.Xr getcwd 3 .
+The environment variable
+.Ev PWD
+is set to the printed value.
+.Pp
+The default is
+.Ic pwd
+.Fl L ,
+but note that the built-in
+.Ic cd
+command doesn't support the
+.Fl L
+option and will cache (almost) the absolute path.
+If
+.Ic cd
+is changed (as unlikely as that is),
+.Ic pwd
+may be changed to default to
+.Ic pwd
+.Fl P .
+.Pp
+If the current directory is renamed and replaced by a symlink to the
+same directory, or the initial
+.Ev PWD
+value followed a symbolic link, then the cached value may not
+be the absolute path.
+.Pp
+The built-in command may differ from the program of the same name because
+the program will use
+.Ev PWD
+and the built-in uses a separately cached value.
+.\"
+.It Ic read Oo Fl p Ar prompt Oc Oo Fl r Oc Ar variable Op Ar ...
+The
+.Ar prompt
+is printed if the
+.Fl p
+option is specified and the standard input is a terminal.
+Then a line is read from the standard input.
+The trailing newline is deleted from the
+line and the line is split as described in the field splitting section of the
+.Sx Word Expansions
+section above, and the pieces are assigned to the variables in order.
+If there are more pieces than variables, the remaining pieces
+(along with the characters in
+.Ev IFS
+that separated them) are assigned to the last variable.
+If there are more variables than pieces,
+the remaining variables are assigned the null string.
+The
+.Ic read
+built-in will indicate success unless EOF is encountered on input, in
+which case failure is returned.
+.Pp
+By default, unless the
+.Fl r
+option is specified, the backslash
+.Dq \e
+acts as an escape character, causing the following character to be treated
+literally.
+If a backslash is followed by a newline, the backslash and the
+newline will be deleted.
+.\"
+.It Ic readonly Ar name Ns Oo =value Oc ...
+.It Ic readonly Oo Fl p Oo Ar name ... Oc Oc
+.It Ic readonly Fl q Ar name ...
+With no options,
+the specified names are marked as read only, so that they cannot be
+subsequently modified or unset.
+The shell allows the value of a variable
+to be set at the same time it is marked read only by writing
+.Pp
+.Dl readonly name=value
+.Pp
+With no arguments the
+.Ic readonly
+command lists the names of all set read only variables.
+With the
+.Fl p
+option specified,
+the output will be formatted suitably for non-interactive use,
+and unset variables are included.
+When the
+.Fl p
+option is given,
+a list of variable names (without values) may also be specified,
+in which case output is limited to the named variables.
+.Pp
+With the
+.Fl q
+option, the
+.Ic readonly
+command tests the read-only status of the variables listed
+and exits with status 0 if all named variables are read-only,
+or with status 1 if any are not read-only.
+.Pp
+Other than as specified for
+.Fl q
+the
+.Ic readonly
+command normally exits with status 0.
+In all cases, if an unknown option, or an invalid option combination,
+or an invalid variable name, is given;
+or a variable which was already read-only is attempted to be set;
+the exit status will not be zero, a diagnostic
+message will be written to the standard error output,
+and a non-interactive shell will terminate.
+.\"
+.It Ic return Op Ar n
+Stop executing the current function or a dot command with return value of
+.Ar n
+or the value of the last executed command, if not specified.
+For portability,
+.Ar n
+should be in the range from 0 to 255.
+.Pp
+The POSIX standard says that the results of
+.Ic return
+outside a function or a dot command are unspecified.
+This implementation treats such a return as a no-op with a return value of 0
+(success, true).
+Use the
+.Ic exit
+command instead, if you want to return from a script or exit
+your shell.
+.\"
+.It Ic set Oo { Fl options | Cm +options | Cm \-- } Oc Ar arg ...
+The
+.Ic set
+command performs four different functions.
+.Pp
+With no arguments, it lists the values of all shell variables.
+.Pp
+With a single option of either
+.Dq Fl o
+or
+.Dq Cm +o
+.Ic set
+outputs the current values of the options.
+In the
+.Fl o
+form, all options are listed, with their current values.
+In the
+.Cm +o
+form, the shell outputs a string that can later be used
+as a command to reset all options to their current values.
+.Pp
+If options are given, it sets the specified option
+flags, or clears them as described in the
+.Sx Argument List Processing
+section.
+In addition to the options listed there,
+when the
+.Dq "option name"
+given to
+.Ic set Fl o
+is
+.Cm default
+all of the options are reset to the values they had immediately
+after
+.Nm
+initialization, before any startup scripts, or other input, had been processed.
+While this may be of use to users or scripts, its primary purpose
+is for use in the output of
+.Dq Ic set Cm +o ,
+to avoid that command needing to list every available option.
+There is no
+.Cm +o default .
+.Pp
+The fourth use of the
+.Ic set
+command is to set the values of the shell's
+positional parameters to the specified arguments.
+To change the positional
+parameters without changing any options, use
+.Dq -\|-
+as the first argument to
+.Ic set .
+If no following arguments are present, the
+.Ic set
+command
+will clear all the positional parameters (equivalent to executing
+.Dq Li shift $# . )
+Otherwise the following arguments become
+.Li \&$1 ,
+.Li \&$2 ,
+\&...,
+and
+.Li \&$#
+is set to the number of arguments present.
+.\"
+.It Ic setvar Ar variable Ar value
+Assigns
+.Ar value
+to
+.Ar variable .
+(In general it is better to write
+.Li variable=value
+rather than using
+.Ic setvar .
+.Ic setvar
+is intended to be used in
+functions that assign values to variables whose names are passed as
+parameters.)
+.\"
+.It Ic shift Op Ar n
+Shift the positional parameters
+.Ar n
+times.
+If
+.Ar n
+is omitted, 1 is assumed.
+Each
+.Ic shift
+sets the value of
+.Li $1
+to the previous value of
+.Li $2 ,
+the value of
+.Li $2
+to the previous value of
+.Li $3 ,
+and so on, decreasing
+the value of
+.Li $#
+by one.
+The shift count must be less than or equal to the number of
+positional parameters (
+.Dq Li $# )
+before the shift.
+.\"
+.It Ic times
+Prints two lines to standard output.
+Each line contains two accumulated time values, expressed
+in minutes and seconds (including fractions of a second.)
+The first value gives the user time consumed, the second the system time.
+.Pp
+The first output line gives the CPU and system times consumed by the
+shell itself.
+The second line gives the accumulated times for children of this
+shell (and their descendants) which have exited, and then been
+successfully waited for by the relevant parent.
+See
+.Xr times 3
+for more information.
+.Pp
+.Ic times
+has no parameters, and exits with an exit status of 0 unless
+an attempt is made to give it an option.
+.\"
+.It Ic trap Ar action signal ...
+.It Ic trap \-
+.It Ic trap Op Fl l
+.It Ic trap Oo Fl p Oc Ar signal ...
+.It Ic trap Ar N signal ...
+.Pp
+Cause the shell to parse and execute action when any of the specified
+signals are received.
+The signals are specified by signal number or as the name of the signal.
+If
+.Ar signal
+is
+.Li 0 \" $0
+or its equivalent,
+.Li EXIT ,
+the action is executed when the shell exits.
+The
+.Ar action
+may be a null (empty) string,
+which causes the specified signals to be ignored.
+With
+.Ar action
+set to
+.Sq Li -
+the specified signals are set to their default actions.
+If the first
+.Ar signal
+is specified in its numeric form, then
+.Ar action
+can be omitted to achieve the same effect.
+This archaic,
+but still standard,
+form should not be relied upon, use the explicit
+.Sq Li -
+action.
+If no signals are specified with an action of
+.Sq Li - ,
+all signals are reset.
+.Pp
+When the shell forks off a sub-shell, it resets trapped (but not ignored)
+signals to the default action.
+On non-interactive shells, the
+.Ic trap
+command has no effect on signals that were
+ignored on entry to the shell.
+On interactive shells, the
+.Ic trap
+command will catch or reset signals ignored on entry.
+.Pp
+Issuing
+.Ic trap
+with option
+.Fl l
+will print a list of valid signal names.
+.Ic trap
+without any arguments causes it to write a list of signals and their
+associated non-default actions to the standard output in a format
+that is suitable as an input to the shell that achieves the same
+trapping results.
+With the
+.Fl p
+flag, trap prints the same information for the signals specified,
+or if none are given, for all signals, including those where the
+action is the default.
+These variants of the trap command may be executed in a sub-shell
+.Pq "such as in a command substitution" ,
+provided they appear as the sole, or first, command in that sub-shell,
+in which case the state of traps from the parent of that
+sub-shell is reported.
+.Pp
+Examples:
+.Pp
+.Dl trap
+.Pp
+List trapped signals and their corresponding actions.
+.Pp
+.Dl trap -l
+.Pp
+Print a list of valid signals.
+.Pp
+.Dl trap '' INT QUIT tstp 30
+.Pp
+Ignore signals INT QUIT TSTP USR1.
+.Pp
+.Dl trap date INT
+.Pp
+Run the
+.Dq date
+command (print the date) upon receiving signal INT.
+.Pp
+.Dl trap HUP INT
+.Pp
+Run the
+.Dq HUP
+command, or function, upon receiving signal INT.
+.Pp
+.Dl trap 1 2
+.Pp
+Reset the actions for signals 1 (HUP) and 2 (INT) to their defaults.
+.Bd -literal -offset indent
+traps=$(trap -p)
+   # more commands ...
+trap 'action' SIG
+   # more commands ...
+eval "$traps"
+.Ed
+.Pp
+Save the trap status, execute commands, changing some traps,
+and then reset all traps to their values at the start of the sequence.
+The
+.Fl p
+option is required in the first command here,
+or any signals that were previously
+untrapped (in their default states)
+and which were altered during the intermediate code,
+would not be reset by the final
+.Ic eval .
+.\"
+.It Ic type Op Ar name ...
+Interpret each
+.Ar name
+as a command and print the resolution of the command search.
+Possible resolutions are:
+shell keyword, alias, shell built-in,
+command, tracked alias and not found.
+For aliases the alias expansion is
+printed; for commands and tracked aliases the complete pathname of the
+command is printed.
+.\"
+.It Ic ulimit Oo Fl H Ns \*(Ba Ns Fl S Oc Op Fl a \*(Ba Fl btfdscmlrpnv Op Ar value
+Inquire about or set the hard or soft limits on processes or set new
+limits.
+The choice between hard limit (which no process is allowed to
+violate, and which may not be raised once it has been lowered) and soft
+limit (which causes processes to be signaled but not necessarily killed,
+and which may be raised) is made with these flags:
+.Bl -tag -width Fl
+.It Fl H
+set or inquire about hard limits
+.It Fl S
+set or inquire about soft limits.
+.El
+.Pp
+If neither
+.Fl H
+nor
+.Fl S
+is specified, the soft limit is displayed or both limits are set.
+If both are specified, the last one wins.
+.Pp
+The limit to be interrogated or set, then, is chosen by specifying
+any one of these flags:
+.Bl -tag -width Fl
+.It Fl a
+show all the current limits
+.It Fl b
+the socket buffer size of a process (bytes)
+.It Fl c
+the largest core dump size that can be produced
+(512-byte blocks)
+.It Fl d
+the data segment size of a process (kilobytes)
+.It Fl f
+the largest file that can be created
+(512-byte blocks)
+.It Fl l
+how much memory a process can lock with
+.Xr mlock 2
+(kilobytes)
+.It Fl m
+the total physical memory that can be
+in use by a process (kilobytes)
+.It Fl n
+the number of files a process can have open at once
+.It Fl p
+the number of processes this user can
+have at one time
+.It Fl r
+the number of threads this user can
+have at one time
+.It Fl s
+the stack size of a process (kilobytes)
+.It Fl t
+CPU time (seconds)
+.It Fl v
+how large a process address space can be
+.El
+.Pp
+If none of these is specified, it is the limit on file size that is shown
+or set.
+If value is specified, the limit is set to that number; otherwise
+the current limit is displayed.
+.Pp
+Limits of an arbitrary process can be displayed or set using the
+.Xr sysctl 8
+utility.
+.It Ic umask Oo Fl S Oc Op Ar mask
+Set the value of umask (see
+.Xr umask 2 )
+to the specified octal value.
+If the argument is omitted, the umask value is printed.
+With
+.Fl S
+a symbolic form is used instead of an octal number.
+.It Ic unalias Oo Fl a Oc Op Ar name
+If
+.Ar name
+is specified, the shell removes that alias.
+If
+.Fl a
+is specified, all aliases are removed.
+.It Ic unset Oo Fl efvx Oc Ar name ...
+If
+.Fl v
+is specified, the specified variables are unset and unexported.
+Readonly variables cannot be unset.
+If
+.Fl f
+is specified, the specified functions are undefined.
+If
+.Fl e
+is given, the specified variables are unexported, but otherwise unchanged,
+alternatively, if
+.Fl x
+is given, the exported status of the variable will be retained,
+even after it is unset.
+.Pp
+If no flags are provided
+.Fl v
+is assumed.
+If
+.Fl f
+is given with one of the other flags,
+then the named variables will be unset, or unexported, and functions
+of the same names will be undefined.
+The
+.Fl e
+and
+.Fl x
+flags both imply
+.Fl v .
+If
+.Fl e
+is given, the
+.Fl x
+flag is ignored.
+.Pp
+The exit status is 0, unless an attempt was made to unset
+a readonly variable, in which case the exit status is 1.
+It is not an error to unset (or undefine) a variable (or function)
+that is not currently set (or defined.)
+.\"
+.It Ic wait Oo Fl n Oc Oo Fl p Ar var Oc Op Ar job ...
+Wait for the specified jobs to complete
+and return the exit status of the last job in the parameter list,
+or 127 if that job is not a current child of the shell.
+.Pp
+If no
+.Ar job
+arguments are given, wait for all jobs to
+complete and then return an exit status of zero
+(including when there were no jobs, and so nothing exited.)
+.Pp
+With the
+.Fl n
+option, wait instead for any one of the given
+.Ar job Ns s,
+or if none are given, any job, to complete, and
+return the exit status of that job.
+If none of the given
+.Ar job
+arguments is a current child of the shell,
+or if no
+.Ar job
+arguments are given and the shell has no unwaited for children,
+then the exit status will be 127.
+.Pp
+The
+.Fl p Ar var
+option allows the process (or job) identifier of the
+job for which the exit status is returned to be obtained.
+The variable named (which must not be readonly) will be
+unset initially, then if a job has exited and its status is
+being returned, set to the identifier from the
+arg list (if given) of that job,
+or the lead process identifier of the job to exit when used with
+.Fl n
+and no job arguments.
+Note that
+.Fl p
+with neither
+.Fl n
+nor
+.Ar job
+arguments is useless, as in that case no job status is
+returned, the variable named is simply unset.
+.Pp
+If the wait is interrupted by a signal,
+its exit status will be greater than 128,
+and
+.Ar var ,
+if given, will remain unset.
+.Pp
+Once waited upon, by specific process number or job-id,
+or by a
+.Ic wait
+with no arguments,
+knowledge of the child is removed from the system,
+and it cannot be waited upon again.
+.Pp
+Note than when a list of jobs are given, more that
+one argument might refer to the same job.
+In that case, if the final argument represents a job
+that is also given earlier in the list, it is not
+defined whether the status returned will be the
+exit status of the job, or 127 indicating that
+the child no longer existed when the wait command
+reached the later argument in the list.
+In this
+.Nm
+the exit status will be that from the job.
+.Nm
+waits for each job exactly once, regardless of
+how many times (or how many different ways) it
+is listed in the arguments to
+.Ic wait .
+That is
+.Bd -literal -offset indent -compact
+wait 100 100 100
+.Ed
+is identical to
+.Bd -literal -offset indent -compact
+wait 100
+.Ed
+.El
+.\"
+.\"
+.Ss Job Control
+.\"
+Each process (or set of processes) started by
+.Nm
+is created as a
+.Dq job
+and added to the jobs table.
+When enabled by the
+.Fl m
+option
+.Pq aka Fl o Cm monitor
+when the job is created,
+.Nm
+places each job (if run from the top level shell)
+into a process group of its own, which allows control
+of the process(es), and its/their descendants, as a unit.
+When the
+.Fl m
+option is off, or when started from a sub-shell environment,
+jobs share the same process group as the parent shell.
+The
+.Fl m
+option is enabled by default in interactive shells with
+a terminal as standard input and standard error.
+.Pp
+Jobs with separate process groups may be stopped, and then later
+resumed in the foreground (with access to the terminal)
+or in the background (where attempting to read from the
+terminal will result in the job stopping.)
+A list of current jobs can be obtained using the
+.Ic jobs
+built-in command.
+Jobs are identified using either the process identifier
+of the lead process of the job (the value available in
+the special parameter
+.Dq Dv \&!
+if the job is started in the background), or using percent
+notation.
+Each job is given a
+.Dq job number
+which is a small integer, starting from 1, and can be
+referenced as
+.Dq Li \&% Ns Ar n
+where
+.Ar n
+is that number.
+Note that this applies to jobs both with and without their own process groups.
+Job numbers are shown in the output from the
+.Ic jobs
+command enclosed in brackets
+.Po
+.Sq Li \&[
+and
+.Sq Li \&]
+.Pc .
+Whenever the job table becomes empty, the numbers begin at one again.
+In addition, there is the concept of a current, and a previous job,
+identified by
+.Dq Li \&%+
+.Po
+or
+.Dq Li \&%%
+or even just
+.Dq Li \&%
+.Pc ,
+and a previous job, identified by
+.Dq Li \&%\- .
+Whenever a background job is started,
+or a job is resumed in the background,
+it becomes the current job.
+The job that was the current job
+(prepare for a big surprise here, drum roll..., wait for it...\&)
+becomes the previous job.
+When the current job terminates, the previous job is
+promoted to be the current job.
+In addition the form
+.Dq Li \&% Ns Ar string\^
+finds the job for which the command starts with
+.Ar string
+and the form
+.Dq Li \&%? Ns Ar string\^
+finds the job which contains the
+.Ar string
+in its command somewhere.
+Both forms require the result to be unambiguous.
+For this purpose the
+.Dq command
+is that shown in the output from the
+.Ic jobs
+command, not the original command line.
+.Pp
+The
+.Ic bg ,
+.Ic fg ,
+.Ic jobid ,
+.Ic jobs ,
+.Ic kill ,
+and
+.Ic wait
+commands all accept job identifiers as arguments, in addition to
+process identifiers (larger integers).
+See the
+.Sx Built-ins
+section above, and
+.Xr kill 1 ,
+for more details of those commands.
+In addition, a job identifier
+(using one of the
+.Dq \&% forms )
+issued as a command, without arguments, is interpreted as
+if it had been given as the argument to the
+.Ic fg
+command.
+.Pp
+To cause a foreground process to stop, enter the terminal's
+.Ic stop
+character (usually control-Z).
+To cause a background process to stop, send it a
+.Dv STOP
+signal, using the kill command.
+A useful function to define is
+.Bd -literal -offset indent
+stop() { kill -s STOP "${@:-%%}"; }
+.Ed
+.Pp
+The
+.Ic fg
+command resumes a stopped job, placing it in the foreground,
+and
+.Ic bg
+resumes a stopped job in the background.
+The
+.Ic jobid
+command provides information about process identifiers, job identifiers,
+and the process group identifier, for a job.
+.Pp
+Whenever a sub-shell is created, the jobs table becomes invalid
+(the sub-shell has no children.)
+However, to enable uses like
+.Bd -literal -offset indent
+PID=$(jobid -p %1)
+.Ed
+.Pp
+the table is only actually cleared in a sub-shell when needed to
+create the first job there (built-in commands run in the foreground
+do not create jobs.)
+Note that in this environment, there is no useful current job
+.Dq ( Li \&%%
+actually refers to the sub-shell itself, but is not accessible)
+but the job which is the current job in the parent can be accessed as
+.Dq Li \&%\- .
+.\"
+.\"
+.Ss Command Line Editing
+.\"
+When
+.Nm
+is being used interactively from a terminal, the current command
+and the command history (see
+.Ic fc
+in the
+.Sx Built-ins
+section)
+can be edited using emacs-mode or vi-mode command-line editing.
+The command
+.Ql set -o emacs
+(or
+.Fl E
+option)
+enables emacs-mode editing.
+The command
+.Ql set -o vi
+(or
+.Fl V
+option)
+enables vi-mode editing and places the current shell process into
+vi insert mode.
+(See the
+.Sx Argument List Processing
+section above.)
+.Pp
+The vi-mode uses commands similar to a subset of those described in the
+.Xr vi 1
+man page.
+With vi-mode
+enabled,
+.Nm sh
+can be switched between insert mode and command mode.
+It's similar to
+.Ic vi :
+pressing the
+.Aq ESC
+key will throw you into vi command mode.
+Pressing the
+.Aq return
+key while in command mode will pass the line to the shell.
+.Pp
+The emacs-mode uses commands similar to a subset available in the
+.Ic emacs
+editor.
+With emacs-mode enabled, special keys can be used to modify the text
+in the buffer using the control key.
+.Pp
+.Nm
+uses the
+.Xr editline 3
+library.
+See
+.Xr editline 7
+for a list of the possible command bindings,
+and the default settings in emacs and vi modes.
+Also see
+.Xr editrc 5
+for the commands that can be given to configure
+.Xr editline 7
+in the file named by the
+.Ev EDITRC
+parameter,
+or a file used with the
+.Ic inputrc
+built-in command,
+or using
+.Xr editline 7 Ap s
+configuration command line.
+.Pp
+When command line editing is enabled, the
+.Xr editline 7
+functions control printing of the
+.Ev PS1
+and
+.Ev PS2
+prompts when required.
+As, in this mode, the command line editor needs to
+keep track of what characters are in what position on
+the command line, care needs to be taken when setting
+the prompts.
+Normal printing characters are handled automatically,
+however mode setting sequences, which do not actually display
+on the terminal, need to be identified to
+.Xr editline 7 .
+This is done, when needed, by choosing a character that
+is not needed anywhere in the prompt, including in the mode
+setting sequences, any single character is acceptable,
+and assigning it to the shell parameter
+.Dv PSlit .
+Then that character should be used, in pairs, in the
+prompt string.
+Between each pair of
+.Dv PSlit
+characters are mode setting sequences, which affect the printing
+attributes of the following (normal) characters of the prompt,
+but do not themselves appear visibly, nor change the terminal's
+cursor position.
+.Pp
+Each such sequence, that is
+.Dv PSlit
+character, mode setting character sequence, and another
+.Dv PSlit
+character, must currently be followed by at least one following
+normal prompt character, or it will be ignored.
+That is, a
+.Dv PSlit
+character cannot be the final character of
+.Ev PS1
+or
+.Ev PS2 ,
+nor may two
+.Dv PSlit
+delimited sequences appear adjacent to each other.
+Each sequence can contain as many mode altering sequences as are
+required however.
+Only the first character from
+.Dv PSlit
+will be used.
+When set
+.Dv PSlit
+should usually be set to a string containing just one
+character, then it can simply be embedded in
+.Ev PS1
+(or
+.Ev PS2 )
+as in
+.Pp
+.D1 Li PS1=\*q${PSlit} Ns Ar mset\^ Ns Li ${PSlit}XYZ${PSlit} Ns Ar mclr\^ Ns Li ${PSlit}ABC\*q
+.Pp
+The prompt visible will be
+.Dq XYZABC
+with the
+.Dq XYZ
+part shown according as defined by the mode setting characters
+.Ar mset ,
+and then cleared again by
+.Ar mclr .
+See
+.Xr tput 1
+for one method to generate appropriate mode sequences.
+Note that both parts, XYZ and ABC, must each contain at least one
+character.
+.Pp
+If
+.Dv PSlit
+is unset, which is its initial state, or set to a null string,
+no literal character will be defined,
+and all characters of the prompt strings will be assumed
+to be visible characters (which includes spaces etc.)
+To allow smooth use of prompts, without needing redefinition, when
+.Xr editline 7
+is disabled, the character chosen should be one which will be
+ignored by the terminal if received, as when
+.Xr editline 7
+is not in use, the prompt strings are simply written to the terminal.
+For example, setting:
+.\" XXX: PS1 line is too long for -offset indent
+.Bd -literal -offset left
+  PSlit="$(printf\ '\e1')"
+  PS1="${PSlit}$(tput\ bold\ blink)${PSlit}\e$${PSlit}$(tput\ sgr0)${PSlit}\ "
+.Ed
+.Pp
+will arrange for the primary prompt to be a bold blinking dollar sign,
+if supported by the current terminal, followed by an (ordinary) space,
+and, as the SOH (control-A) character
+.Pq Sq \e1
+will not normally affect
+a terminal, this same prompt will usually work with
+.Xr editline 7
+enabled or disabled.
+.Sh ENVIRONMENT
+.Bl -tag -width MAILCHECK
+.It Ev CDPATH
+The search path used with the
+.Ic cd
+built-in.
+.It Ev EDITRC
+Gives the name of the file containing commands for
+.Xr editline 7 .
+See
+.Xr editrc 5
+for possible content and format.
+The file is processed, when in interactive mode with
+command line editing enabled, whenever
+.Ev EDITRC
+is set (even with no actual value change,)
+and if command line editing changes from disabled to enabled,
+or the editor style used is changed.
+(See the
+.Fl E
+and
+.Fl V
+options of the
+.Ic set
+built-in command, described in
+.Sx Built-ins
+above, which are documented further above in
+.Sx Argument List Processing . )
+If unset
+.Dq $HOME/.editrc
+is used.
+.It Ev ENV
+Names the file sourced at startup by the shell.
+Unused by this shell after initialization,
+but is usually passed through the environment to
+descendant shells.
+.It Ev EUSER
+Set to the login name of the effective user id running the shell,
+as returned by
+.Bd -compact -literal -offset indent
+getpwuid(geteuid())->pw_name
+.Ed
+.Po
+See
+.Xr getpwuid 3
+and
+.Xr geteuid 2
+for more details.
+.Pc
+This is obtained each time
+.Ev EUSER
+is expanded, so changes to the shell's execution identity
+cause updates without further action.
+If unset, it returns nothing.
+If set it loses its special properties, and is simply a variable.
+.It Ev HISTSIZE
+The number of lines in the history buffer for the shell.
+.It Ev HOME
+Set automatically by
+.Xr login 1
+from the user's login directory in the password file
+.Pq Xr passwd 5 .
+This environment variable also functions as the default argument for the
+.Ic cd
+built-in.
+.It Ev HOSTNAME
+Set to the current hostname of the system, as returned by
+.Xr gethostname 3 .
+This is obtained each time
+.Ev HOSTNAME
+is expanded, so changes to the system's name are reflected
+without further action.
+If unset, it returns nothing.
+If set it loses its special properties, and is simply a variable.
+.It Ev IFS
+Input Field Separators.
+This is normally set to
+.Aq space ,
+.Aq tab ,
+and
+.Aq newline .
+See the
+.Sx White Space Splitting
+section for more details.
+.It Ev LANG
+The string used to specify localization information that allows users
+to work with different culture-specific and language conventions.
+See
+.Xr nls 7 .
+.It Dv LINENO
+The current line number in the script or function.
+See the section
+.Sx LINENO
+below for more details.
+.It Ev MAIL
+The name of a mail file, that will be checked for the arrival of new mail.
+Overridden by
+.Ev MAILPATH .
+The check occurs just before
+.Ev PS1
+is written, immediately after reporting jobs which have changed status,
+in interactive shells only.
+New mail is considered to have arrived if the monitored file
+has increased in size since the last check.
+.\" .It Ev MAILCHECK
+.\" The frequency in seconds that the shell checks for the arrival of mail
+.\" in the files specified by the
+.\" .Ev MAILPATH
+.\" or the
+.\" .Ev MAIL
+.\" file.
+.\" If set to 0, the check will occur at each prompt.
+.It Ev MAILPATH
+A colon
+.Dq \&:
+separated list of file names, for the shell to check for incoming mail.
+This environment setting overrides the
+.Ev MAIL
+setting.
+There is a maximum of 10 mailboxes that can be monitored at once.
+.It Ev PATH
+The default search path for executables.
+See the
+.Sx Path Search
+section above.
+.It Ev POSIXLY_CORRECT
+If set in the environment upon initialization of the shell,
+then the shell option
+.Ic posix
+will be set.
+.Po
+See the description of the
+.Ic set
+command in the
+.Sx Built-ins
+section.
+.Pc
+After initialization it is unused by the shell,
+but is usually passed through the environment to
+descendant processes, including other instances of the shell,
+which may interpret it in a similar way.
+.It Ev PPID
+The process identified of the parent process of the
+current shell.
+This value is set at shell startup, ignoring
+any value in the environment, and then made readonly.
+.It Ev PS1
+The primary prompt string, which defaults to
+.Dq Li "$ " ,
+unless you are the superuser, in which case it defaults to
+.Dq Li "# " .
+This string is subject to parameter, arithmetic, and if
+enabled by setting the
+.Ic promptcmds
+option, command substitution before being output.
+During execution of commands used by command substitution,
+execution tracing, the
+.Ic xtrace
+.Ic ( set Fl x )
+option is temporarily disabled.
+If
+.Ic promptcmds
+is not set and the prompt string uses command substitution,
+the prompt used will be an appropriate error string.
+For other expansion errors, a message will be output,
+and the unexpanded string will then be used as the prompt.
+.It Ev PS2
+The secondary prompt string, which defaults to
+.Dq Li "> " .
+After expansion (as for
+.Ev PS1 )
+it is written whenever more input is required to complete the
+current command.
+.It Ev PS4
+Output, after expansion like
+.Ev PS1 ,
+before each line when execution trace
+.Ic ( set Fl x )
+is enabled.
+.Ev PS4
+defaults to
+.Dq Li "+ " .
+.It Ev PSc
+Initialized by the shell, ignoring any value from the environment,
+to a single character string, either
+.Sq \&#
+or
+.Sq \&$ ,
+depending upon whether the current user is the superuser or not.
+This is intended for use when building a custom
+.Ev PS1 .
+.It Ev PSlit
+Defines the character which may be embedded in pairs, in
+.Ev PS1
+or
+.Ev PS2
+to indicate to
+.Xr editline 7
+that the characters between each pair of occurrences of the
+.Dv PSlit
+character will not appear in the visible prompt, and will not
+cause the terminal's cursor to change position, but rather set terminal
+attributes for the following prompt character(s) at least one of
+which must be present.
+See
+.Sx Command Line Editing
+above for more information.
+.It Ev RANDOM
+Returns a different pseudo-random integer,
+in the range [0,32767] each time it is accessed.
+.Ev RANDOM
+can be assigned an integer value to seed the PRNG.
+If the value assigned is a constant, then the
+sequence of values produces on subsequent references of
+.Ev RANDOM
+will repeat after the next time the same constant is assigned.
+Note, this is not guaranteed to remain constant from one version
+of the shell to another \(en the PRNG algorithm, or seeding
+method is subject to change.
+If
+.Ev RANDOM
+is assigned an empty value (null string) then the next time
+.Ev RANDOM
+is accessed, it will be seeded from a more genuinely random source.
+The sequence of pseudo-random numbers generated will not be able to
+be generated again (except by luck, whether good or bad, depends!)
+This is also how the initial seed is generated, if none has been
+assigned before
+.Ev RANDOM
+is first accessed after shell initialization.
+Should the error message
+.Dq "RANDOM initialisation failed"
+appear on standard error, it indicates that the source
+of good random numbers was not available, and
+.Ev RANDOM
+has instead been seeded with a more predictable value.
+The following sequence of random numbers will
+not be as unpredictable as they otherwise would be.
+.It Ev SECONDS
+Returns the number of seconds since the current shell was started.
+If unset, it remains unset, and returns nothing, unless set again.
+If set, it loses its special properties, and becomes a normal variable.
+.It Ev START_TIME
+Initialized by the shell to the number of seconds since the Epoch
+(see
+.Xr localtime 3 )
+when the shell was started.
+The value of
+.Dl $(( Ns Ev START_TIME + Ev SECONDS Ns ))
+represents the current time, if
+.Ev START_TIME
+has not been modified, and
+.Ev SECONDS
+has not been set or unset.
+.It Ev TERM
+The default terminal setting for the shell.
+This is inherited by
+children of the shell, and is used in the history editing modes.
+.\" This is explicitly last, not in sort order - please leave!
+.It Ev ToD
+When referenced, uses the value of
+.Ev ToD_FORMAT
+(or
+.Dq \&%T
+if
+.Ev ToD_FORMAT
+is unset) as the format argument to
+.Xr strftime 3
+to encode the current time of day, in the time zone
+defined by
+.Ev TZ
+if set, or current local time if not, and returns the result.
+If unset
+.Ev ToD
+returns nothing.
+If set, it loses its special properties, and becomes a normal variable.
+.It Ev ToD_FORMAT
+Can be set to the
+.Xr strftime 3
+format string to be used when expanding
+.Ev ToD .
+Initially unset.
+.It Ev TZ
+If set, gives the time zone
+(see
+.Xr localtime 3 ,
+.Xr environ 7 )
+to use when formatting
+.Ev ToD
+and if exported, other utilities that deal with times.
+If unset, the system's local wall clock time zone is used.
+.It Ev NETBSD_SHELL
+Unlike the variables previously mentioned,
+this variable is somewhat strange,
+in that it cannot be set,
+inherited from the environment,
+modified, or exported from the shell.
+If set, by the shell, it indicates that the shell is the
+.Ic sh
+defined by this manual page, and gives its version information.
+It can also give information in additional space separated words,
+after the version string.
+If the shell was built as part of a reproducible build,
+the relevant date that was used for that build will be included.
+Finally, any non-standard compilation options,
+which may affect features available,
+that were used when building the shell will be listed.
+.Ev NETBSD_SHELL
+behaves like any other variable that has the read-only
+and un-exportable attributes set.
+.El
+.Ss Dv LINENO
+.Dv LINENO
+is in many respects a normal shell variable, containing an
+integer value. and can be expanded using any of the forms
+mentioned above which can be used for any other variable.
+.Pp
+.Dv LINENO
+can be exported, made readonly, or unset, as with any other
+variable, with similar effects.
+Note that while being readonly prevents later attempts to
+set, or unset,
+.Dv LINENO ,
+it does not prevent its value changing.
+References to
+.Dv LINENO
+.Pq "when not unset"
+always obtain the current line number.
+However,
+.Dv LINENO
+should normally not ever be set or unset.
+In this shell setting
+.Dv LINENO
+reverses the effect of an earlier
+.Ic unset ,
+but does not otherwise affect the value obtained.
+If unset,
+.Dv LINENO
+should not normally be set again, doing so is not portable.
+If
+.Dv LINENO
+is set or unset, different shells act differently.
+The value of
+.Dv LINENO
+is never imported from the environment when the shell is
+started, though if present there, as with any other variable,
+.Dv LINENO
+will be exported by this shell.
+.Pp
+.Dv LINENO
+is set automatically by the shell to be the number of the source
+line on which it occurs.
+When exported,
+.Dv LINENO
+is exported with its value set to the line number it would have
+had had it been referenced on the command line of the command to
+which it is exported.
+Line numbers are counted from 1, which is the first line the shell
+reads from any particular file.
+For this shell, standard input, including in an interactive shell,
+the user's terminal, is just another file and lines are counted
+there as well.
+However note that not all shells count interactive
+lines this way, it is not wise to rely upon
+.Dv LINENO
+having a useful value, except in a script, or a function.
+.Pp
+The role of
+.Dv LINENO
+in functions is less clear.
+In some shells,
+.Dv LINENO
+continues to refer to the line number in the script which defines
+the function,
+in others lines count from one within the function, always (and
+resume counting normally once the function definition is complete)
+and others count in functions from one if the function is defined
+interactively, but otherwise just reference the line number in the
+script in which the function is defined.
+This shell gives the user the option to choose.
+If the
+.Fl L
+flag (the
+.Ic local_lineno
+option, see
+.Sx Argument List Processing )
+is set, when the function is defined, then the function
+defaults to counting lines with one being the first line of the
+function.
+When the
+.Fl L
+flag is not set, the shell counts lines in a function definition
+in the same continuous sequence as the lines that surround the
+function definition.
+Further, if
+.Dv LINENO
+is made local
+(see
+.Sx Built-ins
+above)
+inside the function, the function can decide which
+behavior it prefers.
+If
+.Dv LINENO
+is made local and inherited, and not given a value, as in
+.Dl local Fl I Dv LINENO
+then from that point in the function,
+.Dv LINENO
+will give the line number as if lines are counted in sequence
+with the lines that surround the function definition (and
+any other function definitions in which this is nested.)
+If
+.Dv LINENO
+is made local, and in that same command, given a value, as
+.Dl local Oo Fl I Ns | Ns Fl N Oc Dv LINENO Ns = Ns Ar value
+then
+.Dv LINENO
+will give the line number as if lines are counted from one
+from the beginning of the function.
+The value nominally assigned in this case is irrelevant, and ignored.
+For completeness, if lineno is made local and unset, as in
+.Dl local Fl N Dv LINENO
+then
+.Dv LINENO
+is simply unset inside the function, and gives no value at all.
+.Pp
+Now for some technical details.
+The line on which
+.Dv LINENO
+occurs in a parameter expansion, is the line that contains the
+.Sq \&$
+that begins the expansion of
+.Dv LINENO .
+In the case of nested expansions, that
+.Sq \&$
+is the one that actually has
+.Dv LINENO
+as its parameter.
+In an arithmetic expansion, where no
+.Sq \&$
+is used to evaluate
+.Dv LINENO
+but
+.Dv LINENO
+is simply referenced as a variable, then the value is the
+line number of the line that contains the
+.Sq L
+of
+.Dv LINENO .
+For functions line one of the function definition (when relevant)
+is the line that contains the first character of the
+function name in the definition.
+When exported, the line number of the command is the line number
+where the first character of the word which becomes the command name occurs.
+.Pp
+When the shell opens a new file, for any reason,
+it counts lines from one in that file,
+and then resumes its original counting once it resumes reading the
+previous input stream.
+When handling a string passed to
+.Ic eval
+the line number starts at the line on which the string starts,
+and then if the string contains internal newline characters,
+those characters increase the line number.
+This means that references to
+.Dv LINENO
+in such a case can produce values larger than would be
+produced by a reference on the line after the
+.Ic eval .
+.Sh FILES
+.Bl -item
+.It
+.Pa $HOME/.profile
+.It
+.Pa /etc/profile
+.El
+.Sh EXIT STATUS
+Errors that are detected by the shell, such as a syntax error, will cause the
+shell to exit with a non-zero exit status.
+If the shell is not an
+interactive shell, the execution of the shell file will be aborted.
+Otherwise
+the shell will return the exit status of the last command executed, or
+if the exit built-in is used with a numeric argument, it will return the
+argument.
+.Sh SEE ALSO
+.Xr csh 1 ,
+.Xr echo 1 ,
+.Xr getopt 1 ,
+.Xr ksh 1 ,
+.Xr login 1 ,
+.Xr printf 1 ,
+.Xr test 1 ,
+.Xr editline 3 ,
+.Xr getopt 3 ,
+.\" .Xr profile 4 ,
+.Xr editrc 5 ,
+.Xr passwd 5 ,
+.Xr editline 7 ,
+.Xr environ 7 ,
+.Xr nls 7 ,
+.Xr sysctl 8
+.Sh HISTORY
+A
+.Nm
+command appeared in
+.At v1 .
+It was replaced in
+.At v7
+with a version that introduced the basis of the current syntax.
+That was, however, unmaintainable so we wrote this one.
+.Sh BUGS
+Setuid shell scripts should be avoided at all costs, as they are a
+significant security risk.
+.Pp
+The characters generated by filename completion should probably be quoted
+to ensure that the filename is still valid after the input line has been
+processed.
+.Pp
+Job control of compound statements (loops, etc) is a complete mess.
+.Pp
+Many, many, more.
+(But less than there were...)