bash/doc/shell-compat

@node Shell Compatibility Mode
@section Shell Compatibility Mode
@cindex Compatibility Level
@cindex Compatibility Mode

Bash-4.0 introduced the concept of a `shell compatibility level', specified
as a set of options to the shopt builtin
(@code{compat31},
@code{compat32},
@code{compat40},
@code{compat41},
and so on).
There is only one current
compatibility level -- each option is mutually exclusive.
The compatibility level is intended to allow users to select behavior
from previous versions that is incompatible with newer versions
while they migrate scripts to use current features and
behavior. It's intended to be a temporary solution.

This section does not mention behavior that is standard for a particular
version (e.g., setting @code{compat32} means that quoting the rhs of the regexp
matching operator quotes special regexp characters in the word, which is
default behavior in bash-3.2 and above). 

If a user enables, say, @code{compat32}, it may affect the behavior of other
compatibility levels up to and including the current compatibility level.
The idea is that each compatibility level controls behavior that changed
in that version of Bash, but that granularity may not be sufficient for
all uses, and as a result users should employ compatibility levels carefully.
Read the documentation for a particular feature to find out the
current behavior.

Bash-4.3 introduced a new shell variable: @env{BASH_COMPAT}.
The value assigned
to this variable (a decimal version number like 4.2, or an integer
corresponding to the @code{compat}@var{NN} option, like 42) determines the
compatibility level.

Starting with bash-4.4, Bash has begun deprecating older compatibility
levels.
Eventually, the options will be removed in favor of @env{BASH_COMPAT}.

Bash-5.0 is the final version for which there will be an individual shopt
option for the previous version. Users should use @env{BASH_COMPAT}
on bash-5.0 and later versions.

The following table describes the behavior changes controlled by each
compatibility level setting.
The @code{compat}@var{NN} tag is used as shorthand for setting the
compatibility level
to @var{NN} using one of the following mechanisms.
For versions prior to bash-5.0, the compatibility level may be set using
the corresponding @code{compat}@var{NN} shopt option.
For bash-4.3 and later versions, the @env{BASH_COMPAT} variable is preferred,
and it is required for bash-5.1 and later versions.

@table @code
@item compat31
@itemize @bullet
@item
quoting the rhs of the @code{[[} command's regexp matching operator (=~)
has no special effect
@end itemize

@item compat32
@itemize @bullet
@item
interrupting a command list such as "a ; b ; c" causes the execution
of the next command in the list (in bash-4.0 and later versions,
the shell acts as if it received the interrupt, so
interrupting one command in a list aborts the execution of the
entire list)
@end itemize

@item compat40
@itemize @bullet
@item
the @samp{<} and @samp{>} operators to the @code{[[} command do not
consider the current locale when comparing strings; they use ASCII
ordering.
Bash versions prior to bash-4.1 use ASCII collation and strcmp(3);
bash-4.1 and later use the current locale's collation sequence and
strcoll(3).
@end itemize

@item compat41
@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)
@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)
@end itemize

@item compat42
@itemize @bullet
@item
the replacement string in double-quoted pattern substitution is not
run through quote removal, as it is in versions after bash-4.2
@item
in posix mode, single quotes are considered special when expanding
the @var{word} portion of a double-quoted a $@{@dots{}@} parameter expansion
and can be used to quote a closing brace or other special character
(this is part of @sc{posix} interpretation 221);
in later versions, single quotes
are not special within double-quoted word expansions
@end itemize

@item compat43
@itemize @bullet
@item
the shell does not print a warning message if an attempt is made to
use a quoted compound assignment as an argument to declare
(declare -a foo='(1 2)'). Later versions warn that this usage is
deprecated
@item
word expansion errors are considered non-fatal errors that cause the
current command to fail, even in posix mode
(the default behavior is to make them fatal errors that cause the shell
to exit)
@item
when executing a shell function, the loop state (while/until/etc.)
is not reset, so @code{break} or @code{continue} in that function will break
or continue loops in the calling context. Bash-4.4 and later reset
the loop state to prevent this
@end itemize

@item compat44
@itemize @bullet
@item
the shell sets up the values used by @env{BASH_ARGV} and @env{BASH_ARGC}
so they can expand to the shell's positional parameters even if extended
debug mode is not enabled
@item
a subshell inherits loops from its parent context, so @code{break}
or @code{continue} will cause the subshell to exit.
Bash-5.0 and later reset the loop state to prevent the exit
@item
variable assignments preceding builtins like @code{export} and @code{readonly}
that set attributes continue to affect variables with the same
name in the calling environment even if the shell is not in posix
mode
@end itemize

@item compat50 (set using BASH_COMPAT)
@itemize @bullet
@item
Bash-5.1 changed the way @code{$RANDOM} is generated to introduce slightly
more randomness. If the shell compatibility level is set to 50 or
lower, it reverts to the method from bash-5.0 and previous versions,
so seeding the random number generator by assigning a value to
@env{RANDOM} wll produce the same sequence as in bash-5.0
@end itemize
@end table