-6.11 Bash POSIX Mode
-====================
+6.11 Bash and POSIX
+===================
+
+6.11.1 What is POSIX?
+---------------------
+
+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 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 currently maintained by the Austin Group (a
+joint working group of the 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-2017, and thus the former POSIX.2 (from
+1992) is now part of the current unified POSIX standard.
+
+The Shell and Utilities volume concentrates on the command interpreter
+interface and utility programs commonly executed from the command line
+or by other programs. The standard is freely available on the web at
+<https://pubs.opengroup.org/onlinepubs/9699919799/utilities/contents.html>.
+
+Bash is concerned with the aspects of the shell's behavior defined by
+the 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 pipelines, argument handling,
+variable expansion, and quoting.
+
+The special builtins, which must be implemented as part of the shell to
+provide the desired functionality, are specified as being part of the
+shell; examples of these are 'eval' and 'export'. Other utilities
+appear in the sections of POSIX not devoted to the shell which are
+commonly (and in some cases must be) implemented as builtin commands,
+such as 'read' and 'test'. POSIX also specifies aspects of the shell's
+interactive behavior, including job control and command line editing.
+Only vi-style line editing commands have been standardized; emacs
+editing commands were left out due to objections.
+
+6.11.2 Bash POSIX Mode
+----------------------
+
+Although Bash is an implementation of the POSIX shell specification,
+there are areas where the Bash default behavior differs from the
+specification. The Bash "posix mode" changes the Bash behavior in these
+areas so that it conforms to the standard more closely.
Starting Bash with the '--posix' command-line option or executing 'set
-o posix' while Bash is running will cause Bash to conform more closely
16. Function names may not be the same as one of the POSIX special
builtins.
- 17. POSIX special builtins are found before shell functions during
+ 17. Even if a shell function whose name contains a slash was defined
+ before entering POSIX mode, the shell will not execute a function
+ whose name contains one or more slashes.
+
+ 18. POSIX special builtins are found before shell functions during
command lookup.
- 18. When printing shell function definitions (e.g., by 'type'), Bash
+ 19. When printing shell function definitions (e.g., by 'type'), Bash
does not print the 'function' keyword.
- 19. Literal tildes that appear as the first character in elements of
+ 20. Literal tildes that appear as the first character in elements of
the 'PATH' variable are not expanded as described above under *note
Tilde Expansion::.
- 20. The 'time' reserved word may be used by itself as a command. When
+ 21. The 'time' reserved word may be used by itself as a command. When
used in this way, it displays timing statistics for the shell and
its completed children. The 'TIMEFORMAT' variable controls the
format of the timing information.
- 21. When parsing and expanding a ${...} expansion that appears within
+ 22. When parsing and expanding a ${...} expansion that appears within
double quotes, single quotes are no longer special and cannot be
used to quote a closing brace or other special character, unless
the operator is one of those defined to perform pattern removal.
In this case, they do not have to appear as matched pairs.
- 22. The parser does not recognize 'time' as a reserved word if the
+ 23. The parser does not recognize 'time' as a reserved word if the
next token begins with a '-'.
- 23. The '!' character does not introduce history expansion within a
+ 24. The '!' character does not introduce history expansion within a
double-quoted string, even if the 'histexpand' option is enabled.
- 24. If a POSIX special builtin returns an error status, a
+ 25. If a POSIX special builtin returns an error status, a
non-interactive shell exits. The fatal errors are those listed in
the POSIX standard, and include things like passing incorrect
options, redirection errors, variable assignment errors for
assignments preceding the command name, and so on.
- 25. A non-interactive shell exits with an error status if a variable
+ 26. The 'unset' builtin with the '-v' option specified returns a fatal
+ error if it attempts to unset a 'readonly' or 'non-unsettable'
+ variable, or encounters a variable name argument that is an invalid
+ identifier, which causes a non-interactive shell to exit.
+
+ 27. A non-interactive shell exits with an error status if a variable
assignment error occurs when no command name follows the assignment
statements. A variable assignment error occurs, for example, when
trying to assign a value to a readonly variable.
- 26. A non-interactive shell exits with an error status if a variable
+ 28. A non-interactive shell exits with an error status if a variable
assignment error occurs in an assignment statement preceding a
special builtin, but not with any other simple command. For any
other simple command, the shell aborts execution of that command,
perform any further processing of the command in which the error
occurred").
- 27. A non-interactive shell exits with an error status if the
+ 29. A non-interactive shell exits with an error status if the
iteration variable in a 'for' statement or the selection variable
in a 'select' statement is a readonly variable.
- 28. Non-interactive shells exit if FILENAME in '.' FILENAME is not
+ 30. Non-interactive shells exit if FILENAME in '.' FILENAME is not
found.
- 29. Non-interactive shells exit if a syntax error in an arithmetic
+ 31. Non-interactive shells exit if a syntax error in an arithmetic
expansion results in an invalid expression.
- 30. Non-interactive shells exit if a parameter expansion error occurs.
+ 32. Non-interactive shells exit if a parameter expansion error occurs.
- 31. Non-interactive shells exit if there is a syntax error in a script
+ 33. Non-interactive shells exit if there is a syntax error in a script
read with the '.' or 'source' builtins, or in a string processed by
the 'eval' builtin.
- 32. While variable indirection is available, it may not be applied to
+ 34. While variable indirection is available, it may not be applied to
the '#' and '?' special parameters.
- 33. Expanding the '*' special parameter in a pattern context where the
+ 35. Expanding the '*' special parameter in a pattern context where the
expansion is double-quoted does not treat the '$*' as if it were
double-quoted.
- 34. Assignment statements preceding POSIX special builtins persist in
+ 36. Assignment statements preceding POSIX special builtins persist in
the shell environment after the builtin completes.
- 35. The 'command' builtin does not prevent builtins that take
+ 37. The 'command' builtin does not prevent builtins that take
assignment statements as arguments from expanding them as
assignment statements; when not in POSIX mode, assignment builtins
lose their assignment statement expansion properties when preceded
by 'command'.
- 36. The 'bg' builtin uses the required format to describe each job
+ 38. The 'bg' builtin uses the required format to describe each job
placed in the background, which does not include an indication of
whether the job is the current or previous job.
- 37. The output of 'kill -l' prints all the signal names on a single
+ 39. The output of 'kill -l' prints all the signal names on a single
line, separated by spaces, without the 'SIG' prefix.
- 38. The 'kill' builtin does not accept signal names with a 'SIG'
+ 40. The 'kill' builtin does not accept signal names with a 'SIG'
prefix.
- 39. The 'export' and 'readonly' builtin commands display their output
+ 41. The 'export' and 'readonly' builtin commands display their output
in the format required by POSIX.
- 40. The 'trap' builtin displays signal names without the leading
+ 42. The 'trap' builtin displays signal names without the leading
'SIG'.
- 41. The 'trap' builtin doesn't check the first argument for a possible
+ 43. The 'trap' builtin doesn't check the first argument for a possible
signal specification and revert the signal handling to the original
disposition if it is, unless that argument consists solely of
digits and is a valid signal number. If users want to reset the
handler for a given signal to the original disposition, they should
use '-' as the first argument.
- 42. 'trap -p' without arguments displays signals whose dispositions
+ 44. 'trap -p' without arguments displays signals whose dispositions
are set to SIG_DFL and those that were ignored when the shell
started, not just trapped signals.
- 43. The '.' and 'source' builtins do not search the current directory
+ 45. The '.' and 'source' builtins do not search the current directory
for the filename argument if it is not found by searching 'PATH'.
- 44. Enabling POSIX mode has the effect of setting the
+ 46. Enabling POSIX mode has the effect of setting the
'inherit_errexit' option, so subshells spawned to execute command
substitutions inherit the value of the '-e' option from the parent
shell. When the 'inherit_errexit' option is not enabled, Bash
clears the '-e' option in such subshells.
- 45. Enabling POSIX mode has the effect of setting the 'shift_verbose'
+ 47. Enabling POSIX mode has the effect of setting the 'shift_verbose'
option, so numeric arguments to 'shift' that exceed the number of
positional parameters will result in an error message.
- 46. When the 'alias' builtin displays alias definitions, it does not
+ 48. When the 'alias' builtin displays alias definitions, it does not
display them with a leading 'alias ' unless the '-p' option is
supplied.
- 47. When the 'set' builtin is invoked without options, it does not
+ 49. When the 'set' builtin is invoked without options, it does not
display shell function names and definitions.
- 48. When the 'set' builtin is invoked without options, it displays
+ 50. When the 'set' builtin is invoked without options, it displays
variable values without quotes, unless they contain shell
metacharacters, even if the result contains nonprinting characters.
- 49. When the 'cd' builtin is invoked in logical mode, and the pathname
+ 51. When the 'cd' builtin is invoked in logical mode, and the pathname
constructed from '$PWD' and the directory name supplied as an
argument does not refer to an existing directory, 'cd' will fail
instead of falling back to physical mode.
- 50. When the 'cd' builtin cannot change a directory because the length
+ 52. When the 'cd' builtin cannot change a directory because the length
of the pathname constructed from '$PWD' and the directory name
supplied as an argument exceeds 'PATH_MAX' when all symbolic links
are expanded, 'cd' will fail instead of attempting to use only the
supplied directory name.
- 51. The 'pwd' builtin verifies that the value it prints is the same as
+ 53. The 'pwd' builtin verifies that the value it prints is the same as
the current directory, even if it is not asked to check the file
system with the '-P' option.
- 52. When listing the history, the 'fc' builtin does not include an
+ 54. When listing the history, the 'fc' builtin does not include an
indication of whether or not a history entry has been modified.
- 53. The default editor used by 'fc' is 'ed'.
+ 55. The default editor used by 'fc' is 'ed'.
+
+ 56. If there are too many arguments supplied to 'fc -s', 'fc' prints
+ an error message and returns failure.
- 54. The 'type' and 'command' builtins will not report a non-executable
+ 57. The 'type' and 'command' builtins will not report a non-executable
file as having been found, though the shell will attempt to execute
such a file if it is the only so-named file found in '$PATH'.
- 55. The 'vi' editing mode will invoke the 'vi' editor directly when
+ 58. The 'vi' editing mode will invoke the 'vi' editor directly when
the 'v' command is run, instead of checking '$VISUAL' and
'$EDITOR'.
- 56. When the 'xpg_echo' option is enabled, Bash does not attempt to
+ 59. When the 'xpg_echo' option is enabled, Bash does not attempt to
interpret any arguments to 'echo' as options. Each argument is
displayed, after escape characters are converted.
- 57. The 'ulimit' builtin uses a block size of 512 bytes for the '-c'
+ 60. The 'ulimit' builtin uses a block size of 512 bytes for the '-c'
and '-f' options.
- 58. The arrival of 'SIGCHLD' when a trap is set on 'SIGCHLD' does not
+ 61. The arrival of 'SIGCHLD' when a trap is set on 'SIGCHLD' does not
interrupt the 'wait' builtin and cause it to return immediately.
The trap command is run once for each child that exits.
- 59. The 'read' builtin may be interrupted by a signal for which a trap
+ 62. The 'read' builtin may be interrupted by a signal for which a trap
has been set. If Bash receives a trapped signal while executing
'read', the trap handler executes and 'read' returns an exit status
greater than 128.
- 60. The 'printf' builtin uses 'double' (via 'strtod') to convert
+ 63. The 'printf' builtin uses 'double' (via 'strtod') to convert
arguments corresponding to floating point conversion specifiers,
instead of 'long double' if it's available. The 'L' length
modifier forces 'printf' to use 'long double' if it's available.
- 61. Bash removes an exited background process's status from the list
+ 64. Bash removes an exited background process's status from the list
of such statuses after the 'wait' builtin is used to obtain it.
+ 65. A double quote character ('"') is treated specially when it
+ appears in a backquoted command substitution in the body of a
+ here-document that undergoes expansion. That means, for example,
+ that a backslash preceding a double quote character will escape it
+ and the backslash will be removed.
+
There is other POSIX behavior that Bash does not implement by default
even when in POSIX mode. Specifically:
entries if 'FCEDIT' is unset, rather than defaulting directly to
'ed'. 'fc' uses 'ed' if 'EDITOR' is unset.
- 2. As noted above, Bash requires the 'xpg_echo' option to be enabled
+ 2. A non-interactive shell does not exit if a variable assignment
+ preceding the 'command' builtin or another non-special builtin
+ fails.
+
+ 3. As noted above, Bash requires the 'xpg_echo' option to be enabled
for the 'echo' builtin to be fully conformant.
Bash can be configured to be POSIX-conformant by default, by specifying
Bash handles several filenames specially when they are used in
redirections, as described in the following table.
If the operating system on which Bash is running provides these
-special files, bash will use them; otherwise it will emulate them
+special files, Bash will use them; otherwise it will emulate them
internally with the behavior described below.
@table @code
This means that dollar signs in variable names that expand to directories
will not be quoted;
however, any dollar signs appearing in filenames will not be quoted, either.
-This is active only when bash is using backslashes to quote completed
+This is active only when Bash is using backslashes to quote completed
filenames.
This variable is set by default, which is the default Bash behavior in
versions through 4.2.
@item BASH_ARGC
An array variable whose values are the number of parameters in each
-frame of the current bash execution call stack. The number of
+frame of the current Bash execution call stack. The number of
parameters to the current subroutine (shell function or script executed
with @code{.} or @code{source}) is at the top of the stack. When a
subroutine is executed, the number of parameters passed is pushed onto
may result in inconsistent values.
@item BASH_ARGV
-An array variable containing all of the parameters in the current bash
+An array variable containing all of the parameters in the current Bash
execution call stack. The final parameter of the last subroutine call
is at the top of the stack; the first parameter of the initial call is
at the bottom. When a subroutine is executed, the parameters supplied
@node Bash POSIX Mode
-@section Bash POSIX Mode
+@section Bash and POSIX
+
+@subsection What is POSIX?
+@cindex POSIX description
+
+@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
+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
+currently maintained by the Austin Group (a joint working group of the
+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-2017, and thus the former POSIX.2 (from 1992)
+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
+the command line or by other programs.
+The standard is freely available on the web at
+@url{https://pubs.opengroup.org/onlinepubs/9699919799/utilities/contents.html}.
+
+Bash is concerned with the aspects of the shell's behavior defined
+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
+pipelines, argument handling, variable expansion, and quoting.
+
+The @i{special} builtins, which must be implemented as part of the
+shell to provide the desired functionality, are specified as
+being part of the shell; examples of these are @code{eval} and
+@code{export}.
+Other utilities appear in the sections of POSIX not
+devoted to the shell which are commonly (and in some cases must
+be) implemented as builtin commands, such as
+@code{read} and @code{test}.
+POSIX also specifies aspects of the shell's interactive
+behavior, including job control and command
+line editing.
+Only vi-style line editing commands have been
+standardized; emacs editing commands were left out due to
+objections.
+
+@subsection Bash POSIX Mode
@cindex POSIX Mode
+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
+behavior in these areas so that it conforms to the standard more closely.
+
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
entries if @code{FCEDIT} is unset, rather than defaulting directly to
@code{ed}. @code{fc} uses @code{ed} if @code{EDITOR} is unset.
+@item
+A non-interactive shell does not exit if a variable assignment preceding
+the @code{command} builtin or another non-special builtin fails.
+
@item
As noted above, Bash requires the @code{xpg_echo} option to be enabled for
the @code{echo} builtin to be fully conformant.
If you want to build Bash in a directory separate from the source
directory -- to build for multiple architectures, for example --
just use the full path to the configure script. The following commands
-will build bash in a directory under @file{/usr/local/build} from
+will build Bash in a directory under @file{/usr/local/build} from
the source code in @file{/usr/local/src/bash-4.4}:
@example
variable when running @samp{make install}
(e.g., @samp{make install prefix=@var{PATH}}).
The @env{prefix} variable provides a default for @env{exec_prefix} and
-other variables used when installing bash.
+other variables used when installing Bash.
You can specify separate installation prefixes for
architecture-specific files and architecture-independent files.
@samp{make install exec_prefix=/} will install @code{bash} and
@code{bashbug} into @file{/bin} instead of the default @file{/usr/local/bin}.
-If you want to see the files bash will install and where it will install
+If you want to see the files Bash will install and where it will install
them without changing anything on your system, specify the variable
@env{DESTDIR} as an argument to @code{make}. Its value should be the
absolute directory path you'd like to use as the root of your sample
@table @code
@item --enable-largefile
-Enable support for @uref{http://www.unix.org/version2/whatsnew/lfs20mar.html,
+Enable support for @url{http://www.unix.org/version2/whatsnew/lfs20mar.html,
large files} if the operating system requires special compiler options
to build programs which can access large files. This is enabled by
default, if the operating system provides large file support.
builtins (@pxref{Aliases}).
@item --enable-alt-array-implementation
-This builds bash using an alternate implementation of arrays
+This builds Bash using an alternate implementation of arrays
(@pxref{Arrays}) that provides faster access at the expense of using
more memory (sometimes many times more, depending on how sparse an array is).
(@pxref{Pipelines}).
@item --enable-debugger
-Include support for the bash debugger (distributed separately).
+Include support for the Bash debugger (distributed separately).
@item --enable-dev-fd-stat-broken
If calling @code{stat} on /dev/fd/@var{N} returns different results than
Once you have determined that a bug actually exists, use the
@code{bashbug} command to submit a bug report or use the form at the
-<a href="https://savannah.gnu.org/projects/bash/">Bash project page</a>.
+@uref{https://savannah.gnu.org/projects/bash/,Bash project page}.
If you have a fix, you are encouraged to submit that as well!
Suggestions and `philosophical' bug reports may be mailed
to @email{bug-bash@@gnu.org} or @email{help-bash@@gnu.org}.
projects / thirdparty / bash.git / commitdiff
