[src/trunk]: src/bin/sh Omnibus manual update for prompt expansions and new v...

[kre <kre%NetBSD.org@localhost>]

details:   https://anonhg.NetBSD.org/src/rev/9970a24124c2
branches:  trunk
changeset: 825131:9970a24124c2
user:      kre <kre%NetBSD.org@localhost>
date:      Fri Jun 30 23:07:29 2017 +0000

description:
Omnibus manual update for prompt expansions and new variables.  Throw in
some random cleanups as a bonus.

diffstat:

 bin/sh/sh.1 |  270 +++++++++++++++++++++++++++++++++++++++++++++++++++--------
 1 files changed, 230 insertions(+), 40 deletions(-)

diffs (truncated from 453 to 300 lines):

diff -r f1d3fd6d6022 -r 9970a24124c2 bin/sh/sh.1
--- a/bin/sh/sh.1       Fri Jun 30 23:05:45 2017 +0000
+++ b/bin/sh/sh.1       Fri Jun 30 23:07:29 2017 +0000
@@ -1,4 +1,4 @@
-.\"    $NetBSD: sh.1,v 1.156 2017/06/28 13:46:06 kre Exp $
+.\"    $NetBSD: sh.1,v 1.157 2017/06/30 23:07:29 kre Exp $
 .\" Copyright (c) 1991, 1993
 .\"    The Regents of the University of California.  All rights reserved.
 .\"
@@ -31,9 +31,10 @@
 .\"
 .\"    @(#)sh.1        8.6 (Berkeley) 5/4/95
 .\"
-.Dd June 28, 2017
+.Dd July 1, 2017
 .Dt SH 1
-.ds flags abCEeFfhnuvxIimpqV
+.\" everything except c o and s (keep them ordered)
+.ds flags abCeEfFhiILmnpquvVx
 .Os
 .Sh NAME
 .Nm sh
@@ -54,6 +55,7 @@
 .Nm
 .Fl c
 .Bk -words
+.Op Fl s
 .Op Fl \*[flags]
 .Op Cm +\*[flags]
 .Ek
@@ -83,7 +85,7 @@
 is the standard command interpreter for the system.
 The current version of
 .Nm
-is in the process of being changed to conform with the
+is in the process of being changed to conform more closely to the
 .Tn POSIX
 1003.2 and 1003.2a specifications for the shell.
 This version has many
@@ -95,8 +97,8 @@
 .Ss Overview
 The shell is a command that reads lines from either a file or the
 terminal, interprets them, and generally executes other commands.
-It is the program that is running when a user logs into the system
-(although a user can select a different shell with the
+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
@@ -188,12 +190,37 @@
 .Li esac
 .El
 .Pp
-If command line arguments besides the options have been specified, then
-the shell treats the first argument as the name of a file from which to
-read commands (a shell script), and the remaining arguments are set as the
+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 $0 and the remaining arguments are set as the
 positional parameters of the shell ($1, $2, etc).
-Otherwise, the shell
-reads commands from its standard input.
+Otheriwse, 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 $0, $1, ...
+Otherwise, if additional arguments were given
+(which implies that
+.Fl s
+was set)
+those arguments become $1, $2, ...
+If $0 has not been set by the preceding processing, it
+will be set to argv[0] as passed to the shell, which will
+usually be the name of the shell itself.
+If
+.Fl s
+was given, or if neither
+.Fc 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
@@ -206,6 +233,14 @@
 .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 -
@@ -218,26 +253,28 @@
 built-in (described later).
 .\"
 .\" strlen("quietprofile") == strlen("local_lineno"): pick the latter
-.\" to give the indent as the _ in that case, and the fi ligature in
-.\" the former combine to make local_lineno slightly wider when printed
+.\" 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.   Probably should test the actual
 .\" widths and use the wider, but I am not sure if mandoc is up to that...
 .\" (and I don't know how to get at the font that will be used easily anyway!)
+.\" The X's just provide a little extra space.
 .Bl -tag -width \-WXXlocal_linenoXX -offset indent
 .\"
 .It Fl a Em allexport
-Export all variables assigned to.
+Automatically export any variable to which a value is assigned
+while this flag is set.
 .It Fl b Em notify
 Enable asynchronous notification of background job completion.
 (Not implemented.)
 .It Fl c
 Read commands from the
 .Ar command_string
-operand instead of from the standard input.
+operand instead of, or in addition to, from the standard input.
 Special parameter 0 will be set from the
 .Ar command_name
-operand and the positional parameters ($1, $2, etc.)
-set from the remaining argument operands.
+operand if given, and the positional parameters ($1, $2, etc.)
+set from the remaining argument operands, if any.
 .Fl c
 is only available at invocation, it cannot be
 .Ic set ,
@@ -248,6 +285,9 @@
 .Dq > .
 .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 ,
@@ -294,14 +334,16 @@
 .Fl F
 flag has no effect.
 .It Fl h Em trackall
-Bind commands in functions to file system paths when the function is defined.
-When off,
+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 interactive
 Force the shell to behave interactively.
 .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 L Em local_lineno
 When set, before a function is defined,
 causes the variable
@@ -312,7 +354,7 @@
 When reset,
 .Ev LINENO
 in a function refers to the line number within the file
-in which the definition of the function occurs.
+within which the definition of the function occurs.
 This option defaults to
 .Dq on
 in this shell.
@@ -322,8 +364,12 @@
 .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.
+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 (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
@@ -344,20 +390,43 @@
 .Ev ENV
 environment variable.
 .It Fl s Em stdin
-Read commands from standard input (set automatically if no file arguments
-are present).
+Read commands from standard input (set automatically if
+neither
+.Fl c
+nor file arguments are present).
+If after procesing 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 running (i.e. with
-.Ic set ) .
+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 expand a variable
-that is not set, and if the shell is not interactive, exit immediately.
+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 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 +\  )
+Write each command to standard error (preceded by the expanded value of
+.Dq $PS4 )
 before it is executed.
 Useful for debugging.
 .It Fl V Em vi
@@ -383,12 +452,12 @@
 section.)
 (Not implemented.)
 .It "\ \ " Em posix
-Enables closer adherence to the shell standard.
+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 by the
+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)
@@ -403,13 +472,25 @@
 in posix mode),
 and whether the shell treats
 an empty brace-list compound statement as a syntax error
-(required by posix) or permits it.
+(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
@@ -2900,6 +2981,16 @@
 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.