experimental change to use groff instead of man2html for HTML man pages; man page updates for reserved words; fix for pattern matching bracket expression ranges; readline changes to disallow defining some recursive keyboard macros

This commit is contained in:
Chet Ramey
2025-09-18 17:26:51 -04:00
parent a451bfc3f5
commit b88cd1c366
24 changed files with 18920 additions and 19320 deletions
+104 -87
View File
@@ -4,9 +4,9 @@
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<!-- This text is a brief description of the features that are present in
the Bash shell (version 5.3, 7 August 2025).
the Bash shell (version 5.3, 6 September 2025).
This is Edition 5.3, last updated 7 August 2025,
This is Edition 5.3, last updated 6 September 2025,
of The GNU Bash Reference Manual,
for Bash, Version 5.3.
@@ -77,10 +77,10 @@ Next: <a href="#Introduction" accesskey="n" rel="next">Introduction</a>, Previou
<h1 class="top" id="Bash-Features-1"><span>Bash Features<a class="copiable-link" href="#Bash-Features-1"> &para;</a></span></h1>
<p>This text is a brief description of the features that are present in
the Bash shell (version 5.3, 7 August 2025).
the Bash shell (version 5.3, 6 September 2025).
The Bash home page is <a class="url" href="http://www.gnu.org/software/bash/">http://www.gnu.org/software/bash/</a>.
</p>
<p>This is Edition 5.3, last updated 7 August 2025,
<p>This is Edition 5.3, last updated 6 September 2025,
of <cite class="cite">The GNU Bash Reference Manual</cite>,
for <code class="code">Bash</code>, Version 5.3.
</p>
@@ -552,9 +552,9 @@ 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 <small class="sc">POSIX</small>
specification for the &lsquo;standard&rsquo; Unix shell.
specification for the &ldquo;standard&rdquo; Unix shell.
</p>
<p>This chapter briefly summarizes the shell&rsquo;s &lsquo;building blocks&rsquo;:
<p>This chapter briefly summarizes the shell&rsquo;s &ldquo;building blocks&rdquo;:
commands, control structures, shell functions, shell <i class="i">parameters</i>,
shell expansions,
<i class="i">redirections</i>, which are a way to direct input and output from
@@ -1033,8 +1033,23 @@ Next: <a href="#Simple-Commands" accesskey="n" rel="next">Simple Commands</a>, U
<p>Reserved words are words that have special meaning to the shell.
They are used to begin and end the shell&rsquo;s compound commands.
</p>
<p>The following words are recognized as reserved when unquoted and
the first word of a command (see below for exceptions):
<p>Reserved words are recognized as reserved when unquoted and either
</p>
<ul class="itemize mark-bullet">
<li>the first word of a command;
</li><li>the first word following a reserved word
other than <code class="code">case</code>, <code class="code">for</code>, <code class="code">select</code>, or <code class="code">in</code>;
</li><li>the third word of a <code class="code">case</code> command
(only <code class="code">in</code> is valid);
</li><li>the third word of a <code class="code">for</code> or <code class="code">select</code>
command (only <code class="code">in</code> and <code class="code">do</code> are valid);
</li><li>following a control operator.
</li></ul>
<p>The shell will also recognize reserved words where the syntax of a command
specifically requires the reserved word as the only correct token.
</p>
<p>The following are reserved words:
</p>
<table class="multitable">
<tbody><tr><td width="10%"><code class="code">if</code></td><td width="10%"><code class="code">then</code></td><td width="10%"><code class="code">elif</code></td><td width="10%"><code class="code">else</code></td><td width="12%"><code class="code">fi</code></td><td width="10%"><code class="code">time</code></td></tr>
@@ -1044,11 +1059,6 @@ the first word of a command (see below for exceptions):
</tbody>
</table>
<p><code class="code">in</code> is recognized as a reserved word if it is the third word of a
<code class="code">case</code> or <code class="code">select</code> command.
<code class="code">in</code> and <code class="code">do</code> are recognized as reserved
words if they are the third word in a <code class="code">for</code> command.
</p>
<hr>
</div>
<div class="subsection-level-extent" id="Simple-Commands">
@@ -1166,10 +1176,37 @@ Next: <a href="#Compound-Commands" accesskey="n" rel="next">Compound Commands</a
<h4 class="subsection" id="Lists-of-Commands"><span>3.2.4 Lists of Commands<a class="copiable-link" href="#Lists-of-Commands"> &para;</a></span></h4>
<a class="index-entry-id" id="index-commands_002c-lists"></a>
<p>A <code class="code">list</code> is a sequence of one or more pipelines separated by one
of the operators &lsquo;<samp class="samp">;</samp>&rsquo;, &lsquo;<samp class="samp">&amp;</samp>&rsquo;, &lsquo;<samp class="samp">&amp;&amp;</samp>&rsquo;, or &lsquo;<samp class="samp">||</samp>&rsquo;,
and optionally terminated by one of &lsquo;<samp class="samp">;</samp>&rsquo;, &lsquo;<samp class="samp">&amp;</samp>&rsquo;, or a
<code class="code">newline</code>.
<p>A <code class="code">list</code> is a sequence of one or more <small class="sc">AND</small> or <small class="sc">OR</small> lists
separated by one of the operators
&lsquo;<samp class="samp">;</samp>&rsquo; or &lsquo;<samp class="samp">&amp;</samp>&rsquo;, or a <code class="code">newline</code>,
and optionally terminated by one of those three characters.
</p>
<p><small class="sc">AND</small> and <small class="sc">OR</small> lists are sequences of one or more pipelines
separated by the control operators &lsquo;<samp class="samp">&amp;&amp;</samp>&rsquo; and &lsquo;<samp class="samp">||</samp>&rsquo;,
respectively.
<small class="sc">AND</small> and <small class="sc">OR</small> lists are executed with left associativity.
</p>
<p>An <small class="sc">AND</small> list has the form
</p>
<div class="example">
<pre class="example-preformatted"><var class="var">command1</var> &amp;&amp; <var class="var">command2</var>
</pre></div>
<p><var class="var">command2</var> is executed if, and only if, <var class="var">command1</var>
returns an exit status of zero (success).
</p>
<p>An <small class="sc">OR</small> list has the form
</p>
<div class="example">
<pre class="example-preformatted"><var class="var">command1</var> || <var class="var">command2</var>
</pre></div>
<p><var class="var">command2</var> is executed if, and only if, <var class="var">command1</var>
returns a non-zero exit status.
</p>
<p>The return status of
<small class="sc">AND</small> and <small class="sc">OR</small> lists is the exit status of the last command
executed in the list.
</p>
<p>Of these list operators, &lsquo;<samp class="samp">&amp;&amp;</samp>&rsquo; and &lsquo;<samp class="samp">||</samp>&rsquo;
have equal precedence, followed by &lsquo;<samp class="samp">;</samp>&rsquo; and &lsquo;<samp class="samp">&amp;</samp>&rsquo;,
@@ -1188,34 +1225,12 @@ When job control is not active (see <a class="pxref" href="#Job-Control">Job Con
the standard input for asynchronous commands, in the absence of any
explicit redirections, is redirected from <code class="code">/dev/null</code>.
</p>
<p>Commands separated by a &lsquo;<samp class="samp">;</samp>&rsquo; are executed sequentially; the shell
waits for each command to terminate in turn.
The return status is the exit status of the last command executed.
<p>Commands separated or terminated by
&lsquo;<samp class="samp">;</samp>&rsquo; (or equivalent <code class="code">newline</code>)
are executed sequentially; the shell waits for each
command to terminate in turn.
</p>
<p><small class="sc">AND</small> and <small class="sc">OR</small> lists are sequences of one or more pipelines
separated by the control operators &lsquo;<samp class="samp">&amp;&amp;</samp>&rsquo; and &lsquo;<samp class="samp">||</samp>&rsquo;,
respectively.
<small class="sc">AND</small> and <small class="sc">OR</small> lists are executed with left associativity.
</p>
<p>An <small class="sc">AND</small> list has the form
</p><div class="example">
<pre class="example-preformatted"><var class="var">command1</var> &amp;&amp; <var class="var">command2</var>
</pre></div>
<p><var class="var">command2</var> is executed if, and only if, <var class="var">command1</var>
returns an exit status of zero (success).
</p>
<p>An <small class="sc">OR</small> list has the form
</p><div class="example">
<pre class="example-preformatted"><var class="var">command1</var> || <var class="var">command2</var>
</pre></div>
<p><var class="var">command2</var> is executed if, and only if, <var class="var">command1</var>
returns a non-zero exit status.
</p>
<p>The return status of
<small class="sc">AND</small> and <small class="sc">OR</small> lists is the exit status of the last command
executed in the list.
<p>The return status of a list is the exit status of the last command executed.
</p>
<hr>
</div>
@@ -1387,26 +1402,24 @@ the first <var class="var">pattern</var> that matches <var class="var">word</var
proceeding from the first pattern to the last.
The match is performed according
to the rules described below in <a class="ref" href="#Pattern-Matching">Pattern Matching</a>.
If the <code class="code">nocasematch</code> shell option
(see the description of <code class="code">shopt</code> in <a class="ref" href="#The-Shopt-Builtin">The Shopt Builtin</a>)
is enabled, the match is performed without regard to the case
of alphabetic characters.
The &lsquo;<samp class="samp">|</samp>&rsquo; is used to separate multiple patterns in a pattern list,
and the &lsquo;<samp class="samp">)</samp>&rsquo; operator terminates the pattern list.
A pattern list and an associated <var class="var">command-list</var> is known
as a <var class="var">clause</var>.
</p>
<p>Each clause must be terminated with &lsquo;<samp class="samp">;;</samp>&rsquo;, &lsquo;<samp class="samp">;&amp;</samp>&rsquo;, or &lsquo;<samp class="samp">;;&amp;</samp>&rsquo;.
The <var class="var">word</var> undergoes tilde expansion, parameter expansion, command
substitution, process substitution, arithmetic expansion, and quote removal
(see <a class="pxref" href="#Shell-Parameter-Expansion">Shell Parameter Expansion</a>)
before the shell attempts to match the pattern.
Each <var class="var">pattern</var> undergoes tilde expansion, parameter expansion,
Each <var class="var">pattern</var> examined undergoes tilde expansion, parameter expansion,
command substitution, arithmetic expansion, process substitution, and
quote removal.
If the <code class="code">nocasematch</code> shell option
(see the description of <code class="code">shopt</code> in <a class="ref" href="#The-Shopt-Builtin">The Shopt Builtin</a>)
is enabled, the match is performed without regard to the case
of alphabetic characters.
</p>
<p>There may be an arbitrary number of <code class="code">case</code> clauses, each terminated
by a &lsquo;<samp class="samp">;;</samp>&rsquo;, &lsquo;<samp class="samp">;&amp;</samp>&rsquo;, or &lsquo;<samp class="samp">;;&amp;</samp>&rsquo;.
<p>A pattern list is a set of one or more patterns separated by &lsquo;<samp class="samp">|</samp>&rsquo;,
and terminated by the &lsquo;<samp class="samp">)</samp>&rsquo; operator.
A case <var class="var">clause</var> is a pattern list and an associated <var class="var">command-list</var>,
terminated by &lsquo;<samp class="samp">;;</samp>&rsquo;, &lsquo;<samp class="samp">;&amp;</samp>&rsquo;, or &lsquo;<samp class="samp">;;&amp;</samp>&rsquo;.
The terminator is optional for the last clause preceding <code class="code">esac</code>.
There may be an arbitrary number of <code class="code">case</code> clauses.
The first pattern that matches determines the
command-list that is executed.
It&rsquo;s a common idiom to use &lsquo;<samp class="samp">*</samp>&rsquo; as the final pattern to define the
@@ -1428,11 +1441,13 @@ echo &quot; legs.&quot;
</pre></div>
<p>If the &lsquo;<samp class="samp">;;</samp>&rsquo; operator is used, the <code class="code">case</code> command completes
after the first pattern match.
Using &lsquo;<samp class="samp">;&amp;</samp>&rsquo; in place of &lsquo;<samp class="samp">;;</samp>&rsquo; causes execution to continue with
<p>When a match is found, <code class="code">case</code> executes
the corresponding <var class="var">command-list</var>.
If the &lsquo;<samp class="samp">;;</samp>&rsquo; operator terminates the case clause,
the <code class="code">case</code> command completes after the first pattern match.
Using the &lsquo;<samp class="samp">;&amp;</samp>&rsquo; terminator continues execution with
the <var class="var">command-list</var> associated with the next clause, if any.
Using &lsquo;<samp class="samp">;;&amp;</samp>&rsquo; in place of &lsquo;<samp class="samp">;;</samp>&rsquo; causes the shell to test the patterns
Using the &lsquo;<samp class="samp">;;&amp;</samp>&rsquo; terminator causes the shell to test the pattern list
in the next clause, if any, and execute any associated <var class="var">command-list</var>
if the match succeeds,
continuing the case statement execution as if the pattern list had not matched.
@@ -4011,14 +4026,14 @@ and &lsquo;<samp class="samp">\</samp>&rsquo; must be used to quote the characte
however, double quote characters have no special meaning.
</p>
<p>If the redirection operator is &lsquo;<samp class="samp">&lt;&lt;-</samp>&rsquo;,
the shell strips leading tab characters are stripped from input lines
the shell strips leading tab characters from input lines
and the line containing <var class="var">delimiter</var>.
This allows here-documents within shell scripts to be indented in a
natural fashion.
</p>
<p>If the delimiter is not quoted, the
<p>If the delimiter is not quoted, the shell treats the
<code class="code">\&lt;newline&gt;</code>
sequence is treated as a line continuation: the two lines are joined
sequence as a line continuation: the two lines are joined
and the backslash-newline is removed.
This happens while reading the here-document, before the check for
the ending delimiter, so joined lines can form the end delimiter.
@@ -10302,10 +10317,10 @@ command hash table, even if it returns it as a (last-ditch) result
from a <code class="env">$PATH</code> search.
</li><li> The message printed by the job control code and builtins when a job
exits with a non-zero status is &lsquo;Done(status)&rsquo;.
exits with a non-zero status is &ldquo;Done(status)&rdquo;.
</li><li> The message printed by the job control code and builtins when a job
is stopped is &lsquo;Stopped(<var class="var">signame</var>)&rsquo;, where <var class="var">signame</var> is, for
is stopped is &ldquo;Stopped(<var class="var">signame</var>)&rdquo;, where <var class="var">signame</var> is, for
example, <code class="code">SIGTSTP</code>.
</li><li> If the shell is interactive, Bash does not perform job notifications
@@ -11266,11 +11281,11 @@ Next: <a href="#Readline-Interaction" accesskey="n" rel="next">Readline Interact
<p>The following paragraphs use Emacs style to
describe the notation used to represent keystrokes.
</p>
<p>The text <kbd class="kbd">C-k</kbd> is read as &lsquo;Control-K&rsquo; and describes the character
<p>The text <kbd class="kbd">C-k</kbd> is read as &ldquo;Control-K&rdquo; and describes the character
produced when the <kbd class="key">k</kbd> key is pressed while the Control key
is depressed.
</p>
<p>The text <kbd class="kbd">M-k</kbd> is read as &lsquo;Meta-K&rsquo; and describes the character
<p>The text <kbd class="kbd">M-k</kbd> is read as &ldquo;Meta-K&rdquo; and describes the character
produced when the Meta key (if you have one) is depressed, and the <kbd class="key">k</kbd>
key is pressed (a <em class="dfn">meta character</em>), then both are released.
The Meta key is labeled <kbd class="key">ALT</kbd> or <kbd class="key">Option</kbd> on many keyboards.
@@ -11301,7 +11316,7 @@ you can make <kbd class="kbd">M-key</kbd> key bindings you specify
(see <code class="code">Key Bindings</code> in <a class="ref" href="#Readline-Init-File-Syntax">Readline Init File Syntax</a>)
do the same thing by setting the <code class="code">force-meta-prefix</code> variable.
</p>
<p>The text <kbd class="kbd">M-C-k</kbd> is read as &lsquo;Meta-Control-k&rsquo; and describes the
<p>The text <kbd class="kbd">M-C-k</kbd> is read as &ldquo;Meta-Control-k&rdquo; and describes the
character produced by metafying <kbd class="kbd">C-k</kbd>.
</p>
<p>In addition, several keys have their own names.
@@ -11370,10 +11385,10 @@ and then correct your mistake.
Afterwards, you can move the cursor to the right with <kbd class="kbd">C-f</kbd>.
</p>
<p>When you add text in the middle of a line, you will notice that characters
to the right of the cursor are &lsquo;pushed over&rsquo; to make room for the text
to the right of the cursor are &ldquo;pushed over&rdquo; to make room for the text
that you have inserted.
Likewise, when you delete text behind the cursor,
characters to the right of the cursor are &lsquo;pulled back&rsquo; to fill in the
characters to the right of the cursor are &ldquo;pulled back&rdquo; to fill in the
blank space created by the removal of the text.
These are the bare
essentials for editing the text of an input line:
@@ -11458,9 +11473,9 @@ Next: <a href="#Readline-Arguments" accesskey="n" rel="next">Readline Arguments<
<p><em class="dfn">Killing</em> text means to delete the text from the line, but to save
it away for later use, usually by <em class="dfn">yanking</em> (re-inserting)
it back into the line.
(&lsquo;Cut&rsquo; and &lsquo;paste&rsquo; are more recent jargon for &lsquo;kill&rsquo; and &lsquo;yank&rsquo;.)
(&ldquo;Cut&rdquo; and &ldquo;paste&rdquo; are more recent jargon for &ldquo;kill&rdquo; and &ldquo;yank&rdquo;.)
</p>
<p>If the description for a command says that it &lsquo;kills&rsquo; text, then you can
<p>If the description for a command says that it &ldquo;kills&rdquo; text, then you can
be sure that you can get the text back in a different (or the same)
place later.
</p>
@@ -11533,9 +11548,10 @@ act in a backward direction.
For example, to kill text back to the
start of the line, you might type &lsquo;<samp class="samp">M-- C-k</samp>&rsquo;.
</p>
<p>The general way to pass numeric arguments to a command is to type meta
digits before the command.
If the first &lsquo;digit&rsquo; typed is a minus
<p>The general way to pass numeric arguments to a command is to type
the Meta key and then digits (&ldquo;meta digits&rdquo;)
before the command.
If the first &ldquo;digit&rdquo; typed is a minus
sign (&lsquo;<samp class="samp">-</samp>&rsquo;), then the sign of the argument will be negative.
Once you have typed one meta digit to get the argument started, you can
type the remainder of the digits, and then the command.
@@ -12709,12 +12725,12 @@ to its original state.
</p>
</dd>
<dt><a id="index-previous_002dhistory-_0028C_002dp_0029"></a><span><code class="code">previous-history (C-p)</code><a class="copiable-link" href="#index-previous_002dhistory-_0028C_002dp_0029"> &para;</a></span></dt>
<dd><p>Move &lsquo;back&rsquo; through the history list, fetching the previous command.
<dd><p>Move &ldquo;back&rdquo; through the history list, fetching the previous command.
This may also be bound to the up arrow key on some keyboards.
</p>
</dd>
<dt><a id="index-next_002dhistory-_0028C_002dn_0029"></a><span><code class="code">next-history (C-n)</code><a class="copiable-link" href="#index-next_002dhistory-_0028C_002dn_0029"> &para;</a></span></dt>
<dd><p>Move &lsquo;forward&rsquo; through the history list, fetching the next command.
<dd><p>Move &ldquo;forward&rdquo; through the history list, fetching the next command.
This may also be bound to the down arrow key on some keyboards.
</p>
</dd>
@@ -12728,28 +12744,29 @@ being entered.
</p>
</dd>
<dt><a id="index-reverse_002dsearch_002dhistory-_0028C_002dr_0029"></a><span><code class="code">reverse-search-history (C-r)</code><a class="copiable-link" href="#index-reverse_002dsearch_002dhistory-_0028C_002dr_0029"> &para;</a></span></dt>
<dd><p>Search backward starting at the current line and moving &lsquo;up&rsquo; through
<dd><p>Search backward starting at the current line and moving &ldquo;up&rdquo; through
the history as necessary.
This is an incremental search.
This command sets the region to the matched text and activates the region.
</p>
</dd>
<dt><a id="index-forward_002dsearch_002dhistory-_0028C_002ds_0029"></a><span><code class="code">forward-search-history (C-s)</code><a class="copiable-link" href="#index-forward_002dsearch_002dhistory-_0028C_002ds_0029"> &para;</a></span></dt>
<dd><p>Search forward starting at the current line and moving &lsquo;down&rsquo; through
<dd><p>Search forward starting at the current line and moving &ldquo;down&rdquo; through
the history as necessary.
This is an incremental search.
This command sets the region to the matched text and activates the region.
</p>
</dd>
<dt><a id="index-non_002dincremental_002dreverse_002dsearch_002dhistory-_0028M_002dp_0029"></a><span><code class="code">non-incremental-reverse-search-history (M-p)</code><a class="copiable-link" href="#index-non_002dincremental_002dreverse_002dsearch_002dhistory-_0028M_002dp_0029"> &para;</a></span></dt>
<dd><p>Search backward starting at the current line and moving &lsquo;up&rsquo;
through the history as necessary using a non-incremental search
<dd><p>Search backward starting at the current line and moving &ldquo;up&rdquo;
</p>
<p>through the history as necessary using a non-incremental search
for a string supplied by the user.
The search string may match anywhere in a history line.
</p>
</dd>
<dt><a id="index-non_002dincremental_002dforward_002dsearch_002dhistory-_0028M_002dn_0029"></a><span><code class="code">non-incremental-forward-search-history (M-n)</code><a class="copiable-link" href="#index-non_002dincremental_002dforward_002dsearch_002dhistory-_0028M_002dn_0029"> &para;</a></span></dt>
<dd><p>Search forward starting at the current line and moving &lsquo;down&rsquo;
<dd><p>Search forward starting at the current line and moving &ldquo;down&rdquo;
through the history as necessary using a non-incremental search
for a string supplied by the user.
The search string may match anywhere in a history line.
@@ -13519,8 +13536,8 @@ editing modes,
The Readline default is <code class="code">emacs</code> mode.
</p>
<p>When you enter a line in <code class="code">vi</code> mode, you are already placed in
&lsquo;insertion&rsquo; mode, as if you had typed an &lsquo;<samp class="samp">i</samp>&rsquo;. Pressing <kbd class="key">ESC</kbd>
switches you into &lsquo;command&rsquo; mode, where you can edit the text of the
&ldquo;insertion&rdquo; mode, as if you had typed an &lsquo;<samp class="samp">i</samp>&rsquo;. Pressing <kbd class="key">ESC</kbd>
switches you into &ldquo;command&rdquo; mode, where you can edit the text of the
line with the standard <code class="code">vi</code> movement keys, move to previous
history lines with &lsquo;<samp class="samp">k</samp>&rsquo; and subsequent lines with &lsquo;<samp class="samp">j</samp>&rsquo;, and
so forth.
@@ -15645,7 +15662,7 @@ The latest released version of Bash is always available for FTP from
<code class="code">bashbug</code> command to submit a bug report or use the form at the
<a class="uref" href="https://savannah.gnu.org/projects/bash/">Bash project page</a>.
If you have a fix, you are encouraged to submit that as well!
Suggestions and &lsquo;philosophical&rsquo; bug reports may be mailed
Suggestions and &ldquo;philosophical&rdquo; bug reports may be mailed
to <a class="email" href="mailto:bug-bash@gnu.org">bug-bash@gnu.org</a> or <a class="email" href="mailto:help-bash@gnu.org">help-bash@gnu.org</a>.
</p>
<p>All bug reports should include:
@@ -15654,7 +15671,7 @@ to <a class="email" href="mailto:bug-bash@gnu.org">bug-bash@gnu.org</a> or <a cl
</li><li>The hardware and operating system.
</li><li>The compiler used to compile Bash.
</li><li>A description of the bug behavior.
</li><li>A short script or &lsquo;recipe&rsquo; which exercises the bug and may be used
</li><li>A short script or &ldquo;recipe&rdquo; which exercises the bug and may be used
to reproduce it.
</li></ul>