.\"
.\" Chet Ramey
.\" Case Western Reserve University
-.\" chet@po.cwru.edu
+.\" chet.ramey@case.edu
.\"
-.\" Last Change: Sat Feb 7 20:50:40 EST 2009
+.\" Last Change: Sun Feb 2 16:21:40 EST 2014
.\"
.\" bash_builtins, strip all but Built-Ins section
.if \n(zZ=1 .ig zZ
.if \n(zY=1 .ig zY
-.TH BASH 1 "2009 February 7" "GNU Bash-4.0"
+.TH BASH 1 "2014 February 2" "GNU Bash 4.3"
.\"
.\" There's some problem with having a `@'
.\" in a tagged paragraph with the BSD man macros.
.SH SYNOPSIS
.B bash
[options]
-[file]
+[command_string | file]
.SH COPYRIGHT
-.if n Bash is Copyright (C) 1989-2009 by the Free Software Foundation, Inc.
-.if t Bash is Copyright \(co 1989-2009 by the Free Software Foundation, Inc.
+.if n Bash is Copyright (C) 1989-2013 by the Free Software Foundation, Inc.
+.if t Bash is Copyright \(co 1989-2013 by the Free Software Foundation, Inc.
.SH DESCRIPTION
.B Bash
is an \fBsh\fR-compatible command language interpreter that
.B Bash
can be configured to be POSIX-conformant by default.
.SH OPTIONS
-In addition to the single-character shell options documented in the
-description of the \fBset\fR builtin command, \fBbash\fR
+All of the single-character shell options documented in the
+description of the \fBset\fR builtin command can be used as options
+when the shell is invoked.
+In addition, \fBbash\fR
interprets the following options when it is invoked:
.PP
.PD 0
.TP 10
-.BI \-c "\| string\^"
+.B \-c
If the
.B \-c
-option is present, then commands are read from
-.IR string .
+option is present, then commands are read from the first non-option argument
+.IR command_string .
If there are arguments after the
-.IR string ,
+.IR command_string ,
they are assigned to the positional parameters, starting with
.BR $0 .
.TP
.B extdebug
option to the
.B shopt
-builtin below)
-and shell function tracing (see the description of the
-\fB\-o functrace\fP option to the
-.B set
builtin below).
.TP
.B \-\-dump\-po\-strings
.B \-\-posix
Change the behavior of \fBbash\fP where the default operation differs
from the POSIX standard to match the standard (\fIposix mode\fP).
+See
+.SM
+.B "SEE ALSO"
+below for a reference to a document that details how posix mode affects
+bash's behavior.
.TP
.B \-\-restricted
The shell becomes restricted (see
If any of the files exist but cannot be read,
.B bash
reports an error.
-Tildes are expanded in file names as described below under
+Tildes are expanded in filenames as described below under
.B "Tilde Expansion"
in the
.SM
but the value of the
.SM
.B PATH
-variable is not used to search for the file name.
+variable is not used to search for the filename.
.PP
If
.B bash
.PP
.B Bash
attempts to determine when it is being run with its standard input
-connected to a a network connection, as if by the remote shell
+connected to a network connection, as when executed by the remote shell
daemon, usually \fIrshd\fP, or the secure shell daemon \fIsshd\fP.
If
.B bash
.B \-\-norc
option may be used to inhibit this behavior, and the
.B \-\-rcfile
-option may be used to force another file to be read, but
-\fIrshd\fP does not generally invoke the shell with those options
+option may be used to force another file to be read, but neither
+\fIrshd\fP nor \fIsshd\fP generally invoke the shell with those options
or allow them to be specified.
.PP
If the shell is started with the effective user (group) id not equal to the
real user (group) id, and the \fB\-p\fP option is not supplied, no startup
files are read, shell functions are not inherited from the environment, the
.SM
-.B SHELLOPTS
-variable, if it appears in the environment, is ignored,
+.BR SHELLOPTS ,
+.SM
+.BR BASHOPTS ,
+.SM
+.BR CDPATH ,
+and
+.SM
+.B GLOBIGNORE
+variables, if they appear in the environment, are ignored,
and the effective user id is set to the real user id.
If the \fB\-p\fP option is supplied at invocation, the startup behavior is
the same, but the effective user id is not reset.
symbols:
.RS
.PP
-.if t \fB\(bv\(bv & && ; ;; ( ) | |& <newline>\fP
+.if t \fB|| & && ; ;; ( ) | |& <newline>\fP
.if n \fB|| & && ; ;; ( ) | |& <newline>\fP
.RE
.PD
.if t .RS
.PP
.B
-.if n ! case do done elif else esac fi for function if in select then until while { } time [[ ]]
-.if t ! case do done elif else esac fi for function if in select then until while { } time [[ ]]
+.if n ! case coproc do done elif else esac fi for function if in select then until while { } time [[ ]]
+.if t ! case coproc do done elif else esac fi for function if in select then until while { } time [[ ]]
.if t .RE
.SH "SHELL GRAMMAR"
.SS Simple Commands
.SM
.B REDIRECTION
below).
-If \fB|&\fP is used, the standard error of \fIcommand\fP is connected to
-\fIcommand2\fP's standard input through the pipe; it is shorthand for
-\fB2>&1 |\fP.
-This implicit redirection of the standard error is performed after any
-redirections specified by the command.
+If \fB|&\fP is used, \fIcommand\fP's standard error, in addition to its
+standard output, is connected to
+\fIcommand2\fP's standard input through the pipe;
+it is shorthand for \fB2>&1 |\fP.
+This implicit redirection of the standard error to the standard output is
+performed after any redirections specified by the command.
.PP
The return status of a pipeline is the exit status of the last
command, unless the \fBpipefail\fP option is enabled.
system time consumed by its execution are reported when the pipeline
terminates.
The \fB\-p\fP option changes the output format to that specified by POSIX.
+When the shell is in \fIposix mode\fP, it does not recognize
+\fBtime\fP as a reserved word if the next token begins with a `-'.
The
.SM
.B TIMEFORMAT
.B "Shell Variables"
below.
.PP
+When the shell is in \fIposix mode\fP, \fBtime\fP
+may be followed by a newline. In this case, the shell displays the
+total user and system time consumed by the shell and its children.
+The
+.SM
+.B TIMEFORMAT
+variable may be used to specify the format of
+the time information.
+.PP
Each command in a pipeline is executed as a separate process (i.e., in a
subshell).
.SS Lists
.BR & ,
.BR && ,
or
-.BR \(bv\(bv ,
+.BR || ,
and optionally terminated by one of
.BR ; ,
.BR & ,
Of these list operators,
.B &&
and
-.B \(bv\(bv
+.B ||
have equal precedence, followed by
.B ;
and
exit status of the last command executed.
.PP
AND and OR lists are sequences of one of more pipelines separated by the
-\fB&&\fP and \fB\(bv\(bv\fP control operators, respectively.
+\fB&&\fP and \fB||\fP control operators, respectively.
AND and OR lists are executed with left associativity.
An AND list has the form
.RS
An OR list has the form
.RS
.PP
-\fIcommand1\fP \fB\(bv\(bv\fP \fIcommand2\fP
+\fIcommand1\fP \fB||\fP \fIcommand2\fP
.PP
.RE
.PP
executed in the list.
.SS Compound Commands
.PP
-A \fIcompound command\fP is one of the following:
+A \fIcompound command\fP is one of the following.
+In most cases a \fIlist\fP in a command's description may be separated from
+the rest of the command by one or more newlines, and may be followed by a
+newline in place of a semicolon.
.TP
(\fIlist\fP)
\fIlist\fP is executed in a subshell environment (see
.SM
.BR "CONDITIONAL EXPRESSIONS" .
Word splitting and pathname expansion are not performed on the words
-between the \fB[[\fP and \fB]]\fP; tilde expansion, parameter and
-variable expansion, arithmetic expansion, command substitution, process
+between the \fB[[\fP and \fB]]\fP; tilde expansion,
+parameter and variable expansion,
+arithmetic expansion, command substitution, process
substitution, and quote removal are performed.
Conditional operators such as \fB\-f\fP must be unquoted to be recognized
as primaries.
.if t .sp 0.5
.if n .sp 1
+When used with \fB[[\fP, the \fB<\fP and \fB>\fP operators sort
+lexicographically using the current locale.
+.if t .sp 0.5
+.if n .sp 1
When the \fB==\fP and \fB!=\fP operators are used, the string to the
right of the operator is considered a pattern and matched according
-to the rules described below under \fBPattern Matching\fP.
+to the rules described below under \fBPattern Matching\fP,
+as if the \fBextglob\fP shell option were enabled.
+The \fB=\fP operator is equivalent to \fB==\fP.
If the shell option
.B nocasematch
is enabled, the match is performed without regard to the case
of alphabetic characters.
The return value is 0 if the string matches (\fB==\fP) or does not match
(\fB!=\fP) the pattern, and 1 otherwise.
-Any part of the pattern may be quoted to force it to be matched as a
-string.
+Any part of the pattern may be quoted to force the quoted portion
+to be matched as a string.
.if t .sp 0.5
.if n .sp 1
An additional binary operator, \fB=~\fP, is available, with the same
.B nocasematch
is enabled, the match is performed without regard to the case
of alphabetic characters.
-Any part of the pattern may be quoted to force it to be matched as a
-string.
+Any part of the pattern may be quoted to force the quoted portion
+to be matched as a string.
+Bracket expressions in regular expressions must be treated carefully,
+since normal quoting characters lose their meanings between brackets.
+If the pattern is stored in a shell variable, quoting the variable
+expansion forces the entire pattern to be matched as a string.
Substrings matched by parenthesized subexpressions within the regular
-expression are saved in the array variable \fBBASH_REMATCH\fP.
-The element of \fBBASH_REMATCH\fP with index 0 is the portion of the string
+expression are saved in the array variable
+.SM
+.BR BASH_REMATCH .
+The element of
+.SM
+.B BASH_REMATCH
+with index 0 is the portion of the string
matching the entire regular expression.
-The element of \fBBASH_REMATCH\fP with index \fIn\fP is the portion of the
+The element of
+.SM
+.B BASH_REMATCH
+with index \fIn\fP is the portion of the
string matching the \fIn\fPth parenthesized subexpression.
.if t .sp 0.5
.if n .sp 1
.I expression2
are true.
.TP
-.if t \fIexpression1\fP \fB\(bv\(bv\fP \fIexpression2\fP
-.if n \fIexpression1\fP \fB||\fP \fIexpression2\fP
+\fIexpression1\fP \fB||\fP \fIexpression2\fP
True if either
.I expression1
or
is true.
.PD
.LP
-The \fB&&\fP and
-.if t \fB\(bv\(bv\fP
-.if n \fB||\fP
+The \fB&&\fP and \fB||\fP
operators do not evaluate \fIexpression2\fP if the value of
\fIexpression1\fP is sufficient to determine the return value of
the entire conditional expression.
.RE
.TP
-\fBfor\fP \fIname\fP [ \fBin\fP \fIword\fP ] ; \fBdo\fP \fIlist\fP ; \fBdone\fP
+\fBfor\fP \fIname\fP [ [ \fBin\fP [ \fIword ...\fP ] ] ; ] \fBdo\fP \fIlist\fP ; \fBdone\fP
The list of words following \fBin\fP is expanded, generating a list
of items.
The variable \fIname\fP is set to each element of this list
.SM
.B PARAMETERS
below). The
+.SM
.B PS3
prompt is then displayed and a line read from the standard input.
If the line consists of a number corresponding to one of
other value read causes
.I name
to be set to null. The line read is saved in the variable
+.SM
.BR REPLY .
The
.I list
pattern matches. Otherwise, it is the exit status of the
last command executed in \fIlist\fP.
.TP
-\fBif\fP \fIlist\fP; \fBthen\fP \fIlist;\fP \
+\fBif\fP \fIlist\fP; \fBthen\fP \fIlist\fP; \
[ \fBelif\fP \fIlist\fP; \fBthen\fP \fIlist\fP; ] ... \
[ \fBelse\fP \fIlist\fP; ] \fBfi\fP
The
executed, if present. The exit status is the exit status of the
last command executed, or zero if no condition tested true.
.TP
-\fBwhile\fP \fIlist\fP; \fBdo\fP \fIlist\fP; \fBdone\fP
+\fBwhile\fP \fIlist-1\fP; \fBdo\fP \fIlist-2\fP; \fBdone\fP
.PD 0
.TP
-\fBuntil\fP \fIlist\fP; \fBdo\fP \fIlist\fP; \fBdone\fP
+\fBuntil\fP \fIlist-1\fP; \fBdo\fP \fIlist-2\fP; \fBdone\fP
.PD
-The \fBwhile\fP command continuously executes the \fBdo\fP
-\fIlist\fP as long as the last command in \fIlist\fP returns
+The \fBwhile\fP command continuously executes the list
+\fIlist-2\fP as long as the last command in the list \fIlist-1\fP returns
an exit status of zero. The \fBuntil\fP command is identical
to the \fBwhile\fP command, except that the test is negated;
-the
-.B do
-.I list
+.I list-2
is executed as long as the last command in
-.I list
+.I list-1
returns a non-zero exit status.
The exit status of the \fBwhile\fP and \fBuntil\fP commands
is the exit status
-of the last \fBdo\fP \fIlist\fP command executed, or zero if
+of the last command executed in \fIlist-2\fP, or zero if
none was executed.
.SS Coprocesses
.PP
.RE
.PP
This creates a coprocess named \fINAME\fP.
-If \fINAME\fP is not supplied, the default name is \fICOPROC\fP.
+If \fINAME\fP is not supplied, the default name is \fBCOPROC\fP.
\fINAME\fP must not be supplied if \fIcommand\fP is a \fIsimple
command\fP (see above); otherwise, it is interpreted as the first word
of the simple command.
-When the coproc is executed, the shell creates an array variable (see
+When the coprocess is executed, the shell creates an array variable (see
.B Arrays
below) named \fINAME\fP in the context of the executing shell.
The standard output of
below).
The file descriptors can be utilized as arguments to shell commands
and redirections using standard word expansions.
-The process id of the shell spawned to execute the coprocess is
+The file descriptors are not available in subshells.
+The process ID of the shell spawned to execute the coprocess is
available as the value of the variable \fINAME\fP_PID.
The \fBwait\fP
builtin command may be used to wait for the coprocess to terminate.
.PP
+Since the coprocess is created as an asynchronous command,
+the \fBcoproc\fP command always returns success.
The return status of a coprocess is the exit status of \fIcommand\fP.
.SS Shell Function Definitions
.PP
executes a compound command with a new set of positional parameters.
Shell functions are declared as follows:
.TP
-[ \fBfunction\fP ] \fIname\fP () \fIcompound\-command\fP [\fIredirection\fP]
+\fIname\fP () \fIcompound\-command\fP [\fIredirection\fP]
+.PD 0
+.TP
+\fBfunction\fP \fIname\fP [()] \fIcompound\-command\fP [\fIredirection\fP]
+.PD
This defines a function named \fIname\fP.
The reserved word \fBfunction\fP is optional.
If the \fBfunction\fP reserved word is supplied, the parentheses are optional.
may be any command listed under \fBCompound Commands\fP above.
\fIcompound\-command\fP is executed whenever \fIname\fP is specified as the
name of a simple command.
+When in \fIposix mode\fP, \fIname\fP may not be the name of one of the
+POSIX \fIspecial builtins\fP.
Any redirections (see
.SM
.B REDIRECTION
backspace
.TP
.B \ee
+.TP
+.B \eE
an escape character
.TP
.B \ef
.TP
.B \e\(aq
single quote
+.TP
+.B \e\(dq
+double quote
.TP
.B \e\fInnn\fP
the eight-bit character whose value is the octal value \fInnn\fP
the eight-bit character whose value is the hexadecimal value \fIHH\fP
(one or two hex digits)
.TP
+.B \eu\fIHHHH\fP
+the Unicode (ISO/IEC 10646) character whose value is the hexadecimal value
+\fIHHHH\fP (one to four hex digits)
+.TP
+.B \eU\fIHHHHHHHH\fP
+the Unicode (ISO/IEC 10646) character whose value is the hexadecimal value
+\fIHHHHHHHH\fP (one to eight hex digits)
+.TP
.B \ec\fIx\fP
a control-\fIx\fP character
.PD
The expanded result is single-quoted, as if the dollar sign had
not been present.
.PP
-A double-quoted string preceded by a dollar sign (\fB$\fP) will cause
-the string to be translated according to the current locale.
+A double-quoted string preceded by a dollar sign (\fB$\fP\(dq\fIstring\fP\(dq)
+will cause the string to be translated according to the current locale.
If the current locale is \fBC\fP or \fBPOSIX\fP, the dollar sign
is ignored.
If the string is translated and replaced, the replacement is
and
.B local
builtin commands.
+When in \fIposix mode\fP, these builtins may appear in a command after
+one or more instances of the \fBcommand\fP builtin and retain these
+assignment statement properties.
.PP
In the context where an assignment statement is assigning a value
to a shell variable or array index, the += operator can be used to
append to or add to the variable's previous value.
-When += is applied to a variable for which the integer attribute has been
+When += is applied to a variable for which the \fIinteger\fP attribute has been
set, \fIvalue\fP is evaluated as an arithmetic expression and added to the
variable's current value, which is also evaluated.
When += is applied to an array variable using compound assignment (see
associative array.
When applied to a string-valued variable, \fIvalue\fP 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
+(see the descriptions of \fBdeclare\fP and \fBlocal\fP below)
+to create a \fInameref\fP, or a reference to another variable.
+This allows variables to be manipulated indirectly.
+Whenever the nameref variable is referenced or assigned to, the operation
+is actually performed on the variable specified by the nameref variable's
+value.
+A nameref is commonly used within shell functions to refer to a variable
+whose name is passed as an argument to the function.
+For instance, if a variable name is passed to a shell function as its first
+argument, running
+.sp .5
+.RS
+.if t \f(CWdeclare -n ref=$1\fP
+.if n declare -n ref=$1
+.RE
+.sp .5
+inside the function creates a nameref variable \fBref\fP whose value is
+the variable name passed as the first argument.
+References and assignments to \fBref\fP are treated as references and
+assignments to the variable whose name was passed as \fB$1\fP.
+If the control variable in a \fBfor\fP loop has the nameref attribute,
+the list of words can be a list of shell variables, and a name reference
+will be established for each word in the list, in turn, when the loop is
+executed.
+Array variables cannot be given the \fB\-n\fP attribute.
+However, nameref variables can reference array variables and subscripted
+array variables.
+Namerefs can be unset using the \fB\-n\fP option to the \fBunset\fP builtin.
+Otherwise, if \fBunset\fP is executed with the name of a nameref variable
+as an argument, the variable referenced by the nameref variable will be unset.
.SS Positional Parameters
.PP
A
.PD 0
.TP
.B *
-Expands to the positional parameters, starting from one. When the
-expansion occurs within double quotes, it expands to a single word
+Expands to the positional parameters, starting from one.
+When the expansion is not within double quotes, each positional parameter
+expands to a separate word.
+In contexts where it is performed, those words
+are subject to further word splitting and pathname expansion.
+When the expansion occurs within double quotes, it expands to a single word
with the value of each parameter separated by the first character
of the
.SM
subshell.
.TP
.B !
-Expands to the process ID of the most recently executed background
-(asynchronous) command.
+Expands to the process ID of the job most recently placed into the
+background, whether executed as an asynchronous command or using
+the \fBbg\fP builtin (see
+.SM
+.B "JOB CONTROL"
+below).
.TP
.B 0
Expands to the name of the shell or shell script. This is set at
.B $0
is set to the first argument after the string to be
executed, if one is present. Otherwise, it is set
-to the file name used to invoke
+to the filename used to invoke
.BR bash ,
as given by argument zero.
.TP
.PD 0
.TP
.B BASH
-Expands to the full file name used to invoke this instance of
+Expands to the full filename used to invoke this instance of
.BR bash .
.TP
+.B BASHOPTS
+A colon-separated list of enabled shell options. Each word in
+the list is a valid argument for the
+.B \-s
+option to the
+.B shopt
+builtin command (see
+.SM
+.B "SHELL BUILTIN COMMANDS"
+below). The options appearing in
+.SM
+.B BASHOPTS
+are those reported as
+.I on
+by \fBshopt\fP.
+If this variable is in the environment when
+.B bash
+starts up, each shell option in the list will be enabled before
+reading any startup files.
+This variable is read-only.
+.TP
.B BASHPID
-Expands to the process id of the current \fBbash\fP process.
+Expands to the process ID of the current \fBbash\fP process.
This differs from \fB$$\fP under certain circumstances, such as subshells
that do not require \fBbash\fP to be re-initialized.
.TP
.B BASH_ALIASES
An associative array variable whose members correspond to the internal
-list of aliases as maintained by the \fBalias\fP builtin
+list of aliases as maintained by the \fBalias\fP builtin.
Elements added to this array appear in the alias list; unsetting array
elements cause aliases to be removed from the alias list.
.TP
parameters to the current subroutine (shell function or script executed
with \fB.\fP or \fBsource\fP) is at the top of the stack.
When a subroutine is executed, the number of parameters passed is pushed onto
-\fBBASH_ARGC\fP.
-The shell sets \fBBASH_ARGC\fP only when in extended debugging mode
-(see the description of the
+.SM
+.BR BASH_ARGC .
+The shell sets
+.SM
+.B BASH_ARGC
+only when in extended debugging mode (see the description of the
.B extdebug
option to the
.B shopt
execution call stack. The final parameter of the last subroutine call
is at the top of the stack; the first parameter of the initial call is
at the bottom. When a subroutine is executed, the parameters supplied
-are pushed onto \fBBASH_ARGV\fP.
-The shell sets \fBBASH_ARGV\fP only when in extended debugging mode
+are pushed onto
+.SM
+.BR BASH_ARGV .
+The shell sets
+.SM
+.B BASH_ARGV
+only when in extended debugging mode
(see the description of the
.B extdebug
option to the
.TP
.B BASH_LINENO
An array variable whose members are the line numbers in source files
-corresponding to each member of \fBFUNCNAME\fP.
+where each corresponding member of
+.SM
+.B FUNCNAME
+was invoked.
\fB${BASH_LINENO[\fP\fI$i\fP\fB]}\fP is the line number in the source
-file where \fB${FUNCNAME[\fP\fI$i\fP\fB]}\fP was called
+file (\fB${BASH_SOURCE[\fP\fI$i+1\fP\fB]}\fP) where
+\fB${FUNCNAME[\fP\fI$i\fP\fB]}\fP was called
(or \fB${BASH_LINENO[\fP\fI$i-1\fP\fB]}\fP if referenced within another
shell function).
-The corresponding source file name is \fB${BASH_SOURCE[\fP\fI$i\fP\fB]}\fP.
-Use \fBLINENO\fP to obtain the current line number.
+Use
+.SM
+.B LINENO
+to obtain the current line number.
.TP
.B BASH_REMATCH
An array variable whose members are assigned by the \fB=~\fP binary
This variable is read-only.
.TP
.B BASH_SOURCE
-An array variable whose members are the source filenames corresponding
-to the elements in the \fBFUNCNAME\fP array variable.
+An array variable whose members are the source filenames
+where the corresponding shell function names in the
+.SM
+.B FUNCNAME
+array variable are defined.
+The shell function
+\fB${FUNCNAME[\fP\fI$i\fP\fB]}\fP is defined in the file
+\fB${BASH_SOURCE[\fP\fI$i\fP\fB]}\fP and called from
+\fB${BASH_SOURCE[\fP\fI$i+1\fP\fB]}\fP.
.TP
.B BASH_SUBSHELL
-Incremented by one each time a subshell or subshell environment is spawned.
+Incremented by one within each subshell or subshell environment when
+the shell begins executing in that environment.
The initial value is 0.
.TP
.B BASH_VERSINFO
The values assigned to the array members are as follows:
.sp .5
.RS
-.PD 0
.TP 24
.B BASH_VERSINFO[\fR0\fP]
The major version number (the \fIrelease\fP).
The release status (e.g., \fIbeta1\fP).
.TP
.B BASH_VERSINFO[\fR5\fP]
-The value of \fBMACHTYPE\fP.
-.PD
+The value of
+.SM
+.BR MACHTYPE .
.RE
.TP
.B BASH_VERSION
An array variable (see \fBArrays\fP below) consisting of the individual
words in the current command line.
The line is split into words as \fBreadline\fP would split it, using
-\fBCOMP_WORDBREAKS\fP as described above.
+.SM
+.B COMP_WORDBREAKS
+as described above.
This variable is available only in shell functions invoked by the
programmable completion facilities (see \fBProgrammable Completion\fP
below).
.TP
+.B COPROC
+An array variable (see \fBArrays\fP below) created to hold the file descriptors
+for output from and input to an unnamed coprocess (see \fBCoprocesses\fP
+above).
+.TP
.B DIRSTACK
An array variable (see
.B Arrays
currently in the execution call stack.
The element with index 0 is the name of any currently-executing
shell function.
-The bottom-most element is
+The bottom-most element (the one with the highest index) is
.if t \f(CW"main"\fP.
.if n "main".
This variable exists only when a shell function is executing.
.B FUNCNAME
is unset, it loses its special properties, even if it is
subsequently reset.
+.if t .sp 0.5
+.if n .sp 1
+This variable can be used with \fBBASH_LINENO\fP and \fBBASH_SOURCE\fP.
+Each element of \fBFUNCNAME\fP has corresponding elements in
+\fBBASH_LINENO\fP and \fBBASH_SOURCE\fP to describe the call stack.
+For instance, \fB${FUNCNAME[\fP\fI$i\fP\fB]}\fP was called from the file
+\fB${BASH_SOURCE[\fP\fI$i+1\fP\fB]}\fP at line number
+\fB${BASH_LINENO[\fP\fI$i\fP\fB]}\fP.
+The \fBcaller\fP builtin displays the current call stack using this
+information.
.TP
.B GROUPS
An array variable containing the list of groups of which the current
is executing, in the standard GNU \fIcpu-company-system\fP format.
The default is system-dependent.
.TP
+.B MAPFILE
+An array variable (see \fBArrays\fP below) created to hold the text
+read by the \fBmapfile\fP builtin when no variable name is supplied.
+.TP
.B OLDPWD
The previous working directory as set by the
.B cd
is unset, it loses its special properties, even if it is
subsequently reset.
.TP
+.B READLINE_LINE
+The contents of the
+.B readline
+line buffer, for use with
+.if t \f(CWbind -x\fP
+.if n "bind -x"
+(see
+.SM
+.B "SHELL BUILTIN COMMANDS"
+below).
+.TP
+.B READLINE_POINT
+The position of the insertion point in the
+.B readline
+line buffer, for use with
+.if t \f(CWbind -x\fP
+.if n "bind -x"
+(see
+.SM
+.B "SHELL BUILTIN COMMANDS"
+below).
+.TP
.B REPLY
Set to the line of input read by the
.B read
.PP
.PD 0
.TP
+.B BASH_COMPAT
+The value is used to set the shell's compatibility level.
+See the description of the \fBshopt\fP builtin below under
+\fBSHELL BUILTIN COMMANDS\fP
+for a description of the various compatibility
+levels and their effects.
+The value may be a decimal number (e.g., 4.2) or an integer (e.g., 42)
+corresponding to the desired compatibility level.
+If \fBBASH_COMPAT\fP is unset or set to the empty string, the compatibility
+level is set to the default for the current version.
+If \fBBASH_COMPAT\fP is set to a value that is not one of the valid
+compatibility levels, the shell prints an error message and sets the
+compatibility level to the default for the current version.
+The valid compatibility levels correspond to the compatibility options
+accepted by the \fBshopt\fP builtin described below (for example,
+\fBcompat42\fP means that 4.2 and 42 are valid values).
+The current version is also a valid value.
+.TP
.B BASH_ENV
If this parameter is set when \fBbash\fP is executing a shell script,
its value is interpreted as a filename containing commands to
.SM
.B BASH_ENV
is subjected to parameter expansion, command substitution, and arithmetic
-expansion before being interpreted as a file name.
+expansion before being interpreted as a filename.
.SM
.B PATH
-is not used to search for the resultant file name.
+is not used to search for the resultant filename.
+.TP
+.B BASH_XTRACEFD
+If set to an integer corresponding to a valid file descriptor, \fBbash\fP
+will write the trace output generated when
+.if t \f(CWset -x\fP
+.if n \fIset -x\fP
+is enabled to that file descriptor.
+The file descriptor is closed when
+.SM
+.B BASH_XTRACEFD
+is unset or assigned a new value.
+Unsetting
+.SM
+.B BASH_XTRACEFD
+or assigning it the empty string causes the
+trace output to be sent to the standard error.
+Note that setting
+.SM
+.B BASH_XTRACEFD
+to 2 (the standard error file
+descriptor) and then unsetting it will result in the standard error
+being closed.
.TP
.B CDPATH
The search path for the
.if t \f(CW".:~:/usr"\fP.
.if n ".:~:/usr".
.TP
+.B CHILD_MAX
+Set the number of exited child status values for the shell to remember.
+Bash will not allow this value to be decreased below a POSIX-mandated
+minimum, and there is a maximum value (currently 8192) that this may
+not exceed.
+The minimum value is system-dependent.
+.TP
.B COLUMNS
-Used by the \fBselect\fP builtin command to determine the terminal width
-when printing selection lists. Automatically set upon receipt of a SIGWINCH.
+Used by the \fBselect\fP compound command to determine the terminal width
+when printing selection lists.
+Automatically set if the
+.B checkwinsize
+option is enabled or in an interactive shell upon receipt of a
+.SM
+.BR SIGWINCH .
.TP
.B COMPREPLY
An array variable from which \fBbash\fP reads the possible completions
generated by a shell function invoked by the programmable completion
facility (see \fBProgrammable Completion\fP below).
+Each array element contains one possible completion.
.TP
.B EMACS
If \fBbash\fP finds this variable in the environment when the shell starts
with value
.if t \f(CWt\fP,
.if n "t",
-it assumes that the shell is running in an emacs shell buffer and disables
+it assumes that the shell is running in an Emacs shell buffer and disables
line editing.
.TP
+.B ENV
+Similar to
+.SM
+.BR BASH_ENV ;
+used when the shell is invoked in POSIX mode.
+.TP
.B FCEDIT
The default editor for the
.B fc
.if t \f(CW".o:~"\fP.
.if n ".o:~".
.TP
+.B FUNCNEST
+If set to a numeric value greater than 0, defines a maximum function
+nesting level. Function invocations that exceed this nesting level
+will cause the current command to abort.
+.TP
.B GLOBIGNORE
A colon-separated list of patterns defining the set of filenames to
be ignored by pathname expansion.
causes all previous lines matching the current line to be removed from
the history list before that line is saved.
Any value not in the above list is ignored.
-If \fBHISTCONTROL\fP is unset, or does not include a valid value,
+If
+.SM
+.B HISTCONTROL
+is unset, or does not include a valid value,
all lines read by the shell parser are saved on the history list,
subject to the value of
+.SM
.BR HISTIGNORE .
The second and subsequent lines of a multi-line compound command are
not tested, and are added to the history regardless of the value of
+.SM
.BR HISTCONTROL .
.TP
.B HISTFILE
.SM
.B HISTORY
below). The default value is \fI~/.bash_history\fP. If unset, the
-command history is not saved when an interactive shell exits.
+command history is not saved when a shell exits.
.TP
.B HISTFILESIZE
The maximum number of lines contained in the history file. When this
variable is assigned a value, the history file is truncated, if
-necessary, by removing the oldest entries,
-to contain no more than that number of lines. The default
-value is 500. The history file is also truncated to this size after
-writing it when an interactive shell exits.
+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.
+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 \fBHISTSIZE\fP
+after reading any startup files.
.TP
.B HISTIGNORE
A colon-separated list of patterns used to decide which command lines
beginning of the line and must match the complete line (no implicit
`\fB*\fP' is appended). Each pattern is tested against the line
after the checks specified by
+.SM
.B HISTCONTROL
are applied.
In addition to the normal shell pattern matching characters, `\fB&\fP'
backslash; the backslash is removed before attempting a match.
The second and subsequent lines of a multi-line compound command are
not tested, and are added to the history regardless of the value of
+.SM
.BR HISTIGNORE .
.TP
.B HISTSIZE
The number of commands to remember in the command history (see
.SM
.B HISTORY
-below). The default value is 500.
+below).
+If the value is 0, commands are not saved in the history list.
+Numeric values less than zero result in every command being saved
+on the history list (there is no limit).
+The shell sets the default value to 500 after reading any startup files.
.TP
.B HISTTIMEFORMAT
If this variable is set and not null, its value is used as a format string
If
.SM
.B HOSTFILE
-is set, but has no value, \fBbash\fP attempts to read
+is set, but has no value, or does not name a readable file,
+\fBbash\fP attempts to read
.FN /etc/hosts
to obtain the list of possible hostname completions.
When
selected with a variable starting with \fBLC_\fP.
.TP
.B LC_ALL
-This variable overrides the value of \fBLANG\fP and any other
+This variable overrides the value of
+.SM
+.B LANG
+and any other
\fBLC_\fP variable specifying a locale category.
.TP
.B LC_COLLATE
This variable determines the locale category used for number formatting.
.TP
.B LINES
-Used by the \fBselect\fP builtin command to determine the column length
-for printing selection lists. Automatically set upon receipt of a SIGWINCH.
+Used by the \fBselect\fP compound command to determine the column length
+for printing selection lists.
+Automatically set if the
+.B checkwinsize
+option is enabled or in an interactive shell upon receipt of a
+.SM
+.BR SIGWINCH .
.TP
.B MAIL
-If this parameter is set to a file name and the
+If this parameter is set to a file or directory name and the
.SM
.B MAILPATH
variable is not set,
.B bash
-informs the user of the arrival of mail in the specified file.
+informs the user of the arrival of mail in the specified file or
+Maildir-format directory.
.TP
.B MAILCHECK
Specifies how
greater than or equal to zero, the shell disables mail checking.
.TP
.B MAILPATH
-A colon-separated list of file names to be checked for mail.
+A colon-separated list of filenames to be checked for mail.
The message to be printed when mail arrives in a particular file
-may be specified by separating the file name from the message with a `?'.
+may be specified by separating the filename from the message with a `?'.
When used in the text of the message, \fB$_\fP expands to the name of
the current mailfile.
Example:
.SM
.B COMMAND EXECUTION
below).
-A zero-length (null) directory name in the value of \fBPATH\fP indicates the
-current directory.
+A zero-length (null) directory name in the value of
+.SM
+.B PATH
+indicates the current directory.
A null directory name may appear as two adjacent colons, or as an initial
or trailing colon.
The default path is system-dependent,
and is set by the administrator who installs
.BR bash .
A common value is
-.if t \f(CW/usr/gnu/bin:/usr/local/bin:/usr/ucb:/bin:/usr/bin\fP.
-.if n ``/usr/gnu/bin:/usr/local/bin:/usr/ucb:/bin:/usr/bin''.
+.if t \f(CW/usr/local/bin:/usr/local/sbin:/usr/bin:/usr/sbin:/bin:/sbin\fP.
+.if n ``/usr/local/bin:/usr/local/sbin:/usr/bin:/usr/sbin:/bin:/sbin''.
.TP
.B POSIXLY_CORRECT
If this variable is in the environment when \fBbash\fP starts, the shell
.TP
.B PROMPT_DIRTRIM
If set to a number greater than zero, the value is used as the number of
-trailing directory components to retain when expanding the \fB\ew\fB and
+trailing directory components to retain when expanding the \fB\ew\fP and
\fB\eW\fP prompt string escapes (see
.SM
.B PROMPTING
.TP
.B PS2
The value of this parameter is expanded as with
+.SM
.B PS1
and used as the secondary prompt string. The default is
``\fB> \fP''.
.TP
.B PS4
The value of this parameter is expanded as with
+.SM
.B PS1
and the value is printed before each command
.B bash
included.
.IP
If this variable is not set, \fBbash\fP acts as if it had the
-value \fB$\(aq\enreal\et%3lR\enuser\et%3lU\ensys\t%3lS\(aq\fP.
+value \fB$\(aq\enreal\et%3lR\enuser\et%3lU\ensys\et%3lS\(aq\fP.
If the value is null, no timing information is displayed.
A trailing newline is added when the format string is displayed.
+.PD 0
.TP
.B TMOUT
-If set to a value greater than zero, \fBTMOUT\fP is treated as the
+If set to a value greater than zero,
+.SM
+.B TMOUT
+is treated as the
default timeout for the \fBread\fP builtin.
The \fBselect\fP command terminates if input does not arrive
-after \fBTMOUT\fP seconds when input is coming from a terminal.
+after
+.SM
+.B TMOUT
+seconds when input is coming from a terminal.
In an interactive shell, the value is interpreted as the
-number of seconds to wait for input after issuing the primary prompt.
+number of seconds to wait for a line of input after issuing the
+primary prompt.
.B Bash
-terminates after waiting for that number of seconds if input does
-not arrive.
+terminates after waiting for that number of seconds if a complete
+line of input does not arrive.
.TP
.B TMPDIR
-If set, \fBBash\fP uses its value as the name of a directory in which
-\fBBash\fP creates temporary files for the shell's use.
+If set, \fBbash\fP uses its value as the name of a directory in which
+\fBbash\fP creates temporary files for the shell's use.
.TP
.B auto_resume
This variable controls how the shell interacts with the user and
Indexed arrays are referenced using integers (including arithmetic
expressions) and are zero-based; associative arrays are referenced
using arbitrary strings.
+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. 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
+is treated as an arithmetic expression that must evaluate to a number.
+To explicitly declare an indexed array, use
.B declare \-a \fIname\fP
(see
.SM
Arrays are assigned to using compound assignments of the form
\fIname\fP=\fB(\fPvalue\fI1\fP ... value\fIn\fP\fB)\fP, where each
\fIvalue\fP is of the form [\fIsubscript\fP]=\fIstring\fP.
-Indexed array assignments do not require the bracket and subscript.
+Indexed array assignments do not require anything but \fIstring\fP.
When assigning to indexed arrays, if the optional brackets and subscript
are supplied, that index is assigned to;
otherwise the index of the element assigned is the last index assigned
.B declare
builtin. Individual array elements may be assigned to using the
\fIname\fP[\fIsubscript\fP]=\fIvalue\fP syntax introduced above.
+When assigning to an indexed array, if
+.I name
+is subscripted by a negative number, that number is
+interpreted as relative to one greater than the maximum index of
+\fIname\fP, so negative indices count back from the end of the
+array, and an index of \-1 references the last element.
.PP
Any element of an array may be referenced using
${\fIname\fP[\fIsubscript\fP]}. The braces are required to avoid
\fB@\fP, the expansion is the number of elements in the array.
Referencing an array variable without a subscript is equivalent to
referencing the array with a subscript of 0.
+If the
+.I subscript
+used to reference an element of an indexed array
+evaluates to a number less than zero, it is
+interpreted as relative to one greater than the maximum index of the array,
+so negative indices count back from the end of the
+array, and an index of \-1 references the last element.
+.PP
+An array variable is considered set if a subscript has been assigned a
+value. The null string is a valid value.
+.PP
+It is possible to obtain the keys (indices) of an array as well as the values.
+${\fB!\fP\fIname\fP[\fI@\fP]} and ${\fB!\fP\fIname\fP[\fI*\fP]}
+expand to the indices assigned in array variable \fIname\fP.
+The treatment when in double quotes is similar to the expansion of the
+special parameters \fI@\fP and \fI*\fP within double quotes.
.PP
The
.B unset
builtin is used to destroy arrays. \fBunset\fP \fIname\fP[\fIsubscript\fP]
destroys the array element at index \fIsubscript\fP.
-Care must be taken to avoid unwanted side effects caused by filename
-generation.
+Negative subscripts to indexed arrays are interpreted as described above.
+Care must be taken to avoid unwanted side effects caused by pathname
+expansion.
\fBunset\fP \fIname\fP, where \fIname\fP is an array, or
\fBunset\fP \fIname\fP[\fIsubscript\fP], where
\fIsubscript\fP is \fB*\fP or \fB@\fP, removes the entire array.
option to specify an indexed array and a
.B \-A
option to specify an associative array.
+If both options are supplied,
+.B \-A
+takes precedence.
The
.B read
builtin accepts a
and
.IR "pathname expansion" .
.PP
-The order of expansions is: brace expansion, tilde expansion,
-parameter, variable and arithmetic expansion and
-command substitution
-(done in a left-to-right fashion), word splitting, and pathname
-expansion.
+The order of expansions is:
+brace expansion;
+tilde expansion, parameter and variable expansion, arithmetic expansion,
+and command substitution (done in a left-to-right fashion);
+word splitting;
+and pathname expansion.
.PP
On systems that can support it, there is an additional expansion
available: \fIprocess substitution\fP.
+This is performed at the
+same time as tilde, parameter, variable, and arithmetic expansion and
+command substitution.
.PP
Only brace expansion, word splitting, and pathname expansion
can change the number of words of the expansion; other expansions
When integers are supplied, the expression expands to each number between
\fIx\fP and \fIy\fP, inclusive.
Supplied integers may be prefixed with \fI0\fP to force each term to have the
-same width. When either \fIx\fP or \fPy\fP begins with a zero, the shell
+same width.
+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.
When characters are supplied, the expression expands to each character
-lexicographically between \fIx\fP and \fIy\fP, inclusive. Note that
-both \fIx\fP and \fIy\fP must be of the same type.
+lexicographically between \fIx\fP and \fIy\fP, inclusive,
+using the default C locale.
+Note that both \fIx\fP and \fIy\fP must be of the same type.
When the increment is supplied, it is used as the difference between
each term. The default increment is 1 or -1 as appropriate.
.PP
or the first
.BR = .
In these cases, tilde expansion is also performed.
-Consequently, one may use file names with tildes in assignments to
+Consequently, one may use filenames with tildes in assignments to
.SM
.BR PATH ,
.SM
.I parameter
is followed by a character which is not to be
interpreted as part of its name.
+The \fIparameter\fP is a shell parameter as described above
+\fBPARAMETERS\fP) or an array reference (\fBArrays\fP).
.PD
.PP
-If the first character of \fIparameter\fP is an exclamation point,
-a level of variable indirection is introduced.
+If the first character of \fIparameter\fP is an exclamation point (\fB!\fP),
+it introduces a level of variable indirection.
\fBBash\fP uses the value of the variable formed from the rest of
\fIparameter\fP as the name of the variable; this variable is then
expanded and that value is used in the rest of the substitution, rather
than the value of \fIparameter\fP itself.
This is known as \fIindirect expansion\fP.
-The exceptions to this are the expansions of ${!\fIprefix\fP*} and
+The exceptions to this are the expansions of ${\fB!\fP\fIprefix\fP\fB*\fP} and
${\fB!\fP\fIname\fP[\fI@\fP]} described below.
The exclamation point must immediately follow the left brace in order to
introduce indirection.
In each of the cases below, \fIword\fP is subject to tilde expansion,
parameter expansion, command substitution, and arithmetic expansion.
.PP
-When not performing substring expansion, using the forms documented below,
+When not performing substring expansion, using the forms documented below
+(e.g., \fB:-\fP),
\fBbash\fP tests for a parameter that is unset or null. Omitting the colon
results in a test only for a parameter that is unset.
.PP
.TP
${\fIparameter\fP\fB:\fP\fIoffset\fP\fB:\fP\fIlength\fP}
.PD
-\fBSubstring Expansion.\fP
-Expands to up to \fIlength\fP characters of \fIparameter\fP
+\fBSubstring Expansion\fP.
+Expands to up to \fIlength\fP characters of the value of \fIparameter\fP
starting at the character specified by \fIoffset\fP.
-If \fIlength\fP is omitted, expands to the substring of
-\fIparameter\fP starting at the character specified by \fIoffset\fP.
+If \fIparameter\fP is \fB@\fP, an indexed array subscripted by
+\fB@\fP or \fB*\fP, or an associative array name, the results differ as
+described below.
+If \fIlength\fP is omitted, expands to the substring of the value of
+\fIparameter\fP starting at the character specified by \fIoffset\fP
+and extending to the end of the value.
\fIlength\fP and \fIoffset\fP are arithmetic expressions (see
.SM
.B
ARITHMETIC EVALUATION
below).
-\fIlength\fP must evaluate to a number greater than or equal to zero.
+.sp 1
If \fIoffset\fP evaluates to a number less than zero, the value
-is used as an offset from the end of the value of \fIparameter\fP.
+is used as an offset in characters
+from the end of the value of \fIparameter\fP.
+If \fIlength\fP evaluates to a number less than zero,
+it is interpreted as an offset in characters
+from the end of the value of \fIparameter\fP rather than
+a number of characters, and the expansion is the characters between
+\fIoffset\fP and that result.
+Note that a negative offset must be separated from the colon by at least
+one space to avoid being confused with the \fB:-\fP expansion.
+.sp 1
If \fIparameter\fP is \fB@\fP, the result is \fIlength\fP positional
parameters beginning at \fIoffset\fP.
+A negative \fIoffset\fP is taken relative to one greater than the greatest
+positional parameter, so an offset of -1 evaluates to the last positional
+parameter.
+It is an expansion error if \fIlength\fP evaluates to a number less than
+zero.
+.sp 1
If \fIparameter\fP is an indexed array name subscripted by @ or *,
the result is the \fIlength\fP
members of the array beginning with ${\fIparameter\fP[\fIoffset\fP]}.
A negative \fIoffset\fP is taken relative to one greater than the maximum
index of the specified array.
+It is an expansion error if \fIlength\fP evaluates to a number less than
+zero.
+.sp 1
Substring expansion applied to an associative array produces undefined
results.
-Note that a negative offset must be separated from the colon by at least
-one space to avoid being confused with the :- expansion.
+.sp 1
Substring indexing is zero-based unless the positional parameters
are used, in which case the indexing starts at 1 by default.
If \fIoffset\fP is 0, and the positional parameters are used, \fB$0\fP is
.TP
${\fB!\fP\fIprefix\fP\fB@\fP}
.PD
-\fBNames matching prefix.\fP
+\fBNames matching prefix\fP.
Expands to the names of variables whose names begin with \fIprefix\fP,
separated by the first character of the
.SM
.TP
${\fB!\fP\fIname\fP[\fI*\fP]}
.PD
-\fBList of array keys.\fP
+\fBList of array keys\fP.
If \fIname\fP is an array variable, expands to the list of array indices
(keys) assigned in \fIname\fP.
If \fIname\fP is not an array, expands to 0 if \fIname\fP is set and null
key expands to a separate word.
.TP
${\fB#\fP\fIparameter\fP}
-\fBParameter length.\fP
+\fBParameter length\fP.
The length in characters of the value of \fIparameter\fP is substituted.
If
.I parameter
or
.BR @ ,
the value substituted is the number of elements in the array.
+If
+.I parameter
+is an indexed array name subscripted by a negative number, that number is
+interpreted as relative to one greater than the maximum index of
+\fIparameter\fP, so negative indices count back from the end of the
+array, and an index of \-1 references the last element.
.TP
${\fIparameter\fP\fB#\fP\fIword\fP}
.PD 0
.TP
${\fIparameter\fP\fB##\fP\fIword\fP}
.PD
-\fBRemove matching prefix pattern.\fP
+\fBRemove matching prefix pattern\fP.
The
.I word
is expanded to produce a pattern just as in pathname
.TP
${\fIparameter\fP\fB%%\fP\fIword\fP}
.PD
-\fBRemove matching suffix pattern.\fP
+\fBRemove matching suffix pattern\fP.
The \fIword\fP is expanded to produce a pattern just as in
pathname expansion.
If the pattern matches a trailing portion of the expanded value of
array in turn, and the expansion is the resultant list.
.TP
${\fIparameter\fP\fB/\fP\fIpattern\fP\fB/\fP\fIstring\fP}
-\fBPattern substitution.\fP
+\fBPattern substitution\fP.
The \fIpattern\fP is expanded to produce a pattern just as in
pathname expansion.
\fIParameter\fP is expanded and the longest match of \fIpattern\fP
.TP
${\fIparameter\fP\fB,,\fP\fIpattern\fP}
.PD
-\fBCase modification.\fP
+\fBCase modification\fP.
This expansion modifies the case of alphabetic characters in \fIparameter\fP.
The \fIpattern\fP is expanded to produce a pattern just as in
pathname expansion.
+Each character in the expanded value of \fIparameter\fP is tested against
+\fIpattern\fP, and, if it matches the pattern, its case is converted.
+The pattern should not attempt to match more than one character.
The \fB^\fP operator converts lowercase letters matching \fIpattern\fP
to uppercase; the \fB,\fP operator converts matching uppercase letters
to lowercase.
The \fB^^\fP and \fB,,\fP expansions convert each matched character in the
expanded value; the \fB^\fP and \fB,\fP expansions match and convert only
-the first character in the expanded value..
+the first character in the expanded value.
If \fIpattern\fP is omitted, it is treated like a \fB?\fP, which matches
every character.
If
.PP
\fICommand substitution\fP allows the output of a command to replace
the command name. There are two forms:
-.PP
.RS
.PP
\fB$(\fP\fIcommand\fP\|\fB)\fP
.I expression
is treated as if it were within double quotes, but a double quote
inside the parentheses is not treated specially.
-All tokens in the expression undergo parameter expansion, string
-expansion, command substitution, and quote removal.
+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.
.PP
The evaluation is performed according to the rules listed below under
.SM
.B IFS
as a delimiter, and splits the results of the other
-expansions into words on these characters. If
+expansions into words using these characters as field terminators.
+If
.SM
.B IFS
is unset, or its
regarded as a
.IR pattern ,
and replaced with an alphabetically sorted list of
-file names matching the pattern.
-If no matching file names are found,
+filenames matching the pattern
+(see
+.SM
+.B "Pattern Matching"
+below).
+If no matching filenames are found,
and the shell option
.B nullglob
is not enabled, the word is left unchanged.
The
.SM
.B GLOBIGNORE
-shell variable may be used to restrict the set of file names matching a
+shell variable may be used to restrict the set of filenames matching a
.IR pattern .
If
.SM
.B GLOBIGNORE
-is set, each matching file name that also matches one of the patterns in
+is set, each matching filename that also matches one of the patterns in
.SM
.B GLOBIGNORE
is removed from the list of matches.
-The file names
+The filenames
.B ``.''
and
.B ``..''
.B GLOBIGNORE
to a non-null value has the effect of enabling the
.B dotglob
-shell option, so all other file names beginning with a
+shell option, so all other filenames beginning with a
.B ``.''
will match.
-To get the old behavior of ignoring file names beginning with a
+To get the old behavior of ignoring filenames beginning with a
.BR ``.'' ,
make
.B ``.*''
The special pattern characters have the following meanings:
.PP
.PD 0
+.RS
.TP
.B *
Matches any string, including the null string.
When the \fBglobstar\fP shell option is enabled, and \fB*\fP is used in
-a filename expansion context, two adjacent \fB*\fPs used as a single
+a pathname expansion context, two adjacent \fB*\fPs used as a single
pattern will match all files and zero or more directories and
subdirectories.
If followed by a \fB/\fP, two adjacent \fB*\fPs will match only directories
Matches any one of the enclosed characters. A pair of characters
separated by a hyphen denotes a
\fIrange expression\fP;
-any character that sorts between those two characters, inclusive,
+any character that falls between those two characters, inclusive,
using the current locale's collating sequence and character set,
is matched. If the first character following the
.B [
.B ^
then any character not enclosed is matched.
The sorting order of characters in range expressions is determined by
-the current locale and the value of the \fBLC_COLLATE\fP shell variable,
-if set.
+the current locale and the values of the
+.SM
+.B LC_COLLATE
+or
+.SM
+.B LC_ALL
+shell variables, if set.
+To obtain the traditional interpretation of range expressions, where
+.B [a\-d]
+is equivalent to
+.BR [abcd] ,
+set value of the
+.B LC_ALL
+shell variable to
+.BR C ,
+or enable the
+.B globasciiranges
+shell option.
A
.B \-
may be matched by including it as the first or last character
the syntax \fB[.\fP\fIsymbol\fP\fB.]\fP matches the collating symbol
\fIsymbol\fP.
.RE
+.RE
.PD
.PP
If the \fBextglob\fP shell option is enabled using the \fBshopt\fP
may be
.I redirected
using a special notation interpreted by the shell.
-Redirection may also be used to open and close files for the
-current shell execution environment. The following redirection
+Redirection allows commands' file handles to be
+duplicated, opened, closed,
+made to refer to different files,
+and can change the files the command reads from and writes to.
+Redirection may also be used to modify file handles in the
+current shell execution environment.
+The following redirection
operators may precede or appear anywhere within a
.I simple command
or may follow a
Redirections are processed in the order they appear, from
left to right.
.PP
+Each redirection that may be preceded by a file descriptor number
+may instead be preceded by a word of the form {\fIvarname\fP}.
+In this case, for each redirection operator except
+>&- and <&-, the shell will allocate a file descriptor greater
+than or equal to 10 and assign it to \fIvarname\fP.
+If >&- or <&- is preceded
+by {\fIvarname\fP}, the value of \fIvarname\fP defines the file
+descriptor to close.
+.PP
In the following descriptions, if the file descriptor number is
omitted, and the first character of the redirection operator is
.BR < ,
1).
.PP
The word following the redirection operator in the following
-descriptions, unless otherwise noted, is subjected to brace expansion,
-tilde expansion, parameter expansion, command substitution, arithmetic
-expansion, quote removal, pathname expansion, and word splitting.
+descriptions, unless otherwise noted, is subjected to
+brace expansion, tilde expansion, parameter and variable expansion,
+command substitution, arithmetic expansion, quote removal,
+pathname expansion, and word splitting.
If it expands to more than one word,
.B bash
reports an error.
.B /dev/tcp/\fIhost\fP/\fIport\fP
If \fIhost\fP is a valid hostname or Internet address, and \fIport\fP
is an integer port number or service name, \fBbash\fP attempts to open
-a TCP connection to the corresponding socket.
+the corresponding TCP socket.
.TP
.B /dev/udp/\fIhost\fP/\fIport\fP
If \fIhost\fP is a valid hostname or Internet address, and \fIport\fP
is an integer port number or service name, \fBbash\fP attempts to open
-a UDP connection to the corresponding socket.
+the corresponding UDP socket.
.PD
.RE
.PP
\fB>\fP\fIword\fP 2\fB>&\fP1
.RE
.PP
+When using the second form, \fIword\fP may not expand to a number or
+\fB\-\fP. If it does, other redirection operators apply
+(see \fBDuplicating File Descriptors\fP below) for compatibility
+reasons.
.SS Appending Standard Output and Standard Error
.PP
This construct allows both the
.PP
\fB>>\fP\fIword\fP 2\fB>&\fP1
.RE
+.PP
+(see \fBDuplicating File Descriptors\fP below).
.SS Here Documents
.PP
This type of redirection instructs the shell to read input from the
.fi
.RE
.PP
-No parameter expansion, command substitution, arithmetic expansion,
-or pathname expansion is performed on
+No parameter and variable expansion, command substitution,
+arithmetic expansion, or pathname expansion is performed on
.IR word .
If any characters in
.I word
.IR word ,
and the lines in the here-document are not expanded.
If \fIword\fP is unquoted,
-all lines of the here-document are subjected to parameter expansion,
-command substitution, and arithmetic expansion. In the latter
-case, the character sequence
+all lines of the here-document are subjected to
+parameter expansion, command substitution, and arithmetic expansion,
+the character sequence
.B \e<newline>
is ignored, and
.B \e
.fi
.RE
.PP
-The \fIword\fP is expanded and supplied to the command on its standard
-input.
+The \fIword\fP undergoes
+brace expansion, tilde expansion, parameter and variable expansion,
+command substitution, arithmetic expansion, and quote removal.
+Pathname expansion and word splitting are not performed.
+The result is supplied as a single string to the command on its
+standard input.
.SS "Duplicating File Descriptors"
.PP
The redirection operator
If the digits in
.I word
do not specify a file descriptor open for output, a redirection error occurs.
+If
+.I word
+evaluates to
+.BR \- ,
+file descriptor
+.I n
+is closed.
As a special case, if \fIn\fP is omitted, and \fIword\fP does not
-expand to one or more digits, the standard output and standard
+expand to one or more digits or \fB\-\fP, the standard output and standard
error are redirected as described previously.
.SS "Moving File Descriptors"
.PP
during its execution.
The special parameter
.B #
-is updated to reflect the change. Special parameter 0
+is updated to reflect the change. Special parameter \fB0\fP
is unchanged.
The first element of the
.SM
.B FUNCNAME
variable is set to the name of the function while the function
is executing.
+.PP
All other aspects of the shell execution
environment are identical between a function and its caller
-with the exception that the
+with these exceptions: the
.SM
.B DEBUG
and
builtin below) or the
\fB\-o functrace\fP shell option has been enabled with
the \fBset\fP builtin
-(in which case all functions inherit the \fBDEBUG\fP and \fBRETURN\fP traps).
+(in which case all functions inherit the \fBDEBUG\fP and \fBRETURN\fP traps),
+and the
+.SM
+.B ERR
+trap is not inherited unless the \fB\-o errtrace\fP shell option has
+been enabled.
.PP
Variables local to the function may be declared with the
.B local
builtin command. Ordinarily, variables and their values
are shared between the function and its caller.
.PP
+The \fBFUNCNEST\fP variable, if set to a numeric value greater
+than 0, defines a maximum function nesting level. Function
+invocations that exceed the limit cause the entire command to
+abort.
+.PP
If the builtin command
.B return
is executed in a function, the function completes and
shell's children.
Care should be taken in cases where this may cause a problem.
.PP
-Functions may be recursive. No limit is imposed on the number
-of recursive calls.
+Functions may be recursive.
+The \fBFUNCNEST\fP variable may be used to limit the depth of the
+function call stack and restrict the number of function invocations.
+By default, no limit is imposed on the number of recursive calls.
.SH "ARITHMETIC EVALUATION"
The shell allows arithmetic expressions to be evaluated, under
certain circumstances (see the \fBlet\fP and \fBdeclare\fP builtin
when it is referenced, or when a variable which has been given the
\fIinteger\fP attribute using \fBdeclare -i\fP is assigned a value.
A null value evaluates to 0.
-A shell variable need not have its integer attribute
+A shell variable need not have its \fIinteger\fP attribute
turned on to be used in an expression.
.PP
Constants with a leading 0 are interpreted as octal numbers.
A leading 0x or 0X denotes hexadecimal.
-Otherwise, numbers take the form [\fIbase#\fP]n, where \fIbase\fP
+Otherwise, numbers take the form [\fIbase#\fP]n, where the optional \fIbase\fP
is a decimal number between 2 and 64 representing the arithmetic
base, and \fIn\fP is a number in that base.
If \fIbase#\fP is omitted, then base 10 is used.
-The digits greater than 9 are represented by the lowercase letters,
+When specifying \fIn\fP,
+the digits greater< than 9 are represented by the lowercase letters,
the uppercase letters, @, and _, in that order.
If \fIbase\fP is less than or equal to 36, lowercase and uppercase
letters may be used interchangeably to represent numbers between 10
.PP
Unless otherwise specified, primaries that operate on files follow symbolic
links and operate on the target of the link, rather than the link itself.
+.if t .sp 0.5
+.if n .sp 1
+When used with \fB[[\fP, the \fB<\fP and \fB>\fP operators sort
+lexicographically using the current locale.
+The \fBtest\fP command sorts using ASCII ordering.
.sp 1
.PD 0
.TP
.B \-x \fIfile\fP
True if \fIfile\fP exists and is executable.
.TP
-.B \-O \fIfile\fP
-True if \fIfile\fP exists and is owned by the effective user id.
-.TP
.B \-G \fIfile\fP
True if \fIfile\fP exists and is owned by the effective group id.
.TP
.B \-L \fIfile\fP
True if \fIfile\fP exists and is a symbolic link.
.TP
+.B \-N \fIfile\fP
+True if \fIfile\fP exists and has been modified since it was last read.
+.TP
+.B \-O \fIfile\fP
+True if \fIfile\fP exists and is owned by the effective user id.
+.TP
.B \-S \fIfile\fP
True if \fIfile\fP exists and is a socket.
.TP
-.B \-N \fIfile\fP
-True if \fIfile\fP exists and has been modified since it was last read.
+\fIfile1\fP \fB\-ef\fP \fIfile2\fP
+True if \fIfile1\fP and \fIfile2\fP refer to the same device and
+inode numbers.
.TP
\fIfile1\fP \-\fBnt\fP \fIfile2\fP
True if \fIfile1\fP is newer (according to modification date) than \fIfile2\fP,
True if \fIfile1\fP is older than \fIfile2\fP, or if \fIfile2\fP exists
and \fIfile1\fP does not.
.TP
-\fIfile1\fP \fB\-ef\fP \fIfile2\fP
-True if \fIfile1\fP and \fIfile2\fP refer to the same device and
-inode numbers.
-.TP
.B \-o \fIoptname\fP
-True if shell option
+True if the shell option
.I optname
is enabled.
See the list of options under the description of the
.B set
builtin below.
.TP
+.B \-v \fIvarname\fP
+True if the shell variable
+.I varname
+is set (has been assigned a value).
+.TP
+.B \-R \fIvarname\fP
+True if the shell variable
+.I varname
+is set and is a name reference.
+.TP
.B \-z \fIstring\fP
True if the length of \fIstring\fP is zero.
.TP
is non-zero.
.TP
\fIstring1\fP \fB==\fP \fIstring2\fP
-True if the strings are equal. \fB=\fP may be used in place of
-\fB==\fP for strict POSIX compliance.
+.PD 0
+.TP
+\fIstring1\fP \fB=\fP \fIstring2\fP
+.PD
+True if the strings are equal. \fB=\fP should be used
+with the \fBtest\fP command for POSIX conformance.
+When used with the \fB[[\fP command, this performs pattern matching as
+described above (\fBCompound Commands\fP).
.TP
\fIstring1\fP \fB!=\fP \fIstring2\fP
True if the strings are not equal.
.TP
\fIstring1\fP \fB<\fP \fIstring2\fP
-True if \fIstring1\fP sorts before \fIstring2\fP lexicographically
-in the current locale.
+True if \fIstring1\fP sorts before \fIstring2\fP lexicographically.
.TP
\fIstring1\fP \fB>\fP \fIstring2\fP
-True if \fIstring1\fP sorts after \fIstring2\fP lexicographically
-in the current locale.
+True if \fIstring1\fP sorts after \fIstring2\fP lexicographically.
.TP
.I \fIarg1\fP \fBOP\fP \fIarg2\fP
.SM
.SH COMMAND EXECUTION ENVIRONMENT
The shell has an \fIexecution environment\fP, which consists of the
following:
-.sp 1
.IP \(bu
open files inherited by the shell at invocation, as modified by
redirections supplied to the \fBexec\fP builtin
shell aliases defined with \fBalias\fP
.IP \(bu
various process IDs, including those of background jobs, the value
-of \fB$$\fP, and the value of \fB$PPID\fP
+of \fB$$\fP, and the value of
+.SM
+.B PPID
.PP
When a simple command other than a builtin or shell function
is to be executed, it
is invoked in a separate execution environment that consists of
the following. Unless otherwise noted, the values are inherited
from the shell.
-.sp 1
+.if n .sp 1
.IP \(bu
the shell's open files, plus any modifications and additions specified
by redirections to the command
cannot affect the shell's execution environment.
.PP
Subshells spawned to execute command substitutions inherit the value of
-the \fB\-e\fP option from the parent shell. When not in posix mode,
-Bash clears the \fB\-e\fP option in such subshells.
+the \fB\-e\fP option from the parent shell. When not in \fIposix\fP mode,
+\fBbash\fP clears the \fB\-e\fP option in such subshells.
.PP
If a command is followed by a \fB&\fP and job control is not active, the
default standard input for the command is the empty file \fI/dev/null\fP.
.B bash
invokes an external command, the variable
.B _
-is set to the full file name of the command and passed to that
+is set to the full filename of the command and passed to that
command in its environment.
.SH "EXIT STATUS"
.PP
the execution of processes and continue (\fIresume\fP)
their execution at a later point. A user typically employs
this facility via an interactive interface supplied jointly
-by the system's terminal driver and
+by the operating system kernel's terminal driver and
.BR bash .
.PP
The shell associates a
.I 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 write to the
-terminal. Background processes which attempt to read from (write to) the
+Only foreground processes are allowed to read from or, if the
+user so specifies with \f(CWstty tostop\fP, write to the
+terminal.
+Background processes which attempt to read from (write to when
+\f(CWstty tostop\fP is in effect) the
terminal are sent a
.SM
.B SIGTTIN (SIGTTOU)
-signal by the terminal driver,
+signal by the kernel's terminal driver,
which, unless caught, suspends the process.
.PP
If the operating system on which
the release of \fBbash\fP, version + patch level (e.g., 2.00.0)
.TP
.B \ew
-the current working directory, with \fB$HOME\fP abbreviated with a tilde
-(uses the \fB$PROMPT_DIRTRIM\fP variable)
+the current working directory, with
+.SM
+.B $HOME
+abbreviated with a tilde
+(uses the value of the
+.SM
+.B PROMPT_DIRTRIM
+variable)
.TP
.B \eW
-the basename of the current working directory, with \fB$HOME\fP
+the basename of the current working directory, with
+.SM
+.B $HOME
abbreviated with a tilde
.TP
.B \e!
option is given at shell invocation.
Line editing is also used when using the \fB\-e\fP option to the
\fBread\fP builtin.
-By default, the line editing commands are similar to those of emacs.
+By default, the line editing commands are similar to those of Emacs.
A vi-style line editing interface is also available.
Line editing can be enabled at any time using the
.B \-o emacs
builtin.
.SS "Readline Notation"
.PP
-In this section, the emacs-style notation is used to denote
+In this section, the Emacs-style notation is used to denote
keystrokes. Control keys are denoted by C\-\fIkey\fR, e.g., C\-n
means Control\-N. Similarly,
.I meta
treated specially by the kernel's terminal driver to their readline
equivalents.
.TP
+.B colored\-stats (Off)
+If set to \fBOn\fP, readline displays possible completions using different
+colors to indicate their file type.
+The color definitions are taken from the value of the \fBLS_COLORS\fP
+environment variable.
+.TP
.B comment\-begin (``#'')
The string that is inserted when the readline
.B insert\-comment
.TP
.B editing\-mode (emacs)
Controls whether readline begins with a set of key bindings similar
-to \fIemacs\fP or \fIvi\fP.
+to \fIEmacs\fP or \fIvi\fP.
.B editing\-mode
can be set to either
.B emacs
or
.BR vi .
.TP
+.B echo\-control\-characters (On)
+When set to \fBOn\fP, on operating systems that indicate they support it,
+readline echoes a character corresponding to a signal generated from the
+keyboard.
+.TP
.B enable\-keypad (Off)
When set to \fBOn\fP, readline will try to enable the application
keypad when it is called. Some systems need this to enable the
arrow keys.
.TP
+.B enable\-meta\-key (On)
+When set to \fBOn\fP, readline will try to enable any meta modifier
+key the terminal claims to support when it is called. On many terminals,
+the meta key is used to send eight-bit characters.
+.TP
.B expand\-tilde (Off)
-If set to \fBon\fP, tilde expansion is performed when readline
+If set to \fBOn\fP, tilde expansion is performed when readline
attempts word completion.
.TP
.B history\-preserve\-point (Off)
-If set to \fBon\fP, the history code attempts to place point at the
+If set to \fBOn\fP, the history code attempts to place point at the
same location on each history line retrieved with \fBprevious-history\fP
or \fBnext-history\fP.
.TP
.B history\-size (0)
-Set the maximum number of history entries saved in the history list. If
-set to zero, the number of entries in the history list is not limited.
+Set the maximum number of history entries saved in the history list.
+If set to zero, any existing history entries are deleted and no new entries
+are saved.
+If set to a value less than zero, the number of history entries is not
+limited.
+By default, the number of history entries is not limited.
.TP
.B horizontal\-scroll\-mode (Off)
When set to \fBOn\fP, makes readline use a single line for display,
.B editing\-mode
also affects the default keymap.
.TP
+.B keyseq\-timeout (500)
+Specifies the duration \fIreadline\fP will wait for a character when reading an
+ambiguous key sequence (one that can form a complete key sequence using
+the input read so far, or can take additional input to complete a longer
+key sequence).
+If no input is received within the timeout, \fIreadline\fP will use the shorter
+but complete key sequence.
+The value is specified in milliseconds, so a value of 1000 means that
+\fIreadline\fP will wait one second for additional input.
+If this variable is set to a value less than or equal to zero, or to a
+non-numeric value, \fIreadline\fP will wait until another key is pressed to
+decide which key sequence to complete.
+.TP
.B mark\-directories (On)
If set to \fBOn\fP, completed directory names have a slash
appended.
.B match\-hidden\-files (On)
This variable, when set to \fBOn\fP, causes readline to match files whose
names begin with a `.' (hidden files) when performing filename
-completion, unless the leading `.' is
+completion.
+If set to \fBOff\fP, the leading `.' must be
supplied by the user in the filename to be completed.
.TP
+.B menu\-complete\-display\-prefix (Off)
+If set to \fBOn\fP, menu completion displays the common prefix of the
+list of possible completions (which may be empty) before cycling through
+the list.
+.TP
.B output\-meta (Off)
If set to \fBOn\fP, readline will display characters with the
eighth bit set directly rather than as a meta-prefixed escape
sorted horizontally in alphabetical order, rather than down the screen.
.TP
.B revert\-all\-at\-newline (Off)
-If set to \fBon\fP, readline will undo all changes to history lines
+If set to \fBOn\fP, readline will undo all changes to history lines
before returning when \fBaccept\-line\fP is executed. By default,
history lines may be modified and retain individual undo lists across
calls to \fBreadline\fP.
.B show\-all\-if\-ambiguous (Off)
This alters the default behavior of the completion functions. If
set to
-.BR on ,
+.BR On ,
words which have more than one possible completion cause the
matches to be listed immediately instead of ringing the bell.
.TP
This alters the default behavior of the completion functions in
a fashion similar to \fBshow\-all\-if\-ambiguous\fP.
If set to
-.BR on ,
+.BR On ,
words which have more than one possible completion without any
possible partial completion (the possible completions don't share
a common prefix) cause the matches to be listed immediately instead
of ringing the bell.
.TP
+.B show\-mode\-in\-prompt (Off)
+If set to \fBOn\fP, add a character to the beginning of the prompt
+indicating the editing mode: emacs (@), vi command (:) or vi
+insertion (+).
+.TP
+.B skip\-completed\-text (Off)
+If set to \fBOn\fP, this alters the default completion behavior when
+inserting a single match into the line. It's only active when
+performing completion in the middle of a word. If enabled, readline
+does not insert characters from the completion that match characters
+after point in the word being completed, so portions of the word
+following the cursor are not duplicated.
+.TP
.B visible\-stats (Off)
If set to \fBOn\fP, a character denoting a file's type as reported
by \fIstat\fP(2) is appended to the filename when listing possible
file can test for a particular value.
This could be used to bind key sequences to functions useful for
a specific program. For instance, the following command adds a
-key sequence that quotes the current or previous word in Bash:
+key sequence that quotes the current or previous word in \fBbash\fP:
.sp 1
.RS
.nf
.B
yank\-last\-arg (M\-.\^, M\-_\^)
Insert the last argument to the previous command (the last word of
-the previous history entry). With an argument,
-behave exactly like \fByank\-nth\-arg\fP.
+the previous history entry).
+With a numeric argument, behave exactly like \fByank\-nth\-arg\fP.
Successive calls to \fByank\-last\-arg\fP move back through the history
-list, inserting the last argument of each line in turn.
-The history expansion facilities are used to extract the last argument,
+list, inserting the last word (or the word specified by the argument to
+the first call) of each line in turn.
+Any numeric argument supplied to these successive calls determines
+the direction to move through the history. A negative argument switches
+the direction through the history (back or forward).
+The history expansion facilities are used to extract the last word,
as if the "!$" history expansion had been specified.
.TP
.B shell\-expand\-line (M\-C\-e)
.PP
.PD 0
.TP
-.B delete\-char (C\-d)
-Delete the character at point. If point is at the
-beginning of the line, there are no characters in the line, and
-the last character typed was not bound to \fBdelete\-char\fP,
-then return
+.B \fIend\-of\-file\fP (usually C\-d)
+The character indicating end-of-file as set, for example, by
+.if t \f(CWstty\fP.
+.if n ``stty''.
+If this character is read when there are no characters
+on the line, and point is at the beginning of the line, Readline
+interprets it as the end of input and returns
.SM
.BR EOF .
.TP
+.B delete\-char (C\-d)
+Delete the character at point.
+If this function is bound to the
+same character as the tty \fBEOF\fP character, as \fBC\-d\fP
+commonly is, see above for the effects.
+.TP
.B backward\-delete\-char (Rubout)
Delete the character behind the cursor. When given a numeric argument,
save the deleted text on the kill ring.
This command is intended to be bound to \fBTAB\fP, but is unbound
by default.
.TP
+.B menu\-complete\-backward
+Identical to \fBmenu\-complete\fP, but moves backward through the list
+of possible completions, as if \fBmenu\-complete\fP had been given a
+negative argument. This command is unbound by default.
+.TP
.B delete\-char\-or\-list
Deletes the character under the cursor if not at the beginning or
end of the line (like \fBdelete\-char\fP).
.B call\-last\-kbd\-macro (C\-x e)
Re-execute the last keyboard macro defined, by making the characters
in the macro appear as if typed at the keyboard.
+.TP
+.B print\-last\-kbd\-macro ()
+Print the last keyboard macro defined in a format suitable for the
+\fIinputrc\fP file.
.PD
.SS Miscellaneous
.PP
A character is read and point is moved to the previous occurrence of that
character. A negative count searches for subsequent occurrences.
.TP
+.B skip\-csi\-sequence
+Read enough characters to consume a multi-key sequence such as those
+defined for keys like Home and End. Such sequences begin with a
+Control Sequence Indicator (CSI), usually ESC\-[. If this sequence is
+bound to "\e[", keys producing such sequences will have no effect
+unless explicitly bound to a readline command, instead of inserting
+stray characters into the editing buffer. This is unbound by default,
+but usually bound to ESC\-[.
+.TP
.B insert\-comment (M\-#)
Without a numeric argument, the value of the readline
.B comment\-begin
.B glob\-complete\-word (M\-g)
The word before point is treated as a pattern for pathname expansion,
with an asterisk implicitly appended. This pattern is used to
-generate a list of matching file names for possible completions.
+generate a list of matching filenames for possible completions.
.TP
.B glob\-expand\-word (C\-x *)
The word before point is treated as a pattern for pathname expansion,
-and the list of matching file names is inserted, replacing the word.
+and the list of matching filenames is inserted, replacing the word.
If a numeric argument is supplied, an asterisk is appended before
pathname expansion.
.TP
below), the programmable completion facilities are invoked.
.PP
First, the command name is identified.
+If the command word is the empty string (completion attempted at the
+beginning of an empty line), any compspec defined with
+the \fB\-E\fP option to \fBcomplete\fP is used.
If a compspec has been defined for that command, the
compspec is used to generate the list of possible completions for the word.
If the command word is a full pathname, a compspec for the full
pathname is searched for first.
If no compspec is found for the full pathname, an attempt is made to
find a compspec for the portion following the final slash.
+If those searches do not result in a compspec, any compspec defined with
+the \fB\-D\fP option to \fBcomplete\fP is used as the default.
.PP
Once a compspec has been found, it is used to generate the list of
matching words.
.B FIGNORE
is used to filter the matches.
.PP
-Any completions specified by a filename expansion pattern to the
+Any completions specified by a pathname expansion pattern to the
\fB\-G\fP option are generated next.
The words generated by the pattern need not match the word
being completed.
.SM
.B COMP_CWORD
variables are also set.
-When the function or command is invoked, the first argument is the
-name of the command whose arguments are being completed, the
-second argument is the word being completed, and the third argument
-is the word preceding the word being completed on the current command line.
+When the function or command is invoked,
+the first argument (\fB$1\fP) is the name of the command whose arguments are
+being completed,
+the second argument (\fB$2\fP) is the word being completed,
+and the third argument (\fB$3\fP) is the word preceding the word being
+completed on the current command line.
No filtering of the generated completions against the word being completed
is performed; the function or command has complete freedom in generating
the matches.
It must put the possible completions in the
.SM
.B COMPREPLY
-array variable.
+array variable, one per array element.
.PP
Next, any command specified with the \fB\-C\fP option is invoked
in an environment equivalent to command substitution.
to completed names which are symbolic links to directories, subject to
the value of the \fBmark\-directories\fP readline variable, regardless
of the setting of the \fBmark-symlinked\-directories\fP readline variable.
+.PP
+There is some support for dynamically modifying completions. This is
+most useful when used in combination with a default completion specified
+with \fBcomplete -D\fP.
+It's possible for shell functions executed as completion
+handlers to indicate that completion should be retried by returning an
+exit status of 124. If a shell function returns 124, and changes
+the compspec associated with the command on which completion is being
+attempted (supplied as the first argument when the function is executed),
+programmable completion restarts from the beginning, with an
+attempt to find a new compspec for that command. This allows a set of
+completions to be built dynamically as completion is attempted, rather than
+being loaded all at once.
+.PP
+For instance, assuming that there is a library of compspecs, each kept in a
+file corresponding to the name of the command, the following default
+completion function would load completions dynamically:
+.PP
+\f(CW_completion_loader()
+.br
+{
+.br
+ . "/etc/bash_completion.d/$1.sh" >/dev/null 2>&1 && return 124
+.br
+}
+.br
+complete -D -F _completion_loader -o bashdefault -o default
+.br
+\fP
.SH HISTORY
When the
.B \-o history
builtin is enabled, the shell provides access to the
\fIcommand history\fP,
the list of commands previously typed.
-The value of the \fBHISTSIZE\fP variable is used as the
+The value of the
+.SM
+.B HISTSIZE
+variable is used as the
number of commands to save in a history list.
The text of the last
.SM
the number of lines specified by the value of
.SM
.BR HISTFILESIZE .
+If \fBHISTFILESIZE\fP is unset, or set to null, a non-numeric value,
+or a numeric value less than zero, the history file is not truncated.
When the history file is read,
lines beginning with the history comment character followed immediately
by a digit are interpreted as timestamps for the preceding history line.
.SM
.B HISTTIMEFORMAT
variable.
-When an interactive shell exits, the last
+When a shell with history enabled exits, the last
.SM
.B $HISTSIZE
lines are copied from the history list to
not saved.
If the
.SM
-.HISTTIMEFORMAT
+.B HISTTIMEFORMAT
variable is set, time stamps are written to the history file, marked
with the history comment character, so
they may be preserved across shell sessions.
lines. If
.SM
.B HISTFILESIZE
-is not set, no truncation is performed.
+is unset, or set to null, a non-numeric value,
+or a numeric value less than zero, the history file is not truncated.
.PP
The builtin command
.B fc
This section describes what syntax features are available. This
feature is enabled by default for interactive shells, and can be
disabled using the
-.B \+H
+.B +H
option to the
.B set
builtin command (see
.B histverify
shell option is enabled (see the description of the
.B shopt
-builtin), and
+builtin below), and
.B readline
is being used, history substitutions are not immediately passed to
the shell parser.
.PP
An event designator is a reference to a command line entry in the
history list.
+Unless the reference is absolute, events are relative to the current
+position in the history list.
.PP
.PD 0
.TP
.IR n .
.TP
.B !\-\fIn\fR
-Refer to the current command line minus
+Refer to the current command minus
.IR n .
.TP
.B !!
Refer to the previous command. This is a synonym for `!\-1'.
.TP
.B !\fIstring\fR
-Refer to the most recent command starting with
+Refer to the most recent command preceding the current position in the
+history list starting with
.IR string .
.TP
.B !?\fIstring\fR\fB[?]\fR
-Refer to the most recent command containing
+Refer to the most recent command preceding the current position in the
+history list containing
.IR string .
The trailing \fB?\fP may be omitted if
.I string
is followed immediately by a newline.
.TP
.B \d\s+2^\s-2\u\fIstring1\fP\d\s+2^\s-2\u\fIstring2\fP\d\s+2^\s-2\u
-Quick substitution. Repeat the last command, replacing
+Quick substitution. Repeat the previous command, replacing
.I string1
with
.IR string2 .
The first argument. That is, word 1.
.TP
.B $
-The last argument.
+The last word. This is usually the last argument, but will expand to the
+zeroth word if there is only one word in the line.
.TP
.B %
The word matched by the most recent `?\fIstring\fR?' search.
.PP
.TP
.B h
-Remove a trailing file name component, leaving only the head.
+Remove a trailing filename component, leaving only the head.
.TP
.B t
-Remove all leading file name components, leaving the tail.
+Remove all leading filename components, leaving the tail.
.TP
.B r
Remove a trailing suffix of the form \fI.xxx\fP, leaving the
accepts
.B \-\-
to signify the end of the options.
-For example, the \fB:\fP, \fBtrue\fP, \fBfalse\fP, and \fBtest\fP builtins
-do not accept options.
+The \fB:\fP, \fBtrue\fP, \fBfalse\fP, and \fBtest\fP builtins
+do not accept options and do not treat \fB\-\-\fP specially.
+The \fBexit\fP, \fBlogout\fP, \fBbreak\fP, \fBcontinue\fP, \fBlet\fP,
+and \fBshift\fP builtins accept and process arguments beginning with
+\fB\-\fP without requiring \fB\-\-\fP.
+Other builtins that accept arguments but are not specified as accepting
+options interpret arguments beginning with \fB\-\fP as invalid options and
+require \fB\-\-\fP to prevent this interpretation.
.sp .5
.PD 0
.TP
.IR filename .
If
.I filename
-does not contain a slash, file names in
+does not contain a slash, filenames in
.SM
.B PATH
are used to find the directory containing
job control enabled, any specified \fIjobspec\fP was not found
or was started without job control.
.TP
-\fBbind\fP [\fB\-m\fP \fIkeymap\fP] [\fB\-lpsvPSV\fP]
+\fBbind\fP [\fB\-m\fP \fIkeymap\fP] [\fB\-lpsvPSVX\fP]
.PD 0
.TP
\fBbind\fP [\fB\-m\fP \fIkeymap\fP] [\fB\-q\fP \fIfunction\fP] [\fB\-u\fP \fIfunction\fP] [\fB\-r\fP \fIkeyseq\fP]
Cause \fIshell\-command\fP to be executed whenever \fIkeyseq\fP is
entered.
When \fIshell\-command\fP is executed, the shell sets the
+.SM
.B READLINE_LINE
variable to the contents of the \fBreadline\fP line buffer and the
+.SM
.B READLINE_POINT
variable to the current location of the insertion point.
If the executed command changes the value of
+.SM
.B READLINE_LINE
or
+.SM
.BR READLINE_POINT ,
those new values will be reflected in the editing state.
+.TP
+.B \-X
+List all key sequences bound to shell commands and the associated commands
+in a format that can be reused as input.
.PD
.PP
The return value is 0 unless an unrecognized option is given or an
.TP
\fBcaller\fP [\fIexpr\fP]
Returns the context of any active subroutine call (a shell function or
-a script executed with the \fB.\fP or \fBsource\fP builtins.
+a script executed with the \fB.\fP or \fBsource\fP builtins).
Without \fIexpr\fP, \fBcaller\fP displays the line number and source
filename of the current subroutine call.
If a non-negative integer is supplied as \fIexpr\fP, \fBcaller\fP
call or \fIexpr\fP does not correspond to a valid position in the
call stack.
.TP
-\fBcd\fP [\fB\-L|-P\fP] [\fIdir\fP]
-Change the current directory to \fIdir\fP. The variable
+\fBcd\fP [\fB\-L\fP|[\fB\-P\fP [\fB\-e\fP]] [\-@]] [\fIdir\fP]
+Change the current directory to \fIdir\fP.
+if \fIdir\fP is not supplied, the value of the
.SM
.B HOME
-is the
-default
-.IR dir .
+shell variable is the default.
+Any additional arguments following \fIdir\fP are ignored.
The variable
.SM
.B CDPATH
defines the search path for the directory containing
-.IR dir .
+.IR dir :
+each directory name in
+.SM
+.B CDPATH
+is searched for \fIdir\fP.
Alternative directory names in
.SM
.B CDPATH
.B CDPATH
is not used. The
.B \-P
-option says to use the physical directory structure instead of
-following symbolic links (see also the
+option causes \fBcd\fP to use the physical directory structure
+by resolving symbolic links while traversing \fIdir\fP and
+before processing instances of \fI..\fP in \fIdir\fP (see also the
.B \-P
option to the
.B set
builtin command); the
.B \-L
-option forces symbolic links to be followed. An argument of
+option forces symbolic links to be followed by resolving the link
+after processing instances of \fI..\fP in \fIdir\fP.
+If \fI..\fP appears in \fIdir\fP, it is processed by removing the
+immediately previous pathname component from \fIdir\fP, back to a slash
+or the beginning of \fIdir\fP.
+If the
+.B \-e
+option is supplied with
+.BR \-P ,
+and the current working directory cannot be successfully determined
+after a successful directory change, \fBcd\fP will return an unsuccessful
+status.
+On systems that support it, the \fB\-@\fP option presents the extended
+attributes associated with a file as a directory.
+An argument of
.B \-
-is equivalent to
+is converted to
+.SM
+.B $OLDPWD
+before the directory change is attempted.
+If a non-empty directory name from
.SM
-.BR $OLDPWD .
-If a non-empty directory name from \fBCDPATH\fP is used, or if
+.B CDPATH
+is used, or if
\fB\-\fP is the first argument, and the directory change is
successful, the absolute pathname of the new working directory is
written to the standard output.
option is given, the search for
.I command
is performed using a default value for
+.SM
.B PATH
that is guaranteed to find all of the standard utilities.
If either the
.I command
is printed. The
.B \-v
-option causes a single word indicating the command or file name
+option causes a single word indicating the command or filename
used to invoke
.I command
to be displayed; the
The return value is true unless an invalid option is supplied, or no
matches were generated.
.TP
-\fBcomplete\fP [\fB\-abcdefgjksuv\fP] [\fB\-o\fP \fIcomp-option\fP] [\fB\-E\fP] [\fB\-A\fP \fIaction\fP] [\fB\-G\fP \fIglobpat\fP] [\fB\-W\fP \fIwordlist\fP] [\fB\-F\fP \fIfunction\fP] [\fB\-C\fP \fIcommand\fP]
+\fBcomplete\fP [\fB\-abcdefgjksuv\fP] [\fB\-o\fP \fIcomp-option\fP] [\fB\-DE\fP] [\fB\-A\fP \fIaction\fP] [\fB\-G\fP \fIglobpat\fP] [\fB\-W\fP \fIwordlist\fP] [\fB\-F\fP \fIfunction\fP] [\fB\-C\fP \fIcommand\fP]
.br
[\fB\-X\fP \fIfilterpat\fP] [\fB\-P\fP \fIprefix\fP] [\fB\-S\fP \fIsuffix\fP] \fIname\fP [\fIname ...\fP]
.PD 0
.TP
-\fBcomplete\fP \fB\-pr\fP [\fB\-E\fP] [\fIname\fP ...]
+\fBcomplete\fP \fB\-pr\fP [\fB\-DE\fP] [\fIname\fP ...]
.PD
Specify how arguments to each \fIname\fP should be completed.
If the \fB\-p\fP option is supplied, or if no options are supplied,
The \fB\-r\fP option removes a completion specification for
each \fIname\fP, or, if no \fIname\fPs are supplied, all
completion specifications.
+The \fB\-D\fP option indicates that the remaining options and actions should
+apply to the ``default'' command completion; that is, completion attempted
+on a command for which no completion has previously been defined.
The \fB\-E\fP option indicates that the remaining options and actions should
apply to ``empty'' command completion; that is, completion attempted on a
blank line.
quoting special characters, or suppressing trailing spaces).
Intended to be used with shell functions.
.TP 8
+.B noquote
+Tell readline not to quote the completed words if they are filenames
+(quoting filenames is the default).
+.TP 8
.B nospace
Tell readline not to append a space (the default) to words completed at
the end of the line.
Names of all shell variables. May also be specified as \fB\-v\fP.
.RE
.TP 8
-\fB\-G\fP \fIglobpat\fP
-The filename expansion pattern \fIglobpat\fP is expanded to generate
-the possible completions.
-.TP 8
-\fB\-W\fP \fIwordlist\fP
-The \fIwordlist\fP is split using the characters in the
-.SM
-.B IFS
-special variable as delimiters, and each resultant word is expanded.
-The possible completions are the members of the resultant list which
-match the word being completed.
-.TP 8
\fB\-C\fP \fIcommand\fP
\fIcommand\fP is executed in a subshell environment, and its output is
used as the possible completions.
\fB\-F\fP \fIfunction\fP
The shell function \fIfunction\fP is executed in the current shell
environment.
+When the function is executed,
+the first argument (\fB$1\fP) is the name of the command whose arguments are
+being completed,
+the second argument (\fB$2\fP) is the word being completed,
+and the third argument (\fB$3\fP) is the word preceding the word being
+completed on the current command line.
When it finishes, the possible completions are retrieved from the value
of the
.SM
.B COMPREPLY
array variable.
.TP 8
-\fB\-X\fP \fIfilterpat\fP
-\fIfilterpat\fP is a pattern as used for filename expansion.
-It is applied to the list of possible completions generated by the
-preceding options and arguments, and each completion matching
-\fIfilterpat\fP is removed from the list.
-A leading \fB!\fP in \fIfilterpat\fP negates the pattern; in this
-case, any completion not matching \fIfilterpat\fP is removed.
+\fB\-G\fP \fIglobpat\fP
+The pathname expansion pattern \fIglobpat\fP is expanded to generate
+the possible completions.
.TP 8
\fB\-P\fP \fIprefix\fP
\fIprefix\fP is added at the beginning of each possible completion
\fB\-S\fP \fIsuffix\fP
\fIsuffix\fP is appended to each possible completion
after all other options have been applied.
+.TP 8
+\fB\-W\fP \fIwordlist\fP
+The \fIwordlist\fP is split using the characters in the
+.SM
+.B IFS
+special variable as delimiters, and each resultant word is expanded.
+The possible completions are the members of the resultant list which
+match the word being completed.
+.TP 8
+\fB\-X\fP \fIfilterpat\fP
+\fIfilterpat\fP is a pattern as used for pathname expansion.
+It is applied to the list of possible completions generated by the
+preceding options and arguments, and each completion matching
+\fIfilterpat\fP is removed from the list.
+A leading \fB!\fP in \fIfilterpat\fP negates the pattern; in this
+case, any completion not matching \fIfilterpat\fP is removed.
.PD
.PP
The return value is true unless an invalid option is supplied, an option
an error occurs adding a completion specification.
.RE
.TP
-\fBcompopt\fP [\fB\-o\fP \fIoption\fP] [\fB+o\fP \fIoption\fP] [\fIname\fP]
+\fBcompopt\fP [\fB\-o\fP \fIoption\fP] [\fB\-DE\fP] [\fB+o\fP \fIoption\fP] [\fIname\fP]
Modify completion options for each \fIname\fP according to the
\fIoption\fPs, or for the
-currently-execution completion if no \fIname\fPs are supplied.
+currently-executing completion if no \fIname\fPs are supplied.
If no \fIoption\fPs are given, display the completion options for each
\fIname\fP or the current completion.
The possible values of \fIoption\fP are those valid for the \fBcomplete\fP
builtin described above.
-.PP
+The \fB\-D\fP option indicates that the remaining options should
+apply to the ``default'' command completion; that is, completion attempted
+on a command for which no completion has previously been defined.
+The \fB\-E\fP option indicates that the remaining options should
+apply to ``empty'' command completion; that is, completion attempted on a
+blank line.
+.sp 1
The return value is true unless an invalid option is supplied, an attempt
is made to modify the options for a \fIname\fP for which no completion
specification exists, or an output error occurs.
(the ``top-level'' loop) is resumed.
The return value is 0 unless \fIn\fP is not greater than or equal to 1.
.TP
-\fBdeclare\fP [\fB\-aAfFilrtux\fP] [\fB\-p\fP] [\fIname\fP[=\fIvalue\fP] ...]
+\fBdeclare\fP [\fB\-aAfFgilnrtux\fP] [\fB\-p\fP] [\fIname\fP[=\fIvalue\fP] ...]
.PD 0
.TP
-\fBtypeset\fP [\fB\-aAfFilrtux\fP] [\fB\-p\fP] [\fIname\fP[=\fIvalue\fP] ...]
+\fBtypeset\fP [\fB\-aAfFgilnrtux\fP] [\fB\-p\fP] [\fIname\fP[=\fIvalue\fP] ...]
.PD
Declare variables and/or give them attributes.
If no \fIname\fPs are given then display the values of variables.
.IR name .
When
.B \-p
-is used with \fIname\fP arguments, additional options are ignored.
+is used with \fIname\fP arguments, additional options,
+other than \fB\-f\fP and \fB\-F\fP, are ignored.
When
.B \-p
is supplied without \fIname\fP arguments, it will display the attributes
.B \-F
option implies
.BR \-f .
+The
+.B \-g
+option forces variables to be created or modified at the global scope,
+even when \fBdeclare\fP is executed in a shell function.
+It is ignored in all other cases.
The following options can
be used to restrict output to variables with the specified attribute or
to give variables attributes:
.B \-i
The variable is treated as an integer; arithmetic evaluation (see
.SM
-.B "ARITHMETIC EVALUATION" ") "
-is performed when the variable is assigned a value.
+.B "ARITHMETIC EVALUATION"
+above) is performed when the variable is assigned a value.
.TP
.B \-l
When the variable is assigned a value, all upper-case characters are
converted to lower-case.
The upper-case attribute is disabled.
.TP
+.B \-n
+Give each \fIname\fP the \fInameref\fP attribute, making
+it a name reference to another variable.
+That other variable is defined by the value of \fIname\fP.
+All references and assignments to \fIname\fP, except for changing the
+\fB\-n\fP attribute itself, are performed on the variable referenced by
+\fIname\fP's value.
+The \fB\-n\fP attribute cannot be applied to array variables.
+.TP
.B \-r
Make \fIname\fPs readonly. These names cannot then be assigned values
by subsequent assignment statements or unset.
Using `+' instead of `\-'
turns off the attribute instead,
with the exceptions that \fB+a\fP
-may not be used to destroy an array variable and \fB+r\fB will not
+may not be used to destroy an array variable and \fB+r\fP will not
remove the readonly attribute.
When used in a function,
-makes each
-\fIname\fP local, as with the
+.B declare
+and
+.B typeset
+make each
+\fIname\fP local, as with the
.B local
-command.
+command,
+unless the \fB\-g\fP option is supplied.
If a variable name is followed by =\fIvalue\fP, the value of
the variable is set to \fIvalue\fP.
+When using \fB\-a\fP or \fB\-A\fP and the compound assignment syntax to
+create array variables, additional attributes do not take effect until
+subsequent assignments.
The return value is 0 unless an invalid option is encountered,
an attempt is made to define a function using
.if n ``\-f foo=bar'',
or an attempt is made to display a non-existent function with \fB\-f\fP.
.RE
.TP
-.B dirs [+\fIn\fP] [\-\fIn\fP] [\fB\-cplv\fP]
+.B dirs [\fB\-clpv\fP] [+\fIn\fP] [\-\fIn\fP]
Without options, displays the list of currently remembered directories.
The default display is on a single line with directory names separated
by spaces.
.RS
.PD 0
.TP
-\fB+\fP\fIn\fP
-Displays the \fIn\fPth entry counting from the left of the list
-shown by
-.B dirs
-when invoked without options, starting with zero.
-.TP
-\fB\-\fP\fIn\fP
-Displays the \fIn\fPth entry counting from the right of the list
-shown by
-.B dirs
-when invoked without options, starting with zero.
-.TP
.B \-c
Clears the directory stack by deleting all of the entries.
.TP
.B \-l
-Produces a longer listing; the default listing format uses a
-tilde to denote the home directory.
+Produces a listing using full pathnames;
+the default listing format uses a tilde to denote the home directory.
.TP
.B \-p
Print the directory stack with one entry per line.
.B \-v
Print the directory stack with one entry per line,
prefixing each entry with its index in the stack.
+.TP
+\fB+\fP\fIn\fP
+Displays the \fIn\fPth entry counting from the left of the list
+shown by
+.B dirs
+when invoked without options, starting with zero.
+.TP
+\fB\-\fP\fIn\fP
+Displays the \fIn\fPth entry counting from the right of the list
+shown by
+.B dirs
+when invoked without options, starting with zero.
.PD
.PP
The return value is 0 unless an
.RE
.TP
\fBdisown\fP [\fB\-ar\fP] [\fB\-h\fP] [\fIjobspec\fP ...]
-Without options, each
+Without options, remove each
.I jobspec
-is removed from the table of active jobs.
+from the table of active jobs.
If
.I jobspec
-is not present, and neither \fB\-a\fB nor \fB\-r\fP is supplied,
-the shell's notion of the \fIcurrent job\fP is used.
+is not present, and neither the \fB\-a\fP nor the \fB\-r\fP option
+is supplied, the \fIcurrent job\fP is used.
If the \fB\-h\fP option is given, each
.I jobspec
is not removed from the table, but is marked so that
.BR SIGHUP .
If no
.I jobspec
-is present, and neither the
-.B \-a
-nor the
-.B \-r
-option is supplied, the \fIcurrent job\fP is used.
-If no
-.I jobspec
is supplied, the
.B \-a
option means to remove or mark all jobs; the
.TP
\fBecho\fP [\fB\-neE\fP] [\fIarg\fP ...]
Output the \fIarg\fPs, separated by spaces, followed by a newline.
-The return status is always 0.
+The return status is 0 unless a write error occurs.
If \fB\-n\fP is specified, the trailing newline is
suppressed. If the \fB\-e\fP option is given, interpretation of
the following backslash-escaped characters is enabled. The
suppress further output
.TP
.B \ee
+.TP
+.B \eE
an escape character
.TP
.B \ef
.B \ex\fIHH\fP
the eight-bit character whose value is the hexadecimal value \fIHH\fP
(one or two hex digits)
+.TP
+.B \eu\fIHHHH\fP
+the Unicode (ISO/IEC 10646) character whose value is the hexadecimal value
+\fIHHHH\fP (one to four hex digits)
+.TP
+.B \eU\fIHHHHHHHH\fP
+the Unicode (ISO/IEC 10646) character whose value is the hexadecimal value
+\fIHHHHHHHH\fP (one to eight hex digits)
.PD
.RE
.TP
.B \-a
is supplied, the shell passes
.I name
-as the zeroth argument to the executed command. If
+as the zeroth argument to the executed command.
+If
.I command
cannot be executed for some reason, a non-interactive shell exits,
-unless the shell option
+unless the
.B execfail
-is enabled, in which case it returns failure.
+shell option
+is enabled. In that case, it returns failure.
An interactive shell returns failure if the file cannot be executed.
If
.I command
are given, or if the
.B \-p
option is supplied, a list
-of all names that are exported in this shell is printed.
+of names of all exported variables is printed.
The
.B \-n
option causes the export property to be removed from each
.TP
\fBfc\fP \fB\-s\fP [\fIpat\fP=\fIrep\fP] [\fIcmd\fP]
.PD
-Fix Command. In the first form, a range of commands from
+The first form selects a range of commands from
.I first
to
.I last
-is selected from the history list.
+from the history list and displays or edits and re-executes them.
.I First
and
.I last
.sp 1
In the second form, \fIcommand\fP is re-executed after each instance
of \fIpat\fP is replaced by \fIrep\fP.
+\fICommand\fP is intepreted the same as \fIfirst\fP above.
A useful alias to use with this is
.if n ``r="fc -s"'',
.if t \f(CWr='fc \-s'\fP,
.sp 1
When the end of options is encountered, \fBgetopts\fP exits with a
return value greater than zero.
-\fBOPTIND\fP is set to the index of the first non-option argument,
-and \fBname\fP is set to ?.
+.SM
+.B OPTIND
+is set to the index of the first non-option argument,
+and \fIname\fP is set to ?.
.sp 1
.B getopts
normally parses the positional parameters, but if more arguments are
.I optstring
is a colon,
.I silent
-error reporting is used. In normal operation diagnostic messages
+error reporting is used. In normal operation, diagnostic messages
are printed when invalid options or missing option arguments are
encountered.
If the variable
error occurs.
.TP
\fBhash\fP [\fB\-lr\fP] [\fB\-p\fP \fIfilename\fP] [\fB\-dt\fP] [\fIname\fP]
-For each
-.IR name ,
-the full file name of the command is determined by searching
+Each time \fBhash\fP is invoked,
+the full pathname of the command
+.I name
+is determined by searching
the directories in
.B $PATH
-and remembered.
+and remembered. Any previously-remembered pathname is discarded.
If the
.B \-p
option is supplied, no path search is performed, and
.I filename
-is used as the full file name of the command.
+is used as the full filename of the command.
The
.B \-r
option causes the shell to forget all
.B \-d
Display a short description of each \fIpattern\fP
.TP
-.B \ -m
+.B \-m
Display the description of each \fIpattern\fP in a manpage-like format
.TP
.B \-s
Display only a short usage synopsis for each \fIpattern\fP
.PD
-.RE
+.PP
The return status is 0 unless no command matches
.IR pattern .
+.RE
.TP
\fBhistory [\fIn\fP]
.PD 0
lists only the last
.I n
lines.
-If the shell variable \fBHISTTIMEFORMAT\fP is set and not null,
+If the shell variable
+.SM
+.B HISTTIMEFORMAT
+is set and not null,
it is used as a format string for \fIstrftime\fP(3) to display
the time stamp associated with each displayed history entry.
No intervening blank is printed between the formatted time stamp
.TP
.B \-r
Read the contents of the history file
-and use them as the current history.
+and append them to the current history list.
.TP
.B \-w
-Write the current history to the history file, overwriting the
+Write the current history list to the history file, overwriting the
history file's contents.
.TP
.B \-p
are added.
.PD
.PP
-If the \fBHISTTIMEFORMAT\fP is set, the time stamp information
+If the
+.SM
+.B HISTTIMEFORMAT
+variable is set, the time stamp information
associated with each history entry is written to the history file,
marked with the history comment character.
When the history file is read, lines beginning with the history
List process IDs
in addition to the normal information.
.TP
-.B \-p
-List only the process ID of the job's process group
-leader.
-.TP
.B \-n
Display information only about jobs that have changed status since
the user was last notified of their status.
.TP
+.B \-p
+List only the process ID of the job's process group
+leader.
+.TP
.B \-r
-Restrict output to running jobs.
+Display only running jobs.
.TP
.B \-s
-Restrict output to stopped jobs.
+Display only stopped jobs.
.PD
.PP
If
.I arg
is an arithmetic expression to be evaluated (see
.SM
-.BR "ARITHMETIC EVALUATION" ).
+.B "ARITHMETIC EVALUATION"
+above).
If the last
.I arg
evaluates to 0,
.TP
\fBreadarray\fP [\fB\-n\fP \fIcount\fP] [\fB\-O\fP \fIorigin\fP] [\fB\-s\fP \fIcount\fP] [\fB\-t\fP] [\fB\-u\fP \fIfd\fP] [\fB\-C\fP \fIcallback\fP] [\fB\-c\fP \fIquantum\fP] [\fIarray\fP]
.PD
-Read lines from the standard input into array variable
+Read lines from the standard input into the indexed array variable
.IR array ,
or from file descriptor
.IR fd
if the
.B \-u
option is supplied.
-The variable \fBMAPFILE\fP is the default \fIarray\fP.
+The variable
+.SM
+.B MAPFILE
+is the default \fIarray\fP.
Options, if supplied, have the following meanings:
.RS
.PD 0
Discard the first \fIcount\fP lines read.
.TP
.B \-t
-Remove a trailing line from each line read.
+Remove a trailing newline from each line read.
.TP
.B \-u
Read lines from file descriptor \fIfd\fP instead of the standard input.
.BR \-c ,
the default quantum is 5000.
When \fIcallback\fP is evaluated, it is supplied the index of the next
-array element to be assigned as an additional argument.
+array element to be assigned and the line to be assigned to that element
+as additional arguments.
\fIcallback\fP is evaluated after the line is read but before the
array element is assigned.
.PP
before assigning to it.
.PP
\fBmapfile\fP returns successfully unless an invalid option or option
-argument is supplied, or \fIarray\fP is invalid or unassignable.
+argument is supplied, \fIarray\fP is invalid or unassignable, or if
+\fIarray\fP is not an indexed array.
.RE
.TP
\fBpopd\fP [\-\fBn\fP] [+\fIn\fP] [\-\fIn\fP]
\fBprintf\fP [\fB\-v\fP \fIvar\fP] \fIformat\fP [\fIarguments\fP]
Write the formatted \fIarguments\fP to the standard output under the
control of the \fIformat\fP.
+The \fB\-v\fP option causes the output to be assigned to the variable
+\fIvar\fP rather than being printed to the standard output.
+.sp 1
The \fIformat\fP is a character string which contains three types of objects:
plain characters, which are simply copied to standard output, character
escape sequences, which are converted and copied to the standard output, and
format specifications, each of which causes printing of the next successive
\fIargument\fP.
-In addition to the standard \fIprintf\fP(1) formats, \fB%b\fP causes
+In addition to the standard \fIprintf\fP(1) format specifications,
+\fBprintf\fP interprets the following extensions:
+.RS
+.PD 0
+.TP
+.B %b
+causes
\fBprintf\fP to expand backslash escape sequences in the corresponding
\fIargument\fP (except that \fB\ec\fP terminates output, backslashes in
\fB\e\(aq\fP, \fB\e"\fP, and \fB\e?\fP are not removed, and octal escapes
-beginning with \fB\e0\fP may contain up to four digits),
-and \fB%q\fP causes \fBprintf\fP to output the corresponding
+beginning with \fB\e0\fP may contain up to four digits).
+.TP
+.B %q
+causes \fBprintf\fP to output the corresponding
\fIargument\fP in a format that can be reused as shell input.
-.sp 1
-The \fB\-v\fP option causes the output to be assigned to the variable
-\fIvar\fP rather than being printed to the standard output.
-.sp 1
+.TP
+.B %(\fIdatefmt\fP)T
+causes \fBprintf\fP to output the date-time string resulting from using
+\fIdatefmt\fP as a format string for \fIstrftime\fP(3).
+The corresponding \fIargument\fP is an integer representing the number of
+seconds since the epoch.
+Two special argument values may be used: -1 represents the current
+time, and -2 represents the time the shell was invoked.
+If no argument is specified, conversion behaves as if -1 had been given.
+This is an exception to the usual \fBprintf\fP behavior.
+.PD
+.PP
+Arguments to non-string format specifiers are treated as C constants,
+except that a leading plus or minus sign is allowed, and if the leading
+character is a single or double quote, the value is the ASCII value of
+the following character.
+.PP
The \fIformat\fP is reused as necessary to consume all of the \fIarguments\fP.
If the \fIformat\fP requires more \fIarguments\fP than are supplied, the
extra format specifications behave as if a zero value or null string, as
-appropriate, had been supplied. The return value is zero on success,
-non-zero on failure.
+appropriate, had been supplied.
+The return value is zero on success, non-zero on failure.
+.RE
.TP
\fBpushd\fP [\fB\-n\fP] [+\fIn\fP] [\-\fIn\fP]
.PD 0
Adds
.I dir
to the directory stack at the top, making it the
-new current working directory.
+new current working directory as if it had been supplied as the argument
+to the \fBcd\fP builtin.
.PD
.PP
If the
reading the name of the current directory or an
invalid option is supplied.
.TP
-\fBread\fP [\fB\-ers\fP] [\fB\-a\fP \fIaname\fP] [\fB\-d\fP \fIdelim\fP] [\fB\-i\fP \fItext\fP] [\fB\-n\fP \fInchars\fP] [\fB\-p\fP \fIprompt\fP] [\fB\-t\fP \fItimeout\fP] [\fB\-u\fP \fIfd\fP] [\fIname\fP ...]
+\fBread\fP [\fB\-ers\fP] [\fB\-a\fP \fIaname\fP] [\fB\-d\fP \fIdelim\fP] [\fB\-i\fP \fItext\fP] [\fB\-n\fP \fInchars\fP] [\fB\-N\fP \fInchars\fP] [\fB\-p\fP \fIprompt\fP] [\fB\-t\fP \fItimeout\fP] [\fB\-u\fP \fIfd\fP] [\fIname\fP ...]
One line is read from the standard input, or from the file descriptor
\fIfd\fP supplied as an argument to the \fB\-u\fP option, and the first word
is assigned to the first
The characters in
.SM
.B IFS
-are used to split the line into words.
+are used to split the line into words using the same rules the shell
+uses for expansion (described above under \fBWord Splitting\fP).
The backslash character (\fB\e\fP) may be used to remove any special
meaning for the next character read and for line continuation.
Options, if supplied, have the following meanings:
.TP
.B \-n \fInchars\fP
\fBread\fP returns after reading \fInchars\fP characters rather than
-waiting for a complete line of input.
+waiting for a complete line of input, but honor a delimiter if fewer
+than \fInchars\fP characters are read before the delimiter.
+.TP
+.B \-N \fInchars\fP
+\fBread\fP returns after reading exactly \fInchars\fP characters rather
+than waiting for a complete line of input, unless EOF is encountered or
+\fBread\fP times out.
+Delimiter characters encountered in the input are
+not treated specially and do not cause \fBread\fP to return until
+\fInchars\fP characters are read.
.TP
.B \-p \fIprompt\fP
Display \fIprompt\fP on standard error, without a
.TP
.B \-t \fItimeout\fP
Cause \fBread\fP to time out and return failure if a complete line of
-input is not read within \fItimeout\fP seconds.
+input (or a specified number of characters)
+is not read within \fItimeout\fP seconds.
\fItimeout\fP may be a decimal number with a fractional portion following
the decimal point.
This option is only effective if \fBread\fP is reading input from a
terminal, pipe, or other special file; it has no effect when reading
from regular files.
-If \fItimeout\fP is 0, \fBread\fP returns success if input is available on
-the specified file descriptor, failure otherwise.
+If \fBread\fP times out, \fBread\fP saves any partial input read into
+the specified variable \fIname\fP.
+If \fItimeout\fP is 0, \fBread\fP returns immediately, without trying to
+read any data. The exit status is 0 if input is available on
+the specified file descriptor, non-zero otherwise.
The exit status is greater than 128 if the timeout is exceeded.
.TP
.B \-u \fIfd\fP
.SM
.BR REPLY .
The return code is zero, unless end-of-file is encountered, \fBread\fP
-times out (in which case the return code is greater than 128), or an
-invalid file descriptor is supplied as the argument to \fB\-u\fP.
+times out (in which case the return code is greater than 128),
+a variable assignment error (such as assigning to a readonly variable) occurs,
+or an invalid file descriptor is supplied as the argument to \fB\-u\fP.
.RE
.TP
-\fBreadonly\fP [\fB\-aApf\fP] [\fIname\fP[=\fIword\fP] ...]
+\fBreadonly\fP [\fB\-aAf\fP] [\fB\-p\fP] [\fIname\fP[=\fIword\fP] ...]
.PD
The given
\fInames\fP are marked readonly; the values of these
option restricts the variables to indexed arrays; the
.B \-A
option restricts the variables to associative arrays.
+If both options are supplied,
+.B \-A
+takes precedence.
If no
.I name
arguments are given, or if the
.B \-p
option is supplied, a list of all readonly names is printed.
+The other options may be used to restrict the output to a subset of
+the set of readonly names.
The
.B \-p
option causes output to be displayed in a format that
that is not a function.
.TP
\fBreturn\fP [\fIn\fP]
-Causes a function to exit with the return value specified by
-.IR n .
+Causes a function to stop executing and return the value specified by
+.I n
+to its caller.
If
.I n
is omitted, the return status is that of the last command
-executed in the function body. If used outside a function,
+executed in the function body. If
+.B return
+is used outside a function,
but during execution of a script by the
.B .
(\fBsource\fP) command, it causes the shell to stop executing
that script and return either
.I n
or the exit status of the last command executed within the
-script as the exit status of the script. If used outside a
-function and not during execution of a script by \fB.\fP\^,
-the return status is false.
+script as the exit status of the script.
+If \fIn\fP is supplied, the return value is its least significant
+8 bits.
+The return status is non-zero if
+.B return
+is supplied a non-numeric argument, or
+is used outside a
+function and not during execution of a script by \fB.\fP\^ or \fBsource\fP.
Any command associated with the \fBRETURN\fP trap is executed
before execution resumes after the function or script.
.TP
-\fBset\fP [\fB\-\-abefhkmnptuvxBCEHPT\fP] [\fB\-o\fP \fIoption\fP] [\fIarg\fP ...]
+\fBset\fP [\fB\-\-abefhkmnptuvxBCEHPT\fP] [\fB\-o\fP \fIoption\-name\fP] [\fIarg\fP ...]
.PD 0
.TP
-\fBset\fP [\fB+abefhkmnptuvxBCEHPT\fP] [\fB+o\fP \fIoption\fP] [\fIarg\fP ...]
+\fBset\fP [\fB+abefhkmnptuvxBCEHPT\fP] [\fB+o\fP \fIoption\-name\fP] [\fIarg\fP ...]
.PD
Without options, the name and value of each shell variable are displayed
in a format that can be reused as input
for setting or resetting the currently-set variables.
Read-only variables cannot be reset.
-In \fIposix mode\fP, only shell variables are listed.
+In \fIposix\fP mode, only shell variables are listed.
The output is sorted according to the current locale.
When options are specified, they set or unset shell attributes.
Any arguments remaining after option processing are treated
effective only when job control is enabled.
.TP 8
.B \-e
-Exit immediately if a \fIpipeline\fP (which may consist of a single
-\fIsimple command\fP), a \fIsubshell\fP command enclosed in parentheses,
-or one of the commands executed as part of a command list enclosed
-by braces (see
+Exit immediately if a
+\fIpipeline\fP (which may consist of a single \fIsimple command\fP),
+a \fIlist\fP,
+or a \fIcompound command\fP
+(see
.SM
.B SHELL GRAMMAR
-above) exits with a non-zero status.
+above), exits with a non-zero status.
The shell does not exit if the
command that fails is part of the command list immediately following a
.B while
reserved words, part of any command executed in a
.B &&
or
-.B \(bv\(bv
-list except the command following the final \fB&&\fP or \fB\(bv\(bv\fP,
+.B ||
+list except the command following the final \fB&&\fP or \fB||\fP,
any command in a pipeline but the last,
or if the command's return value is
being inverted with
.BR ! .
+If a compound command other than a subshell
+returns a non-zero status because a command failed
+while \fB\-e\fP was being ignored, the shell does not exit.
A trap on \fBERR\fP, if set, is executed before the shell exits.
This option applies to the shell environment and each subshell environment
separately (see
+.SM
.B "COMMAND EXECUTION ENVIRONMENT"
above), and may cause
subshells to exit before executing all the commands in the subshell.
+.if t .sp 0.5
+.if n .sp 1
+If a compound command or shell function executes in a context
+where \fB\-e\fP is being ignored,
+none of the commands executed within the compound command or function body
+will be affected by the \fB\-e\fP setting, even if \fB\-e\fP is set
+and a command returns a failure status.
+If a compound command or shell function sets \fB\-e\fP while executing in
+a context where \fB\-e\fP is ignored, that setting will not have any
+effect until the compound command or the command containing the function
+call completes.
.TP 8
.B \-f
Disable pathname expansion.
it (see
.SM
.B JOB CONTROL
-above). Background processes run in a separate process
-group and a line containing their exit status is printed
-upon their completion.
+above).
+All processes run in a separate process group.
+When a background job completes, the shell prints a line
+containing its exit status.
.TP 8
.B \-n
Read commands but do not execute them. This may be used to
option.
This also affects the editing interface used for \fBread \-e\fP.
.TP 8
+.B errexit
+Same as
+.BR \-e .
+.TP 8
.B errtrace
Same as
.BR \-E .
Same as
.BR \-T .
.TP 8
-.B errexit
-Same as
-.BR \-e .
-.TP 8
.B hashall
Same as
.BR \-h .
.B bash
where the default operation differs
from the POSIX standard to match the standard (\fIposix mode\fP).
+See
+.SM
+.B "SEE ALSO"
+below for a reference to a document that details how posix mode affects
+bash's behavior.
.TP 8
.B privileged
Same as
environment, and the
.SM
.BR SHELLOPTS ,
+.SM
+.BR BASHOPTS ,
+.SM
.BR CDPATH ,
and
+.SM
.B GLOBIGNORE
variables, if they appear in the environment, are ignored.
If the shell is started with the effective user (group) id not equal to the
Exit after reading and executing one command.
.TP 8
.B \-u
-Treat unset variables as an error when performing
+Treat unset variables and parameters other than the special
+parameters "@" and "*" as an error when performing
parameter expansion. If expansion is attempted on an
-unset variable, the shell prints an error message, and,
+unset variable or parameter, the shell prints an error message, and,
if not interactive, exits with a non-zero status.
.TP 8
.B \-v
default when the shell is interactive.
.TP 8
.B \-P
-If set, the shell does not follow symbolic links when executing
+If set, the shell does not resolve symbolic links when executing
commands such as
.B cd
that change the current working directory. It uses the
or less than zero; otherwise 0.
.TP
\fBshopt\fP [\fB\-pqsu\fP] [\fB\-o\fP] [\fIoptname\fP ...]
-Toggle the values of variables controlling optional shell behavior.
+Toggle the values of settings controlling optional shell behavior.
+The settings can be either those listed below, or, if the
+.B \-o
+option is used, those available with the
+.B \-o
+option to the \fBset\fP builtin command.
With no options, or with the
.B \-p
option, a list of all settable options is displayed, with
.B \-s
or
.B \-u
-is used with no \fIoptname\fP arguments, the display is limited to
-those options which are set or unset, respectively.
+is used with no \fIoptname\fP arguments,
+.B shopt
+shows only those options which are set or unset, respectively.
Unless otherwise noted, the \fBshopt\fP options are disabled (unset)
by default.
.PP
command will be corrected.
The errors checked for are transposed characters,
a missing character, and one character too many.
-If a correction is found, the corrected file name is printed,
+If a correction is found, the corrected filename is printed,
and the command proceeds.
This option is only used by interactive shells.
.TP 8
If set, \fBbash\fP lists the status of any stopped and running jobs before
exiting an interactive shell. If any jobs are running, this causes
the exit to be deferred until a second exit is attempted without an
-intervening command (see \fBJOB CONTROL\fP above). The shell always
+intervening command (see
+.SM
+.B "JOB CONTROL"
+above). The shell always
postpones exiting if any jobs are stopped.
.TP 8
.B checkwinsize
If set,
.B bash
changes its behavior to that of version 3.1 with respect to quoted
-arguments to the conditional command's =~ operator.
+arguments to the \fB[[\fP conditional command's \fB=~\fP operator
+and locale-specific string comparison when using the \fB[[\fP
+conditional command's \fB<\fP and \fB>\fP operators.
+Bash versions prior to bash-4.1 use ASCII collation and
+.IR strcmp (3);
+bash-4.1 and later use the current locale's collation sequence and
+.IR strcoll (3).
+.TP 8
+.B compat32
+If set,
+.B bash
+changes its behavior to that of version 3.2 with respect to
+locale-specific string comparison when using the \fB[[\fP
+conditional command's \fB<\fP and \fB>\fP operators (see previous item).
+.TP 8
+.B compat40
+If set,
+.B bash
+changes its behavior to that of version 4.0 with respect to locale-specific
+string comparison when using the \fB[[\fP
+conditional command's \fB<\fP and \fB>\fP operators (see description of
+\fBcompat31\fP)
+and the effect of interrupting a command list.
+Bash versions 4.0 and later interrupt the list as if the shell received the
+interrupt; previous versions continue with the next command in the list.
+.TP 8
+.B compat41
+If set,
+.BR bash ,
+when in \fIposix\fP mode, treats a single quote in a double-quoted
+parameter expansion as a special character. The single quotes must match
+(an even number) and the characters between the single quotes are considered
+quoted. This is the behavior of posix mode through version 4.1.
+The default bash behavior remains as in previous versions.
+.TP 8
+.B compat42
+If set,
+.B bash
+does not process the replacement string in the pattern substitution word
+expansion using quote removal.
+.TP 8
+.B complete_fullquote
+If set,
+.B bash
+quotes all shell metacharacters in filenames and directory names when
+performing completion.
+If not set,
+.B bash
+removes metacharacters such as the dollar sign from the set of
+characters that will be quoted in completed filenames
+when these metacharacters appear in shell variable references in words to be
+completed.
+This means that dollar signs in variable names that expand to directories
+will not be quoted;
+however, any dollar signs appearing in filenames will not be quoted, either.
+This is active only when bash is using backslashes to quote completed
+filenames.
+This variable is set by default, which is the default bash behavior in
+versions through 4.2.
+.TP 8
+.B direxpand
+If set,
+.B bash
+replaces directory names with the results of word expansion when performing
+filename completion. This changes the contents of the readline editing
+buffer.
+If not set,
+.B bash
+attempts to preserve what the user typed.
.TP 8
.B dirspell
If set,
\fBreturn\fP is simulated.
.TP
.B 4.
-\fBBASH_ARGC\fP and \fBBASH_ARGV\fP are updated as described in their
-descriptions above.
+.SM
+.B BASH_ARGC
+and
+.SM
+.B BASH_ARGV
+are updated as described in their descriptions above.
.TP
.B 5.
Function tracing is enabled: command substitution, shell functions, and
.B 6.
Error tracing is enabled: command substitution, shell functions, and
subshells invoked with \fB(\fP \fIcommand\fP \fB)\fP inherit the
-\fBERROR\fP trap.
+\fBERR\fP trap.
.RE
.TP 8
.B extglob
result in an expansion error.
.TP 8
.B force_fignore
-If set, the suffixes specified by the \fBFIGNORE\fP shell variable
+If set, the suffixes specified by the
+.SM
+.B FIGNORE
+shell variable
cause words to be ignored when performing word completion even if
the ignored words are the only possible completions.
See
.SM
\fBSHELL VARIABLES\fP
-above for a description of \fBFIGNORE\fP.
+above for a description of
+.SM
+.BR FIGNORE .
This option is enabled by default.
.TP 8
+.B globasciiranges
+If set, range expressions used in pattern matching bracket expressions (see
+.SM
+.B Pattern Matching
+above) behave as if in the traditional C locale when performing
+comparisons. That is, the current locale's collating sequence
+is not taken into account, so
+.B b
+will not collate between
+.B A
+and
+.BR B ,
+and upper-case and lower-case ASCII characters will collate together.
+.TP 8
.B globstar
-If set, the pattern \fB**\fP used in a filename expansion context will
-match a files and zero or more directories and subdirectories.
+If set, the pattern \fB**\fP used in a pathname expansion context will
+match all files and zero or more directories and subdirectories.
If the pattern is followed by a \fB/\fP, only directories and
subdirectories match.
.TP 8
.B histappend
If set, the history list is appended to the file named by the value
of the
+.SM
.B HISTFILE
variable when the shell exits, rather than overwriting the file.
.TP 8
.B COMMENTS
above). This option is enabled by default.
.TP 8
+.B lastpipe
+If set, and job control is not active, the shell runs the last command of
+a pipeline not executed in the background in the current shell environment.
+.TP 8
.B lithist
If set, and the
.B cmdhist
.B readline
is being used,
.B bash
-will not attempt to search the \fBPATH\fP for possible completions when
+will not attempt to search the
+.SM
+.B PATH
+for possible completions when
completion is attempted on an empty line.
.TP 8
.B nocaseglob
If set, the \fBecho\fP builtin expands backslash-escape sequences
by default.
.RE
+.PD
.TP
\fBsuspend\fP [\fB\-f\fP]
Suspend the execution of this shell until it receives a
.PD 0
.TP
\fB[\fP \fIexpr\fP \fB]\fP
-Return a status of 0 or 1 depending on
+Return a status of 0 (true) or 1 (false) depending on
the evaluation of the conditional expression
.IR expr .
Each operator and operand must be a separate argument.
Expressions may be combined using the following operators, listed
in decreasing order of precedence.
The evaluation depends on the number of arguments; see below.
+Operator precedence is used when there are five or more arguments.
.RS
.PD 0
.TP
is false.
.TP
3 arguments
+The following conditions are applied in the order listed.
If the second argument is one of the binary conditional operators listed above
under
.SM
5 or more arguments
The expression is parsed and evaluated according to precedence
using the rules listed above.
+.if t .sp 0.5
+.if n .sp 1
+.LP
+When used with \fBtest\fP or \fB[\fP, the \fB<\fP and \fB>\fP operators
+sort lexicographically using ASCII ordering.
.RE
.PD
.TP
.I sigspec
is either
a signal name defined in <\fIsignal.h\fP>, or a signal number.
-Signal names are case insensitive and the SIG prefix is optional.
+Signal names are case insensitive and the
+.SM
+.B SIG
+prefix is optional.
+.if t .sp 0.5
+.if n .sp 1
If a
.I sigspec
is
.I sigspec
is
.SM
+.BR RETURN ,
+the command
+.I arg
+is executed each time a shell function or a script executed with
+the \fB.\fP or \fBsource\fP builtins finishes executing.
+.if t .sp 0.5
+.if n .sp 1
+If a
+.I sigspec
+is
+.SM
.BR ERR ,
the command
.I arg
-is executed whenever a simple command has a non\-zero exit status,
+is executed whenever a
+a pipeline (which may consist of a single simple
+command), a list, or a compound command returns a
+non\-zero exit status,
subject to the following conditions.
The
.SM
statement, part of a command executed in a
.B &&
or
-.B \(bv\(bv
-list, or if the command's return value is
-being inverted via
+.B ||
+list except the command following the final \fB&&\fP or \fB||\fP,
+any command in a pipeline but the last,
+or if the command's return value is
+being inverted using
.BR ! .
-These are the same conditions obeyed by the \fBerrexit\fP option.
-If a
-.I sigspec
-is
-.SM
-.BR RETURN ,
-the command
-.I arg
-is executed each time a shell function or a script executed with the
-\fB.\fP or \fBsource\fP builtins finishes executing.
+These are the same conditions obeyed by the \fBerrexit\fP (\fB\-e\fP) option.
+.if t .sp 0.5
+.if n .sp 1
Signals ignored upon entry to the shell cannot be trapped or reset.
Trapped signals that are not being ignored are reset to their original
-values in a child process when it is created.
+values in a subshell or subshell environment when one is created.
The return status is false if any
.I sigspec
is invalid; otherwise
.B \-p
and
.B \-P
-print the hashed value, not necessarily the file that appears
+print the hashed value, which is not necessarily the file that appears
first in
.SM
.BR PATH .
The maximum number of processes available to a single user
.TP
.B \-v
-The maximum amount of virtual memory available to the shell
+The maximum amount of virtual memory available to the shell and, on
+some systems, to its children
.TP
.B \-x
The maximum number of file locks
.PP
If
.I limit
-is given, it is the new value of the specified resource (the
+is given, and the
.B \-a
-option is display only).
+option is not used,
+\fIlimit\fP is the new value of the specified resource.
If no option is given, then
.B \-f
is assumed. Values are in 1024-byte increments, except for
.BR \-t ,
-which is in seconds,
+which is in seconds;
.BR \-p ,
-which is in units of 512-byte blocks,
+which is in units of 512-byte blocks;
and
.BR \-T ,
.BR \-b ,
.I name
is not a defined alias.
.TP
-\fBunset\fP [\-\fBfv\fP] [\fIname\fP ...]
+\fBunset\fP [\-\fBfv\fP] [\-\fBn\fP] [\fIname\fP ...]
For each
.IR name ,
remove the corresponding variable or function.
-If no options are supplied, or the
+If the
.B \-v
option is given, each
.I name
-refers to a shell variable.
+refers to a shell variable, and that variable is removed.
Read-only variables may not be unset.
If
.B \-f
.I name
refers to a shell function, and the function definition
is removed.
+If the
+.B \-n
+option is supplied, and \fIname\fP is a variable with the \fInameref\fP
+attribute, \fIname\fP will be unset rather than the variable it
+references.
+\fB\-n\fP has no effect if the \fB\-f\fP option is supplied.
+If no options are supplied, each \fIname\fP refers to a variable; if
+there is no variable by that name, any function with that name is
+unset.
Each unset variable or function is removed from the environment
passed to subsequent commands.
If any of
.SM
+.BR COMP_WORDBREAKS ,
+.SM
.BR RANDOM ,
.SM
.BR SECONDS ,
.I name
is readonly.
.TP
-\fBwait\fP [\fIn ...\fP]
-Wait for each specified process and return its termination status.
+\fBwait\fP [\fB\-n\fP] [\fIn ...\fP]
+Wait for each specified child process and return its termination status.
Each
.I n
may be a process
in that job's pipeline are waited for. If
.I n
is not given, all currently active child processes
-are waited for, and the return status is zero. If
+are waited for, and the return status is zero.
+If the \fB\-n\fP option is supplied, \fBwait\fP waits for any job to
+terminate and returns its exit status.
+If
.I n
specifies a non-existent process or job, the return status is
127. Otherwise, the return status is the exit status of the last
changing directories with \fBcd\fP
.IP \(bu
setting or unsetting the values of
+.SM
.BR SHELL ,
+.SM
.BR PATH ,
+.SM
.BR ENV ,
or
+.SM
.B BASH_ENV
.IP \(bu
specifying command names containing
.B /
.IP \(bu
-specifying a file name containing a
+specifying a filename containing a
.B /
as an argument to the
.B .
builtin command
.IP \(bu
-Specifying a filename containing a slash as an argument to the
+specifying a filename containing a slash as an argument to the
.B \-p
option to the
.B hash
.IP \(bu
importing function definitions from the shell environment at startup
.IP \(bu
-parsing the value of \fBSHELLOPTS\fP from the shell environment at startup
+parsing the value of
+.SM
+.B SHELLOPTS
+from the shell environment at startup
.IP \(bu
redirecting output using the >, >|, <>, >&, &>, and >> redirection operators
.IP \(bu
.B enable
builtin command
.IP \(bu
-Using the \fBenable\fP builtin command to enable disabled shell builtins
+using the \fBenable\fP builtin command to enable disabled shell builtins
.IP \(bu
specifying the
.B \-p
.TP
\fIThe Gnu History Library\fP, Brian Fox and Chet Ramey
.TP
-\fIPortable Operating System Interface (POSIX) Part 2: Shell and Utilities\fP, IEEE
+\fIPortable Operating System Interface (POSIX) Part 2: Shell and Utilities\fP, IEEE --
+http://pubs.opengroup.org/onlinepubs/9699919799/
+.TP
+http://tiswww.case.edu/~chet/bash/POSIX -- a description of posix mode
.TP
\fIsh\fP(1), \fIksh\fP(1), \fIcsh\fP(1)
.TP
version of
.BR bash .
The latest version is always available from
-\fIftp://ftp.gnu.org/pub/bash/\fP.
+\fIftp://ftp.gnu.org/pub/gnu/bash/\fP.
.PP
Once you have determined that a bug actually exists, use the
.I bashbug
.PP
Comments and bug reports concerning
this manual page should be directed to
-.IR chet@po.cwru.edu .
+.IR chet.ramey@case.edu .
.SH BUGS
.PP
It's too big and too slow.
projects / platform / upstream / bash.git / blobdiff