[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[PATCH 6/9] Slightly revise documentation of POSIX mode.
|
From: |
G. Branden Robinson |
|
Subject: |
[PATCH 6/9] Slightly revise documentation of POSIX mode. |
|
Date: |
Mon, 16 Dec 2024 11:48:25 -0600 |
* doc/bash.1: Introduce "POSIX mode" earlier in the document. Set the
word "POSIX" in small caps (as traditionally done for acronyms) to
parallel the typesetting of the "bashref" Texinfo manual. Also set
the phrase "POSIX mode" in italics, but only on the introduction of
the term. Do not capitalize the 'm' in "POSIX mode". Refer reader to
the section of the "bashref" Texinfo manual that documents the ~60
behavior changes governed by POSIX mode.
* doc/bashref.texi:
* lib/readline/doc/rluser.texi: Parallelize line breaks with bash.1 for
easier diffing and maintenance.
---
doc/bash.1 | 239 +++++++++++++++++------
doc/bashref.texi | 355 ++++++++++++++++++++++++++---------
lib/readline/doc/rluser.texi | 4 +-
3 files changed, 449 insertions(+), 149 deletions(-)
diff --git a/doc/bash.1 b/doc/bash.1
index 2f0edf7d..e7a3ae9e 100644
--- a/doc/bash.1
+++ b/doc/bash.1
@@ -80,13 +80,29 @@ .SH DESCRIPTION
also incorporates useful features from the \fIKorn\fP and \fIC\fP
shells (\fBksh\fP and \fBcsh\fP).
.PP
-POSIX is the name for a family of computing standards based on Unix.
+.SM POSIX
+is the name for a family of computing standards based on Unix.
.B Bash
is intended to be a conformant implementation of the
-Shell and Utilities portion of the IEEE POSIX specification
+Shell and Utilities portion of the IEEE
+.SM POSIX
+specification
(IEEE Standard 1003.1).
+In
+.I
+.SM POSIX
+.IR mode ,
.B Bash
-can be configured to be POSIX-conformant by default.
+conforms more strictly to the standard,
+even where this makes the shell's behavior less useful;
+see
+.Q "Bash POSIX Mode"
+in the
+.IR "Bash Reference Manual" .
+.B Bash
+can be configured to be
+.SM POSIX\c
+-conformant by default.
.SH OPTIONS
All of the single-character shell options documented in the
description of the \fBset\fP builtin command, including \fB\-o\fP,
@@ -247,13 +263,14 @@ .SH OPTIONS
.BR sh .
.TP
.B \-\-posix
-Change the behavior of \fBbash\fP where the default operation differs
-from the POSIX standard to match the standard (\fIposix mode\fP).
-See
-.SM
-.B "SEE ALSO"
-below for a reference to a document that details how posix mode affects
-\fBBash\fP's behavior.
+Enable
+.SM POSIX
+mode;
+change the behavior of
+.B bash
+where the default operation differs from the
+.SM POSIX
+standard to match it.
.TP
.B \-\-restricted
The shell becomes restricted (see
@@ -400,7 +417,9 @@ .SH INVOCATION
it tries to mimic the startup behavior of historical versions of
.B sh
as closely as possible,
-while conforming to the POSIX standard as well.
+while conforming to the
+.SM POSIX
+standard as well.
When invoked as an interactive login shell, or a non-interactive
shell with the \fB\-\-login\fP option, it first attempts to
read and execute commands from
@@ -431,13 +450,20 @@ .SH INVOCATION
When invoked as
.BR sh ,
.B bash
-enters posix mode after reading the startup files.
+enters
+.SM POSIX
+mode after reading the startup files.
.PP
When
.B bash
-is started in posix mode, as with the
+is started in
+.SM POSIX
+mode,
+as with the
.B \-\-posix
-command line option, it follows the POSIX standard for startup files.
+command line option, it follows the
+.SM POSIX
+standard for startup files.
In this mode, interactive shells expand the
.SM
.B ENV
@@ -608,8 +634,13 @@ .SS Pipelines
reserved word precedes a pipeline, the shell reports the
elapsed as well as user and system time consumed by its execution
when the pipeline terminates.
-The \fB\-p\fP option changes the output format to that specified by POSIX.
-When the shell is in posix mode, it does not recognize
+The \fB\-p\fP option changes the output format to that specified by
+.SM POSIX\c
+\&.
+When the shell is in
+.SM POSIX
+mode,
+it does not recognize
\fBtime\fP as a reserved word if the next token begins with a
.Q \- .
The value of the
@@ -622,7 +653,10 @@ .SS Pipelines
below under
.BR "Shell Variables" .
.PP
-When the shell is in posix mode, \fBtime\fP
+When the shell is in
+.SM POSIX
+mode,
+\fBtime\fP
may appear by itself as the only word in a simple command.
In this case, the shell displays the
total user and system time consumed by the shell and its children.
@@ -786,9 +820,12 @@ .SS Compound Commands
.IP
An additional binary operator, \fB=\*~\fP, is available, with the same
precedence as \fB==\fP and \fB!=\fP.
-When it is used, the string to the right of the operator is considered
-a POSIX extended regular expression and matched accordingly
-(using the POSIX \fIregcomp\fP and \fIregexec\fP interfaces
+When it is used, the string to the right of the operator is considered a
+.SM POSIX
+extended regular expression and matched accordingly
+(using the
+.SM POSIX
+\fIregcomp\fP and \fIregexec\fP interfaces
usually described in
.IR regex (3)).
The return value is 0 if the string matches
@@ -1105,8 +1142,13 @@ .SS Shell Function Definitions
parentheses are not supplied, the braces are recommended.
\fIcompound\-command\fP is executed whenever \fIfname\fP is specified as the
name of a simple command.
-When in posix mode, \fIfname\fP must be a valid shell \fIname\fP
-and may not be the name of one of the POSIX \fIspecial builtins\fP.
+When in
+.SM POSIX
+mode,
+\fIfname\fP must be a valid shell \fIname\fP
+and may not be the name of one of the
+.SM POSIX
+\fIspecial builtins\fP.
In default mode, a function name can be any unquoted shell word that does
not contain \fB$\fP.
.PP
@@ -1192,7 +1234,9 @@ .SH QUOTING
.BR \e ,
and, when history expansion is enabled,
.BR ! .
-When the shell is in posix mode,
+When the shell is in
+.SM POSIX
+mode,
the \fB!\fP has no special meaning
within double quotes, even when history expansion is enabled.
The characters
@@ -1388,7 +1432,10 @@ .SH PARAMETERS
and
.B local
builtin commands (\fIdeclaration\fP commands).
-When in posix mode, these builtins may appear in a command after
+When in
+.SM POSIX
+mode,
+these builtins may appear in a command after
one or more instances of the \fBcommand\fP builtin and retain these
assignment statement properties.
.PP
@@ -2364,7 +2411,9 @@ .SS "Shell Variables"
.TP
.B CHILD_MAX
Set the number of exited child status values for the shell to remember.
-\fBBash\fP will not allow this value to be decreased below a POSIX-mandated
+\fBBash\fP will not allow this value to be decreased below a
+.SM POSIX\c
+-mandated
minimum, and there is a maximum value (currently 8192) that this may
not exceed.
The minimum value is system-dependent.
@@ -2398,7 +2447,9 @@ .SS "Shell Variables"
(see
.SM
.B INVOCATION
-above) when an interactive shell is invoked in posix mode.
+above) when an interactive shell is invoked in
+.SM POSIX
+mode.
.TP
.B EXECIGNORE
A colon-separated list of shell patterns (see \fBPattern Matching\fP)
@@ -2833,13 +2884,22 @@ .SS "Shell Variables"
.TP
.B POSIXLY_CORRECT
If this variable is in the environment when \fBbash\fP starts, the shell
-enters posix mode before reading the startup files, as if the
+enters
+.SM POSIX
+mode
+before reading the startup files, as if the
.B \-\-posix
invocation option had been supplied. If it is set while the shell is
-running, \fBbash\fP enables posix mode, as if the command
+running, \fBbash\fP enables
+.SM POSIX
+mode,
+as if the command
.Q "set \-o posix"
had been executed.
-When the shell enters posix mode, it sets this variable if it was
+When the shell enters
+.SM POSIX
+mode,
+it sets this variable if it was
not already set.
.TP
.B PROMPT_COMMAND
@@ -3468,7 +3528,9 @@ .SS Tilde Expansion
.BR PARAMETERS )
when they appear as arguments to simple commands.
\fBBash\fP does not do this, except for the \fIdeclaration\fP commands listed
-above, when in posix mode.
+above, when in
+.SM POSIX
+mode.
.SS Parameter Expansion
The
.Q \fB$\fP
@@ -4398,7 +4460,9 @@ .SS "Pathname Expansion"
Within a bracket expression,
\fIcharacter classes\fP can be specified using the syntax
\fB[:\fP\fIclass\fP\fB:]\fP, where \fIclass\fP is one of the
-following classes defined in the POSIX standard:
+following classes defined in the
+.SM POSIX
+standard:
.IP
.RS
.B
@@ -5303,10 +5367,14 @@ .SH "CONDITIONAL EXPRESSIONS"
links and operate on the target of the link, rather than the link itself.
.PP
When used with \fB[[\fP,
-or when the shell is in posix mode,
+or when the shell is in
+.SM POSIX
+mode,
the \fB<\fP and \fB>\fP operators sort
lexicographically using the current locale.
-When the shell is not in posix mode,
+When the shell is not in
+.SM POSIX
+mode,
the \fBtest\fP command sorts using ASCII ordering.
.PP
.PD 0
@@ -5421,7 +5489,9 @@ .SH "CONDITIONAL EXPRESSIONS"
.TP
\fIstring1\fP \fB=\fP \fIstring2\fP
True if the strings are equal.
-\fB=\fP should be used with the \fBtest\fP command for POSIX conformance.
+\fB=\fP should be used with the \fBtest\fP command for
+.SM POSIX
+conformance.
When used with the \fB[[\fP command, this performs pattern matching as
described above (\fBCompound Commands\fP).
.TP
@@ -5667,14 +5737,20 @@ .SH "COMMAND EXECUTION ENVIRONMENT"
Changes made to the subshell environment
cannot affect the shell's execution environment.
.PP
-When the shell is in posix mode,
+When the shell is in
+.SM POSIX
+mode,
subshells spawned to execute command substitutions inherit the value of
the \fB\-e\fP option from their parent shell.
-When not in posix mode,
+When not in
+.SM POSIX
+mode,
\fBbash\fP clears the \fB\-e\fP option in such subshells.
See the
description of the \fBinherit_errexit\fP shell option below
-for how to control this behavior when not in posix mode.
+for how to control this behavior when not in
+.SM POSIX
+mode.
.PP
If a command is followed by a \fB&\fP and job control is not active, the
default standard input for the command is the empty file
@@ -8847,7 +8923,10 @@ .SH "SHELL BUILTIN COMMANDS"
to find the directory containing
.IR filename .
\fIfilename\fP does not need to be executable.
-When \fBbash\fP is not in posix mode, it searches
+When \fBbash\fP is not in
+.SM POSIX
+mode,
+it searches
the current directory if \fIfilename\fP is not found in
.SM
.BR PATH ,
@@ -9930,7 +10009,8 @@ .SH "SHELL BUILTIN COMMANDS"
If \fB\-n\fP is supplied, print only disabled builtins.
If \fB\-a\fP is supplied, the list printed includes all builtins, with an
indication of whether or not each is enabled.
-The \fB\-s\fP option means to restrict the output to the POSIX
+The \fB\-s\fP option means to restrict the output to the
+.SM POSIX
\fIspecial\fP builtins.
.IP
The
@@ -9950,7 +10030,8 @@ .SH "SHELL BUILTIN COMMANDS"
The
.B \-d
option will delete a builtin previously loaded with \fB\-f\fP.
-If \fI\-s\fP is used with \fI\-f\fP, the new builtin becomes a POSIX
+If \fI\-s\fP is used with \fI\-f\fP, the new builtin becomes a
+.SM POSIX
special builtin.
.IP
If no options are supplied and a \fIname\fP is not a shell builtin,
@@ -11187,7 +11268,10 @@ .SH "SHELL BUILTIN COMMANDS"
in a format that can be reused as input
for setting or resetting the currently-set variables.
Read-only variables cannot be reset.
-In posix mode, only shell variables are listed.
+In
+.SM POSIX
+mode,
+only shell variables are listed.
The output is sorted according to the current locale.
When options are specified, they set or unset shell attributes.
Any arguments remaining after option processing are treated
@@ -11404,13 +11488,21 @@ .SH "SHELL BUILTIN COMMANDS"
Change the behavior of
.B bash
where the default operation differs
-from the POSIX standard to match the standard (\fIposix mode\fP).
+from the
+.SM POSIX
+standard to match the standard
+(\c
+.I
+.SM POSIX
+.IR mode ).
See
.SM
.B "SEE ALSO"
.ie \n(zZ=1 in \fIbash\fP(1)
.el below
-for a reference to a document that details how posix mode affects
+for a reference to a document that details how
+.SM POSIX
+mode affects
bash's behavior.
.TP 8
.B privileged
@@ -11992,7 +12084,10 @@ .SH "SHELL BUILTIN COMMANDS"
.B inherit_errexit
If set, command substitution inherits the value of the \fBerrexit\fP option,
instead of unsetting it in the subshell environment.
-This option is enabled when posix mode is enabled.
+This option is enabled when
+.SM POSIX
+.I mode
+is enabled.
.TP 8
.B interactive_comments
In an interactive shell, a word beginning with \fB#\fP
@@ -12283,16 +12378,23 @@ .SH "SHELL BUILTIN COMMANDS"
using the rules listed above.
.PD
.PP
-When the shell is in posix mode, or if the expression is part
+When the shell is in
+.SM POSIX
+mode,
+or if the expression is part
of the \fB[[\fP command,
the \fB<\fP and \fB>\fP operators sort using the
current locale.
-If the shell is not in posix mode, the \fBtest\fP and \fB[\fP
+If the shell is not in
+.SM POSIX
+mode,
+the \fBtest\fP and \fB[\fP
commands sort lexicographically using ASCII ordering.
.PP
The historical operator-precedence parsing with 4 or more arguments can
lead to ambiguities when it encounters strings that look like primaries.
-The POSIX
+The
+.SM POSIX
standard has deprecated the \fB\-a\fP and \fB\-o\fP
primaries and enclosing expressions within parentheses.
Scripts should no longer use them.
@@ -12609,7 +12711,9 @@ .SH "SHELL BUILTIN COMMANDS"
The pipe size in 512-byte blocks (this may not be set).
.TP
.B \-q
-The maximum number of bytes in POSIX message queues.
+The maximum number of bytes in
+.SM POSIX
+message queues.
.TP
.B \-r
The maximum real-time scheduling priority.
@@ -12665,7 +12769,9 @@ .SH "SHELL BUILTIN COMMANDS"
and
.BR \-u ,
which are unscaled values;
-and, when in posix mode,
+and, when in
+.SM POSIX
+mode,
.B \-c
and
.BR \-f ,
@@ -12927,14 +13033,25 @@ .SH "SHELL COMPATIBILITY MODE"
.PD 0
.RS
.IP \(bu
-In \fIposix\fP mode, \fBtime\fP may be followed by options and still be
-recognized as a reserved word (this is POSIX interpretation 267).
+In
+.SM POSIX
+mode,
+\fBtime\fP may be followed by options and still be
+recognized as a reserved word
+(this is
+.SM POSIX
+interpretation 267).
.IP \(bu
-In \fIposix\fP mode, the parser requires that an even number of single
+In
+.SM POSIX
+mode,
+the parser requires that an even number of single
quotes occur in the \fIword\fP portion of a double-quoted
parameter expansion and treats them specially, so that characters within
the single quotes are considered quoted
-(this is POSIX interpretation 221).
+(this is
+.SM POSIX
+interpretation 221).
.RE
.PD
.TP
@@ -12945,10 +13062,15 @@ .SH "SHELL COMPATIBILITY MODE"
The replacement string in double-quoted pattern substitution does not
undergo quote removal, as it does in versions after bash-4.2.
.IP \(bu
-In posix mode, single quotes are considered special when expanding
+In
+.SM POSIX
+mode,
+single quotes are considered special when expanding
the \fIword\fP portion of a double-quoted parameter expansion
and can be used to quote a closing brace or other special character
-(this is part of POSIX interpretation 221);
+(this is part of
+.SM POSIX
+interpretation 221);
in later versions, single quotes
are not special within double-quoted word expansions.
.RE
@@ -12959,7 +13081,9 @@ .SH "SHELL COMPATIBILITY MODE"
.RS
.IP \(bu
Word expansion errors are considered non-fatal errors that cause the
-current command to fail, even in posix mode
+current command to fail, even in
+.SM POSIX
+mode,
(the default behavior is to make them fatal errors that cause the shell
to exit).
.IP \(bu
@@ -12989,7 +13113,8 @@ .SH "SHELL COMPATIBILITY MODE"
.IP \(bu
Variable assignments preceding builtins like \fBexport\fP and \fBreadonly\fP
that set attributes continue to affect variables with the same
-name in the calling environment even if the shell is not in posix
+name in the calling environment even if the shell is not in
+.SM POSIX
mode.
.RE
.PD
diff --git a/doc/bashref.texi b/doc/bashref.texi
index ee9643aa..0998411e 100644
--- a/doc/bashref.texi
+++ b/doc/bashref.texi
@@ -123,7 +123,9 @@ @node Top
Bash is largely compatible with @code{sh} and incorporates useful
features from the Korn shell @code{ksh} and the C shell @code{csh}.
It is intended to be a conformant implementation of the @sc{ieee}
-@sc{posix} Shell and Tools portion of the @sc{ieee} @sc{posix}
+@sc{posix}
+Shell and Tools portion of the @sc{ieee}
+@sc{posix}
specification (@sc{ieee} Standard 1003.1).
It offers functional improvements over @code{sh} for both interactive and
programming use.
@@ -199,7 +201,8 @@ @node Top
@cindex POSIX
A family of open system standards based on Unix. Bash
is primarily concerned with the Shell and Utilities portion of the
-@sc{posix} 1003.1 standard.
+@sc{posix}
+1003.1 standard.
@item blank
A space or tab character.
@@ -295,7 +298,8 @@ @node Top
@item special builtin
@cindex special builtin
A shell builtin command that has been classified as special by the
-@sc{posix} standard.
+@sc{posix}
+standard.
@item token
@cindex token
@@ -316,7 +320,8 @@ @node Top
The Bourne shell is
the traditional Unix shell originally written by Stephen Bourne.
All of the Bourne shell builtin commands are available in Bash, and
-the rules for evaluation and quoting are taken from the @sc{posix}
+the rules for evaluation and quoting are taken from the
+@sc{posix}
specification for the `standard' Unix shell.
This chapter briefly summarizes the shell's `building blocks':
@@ -463,7 +468,8 @@ @node Top
@samp{$}, @samp{`}, @samp{\},
and, when history expansion is enabled, @samp{!}.
When the shell is in
-@sc{posix} mode (@pxref{Bash POSIX Mode}),
+@sc{posix}
+mode (@pxref{Bash POSIX Mode}),
the @samp{!} has no special meaning
within double quotes, even when history expansion is enabled.
The characters @samp{$} and @samp{`}
@@ -763,7 +769,9 @@ @node Top
The return status (@pxref{Exit Status}) of a simple command is
its exit status as provided
-by the @sc{posix} 1003.1 @code{waitpid} function, or 128+@var{n} if
+by the
+@sc{posix}
+1003.1 @code{waitpid} function, or 128+@var{n} if
the command was terminated by signal @var{n}.
@node Pipelines
@@ -803,8 +811,11 @@ @node Top
The statistics currently consist of elapsed (wall-clock) time and
user and system time consumed by the command's execution.
The @option{-p} option changes the output format to that specified
-by @sc{posix}.
-When the shell is in @sc{posix} mode (@pxref{Bash POSIX Mode}),
+by
+@sc{posix}.
+When the shell is in
+@sc{posix}
+mode (@pxref{Bash POSIX Mode}),
it does not recognize @code{time} as a reserved word if the next
token begins with a @samp{-}.
The value of the @env{TIMEFORMAT} variable is a format string that
@@ -814,7 +825,9 @@ @node Top
shell builtins, shell functions, and pipelines.
An external @code{time} command cannot time these easily.
-When the shell is in @sc{posix} mode (@pxref{Bash POSIX Mode}),
+When the shell is in
+@sc{posix}
+mode (@pxref{Bash POSIX Mode}),
you can use @code{time} by itself as a simple command.
In this case, the shell displays the
total user and system time consumed by the shell and its children.
@@ -1209,8 +1222,12 @@ @node Top
An additional binary operator, @samp{=~}, is available, with the same
precedence as @samp{==} and @samp{!=}.
When you use @samp{=~}, the string to the right of the operator is considered
-a @sc{posix} extended regular expression pattern and matched accordingly
-(using the @sc{posix} @code{regcomp} and @code{regexec} interfaces
+a
+@sc{posix}
+extended regular expression pattern and matched accordingly
+(using the
+@sc{posix}
+@code{regcomp} and @code{regexec} interfaces
usually described in @i{regex}(3)).
The return value is 0 if the string matches the pattern, and 1 if it does not.
If the regular expression is syntactically incorrect, the conditional
@@ -1564,11 +1581,16 @@ @node Top
may be any compound command listed above.
If the @code{function} reserved word is used, but the
parentheses are not supplied, the braces are recommended.
-When the shell is in @sc{posix} mode (@pxref{Bash POSIX Mode}),
+When the shell is in
+@sc{posix}
+mode
+(@pxref{Bash POSIX Mode}),
@var{fname} must be a valid shell name and
may not be the same as one of the special builtins
(@pxref{Special Builtins}).
-When not in @sc{posix} mode,
+When not in
+@sc{posix}
+mode,
a function name can be any unquoted shell word that does
not contain @samp{$}.
@@ -1787,7 +1809,9 @@ @node Top
@code{alias},
@code{declare}, @code{typeset}, @code{export}, @code{readonly},
and @code{local} builtin commands (@dfn{declaration commands}).
-When in @sc{posix} mode (@pxref{Bash POSIX Mode}), these builtins may appear
+When in
+@sc{posix}
+mode (@pxref{Bash POSIX Mode}), these builtins may appear
in a command after one or more instances of the @code{command} builtin
and retain these assignment statement properties.
For example,
@@ -2182,7 +2206,9 @@ @node Top
variable assignments (@pxref{Shell Parameters})
when they appear as arguments to simple commands.
Bash does not do this, except for the declaration commands listed
-above, when in @sc{posix} mode.
+above, when in
+@sc{posix}
+mode.
@node Shell Parameter Expansion
@subsection Shell Parameter Expansion
@@ -3091,7 +3117,9 @@ @node Top
Within a bracket expression, @dfn{character classes} can be specified
using the syntax
@code{[:}@var{class}@code{:]}, where @var{class} is one of the
-following classes defined in the @sc{posix} standard:
+following classes defined in the
+@sc{posix}
+standard:
@example
alnum alpha ascii blank cntrl digit graph lower
print punct space upper word xdigit
@@ -3728,14 +3756,20 @@ @node Top
Changes made to the subshell environment
cannot affect the shell's execution environment.
-When the shell is in @sc{posix} mode,
+When the shell is in
+@sc{posix}
+mode,
subshells spawned to execute command substitutions inherit the value of
the @option{-e} option from the parent shell.
-When not in @sc{posix} mode,
+When not in
+@sc{posix}
+mode,
Bash clears the @option{-e} option in such subshells
See the description of the @code{inherit_errexit} shell option
(@pxref{Bash Builtins}) for how to control this behavior when not
-in @sc{posix} mode.
+in
+@sc{posix}
+mode.
If a command is followed by a @samp{&} and job control is not active, the
default standard input for the command is the empty file @file{/dev/null}.
@@ -4051,7 +4085,9 @@ @node Top
(@pxref{Bash History Builtins}), and the programmable completion
facilities (@pxref{Programmable Completion Builtins}).
-Many of the builtins have been extended by @sc{posix} or Bash.
+Many of the builtins have been extended by
+@sc{posix}
+or Bash.
Unless otherwise noted, each builtin command documented as accepting
options preceded by @samp{-} accepts @samp{--}
@@ -4070,7 +4106,9 @@ @node Top
@section Bourne Shell Builtins
The following shell builtin commands are inherited from the Bourne Shell.
-These commands are implemented as specified by the @sc{posix} standard.
+These commands are implemented as specified by the
+@sc{posix}
+standard.
@table @code
@item : @r{(a colon)}
@@ -4096,7 +4134,9 @@ @node Top
as a colon-separated list of directories in which to find @var{filename};
otherwise, @code{.} uses the directories in @env{PATH} to find @var{filename}.
@var{filename} does not need to be executable.
-When Bash is not in @sc{posix} mode, it searches the current directory
+When Bash is not in
+@sc{posix}
+mode, it searches the current directory
if @var{filename} is not found in @env{$PATH},
but does not search the current directory if @option{-p} is supplied.
If the @code{sourcepath} option (@pxref{The Shopt Builtin}) is turned off,
@@ -4594,15 +4634,21 @@ @node Top
using the rules listed above.
@end table
-If the shell is in @sc{posix} mode, or if the expression is part
+If the shell is in
+@sc{posix}
+mode, or if the expression is part
of the @code{[[} command,
the @samp{<} and @samp{>} operators sort using the current locale.
-If the shell is not in @sc{posix} mode, the @code{test} and @samp{[}
+If the shell is not in
+@sc{posix}
+mode, the @code{test} and @samp{[}
commands sort lexicographically using ASCII ordering.
The historical operator-precedence parsing with 4 or more arguments can
lead to ambiguities when it encounters strings that look like primaries.
-The @sc{posix} standard has deprecated the @option{-a} and @option{-o}
+The
+@sc{posix}
+standard has deprecated the @option{-a} and @option{-o}
primaries and enclosing expressions within parentheses.
Scripts should no longer use them.
It's much more reliable to restrict test invocations to a single primary,
@@ -4775,7 +4821,9 @@ @node Top
This section describes builtin commands which are unique to
or have been extended in Bash.
-Some of these commands are specified in the @sc{posix} standard.
+Some of these commands are specified in the
+@sc{posix}
+standard.
@table @code
@@ -5190,7 +5238,9 @@ @node Top
The @option{-a} option means to list
each builtin with an indication of whether or not it is enabled.
The @option{-s} option means to
-restrict @code{enable} to the @sc{posix} special builtins.
+restrict @code{enable} to the
+@sc{posix}
+special builtins.
The @option{-f} option means to load the new builtin command @var{name}
from shared object @var{filename}, on systems that support dynamic loading.
@@ -5676,7 +5726,9 @@ @node Top
The pipe buffer size.
@item -q
-The maximum number of bytes in @sc{posix} message queues.
+The maximum number of bytes in
+@sc{posix}
+message queues.
@item -r
The maximum real-time scheduling priority.
@@ -5732,7 +5784,9 @@ @node Top
@option{-b},
@option{-k},
@option{-n} and @option{-u}, which are unscaled values;
-and, when in @sc{posix} Mode (@pxref{Bash POSIX Mode}),
+and, when in
+@sc{posix}
+mode (@pxref{Bash POSIX Mode}),
@option{-c} and @option{-f}, which are in 512-byte increments.
The return status is zero unless an invalid option or argument is supplied,
@@ -5781,7 +5835,9 @@ @node Top
current locale, in a format that may be reused as input
for setting or resetting the currently-set variables.
Read-only variables cannot be reset.
-In @sc{posix} mode, only shell variables are listed.
+In
+@sc{posix}
+mode, only shell variables are listed.
When options are supplied, they set or unset shell attributes.
Any arguments remaining after option processing replace the
@@ -5941,7 +5997,9 @@ @node Top
@item posix
Change the behavior of Bash where the default operation differs
-from the @sc{posix} standard to match the standard
+from the
+@sc{posix}
+standard to match the standard
(@pxref{Bash POSIX Mode}).
This is intended to make Bash behave as a strict superset of that
standard.
@@ -6367,7 +6425,9 @@ @node Top
@item inherit_errexit
If set, command substitution inherits the value of the @code{errexit} option,
instead of unsetting it in the subshell environment.
-This option is enabled when @sc{posix} mode is enabled.
+This option is enabled when
+@sc{posix}
+mode is enabled.
@item interactive_comments
In an interactive shell, a word beginning with @samp{#}
@@ -6495,9 +6555,13 @@ @node Top
@section Special Builtins
@cindex special builtin
-For historical reasons, the @sc{posix} standard has classified
+For historical reasons, the
+@sc{posix}
+standard has classified
several builtin commands as @emph{special}.
-When Bash is executing in @sc{posix} mode, the special builtins
+When Bash is executing in
+@sc{posix}
+mode, the special builtins
differ from other builtin commands in three respects:
@enumerate
@@ -6512,11 +6576,17 @@ @node Top
environment after the command completes.
@end enumerate
-When Bash is not executing in @sc{posix} mode, these builtins behave no
+When Bash is not executing in
+@sc{posix}
+mode, these builtins behave no
differently than the rest of the Bash builtin commands.
-The Bash @sc{posix} mode is described in @ref{Bash POSIX Mode}.
+The Bash
+@sc{posix}
+mode is described in @ref{Bash POSIX Mode}.
-These are the @sc{posix} special builtins:
+These are the
+@sc{posix}
+special builtins:
@example
@w{break : . source continue eval exec exit export readonly return set}
@w{shift times trap unset}
@@ -6863,7 +6933,8 @@ @node Top
@item CHILD_MAX
Set the number of exited child status values for the shell to remember.
-Bash will not allow this value to be decreased below a @sc{posix}-mandated
+Bash will not allow this value to be decreased below a
+@sc{posix}-mandated
minimum, and there is a maximum value (currently 8192) that this may
not exceed.
The minimum value is system-dependent.
@@ -6962,7 +7033,8 @@ @node Top
Expanded and executed similarly to @code{BASH_ENV}
(@pxref{Bash Startup Files})
when an interactive shell is invoked in
-@sc{posix} Mode (@pxref{Bash POSIX Mode}).
+@sc{posix}
+mode (@pxref{Bash POSIX Mode}).
@item EPOCHREALTIME
Each time this parameter is referenced, it expands to the number of seconds
@@ -7369,16 +7441,22 @@ @node Top
@item POSIXLY_CORRECT
If this variable is in the environment when Bash starts, the shell
-enters @sc{posix} mode (@pxref{Bash POSIX Mode}) before reading the
+enters
+@sc{posix}
+mode (@pxref{Bash POSIX Mode}) before reading the
startup files, as if the @option{--posix} invocation option had been supplied.
-If it is set while the shell is running, Bash enables @sc{posix} mode,
+If it is set while the shell is running, Bash enables
+@sc{posix}
+mode,
as if the command
@example
@code{set -o posix}
@end example
@noindent
had been executed.
-When the shell enters @sc{posix} mode, it sets this variable if it was
+When the shell enters
+@sc{posix}
+mode, it sets this variable if it was
not already set.
@item PPID
@@ -7656,10 +7734,14 @@ @node Top
@item --posix
Change the behavior of Bash where the default operation differs
-from the @sc{posix} standard to match the standard.
+from the
+@sc{posix}
+standard to match the standard.
This is intended to make Bash behave as a strict superset of that
standard.
-@xref{Bash POSIX Mode}, for a description of the Bash @sc{posix} mode.
+@xref{Bash POSIX Mode}, for a description of the Bash
+@sc{posix}
+mode.
@item --restricted
Equivalent to @option{-r}.
@@ -7717,8 +7799,15 @@ @node Top
on the standard output.
These are the strings that
are subject to language translation when the current locale
-is not @code{C} or @code{POSIX} (@pxref{Locale Translation}).
-This implies the @option{-n} option; no commands will be executed.
+is not
+@samp{C}
+or
+@samp{POSIX}
+(@pxref{Locale Translation}).
+This implies the
+@option{-n}
+option;
+no commands will be executed.
@item [-+]O [@var{shopt_option}]
@var{shopt_option} is one of the shell options accepted by the
@@ -7833,7 +7922,9 @@ @node Top
If Bash is invoked with the name @code{sh}, it tries to mimic the
startup behavior of historical versions of @code{sh} as closely as
-possible, while conforming to the @sc{posix} standard as well.
+possible, while conforming to the
+@sc{posix}
+standard as well.
When invoked as an interactive login shell, or as a non-interactive
shell with the @option{--login} option, it first attempts to read
@@ -7856,8 +7947,12 @@ @node Top
@subsubheading Invoked in @sc{posix} mode
-When Bash is started in @sc{posix} mode, as with the
-@option{--posix} command line option, it follows the @sc{posix} standard
+When Bash is started in
+@sc{posix}
+mode, as with the
+@option{--posix} command line option, it follows the
+@sc{posix}
+standard
for startup files.
In this mode, interactive shells expand the @env{ENV} variable
and read and execute commands from the file whose name is the
@@ -8043,7 +8138,9 @@ @node Top
shell to exit.
@item
-When running in @sc{posix} mode, a special builtin returning an error
+When running in
+@sc{posix}
+mode, a special builtin returning an error
status will not cause the shell to exit (@pxref{Bash POSIX Mode}).
@item
@@ -8212,7 +8309,9 @@ @node Top
When used with the @code{[[} command, this performs pattern matching as
described above (@pxref{Conditional Constructs}).
-@samp{=} should be used with the @code{test} command for @sc{posix}
conformance.
+@samp{=} should be used with the @code{test} command for
+@sc{posix}
+conformance.
@item @var{string1} != @var{string2}
True if the strings are not equal.
@@ -8936,12 +9035,15 @@ @node Top
@subsection What is POSIX?
@cindex POSIX description
-@sc{posix} is the name for a family of standards based on Unix.
+@sc{posix}
+is the name for a family of standards based on Unix.
A number of Unix services, tools, and functions are part of the standard,
ranging from the basic system calls and C library functions to common
applications and tools to system administration and management.
-The @sc{posix} Shell and Utilities standard was originally developed by
+The
+@sc{posix}
+Shell and Utilities standard was originally developed by
IEEE Working Group 1003.2 (POSIX.2).
The first edition of the 1003.2 standard was published in 1992.
It was merged with the original IEEE 1003.1 Working Group and is
@@ -8949,7 +9051,9 @@ @node Top
IEEE, The Open Group and ISO/IEC SC22/WG15).
Today the Shell and Utilities are a volume within the set of documents that
make up IEEE Std 1003.1-2024, and thus the former POSIX.2 (from 1992)
-is now part of the current unified @sc{posix} standard.
+is now part of the current unified
+@sc{posix}
+standard.
The Shell and Utilities volume concentrates on the command
interpreter interface and utility programs commonly executed from
@@ -8958,7 +9062,9 @@ @node Top
@url{https://pubs.opengroup.org/onlinepubs/9799919799/utilities/contents.html}.
Bash is concerned with the aspects of the shell's behavior defined
-by the @sc{posix} Shell and Utilities volume.
+by the
+@sc{posix}
+Shell and Utilities volume.
The shell command
language has of course been standardized, including the basic flow
control and program execution constructs, I/O redirection and
@@ -8981,7 +9087,9 @@ @node Top
@subsection Bash POSIX Mode
@cindex POSIX Mode
-Although Bash is an implementation of the @sc{posix} shell
+Although Bash is an implementation of the
+@sc{posix}
+shell
specification, there are areas where the Bash default behavior
differs from the specification.
The Bash @dfn{posix mode} changes the Bash
@@ -8990,20 +9098,30 @@ @node Top
Starting Bash with the @option{--posix} command-line option or executing
@samp{set -o posix} while Bash is running will cause Bash to conform more
-closely to the @sc{posix} standard by changing the behavior to
-match that specified by @sc{posix} in areas where the Bash default differs.
-
-When invoked as @code{sh}, Bash enters @sc{posix} mode after reading the
+closely to the
+@sc{posix}
+standard by changing the behavior to
+match that specified by
+@sc{posix}
+in areas where the Bash default differs.
+
+When invoked as @code{sh}, Bash enters
+@sc{posix}
+mode after reading the
startup files.
-The following list is what's changed when `@sc{posix} mode' is in effect:
+The following list is what's changed when
+@sc{posix}
+mode is in effect:
@enumerate
@item
Bash ensures that the @env{POSIXLY_CORRECT} variable is set.
@item
-Bash reads and executes the @sc{posix} startup files
+Bash reads and executes the
+@sc{posix}
+startup files
(@env{$ENV}) rather than
the normal Bash files (@pxref{Bash Startup Files}.
@@ -9057,7 +9175,9 @@ @node Top
redirection.
@item
-Function names may not be the same as one of the @sc{posix} special
+Function names may not be the same as one of the
+@sc{posix}
+special
builtins.
@item
@@ -9094,12 +9214,16 @@ @node Top
under @ref{Tilde Expansion}.
@item
-Command lookup finds @sc{posix} special builtins before shell functions,
+Command lookup finds
+@sc{posix}
+special builtins before shell functions,
including output printed by the @code{type} and @code{command} builtins.
@item
Even if a shell function whose name contains a slash was defined before
-entering @sc{posix} mode, the shell will not execute a function whose name
+entering
+@sc{posix}
+mode, the shell will not execute a function whose name
contains one or more slashes.
@item
@@ -9148,7 +9272,8 @@ @node Top
@item
Prompt expansion enables the
-@sc{posix} @env{PS1} and @env{PS2} expansions of @samp{!} to
+@sc{posix}
+@env{PS1} and @env{PS2} expansions of @samp{!} to
the history number and @samp{!!} to @samp{!},
and Bash performs parameter expansion on the values of @env{PS1} and
@env{PS2} regardless of the setting of the @code{promptvars} option.
@@ -9173,10 +9298,14 @@ @node Top
Non-interactive shells exit if a parameter expansion error occurs.
@item
-If a @sc{posix} special builtin returns an error status, a
+If a
+@sc{posix}
+special builtin returns an error status, a
non-interactive shell exits.
The fatal errors are those listed in
-the @sc{posix} standard, and include things like passing incorrect options,
+the
+@sc{posix}
+standard, and include things like passing incorrect options,
redirection errors, variable assignment errors for assignments preceding
the command name, and so on.
@@ -9219,17 +9348,23 @@ @node Top
These errors force an exit because these are special builtins.
@item
-Assignment statements preceding @sc{posix} special builtins
+Assignment statements preceding
+@sc{posix}
+special builtins
persist in the shell environment after the builtin completes.
@item
The @code{command} builtin does not prevent builtins that take assignment
statements as arguments from expanding them as assignment statements;
-when not in @sc{posix} mode, declaration commands lose their assignment
+when not in
+@sc{posix}
+mode, declaration commands lose their assignment
statement expansion properties when preceded by @code{command}.
@item
-Enabling @sc{posix} mode has the effect of setting the
+Enabling
+@sc{posix}
+mode has the effect of setting the
@code{inherit_errexit} option, so
subshells spawned to execute command substitutions inherit the value of
the @option{-e} option from the parent shell.
@@ -9237,13 +9372,17 @@ @node Top
Bash clears the @option{-e} option in such subshells.
@item
-Enabling @sc{posix} mode has the effect of setting the
+Enabling
+@sc{posix}
+mode has the effect of setting the
@code{shift_verbose} option, so numeric arguments to @code{shift}
that exceed the number of positional parameters will result in an
error message.
@item
-Enabling @sc{posix} mode has the effect of setting the
+Enabling
+@sc{posix}
+mode has the effect of setting the
@code{interactive_comments} option (@pxref{Comments}).
@item
@@ -9280,7 +9419,8 @@ @node Top
@item
The @code{export} and @code{readonly} builtin commands display their
-output in the format required by @sc{posix}.
+output in the format required by
+@sc{posix}.
@item
When listing the history, the @code{fc} builtin does not include an
@@ -9391,8 +9531,12 @@ @node Top
@end enumerate
-There is other @sc{posix} behavior that Bash does not implement by
-default even when in @sc{posix} mode.
+There is other
+@sc{posix}
+behavior that Bash does not implement by
+default even when in
+@sc{posix}
+mode.
Specifically:
@enumerate
@@ -9407,7 +9551,9 @@ @node Top
@item
A non-interactive shell does not exit if a variable assignment preceding
the @code{command} builtin or another non-special builtin fails.
-There is ambiguity in @sc{posix} about this.
+There is ambiguity in
+@sc{posix}
+about this.
@end ignore
@item
@@ -9416,7 +9562,8 @@ @node Top
@end enumerate
-Bash can be configured to be @sc{posix}-conformant by default, by specifying
+Bash can be configured to be
+@sc{posix}-conformant by default, by specifying
the @option{--enable-strict-posix-default} to @code{configure} when building
(@pxref{Optional Features}).
@@ -9506,13 +9653,17 @@ @node Top
@itemize @bullet
@item
In posix mode, @code{time} may be followed by options and still be
-recognized as a reserved word (this is @sc{posix} interpretation 267).
+recognized as a reserved word (this is
+@sc{posix}
+interpretation 267).
@item
In posix mode, the parser requires that an even number of single
quotes occur in the @var{word} portion of a double-quoted $@{@dots{}@}
parameter expansion and treats them specially, so that characters within
the single quotes are considered quoted
-(this is @sc{posix} interpretation 221).
+(this is
+@sc{posix}
+interpretation 221).
@end itemize
@item compat42
@@ -9524,7 +9675,9 @@ @node Top
In posix mode, single quotes are considered special when expanding
the @var{word} portion of a double-quoted $@{@dots{}@} parameter expansion
and can be used to quote a closing brace or other special character
-(this is part of @sc{posix} interpretation 221);
+(this is part of
+@sc{posix}
+interpretation 221);
in later versions, single quotes
are not special within double-quoted word expansions.
@end itemize
@@ -10530,7 +10683,9 @@ @node Top
(@pxref{Conditional Constructs}).
@item --enable-cond-regexp
-Include support for matching @sc{posix} regular expressions using the
+Include support for matching
+@sc{posix}
+regular expressions using the
@samp{=~} binary operator in the @code{[[} conditional command.
(@pxref{Conditional Constructs}).
@@ -10646,7 +10801,8 @@ @node Top
literals.
@item --enable-strict-posix-default
-Make Bash @sc{posix}-conformant by default (@pxref{Bash POSIX Mode}).
+Make Bash
+@sc{posix}-conformant by default (@pxref{Bash POSIX Mode}).
@item --enable-translatable-strings
Enable support for @code{$"@var{string}"} translatable strings
@@ -10718,7 +10874,9 @@ @node Top
Bash implements essentially the same grammar, parameter and
variable expansion, redirection, and quoting as the Bourne Shell.
-Bash uses the @sc{posix} standard as the specification of
+Bash uses the
+@sc{posix}
+standard as the specification of
how these features are to be implemented and how they should behave.
There are some
differences between the traditional Bourne shell and Bash; this
@@ -10731,7 +10889,10 @@ @node Top
@itemize @bullet
@item
-Bash is @sc{posix}-conformant, even where the @sc{posix} specification
+Bash is
+@sc{posix}-conformant, even where the
+@sc{posix}
+specification
differs from traditional @code{sh} behavior (@pxref{Bash POSIX Mode}).
@item
@@ -10862,7 +11023,9 @@ @node Top
(@pxref{Shell Parameters}).
@item
-Bash includes the @sc{posix} pattern removal @samp{%}, @samp{#}, @samp{%%}
+Bash includes the
+@sc{posix}
+pattern removal @samp{%}, @samp{#}, @samp{%%}
and @samp{##} expansions to remove leading or trailing substrings from
variable values (@pxref{Shell Parameter Expansion}).
@@ -10899,7 +11062,9 @@ @node Top
(@pxref{Shell Parameter Expansion}).
@item
-The @sc{posix} @code{$()} form of command substitution
+The
+@sc{posix}
+@code{$()} form of command substitution
is implemented (@pxref{Command Substitution}),
and preferred to the Bourne shell's @code{``} (which
is also implemented for backwards compatibility).
@@ -10946,7 +11111,9 @@ @node Top
The Bourne shell uses only @samp{!}.
@item
-Bash implements the full set of @sc{posix} filename expansion operators,
+Bash implements the full set of
+@sc{posix}
+filename expansion operators,
including character classes, equivalence classes, and
collating symbols (@pxref{Filename Expansion}).
@@ -11147,7 +11314,9 @@ @node Top
@item
The @code{test} builtin (@pxref{Bourne Shell Builtins})
-is slightly different, as it implements the @sc{posix} algorithm,
+is slightly different, as it implements the
+@sc{posix}
+algorithm,
which specifies the behavior based on the number of arguments.
@item
@@ -11275,8 +11444,12 @@ @node Top
@item
The SVR4.2 shell exits a script if any builtin fails; Bash exits
-a script only if one of the @sc{posix} special builtins fails, and
-only for certain failures, as enumerated in the @sc{posix} standard.
+a script only if one of the
+@sc{posix}
+special builtins fails, and
+only for certain failures, as enumerated in the
+@sc{posix}
+standard.
@item
If the @code{lastpipe} option is enabled, and job control is not active,
diff --git a/lib/readline/doc/rluser.texi b/lib/readline/doc/rluser.texi
index 7f21dd34..a2eab9b3 100644
--- a/lib/readline/doc/rluser.texi
+++ b/lib/readline/doc/rluser.texi
@@ -2125,7 +2125,9 @@
editing functions, it does contain enough to allow simple editing
of the line.
The Readline @code{vi} mode behaves as specified in the
-@code{sh} description in the @sc{posix} standard.
+@code{sh} description in the
+@sc{posix}
+standard.
@ifset BashFeatures
You can use the @samp{set -o emacs} and @samp{set -o vi}
--
2.30.2
signature.asc
Description: PGP signature
- [PATCH 6/9] Slightly revise documentation of POSIX mode.,
G. Branden Robinson <=