[src/trunk]: src/bin/sh Document the NETBSD_SHELL variable, the enhancements ...

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

details:   https://anonhg.NetBSD.org/src/rev/e8508443d32f
branches:  trunk
changeset: 344465:e8508443d32f
user:      christos <christos%NetBSD.org@localhost>
date:      Thu Mar 31 16:18:22 2016 +0000

description:
Document the NETBSD_SHELL variable, the enhancements to export,
the posix option, and a whole bunch of miscellaneous updates and
corrections. (from kre@)

diffstat:

 bin/sh/sh.1 |  381 +++++++++++++++++++++++++++++++++++++++++++++++++----------
 1 files changed, 316 insertions(+), 65 deletions(-)

diffs (truncated from 682 to 300 lines):

diff -r fc72f005e7ce -r e8508443d32f bin/sh/sh.1
--- a/bin/sh/sh.1       Thu Mar 31 16:16:35 2016 +0000
+++ b/bin/sh/sh.1       Thu Mar 31 16:18:22 2016 +0000
@@ -1,4 +1,4 @@
-.\"    $NetBSD: sh.1,v 1.119 2016/02/24 15:28:36 wiz Exp $
+.\"    $NetBSD: sh.1,v 1.120 2016/03/31 16:18:22 christos 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 January 5, 2015
+.Dd March 31, 2016
 .Dt SH 1
 .ds flags abCEeFfhnuvxIimpqV
 .Os
@@ -330,9 +330,11 @@
 flag has no effect.
 .It Fl h Em trackall
 Bind commands in functions to file system paths when the function is defined.
+.\" They can seek me here (that dreaded filesystem)
 When off,
 the file system is searched for commands each time the function is invoked.
 (Not implemented.)
+.\" then can seek me there (the filesystem, once again)
 .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
@@ -352,6 +354,22 @@
 .Sx Built-ins
 section.)
 (Not implemented.)
+.It "\ \ " Em posix
+Enables closer adherence to the 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
+.Fl o
+option on the command line.
+Currently this option controls whether (!posix) or not (posix)
+the file given by the
+.Ev ENV
+variable is read at startup by a non-interactive shell.
+Consequently, while it can be manipulated by the
+.Ic set
+command, doing so has no current purpose.
 .It "\ \ " Em tabcomplete
 Enables filename completion in the command line editor.
 Typing a tab character will extend the current input word to match a
@@ -528,7 +546,9 @@
 .Li delimiter
 .El
 .Pp
-All the text on successive lines up to the delimiter, or to an EOF, is
+All the text on successive lines up to the delimiter,
+which must appear on a line by itself, with nothing other
+than an immediately following newline, is
 saved away and made available to the command on standard input, or file
 descriptor n if it is specified.
 If the delimiter as specified on the initial line is
@@ -538,10 +558,15 @@
 .Sx Word Expansions
 section below.
 If the operator is
-.Dq \*[Lt]\*[Lt]-
+.Dq \*[Lt]\*[Lt]\(mi
 instead of
 .Dq \*[Lt]\*[Lt] ,
-then leading tabs in the here-doc-text are stripped.
+then leading tabs in all lines in the here-doc-text, including before the
+end delimiter, are stripped.
+If the delimiter is not quoted, lines in here-doc-text that end with
+an unquoted \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.
 .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.
@@ -564,6 +589,7 @@
 Otherwise, if the command name doesn't match a function or built-in, the
 command is searched for as a normal program in the file system (as
 described in the next section).
+.\" But the damned elusive filesystem shall never be defeated!
 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
@@ -697,13 +723,18 @@
 If the shell is not interactive, the standard input of an asynchronous
 command is set to
 .Pa /dev/null .
+The process identifier of the most recent command started in the
+background can be obtained from the value of the special parameter
+.Dq \&!
+(see
+.Sx Special Parameters ) .
 .Ss Lists -- Generally Speaking
 A list is a sequence of zero 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 proceed onto the next command; otherwise it waits
+command and immediately proceeds to the next command; otherwise it waits
 for the command to terminate before proceeding to the next one.
 .Ss Short-Circuit List Operators
 .Dq \*[Am]\*[Am]
@@ -760,17 +791,19 @@
 .Pp
 The syntax of the for command is
 .Bd -literal -offset indent
-for variable in word ...
+for variable [ in word ... ]
 do   list
 done
 .Ed
 .Pp
-The words are expanded, and then the list is executed repeatedly with the
+The words are expanded, or "$@" if no words are given,
+and then the list is executed repeatedly with the
 variable set to each word in turn.
 do and done may be replaced with
 .Dq {
 and
-.Dq } .
+.Dq } ,
+but doing so is non-standard and not recommended.
 .Pp
 The syntax of the break and continue command is
 .Bd -literal -offset indent
@@ -821,7 +854,7 @@
 .Ss Functions
 The syntax of a function definition is
 .Pp
-.Dl name ( ) command
+.Dl name ( ) command [ redirect... ]
 .Pp
 A function definition is an executable statement; when executed it
 installs a function named name and returns an exit status of zero.
@@ -829,6 +862,43 @@
 .Dq {
 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.
+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
+.Dl l() ls "$@"
+works to make
+.Dq l
+an alternative name for the
+.Ic ls
+command.
+.Pp
+If the optional redirect, (see
+.Sx Redirections ) ,
+which may be of any of the normal forms,
+is given, it is applied each time the
+function is called.
+This means that a simple
+.Dq "Hello World
+function might be written (in the extended syntax) as:
+.Dl hello() cat <<EOF
+.Dl Hello World!
+.Dl EOF
+To be correctly standards conforming this should be re-written as:
+.Dl hello() { cat; } <<EOF
+.Dl Hello World!
+.Dl EOF
+Note the distinction between those forms, and
+.Dl hello() { cat <<EOF
+.Dl Hello World!
+.Dl EOF
+.Dl \&}
+which reads and processes the
+.Ic "here document
+each time the shell executes the function, and which applies
+that input only to the cat command, not to any other commands
+that might appear in the function.
 .Pp
 Variables may be declared to be local to a function by using a local
 command.
@@ -836,18 +906,43 @@
 .Pp
 .Dl local [ variable | - ] ...
 .Pp
-.Dq Local
+.Dq Ic local
 is implemented as a built-in command.
 .Pp
-When a variable is made local, it inherits the initial value and exported
+When a variable is made local, it inherits the initial value and exported,
+unexportable,
 and read-only flags from the variable with the same name in the surrounding
 scope, if there is one.
 Otherwise, the variable is initially unset.
+Making a read-only variable local is possible, but pointless.
+If the
+.Ic readonly
+command is applied to a variable that has been declared local,
+the variable cannot be (further) modified within the function,
+or any other functions it calls, however when the function returns,
+the previous status (and value) of the variable is returned.
+.Pp
+Values may be given to local variables on the
+.Ic local
+command line in a similar fashion as used for
+.Ic export
+and
+.Ic readonly .
+.Pp
 The shell uses dynamic scoping, so that if you make the variable x local to
 function f, which then calls function g, references to the variable x made
 inside g will refer to the variable x declared inside f, not to the global
 variable named x.
 .Pp
+Note that the parameters $1, $2, ... (see
+.Sx Positional Parameters ) ,
+and $#, $* and $@ (see
+.Sx Special Parameters ) ,
+are always made local in all functions, and are reset inside the
+function to represent the options and arguments passed to the function.
+Note that $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
 .Dq - .
 Making
@@ -856,12 +951,26 @@
 function to be restored to their original values when the function
 returns.
 .Pp
+It is a syntax error to use
+.Ic local
+outside the scope of a function definition.
+When used inside a function, it exits with status 0.
+.Pp
 The syntax of the return command is
 .Pp
 .Dl return [ exitstatus ]
 .Pp
-It terminates the currently executing function.
+It terminates the currently executing function or
+.Dq \&.
+script.
 Return is implemented as a built-in command.
+The exit status of the function (or
+.Dl \&.
+command) is either that given on the
+.Ic return
+command line, or the value of the special parameter
+.Dq $?
+immediately before the return was executed.
 .Ss Variables and Parameters
 The shell maintains a set of parameters.
 A parameter denoted by a name is called a variable.
@@ -882,7 +991,21 @@
 that follow the name of the shell script.
 The
 .Ic set
-built-in can also be used to set or reset them.
+built-in can also be used to set or reset them, and
+.Ic shift
+can be used to manipulate the list.
+.Pp
+To refer to the 10th (and later) positional parameters,
+the form ${n} must be used.
+Without the braces, a digit following
+.Dq $
+can only refer to one of the first 9 positional parameters,
+or the special parameter
+.Dq 0 .
+The word
+.Dq $10
+is treated identically to
+.Dq ${1}0 .
 .Ss Special Parameters
 A special parameter is a parameter denoted by one of the following special
 characters.
@@ -936,6 +1059,12 @@
 Expands to the process ID of the most recent background
 command executed from the current shell.
 For a pipeline, the process ID is that of the last command in the pipeline.
+If no background commands have yet been started by the shell, then
+.Dq \&!
+will be unset.
+Once set, the value of
+.Dq \&!
+will be retained until another background command is started.
 .It 0 (Zero.)
 Expands to the name of the shell or shell script.
 .El
@@ -1023,7 +1152,7 @@
 is omitted in the following modifiers, then the expansion is applied only
 to unset parameters, not null ones.
 .Bl -tag -width aaparameterwordaaaaa