Mechanically kill hard sentence breaks.
authorPeter Avalos <pavalos@dragonflybsd.org>
Sun, 14 Jan 2007 16:30:20 +0000 (16:30 +0000)
committerPeter Avalos <pavalos@dragonflybsd.org>
Sun, 14 Jan 2007 16:30:20 +0000 (16:30 +0000)
Fix references to non-existing or obsoleted man pages.

Use ``.Pq Ql'' to quote single characters, instead of ``.Pq Li''.
This makes the resulting output more aesthetically pleasing in
text-only terminals.

mdoc cleanups.

Add missed '.'.

Document that '#' starts a comment.

o Discuss the ways to escape an alias.
o Fix the alias syntax lines.
o Refer to the Aliases subsection.

Document that `in word ...' is optional in the for command.

Document the "return" built-in better: it will exit . (sources) and
the top-level shell instance, too.

When listing the special $ variables, ($!, $#, etc) list them as $!
instead of just !, this allows one to more easily locate/understand
the section of the manpage in question.

Document the -L and -P options to the cd and pwd commands as being
mutually exclusive.

Document command -v and -V.

Split the export synopsis into two lines as -p cannot be mixed with variable
names.

Document the fact that 'true' and 'false' are among sh(1) built-in commands.

- Move the description of the ``-c string'' option closer to the option itself.
- Add an ENVIRONMENT section (1)
- Add more .Xr cross references to the SEE ALSO section.

Add `local' and `return' to the list of built-ins.

Document that read -t timeout returns 1 if the timeout elapses.

Make it easier to find that we have test(1) built-in in sh(1).

- Document trap's -l option and the behaviour of a missing action or a single
  dash.
- Discourage the omission of the action.

Document umask's -S option.

Tell more of the sh(1) history.
Acknowledge Kenneth Almquist's contribution in AUTHORS.

Document missing multibyte character handling in utilities specified
by POSIX.

Obtained-from:  FreeBSD

bin/sh/sh.1

index 6449bfd..04082fa 100644 (file)
@@ -1,3 +1,4 @@
+.\"-
 .\" Copyright (c) 1991, 1993
 .\"    The Regents of the University of California.  All rights reserved.
 .\"
 .\" SUCH DAMAGE.
 .\"
 .\"    from: @(#)sh.1  8.6 (Berkeley) 5/4/95
-.\" $FreeBSD: src/bin/sh/sh.1,v 1.39.2.25 2003/02/13 19:28:08 fanf Exp $
-.\" $DragonFly: src/bin/sh/sh.1,v 1.7 2007/01/13 20:33:47 pavalos Exp $
+.\" $FreeBSD: src/bin/sh/sh.1,v 1.124 2006/10/07 16:51:16 stefanf Exp $
+.\" $DragonFly: src/bin/sh/sh.1,v 1.8 2007/01/14 16:30:20 pavalos Exp $
 .\"
-.Dd December 4, 2005
+.Dd October 7, 2006
 .Dt SH 1
 .Os
 .Sh NAME
@@ -57,11 +58,11 @@ The current version of
 is in the process of being changed to
 conform with the
 .St -p1003.2
-specification for the shell.  This version has many features which make
+specification 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 like
-.Xr pdksh 1 .
+shell clone like pdksh.
 Only features
 designated by POSIX, plus a few Berkeley extensions, are being
 incorporated into this shell.
@@ -79,10 +80,12 @@ 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
+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
+use (shell scripts).
+That is, commands can be typed directly
 to the running shell or can be put into a file,
 which can be executed directly by the shell.
 .Ss Invocation
@@ -94,20 +97,23 @@ is connected to a terminal
 (or if the
 .Fl i
 option is set),
-the shell is considered an interactive shell.  An interactive shell
+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
-.Pq Li - ,
+.Pq Ql - ,
 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
+when the user first logs in.
+A login shell first reads commands
 from the files
 .Pa /etc/profile
 and then
 .Pa .profile
-if they exist.  If the environment variable
+if they exist.
+If the environment variable
 .Ev ENV
 is set on entry to a shell, or is set in the
 .Pa .profile
@@ -134,14 +140,16 @@ The first non-option argument specified on the command line
 will be treated as the
 name of a file from which to read commands (a shell script), and
 the remaining arguments are set as the positional parameters
-of the shell ($1, $2, etc).  Otherwise, the shell reads commands
+of the shell ($1, $2, etc).
+Otherwise, the shell reads commands
 from its standard input.
 .Pp
 Unlike older versions of
 .Nm
 the
 .Ev ENV
-script is only sourced on invocation of interactive shells.  This
+script is only sourced on invocation of interactive shells.
+This
 closes a well-known, and sometimes easily exploitable security
 hole related to poorly thought out
 .Ev ENV
@@ -169,15 +177,15 @@ built-in command
 (described later in the section called
 .Sx Built-in Commands ) .
 Introducing an option with a dash
-.Pq Li -
+.Pq Ql -
 enables the option,
 while using a plus
-.Pq Li +
+.Pq Ql +
 disables the option.
 A
 .Dq Li --
 or plain
-.Dq Li -
+.Dq Ql -
 will stop option processing and will force the remaining
 words on the command line to be treated as arguments.
 The
@@ -206,7 +214,11 @@ option if it has been set).
 Exit immediately if any untested command fails in non-interactive mode.
 The exit status of a command is considered to be
 explicitly tested if the command is part of the list used to control
-an if, elif, while, or until; if the command is the left
+an
+.Ic if , elif , while ,
+or
+.Ic until ;
+if the command is the left
 hand operand of an
 .Dq Li &&
 or
@@ -229,7 +241,8 @@ Force the shell to behave interactively.
 Turn on job control (set automatically when interactive).
 .It Fl n Li noexec
 If not interactive, read commands but do not
-execute them.  This is useful for checking the
+execute them.
+This is useful for checking the
 syntax of shell scripts.
 .It Fl P Li physical
 Change the default for the
@@ -243,9 +256,11 @@ to
 .Fl P
 (physical directory layout).
 .It Fl p Li privileged
-Turn on privileged mode.  This mode is enabled on startup
+Turn on privileged mode.
+This mode is enabled on startup
 if either the effective user or group id is not equal to the
-real user or group id.  Turning this mode off sets the
+real user or group id.
+Turning this mode off sets the
 effective user and group ids to the real user and group ids.
 When this mode is enabled for interactive shells, the file
 .Pa /etc/suid_profile
@@ -258,9 +273,10 @@ is sourced, and the contents of the
 variable are ignored.
 .It Fl s Li stdin
 Read commands from standard input (set automatically
-if no file arguments are present).  This option has
+if no file arguments are present).
+This option has
 no effect when set after the shell has already started
-running (i.e. when set with the
+running (i.e., when set with the
 .Ic set
 command).
 .It Fl T Li trapsasync
@@ -268,9 +284,10 @@ When waiting for a child, execute traps immediately.
 If this option is not set,
 traps are executed after the child exits,
 as specified in
-.St -p1003.2
+.St -p1003.2 .
 This nonstandard option is useful for putting guarding shells around
-children that block signals.  The surrounding shell may kill the child
+children that block signals.
+The surrounding shell may kill the child
 or it may just return control to the tty and leave the child alone,
 like this:
 .Bd -literal -offset indent
@@ -289,7 +306,8 @@ command line editor (disables
 if it has been set).
 .It Fl v Li verbose
 The shell writes its input to standard error
-as it is read.  Useful for debugging.
+as it is read.
+Useful for debugging.
 .It Fl x Li xtrace
 Write each command
 (preceded by the value of the
@@ -301,8 +319,9 @@ Useful for debugging.
 .Pp
 The
 .Fl c
-option may be used to pass its string argument to the shell
-to be interpreted as input.
+option causes the commands to be read from the
+.Ar string
+operand instead of from the standard input.
 Keep in mind that this option only accepts a single string as its
 argument, hence multi-word strings must be quoted.
 .Pp
@@ -349,10 +368,19 @@ The following is a list of valid operators:
 .It Li <& Ta Li >& Ta Li <<- Ta Li >|
 .El
 .El
+.Pp
+The character
+.Ql #
+introduces a comment if used at the beginning of a word.
+The word starting with
+.Ql #
+and the rest of the line are ignored.
 .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 three types of quoting: matched single quotes,
+or words to the shell, such as operators, whitespace, keywords,
+or alias names.
+.Pp
+There are three types of quoting: matched single quotes,
 matched double quotes, and backslash.
 .Bl -tag -width indent
 .It Single Quotes
@@ -362,11 +390,11 @@ it impossible to put single-quotes in a single-quoted string).
 .It Double Quotes
 Enclosing characters within double quotes preserves the literal
 meaning of all characters except dollarsign
-.Pq Li $ ,
+.Pq Ql $ ,
 backquote
-.Pq Li ` ,
+.Pq Ql ` ,
 and backslash
-.Pq Li \e .
+.Pq Ql \e .
 The backslash inside double quotes is historically weird.
 It remains literal unless it precedes the following characters,
 which it serves to quote:
@@ -376,13 +404,14 @@ which it serves to quote:
 .It Backslash
 A backslash preserves the literal meaning of the following
 character, with the exception of the newline character
-.Pq Li \en .
+.Pq Ql \en .
 A backslash preceding a newline is treated as a line continuation.
 .El
 .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:
+after a control operator.
+The following are reserved words:
 .Bl -column "doneXX" "elifXX" "elseXX" "untilXX" "whileX" -offset center
 .It Li \&! Ta { Ta } Ta Ic case Ta Ic do
 .It Ic done Ta Ic elif Ta Ic else Ta Ic esac Ta Ic fi
@@ -391,7 +420,8 @@ after a control operator.  The following are reserved words:
 .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),
+built-in command.
+Whenever a reserved word may occur (see above),
 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.
@@ -411,17 +441,31 @@ ls -F foobar
 .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 discouraged.
+to create functions with arguments.
+They can also be
+used to create lexically obscure code.
+This use is discouraged.
+.Pp
+An alias name may be escaped in a command line, so that it is not
+replaced by its alias value, by using quoting characters within or
+adjacent to the alias name.
+This is most often done by prefixing
+an alias name with a backslash to execute a function, built-in, or
+normal program with the same name.
+See the
+.Sx Quoting
+subsection.
 .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
 .St -p1003.2
-document).  Essentially though, a line is read and if
+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
+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
@@ -431,7 +475,8 @@ the following actions:
 Leading words of the form
 .Dq Li name=value
 are stripped off and assigned to the environment of
-the simple command.  Redirection operators and
+the simple command.
+Redirection operators and
 their arguments (as described below) are stripped
 off and saved for processing.
 .It
@@ -439,7 +484,8 @@ The remaining words are expanded as described in
 the section called
 .Sx Word Expansions ,
 and the first remaining word is considered the command
-name and the command is located.  The remaining
+name and the command is located.
+The remaining
 words are considered the arguments of the command.
 If no command name resulted, then the
 .Dq Li name=value
@@ -451,8 +497,10 @@ 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
+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 [n] redir-op file
@@ -460,7 +508,8 @@ used for redirection is:
 The
 .Ql redir-op
 is one of the redirection operators mentioned
-previously.  The following gives some examples of how these
+previously.
+The following gives some examples of how these
 operators can be used.
 Note that stdin and stdout are commonly used abbreviations
 for standard input and standard output respectively.
@@ -498,7 +547,8 @@ delimiter
 .Pp
 All the text on successive lines up to the delimiter is
 saved away and made available to the command on standard
-input, or file descriptor n if it is specified.  If the delimiter
+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 subjected to
 parameter expansion, command substitution, and arithmetic
@@ -537,7 +587,7 @@ 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
-(i.e. if it does not begin with the
+(i.e., if it does not begin with the
 .Qq magic number
 whose
 .Tn ASCII
@@ -561,8 +611,10 @@ as a
 .Qq 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,
+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
@@ -571,10 +623,12 @@ performing any searches.
 .It
 The shell searches each entry in
 .Ev PATH
-in turn for the command.  The value of the
+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
+entries separated by colons.
+Each entry consists of a
 directory name.
 The current directory
 may be indicated implicitly by an empty directory name,
@@ -582,20 +636,24 @@ or explicitly by a single period.
 .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
+of other shell commands.
+The paradigm is that a command exits
 with zero for normal or success, and non-zero for failure,
-error, or a false indication.  The man page for each command
+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 is terminated by a signal, its exit status is 128 plus
-the signal number.  Signal numbers are defined in the header file
+the signal number.
+Signal numbers are defined in the header file
 .In sys/signal.h .
 .Ss Complex Commands
 Complex commands are combinations of simple commands
 with control operators or reserved words, together creating a larger complex
-command.  More generally, a command is one of the following:
+command.
+More generally, a command is one of the following:
 .Bl -item -offset indent
 .It
 simple command
@@ -613,9 +671,11 @@ Unless otherwise stated, the exit status of a command is
 that of the last simple command executed by the command.
 .Ss Pipelines
 A pipeline is a sequence of one or more commands separated
-by the control operator |.  The standard output of all but
+by the control operator |.
+The standard output of all but
 the last command is connected to the standard input
-of the next command.  The standard output of the last
+of the next command.
+The standard output of the last
 command is inherited from the shell, as usual.
 .Pp
 The format for a pipeline is:
@@ -623,7 +683,8 @@ The format for a pipeline is:
 .Dl [!] command1 [ | command2 ...]
 .Pp
 The standard output of command1 is connected to the standard
-input of command2.  The standard input, standard output, or
+input of 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.
@@ -631,17 +692,22 @@ operators that are part of the command.
 If the pipeline is not in the background (discussed later),
 the shell waits for all commands to complete.
 .Pp
-If the reserved word ! does not precede the pipeline, the
+If the reserved word
+.Ic !\&
+does not precede the pipeline, the
 exit status is the exit status of the last command specified
-in the pipeline.  Otherwise, the exit status is the logical
-NOT of the exit status of the last command.  That is, if
+in the pipeline.
+Otherwise, the exit status is the logical
+NOT of the exit status of the last command.
+That is, if
 the last command returns zero, the exit status is 1; if
 the last command returns greater than zero, the exit status
 is zero.
 .Pp
 Because pipeline assignment of standard input or standard
 output or both takes place before redirection, it can be
-modified by redirection.  For example:
+modified by redirection.
+For example:
 .Pp
 .Dl $ command1 2>&1 | command2
 .Pp
@@ -671,7 +737,7 @@ They are executed in the current shell, although they do not affect its
 environment when used in pipelines.
 .Ss Background Commands (&)
 If a command is terminated by the control operator ampersand
-.Pq Li & ,
+.Pq Ql & ,
 the shell executes the command asynchronously;
 the shell does not wait for the command to finish
 before executing the next command.
@@ -743,10 +809,15 @@ repeat until the exit status of the first list is zero.
 The syntax of the
 .Ic for
 command is:
-.Dl Ic for Ar variable Ic in Ar word ...
+.Dl Ic for Ar variable Op Ic in Ar word ...
 .Dl Ic do Ar list
 .Dl Ic done
 .Pp
+If
+.Ic in
+and the following words are omitted,
+.Ic in Li $@
+is used instead.
 The words are expanded, and then the list is executed
 repeatedly with the variable set to each word in turn.
 The
@@ -823,7 +894,8 @@ name ( ) command
 .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
+exit status of zero.
+The command is normally a list
 enclosed between
 .Dq Li {
 and
@@ -838,7 +910,7 @@ and the syntax is:
 .Bd -ragged -offset indent
 .Ic local
 .Op Ar variable ...
-.Op Ar -
+.Op Fl
 .Ed
 .Pp
 The
@@ -848,7 +920,9 @@ command is implemented as a built-in command.
 When a variable is made local, it inherits the initial
 value and exported and readonly flags from the variable
 with the same name in the surrounding scope, if there is
-one.  Otherwise, the variable is initially unset.  The shell
+one.
+Otherwise, the variable is initially unset.
+The shell
 uses dynamic scoping, so that if the variable
 .Em x
 is made local to function
@@ -866,7 +940,7 @@ declared inside
 not to the global variable named
 .Em x .
 .Pp
-The only special parameter than can be made local is
+The only special parameter that can be made local is
 .Dq Li - .
 Making
 .Dq Li -
@@ -883,15 +957,19 @@ command is
 .Op Ar exitstatus
 .Ed
 .Pp
-It terminates the currently executing function.
+It terminates the current executional scope, returning from the previous
+nested function, sourced script, or shell instance, in that order.
 The
 .Ic return
 command is implemented as a built-in 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 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.  New variables can be set using the form
+variables.
+New variables can be set using the form
 .Bd -literal -offset indent
 name=value
 .Ed
@@ -904,16 +982,23 @@ or a special character as explained below.
 .Ss Positional Parameters
 A positional parameter is a parameter denoted by a number greater than zero.
 The shell sets these initially to the values of its command line
-arguments that follow the name of the shell script.  The
+arguments that follow the name of the shell script.
+The
 .Ic set
 built-in command can also be used to set or reset them.
 .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.
+A special parameter is a parameter denoted by a special one-character
+name.
+The special parameters recognized by the
+.Nm
+shell of
+.Fx
+are shown in the following list, exactly as they would appear in input
+typed by the user or in the source of a shell script.
 .Bl -hang
-.It Li *
-Expands to the positional parameters, starting from one.  When
+.It Li $*
+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
@@ -924,8 +1009,9 @@ or by a
 if
 .Ev IFS
 is unset.
-.It Li @
-Expands to the positional parameters, starting from one.  When
+.It Li $@
+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
@@ -933,7 +1019,8 @@ expansion of
 .Li @
 generates zero arguments, even when
 .Li @
-is double-quoted.  What this basically means, for example, is
+is double-quoted.
+What this basically means, for example, is
 if $1 is
 .Dq abc
 and $2 is
@@ -945,34 +1032,38 @@ the two arguments:
 .Bd -literal -offset indent
 "abc"   "def ghi"
 .Ed
-.It Li #
+.It Li $#
 Expands to the number of positional parameters.
-.It Li \&?
+.It Li $\&?
 Expands to the exit status of the most recent pipeline.
-.It Li -
+.It Li $-
 (hyphen) 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 Li $
-Expands to the process ID of the invoked shell.  A subshell
+.It Li $$
+Expands to the process ID of the invoked shell.
+A subshell
 retains the same value of $ as its parent.
-.It Li \&!
+.It Li $\&!
 Expands to the process ID of the most recent background
-command executed from the current shell.  For a
+command executed from the current shell.
+For a
 pipeline, the process ID is that of the last command in the
 pipeline.
-.It Li 0
+.It Li $0
 (zero) Expands to the name of the shell or shell script.
 .El
 .Ss Word Expansions
 This clause describes the various expansions that are
-performed on words.  Not all expansions are performed on
+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
+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
@@ -1005,13 +1096,14 @@ 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
-.Pq Li ~
+.Pq Ql ~
 is
 subjected to tilde expansion.
 All the characters up to a slash
-.Pq Li /
+.Pq Ql /
 or the end of the word are treated as a username
-and are replaced with the user's home directory.  If the
+and are replaced with the user's home directory.
+If the
 username is missing (as in ~/foobar), the tilde is replaced
 with the value of the HOME variable (the current user's
 home directory).
@@ -1056,30 +1148,37 @@ In addition, a parameter expansion can be modified by using one of the
 following formats.
 .Bl -tag -width indent
 .It Li ${parameter:-word}
-Use Default Values.  If parameter is unset or
+Use Default Values.
+If parameter is unset or
 null, the expansion of word is
 substituted; otherwise, the value of
 parameter is substituted.
 .It Li ${parameter:=word}
-Assign Default Values.  If parameter is unset
+Assign Default Values.
+If parameter is unset
 or null, the expansion of word is
-assigned to parameter.  In all cases, the
+assigned to parameter.
+In all cases, the
 final value of parameter is
-substituted.  Only variables, not positional
+substituted.
+Only variables, not positional
 parameters or special parameters, can be
 assigned in this way.
 .It Li ${parameter:?[word]}
-Indicate Error if Null or Unset.  If
+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
+parameter is substituted.
+An
 interactive shell need not exit.
 .It Li ${parameter:+word}
-Use Alternate Value.  If parameter is unset
+Use Alternate Value.
+If parameter is unset
 or null, null is substituted;
 otherwise, the expansion of word is
 substituted.
@@ -1090,7 +1189,8 @@ format results in a test for a parameter that is unset or null; omission
 of the colon results in a test for a parameter that is only unset.
 .Bl -tag -width indent
 .It Li ${#parameter}
-String Length.  The length in characters of
+String Length.
+The length in characters of
 the value of parameter.
 .El
 .Pp
@@ -1111,33 +1211,42 @@ cause the following four varieties of pattern characters to be quoted,
 whereas quoting characters within the braces has this effect.
 .Bl -tag -width indent
 .It Li ${parameter%word}
-Remove Smallest Suffix Pattern.  The word
-is expanded to produce a pattern.  The
+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.
 .It Li ${parameter%%word}
-Remove Largest Suffix Pattern.  The word
-is expanded to produce a pattern.  The
+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.
 .It Li ${parameter#word}
-Remove Smallest Prefix Pattern.  The word
-is expanded to produce a pattern.  The
+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.
 .It Li ${parameter##word}
-Remove Largest Prefix Pattern.  The word
-is expanded to produce a pattern.  The
+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.
 .El
 .Ss Command Substitution
 Command substitution allows the output of a command to be substituted in
-place of the command name itself.  Command substitution occurs when
+place of the command name itself.
+Command substitution occurs when
 the command is enclosed as follows:
 .Bd -literal -offset indent
 $(command)
@@ -1166,7 +1275,8 @@ $((expression))
 .Ed
 .Pp
 The expression is treated as if it were in double-quotes, except
-that a double-quote inside the expression is not treated specially.  The
+that a double-quote inside the expression is not treated specially.
+The
 shell expands all tokens in the expression for parameter expansion,
 command substitution, and quote removal.
 .Pp
@@ -1188,8 +1298,10 @@ Unless the
 .Fl f
 option 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
+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.
@@ -1217,13 +1329,13 @@ variable or the output of the command is scanned for these
 characters and they are turned into meta-characters.
 .Pp
 An asterisk
-.Pq Li *
+.Pq Ql *
 matches any string of characters.
 A question mark
-.Pq Li \&?
+.Pq Ql \&?
 matches any single character.
 A left bracket
-.Pq Li [
+.Pq Ql [
 introduces a character class.
 The end of the character class is indicated by a
 .Dq Li \&] ;
@@ -1237,9 +1349,9 @@ rather than introducing a character class.
 A character class matches any of the characters between the square brackets.
 A range of characters may be specified using a minus sign.
 The character class may be complemented by making an exclamation point
-.Pq Li !\&
+.Pq Ql !\&
 or the caret
-.Pq Li ^\&
+.Pq Ql ^\&
 the first character of the character class.
 .Pp
 To include a
@@ -1256,28 +1368,35 @@ make it the first or last character listed.
 .Ss Built-in Commands
 This section lists the commands which
 are built-in because they need to perform some operation
-that cannot be performed by a separate process.  In addition to
-these, built-in versions of the
-.Xr printf 1
-and
-.Xr test 1
-commands are provided for efficiency.
+that cannot be performed by a separate process.
+In addition to
+these, built-in versions of essential utilities
+are provided for efficiency.
 .Bl -tag -width indent
 .It Ic \&:
 A null command that returns a 0 (true) exit value.
 .It Ic \&. Ar file
 The commands in the specified file are read and executed by the shell.
+The
+.Ic return
+command may be used to return to the
+.Ic \&.
+command's caller.
 If
 .Ar file
 contains any
 .Dq /
-characters, it is used as is.  Otherwise, the shell searches the
+characters, it is used as is.
+Otherwise, the shell searches the
 .Ev PATH
-for the file.  If it is not found in the
+for the file.
+If it is not found in the
 .Ev PATH ,
 it is sought in the current working directory.
-.It Ic alias Op Ar name ...
-.It Ic alias Op Ar name Ns = Ns Ar string ...
+.It Ic \&[
+A built-in equivalent of
+.Xr test 1 .
+.It Ic alias Oo Ar name Ns Oo = Ns Ar string Oc ... Oc
 If
 .Ar name Ns = Ns Ar string
 is specified, the shell defines the alias
@@ -1296,6 +1415,9 @@ built-in command prints the names and values of all defined aliases
 .Ic unalias ) .
 Alias values are written with appropriate quoting so that they are
 suitable for re-input to the shell.
+Also see the
+.Sx Aliases
+subsection.
 .It Ic bg Op Ar job ...
 Continue the specified jobs
 (or the current job if no jobs are given)
@@ -1309,7 +1431,7 @@ with the same name as a built-in command.
 List or alter key bindings for the line editor.
 This command is documented in
 .Xr editrc 5 .
-.It Ic cd Oo Fl LP Oc Op Ar directory
+.It Ic cd Oo Fl L | P Oc Op Ar directory
 Switch to the specified
 .Ar directory ,
 or to the directory specified in the
@@ -1363,7 +1485,8 @@ A synonym for the
 .Ic cd
 built-in command.
 .It Ic command Oo Fl p Oc Op Ar utility Op Ar argument ...
-Execute the specified
+.It Ic command Oo Fl v | V Oc Op Ar utility
+The first form of invocation executes the specified
 .Ar utility
 as a simple command (see the
 .Sx Simple Commands
@@ -1375,10 +1498,39 @@ option is specified, the command search is performed using a
 default value of
 .Ev PATH
 that is guaranteed to find all of the standard utilities.
-.It Ic echo Oo Fl e | n Oc Op Ar string
-Print
-.Ar string
-to the standard output with a newline appended.
+.Pp
+If the
+.Fl v
+option is specified,
+.Ar utility
+is not executed but a description of its interpretation by the shell is
+printed.
+For ordinary commands the output is the path name; for shell built-in
+commands, shell functions and keywords only the name is written.
+Aliases are printed as
+.Dq Ic alias Ar name Ns = Ns Ar value .
+.Pp
+The
+.Fl V
+option is identical to
+.Fl v
+except for the output.
+It prints
+.Dq Ar utility Ic is Ar description
+where
+.Ar description
+is either
+the path name to
+.Ar utility ,
+a shell builtin,
+a shell function,
+a shell keyword
+or
+an alias for
+. Ar value .
+.It Ic echo Oo Fl e | n Oc Op Ar string ...
+Print a space-separated list of the arguments to the standard output
+and append a newline character.
 .Bl -tag -width indent
 .It Fl n
 Suppress the output of the trailing newline.
@@ -1415,7 +1567,8 @@ Literal backslash
 If
 .Ar string
 is not enclosed in quotes then the backslash itself must be escaped
-with a backslash to protect it from the shell. For example
+with a backslash to protect it from the shell.
+For example
 .Bd -literal -offset indent
 $ echo -e "a\evb"
 a
@@ -1457,7 +1610,8 @@ If
 is given
 it is used as the exit status of the shell;
 otherwise the exit status of the preceding command is used.
-.It Ic export Oo Fl p Oc Op Ar name ...
+.It Ic export Ar name ...
+.It Ic export Op Fl p
 The specified names are exported so that they will
 appear in the environment of subsequent commands.
 The only way to un-export a variable is to
@@ -1476,6 +1630,8 @@ If the
 option is specified, the exported variables are printed as
 .Dq Ic export Ar name Ns = Ns Ar value
 lines, suitable for re-input to the shell.
+.It Ic false
+A null command that returns a non-zero (false) exit value.
 .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 Ns = Ns Ar new Oc Op Ar first
@@ -1509,7 +1665,8 @@ is null or unset,
 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
+an editor on them.
+The commands are written in the
 sequence indicated by the first and last operands, as
 affected by
 .Fl r ,
@@ -1566,9 +1723,9 @@ the string form of the first operand cannot contain an embedded equal sign.
 .Pp
 The following environment variables affect the execution of
 .Ic fc :
-.Bl -tag -width indent
+.Bl -tag -width ".Ev HISTSIZE"
 .It Ev FCEDIT
-Name of the editor to use.
+Name of the editor to use for history editing.
 .It Ev HISTSIZE
 The number of previous commands that are accessible.
 .El
@@ -1587,7 +1744,8 @@ command deprecates the older
 command.
 The first argument should be a series of letters, each possibly
 followed by a colon which indicates that the option takes an argument.
-The specified variable is set to the parsed option.  The index of
+The specified variable is set to the parsed option.
+The index of
 the next argument is placed into the shell variable
 .Ev OPTIND .
 If an option takes an argument, it is placed into the shell variable
@@ -1645,12 +1803,19 @@ If the
 .Fl s
 option is specified, only the PIDs of the job commands are printed, one per
 line.
-.It Ic pwd Op Fl LP
-Print the path of the current directory.  The built-in command may
+.It Ic local Oo Ar variable ... Oc Op Fl
+See the
+.Sx Functions
+subsection.
+.It Ic pwd Op Fl L | P
+Print the path of the current directory.
+The built-in command may
 differ from the program of the same name because the
 built-in command remembers what the current directory
-is rather than recomputing it each time.  This makes
-it faster.  However, if the current directory is
+is rather than recomputing it each time.
+This makes
+it faster.
+However, if the current directory is
 renamed,
 the built-in version of
 .Xr pwd 1
@@ -1670,8 +1835,10 @@ The
 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
+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 section on
 .Sx White Space Splitting (Field Splitting)
@@ -1688,9 +1855,11 @@ variables are assigned the null string.
 Backslashes are treated specially, unless the
 .Fl r
 option is
-specified.  If a backslash is followed by
+specified.
+If a backslash is followed by
 a newline, the backslash and the newline will be
-deleted.  If a backslash is followed by any other
+deleted.
+If a backslash is followed by any other
 character, the backslash will be deleted and the following
 character will be treated as though it were not in
 .Ev IFS ,
@@ -1703,7 +1872,7 @@ option is specified and the
 elapses before any input is supplied,
 the
 .Ic read
-command will return without assigning any values.
+command will return an exit status of 1 without assigning any values.
 The
 .Ar timeout
 value may optionally be followed by one of
@@ -1739,6 +1908,10 @@ If the
 option is specified, the read-only variables are printed as
 .Dq Ic readonly Ar name Ns = Ns Ar value
 lines, suitable for re-input to the shell.
+.It Ic return Op Ar exitstatus
+See the
+.Sx Functions
+subsection.
 .It Ic set Oo Fl /+abCEefIimnpTuVvx Oc Oo Fl /+o Ar longname Oc Oo
 .Fl c Ar string Oc Op Fl - Ar arg ...
 The
@@ -1773,9 +1946,9 @@ flag may be omitted when specifying arguments to be used
 as positional replacement parameters.
 This is not recommended,
 because the first argument may begin with a dash
-.Pq Li -
+.Pq Ql -
 or a plus
-.Pq Li + ,
+.Pq Ql + ,
 which the
 .Ic set
 command will interpret as a request to enable or disable options.
@@ -1804,12 +1977,16 @@ A shift sets the value of $1 to the value of $2,
 the value of $2 to the value of $3, and so on,
 decreasing the value of $# by one.
 If there are zero positional parameters, shifting does not do anything.
+.It Ic test
+A built-in equivalent of
+.Xr test 1 .
 .It Ic times
 Print the amount of time spent executing the shell and its children.
 The first output line shows the user and system times for the shell
 itself, the second one contains the user and system times for the
 children.
 .It Ic trap Oo Ar action Oc Ar signal ...
+.It Ic trap Fl l
 Cause the shell to parse and execute
 .Ar action
 when any specified
@@ -1821,14 +1998,27 @@ In addition, the pseudo-signal
 may be used to specify an action that is performed when the shell terminates.
 The
 .Ar action
-may be null or omitted;
+may be an empty string or a dash
+.Pq Ql - ;
 the former causes the specified signal to be ignored
 and the latter causes the default action to be taken.
+Omitting the
+.Ar action
+is another way to request the default action, for compatibility reasons this
+usage is not recommended though.
 When the shell forks off a subshell,
 it resets trapped (but not ignored) signals to the default action.
 The
 .Ic trap
 command has no effect on signals that were ignored on entry to the shell.
+.Pp
+Option
+.Fl l
+causes the
+.Ic trap
+command to display a list of valid signal names.
+.It Ic true
+A null command that returns a 0 (true) exit value.
 .It Ic type Op Ar name ...
 Interpret each
 .Ar name
@@ -1855,7 +2045,8 @@ only the superuser can increase it.
 The
 .Fl S
 option
-specifies the soft limits instead.  When displaying limits,
+specifies the soft limits instead.
+When displaying limits,
 only one of
 .Fl S
 or
@@ -1901,16 +2092,19 @@ The maximal number of simultaneous processes for this user ID.
 .It Fl v Ar virtualmem
 The maximal virtual size of a process, in kilobytes.
 .El
-.It Ic umask Op Ar mask
+.It Ic umask Oo Fl S Oc Op Ar mask
 Set the file creation mask (see
 .Xr umask 2 )
-to the octal value specified by
+to the octal or symbolic (see
+.Xr chmod 1 )
+value specified by
 .Ar mask .
 If the argument is omitted, the current mask value is printed.
-.It Ic unalias Oo Fl a Oc Op Ar name
-If
-.Ar name
-is specified, the shell removes that alias.
+If the
+.Fl S
+option is specified, the output is symbolic, otherwise the output is octal.
+.It Ic unalias Oo Fl a Oc Op Ar name ...
+The specified alias names are removed.
 If
 .Fl a
 is specified, all aliases are removed.
@@ -1952,7 +2146,8 @@ The command
 .Dq Li set -V )
 enables vi-mode editing and places
 .Nm
-into vi insert mode.  With vi-mode enabled,
+into vi insert mode.
+With vi-mode enabled,
 .Nm
 can be switched between insert mode and command mode by typing
 .Aq ESC .
@@ -1966,15 +2161,123 @@ Similarly, the
 .Dq Li set -E )
 command can be used to enable a subset of
 emacs-style command line editing features.
+.Sh ENVIRONMENT
+The following environment variables affect the execution of
+.Nm :
+.Bl -tag -width ".Ev HISTSIZE"
+.It Ev CDPATH
+The search path used with the
+.Ic cd
+built-in.
+.It Ev EDITOR
+The fallback editor used with the
+.Ic fc
+built-in.
+If not set, the default editor is
+.Xr ed 1 .
+.It Ev FCEDIT
+The default editor used with the
+.Ic fc
+built-in.
+.It Ev HISTSIZE
+The number of previous commands that are accessible.
+.It Ev HOME
+The starting directory of
+.Nm .
+.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 MAIL
+The name of a mail file, that will be checked for the arrival of new
+mail.
+Overridden by
+.Ev MAILPATH .
+.It Ev MAILPATH
+A colon
+.Pq Ql \&:
+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 for details.
+.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 "# " .
+.It Ev PS2
+The secondary prompt string, which defaults to
+.Dq Li "> " .
+.It Ev PS4
+The prefix for the trace output (if
+.Fl x
+is active).
+The default is
+.Dq Li "+ " .
+.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.
+.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 builtin is used with a numeric argument, it
+will return the argument.
 .Sh SEE ALSO
 .Xr builtin 1 ,
+.Xr chsh 1 ,
 .Xr echo 1 ,
+.Xr ed 1 ,
+.Xr emacs 1 ,
 .Xr expr 1 ,
+.Xr getopt 1 ,
 .Xr printf 1 ,
 .Xr pwd 1 ,
-.Xr test 1
+.Xr test 1 ,
+.Xr vi 1 ,
+.Xr execve 2 ,
+.Xr getrlimit 2 ,
+.Xr umask 2 ,
+.Xr editrc 5
 .Sh HISTORY
 A
 .Nm
-command appeared in
+command, the Thompson shell, appeared in
 .At v1 .
+It was superseded in
+.At v7
+by the Bourne shell, which inherited the name
+.Nm .
+.Pp
+This version of
+.Nm
+was rewritten in 1989 under the
+.Bx
+license after the Bourne shell from
+.At V.4 .
+.Sh AUTHORS
+This version of
+.Nm
+was originally written by
+.An Kenneth Almquist .
+.Sh BUGS
+The
+.Nm
+utility does not recognize multibyte characters.