sh(1): fix few relatively recently introduced typos (rev 1.265).
s/agument/argument/
s/suport/support/
s/prvileges/privileges/

Better explain the expansions in case statements.

nb: no Dd bump, this change is not significant enough to warrant that.

This commit is intended to be what was intended to happen in the
commit of Sun Nov 10 01:22:24 UTC 2024, see:

http://mail-index.netbsd.org/source-changes/2024/11/10/msg154310.html

The commit message for that applies to this one (wholly). I believe that
the problem with that version which caused it to be reverted has been found
and fixed in this version (a necessary change was made as part of one of
the fixes, but the side-effect implications of that were missed -- bad bad me.)

In addition, I found some more issues with setting close-on-exec on other
command lines

With:
func 3>whatever

fd 3 (anything > 2) got close on exec set. That makes no difference
to the function itself (nothing gets exec'd therefore nothing gets closed)
but does to any exec that might happen running a command within the function.

I believe that if this is done (just as if "func" was a regular command,
and not a function) such open fds should be passed through to anything
they exec - unless the function (or other command) takes care to close the
fd passed to it, or explicitly turn on close-on exec.

I expect this usage to be quite rare, and not make much practical difference.

The same applies do builtin commands, but is even less relevant there, eg:

printf 3>whatever

would have set close-on-exec on fd 3 for printf. This is generally
completely immaterial, as printf - and most other built-in commands -
neither uses any fd other than (some of) 0 1 & 2, nor do they exec anything.

That is, except for the "exec" built-in which was the focus of the original
fix (mentioned above) and which should remain fixed here, and for the "."
command.

Because of that last one (".") close-on-exec should not be set on built-in
commands (any of them) for redirections on the command line. This will
almost never make a difference - any such redirections last only as long
as the built-in command lasts (same with functions) and so will generally
never care about the state of close-on-exec, and I have never seen a use
of the "." command with any redirections other than stderr (which is unaffected
here, fd's <= 2 never get close-on-exec set). That's probably why no-one
ever noticed.

There are still "fd issues" when running a (non #!) shell script, that
are hard to fix, which we should probably handle the way most other shells
have, by simply abandoning the optimisation of not exec'ing a whole new
shell (#! scripts do that exec) and just doing it that way. Issues solved!
One day.

Revert the recent change until I can work out how things are broken.

exec builtin command redirection fixes

Several changes, all related to the exec special built in command,
or to close on exec, one way or another. (Except a few white space
and comment additions, KNF, etc)

1. The bug found by Edgar Fuß reported in:
http://mail-index.netbsd.org/tech-userlevel/2024/11/05/msg014588.html
has been fixed, now "exec N>whatever" will set close-on-exec for fd N
(as do ksh versions, and allowed by POSIX, though other shells do not)
which has happened now for many years. But "exec cmd N>whatever"
(which looks like the same command when redirections are processed)
which was setting close-on-exec on N, now no longer does, so fd N
can be passed to cmd as an open fd.

For anyone who cares, the big block of change just after "case CMDBUILTIN:"
in evalcommand() in eval.c is the fix for this (one line replaced by
about 90 ... though most of that is comments or #if 0'd example code
for later). It is a bit ugly, and will get worse if our exec command
ever gets any options, as others have, but it does work.

2. when the exec builtin utility is used to alter the shell's redirections
it is now "all or nothing". Previously the redirections were executed
left to right. If one failed, no more were attempted, but the earlier
ones remained. This makes no practical difference to a non-interactive
shell, as a redirection error causes that shell to exit, but it makes
a difference to interactive shells. Now if a redirection fails, any
earlier ones which had been performed are undone. Note however that
side-effects of redirections (like creating, or truncating, files in
the filesystem, cannot be reversed - just the shell's file descriptors
returned to how they were before the error).

Similarly usage errors on exec now exist .. our exec takes no options
(but does handle "--" as POSIX says it must - has done for ages).
Until now, that was the only magic piece of exec, running
exec -a name somecommand
(which several other shells support) would attempt to exec the "-a"
command, and most likely fail, causing immediate exit from the shell.
Now that is a usage error - a non-interactive shell still exits, as
exec is a special builtin, and any error from a special builtin causes
a non-interactive shell to exit. But now, an interactive shell will
no longer exit (and any redirections that were on the command will be
undone, the same as for a redirection error).

3. When a "close on exec" file descriptor is temporarily saved, so the
same fd can be redirected for another command (only built-in commands
and functions matter, redirects for file system commands happen after
a fork() and at that stage if anything goes wrong, the child simply
exits - but for non-forking commands, doing something like printf >file
required the previous stdout to be saved elsewhere, "file" opened to
be the new stdout, then when printf is finished, the old stdout moved
back. Anyway, if the fd being moved had close on exec set, then
when it was moved back, the close on exec was lost. That is now fixed.

4. The fdflags command no longer allows setting close on exec on stdin,
stdout, or stderr - POSIX requires that those 3 fd's always be open
(to something) when any normal command is invoked. With close-on-exec
set on one of these, that is impossible, so simply refuse it (when
"exec N>file" sets close on exec, it only does it for N>2).

Minor changes (should be invisible)

a. The shell now keeps track of the highest fd number it sees doing
normal operations (there are a few internal pipe() calls that aren't
monitored and a couple of others, but in general the shell will now
know the highest fd it ever saw allocated to it). This is mostly
for debugging.

b. calls to fcntl() passing an int as the "arg" are now all properly
cast to the void * that the fcntl kernel is expecting to receive.
I suspect that makes no actual difference to anything, but ...

Add a -r (version) option to sh

This new -r (or +r) option is for command line use only.
When encountered, the shell simply prints its version info
(such as it has, which isn't much) and exits (immediately).

This allows "funny" uses like
sh -version
the -v and -e options are standard, and processed as normal
(changing nothing, yet, except setting the option). Then the
'r' option is seen, the version info is printed, and the shell
exits. Any remaining "options" (there is no "-o n" option) are
ignored, as are any other args given to the shell.

The string printed (currently) is just "NetBSD shell:" followed
by the value of the NETBSD_SHELL variable (which has been established
already by the time options are processed).

Add -b and -nMAX options to the read builtin.

As requested on (perhaps more than one) mailing list, this adds
a -n MAX option, to allow the amount of data read by the read
builtin to be limited to MAX bytes (in case the record delimiter
doesn't appear in the input for a long time). There is
currently an upper bound of 8MiB on the value of MAX.

Also add a -b option, which allows for buffered input (with
some usage caveats) rather than 1 byte at a time.

Neither option exists in SMALL shells.

Note that the proposed -z option got deleted ... I couldn't
find a rational way to explain what the final state would be
if a \0 on input generated an error, so rather than have
things ambiguous, better just not to have the option, and
simply keep ignoring input \0's as always.

See the (updated) sh(1) man page for more details.

No pullups planned (new feature, only for new releases).

PR bin/58687 -- implement suspend as a builtin in sh

Requested by uwe@ in PR bin/58687 without objections from
anyone except me, here is an implementation of a suspend
builtin command for /bin/sh

The sh.1 man page is updated, naturally, to describe it.

This new builtin does not exist in SMALL shells -- as used
on (some) boot media, etc.

If this turns out not to be useful, it can easily be removed.

In !TINYPROG versions of sh, make the builtin "shift" builtin command
perform a rotate instead or shift if given a numeric arg (which is
otherwise an error).

"set -- a b c; shift -1; echo $*" will echo "c a b".

While here, make the shift builtin comply with POSIX, and accept
(and ignore) a '--' arg before the shift (or rotate) count.

Document the variant of shift in sh(1)

Adapt the shell test for shift to not expect "shift -1" to be an
error, test that rotate works as expected, and include some tests
that use the (useless, but required) "--" arg.

sh(1): fix up formatting of syntax examples

.Bd -literal with all lines explicitly formatted (usually with .Ic)
doesn't seem to work too well with mandoc shipped with the heirloom
doctools - the next paragraph after the display remains literal.
Use .Bd -unfilled instead.

Implement the HISTFILE and HISTAPPEND variables.

See the (newly updated) sh(1) for details.
Also add the -z option to fc (clear history).

None of this exists in SMALL shells.

Remove caveat about $'' quoting, now POSIX.1-2004 exists.

nb: no Dd bump, that's coming soon (not needed for this change anyway)

branches: 1.260.2;
Edgar Fuß pointed out that sh(1) did not mention comments (at all).
This has been true forever, and no-one else (including me) ever seems
to have noticed this ommission.

Correct that.

While in the area, improve the general sections on the Lexical structure
of the shell's input, and including some refinements to how quoting is
described.

Remove an ancient incorrect notion which somehow survived intact for ages.
"$@" is (as it is in double quotes) not subject to field splitting. "$@"
generates (potentially) multiple words, but field splitting has nothing
to do with it.

While here, rename the section from "White Space Splitting (Field Splitting)"
to simply be "Field Splitting" as white space is only relevant if it happens
to occur in IFS (which is the default case, but IFS can be anything, and
isn't required to contain any white space at all).

sh(1): touch up markup for the ENV example

Don't use Dq in a literal display, ascii quotes are \*q
While here mark up as literal a few things around this example.

At the request of bad@ enhance the synopsis of the set built-in
command to include explicit mention of the -o opt and +o opt forms.

Fix the synopsis to have the 4 forms that the description of the
utility discusses, rather than expecting users to understand that
the 3rd and 4th forms of the command were combined into the 3rd
synopsis format. After doing that, the options in the 3rd format
no longer need to be optional, so now all 4 formats are distinct
(previously, the third, omitting everything that was optional, and
the first, could not be distinguished).

While here, some wording and formatting "improvements" as well (nothing
too serious).

tyops:
* redicection -> redirection
* escaoed -> escaped

Noted by J. Lewis Muir on netbsd-docs@

More markup errors. \+ was intended to be \&+ and .EV .Ev of course.
As best I can tell, the rest of what mandoc -Wall complains about is
incorrect (it could probably be avoided by adding more markup, but
there doesn't seem to be any point).

Using .Cm Cm makes no sense at all - no idea what I was thinking there
(perhaps just an editing error).

sh(1): Fix markup. -compact must be last.

branches: 1.252.2;

It appears that POSIX intends to add a -d X option to the read command
in its next version, so it can be used as -d '' (to specify a \0 end
character for the record read, rather than the default \n) to accompany
find -print0 and xargs -0 options (also likely to be added).

Add support for -d now. While here fix a bug where escaped nul
chars (\ \0) in non-raw mode were not being dropped, as they are
when not escaped (if not dropped, they're still not used in any
useful way, they just ended the value at that point).

Note in the description of "jobs -p" that the process id returned is
also the process group identifier (that's a requirement from POSIX, and
is what we have always done - just not been explicit about in sh.1).
Add a note that this value and $! are not necessarily the same (currently,
and perhaps forever, never the same in a pipeline with 2 or more elements).

Add the -l option (aka -o login): be a login shell. Meaningful only on
the command line (with both - and + forms) - overrides the presence (or
otherwise) of a '-' as argv[0][0].

Since this allows any shell to be a login shell (which simply means that
it runs /etc/profile and ~/.profile at shell startup - there are no other
side effects) add a new, always set at startup, variable NBSH_INVOCATION
which has a char string as its value, where each char has a meaning,
more or less related to how the shell was started. See sh(1).
This is intended to allow those startup scripts to tailor their behaviour
to the nature of this particular login shell (it is possible to detect
whether a shell is a login shell merely because of -l, or whether it would
have been anyway, before the -l option was added - and more). The
var could also be used to set different values for $ENV for different
uses of the shell.

More wording improvements. There might be more to come.

Minor wording improvements.

Note these do not alter anything about what the man page specifies,
just say a couple of things in a slightly better way, hence no Dd
update accompanies this change (deliberately).

Move a comment that used to be in the correct place, once upon a time,
back where it belongs, and make it stand out more, so other text is
less likely to find itself pushed between the comment and the text
to which it appears. This change should make no visible difference
to the man page displayed.

Whitespace.

Correct spelling of terminal (it doesn't have a 2nd m).

Improve the description of the read builtin command.

sh(1): improve getopts docs for optstring leading :

getopts has different behaviour if the leading character
of optstring is `:', so describe in more detail:
- no errors are printed (already there)
- unknown options set var to `?' and OPTARG to the unknown option
- missing arguments set var to `:' and OPTARG to the option name

Slight rewording of other paragraphs for more clarity.

sh(1): fix formatting warnings

Improve the however-many-negatives wording even more.

sh.1: replace triple negation with single negation, fix typo

Improve the wording of the "Argument List Processing" section (where
all the sh options, also used with "set", are listed) in response to
a discussion on icb conveyed to me by Darrin B. Jewell.
A few improvements to the description of the "set" built-in as well.

Bump Dd to cover all of this month's changes (so far).

sh.1: fix typos

PR bin/56491

Make "hash" exit(!=0) (ie: exit(1)) if it writes an error message to
stderr as required by POSIX (it was writing "not found" errors, yet
still doing exit(0)).

Whether, when doing "hash foobar", and "foobar" is not found as a command
(not a built-in, not a function, and not found via a PATH search), that
should be considered an error differs between shells. All of the ksh
descendant shells say "no", write no error message in this case, and
exit(0) if no other errors occur. Other shells (essentially all) do
consider it an error, write a message to stderr, and exit(1) when this happens.

POSIX isn't clear, the bug report:
https://austingroupbugs.net/view.php?id=1460
which is not yet resolved, suggests that the outcome will be that
this is to be unspecified. Given the diversity, there might be no
other choice.

Have a foot in both camps - default to the "other shell" behaviour,
but add a -e option (no errors ... applies only to these "not found"
errors) to generate the ksh behaviour. Without other errors (like an
unknown option, etc) "hash -e anyname" will always exit(0).

See the PR for details on how it all works now, or read the updated man page.

While here, when hash is in its other mode (reporting what is in the
table) check for I/O errors on stdout, and exit(1) (with an error
message!) if any occurred. This does not apply to output generated
by the -v option when command names are given (that output is incidental).

In sh.1 document all of this. Also add documentation for a bunch of
other options the hash command has had for years, but which were never
documented. And while there, clean up some other sections I noticed
needed improving (either formatting or content or both).

PR bin/45390

Be explicit about what happens to PWD after a successful cd command.
Also be very clear that "cd" and "cd -P" are the same thing, and
the only cd variant implemented.

Also, when it is appropriate to print the new directory after a cd
command, note that it happens if interactive (as it always has here)
and also if the posix option is set (for POSIX compat, where "interactive"
is irrelevant). Mention that "cd -" is a case where the new directory
is printed (along with paths relative to a non-empty CDPATH entry,
and where the "cd old new" (string replacement in curdir) is used.

While here document the new -e option to cd.

XXX pullup -9

PR bin/56464

After almost 30 years, finally do the right thing and read $HOME/.profile
rather than .profile in the initial directory (it was that way in version
1.1 ...) All other ash descendants seem to have fixed this long ago.

While here, copy a feature from FreeBSD which allows "set +p" (if a
shell run by a setuid process with the -p flag is privileged) to reset
the privileges. Once done (the set +p) it cannot be undone (a later
set -p sets the 'p' flag, but that's all it does) - that just becomes a
one bit storage location.

We do this, as (also copying from FreeBSD, and because it is the right
thing to do) we don't run .profile in a privileged shell - FreeBSD run
/etc/suid_profile in that case (not a good name, it also applies to setgid
shells) but I see no real need for that, we run /etc/profile in any case,
anything that would go in /etc/suid_profile can just go in /etc/profile
instead (with suitable guards so the commands only run in priv'd shells).

One or two minor DEBUG mode changes (notably having priv'd shells identify
themselves in the DEBUG trace) and sh.1 changes with doc of the "set +p"
change, the effect that has on $PSc and a few other wording tweaks.

XXX pullup -9 (not -8, this isn't worth it for the short lifetime
that has left - if it took 28+ years for anyone to notice this, it
cannot be having all that much effect).

Have the ulimit command watch for ulimit -n (alter number of available fds)
and keep the rest of the shell aware of any changes.

While here, modify 'ulimit -aSH' to print both the soft and hard limits
for the resources, rather than just (in this case, as H comes last) the
hard limit. In any other case when both S and H are present, and we're
examining a limit, use the soft limit (just as if neither were given).

No change for setting limits (both are set, unless exactly one of -H
or -S is given). However, we now check for overflow when converting
the value to be assigned, rather than just truncating the value however
it happens to work out...

Mark up NULL with Dv.

Improve the formatting of the list of Built-in commands for those
commands with multiple synopsis lines (eg: trap).

But there really must be a better way to achieve this effect than
the way it is accomplished here, and I'm hoping some wizard who
understands mdoc much better than I do will revert this change and
do it using some inspired magic incantation instead.

Don't dereference NULL on "jobs -Z" (with no title given), instead
do setproctitle(NULL) (which is not the same thing at all). Do the
same with jobs -Z '' as setting the title to "sh: " isn't useful.

Improve the way this is documented, and note that it is only done
this way because zsh did it first (ie: pass on the balme, doing this
in the jobs command is simply absurd.)

Add jobs -Z (like in zsh(1)) to setproctitle(3).

Remove superfluous Ed.

Correct an incorrectly quoted (unquoted, but should be) example used in
the "local" built-in command description (pointed out by mrg@ via uwe@ in
private e-mail).

Add a description to the export command of why this quoting is required,
and then refer to it from local and readonly (explained in export as that
one comes first).

Note that some shells parse export/local/readonly (and often more) as
"declarative" commands, and this quoting isn't needed (provided the
command name is literal and not the result of an expansion) making
X=$Y type args not require quoting, as they often don't in a regular
variable assignment (preceding, or not part of, another command).
POSIX is going to allow, but not require, that behaviour. We do not
implement it.

Idiot typo, generated by an idiot, fixed by the same one.

Remove unmatched .El and mark up signal name with Dv.

Man page enhancements.

Better describe the command search procedure.
Document "trap -P"
Describe what works as a function name.
More accurate description of reserved word recognition.
Be more accurate about when field splittng happens after
expansions (and in particular note that tilde expansions are
not subject to field splitting). Be clear that "$@" is
not field split, it simply produces multiple fields as part
of its expansion (hence IFS is irrelevant to this), but if
used as $@ (unquoted) each field produced is potentially subject
to field splitting. Other minor wording changes.

Typo: s/./,/

branches: 1.223.2;

Bump date for previous.

PR standards/40554

Update the description of the <& and >& redirection operators
(as indicated would happen in a message appended to the PR a week ago,
which received no opposition - no feedback).

Some rewriting of the section on redirects (including how the word
expansion of the "file" works) to make this simpler & more accurate.

-compact must come last

Add the "specialvar" built-in command. Discussed (well, mentioned
anway) on tech-userlevel with no adverse response.

This allows the magic of vars like HOSTNAME SECONDS, ToD (etc) to be
restored should it be lost - perhaps by having a var of the same name
imported from the environment (which needs to remove the magic in case
a set of scripts are using the env to pass data, and the var name chosen
happens to be one of our magic ones).

No change to SMALL shells (or smaller) - none of the magic vars (except
LINENO, which is exempt from all of this) exist in those, hence such a
shell has no need for this command either.

Remove leading zero from date.

PR bin/53919

Suppress shell error messages while expanding $ENV (which also causes
errors while expanding $PS1 $PS2 and $PS4 to be suppressed as well).

This allows any random garbage that happens to be in ENV to not
cause noise when the shell starts (which is effectively all it did).

On a parse error (for any of those vars) we also use "" as the result,
which will be a null prompt, and avoid attempting to open any file for ENV.

This does not in any way change what happens for a correctly parsed command
substitution (either when it is executed when permitted for one of the
prompts, or when it is not (which is always for ENV)) and commands run
from those can still produce error output (but shell errors remain suppressed).

Add an explanation of the error (warning)
RANDOM initialisation failed
when the shell might print after RANDOM has been reseeded
(which includes at sh startup) the next time RANDOM is accessed.
It indicates that /dev/urandom was not available or did not
provide data - in that case, sh uses a (weak) seed made out of
the pid and time (but otherwise nothing else changes).

Reverse a decision made when the printsignals() routines from
kill and sh were merged so that the shell (for trap -l) and
kill (for kill -l) can use the same routine, and site that function
in the shell, rather than in kill (use the code that is in kill as
the basis for that routine). This allows access to sh internals,
and in particular to the posix option, so the builtin kill can
operate in posix mode where the standard requires just a single
character (space of newline) between successive signal names (and
we prefer nicely aligned columns instead)..

In a SMALL shell, use the ancient sh printsignals routine instead,
it is smaller (and very much dumber).

/bin/kill still uses the routine that is in its source, and is
not posix compliant. A task for some other day...

More fixes for the SYNPOSIS of the readonly built-in.
The SYNOPSIS for "readonly -q" cannot have the -q be
optional ... Also harmonise the output appearance with
that of the export command.

wiz: have at it...

Fix Oo Op Oc syntax error (which seemed to work OK to me....)
Pointed out by wiz@

Implement:
readonly -q VAR...
readonly -p VAR...
export -q [-x] VAR...
export -p [-x] VAR...

all available only in !SMALL shells - and while here, limit
"export -x" to full sized shells as well.

Also, do a better job of arg checking and validating of the
export and readonly commands (which is really just one built-in)
and of issuing error messages when something bogus is detected.

Since these commands are special builtin commands, any error
causes shell exit (for non-interactive shells).

PR standards/42829

Implement parameter and arithmetic expansion of $ENV
before using it as the name of a file from which to
read startup commands for the shell. This continues
to happen for all interactive shells, and non-interactive
shells for which the posix option is not set (-o posix).

On any actual error, or if an attempt is made to use
command substitution, then the value of ENV is used
unchanged as the file name.

The expansion complies with POSIX XCU 2.5.3, though that
only requires parameter expansion - arithmetic expansion
is an extension (but for us, it is much easier to do, than
not to do, and it allows some weird stuff, if you're so
inclined....) Note that there is no ~ expansion (use $HOME).

Alter a design botch when magic (self modifying) variables
were added to sh ... in other shells, setting such a variable
(for most of them) causes it to lose its special properties,
and act the same as any other variable. I had assumed that
was just implementor laziness... I was wrong.

From now on the NetBSD shell will act like the others, and if vars
like HOSTNAME (and SECONDS, etc) are used as variables in a script
or whatever, they will act just like normal variables (and unless
this happens when they have been made local, or as a variable-assignment
as a prefix to a command, the special properties they would have had
otherwise are lost for the remainder of the life of the (sub-)shell
in which the variables were set).

Importing a value from the environment counts as setting the
value for this purpose (so if HOSTNAME is set in the environment,
the value there will be the value $HOSTNAME expands to).

The two exceptions to this are LINENO and RANDOM. RANDOM
needs to be able to be set to (re-)set its seed. LINENO needs to
be able to be set (at least in the "local" command) to achieve
the desired functionality. It is unlikely that any (sane) script
is going to want to use those two as normal vars however.

While here, fix a minor bug in popping local vars (fn return) that need
to notify the shell of changes in value (like PATH).

Change sh(1) to reflect this alteration. Also add doc of the
(forgotten) magic var EUSER (which has been there since the others
were added), and add a few more vars (which are documented
in other places in sh(1) - like ENV) into the defined or used
variable list (as well as wherever else they appear).

XXX pullup -8

Cleanup traps a bit - attempt to handle weird uses in traps, such
as traps that issue break/continue/return to cause the loop/function
executing when the trap occurred to break/continue/return, and
generating the correct exit code from the shell including when a
signal is caught, but the trap handler for it exits.

All that from FreeBSD.

Also make
T=$(trap)
work as it is supposed to (also trap -p).

For now this is handled by the same technique as $(jobs) - rather
than clearing the traps in subshells, just mark them invalid, and
then whenever they're invalid, clear them before executing anything
other than the special blessed "trap" command. Eventually we will
handle these using non-subshell command substitution instead (not
creating a subshell environ when the commands in a command-sub alter
nothing in the environment).

Avoid long option names that differ only in character case.
Change Xtrace (the name) to xlock instead. Aside from the different
name, there is no change to functionality.

Change the way the pipefail option works. Now it is the setting of
the option when a pipeline is created that controls the way the exit
status of the pipeline is calculated. Previously it was the state of
the option when the exit status of the pipeline was collected.

This makes no difference at all for foreground pipelines (there is
no way to change the option between starting and completing the
pipeline) but it does for asynchronous (background) pipelines.

This was always the right way to implement it - it was originally
done the other way as I could not find any other shell implemented
this way - they all seemed to do it our previous way, and I could
not see a good reason to be the sole different shell.

However, now I know that ksh93 works as we will now work, and I
am told that if the option is added to the FreeBSD shell (apparently
the code exists, uncommitted) it will be the same.

PR bin/48875

Add a paragraph (briefer than previously posted to mailing lists)
to explain that there is no guarantee that the results of a command
substitution will be available before all commands started by the
cmdsub have completed.

Include the original proposed text (much longer) as *roff comments, so
it will at least be available to those who browse the man page sources.

While here, clean up the existing text about command substitutions to
make it a little more accurate (and to advise against using the `` form).

branches: 1.206.2;
Remove Pps without effect.

Simplify convoluted language, and remove incorrect statement
(that I added a while ago) about what is required by POSIX.

Minor grammatical correction (don't end a sentence/phrase with a
preposition).

Drop "show or set the limit on" legalese from the description of each
and every option to ulimit built-in. The show-or-set text is already
supplied *both* before and after the list. Pedantically repeating it
for each option just adds a lot of visual clutter that gets in the way
of actually using this fragment of the manual page as a quick
reference.

Tweak "ulimit" synopsis.

Cleanup markup in the "Command Line Editing" section.

Cleanup markup in the "Job Control" section.

Use .Dv, not .Ev, to refer to LINENO, it's not an environment variable.

Default values of PS1 and friends have only single space. Use .Li to
typeset them to make that space more visible in PostScript output.

Use .Bd -literal for code example.

Markup fixes (partly from uwe@) and change some tabs to spaces, they
seem to work better...

Restore some (*roff) comments deleted in previous (partially unshave
the yak) for which the purpose was misunderstood. But trim one more hair.

Give the yak a quick trim and shave, and make one or two minor
wording changes (which are, hopefully, improvements).

Start adding more gaudy markup. Use .Li or .Dv when referring to
parameters. Use more .Ic and .Ar when defining syntax.

The manual is still rather inconsistent e.g. when referring to
parameters where it randomly uses both $0 and 0 or $@ and @ - but I'm
not shaving that yak at least for now.

Compute tag width for the list of options in Argument List Processing,
mandoc *is* up to that. Remove the part of the comment before the
list that was wondering about that.

Small markup tweaks in Argument List Processing

Instead of .Oo/.Oc use .Op directly where possible.

Revert previous. Fix the real problem properly.

Remove Ic macro without effect.

Try to improve markup in the Built-ins section.
Mostly sprinkle missing .Ic and .Ar

Try to improve markup in the Parameter Expansion section.

Try to improve markup of the redirections definitions.

Fix horrendous markup abuse in the here-document example.
Consistently spell "here-document" in full.

Spell "here-document" with a hyphen, don't mark it up as a command.

Mark up "in" (of the "for" command) appropriately.

Use \(or not \*(Ba when discussing case patterns.

Use \(em for em-dash

Standalone | means \[ba] while we want \[or] so add \& protection to
the few places where it was missing.

.Dl is a a single line .Bd -literal -offset indent so don't abuse
multiple consecutive .Dl and use proper .Bd instead.

.Bd expects the display type to come first, so move -compact to the end.

Add missing word.

branches: 1.175.2;

Paul Goyette suggested improvements to parts of the description of
LINENO ... this is what resulted (with thanks for the grammar lessons,
and sundry references provided!)

No date (Dd) bump - there is no change of substance here, just (hopefully)
a clearer way of saying the same thing.

Implement the -X option - an apparent variant of -x which sends all trace
output to the stderr which existed when the -X option was (last) enabled.
It also enables tracing by enabling -x (and when reset, +X, also resets
the 'x' flag (+x)). Note that it is still -x/+x which actually
enables/disables the trace output. Hence "apparent variant" - what -X
actually does (aside from setting -x) is just to lock the trace output,
rather than having it follow wherever stderr is later redirected.

Correct a typo: s/ at / an /

Minor spellchecking changes.

Correct a markup typo (Sv -> Dv)

Add '-n' and '-p var' args to the wait command (-n: wait for any,
-p var: set var to identifier, from arg list, or PID if no job args)
of the job for which status is returned (becomes $? after wait.)

Note: var is unset if the status returned from wait came from wait
itself rather than from some job exiting (so it is now possible to
tell whether 127 means "no such job" or "job did exit(127)", and
whether $? > 128 means "wait was interrupted" or "job was killed
by a signal or did exit(>128)". ($? is too limited to to allow
indicating whether the job died with a signal, or exited with a
status such that it looks like it did...)

Add options to the builtin jobid command to allow discovering the
process group (-g), the process leader pid (-p) ($! if the job was &'d)
and the job identifier (-j) (the %n that refers to the job) in addition to
(default) the list of all pids in the job (which it has always done).
No change to the (single) "job" arg, which is a specifier of the job:
the process leader pid, or one of the % forms, and defaults to %% (aka %+).
(This is all now documented in sh(1))

Also document the jobs command properly (no change to the command, just
document what it actually is.)

And while here, a whole new section in sh(1) "Job Control". It probably
needs better wording, but this is (perhaps) better than the nothing that
was there before.

Fix typo: s/one or mode/one or more/

Three fixes and a change to ~ expansions

1. A serious bug introduced 3 1/2 months ago (approx) (rev 1.116) which
broke all but the simple cases of ~ expansions is fixed (amazingly,
given the magnitude of this problem, no-one noticed!)

2. An ancient bug (probably from when ~ expansion was first addedin 1994, and
certainly is in NetBSD-6 vintage shells) where ${UnSeT:-~} (and similar)
does not expand the ~ is fixed (note that ${UnSeT:-~/} does expand,
this should give a clue to the cause of the problem.

3. A fix/change to make the effects of ~ expansions on ${UnSeT:=whatever}
identical to those in UnSeT=whatever In particular, with HOME=/foo
${UnSeT:=~:~} now assigns, and expands to, /foo:/foo rather than ~:~
just as VAR=~:~ assigns /foo:/foo to VAR. Note this is even after the
previous fix (ie: appending a '/' would not change the results here.)

It is hard to call this one a bug fix for certain (though I believe it is)
as many other shells also produce different results for the ${V:=...}
expansions than they do for V=... (though not all the same as we did).

POSIX is not clear about this, expanding ~ after : in VAR=whatever
assignments is clear, whether ${U:=whatever} assignments should be
treated the same way is not stated, one way or the other.

4. Change to make ':' terminate the user name in a ~ expansion in all cases,
not only in assignments. This makes sense, as ':' is one character that
cannot occur in user names, no matter how otherwise weird they become.
bash (incl in posix mode) ksh93 and bosh all act this way, whereas most
other shells (and POSIX) do not. Because this is clearly an extension
to POSIX, do this one only when not in posix mode (not set -o posix).

Whitespace fixes. Fix a typo. Refer to emacs using Ic, since emacs(1)
does not exist in the base system.

Remove unnecessary Tn macro.

Add support for $'...' quoting (based upon C "..." strings, with \ expansions.)

Implementation largely obtained from FreeBSD, with adaptations to meet the
needs and style of this sh, some updates to agree with the current POSIX spec,
and a few other minor changes.

The POSIX spec for this ( http://austingroupbugs.net/view.php?id=249 )
[see note 2809 for the current proposed text] is yet to be approved,
so might change. It currently leaves several aspects as unspecified,
this implementation handles those as:

Where more than 2 hex digits follow \x this implementation processes the
first two as hex, the following characters are processed as if the \x
sequence was not present. The value obtained from a \nnn octal sequence
is truncated to the low 8 bits (if a bigger value is written, eg: \456.)
Invalid escape sequences are errors. Invalid \u (or \U) code points are
errors if known to be invalid, otherwise can generate a '?' character.
Where any escape sequence generates nul ('\0') that char, and the rest of
the $'...' string is discarded, but anything remaining in the word is
processed, ie: aaa$'bbb\0ccc'ddd produces the same as aaa'bbb'ddd.

Differences from FreeBSD:
FreeBSD allows only exactly 4 or 8 hex digits for \u and \U (as does C,
but the current sh proposal differs.) reeBSD also continues consuming
as many hex digits as exist after \x (permitted by the spec, but insane),
and reject \u0000 as invalid). Some of this is possibly because that
their implementation is based upon an earlier proposal, perhaps note 590 -
though that has been updated several times.

Differences from the current POSIX proposal:
We currently always generate UTF-8 for the \u & \U escapes. We should
generate the equivalent character from the current locale's character set
(and UTF8 only if that is what the current locale uses.)
If anyone would like to correct that, go ahead.

We (and FreeBSD) generate (X & 0x1F) for \cX escapes where we should generate
the appropriate control character (SOH for \cA for example) with whatever
value that has in the current character set. Apart from EBCDIC, which
we do not support, I've never seen a case where they differ, so ...

Remove trailing whitespace.

Implement the "pipefail" option (same semantics as in other shells)
to cause (when set, which it is not by default) the exit status of a
pipe to be 0 iff all commands in the pipe exited with status 0, and
otherwise, the status of the rightmost command to exit with a non-0
status.

In the doc, while describing this, also reword some of the text about
commands in general, how they are structured, and when they are executed.

Add support for ++ and -- (pre & post) and ',' to arithmetic.

Document the times builtin command, reported as lost in space
by rudolf at eq.cz on tech-userlevel (July 15, 2017.)

Also correct a typo, de-correct some entirely proper English so
the doc remains written in American instead. And note that
interactive mode is set when stdin & stderr are terminals, not
stding and stdout.

Sort options (our default is 0..9AaBbZz).
Fix markup problems and a typo.

Correct a markup typo (why did I not see this before the prev commit??)

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

Now libedit supports embedded mode switch sequence, improve sh
support for them (adds PSlit variable to set the magic character).

Make one example more like a real world possibility (it still isn't, but
is closer) - though the actual content is irrelevant to the point being made.

Get rid of workarounds for ancient groff html backend.
Simplify macro usage.

Properly support EDITRC - use it as (naming) the file when setting
up libedit, and re-do the config whenever EDITRC is set.

Changed the long name for the -L option from lineno_fn_relative
to local_lineno as the latter seemed to be marginally more popular,
and perhaps more importantly, is the same length as the peviously
existing quietprofile option, which means the man page indentation
for the list of options can return to (about) what it was before...
(That is, less indented, which means more data/line, which means less
lines of man page - a good thing!)

Improve the (new) LINENO section, markup changes (with thanks to wiz@ for
assistace) and some better wording in a few placed.

New sentence, new line. Whitespace.

A better LINENO implementation. This version deletes (well, #if 0's out)
the LINENO hack, and uses the LINENO var for both ${LINENO} and $((LINENO)).
(Code to invert the LINENO hack when required, like when de-compiling the
execution tree to provide the "jobs" command strings, is still included,
that can be deleted when the LINENO hack is completely removed - look for
refs to VSLINENO throughout the code. The var funclinno in parser.c can
also be removed, it is used only for the LINENO hack.)

This version produces accurate results: $((LINENO)) was made as accurate
as the LINENO hack made ${LINENO} which is very good. That's why the
LINENO hack is not yet completely removed, so it can be easily re-enabled.
If you can tell the difference when it is in use, or not in use, then
something has broken (or I managed to miss a case somewhere.)

The way that LINENO works is documented in its own (new) section in the
man page, so nothing more about that, or the new options, etc, here.

This version introduces the possibility of having a "reference" function
associated with a variable, which gets called whenever the value of the
variable is required (that's what implements LINENO). There is just
one function pointer however, so any particular variable gets at most
one of the set function (as used for PATH, etc) or the reference function.
The VFUNCREF bit in the var flags indicates which func the variable in
question uses (if any - the func ptr, as before, can be NULL).

I would not call the results of this perfect yet, but it is close.

Fix a typo (or rather a remnant of an earlier intent).

Make cd (really) do cd -P, and not just claim that is what it is doing
while doing a half-hearted, broken, partial, version of cd -L instead.
The latter (as the manual says) is not supported, what's more, it is an
abomination, and should never be supported (anywhere.)

Fix the doc so that the pretense that we notice when a path given crosses
a symlink (and turns on printing of the destination directory) is claimed
no more (that used to be true until late Dec 2016, but was changed). Now
the print happens if -o cdprint is set, or if an entry from CDPATH that is
not "" or "." is used (or if the "cd dest repl" cd cmd variant is used.)

Fix CDPATH processing: avoid the magic '%' processing that is used for
PATH and MAILPATH from corrupting CDPATH. The % magic (both variants)
remains undocumented.

Also, don't double the '/' if an entry in PATH or CDPATH ends in '/'
(as in CDPATH=":/usr/src/"). A "cd usr.bin" used to do
chdir("/usr/src//usr.bin"). No more. This is almost invisible,
and relatively harmless, either way....

Also fix a bug where if a plausible destination directory in CDPATH
was located, but the chdir() failed (eg: permission denied) and then
a later "." or "" CDPATH entry succeeded, "print" mode was turned on.
That is:
cd /tmp; mkdir bin
mkdir -p P/bin; chmod 0 P/bin
CDPATH=/tmp/P:
cd bin
would cd to /tmp/bin (correctly) but print it (incorrectly).

Also when in "cd dest replace" mode, if the result of the replacement
generates '-' as the path named, as in:
cd $PWD -
then simply change to '-' (or attempt to, with CDPATH search), rather
than having this being equivalent to "cd -")

Because of these changes, the pwd command (and $PWD) essentially
always acts as pwd -P, even when called as pwd -L (which is still
the default.) That is, even more than it did before.

Also fixed a (kind of minor) mem management error (CDPATH related)
"whosoever shall padvance must stunalloc before repeating" (and the
same for MAILPATH).

branches: 1.146.2;
Fix typo

More standard (and saner) implementation of the ! reserved word.
Unless the shell is compiled with the (compilation time) option
BOGUS_NOT_COMMAND (as in CFLAGS+=-DBOGUS_NOT_COMMAND) which it
will not normally be, the ! command (reserved word) will only
be permitted at the start of a pipeline (which includes the
degenerate pipeline with no '|'s in it of course - ie: a simple cmd)
and not in the middle of a pipeline sequence (no "cmd | ! cmd" nonsense.)
If the latter is really required, then "cmd | { ! cmd; }" works as
a standard equivalent.

In POSIX mode, permit only one ! ("! pipeline" is ok. "! ! pipeline" is not).
Again, if needed (and POSIX conformance is wanted) "! { ! pipeline; }"
works as an alternative - and is safer, some shells treat "! ! cmd" as
being identical to "cmd" (this one did until recently.)

It turns out that most shells do not do variable value/attribute
inheritance when a variable is declared local, but instead leave
the local var unset (if not given a value) in the function.
Only ash derived shells do inheritance it seems.

So, to compensate for that, and get one step closer to making
"local" part of POSIX, so we can really rely upon it, a compromise
has been suggested, where "local x" is implementation defined
when it comes to this issue, and we add "local -I x" to specify
inheritance, and "local -N x" to specify "not" (something...)
(not inherited, or not set, or whatever you prefer to imagine!)
The option names took a lot of hunting to find something reasonable
that no shell (we know of) had already used for some other purpose...
The I was easy, but 'u' 'U' 'X' ... all in use somewhere.

This implements that (well, semi-) agreement.

While here, add "local -x" (which many other shells already have)
which causes the local variable to be made exported. Not a lot
of gain in that (since "export x" can always be done immediately
after "local x") but it is very cheap to add and allows more other
scripts to work with out shell.

Note that while 'local x="${x}"' always works to specify inheritance
(while making the shell work harder), "local x; unset x" does not
always work to specify the alternative, as some shells have
"re-interpreted" unset of a local variable to mean something that
would best be described as "unlocal" instead - ie: after the unset
you might be back with the variable from the outer scope, rather
than with an unset local variable.

Also add "unset -x" to allow unsetting a variable without removing
any exported status it has.

There are gazillions of other options that are not supported here!

Allow abbreviations of option names for the "fdflags -s" command.
While documenting that, cleanup markup of the fdflags section of the
man page.

Command line, and "set" command options processing cleanup.

sh +c "command string" no longer works (it must be -c)
sh +o and sh -o no longer work (if you could call what they did
before working.) nb: this is without an option name.
-ooo Opt1 Opt2 Opt3 no longer works (set & cmd line), this should be
-o Opt1 -o Opt2 -o Opt3 (same with +ooo of course).
-oOpt is now supported - option value (name of option in
this case) immediately following -o (or +o).
(as with other commands that use std opt parsing)
Both set comamnd and command line.

In addition, the output from "set +o" has shrunk dramatically, by borrowing
a trick from ksh93 (but implemented in a more traditional syntax).
"set +o" is required to produce a command (or commands) which when executed
later, will return all options to the state they were in when "set +o"
was done. Previously that was done by generating a set command, with
every option listed (set -o opt +o other-opt ...) to set them all back
to their current setings. Now we have a new "magic option" ("default")
which sets all options to their default values, so now set +o output
need only be "set -o default -o changed-opt ..." (only the options that
have been changed from their default values need be explicitly mentioned.)
The definition of "default value" for this is the value the shell set the
option to, after startup, after processing the command line (with any
flags, or -o option type settings), but before beginning processing any
user input (incuding startup files, like $ENV etc).

Anyone can execute "set -o default" of course, but only from a "set"
command (it makes no sense at all as a -o option to sh). This also
causes "set +o" to be slightly more useful as a general command, as
ignoring the "set -o default" part of the result, it lists just those
options that have been altered after sh startup. There is no +o default.
There isn't an option called "default" at all...

This causes some of the commented out text from sh.1 to become uncommented.

When opening a file descritor with "exec n>/file" (and similar) only
set the close-on-exec bit when not in posix mode (to comply with posix...)
OK: christos@

Add mention of ;& in the list of control operators (forgotten before).
Document the (slightly) enhanced NETBSD_SHELL.
Fix a typo (one of my typos...)
Move a commented out section to align with current planned changes
(and fix its commented out markup.)

Use more, or more appropriate, markup.

Improve the description of option processing (including the shell's
arg list processing), and the set command in general.
Also add some (new) commented out text related to options which may
be commented back in sometime soon...

Corrected some typos, added some (hopefully improving) extra text,
sorted stuff that needed sorting, and added some (probably incorrect)
markup...

Enhance the trap command to make it possible to do what POSIX wants
(even if no shell in existence, that I am aware of, does that).

That is, POSIX says ... [of the trap command with no args]

The shell shall format the output, including the proper use of
quoting, so that it is suitable for re-input to the shell as commands
that achieve the same trapping results. For example:

save_traps=$(trap)

...

eval "$save_traps"

It is obvious what the intent is there. But no shell makes it work.

An example using bash (as the NetBSD shell, still does not do the save_traps=
stuff correctly - but that is a problem for a different time and place...)

Given this script

printf 'At start: '; trap
printf '\n'

traps=$(trap)
trap 'echo hello' INT
printf 'inside : '; trap
printf '\n'
eval "${traps}"

printf 'At end : '; trap
printf '\n'

One would expect that (assuming no traps are set at the start, and
there aren't) that the first trap will print nothing, then the inside
trap will show the trap that was set, and then when we get to the
end everything will be back to nothing again.

But:

At start:
inside : trap -- 'echo hello' SIGINT

At end : trap -- 'echo hello' SIGINT

And of course. when you think about it, it is obvious why this happens.
The first "trap" command prints nothing ... nothing has changed when we
get to the "traps=$(trap)" command ... that trap command also prints
nothing. So this does traps=''. When we do eval "${traps}" we are
doing eval "", and it is hardly surprising that this accomplishes nothing!

Now we cannot rationally change the "trap" command without args to
behave in a way that would make it useful for the posix purpose (and
here, what they're aiming for is good, it should be possible to
accomplish that objective) so is there some other way?

I think I have seen some shell (but I do not remember which one) that
actually has "trap -" that resets all traps to the default, so with that,
if we changed the 'eval "${traps}"' line to 'trap -; eval "${traps}"'
then things would actually work - kind of - that version has race conditions,
so is not really safe to use (it will work, most of the time...)

But, both ksh93 and bash have a -p arg to "trap" that allows information
about the current trap status of named signals to be reported. Unfortunately
they don't do quite the same thing, but that's not important right now,
either would be usable, and they are, but it is a lot of effort, not
nearly as simple as the posix example.

First, while "trap -p" (with no signals specified) works, it works just
the same (in both bash and ksh93, aside from output format) as "trap".
That is, that is useless. But we can to

trap_int=$(trap -p int)
trap_hup=$(trap -p hup)
...

and then reset them all, one by one, later...

(bash syntax)
test -n "${trap_int}" && eval "${trap_int}" || trap - int
test -n "${trap_hup}" && eval "${trap_hup}" || trap - hup
(ksh93 syntax)
trap "${trap_int:-}" int
trap "${trap_hup:-}" hup

the test (for bash) and variable with default for ksh93, is needed
because they both still print nothing if the signal action is the default.

So, this modification attempts to fix all of that...

1) we add trap -p, but make it always output something for every signal
listed (all of the signals if none are given) even if the signal
action is the default.

2) choose the bash output format for trap -p, over the ksh93 format,
even though the simpler usage just above makes the ksh93 form seem
better. But it isn't. Consider:

ksh93$ trap -p int hup
echo hello

One of the two traps has "echo hello" as its action, the other is
still at the default, but which?

From bash...
bash$ trap -p int hup
trap -- 'echo hello' SIGINT

And now we know! Given the bash 'trap -p' format, the following function
produces ksh93 format output (for use with named signals only) instead...

ksh93_trap_p() {
for _ARG_ do
_TRAP_=$(trap -p "${_ARG_}") || return 1
eval set -- "${_TRAP_}"
printf '%s' "$3${3:+
}"
done
return 0
}

[ It needs to be entered without the indentation, that '}"' line has to be
at the margin. If the shell running that has local vars (bash does) then
_ARG_ and _TRAP_ should be made local. ]

So the bash format was chosen (except we do not include the "SIG" on the
signal names. That's irrelevant.)

If no traps are set, "trap -p" will say (on NetBSD of course)...

trap -- - EXIT HUP INT QUIT ILL TRAP ABRT EMT FPE KILL BUS SEGV SYS
trap -- - PIPE ALRM TERM URG STOP TSTP CONT CHLD TTIN TTOU IO XCPU XFSZ
trap -- - VTALRM PROF WINCH INFO USR1 USR2 PWR RT0 RT1 RT2 RT3 RT4 RT5
trap -- - RT6 RT7 RT8 RT9 RT10 RT11 RT12 RT13 RT14 RT15 RT16 RT17 RT18
trap -- - RT19 RT20 RT21 RT22 RT23 RT24 RT25 RT26 RT27 RT28 RT29 RT30

Obviously if traps are set, the relevant signal names will be removed from
that list, and additional lines added for the trapped signals.

With args, the signals names are listed, one line each, whatever
the status of the trap for that signal is:

$ trap -p HUP INT QUIT
trap -- - HUP
trap -- 'echo interrupted' INT
trap -- - QUIT

3) we add "trap -" to reset all traps to default. (It is easy, and seems
useful.)

4) While here, lots of generic cleanup. In particular, get rid of the
NSIG+1 nonsense, and anything that ever believes a signo == NSIG
is in any way rational. Before there was a bunch of confusion,
as we need all the signals for traps, plus one more for the EXIT
trap, which looks like we then need NSIG+1. But EXIT is 0, NSIG
includes signals from 0..NSIG-1 but there is no signal 0, EXIT
uses that slot, so we do not need to add and extra one, NSIG is
enough. (To see the effect of this, use a /bin/sh from before
this fix, and compare the output from

trap '' 64
and trap '' 65

both invalid signal numbers.

Then try just "trap" and watch your shell drop core...)

Eventually NSIG needs to go away completely (from user apps), it
is not POSIX, it isn't really useful (unless we make lots of
assumptions about how signals are numbered, which are not guaranteed,
so even if apps, like this sh, work on NetBSD, they're not portable,)
and it isn't necessary (or will not be, soon.)

But that is for another day...

5) As is kind of obvious above, when listing "all" traps, list all the
ones still at their defaults, and all the ignored signals, on as
few lines as possible (it could all be on one line - technically it
would work as well, but it would have made this cvs log message
really ugly...) Signals with a non-null action still get listed
one to a line (even if several do have the exact same action.)

6) Man page updates as well.

After this change, the following script:

printf 'At start: '; trap
printf '\n'

trap -p >/tmp/out.$$
trap 'echo hello' INT
printf 'inside : '; trap
printf '\n'
. /tmp/out.$$; rm /tmp/out.$$

printf 'At end : '; trap
printf '\n'

which is just the example from above,
using "trap -p" instead of just "trap" to save the traps,
and modified to a form that will work with the NetBSD shell today
produces:

At start:
inside : trap -- 'echo hello' INT

At end :

[Do I get a prize for longest commit log message of the year?]

Implement the ';&' (used instead of ';;') case statement list terminator
which causes fall through the to command list of the following pattern
(wuthout evaluating that pattern). This has been approved for inclusion
in the next major version of the POSIX standard (Issue 8), and is
implemented by most other shells.

Now all form a circle and together attempt to summon the great wizd
in the hopes that his magic spells can transform the poor attempt
at documenting this feature into something rational...

Undocument (comment out) the description of the unimplemented MAILCHECK
variable, and while here, enhance the description of MAIL a little.

Uppercase UID. Fix typo.

Correct description of the trap command (make it posix compatible)
and add a couple more examples. Also terminate a few sentences...

branches: 1.131.2;
Fix mandoc -Tlint warnings:
s/PP/Pp
Remove Pp before It

Instead of removing markup as I did in the last commit, use markup but properly.
Hint taken from FreeBSD man page.

ok wiz@

Use \- instead of .Fl for the -number argument.

.Fl causes the -number argument to be rendered in bold, which causes confusion
with the [+]number argument right above it.

ok wiz@

PR bin/14578

Add a reference to editline(7) so we document the "-o vi" and "-o emacs"
bindings (defaults, and what can be set.)

At the suggestion of Matthew Sporleder (on current-users@) reword some
of the description of arithmetic expressions to make it a bit more
human friendly.

While here fix a few other minor errors, and bump date.

Finish support for all required $(( )) (shell arithmetic) operators,
closing PR bin/50958

That meant adding the assignment operators ('=', and all of the +=, *= ...)
Currently, ++, --, and ',' are not implemented (none of those are required
by posix) but support for them (most likely ',' first) might be added later.

To do this, I removed the yacc/lex arithmetic parser completely, and
replaced it with a hand written recursive descent parser, that I obtained
from FreeBSD, who earlier had obtained it from dash (Herbert Xu).

While doing the import, I cleaned up the sources (changed some file names
to avoid requiring a clean build, or signifigant surgery to the obj
directories if "build.sh -u" was to be used - "build.sh -u" should work
fine as it is now) removed some dashisms, applied some KNF, ...

Remove trailing space.

Add fdflags builtin. Discussed with Chet and he has implemented it for
bash too.

branches: 1.123.2; 1.123.4;

Document that a N>&N (or N<&N) redirection turns off close-on-exec for N
(where N is a decimal fd number) either when used as
some-command N>&N
(where fd N is passed, open, to some-command - which is obviously what is
wanted)

Or as
exec N>&N
which effects fd N for all future commands.

Note that this means
exec N>foo N>&N
returns to the old behaviour of leaving the file descriptor open
when commands are run (as do most shells, other than ksh) and works for
both new and old NetBSD shells (old ones never set close-on-exec, and treat
N>&N as a rather meaingless no-op request, and just ignore it), new ones
set close-on-exec on the first redirection, then disable it again on the
second.

Everything here about >& for output fds applies to <& for input ones.

OK christos@

PR bin/48489 -- Shell "simple commands" are now not allowed to be
completely empty, they must have something (var assignment, redirect,
or command, or multiple of those) to avoid a syntax error. This
matches the requirements of the grammar in the standard. Correct the
parser (using FreeBSD's sh as a guide) and update the man page to
remove text that noted a couple of places this was previously OK.

OK christos@

Remove some double quotes.

Parity is kept.

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

file system police.

Make sh.1 catch up with reality. Document -h (such as it is...)
and also added doc for some other stuff that was missing.

Take the opportunity to clean up the way the flags are set in the
man page, so every new flag doesn't have to be added 6 times!
(Some of the lists were different from others, in ordering, and
content, for no good reason at all.)

Make a few other cleanups ... Add text about AND-OR lists,
This can be also used to justify closing an open PR:
(that "sh -c 'command &&'" is not a syntax error...).

Add doc for -F, which should default to set if the shell somehow
gets compiled without DO_SHAREDVFORK defined, (to be committed
separately)

XXX: Consider disabling DO_SHAREDVFORK if SMALL is defined?

From kre

Whitespace.

Document close-on-exec redirection behavior.

Drop privileges when executed set{u,g}id unless -p is specified like other
shells do to avoid system() and popen() abuse.

PR/48843: Jarmo Jaakkola: Soften the language in the manual page,
making less promises about behavior not explicitly stated in the standard.

PR/48843: Jarmo Jaakkola: dot commands mess up scope nesting tracking

Evaluation of commands goes completely haywire if a file containing
a break/continue/return command outside its "intended" scope is sourced
using a dot command inside its "intended" scope. The main symptom is
not exiting from the sourced file when supposed to, leading to evaluation
of commands that were not supposed to be evaluated. A secondary symptom
is that these extra commands are not evaluated correctly, as some of them
are skipped. Some examples are listed in the How-To-Repeat section.

According to the POSIX standard, this is how it should work:
dot:
The shell shall execute commands from the file in the current
environment.
break:
The break utility shall exit from the smallest enclosing for, while,
or until loop, [...]
continue:
The continue utility shall return to the top of the smallest
enclosing for, while, or until loop, [...]
return:
The return utility shall cause the shell to stop executing
the current function or dot script. If the shell is not currently
executing a function or dot script, the results are unspecified.

It is clear that return should return from a sourced file, which
it does not do. Whether break and continue should work from the sourced
file might be debatable. Because the dot command says "in the current
environment", I'd say yes. In any case, it should not fail in weird
ways like it does now!

The problems occur with return (a) and break/continue (b) because:
1) dotcmd() does not record the function nesting level prior to
sourcing the file nor does it touch the loopnest variable,
leading to either
2 a) returncmd() being unable to detect that it should not set
evalskip to SKIPFUNC but SKIPFILE, or
b) breakcmd() setting evalskip to SKIPCONT or SKIPBREAK,
leading to
3) cmdloop() not detecting that it should skip the rest of
the file, due to only checking for SKIPFILE.
The result is that cmdloop() keeps executing lines from the file
whilst evalskip is set, which is the main symptom. Because
evalskip is checked in multiple places in eval.c, the secondary
symptom appears.
>How-To-Repeat:
Run the following script:

printf "break\necho break1; echo break2" >break
printf "continue\necho continue1; echo continue2" >continue
printf "return\necho return1; echo return2" >return

while true; do . ./break; done

for i in 1 2; do . ./continue; done

func() {
. ./return
}
func

No output should be produced, but instead this is the result:
break1
continue1
continue1
return1

The main symptom is evident from the unexpected output and the secondary
one from the fact that there are no lines with '2' in them.
>Fix:
Here is patch to src/bin/sh to fix the above problems. It keeps
track of the function nesting level at the beginning of a dot command
to enable the return command to work properly.

I also changed the undefined-by-standard functionality of the return
command when it's not in a dot command or function from (indirectly)
exiting the shell to being silently ignored. This was done because
the previous way has at least one bug: the shell exits without asking
for confirmation when there are stopped jobs.

Because I read the standard to mean that break and continue should have
an effect outside the sourced file, that's how I implemented it. For what
it's worth, this also seems to be what bash does. Also laziness, because
this way required no changes to loopnesting tracking. If this is not
wanted, it might make sense to move the nesting tracking to the inputfile
stack.

The patch also does some clean-up to reduce the amount of global
variables by moving the dotcmd() and the find_dot_file() functions from
main.c to eval.c and making in_function() a proper function.

branches: 1.112.2;
Add wctype(3) support to Shell Patterns.
Obtained from FreeBSD.

document LINENO
XXX: someone should fix all the .Ev stuff because some of them are just
shell variables .Va and are not really exported to the environment. See
the FreeBSD man page.

Document that a here-document can finish at an EOF as well as at the
delimiter.

- Correct macro usage;
- improve wording, including creating more consistency therein.

From Bug Hunting.

branches: 1.108.2;
- improve punctuation;
- improve (create more consistency in) spelling;
- remove unnecessary (and in part ignored) macros, as well as an
unnecessary argument to `.Bl' (fixes mandoc(1) warnings);
- improve wording;
- bump date.

Patch from Bug Hunting.

Allow thread limit queries by adding the new -r flag to ulimit. Add
the corresponding documentation in the man page.

branches: 1.106.2;
Merge duplicate information.

.Dq Dv \&:

Mention what happens when we don't include :. It would be nice to use
.Dv :
but it produces ``'':

A feature that wasn't implemented for 4.4alpha and still isn't implemented
is just plain not implemented.

Sort sections. Remove trailing whitespace.

Typos.

document OLDPWD and cd -

branches: 1.99.4;
Note that set -o tabcomplete requires either set -o emacs or set -o vi
to work.

\\ -> \e

Bump date for cd -P support.

fix another typo

Make the cd builtin accept and ignore -P, which is a kshism that has been
allowed to leak into POSIX and selects the behavior cd already implements.
Closes PR bin/42557 and also relevant to PR pkg/42168.

I suppose this should probably be pulled up to both -4 and -5...

fix typo

Bump date for previous.

- add new RLIMIT_AS (aka RLIMIT_VMEM) resource that limits the total
address space available to processes. this limit exists in most other
modern unix variants, and like most of them, our defaults are unlimited.
remove the old mmap / rlimit.datasize hack.

- adds the VMCMD_STACK flag to all the stack-creation vmcmd callers.
it is currently unused, but was added a few years ago.

- add a pair of new process size values to kinfo_proc2{}. one is the
total size of the process memory map, and the other is the total size
adjusted for unused stack space (since most processes have a lot of
this...)

- patch sh, and csh to notice RLIMIT_AS. (in some cases, the alias
RLIMIT_VMEM was already present and used if availble.)

- patch ps, top and systat to notice the new k_vm_vsize member of
kinfo_proc2{}.

- update irix, svr4, svr4_32, linux and osf1 emulations to support
this information. (freebsd could be done, but that it's best left
as part of the full-update of compat/freebsd.)


this addresses PR 7897. it also gives correct memory usage values,
which have never been entirely correct (since mmap), and have been
very incorrect since jemalloc() was enabled.

tested on i386 and sparc64, build tested on several other platforms.

thanks to many folks for feedback and testing but most espcially
chuq and yamt for critical suggestions that lead to this patch not
having a special ugliness i wasn't happy with anyway :-)

Explicitly escape -- as it is not an argment to the Cm macro.

Don't use .Xo/.Xc to workaround ancient macro argument limit.

Fix preamble to match order set out by mdoc(7). Discussed with wiz.

branches: 1.88.2;
document "EXIT" pseudo signal.

branches: 1.87.18;
PR/36533: Greg A. Woods: minor doc fixes for sh(1)

Document that shell arithmetic now uses intmax_t. Document that
variables in shell arithmetic don't need "$" signs.

branches: 1.85.2;
Fix typo, update date.
Fixes PR/34472

In mdoc, use .Pp for new paragraphs, not .br.

Don't apply CDPATH if the the first component of the target is "." or "..".
Fixes PR/30973 and applies the principle of least surprise.
Update documentation to match (including date).
(matches behaviour of pdksh - if not it's documentation)

Aspell, fix an Xref, drop trailing whitespace.

Allow trap to work on ignored signals when the shell is interactive.

Whitespace and punctuation fixes.

If 'set -o tabcomplete' it set, then bind <tab> to the libedit filename
completion function.
Note that the libedit code will probably want fine-tuning!
While editing the man page, add a note that non-whitespace IFS chars are
terminators and can generate null arguments.

Fix typo: and the -> and then

Fix typo noted by Patrick Welche.

Bump date for previous.

understand rlimit sbsize

Fix example added in previous.

add a note to Short-Circuit operators section about the somewhat
nonintuitive evaluation in case there is both || and && specified
pointed out in bin/23814 by VaX#n8

correct 2 typos

Posix requires that 'pwd -P' reset the shells saved cwd value - so a
subsequent 'pwd -L' will report the same value.
Update man page to be a closer match to reality.

passwd(5), not passwd(4). From Igor Sobrado in PR 23278.

Do not xref alias(1) since that points to csh(1).
Noted by Igor Sobrado in PR 23278, fixed following a suggestion by Greg A. Woods.

Move UCB-licensed code from 4-clause to 3-clause licence.

Patches provided by Joel Baker in PR 22249, verified by myself.

Quote some punctuation.

Drop trailing space.

Add new builtin 'inputrc' which allows keybindings to be redefined
for the current shell. From Arne H Juul in PR#10097.

Expand documentation of emacs and vi modes. From
Jeremy C. Reed in PR#14578.

add missing parenthesis

Change "if" to "if and only if" per discussion in PR 20794.

.Nm does not need a dummy argument ("") before punctuation or
for correct formatting of the SYNOPSIS any longer.

New sentence, new line; bump date for last change.

Introduce LANG environment variable and Xref to nls(7).
Comment out the statement: "We expect POSIX conformance
by the time 4.4BSD is released."

Fix indentation of continuation of first line in SYNOPSIS.

More markup, more commas, less typos.

Support command -p, -v and -V as posix
Stop temporary PATH assigments messing up hash table
Fix sh -c -e "echo $0 $*" -a x (as posix)
(agreed by christos)

trap '' SIGINT -> trap '' INT.

Another it's -> its.

`` [n1]>&n2 Duplicate standard output (or n1) _TO_ n2.''

filesystem -> file system, automaticly -> automatically.

Use more mdoc, particularly to get rid of some \*[Lt] and \*[Gt].

New policy: New sentences start on a new line.
Patches by Robert Elz <kre at munnari oz au>, with minimal changes by me.

Implement sh -a (allexport). Code (all two lines of it) from FreeBSD
(FreeBSD var.c 1.13, sh.1 1.27).

implement noclobber. From Ben Harris, with minor tweaks from me. Two
unimplemented comments to go. Go Ben!

Implement unset variable error messages from Ben Harris.

first variable argument to "read" is not optional

Generate <>& symbolically. I'm avoiding .../dist/... directories for now.

Punctuation nits, drop unnecessary .Pps, sort sections.

Don't xref set(1) and case(1), since they are builtins and we don't
have separate man pages for them.
Xref passwd 5 instead of 4, environ 7 instead of 5, and comment out xref
to profile(4), which we don't have.
Improve markup of SYNOPSIS.
Some whitespace fixes while I'm here.

Correct {list;} example and fix formatting/typo in the operator lists.

Extended functionality of the trap builtin, which now closely follows
POSIX recommendations.

- trap now accepts signal names and signal numbers
e.g. INT, SIGINT, 2
- added option -l that outputs a list of valid signals
- added signal EXIT to list of valid signals
- a `-' in the action part will reset specified signal to their
default behaviour
- changed standard output format to make it suitable as an input
to another shell that achieves the same trapping results

fix typo.

Add an example on how to use getopts, stolen from the getopt manual page :-)

.Bl takes parameter "-offset indent", not "-indent".

For commands and utilities, use EXIT STATUS rather than RETURN VALUES as
appropriate (and documented in mdoc(7)).

Add 'RETURN VALUE' section header.

Various mandoc updates to the Builtins
section; mostly .Ic, a few other nits.

Note the meaning of 'trap 0' (execute on exit from shell)

branches: 1.33.4;
Add under which conditions the "read" builtin returns success/failure.

Suggested in PR 8813 by Eric Mumpower <nocturne@arepa.com>

xref sysctl(8) (for proc.<pid>.rlimits)

Mention -c option to sh(1), noticed by Matthew Aldous in PR/8499.

branches: 1.30.2;
add -q in the synopsis line

Make the `...' actually appear in the case/esac syntax section.
Fix a space botch in the $@ example.
Kill warnings caused by the effective but wrong use of \[ and \] to
perform the function of \&[ and \&].

Add -q option, which when used with -v and/or -x, turns off the tracing
during the execution of /etc/profile, .profile and $ENV.

Add support for the export and readonly -p option.

Massive fixup:
Rewrite man page in mandoc format rather than nasty man format.
Fix a ton of parsing errors, and generate proper .Xr's.
document all known environment variables.
suggest ksh rather than bash.

The last two fix PR #1966. Wheee!

Somebody with access to the POSIX spec needs to go in here, and document
our adherence, or lack thereof.

fix some bugs

Modify to better document getopts. This fixes PR# 704. Much thanks to
Christos for helping me out with this.

Small edit to n1>&n2 description.

Per 1003.2, the (builtin) read utility shall treat the backslash as an
escape character (including line continuation), unless the `-r' option
is specified:
* adopt to this behaviour, add the `-r' option to disable it;
* remove the `-e' option, which was previously necessary to get this behaviour.

branches: 1.21.2;
Add a missing ) in the description of the builtin "set".

Add documentation for ulimit command, courtsey of
Eric Fischer <eric@fudge.uchicago.edu>.

alternate -> alternative, per PR 2643

add type builtin.

PR/2808: Add HISTORY section and documentation of getopts. (from FreeBSD)

Apply PR#2721 from VaX#n8: make man page more lucid in places.

branches: 1.15.6;
Merge in my changes from vangogh, and fix the x=`false`; echo $? == 0
bug.

convert to new RCS id conventions.

I added the documented in the manual but not implemented variable expansions:

${#WORD}
${WORD%PAT}
${WORD%%PAT}
${WORD#PAT}
${WORD##PAT}

Describe the : shell builtin.
Fixes PR #712.

Add RCS ids.

sync with 4.4lite

Comment out sections of the manpages that are not, and will probably never
be, appropriate for ash as configured for NetBSD. In particular the /u
"magic" directory, and atty(1) support.

spelling mistakes

Remove text describing how the dot command does not do a $PATH search,
since we added that behavior to get closer to POSIX.2.

Add RCS identifiers.

Fix typo.

Fix various bugs in man pages (from 386BSD patch 130).

changed "Id" to "Header" for rcsids

added rcs ids to all files

branches: 1.1.1;
Initial revision