Module Name: src
Committed By: kre
Date: Fri May 12 08:39:47 UTC 2017
Modified Files:
src/bin/sh: sh.1
Log Message:
Corrected some typos, added some (hopefully improving) extra text,
sorted stuff that needed sorting, and added some (probably incorrect)
markup...
To generate a diff of this commit:
cvs rdiff -u -r1.136 -r1.137 src/bin/sh/sh.1
Please note that diffs are not public domain; they are subject to the
copyright notices on the relevant files.
Modified files:
Index: src/bin/sh/sh.1
diff -u src/bin/sh/sh.1:1.136 src/bin/sh/sh.1:1.137
--- src/bin/sh/sh.1:1.136 Sun May 7 15:01:18 2017
+++ src/bin/sh/sh.1 Fri May 12 08:39:47 2017
@@ -1,4 +1,4 @@
-.\" $NetBSD: sh.1,v 1.136 2017/05/07 15:01:18 kre Exp $
+.\" $NetBSD: sh.1,v 1.137 2017/05/12 08:39:47 kre Exp $
.\" Copyright (c) 1991, 1993
.\" The Regents of the University of California. All rights reserved.
.\"
@@ -31,7 +31,7 @@
.\"
.\" @(#)sh.1 8.6 (Berkeley) 5/4/95
.\"
-.Dd May 7, 2017
+.Dd May 12, 2017
.Dt SH 1
.ds flags abCEeFfhnuvxIimpqV
.Os
@@ -90,12 +90,6 @@ 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 ) .
-Only features designated by
-.Tn POSIX ,
-plus a few Berkeley extensions, are being incorporated into this shell.
-.\" We expect
-.\" .Tn POSIX
-.\" conformance by the time 4.4 BSD is released.
This man page is not intended
to be a tutorial or a complete specification of the shell.
.Ss Overview
@@ -116,8 +110,9 @@ 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 of the shell
-is connected to a terminal (or if the
+If no arguments are present and if the standard input,
+and output, of the shell
+are connected to a terminal (or if the
.Fl i
flag is set),
and the
@@ -140,9 +135,14 @@ and
if they exist.
If the environment variable
.Ev ENV
-is set on entry to a shell, or is set in the
+is set on entry to a shell,
+or is set in the
.Pa .profile
-of a login shell, the shell next reads
+of a login shell,
+and either the shell is interactive, or the
+.Cm posix
+option is not set,
+the shell next reads
commands from the file named in
.Ev ENV .
Therefore, a user should place commands that are to be executed only at
@@ -164,7 +164,7 @@ substituting for
any filename you wish.
Since the
.Ev ENV
-file is read for every invocation of the shell, including shell scripts
+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
@@ -215,6 +215,9 @@ built-in (described later).
.Bl -tag -width aaaallexportfoo -offset indent
.It Fl a Em allexport
Export all variables assigned to.
+.It Fl b Em notify
+Enable asynchronous notification of background job completion.
+(Not implemented.)
.It Fl c
Read commands from the
.Ar command_string
@@ -253,55 +256,6 @@ With pipelines, only the status of the e
is tested when
.Fl e
is set to determine if the shell should exit.
-.It Fl f Em noglob
-Disable pathname expansion.
-.It Fl n Em noexec
-If not interactive, read commands but do not execute them.
-This is useful for checking the syntax of shell scripts.
-.It Fl u Em nounset
-Write a message to standard error when attempting to expand a variable
-that is not set, and if the shell is not interactive, exit immediately.
-.It Fl v Em verbose
-The shell writes its input to standard error as it is read.
-Useful for debugging.
-.It Fl x Em xtrace
-Write each command to standard error (preceded by a
-.Sq +\ )
-before it is executed.
-Useful for debugging.
-.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 I Em ignoreeof
-Ignore EOFs from input when interactive.
-.It Fl i Em interactive
-Force the shell to behave interactively.
-.It Fl m Em monitor
-Turn on job control (set automatically when interactive).
-.It Fl s Em stdin
-Read commands from standard input (set automatically if no file arguments
-are present).
-This option has no effect when set or reset after the shell has
-already started running (i.e. with
-.Ic set ) .
-.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 E Em emacs
Enable the built-in emacs style
command line editor (disables
@@ -310,9 +264,8 @@ if it has been set).
(See the
.Sx Command Line Editing
section below.)
-.It Fl b Em notify
-Enable asynchronous notification of background job completion.
-(Not implemented.)
+.It Fl f Em noglob
+Disable pathname expansion.
.It Fl F Em fork
Cause the shell to always use
.Xr fork 2
@@ -333,6 +286,15 @@ Bind commands in functions to file syste
When off,
the file system is searched for commands each time the function is invoked.
(Not implemented.)
+.It Fl i Em interactive
+Force the shell to behave interactively.
+.It Fl I Em ignoreeof
+Ignore EOFs from input when interactive.
+.It Fl m Em monitor
+Turn on job control (set automatically when interactive).
+.It Fl n Em noexec
+If not interactive, read commands but do not execute them.
+This is useful for checking the syntax of shell scripts.
.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
@@ -340,6 +302,44 @@ 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 no file arguments
+are present).
+This option has no effect when set or reset after the shell has
+already started running (i.e. with
+.Ic set ) .
+.It Fl u Em nounset
+Write a message to standard error when attempting to expand a variable
+that is not set, and if the shell is not interactive, exit immediately.
+.It Fl v Em verbose
+The shell writes its input to standard error as it is read.
+Useful for debugging.
+.It Fl x Em xtrace
+Write each command to standard error (preceded by a
+.Sq +\ )
+before it is executed.
+Useful for debugging.
+.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 "\ \ " Em cdprint
Make an interactive shell always print the new directory name when
changed by the
@@ -365,9 +365,12 @@ Currently this option controls whether (
the file given by the
.Ev ENV
variable is read at startup by a non-interactive shell.
-Consequently, while it can be manipulated by the
-.Ic set
-command, doing so has no current purpose.
+It also controls whether the shell treats
+an empty compound statement as a syntax error (required
+by posix) or permits it.
+Empty compound statements
+.Dq "{ }"
+can be useful when defining dummy functions.
.It "\ \ " Em tabcomplete
Enables filename completion in the command line editor.
Typing a tab character will extend the current input word to match a
@@ -387,7 +390,7 @@ characters that are special to the shell
.Dq operators .
There are two types of operators: control operators and redirection
operators (their meaning is discussed later).
-Following is a list of operators:
+The following is a list of operators:
.Bl -ohang -offset indent
.It "Control operators:"
.Dl \*[Am] \*[Am]\*[Am] \&( \&) \&; ;; | || \*[Lt]newline\*[Gt]
@@ -400,12 +403,12 @@ words to the shell, such as operators, w
There are three types of quoting: matched single quotes,
matched double quotes, and backslash.
.Ss Backslash
-A backslash preserves the literal meaning of the following
+An unquoted backslash preserves the literal meaning of the following
character, with the exception of
.Aq newline .
-A backslash preceding a
+An unquoted backslash preceding a
.Aq newline
-is treated as a line continuation.
+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
@@ -419,26 +422,28 @@ backquote
and backslash
.Pq \e .
The backslash inside double quotes is historically weird, and serves to
-quote only the following characters:
-.Dl $ ` \*q \e \*[Lt]newline\*[Gt] .
+quote only the following characters (and these not in all contexts):
+.Dl $ ` \*q \e \*[Lt]newline\*[Gt] ,
+where a backslash newline is a line continuation as above.
Otherwise it remains literal.
.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 while -offset indent
-.It ! Ta elif Ta fi Ta while Ta case
-.It else Ta for Ta then Ta { Ta }
-.It do Ta done Ta until Ta if Ta esac
+.Bl -column while while while while -offset indent
+.It ! Ta { Ta } Ta case
+.It do Ta done Ta elif Ta else
+.It esac Ta fi Ta for Ta if
+.It in Ta then Ta until Ta while
.El
.Pp
-Their meaning is discussed later.
+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 may occur (see above),
+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.
@@ -457,7 +462,7 @@ would become
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 discouraged.
+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
@@ -476,21 +481,23 @@ the following actions:
.It
Leading words of the form
.Dq name=value
-are stripped off and assigned to the environment of the simple command.
+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.
+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,
-and the first remaining word is considered the command name and the
+section below.
+The first remaining word is considered the command name and the
command is located.
-The remaining words are considered the arguments of the command.
+Any remaining words are considered the arguments of the command.
If no command name resulted, then the
.Dq name=value
variable assignments recognized in item 1 affect the current shell.
.It
-Redirections are performed as described in the next section.
+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
@@ -504,7 +511,7 @@ The overall format used for redirection
where
.Va redir-op
is one of the redirection operators mentioned previously.
-Following is a list of the possible redirections.
+The following is a list of the possible redirections.
The
.Bq n
is an optional number, as in
@@ -512,19 +519,27 @@ is an optional number, as in
(not
.Sq Bq 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 [n] Ns \*[Gt] file
-Redirect standard output (or n) to file.
+Redirect standard output (or n) to
+.Cm file .
.It [n] Ns \*[Gt]| file
-Same, but override the
+The same, but override the
.Fl C
option.
.It [n] Ns \*[Gt]\*[Gt] file
-Append standard output (or n) to file.
+Append standard output (or n) to
+.Cm file .
.It [n] Ns \*[Lt] file
-Redirect standard input (or n) from file.
+Redirect standard input (or n) from
+.Cm file .
.It [n1] Ns \*[Lt]\*[Am] Ns n2
Duplicate standard input (or n1) from file descriptor n2.
+.Cm n2
+is expanded if not a digit string, the result must be a number.
.It [n] Ns \*[Lt]\*[Am]-
Close standard input (or n).
.It [n1] Ns \*[Gt]\*[Am] Ns n2
@@ -532,7 +547,9 @@ Duplicate standard output (or n1) to n2.
.It [n] Ns \*[Gt]\*[Am]-
Close standard output (or n).
.It [n] Ns \*[Lt]\*[Gt] file
-Open file for reading and writing on standard input (or n).
+Open
+.Cm file
+for reading and writing on standard input (or n).
.El
.Pp
The following redirection is often called a
@@ -544,6 +561,16 @@ The following redirection is often calle
.Li delimiter
.El
.Pp
+The
+.Dq here-doc-text
+starts immediately after the next unquoted newline character following
+the here-doc 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-doc 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
@@ -551,7 +578,11 @@ saved away and made available to the com
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
-subjected to parameter expansion, command substitution, and arithmetic
+treated much like a double quoted string, except that
+.Sq \&"
+characters have no special meaning, and are not escaped by
+.Sq \&\e ,
+and is subjected to parameter expansion, command substitution, and arithmetic
expansion as described in the
.Sx Word Expansions
section below.
@@ -565,9 +596,15 @@ If the delimiter is not quoted, lines in
an unquoted \e are joined to the following line, the \e and following
newline are simply removed while reading the here-doc, 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 -- 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
@@ -575,11 +612,13 @@ When a shell function is executed, all o
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.
+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 are restored to their original values
-when the command completes.
-This all occurs within the current shell.
+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.
.Pp
Shell built-ins are executed internally to the shell, without spawning a
new process.
@@ -589,14 +628,14 @@ command is searched for as a normal prog
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 (i.e., if it does
+If the program is not a normal executable file, and if it does
not begin with the "magic number" whose
.Tn ASCII
representation is "#!", so
.Xr execve 2
returns
.Er ENOEXEC
-then) the shell will interpret the program in a subshell.
+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
@@ -616,7 +655,7 @@ If a built-in command is not found, one
Command names containing a slash are simply executed without performing
any searches.
.It
-The shell searches each entry in
+Otherwise, the shell searches each entry in
.Ev PATH
in turn for the command.
The value of the
@@ -625,12 +664,16 @@ variable should be a series of entries s
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 for normal or success, and non-zero for failure,
+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.
@@ -640,6 +683,10 @@ an executed shell function.
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.
@@ -661,7 +708,11 @@ Unless otherwise stated, the exit status
simple command executed by the command.
.Ss Pipelines
A pipeline is a sequence of one or more commands separated
-by the control operator |.
+by the control operator
+.Sq \&| ,
+and optionally preceded by the
+.Dq \&!
+reserved word.
The standard output of all but
the last command is connected to the standard input
of the next command.
@@ -676,7 +727,7 @@ The standard output of command1 is conne
command2.
The standard input, standard output, or both of a command is
considered to be assigned by the pipeline before any redirection specified
-by redirection operators that are part of the command.
+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.
@@ -703,6 +754,12 @@ A ; or
terminator causes the preceding AND-OR-list (described
next) to be executed sequentially; a \*[Am] causes asynchronous execution of
the preceding AND-OR-list.
+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
+.Cm wait
+built-in command described later.
.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
@@ -726,13 +783,18 @@ background can be obtained from the valu
(see
.Sx Special Parameters ) .
.Ss Lists -- Generally Speaking
-A list is a sequence of zero or more commands separated by newlines,
+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.
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 \&;
+when no other operator is present, and the command being input
+could syntatically correctly be terminated at the point where
+the newline is encountered, otherwise it is just whitespace.
.Ss Short-Circuit List Operators
.Dq \*[Am]\*[Am]
and
@@ -764,6 +826,19 @@ then list ] ...
[ else list ]
fi
.Ed
+The first list is executed, and if the exit status of that list is zero,
+the list following the
+.Cm then
+is executed.
+Otherwise the list after an
+.Cm elif
+(if any) is executed and the process repeats.
+When no more
+.Cm elif
+reserved words, and accompanying lists, appear,
+the list after the
+.Cm else
+reserved word, if any, is executed.
.Pp
The syntax of the while command is
.Bd -literal -offset indent
@@ -794,15 +869,20 @@ and
.Dq } ,
but doing so is non-standard and not recommended.
.Pp
-The syntax of the break and continue command is
+The syntax of the break and continue commands is
.Bd -literal -offset indent
break [ num ]
continue [ num ]
.Ed
.Pp
-Break terminates the num innermost for or while loops.
-Continue continues with the next iteration of the innermost loop.
+Break terminates the num innermost for, while or until loops.
+Continue breaks execution of the num\-1 innermost for, while, or until
+loops, and then continues with the next iteration of the enclosing loop.
These are implemented as built-in commands.
+The parameter
+.Cm num ,
+if given, must be an unsigned positive integer (greater than zero).
+If not given, 1 is used.
.Pp
The syntax of the case command is
.Bd -literal -offset indent
@@ -846,9 +926,16 @@ or
.Pp
.Dl { list; }
.Pp
-The first of these executes the commands in a subshell.
+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 (list) will not affect the current shell.
-The second form does not fork another shell so is slightly more efficient.
+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
@@ -872,7 +959,7 @@ The command is normally a list enclosed
and
.Dq } .
The standard syntax also allows the command to be any of the other
-compound commands, or a sub-shell, all of which are supported.
+compound commands, including a sub-shell, all of which are supported.
As an extension, this shell also allows a simple command to be
used, though users should be aware this is non-standard syntax.
This means that
@@ -909,9 +996,11 @@ each time the shell executes the functio
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 a local
+Variables may be declared to be local to a function by using a
+.Cm local
command.
-This should appear as the first statement of a function, and the syntax is
+This should usually appear as the first statement of a function,
+its syntax is
.Pp
.Dl local [ variable | - ] ...
.Pp
@@ -952,7 +1041,7 @@ function to represent the options and ar
Note that $0 however retains the value it had outside the function,
as do all the other special parameters.
.Pp
-The only special parameter that can be made local is
+The only other special parameter that can be made local is
.Dq - .
Making
.Dq -
@@ -984,7 +1073,7 @@ immediately before the return was execut
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.
+variables into shell variables, and exports them.
New variables can be set using the form
.Pp
.Dl name=value
@@ -1056,14 +1145,14 @@ the two arguments:
Expands to the number of positional parameters.
.It \&?
Expands to the exit status of the most recent pipeline.
-.It - (Hyphen.)
+.It \- (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 $
Expands to the process ID of the invoked shell.
-A subshell retains the same value of $ as its parent.
+A sub-shell retains the same value of $ as its parent.
.It \&!
Expands to the process ID of the most recent background
command executed from the current shell.
@@ -1113,10 +1202,10 @@ 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.
-All the characters up to
-a slash (/) or the end of the word are treated as a username
-and are replaced with the user's home directory.
-If the username is missing (as in
+All the following characters in the word up to
+a slash (/) or the end of the word are treated as a user name
+and are replaced with 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
.Va HOME
@@ -1141,8 +1230,9 @@ The simplest form for parameter expansio
.Pp
The value, if any, of parameter is substituted.
.Pp
-The parameter name or symbol can be enclosed in braces, which are
-optional except for positional parameters with more than one digit or
+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:
@@ -1154,12 +1244,12 @@ Field splitting is not performed on the
expansion, with the exception of the special rules for @.
.El
.Pp
-In addition, a parameter expansion can be modified by using one of the
-following formats.
+In addition, a parameter expansion where braces are used,
+can be modified by using one of the following formats.
If the
.Dq Dv \&:
-is omitted in the following modifiers, then the expansion is applied only
-to unset parameters, not null ones.
+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 ${parameter:\(miword}
Use Default Values.
@@ -1176,13 +1266,16 @@ parameters, can be assigned in this way.
Indicate Error if Null or Unset.
If parameter is unset or null, the
expansion of word (or a message indicating it is unset if word is omitted)
-is written to standard error and the shell exits with a nonzero exit status.
-Otherwise, the value of parameter is substituted.
-An interactive shell need not exit.
+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 parameter is set, its value is substituted.
.It ${parameter:+word}
Use Alternative Value.
If parameter is unset or null, null is
substituted; otherwise, the expansion of word is substituted.
+The value of parameter is not used in this expansion.
.It ${#parameter}
String Length.
The length in characters of the value of parameter.
@@ -1203,25 +1296,43 @@ Remove Smallest Suffix Pattern.
The word is expanded to produce a pattern.
The parameter expansion then results in parameter, with the
smallest portion of the suffix matched by the pattern deleted.
+If the word is to start with a
+.Sq \&%
+character, it must be quoted.
.It ${parameter%%word}
Remove Largest Suffix Pattern.
The word is expanded to produce a pattern.
The parameter expansion then results in parameter, with the largest
portion of the suffix matched by the pattern deleted.
+The
+.Dq %%
+pattern operator only produces different results from the
+.Dq \&%
+operator when the pattern contains at least one unquoted
+.Sq \&* .
.It ${parameter#word}
Remove Smallest Prefix Pattern.
The word is expanded to produce a pattern.
The parameter expansion then results in parameter, with the
smallest portion of the prefix matched by the pattern deleted.
+If the word is to start with a
+.Sq \&#
+character, it must be quoted.
.It ${parameter##word}
Remove Largest Prefix Pattern.
The word is expanded to produce a pattern.
The parameter expansion then results in parameter, with the largest
portion of the prefix matched by the pattern deleted.
+This has the same relationship with the
+.Sq \&#
+pattern operator as
+.Dq %%
+has with
+.Dq \&% .
.El
.Ss Command Substitution
Command substitution allows the output of a command to be substituted in
-place of the command name itself.
+place of the command (and surrounding syntax).
Command substitution occurs when the command is enclosed as follows:
.Pp
.Dl $(command)
@@ -1235,7 +1346,7 @@ version
.Dl `command`
.Pp
The shell expands the command substitution by executing command in a
-subshell environment and replacing the command substitution with the
+sub-shell environment and replacing the command substitution with the
standard output of the command, removing sequences of one or more
.Ao newline Ac Ns s
at the end of the substitution.
@@ -1247,7 +1358,7 @@ they may be translated into
.Ao space Ac Ns s ,
depending on the value of
.Ev IFS
-and quoting that is in effect.)
+and any quoting that is in effect.)
.Ss Arithmetic Expansion
Arithmetic expansion provides a mechanism for evaluating an arithmetic
expression and substituting its value.
@@ -1346,7 +1457,7 @@ characters that occur in
whitespace)
can occur, leading and trailing
.Ev IFS
-whitespace, and
+whitespace, and any
.Ev IFS
whitespace surrounding a non whitespace
.Ev IFS
@@ -1355,7 +1466,7 @@ Any sequence of
.Ev IFS
whitespace characters without a non-whitespace
.Ev IFS
-delimiter acts as a field separator.
+delimiter acts as a single field separator.
.Pp
If
.Ev IFS
@@ -1442,7 +1553,17 @@ in a character class, make it the first
if any).
To include a
.Dq \(mi ,
-make it the first or last character listed.
+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
@@ -1611,15 +1732,19 @@ or by using
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.
.It 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 is used.
+exit status of the preceding command (the current value of $?) is used.
.It export Oo Fl npx Oc Ar name ...
.It export Fl p Oo Fl x Oc
With no options,
+but one or mode names,
the specified names are exported so that they will appear in the
environment of subsequent commands.
With
@@ -1748,6 +1873,8 @@ The number of previous commands that are
.El
.It 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 fdflags Oo Fl v Oc Oo fd ... Oc
.It fdflags Oo Fl v Oc Fl s Ar flags fd Oo ... Oc
Get or set file descriptor flags.
@@ -1862,7 +1989,7 @@ do
\e?) echo $USAGE; exit 1;;
esac
done
-shift $(expr $OPTIND - 1)
+shift $((OPTIND - 1))
.Ed
.Pp
This code will accept any of the following as equivalent:
@@ -1927,12 +2054,12 @@ The default is
.Fl L ,
but note that the built-in
.Ic cd
-command doesn't currently support the
+command doesn't support the
.Fl L
option and will cache (almost) the absolute path.
If
.Ic cd
-is changed,
+is changed (as unlikely as that is),
.Ic pwd
may be changed to default to
.Ic pwd
@@ -1954,7 +2081,7 @@ The prompt is printed if the
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
+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
@@ -1977,7 +2104,7 @@ literally.
If a backslash is followed by a newline, the backslash and the
newline will be deleted.
.It readonly Ar name ...
-.It readonly Fl p
+.It readonly Oo Fl p Oc
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
@@ -2094,7 +2221,7 @@ If no signals are specified with an acti
.Sq - ,
all signals are reset.
.Pp
-When the shell forks off a subshell, it resets trapped (but not ignored)
+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
@@ -2204,33 +2331,33 @@ any one of these flags:
show all the current limits
.It Fl b
show or set the limit on the socket buffer size of a process (in bytes)
-.It Fl t
-show or set the limit on CPU time (in seconds)
-.It Fl f
-show or set the limit on the largest file that can be created
+.It Fl c
+show or set the limit on the largest core dump size that can be produced
(in 512-byte blocks)
.It Fl d
show or set the limit on the data segment size of a process (in kilobytes)
-.It Fl s
-show or set the limit on the stack size of a process (in kilobytes)
-.It Fl c
-show or set the limit on the largest core dump size that can be produced
+.It Fl f
+show or set the limit on the largest file that can be created
(in 512-byte blocks)
-.It Fl m
-show or set the limit on the total physical memory that can be
-in use by a process (in kilobytes)
.It Fl l
show or set the limit on how much memory a process can lock with
.Xr mlock 2
(in kilobytes)
-.It Fl r
-show or set the limit on the number of threads this user can
-have at one time
+.It Fl m
+show or set the limit on the total physical memory that can be
+in use by a process (in kilobytes)
+.It Fl n
+show or set the limit on the number of files a process can have open at once
.It Fl p
show or set the limit on the number of processes this user can
have at one time
-.It Fl n
-show or set the limit on the number of files a process can have open at once
+.It Fl r
+show or set the limit on the number of threads this user can
+have at one time
+.It Fl s
+show or set the limit on the stack size of a process (in kilobytes)
+.It Fl t
+show or set the limit on CPU time (in seconds)
.It Fl v
show or set the limit on how large a process address space can be
.El
@@ -2243,11 +2370,14 @@ the current limit is displayed.
Limits of an arbitrary process can be displayed or set using the
.Xr sysctl 8
utility.
-.It umask Op Ar mask
+.It 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 unalias Oo Fl a Oc Oo Ar name Oc
If
.Ar name
@@ -2398,6 +2528,8 @@ See
.Xr nls 7 .
.It Ev LINENO
The current line number in the script or function.
+The value of this variable is automatically set by the
+shell, even if made readonly.
.It Ev MAIL
The name of a mail file, that will be checked for the arrival of new mail.
Overridden by
@@ -2428,6 +2560,11 @@ The default search path for executables.
See the
.Sx Path Search
section above.
+.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 $ \ ,
@@ -2446,12 +2583,12 @@ 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 NETBSD_SHELL
-Unlike the variables mentioned above,
+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, it indicates that the shell is the
+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 behaves like any other variable that has the read-only
@@ -2516,9 +2653,9 @@ trap
command cannot usefully be used, yet, within a command substitution,
to obtain the current trap values,
as all command substitutions are currently executed within a
-subshell environment,
+sub-shell environment,
and in sub-shells all non-ignored, non-default, traps are reset.
-As a workaround, it is possible to redirect ooutput from
+As a workaround, it is possible to redirect output from
.Dq trap
or
.Dq trap -p
