documentation updates for arithmetic expansion and array subscripts; update BASH_COMMAND for subshells; fix potential file descriptor leak in here document pipes

This commit is contained in:
Chet Ramey
2025-03-07 10:23:58 -05:00
parent e608233770
commit c3997d51f8
36 changed files with 19690 additions and 19094 deletions
+255 -201
View File
@@ -2,9 +2,9 @@ This is bashref.info, produced by makeinfo version 7.1 from
bashref.texi.
This text is a brief description of the features that are present in the
Bash shell (version 5.3, 8 January 2025).
Bash shell (version 5.3, 24 February 2025).
This is Edition 5.3, last updated 8 January 2025, of The GNU Bash
This is Edition 5.3, last updated 24 February 2025, of The GNU Bash
Reference Manual, for Bash, Version 5.3.
Copyright © 1988-2025 Free Software Foundation, Inc.
@@ -27,10 +27,10 @@ Bash Features
*************
This text is a brief description of the features that are present in the
Bash shell (version 5.3, 8 January 2025). The Bash home page is
Bash shell (version 5.3, 24 February 2025). The Bash home page is
<http://www.gnu.org/software/bash/>.
This is Edition 5.3, last updated 8 January 2025, of The GNU Bash
This is Edition 5.3, last updated 24 February 2025, of The GNU Bash
Reference Manual, for Bash, Version 5.3.
Bash contains features that appear in other popular shells, and some
@@ -993,8 +993,10 @@ File: bashref.info, Node: Conditional Constructs, Next: Command Grouping, Pre
The arithmetic EXPRESSION is evaluated according to the rules
described below (*note Shell Arithmetic::). The EXPRESSION
undergoes the same expansions as if it were within double quotes,
but double quote characters in EXPRESSION are not treated specially
and are removed. If the value of the expression is non-zero, the
but unescaped double quote characters in EXPRESSION are not treated
specially and are removed. Since this can potentially result in
empty strings, this command treats those as expressions that
evaluate to 0. If the value of the expression is non-zero, the
return status is 0; otherwise the return status is 1.
[[...]]
@@ -1490,7 +1492,7 @@ attributes.
is a valid value. Once a variable is set, it may be unset only by using
the unset builtin command.
A variable may be assigned to by a statement of the form
A variable is assigned to using a statement of the form
NAME=[VALUE]
If VALUE is not given, the variable is assigned the null string. All
VALUEs undergo tilde expansion, parameter and variable expansion,
@@ -1729,11 +1731,10 @@ integer. When integers are supplied, the expression expands to each
number between X and Y, inclusive. If either X or Y begins with a zero,
each generated term will contain the same number of digits, zero-padding
where necessary. When letters are supplied, the expression expands to
each character lexicographically between X and Y, inclusive, using the
default C locale. Note that both X and Y must be of the same type
(integer or letter). When the increment is supplied, it is used as the
difference between each term. The default increment is 1 or -1 as
appropriate.
each character lexicographically between X and Y, inclusive, using the C
locale. Note that both X and Y must be of the same type (integer or
letter). When the increment is supplied, it is used as the difference
between each term. The default increment is 1 or -1 as appropriate.
Brace expansion is performed before any other expansions, and any
characters special to other expansions are preserved in the result. It
@@ -1917,6 +1918,14 @@ omitted, the operator tests only for existence.
$ echo $var
DEFAULT
$ var=
$ : ${var=DEFAULT}
$ echo $var
$ var=
$ : ${var:=DEFAULT}
$ echo $var
DEFAULT
$ unset var
$ : ${var:=DEFAULT}
$ echo $var
DEFAULT
@@ -1932,6 +1941,16 @@ omitted, the operator tests only for existence.
$ var=
$ : ${var:?var is unset or null}
bash: var: var is unset or null
$ echo ${var?var is unset}
$ unset var
$ : ${var?var is unset}
bash: var: var is unset
$ : ${var:?var is unset or null}
bash: var: var is unset or null
$ var=123
$ echo ${var:?var is unset or null}
123
${PARAMETER:+WORD}
If PARAMETER is null or unset, nothing is substituted, otherwise
@@ -1941,9 +1960,18 @@ omitted, the operator tests only for existence.
$ var=123
$ echo ${var:+var is set and not null}
var is set and not null
$ echo ${var+var is set}
var is set
$ var=
$ echo ${var:+var is set and not null}
$ echo ${var+var is set}
var is set
$ unset var
$ echo ${var+var is set}
$ echo ${var:+var is set and not null}
$
${PARAMETER:OFFSET}
@@ -1952,11 +1980,13 @@ omitted, the operator tests only for existence.
LENGTH characters of the value of PARAMETER starting at the
character specified by OFFSET. If PARAMETER is @ or *, an
indexed array subscripted by @ or *, or an associative array
name, the results differ as described below. If LENGTH is omitted,
it expands to the substring of the value of PARAMETER starting at
the character specified by OFFSET and extending to the end of the
value. LENGTH and OFFSET are arithmetic expressions (*note Shell
Arithmetic::).
name, the results differ as described below. If :LENGTH is omitted
(the first form above), this expands to the substring of the value
of PARAMETER starting at the character specified by OFFSET and
extending to the end of the value. If OFFSET is omitted, it is
treated as 0. If LENGTH is omitted, but the colon after OFFSET is
present, it is treated as 0. LENGTH and OFFSET are arithmetic
expressions (*note Shell Arithmetic::).
If OFFSET evaluates to a number less than zero, the value is used
as an offset in characters from the end of the value of PARAMETER.
@@ -2399,11 +2429,13 @@ the result. The format for arithmetic expansion is:
$(( EXPRESSION ))
The EXPRESSION undergoes the same expansions as if it were within
double quotes, but double quote characters in EXPRESSION are not treated
specially and are removed. All tokens in the expression undergo
parameter and variable expansion, command substitution, and quote
removal. The result is treated as the arithmetic expression to be
evaluated. Arithmetic expansions may be nested.
double quotes, but unescaped double quote characters in EXPRESSION are
not treated specially and are removed. All tokens in the expression
undergo parameter and variable expansion, command substitution, and
quote removal. The result is treated as the arithmetic expression to be
evaluated. Since the way Bash handles double quotes can potentially
result in empty strings, arithmetic expansion treats those as
expressions that evaluate to 0. Arithmetic expansions may be nested.
The evaluation is performed according to the rules listed below
(*note Shell Arithmetic::). If the expression is invalid, Bash prints a
@@ -3898,11 +3930,11 @@ standard.
compound command returns a non-zero exit status, subject to the
following conditions. The ERR trap is not executed if the failed
command is part of the command list immediately following an
until or while keyword, part of the test following the if or
elif reserved words, part of a command executed in a && or ||
list except the command following the final && or ||, any
command in a pipeline but the last, (subject to the state of the
pipefail shell option), or if the command's return status is
until or while reserved word, part of the test following the
if or elif reserved words, part of a command executed in a &&
or || list except the command following the final && or ||,
any command in a pipeline but the last, (subject to the state of
the pipefail shell option), or if the command's return status is
being inverted using !. These are the same conditions obeyed by
the errexit (-e) option.
@@ -4857,9 +4889,9 @@ parameters, or to display the names and values of shell variables.
a list (*note Lists::), or a compound command (*note Compound
Commands::) returns a non-zero status. The shell does not
exit if the command that fails is part of the command list
immediately following a while or until keyword, part of
the test in an if statement, part of any command executed in
a && or || list except the command following the final
immediately following a while or until reserved word, part
of the test in an if statement, part of any command executed
in a && or || list except the command following the final
&& or ||, any command in a pipeline but the last (subject
to the state of the pipefail shell option), or if the
command's return status is being inverted with !. If a
@@ -7002,7 +7034,10 @@ link itself.
greater than or equal to ARG2, respectively. ARG1 and ARG2 may be
positive or negative integers. When used with the [[ command,
ARG1 and ARG2 are evaluated as arithmetic expressions (*note Shell
Arithmetic::).
Arithmetic::). Since the expansions the [[ command performs on
ARG1 and ARG2 can potentially result in empty strings, arithmetic
expression evaluation treats those as expressions that evaluate to
0.

File: bashref.info, Node: Shell Arithmetic, Next: Aliases, Prev: Bash Conditional Expressions, Up: Bash Features
@@ -7183,8 +7218,18 @@ expressions that must expand to an integer (*note Shell Arithmetic::))
and are zero-based; associative arrays use arbitrary strings. Unless
otherwise noted, indexed array indices must be non-negative integers.
An indexed array is created automatically if any variable is assigned
to using the syntax
The shell performs parameter and variable expansion, arithmetic
expansion, command substitution, and quote removal on indexed array
subscripts. Since this can potentially result in empty strings,
subscript indexing treats those as expressions that evaluate to 0.
The shell performs tilde expansion, parameter and variable expansion,
arithmetic expansion, command substitution, and quote removal on
associative array subscripts. Empty strings cannot be used as
associative array keys.
Bash automatically creates an indexed array if any variable is
assigned to using the syntax
NAME[SUBSCRIPT]=VALUE
The SUBSCRIPT is treated as an arithmetic expression that must evaluate
@@ -7759,7 +7804,7 @@ startup files.
double-quoted string, even if the histexpand option is enabled.
31. When printing shell function definitions (e.g., by type), Bash
does not print the function keyword unless necessary.
does not print the function reserved word unless necessary.
32. Non-interactive shells exit if a syntax error in an arithmetic
expansion results in an invalid expression.
@@ -7868,72 +7913,77 @@ startup files.
58. The kill builtin does not accept signal names with a SIG
prefix.
59. The printf builtin uses double (via strtod) to convert
59. The kill builtin returns a failure status if any of the pid or
job arguments are invalid or if sending the specified signal to any
of them fails. In default mode, kill returns success if the
signal was successfully sent to any of the specified processes.
60. 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.
60. The pwd builtin verifies that the value it prints is the same as
61. 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.
61. 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.
62. When the set builtin is invoked without options, it does not
63. When the set builtin is invoked without options, it does not
display shell function names and definitions.
63. When the set builtin is invoked without options, it displays
64. 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.
64. The test builtin compares strings using the current locale when
65. The test builtin compares strings using the current locale when
evaluating the < and > binary operators.
65. The test builtin's -t unary primary requires an argument.
66. The test builtin's -t unary primary requires an argument.
Historical versions of test made the argument optional in certain
cases, and Bash attempts to accommodate those for backwards
compatibility.
66. The trap builtin displays signal names without the leading
67. The trap builtin displays signal names without the leading
SIG.
67. The trap builtin doesn't check the first argument for a possible
68. 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.
68. trap -p without arguments displays signals whose dispositions
69. 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.
69. The type and command builtins will not report a non-executable
70. 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.
70. The ulimit builtin uses a block size of 512 bytes for the -c
71. The ulimit builtin uses a block size of 512 bytes for the -c
and -f options.
71. The unset builtin with the -v option specified returns a fatal
72. The unset builtin with the -v option specified returns a fatal
error if it attempts to unset a readonly or non-unsettable
variable, which causes a non-interactive shell to exit.
72. When asked to unset a variable that appears in an assignment
73. When asked to unset a variable that appears in an assignment
statement preceding the command, the unset builtin attempts to
unset a variable of the same name in the current or previous scope
as well. This implements the required "if an assigned variable is
further modified by the utility, the modifications made by the
utility shall persist" behavior.
73. The arrival of SIGCHLD when a trap is set on SIGCHLD does not
74. 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.
74. Bash removes an exited background process's status from the list
75. Bash removes an exited background process's status from the list
of such statuses after the wait builtin returns it.
There is other POSIX behavior that Bash does not implement by default
@@ -8159,19 +8209,22 @@ uses the JOB abstraction as the basis for job control.
To facilitate the implementation of the user interface to job
control, each process has a “process group ID”, and the operating system
maintains the notion of a current terminal process group ID. Processes
that have the same process group ID are said to be part of the same
“process group”. Members of the foreground process group (processes
whose process group ID is equal to the current terminal process group
ID) receive keyboard-generated signals such as SIGINT. Processes in
the foreground process group are said to be foreground processes.
Background processes are those whose process group ID differs from the
terminal's; such processes are immune to keyboard-generated signals.
Only foreground processes are allowed to read from or, if the user so
specifies with stty tostop, write to the terminal. Background
processes which attempt to read from (write to when tostop is in
effect) the terminal are sent a SIGTTIN (SIGTTOU) signal by the
kernel's terminal driver, which, unless caught, suspends the process.
maintains the notion of a current terminal process group ID. This
terminal process group ID is associated with the “controlling terminal”.
Processes that have the same process group ID are said to be part of
the same “process group”. Members of the foreground process group
(processes whose process group ID is equal to the current terminal
process group ID) receive keyboard-generated signals such as SIGINT.
Processes in the foreground process group are said to be foreground
processes. Background processes are those whose process group ID
differs from the controlling terminal's; such processes are immune to
keyboard-generated signals. Only foreground processes are allowed to
read from or, if the user so specifies with stty tostop, write to the
controlling terminal. The system sends a SIGTTIN (SIGTTOU) signal
to background processes which attempt to read from (write to when
tostop is in effect) the terminal, which, unless caught, suspends the
process.
If the operating system on which Bash is running supports job
control, Bash contains facilities to use it. Typing the “suspend”
@@ -9561,7 +9614,8 @@ File: bashref.info, Node: Commands For Moving, Next: Commands For History, Up
clear-screen (C-l)
Clear the screen, then redraw the current line, leaving the current
line at the top of the screen.
line at the top of the screen. If given a numeric argument, this
refreshes the current line without clearing the screen.
redraw-current-line ()
Refresh the current line. By default, this is unbound.
@@ -11891,8 +11945,8 @@ historical Bourne shell) as the baseline reference.
• Bash implements command aliases and the alias and unalias
builtins (*note Aliases::).
• Bash implements the ! keyword to negate the return value of a
pipeline (*note Pipelines::). This is very useful when an if
• Bash implements the ! reserved word to negate the return value of
a pipeline (*note Pipelines::). This is very useful when an if
statement needs to act only if a test fails. The Bash -o
pipefail option to set will cause a pipeline to return a failure
status if any command fails (*note The Set Builtin::).
@@ -12877,9 +12931,9 @@ D.2 Index of Shell Reserved Words
* !: Pipelines. (line 9)
* [[: Conditional Constructs.
(line 126)
(line 128)
* ]]: Conditional Constructs.
(line 126)
(line 128)
* {: Command Grouping. (line 21)
* }: Command Grouping. (line 21)
* case: Conditional Constructs.
@@ -13322,7 +13376,7 @@ D.4 Function Index
* quoted-insert (C-q or C-v): Commands For Text. (line 28)
* re-read-init-file (C-x C-r): Miscellaneous Commands.
(line 6)
* redraw-current-line (): Commands For Moving. (line 61)
* redraw-current-line (): Commands For Moving. (line 62)
* reverse-search-history (C-r): Commands For History.
(line 29)
* revert-line (M-r): Miscellaneous Commands.
@@ -13545,138 +13599,138 @@ D.5 Concept Index

Tag Table:
Node: Top900
Node: Introduction2840
Node: What is Bash?3056
Node: What is a shell?4192
Node: Definitions6805
Node: Basic Shell Features10135
Node: Shell Syntax11362
Node: Shell Operation12392
Node: Quoting13686
Node: Escape Character15027
Node: Single Quotes15565
Node: Double Quotes15917
Node: ANSI-C Quoting17265
Node: Locale Translation18662
Node: Creating Internationalized Scripts20068
Node: Comments24269
Node: Shell Commands25039
Node: Reserved Words25981
Node: Simple Commands26849
Node: Pipelines27514
Node: Lists30773
Node: Compound Commands32648
Node: Looping Constructs33660
Node: Conditional Constructs36182
Node: Command Grouping51121
Node: Coprocesses52616
Node: GNU Parallel55305
Node: Shell Functions56226
Node: Shell Parameters64677
Node: Positional Parameters69582
Node: Special Parameters70675
Node: Shell Expansions74139
Node: Brace Expansion76331
Node: Tilde Expansion79680
Node: Shell Parameter Expansion82638
Node: Command Substitution102449
Node: Arithmetic Expansion105981
Node: Process Substitution106998
Node: Word Splitting108109
Node: Filename Expansion110556
Node: Pattern Matching113783
Node: Quote Removal119509
Node: Redirections119816
Node: Executing Commands130082
Node: Simple Command Expansion130752
Node: Command Search and Execution132863
Node: Command Execution Environment135310
Node: Environment138761
Node: Exit Status140667
Node: Signals142728
Node: Shell Scripts147660
Node: Shell Builtin Commands150961
Node: Bourne Shell Builtins153075
Node: Bash Builtins179642
Node: Modifying Shell Behavior216569
Node: The Set Builtin216914
Node: The Shopt Builtin228905
Node: Special Builtins245960
Node: Shell Variables246952
Node: Bourne Shell Variables247389
Node: Bash Variables249900
Node: Bash Features288808
Node: Invoking Bash289825
Node: Bash Startup Files296412
Node: Interactive Shells301657
Node: What is an Interactive Shell?302068
Node: Is this Shell Interactive?302733
Node: Interactive Shell Behavior303560
Node: Bash Conditional Expressions307324
Node: Shell Arithmetic312538
Node: Aliases315870
Node: Arrays319007
Node: The Directory Stack326102
Node: Directory Stack Builtins326902
Node: Controlling the Prompt331350
Node: The Restricted Shell334238
Node: Bash POSIX Mode337123
Node: Shell Compatibility Mode355187
Node: Job Control364197
Node: Job Control Basics364657
Node: Job Control Builtins370938
Node: Job Control Variables377623
Node: Command Line Editing378857
Node: Introduction and Notation380563
Node: Readline Interaction382918
Node: Readline Bare Essentials384109
Node: Readline Movement Commands385920
Node: Readline Killing Commands386919
Node: Readline Arguments388945
Node: Searching390005
Node: Readline Init File392251
Node: Readline Init File Syntax393557
Node: Conditional Init Constructs420385
Node: Sample Init File424773
Node: Bindable Readline Commands427896
Node: Commands For Moving429437
Node: Commands For History431808
Node: Commands For Text437201
Node: Commands For Killing441329
Node: Numeric Arguments444120
Node: Commands For Completion445275
Node: Keyboard Macros450974
Node: Miscellaneous Commands451678
Node: Readline vi Mode458248
Node: Programmable Completion459228
Node: Programmable Completion Builtins467968
Node: A Programmable Completion Example479708
Node: Using History Interactively485056
Node: Bash History Facilities485740
Node: Bash History Builtins489478
Node: History Interaction495952
Node: Event Designators500905
Node: Word Designators502486
Node: Modifiers504881
Node: Installing Bash506821
Node: Basic Installation507940
Node: Compilers and Options511819
Node: Compiling For Multiple Architectures512572
Node: Installation Names514328
Node: Specifying the System Type516565
Node: Sharing Defaults517314
Node: Operation Controls518031
Node: Optional Features519053
Node: Reporting Bugs531436
Node: Major Differences From The Bourne Shell532796
Node: GNU Free Documentation License554219
Node: Indexes579399
Node: Builtin Index579853
Node: Reserved Word Index586954
Node: Variable Index589402
Node: Function Index606818
Node: Concept Index620816
Node: Top904
Node: Introduction2848
Node: What is Bash?3064
Node: What is a shell?4200
Node: Definitions6813
Node: Basic Shell Features10143
Node: Shell Syntax11370
Node: Shell Operation12400
Node: Quoting13694
Node: Escape Character15035
Node: Single Quotes15573
Node: Double Quotes15925
Node: ANSI-C Quoting17273
Node: Locale Translation18670
Node: Creating Internationalized Scripts20076
Node: Comments24277
Node: Shell Commands25047
Node: Reserved Words25989
Node: Simple Commands26857
Node: Pipelines27522
Node: Lists30781
Node: Compound Commands32656
Node: Looping Constructs33668
Node: Conditional Constructs36190
Node: Command Grouping51263
Node: Coprocesses52758
Node: GNU Parallel55447
Node: Shell Functions56368
Node: Shell Parameters64819
Node: Positional Parameters69723
Node: Special Parameters70816
Node: Shell Expansions74280
Node: Brace Expansion76472
Node: Tilde Expansion79813
Node: Shell Parameter Expansion82771
Node: Command Substitution103417
Node: Arithmetic Expansion106949
Node: Process Substitution108128
Node: Word Splitting109239
Node: Filename Expansion111686
Node: Pattern Matching114913
Node: Quote Removal120639
Node: Redirections120946
Node: Executing Commands131212
Node: Simple Command Expansion131882
Node: Command Search and Execution133993
Node: Command Execution Environment136440
Node: Environment139891
Node: Exit Status141797
Node: Signals143858
Node: Shell Scripts148790
Node: Shell Builtin Commands152091
Node: Bourne Shell Builtins154205
Node: Bash Builtins180778
Node: Modifying Shell Behavior217705
Node: The Set Builtin218050
Node: The Shopt Builtin230047
Node: Special Builtins247102
Node: Shell Variables248094
Node: Bourne Shell Variables248531
Node: Bash Variables251042
Node: Bash Features289950
Node: Invoking Bash290967
Node: Bash Startup Files297554
Node: Interactive Shells302799
Node: What is an Interactive Shell?303210
Node: Is this Shell Interactive?303875
Node: Interactive Shell Behavior304702
Node: Bash Conditional Expressions308466
Node: Shell Arithmetic313886
Node: Aliases317218
Node: Arrays320355
Node: The Directory Stack327946
Node: Directory Stack Builtins328746
Node: Controlling the Prompt333194
Node: The Restricted Shell336082
Node: Bash POSIX Mode338967
Node: Shell Compatibility Mode357327
Node: Job Control366337
Node: Job Control Basics366797
Node: Job Control Builtins373168
Node: Job Control Variables379853
Node: Command Line Editing381087
Node: Introduction and Notation382793
Node: Readline Interaction385148
Node: Readline Bare Essentials386339
Node: Readline Movement Commands388150
Node: Readline Killing Commands389149
Node: Readline Arguments391175
Node: Searching392235
Node: Readline Init File394481
Node: Readline Init File Syntax395787
Node: Conditional Init Constructs422615
Node: Sample Init File427003
Node: Bindable Readline Commands430126
Node: Commands For Moving431667
Node: Commands For History434134
Node: Commands For Text439527
Node: Commands For Killing443655
Node: Numeric Arguments446446
Node: Commands For Completion447601
Node: Keyboard Macros453300
Node: Miscellaneous Commands454004
Node: Readline vi Mode460574
Node: Programmable Completion461554
Node: Programmable Completion Builtins470294
Node: A Programmable Completion Example482034
Node: Using History Interactively487382
Node: Bash History Facilities488066
Node: Bash History Builtins491804
Node: History Interaction498278
Node: Event Designators503231
Node: Word Designators504812
Node: Modifiers507207
Node: Installing Bash509147
Node: Basic Installation510266
Node: Compilers and Options514145
Node: Compiling For Multiple Architectures514898
Node: Installation Names516654
Node: Specifying the System Type518891
Node: Sharing Defaults519640
Node: Operation Controls520357
Node: Optional Features521379
Node: Reporting Bugs533762
Node: Major Differences From The Bourne Shell535122
Node: GNU Free Documentation License556551
Node: Indexes581731
Node: Builtin Index582185
Node: Reserved Word Index589286
Node: Variable Index591734
Node: Function Index609150
Node: Concept Index623148

End Tag Table