Break lines in the same places for ease of diffing and maintenance. Parallelize/copy material to align the documents more closely.
Favor man(7) font selection/alternation macros over roff(7) font
selection escape sequences.
Protect more literals from hyphenation.
Quote the `+=` operator in the man page as it is in Texinfo.
Write "key-value pairs" with a plain hyphen, not a minus sign.
---
doc/bash.1 | 427 +++++++++++++++++++++++++------------
doc/bashref.texi | 538 +++++++++++++++++++++++++++++++++--------------
2 files changed, 678 insertions(+), 287 deletions(-)
diff --git a/doc/bash.1 b/doc/bash.1
index e7a3ae9e..5811e2ce 100644
--- a/doc/bash.1
+++ b/doc/bash.1
@@ -286,42 +286,58 @@ .SH OPTIONS
.B bash
on the standard output and exit successfully.
.SH ARGUMENTS
-If arguments remain after option processing, and neither the
+If arguments remain after option processing,
+and neither the
.B \-c
nor the
.B \-s
-option has been supplied, the first argument is assumed to
-be the name of a file containing shell commands (a \fIshell script\fP).
-If
+option has been supplied,
+the first argument is assumed to be the name of a file
+containing shell commands
+(a
+.IR "shell script" ).
+When
.B bash
is invoked in this fashion,
.B $0
-is set to the name of the file, and the positional parameters
-are set to the remaining arguments.
+is set to the name of the file,
+and the positional parameters are set to the remaining arguments.
.B Bash
reads and executes commands from this file, then exits.
-\fBBash\fP's exit status is the exit status of the last command
-executed in the script.
-If no commands are executed, the exit status is 0.
-Bash first attempts to open the file in the current directory, and,
-if no file is found, then searches the directories in
+.BR Bash 's
+exit status is the exit status of the last command executed
+in the script.
+If no commands are executed,
+the exit status is 0.
+.B Bash
+first attempts to open the file in the current directory,
+and,
+if no file is found,
+then searches the directories in
.SM
.B PATH
for the script.
.SH INVOCATION
-A \fIlogin shell\fP is one whose first character of argument zero is a
+A
+.I "login shell"
+is one whose first character of argument zero is a
.BR \- ,
or one started with the
.B \-\-login
option.
.PP
-An \fIinteractive\fP shell is one started without non-option arguments
-(unless \fB\-s\fP is specified)
-and without the
+An
+.I interactive
+shell is one started without non-option arguments
+(unless
+.B \-s
+is specified),
+without specifying the
.B \-c
option,
-whose standard input and standard error are
-both connected to terminals (as determined by
+and whose standard input and standard error
+are both connected to terminals
+(as determined by
.IR isatty (3)),
or one started with the
.B \-i
@@ -420,33 +436,40 @@ .SH INVOCATION
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
+.IP
+When invoked as an interactive login shell,
+or a non-interactive shell with the
+.B \%\-\-login
+option,
+it first attempts to read and execute commands from
.FN /etc/profile
and
.FN \*~/.profile ,
in that order.
The
-.B \-\-noprofile
+.B \%\-\-noprofile
option inhibits this behavior.
+.IP
When invoked as an interactive shell with the name
.BR sh ,
.B bash
looks for the variable
.SM
.BR ENV ,
-expands its value if it is defined, and uses the
-expanded value as the name of a file to read and execute.
+expands its value if it is defined,
+and uses the expanded value as the name of a file to read and execute.
Since a shell invoked as
.B sh
does not attempt to read and execute commands from any other startup
-files, the
+files,
+the
.B \-\-rcfile
option has no effect.
+.IP
A non-interactive shell invoked with the name
.B sh
does not attempt to read any other startup files.
+.IP
When invoked as
.BR sh ,
.B bash
@@ -1204,7 +1227,8 @@ .SH QUOTING
(see
.SM
.B "HISTORY EXPANSION"
-below), the
+below),
+the
\fIhistory expansion\fP character, usually \fB!\fP, must be quoted
to prevent history expansion.
.PP
@@ -1268,8 +1292,8 @@ .SH QUOTING
.B *
and
.B @
-have special meaning when in double
-quotes (see
+have special meaning when in double quotes
+(see
.SM
.B PARAMETERS
below).
@@ -1440,27 +1464,44 @@ .SH PARAMETERS
assignment statement properties.
.PP
In the context where an assignment statement is assigning a value
-to a shell variable or array index,
-the += operator appends to or adds to
-the variable's previous value.
-This includes arguments to \fIdeclaration\fP commands such as
-\fBdeclare\fP that accept assignment statements.
-When += is applied to a variable
-for which the \fBinteger\fP attribute has been set,
-the variable's current value and \fIvalue\fP are each evaluated as
-arithmetic expressions,
-and the sum of the results is assigned as the variable's value.
-The current value is usually an integer constant, but may be an expression.
-When += is applied to an array variable using compound assignment
+to a shell variable or array index
(see
.B Arrays
below), the
-variable's value is not unset (as it is when using =), and new
-values are appended to the array beginning at one greater than the array's
-maximum index (for indexed arrays) or added as additional key\-value pairs
-in an associative array.
-When applied to a string-valued variable, \fIvalue\fP is expanded and
-appended to the variable's value.
+the
+.Q +=
+operator appends to or adds to the variable's previous value.
+This includes arguments to declaration commands such as
+.B \%declare
+that accept assignment statements.
+When
+.Q +=
+is applied to a variable
+for which the
+.B \%integer
+attribute has been set,
+the variable's current value and
+.I value
+are each evaluated as arithmetic expressions,
+and the sum of the results is assigned as the variable's value.
+The current value is usually an integer constant,
+but may be an expression.
+When
+.Q +=
+is applied to an array variable using compound assignment
+(see
+.B Arrays
+below),
+the variable's value is not unset
+(as it is when using
+.Q = ),
+and new values are appended to the array
+beginning at one greater than the array's maximum index
+(for indexed arrays),
+or added as additional key-value pairs in an associative array.
+When applied to a string-valued variable,
+.I value
+is expanded and appended to the variable's value.
.PP
A variable can be assigned the \fInameref\fP attribute using the
\fB\-n\fP option to the \fBdeclare\fP or \fBlocal\fP builtin commands
@@ -2198,7 +2239,8 @@ .SS "Shell Variables"
command.
.TP
.B RANDOM
-Each time this parameter is referenced, it expands to a random integer
+Each time this parameter is referenced,
+it expands to a random integer
between 0 and 32767.
Assigning a value to
.SM
@@ -2213,7 +2255,9 @@ .SS "Shell Variables"
subsequently reset.
.TP
.B READLINE_ARGUMENT
-Any numeric argument given to a \fBreadline\fP command that was defined using
+Any numeric argument given to a
+.B \%readline
+command that was defined using
.Q "bind \-x"
(see
.SM
@@ -2241,7 +2285,8 @@ .SS "Shell Variables"
.B "SHELL BUILTIN COMMANDS"
below).
The characters between the insertion point and the mark are often
-called the \fIregion\fP.
+called the
+.IR region .
.TP
.B READLINE_POINT
The position of the insertion point in the
@@ -2413,9 +2458,8 @@ .SS "Shell Variables"
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
.SM POSIX\c
--mandated
-minimum, and there is a maximum value (currently 8192) that this may
-not exceed.
+-mandated minimum,
+and there is a maximum value (currently 8192) that this may not exceed.
The minimum value is system-dependent.
.TP
.B COLUMNS
@@ -2549,7 +2593,8 @@ .SS "Shell Variables"
.Q 10 ,
for example).
When using \fInumeric\fP, names containing non-digits sort after all
-the all-digit names and are sorted by name using the traditional behavior.
+the all-digit names and are sorted by name using the traditional
+behavior.
.IP
A sort specifier of \fInosort\fP disables sorting completely;
.B bash
@@ -2617,7 +2662,9 @@ .SS "Shell Variables"
if necessary, to contain no more than that number of lines
by removing the oldest entries.
The history file is also truncated to this size after
-writing it when a shell exits or by the \fBhistory\fP builtin.
+writing it when a shell exits or by the
+.B \%history
+builtin.
If the value is 0, the history file is truncated to zero size.
Non-numeric values and numeric values less than zero inhibit truncation.
The shell sets the default value to the value of
@@ -2634,7 +2681,8 @@ .SS "Shell Variables"
it is not saved on the history list.
Each pattern is anchored at the
beginning of the line and must match the complete line
-(\fBbash\fP does not implicitly append a
+.RB ( bash
+does not implicitly append a
.Q \fB*\fP ).
Each pattern is tested against the line
after the checks specified by
@@ -2651,11 +2699,31 @@ .SS "Shell Variables"
the second and subsequent lines are not tested,
and are added to the history regardless of the value of
.SM
-.BR HISTIGNORE .
-If the first line was not saved, the second and subsequent lines of
-the command are not saved either.
-The pattern matching honors the setting of the \fBextglob\fP shell
-option.
+.BR HISTIGNORE ,
+if the first line was saved.
+If it was not,
+the second and subsequent lines of the command are not saved either.
+The pattern matching honors the setting of the
+.B \%extglob
+shell option.
+.IP
+.SM
+.B HISTIGNORE
+subsumes some of the function of
+.SM
+.BR HISTCONTROL .
+A pattern of
+.Q &
+is identical to
+.Q \%ignoredups ,
+and a pattern of
+.Q "[ ]*"
+is identical to
+.Q \%ignorespace .
+Combining these two patterns,
+separating them with a colon,
+provides the functionality of
+.Q \%ignoreboth .
.TP
.B HISTSIZE
The number of commands to remember in the command history (see
@@ -3073,24 +3141,35 @@ .SS "Shell Variables"
this provides functionality analogous to the \fB%\fP\fIstring\fP job
identifier.
.TP
.B histchars
-The two or three characters which control history expansion,
-quick substitution, and tokenization
+The two or three characters which control
+history expansion,
+quick substitution,
+and tokenization
(see
.SM
.B "HISTORY EXPANSION"
below).
-The first character is the \fIhistory expansion\fP character,
-the character which begins a history expansion, normally
-.Q \fB!\fP .
-The second character is the \fIquick substitution\fP character, normally
-.Q \fB\*^\fP .
-When it appears as the first character on the line,
+The first is the
+.Q "history expansion"
+character:
+normally
+.Q \fB!\fP ,
+it begins a history expansion.
+The second is the
+.Q "quick substitution"
+character:
+normally
+.Q \fB\*^\fP ,
+when it appears as the first character on the line,
history substitution repeats the previous command,
replacing one string with another.
-The optional third character is the character which indicates that
-the remainder of the line is a comment when found as the first character
-of a word, normally
-.Q \fB#\fP .
+The optional third is the
+.Q "history comment"
+character:
+normally
+.Q \fB#\fP ,
+when it appears as the first character of a word,
+it marks the remainder of the line as a comment.
The history comment character disables history substitution
for the remaining words on the line.
It does not necessarily cause the shell parser to treat the rest of the
@@ -3099,41 +3178,61 @@ .SS "Shell Variables"
.SS Arrays
.B Bash
provides one-dimensional indexed and associative array variables.
-Any variable may be used as an indexed array; the
+Any variable may be used as an indexed array;
+the
.B declare
builtin explicitly declares an array.
There is no maximum
-limit on the size of an array, nor any requirement that members
-be indexed or assigned contiguously.
+limit on the size of an array,
+nor any requirement that members be indexed or assigned contiguously.
Indexed arrays are referenced using arithmetic expressions
+(see
+.SM
+.B
+ARITHMETIC EVALUATION
+below)
that must expand to an integer and are zero-based;
associative arrays are referenced using arbitrary strings.
-Unless otherwise noted, indexed array indices must be non-negative integers.
+Unless otherwise noted,
+indexed array indices must be non-negative integers.
.PP
An indexed array is created automatically if any variable is assigned to
using the syntax
-\fIname\fP[\fIsubscript\fP]=\fIvalue\fP.
+.RS
+.BI name [ subscript ]= value\c
+\&.
+.RE
The
.I subscript
is treated as an arithmetic expression that must evaluate to a number
greater than or equal to zero.
-To explicitly declare an indexed array, use
-.B declare \-a \fIname\fP
+To explicitly declare an indexed array,
+use
+.RS
+.BI "declare \-a\ " name
+.RE
(see
.SM
.B "SHELL BUILTIN COMMANDS"
below).
-.B declare \-a \fIname\fP[\fIsubscript\fP]
-is also accepted; the \fIsubscript\fP is ignored.
+.RS
+.BI "declare \-a\ " name [ subscript ]
+.RE
+is also accepted;
+the
+.I subscript
+is ignored.
.PP
Associative arrays are created using
-.BR "declare \-A \fIname\fP" .
+.RS
+.BI "declare \-A\ " name
+.RE
+\&.
.PP
-Attributes may be
-specified for an array variable using the
-.B declare
+Attributes may be specified for an array variable using the
+.B \%declare
and
-.B readonly
+.B \%readonly
builtins.
Each attribute applies to all members of an array.
.PP
@@ -3182,8 +3281,11 @@ .SS Arrays
\fIname\fP, so negative indices count back from the end of the
array, and an index of \-1 references the last element.
.PP
-The += operator appends to an array variable when assigning
-using the compound assignment syntax; see
+The
+.Q +=
+operator appends to an array variable
+when assigning using the compound assignment syntax;
+see
.SM
.B PARAMETERS
above.
@@ -3368,21 +3470,39 @@ .SS Brace Expansion
.Q "ade ace abe" .
.PP
A sequence expression takes the form
-\fB{\fP\fIx\fP\fB..\fP\fIy\fP\fB[..\fP\fIincr\fP\fB]}\fP,
-where \fIx\fP and \fIy\fP are either integers or single letters,
-and \fIincr\fP, an optional increment, is an integer.
-When integers are supplied, the expression expands to each number between
-\fIx\fP and \fIy\fP, inclusive.
-If either \fIx\fP or \fIy\fP begins with \fI0\fP,
-each generated term will contain the same number of digits,
-zero-padding where necessary.
-When either \fIx\fP or \fPy\fP begins with a zero, the shell
-attempts to force all generated terms to contain the same number of digits,
-zero-padding where necessary.
+.BI { x .. y\c
+[\c
+.I incr
+.RB ] } ,
+where
+.I x
+and
+.I y
+and
+.IR incr ,
+an optional increment, is an integer.
+When integers are supplied,
+the expression expands to each number between
+.I x
+and
+.IR y ,
+inclusive.
+If the supplied integers are prefixed with
+.Q 0 ,
+each term will have the same width,
+zero-padding if necessary.
When letters are supplied, the expression expands to each character
-lexicographically between \fIx\fP and \fIy\fP, inclusive,
+lexicographically between
+.I x
+and
+.IR y ,
+inclusive,
using the default C locale.
-Note that both \fIx\fP and \fIy\fP must be of the same type
+Note that both
+.I x
+and
+.I y
+must be of the same type
(integer or letter).
When the increment is supplied, it is used as the difference between
each term.
@@ -3401,22 +3521,33 @@ .SS Brace Expansion
sequence expression.
Any incorrectly formed brace expansion is left unchanged.
.PP
-A \fB{\fP or \fB,\fP may be quoted with a backslash to prevent its
-being considered part of a brace expression.
-To avoid conflicts with parameter expansion, the string \fB${\fP
-is not considered eligible for brace expansion, and inhibits brace
-expansion until the closing \fB}\fP.
+A
+.Q {
+or
+.Q ,
+may be quoted with a backslash
+to prevent its being considered part of a brace expression.
+To avoid conflicts with parameter expansion,
+the string
+.Q ${
+is not considered eligible for brace expansion,
+and inhibits brace expansion until the closing
+.Q } .
.PP
This construct is typically used as shorthand when the common
prefix of the strings to be generated is longer than in the
above example:
-.RS
.PP
+.RS
+.EX
mkdir /usr/local/src/bash/{old,new,dist,bugs}
+.EE
.RE
or
.RS
+.EX
chown root /usr/{ucb/{ex,edit},lib/{ex?.?*,how_ex}}
+.EE
.RE
.PP
Brace expansion introduces a slight incompatibility with
@@ -3430,10 +3561,12 @@ .SS Brace Expansion
expansion.
For example, a word entered to
.B sh
-as \fIfile{1,2}\fP
+as
+.Q file{1,2}
appears identically in the output.
-\fBBash\fP outputs that word as
-.I file1 file2
+.B Bash
+outputs that word as
+.Q "file1 file2"
after brace expansion.
Start
.B bash
@@ -3443,10 +3576,14 @@ .SS Brace Expansion
.B +B
option to the
.B set
-command (see
+command
+(see
.SM
.B "SHELL BUILTIN COMMANDS"
-below) for strict \fBsh\fP compatibility.
+below)
+for strict
+.B sh
+compatibility.
.SS Tilde Expansion
If a word begins with an unquoted tilde character (\c
.Q \fB\*~\fP ),
@@ -4145,17 +4282,30 @@ .SS Process Substitution
passed as an argument to the current command as the result of the
expansion.
.PP
-If the \fB>(\fP\fIlist\^\fP\fB)\fP form is used, writing to
-the file provides input for \fIlist\fP.
If the
-\fB<(\fP\fIlist\^\fP\fB)\fP form is used, reading the file
-obtains the output of \fIlist\fP.
-No space may appear between the \fB<\fP or \fB>\fP
-and the left parenthesis, otherwise the construct would be interpreted
-as a redirection.
+.BI >( list )
+form is used,
+writing to the file provides input for
+.I list .
+If the
+.BI <( list )
+form is used,
+reading the file obtains the output of
+.I list .
+No space may appear between the
+.B <
+or
+.B >
+and the left parenthesis;
+otherwise the construct would be interpreted as a redirection.
.PP
-Process substitution is supported on systems that support named
-pipes (\fIFIFOs\fP) or the \fB/dev/fd\fP method of naming open files.
+Process substitution is supported on systems that support named pipes
+(\c
+.SM FIFO\c
+s)
+or the
+.I /dev/fd
+method of naming open files.
.PP
When available, process substitution is performed
simultaneously with parameter and variable expansion,
@@ -4366,7 +4516,8 @@ .SS "Pathname Expansion"
.Q .*
one of the patterns in
.SM
-.BR GLOBIGNORE .
+.B GLOBIGNORE \c
+\&. \" Set the period outside the reach of `SM`.
The
.B dotglob
option is disabled when
@@ -4375,14 +4526,18 @@ .SS "Pathname Expansion"
is unset.
The
.B GLOBIGNORE
-pattern matching honors the setting of the \fBextglob\fP shell
-option.
+pattern matching honors the setting of the
+.B \%extglob
+shell option.
.PP
The
.SM
.B GLOBSORT
-shell variable controls how the results of pathname expansion are sorted,
-as described above.
+shell variable controls
+how the results of pathname expansion are sorted,
+as described in
+.B "Shell Variables"
+above.
.PP
\fBPattern Matching\fP
.PP
@@ -4715,9 +4870,11 @@ .SS Redirecting Output
.B noclobber
option to the
.B set
-builtin has been enabled, the redirection fails if the file
-whose name results from the expansion of \fIword\fP exists and is
-a regular file.
+builtin has been enabled,
+the redirection fails
+if the file whose name results from the expansion of
+.I word
+exists and is a regular file.
If the redirection operator is
.BR >| ,
or the redirection operator is
@@ -4727,10 +4884,12 @@ .SS Redirecting Output
option to the
.B set
builtin command is not enabled,
-\fBbash\fP attempts the redirection
-even if the file named by \fIword\fP exists.
+.B bash
+attempts the redirection even if the file named by
+.I word
+exists.
.SS Appending Redirected Output
-Redirecting output in this fashion opens
+Redirecting output in this fashion opens
the file whose name results from the expansion of
.I word
for appending on file descriptor
@@ -5162,8 +5321,10 @@ .SH FUNCTIONS
Once the function returns, any instance of the variable at a previous
scope becomes visible.
If the unset acts on a variable at a previous scope, any instance of a
-variable with that name that had been shadowed becomes visible
-(see below how the \fBlocalvar_unset\fP shell option changes this behavior).
+variable with that name that had been shadowed will become visible
+(see below how the
+.B localvar_unset
+shell option changes this behavior).
.PP
The
.SM
diff --git a/doc/bashref.texi b/doc/bashref.texi
index 0998411e..c8dcc142 100644
--- a/doc/bashref.texi
+++ b/doc/bashref.texi
@@ -487,10 +487,16 @@ @node Top
If enabled, history expansion will be performed unless an
@samp{!}
appearing in double quotes is escaped using a backslash.
-The backslash preceding the @samp{!} is not removed.
+The backslash preceding the
+@samp{!}
+is not removed.
-The special parameters @samp{*} and @samp{@@} have special meaning
-when in double quotes (@pxref{Shell Parameter Expansion}).
+The special parameters
+@samp{*}
+and
+@samp{@@}
+have special meaning when in double quotes
+(@pxref{Shell Parameter Expansion}).
@node ANSI-C Quoting
@subsubsection ANSI-C Quoting
@@ -1739,10 +1745,12 @@ @node Top
(appearing as unset)
until it is reset in that scope or until the function returns.
Once the function returns, any instance of the variable at a previous
-scope becomes visible.
+scope will become visible.
If the unset acts on a variable at a previous scope, any instance of a
variable with that name that had been shadowed will become visible
-(see below how the @code{localvar_unset} shell option changes this behavior).
+(see below how the
+@code{localvar_unset}
+shell option changes this behavior).
The @option{-f} option to the @code{declare} (@code{typeset})
builtin command (@pxref{Bash Builtins})
@@ -1819,26 +1827,41 @@ @node Top
command export var=value
@end example
-In the context where an assignment statement is assigning a value
-to a shell variable or array index (@pxref{Arrays}),
-the @samp{+=} operator appends to or adds to
-the variable's previous value.
+In the context where an assignment statement is assigning a value
+to a shell variable or array index
+(@pxref{Arrays}),
+the
+@samp{+=}
+operator appends to or adds to the variable's previous value.
This includes arguments to declaration commands such as
-@code{declare} that accept assignment statements.
-When @samp{+=} is applied to a variable
-for which the @code{integer} attribute has been set,
-the variable's current value and @var{value} are each evaluated as
-arithmetic expressions,
+@code{declare}
+that accept assignment statements.
+When
+@samp{+=}
+is applied to a variable
+for which the
+@code{integer}
+attribute has been set,
+the variable's current value and
+@var{value}
+are each evaluated as arithmetic expressions,
and the sum of the results is assigned as the variable's value.
-The current value is usually an integer constant, but may be an expression.
-When @samp{+=} is applied to an array variable using compound assignment
-(@pxref{Arrays}), the
-variable's value is not unset (as it is when using @samp{=}), and new
-values are appended to the array beginning at one greater than the array's
-maximum index (for indexed arrays), or added as additional key-value pairs
-in an associative array.
-When applied to a string-valued variable, @var{value} is expanded and
-appended to the variable's value.
+The current value is usually an integer constant,
+but may be an expression.
+When
+@samp{+=}
+is applied to an array variable using compound assignment
+(@pxref{Arrays}),
+the variable's value is not unset
+(as it is when using
+@samp{=}),
+and new values are appended to the array
+beginning at one greater than the array's maximum index
+(for indexed arrays),
+or added as additional key-value pairs in an associative array.
+When applied to a string-valued variable,
+@var{value}
+is expanded and appended to the variable's value.
A variable can be assigned the @code{nameref} attribute using the
@option{-n} option to the @code{declare} or @code{local} builtin commands
@@ -2081,18 +2104,38 @@ @node Top
ade ace abe
@end example
-A sequence expression takes the form @code{@{@var{x}..@var{y}[..@var{incr}]@}},
-where @var{x} and @var{y} are either integers or letters,
-and @var{incr}, an optional increment, is an integer.
-When integers are supplied, the expression expands to each number between
-@var{x} and @var{y}, inclusive.
-If either @var{x} or @var{y} begins with a zero,
-each generated term will contain the same number of digits,
-zero-padding where necessary.
+A sequence expression takes the form
+@code{@{@var{x}..@var{y}[..@var{incr}]@}},
+where
+@var{x}
+and
+@var{y}
+are either integers or single letters,
+and
+@var{incr},
+an optional increment, is an integer.
+When integers are supplied,
+the expression expands to each number between
+@var{x}
+and
+@var{y},
+inclusive.
+If the supplied integers are prefixed with
+@samp{0},
+each term will have the same width,
+zero-padding if necessary.
When letters are supplied, the expression expands to each character
-lexicographically between @var{x} and @var{y}, inclusive,
+lexicographically between
+@var{x}
+and
+@var{y},
+inclusive,
using the default C locale.
-Note that both @var{x} and @var{y} must be of the same type
+Note that both
+@var{x}
+and
+@var{y}
+must be of the same type
(integer or letter).
When the increment is supplied, it is used as the difference between
each term.
@@ -2110,11 +2153,18 @@ @node Top
sequence expression.
Any incorrectly formed brace expansion is left unchanged.
-A @{ or @samp{,} may be quoted with a backslash to prevent its
-being considered part of a brace expression.
-To avoid conflicts with parameter expansion, the string @samp{$@{}
+A
+@samp{@{}
+or
+@samp{,}
+may be quoted with a backslash
+to prevent its being considered part of a brace expression.
+To avoid conflicts with parameter expansion,
+the string
+@samp{$@{}
is not considered eligible for brace expansion,
-and inhibits brace expansion until the closing @samp{@}}.
+and inhibits brace expansion until the closing
+@samp{@}}.
This construct is typically used as shorthand when the common
prefix of the strings to be generated is longer than in the
@@ -2127,6 +2177,38 @@ @node Top
chown root /usr/@{ucb/@{ex,edit@},lib/@{ex?.?*,how_ex@}@}
@end example
+Brace expansion introduces a slight incompatibility with
+historical versions of
+@command{sh}.
+@command{sh}
+does not treat opening or closing braces specially when they
+appear as part of a word, and preserves them in the output.
+Bash
+removes braces from words as a consequence of brace
+expansion.
+For example, a word entered to
+@command{sh}
+as
+@samp{file@{1,2@}}
+appears identically in the output.
+Bash
+outputs that word as
+@samp{file1 file2}
+after brace expansion.
+Start
+Bash
+with the
+@option{+B}
+option or disable brace expansion with the
+@option{+B}
+option to the
+@code{set}
+command
+(@pxref{Shell Builtin Commands})
+for strict
+@command{sh}
+compatibility.
+
@node Tilde Expansion
@subsection Tilde Expansion
@cindex tilde expansion
@@ -2906,17 +2988,28 @@ @node Top
passed as an argument to the current command as the result of the
expansion.
-If the @code{>(@var{list})} form is used, writing to
-the file provides input for @var{list}.
If the
-@code{<(@var{list})} form is used, reading the file
-obtains the output of @var{list}.
-Note that no space may appear between the @code{<} or @code{>}
-and the left parenthesis, otherwise the construct would be interpreted
-as a redirection.
+@code{>(@var{list})}
+form is used,
+writing to the file provides input for
+@var{list}.
+If the
+@code{<(@var{list})}
+form is used,
+reading the file obtains the output of
+@var{list}.
+No space may appear between the
+@code{<}
+or
+@code{>}
+and the left parenthesis;
+otherwise the construct would be interpreted as a redirection.
-Process substitution is supported on systems that support named
-pipes (@sc{fifo}s) or the @file{/dev/fd} method of naming open files.
+Process substitution is supported on systems that support named pipes
+(@sc{fifo}s)
+or the
+@file{/dev/fd}
+method of naming open files.
When available, process substitution is performed simultaneously with
parameter and variable expansion, command substitution, and arithmetic
@@ -3046,17 +3139,24 @@ @node Top
@samp{.}
match.
To get the old behavior of ignoring filenames beginning with a
-@samp{.}, make @samp{.*} one of the patterns in @env{GLOBIGNORE}.
-The @code{dotglob} option is disabled when @env{GLOBIGNORE}
+@samp{.},
+make @samp{.*}
+one of the patterns in
+@env{GLOBIGNORE}.
+The @code{dotglob} option is disabled when
+@env{GLOBIGNORE}
is unset.
The @code{GLOBIGNORE}
-pattern matching honors the setting of the @code{extglob} shell
-option.
+pattern matching honors the setting of the
+@code{extglob}
+shell option.
-After the pattern is expanded and matched against filenames, the value of the
-@env{GLOBSORT} shell
-variable controls how the results are sorted, as described
-below (@pxref{Bash Variables}).
+The
+@env{GLOBSORT}
+shell variable controls
+how the results of pathname expansion are sorted,
+as described below
+(@pxref{Bash Variables}).
@node Pattern Matching
@subsubsection Pattern Matching
@@ -3349,19 +3449,33 @@ @node Top
@code{noclobber}
option to the
@code{set}
-builtin has been enabled, the redirection fails if the file
-whose name results from the expansion of @var{word} exists and is
-a regular file.
-If the redirection operator is @samp{>|}, or the redirection operator is
-@samp{>} and the @code{noclobber} option is not enabled,
-Bash attemps the redirection
-even if the file named by @var{word} exists.
+builtin has been enabled,
+the redirection fails
+if the file whose name results from the expansion of
+@var{word}
+exists and is a regular file.
+If the redirection operator is
+@samp{>|},
+or the redirection operator is
+@samp{>}
+and the
+@code{noclobber}
+option to the
+@code{set}
+builtin command is not enabled,
+Bash
+attemps the redirection even if the file named by
+@var{word}
+exists.
@subsection Appending Redirected Output
Redirecting output in this fashion opens
-the file whose name results from the expansion of @var{word}
-for appending on file descriptor @var{n},
-or the standard output (file descriptor 1) if @var{n}
+the file whose name results from the expansion of
+@var{word}
+for appending on file descriptor
+@var{n},
+or the standard output (file descriptor 1) if
+@var{n}
is not specified.
If the file does not exist it is created.
@@ -6912,7 +7026,8 @@ @node Top
@item BASH_XTRACEFD
If set to an integer corresponding to a valid file descriptor,
-Bash writes the trace output generated when
+Bash
+writes the trace output generated when
@samp{set -x}
is enabled to that file descriptor,
instead of the standard error.
@@ -7157,9 +7272,14 @@ @node Top
The @samp{numeric} specifier treats names consisting solely of digits as
numbers and sorts them using their numeric value
-(so ``2'' sorts before ``10'', for example).
+(so
+``2''
+sorts before
+``10'',
+for example).
When using @samp{numeric}, names containing non-digits sort after all
-the all-digit names and are sorted by name using the traditional behavior.
+the all-digit names and are sorted by name using the traditional
+behavior.
A sort specifier of @samp{nosort} disables sorting completely;
Bash returns the results
@@ -7181,20 +7301,32 @@ @node Top
subsequently reset.
@item histchars
-The two or three characters which control history expansion,
-quick substitution, and tokenization
+The two or three characters that control
+history expansion,
+quick substitution,
+and tokenization
(@pxref{History Interaction}).
-The first character is the @dfn{history expansion} character,
-the character which begins a history expansion, normally
-@samp{!}.
-The second character is the ``quick substitution'' character, normally
-@samp{^}.
-When it appears as the first character on the line,
+The first is the
+``history expansion''
+character:@:
+normally
+@samp{!},
+it begins a history expansion.
+The second is the
+``quick substitution''
+character:@:
+normally
+@samp{^},
+when it appears as the first character on the line,
history substitution repeats the previous command,
replacing one string with another.
-The optional third character is the character which indicates that
-the remainder of the line is a comment when found as the first character
-of a word, usually @samp{#}.
+The optional third is the
+``history comment''
+character:@:
+normally
+@samp{#};
+when it appears as the first character of a word,
+it marks the remainder of the line as a comment.
The history comment character disables history substitution
for the remaining words on the line.
It does not necessarily cause the shell parser to treat the rest of the
@@ -7244,10 +7376,13 @@ @node Top
if necessary, to contain no more than that number of lines
by removing the oldest entries.
The history file is also truncated to this size after
-writing it when a shell exits or by the @code{history} builtin.
+writing it when a shell exits or by the
+@code{history}
+builtin.
If the value is 0, the history file is truncated to zero size.
Non-numeric values and numeric values less than zero inhibit truncation.
-The shell sets the default value to the value of @env{HISTSIZE}
+The shell sets the default value to the value of
+@env{HISTSIZE}
after reading any startup files.
@item HISTIGNORE
@@ -7258,7 +7393,8 @@ @node Top
it is not saved on the history list.
Each pattern is anchored at the
beginning of the line and must match the complete line
-(Bash does not implicitly append a
+(Bash
+does not implicitly append a
@samp{*}).
Each pattern is tested against the line
after the checks specified by
@@ -7273,17 +7409,29 @@ @node Top
If the first line of a multi-line compound command was saved,
the second and subsequent lines are not tested,
and are added to the history regardless of the value of
-@env{HISTIGNORE}.
-If the first line was not saved, the second and subsequent lines of
-the command are not saved either.
-The pattern matching honors the setting of the @code{extglob} shell
-option.
-
-@env{HISTIGNORE} subsumes some of the function of @env{HISTCONTROL}.
-A pattern of @samp{&} is identical to @code{ignoredups}, and a
-pattern of @samp{[ ]*} is identical to @code{ignorespace}.
-Combining these two patterns, separating them with a colon,
-provides the functionality of @code{ignoreboth}.
+@env{HISTIGNORE},
+if the first line was saved.
+If it was not,
+the second and subsequent lines of the command are not saved either.
+The pattern matching honors the setting of the
+@code{extglob}
+shell option.
+
+@env{HISTIGNORE}
+subsumes some of the function of
+@env{HISTCONTROL}.
+A pattern of
+@samp{&}
+is identical to
+@code{ignoredups},
+and a pattern of
+@samp{[ ]*}
+is identical to
+@code{ignorespace}.
+Combining these two patterns,
+separating them with a colon,
+provides the functionality of
+@code{ignoreboth}.
@item HISTSIZE
The maximum number of commands to remember on the history list.
@@ -7498,7 +7646,8 @@ @node Top
The current working directory as set by the @code{cd} builtin.
@item RANDOM
-Each time this parameter is referenced, it expands to a random integer
+Each time this parameter is referenced,
+it expands to a random integer
between 0 and 32767.
Assigning a value to
@env{RANDOM}
@@ -7510,24 +7659,34 @@ @node Top
subsequently reset.
@item READLINE_ARGUMENT
-Any numeric argument given to a Readline command that was defined using
-@samp{bind -x} (@pxref{Bash Builtins}
+Any numeric argument given to a
+Readline
+command that was defined using
+@samp{bind -x}
+(@pxref{Bash Builtins}
when it was invoked.
@item READLINE_LINE
The contents of the Readline line buffer, for use
-with @samp{bind -x} (@pxref{Bash Builtins}).
+with
+@samp{bind -x}
+(@pxref{Bash Builtins}).
@item READLINE_MARK
The position of the @dfn{mark} (saved insertion point) in the
Readline line buffer, for use
-with @samp{bind -x} (@pxref{Bash Builtins}).
+with
+@samp{bind -x}
+(@pxref{Bash Builtins}).
The characters between the insertion point and the mark are often
-called the @dfn{region}.
+called the
+@dfn{region}.
@item READLINE_POINT
The position of the insertion point in the Readline line buffer, for use
-with @samp{bind -x} (@pxref{Bash Builtins}).
+with
+@samp{bind -x}
+(@pxref{Bash Builtins}).
@item REPLY
The default variable for the @code{read} builtin;
@@ -7733,8 +7892,9 @@ @node Top
This is on by default if the shell is invoked as @code{sh}.
@item --posix
-Change the behavior of Bash where the default operation differs
-from the
+Change the behavior of
+Bash
+where the default operation differs from the
@sc{posix}
standard to match the standard.
This is intended to make Bash behave as a strict superset of that
@@ -7795,7 +7955,8 @@ @node Top
through a pipe.
@item -D
-Print a list of all double-quoted strings preceded by @samp{$}
+Print a list of all double-quoted strings preceded by
+@samp{$}
on the standard output.
These are the strings that
are subject to language translation when the current locale
@@ -7833,28 +7994,62 @@ @node Top
@end table
@cindex login shell
-A @emph{login} shell is one whose first character of argument zero is
-@samp{-}, or one invoked with the @option{--login} option.
+A
+@dfn{login shell}
+is one whose first character of argument zero is
+@samp{-},
+or one invoked with the
+@option{--login}
+option.
@cindex interactive shell
-An @emph{interactive} shell is one started without non-option arguments,
-unless @option{-s} is specified, without specifying the @option{-c} option,
-and whose input and output (using the standard error) are both
-connected to terminals (as determined by @code{isatty(3)}), or one
-started with the @option{-i} option.
+An
+@dfn{interactive}
+shell is one started without non-option arguments
+(unless
+@option{-s}
+is specified),
+without specifying the
+@option{-c}
+option,
+and whose standard input and standard error
+are both connected to terminals
+(as determined by
+@i{isatty}(3)),
+or one started with the
+@option{-i} option.
@xref{Interactive Shells}, for more information.
-If arguments remain after option processing, and neither the
-@option{-c} nor the @option{-s}
-option has been supplied, the first argument is assumed to
-be the name of a file containing shell commands (@pxref{Shell Scripts}).
-When Bash is invoked in this fashion, @code{$0}
-is set to the name of the file, and the positional parameters
-are set to the remaining arguments.
-Bash reads and executes commands from this file, then exits.
-Bash's exit status is the exit status of the last command executed
+If arguments remain after option processing,
+and neither the
+@option{-c}
+nor the
+@option{-s}
+option has been supplied,
+the first argument is assumed to be the name of a file
+containing shell commands
+(@pxref{Shell Scripts}).
+When
+Bash
+is invoked in this fashion,
+@code{$0}
+is set to the name of the file,
+and the positional parameters are set to the remaining arguments.
+Bash
+reads and executes commands from this file,
+then exits.
+Bash's
+exit status is the exit status of the last command executed
in the script.
-If no commands are executed, the exit status is 0.
+If no commands are executed,
+the exit status is 0.
+Bash
+first attempts to open the file in the current directory,
+and,
+if no file is found,
+then searches the directories in
+@env{PATH}
+for the script.
@node Bash Startup Files
@section Bash Startup Files
@@ -7914,36 +8109,58 @@ @node Top
but does not the value of the @env{PATH} variable to search for the
filename.
-As noted above, if a non-interactive shell is invoked with the
-@option{--login} option, Bash attempts to read and execute commands from the
-login shell startup files.
+As noted above,
+if a non-interactive shell is invoked with the
+@option{--login}
+option,
+Bash
+attempts to read and execute commands from the
+login shell startup files.
@subsubheading Invoked with name @code{sh}
-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
+If
+Bash
+is invoked with the name
+@command{sh},
+it tries to mimic the startup behavior of historical versions of
+@command{sh}
+as closely as 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
-and execute commands from @file{/etc/profile} and @file{~/.profile}, in
-that order.
-The @option{--noprofile} option inhibits this behavior.
+When invoked as an interactive login shell,
+or as a non-interactive shell with the
+@option{--login}
+option,
+it first attempts to read and execute commands from
+@file{/etc/profile}
+and
+@file{~/.profile},
+in that order.
+The
+@option{--noprofile}
+option inhibits this behavior.
-When invoked as an interactive shell with the name @code{sh}, Bash
-looks for the variable @env{ENV}, expands its value if it is defined,
+When invoked as an interactive shell with the name
+@command{sh},
+Bash
+looks for the variable
+@env{ENV},
+expands its value if it is defined,
and uses the expanded value as the name of a file to read and execute.
-Since a shell invoked as @code{sh} does not attempt to read and execute
-commands from any other startup files, the @option{--rcfile} option has
-no effect.
-
-A non-interactive shell invoked with the name @code{sh} does not attempt
-to read any other startup files.
+Since a shell invoked as
+@command{sh}
+does not attempt to read and execute commands from any other startup
+files,
+the
+@option{--rcfile}
+option has no effect.
-When invoked as @code{sh}, Bash enters @sc{posix} mode after reading
-the startup files.
+A non-interactive shell invoked with the name
+@command{sh}
+does not attempt to read any other startup files.
@subsubheading Invoked in @sc{posix} mode
@@ -8538,16 +8755,19 @@ @node Top
Bash
provides one-dimensional indexed and associative array variables.
-Any variable may be used as an indexed array; the
+Any variable may be used as an indexed array;
+the
@code{declare}
builtin explicitly declares an array.
There is no maximum
-limit on the size of an array, nor any requirement that members
-be indexed or assigned contiguously.
+limit on the size of an array,
+nor any requirement that members be indexed or assigned contiguously.
Indexed arrays are referenced using arithmetic expressions
-that must expand to an integer (@pxref{Shell Arithmetic})) and are zero-based;
-associative arrays use arbitrary strings.
-Unless otherwise noted, indexed array indices must be non-negative integers.
+(@pxref{Shell Arithmetic})
+that must expand to an integer and are zero-based;
+associative arrays are referenced using 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
@@ -8556,10 +8776,12 @@ @node Top
@end example
@noindent
-The @var{subscript}
+The
+@var{subscript}
is treated as an arithmetic expression that must evaluate to a number
greater than or equal to zero.
-To explicitly declare an array, use
+To explicitly declare an indexed array,
+use
@example
declare -a @var{name}
@end example
@@ -8578,9 +8800,11 @@ @node Top
declare -A @var{name}
@end example
-Attributes may be
-specified for an array variable using the @code{declare} and
-@code{readonly} builtins.
+Attributes may be specified for an array variable using the
+@code{declare}
+and
+@code{readonly}
+builtins.
Each attribute applies to all members of an array.
Arrays are assigned using compound assignments of the form
@@ -8628,8 +8852,13 @@ @node Top
@var{name}, so negative indices count back from the end of the
array, and an index of -1 references the last element.
-The @samp{+=} operator appends to an array variable when assigning
-using the compound assignment syntax; see @ref{Shell Parameters} above.
+The
+@samp{+=}
+operator appends to an array variable
+when assigning using the compound assignment syntax;
+see
+@ref{Shell Parameters}
+above.
An array element is referenced using
@code{$@{@var{name}[@var{subscript}]@}}.
@@ -8671,7 +8900,8 @@ @node Top
Referencing an array variable without a subscript is equivalent to
referencing with a subscript of 0.
Any reference to a variable using a valid subscript is valid;
-Bash creates an array if necessary.
+Bash
+creates an array if necessary.
An array variable is considered set if a subscript has been assigned a
value.
--
2.30.2
signature.asc
Description: PGP signature
