</HEAD>
<BODY><TABLE WIDTH=100%>
<TR>
-<TH ALIGN=LEFT width=33%>BASH(1)<TH ALIGN=CENTER width=33%>2016 August 26<TH ALIGN=RIGHT width=33%>BASH(1)
+<TH ALIGN=LEFT width=33%>BASH(1)<TH ALIGN=CENTER width=33%>2018 December 7<TH ALIGN=RIGHT width=33%>BASH(1)
</TR>
</TABLE>
<BR><A HREF="#index">Index</A>
+
+
+
+
+
+
+
+
+
+
+
+
<H3>COPYRIGHT</H3>
-Bash is Copyright © 1989-2016 by the Free Software Foundation, Inc.
+Bash is Copyright © 1989-2018 by the Free Software Foundation, Inc.
<A NAME="lbAE"> </A>
<H3>DESCRIPTION</H3>
<H3>OPTIONS</H3>
All of the single-character shell options documented in the
-description of the <B>set</B> builtin command can be used as options
-when the shell is invoked.
+description of the <B>set</B> builtin command, including <B>-o</B>,
+can be used as options when the shell is invoked.
In addition, <B>bash</B>
interprets the following options when it is invoked:
<P>
option is present, or if no arguments remain after option
processing, then commands are read from the standard input.
This option allows the positional parameters to be set
-when invoking an interactive shell.
+when invoking an interactive shell or when reading input
+through a pipe.
<DT><B>-D</B>
<DD>
Each command in a pipeline is executed as a separate process (i.e., in a
subshell).
+See
+<FONT SIZE=-1><B>COMMAND EXECUTION ENVIRONMENT</B></FONT>
+for a description of a subshell environment.
+If the <B>lastpipe</B> option is enabled using the <B>shopt</B> builtin
+(see the description of <B>shopt</B> below),
+the last element of a pipeline may be run by the shell process.
<A NAME="lbAN"> </A>
<H4>Lists</H4>
<B>&</B>,
the shell executes the command in the <I>background</I>
-in a subshell. The shell does not wait for the command to
-finish, and the return status is 0. Commands separated by a
+in a subshell.
+The shell does not wait for the command to
+finish, and the return status is 0.
+These are referred to as <I>asynchronous</I> commands.
+Commands separated by a
<B>;</B>
are executed sequentially; the shell waits for each
is executed if, and only if,
<I>command1</I>
-returns an exit status of zero.
+returns an exit status of zero (success).
<P>
An OR list has the form
<I>command2</I>
-is executed if and only if
+is executed if, and only if,
<I>command1</I>
returns a non-zero exit status.
An additional binary operator, <B>=~</B>, is available, with the same
precedence as <B>==</B> and <B>!=</B>.
When it is used, the string to the right of the operator is considered
-an extended regular expression and matched accordingly (as in <I>regex</I>(3)).
+a POSIX extended regular expression and matched accordingly (as in <I>regex</I>(3)).
The return value is 0 if the string matches
the pattern, and 1 otherwise.
If the regular expression is syntactically incorrect, the conditional
<DT><B>case</B> <I>word</I> <B>in</B> [ [(] <I>pattern</I> [ <B>|</B> <I>pattern</I> ]
<DD>
A <B>case</B> command first expands <I>word</I>, and tries to match
-it against each <I>pattern</I> in turn, using the same matching rules
-as for pathname expansion (see
-<B>Pathname Expansion</B>
+it against each <I>pattern</I> in turn, using the matching rules
+described under
+<B>Pattern Matching</B>
-below).
+below.
The <I>word</I> is expanded using tilde
expansion, parameter and variable expansion, arithmetic expansion,
command substitution, process substitution and quote removal.
below).
The file descriptors can be utilized as arguments to shell commands
and redirections using standard word expansions.
-The file descriptors are not available in subshells.
+Other than those created to execute command and process substitutions,
+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 <I>NAME</I>_PID.
The <B>wait</B>
<DD>
the eight-bit character whose value is the octal value <I>nnn</I>
-(one to three digits)
+(one to three octal digits)
<DT><B>\x</B><I>HH</I>
<DD>
<DT><B>@</B>
<DD>
-Expands to the positional parameters, starting from one. When the
+Expands to the positional parameters, starting from one.
+In contexts where word splitting is performed, this expands each
+positional parameter to a separate word; if not within double
+quotes, these words are subject to word splitting.
+In contexts where word splitting is not performed,
+this expands to a single word
+with each positional parameter separated by a space.
+When the
expansion occurs within double quotes, each parameter expands to a
separate word. That is, "<B>$@</B>" is equivalent to
"<B>$1</B>" "<B>$2</B>" ...
At shell startup, set to the absolute pathname used to invoke the
shell or shell script being executed as passed in the environment
or argument list.
-Subsequently, expands to the last argument to the previous command,
-after expansion.
+Subsequently, expands to the last argument to the previous simple
+command executed in the foreground, after expansion.
Also set to the full pathname used to invoke each command executed
and placed in the environment exported to that command.
When checking mail, this parameter holds the name of the mail file
Expands to the process ID of the current <B>bash</B> process.
This differs from <B>$$</B> under certain circumstances, such as subshells
that do not require <B>bash</B> to be re-initialized.
+Assignments to
+<FONT SIZE=-1><B>BASHPID</B>
+
+</FONT>
+have no effect.
+If
+<B>BASHPID</B>
+
+is unset, it loses its special properties, even if it is
+subsequently reset.
<DT><B>BASH_ALIASES</B>
<DD>
option to the
<B>shopt</B>
-builtin below)
+builtin below).
+Setting <B>extdebug</B> after the shell has started to execute a script,
+or referencing this variable when <B>extdebug</B> is not set,
+may result in inconsistent values.
<DT><B>BASH_ARGV</B>
<DD>
option to the
<B>shopt</B>
-builtin below)
+builtin below).
+Setting <B>extdebug</B> after the shell has started to execute a script,
+or referencing this variable when <B>extdebug</B> is not set,
+may result in inconsistent values.
+<DT><B>BASH_ARGV0</B>
+
+<DD>
+When referenced, this variable expands to the name of the shell or shell
+script (identical to
+<B>$0</B>;
+
+see the description of special parameter 0 above).
+Assignment to
+<B>BASH_ARGV0</B>
+
+causes the value assigned to also be assigned to <B>$0</B>.
+If
+<B>BASH_ARGV0</B>
+
+is unset, it loses its special properties, even if it is
+subsequently reset.
<DT><B>BASH_CMDS</B>
<DD>
If
<FONT SIZE=-1><B>DIRSTACK</B>
+</FONT>
+is unset, it loses its special properties, even if it is
+subsequently reset.
+<DT><B>EPOCHREALTIME</B>
+
+<DD>
+Each time this parameter is referenced, it expands to the number of seconds
+since the Unix Epoch (see <I>time</I>(3)) as a floating point value
+with micro-second granularity.
+Assignments to
+<FONT SIZE=-1><B>EPOCHREALTIME</B>
+
+</FONT>
+are ignored.
+If
+<FONT SIZE=-1><B>EPOCHREALTIME</B>
+
+</FONT>
+is unset, it loses its special properties, even if it is
+subsequently reset.
+<DT><B>EPOCHSECONDS</B>
+
+<DD>
+Each time this parameter is referenced, it expands to the number of seconds
+since the Unix Epoch (see <I>time</I>(3)).
+Assignments to
+<FONT SIZE=-1><B>EPOCHSECONDS</B>
+
+</FONT>
+are ignored.
+If
+<FONT SIZE=-1><B>EPOCHSECONDS</B>
+
</FONT>
is unset, it loses its special properties, even if it is
subsequently reset.
<FONT SIZE=-1><B>BASH_ENV</B>;
</FONT>
-used when the shell is invoked in POSIX mode.
+used when the shell is invoked in <I>posix mode</I>.
<DT><B>EXECIGNORE</B>
<DD>
<DT><B>GLOBIGNORE</B>
<DD>
-A colon-separated list of patterns defining the set of filenames to
+A colon-separated list of patterns defining the set of file names to
be ignored by pathname expansion.
-If a filename matched by a pathname expansion pattern also matches one
+If a file name matched by a pathname expansion pattern also matches one
of the patterns in
<FONT SIZE=-1><B>GLOBIGNORE</B>,
</FONT>
below).
+<DT><B>INSIDE_EMACS</B>
+
+<DD>
+If this variable appears in the environment when the shell starts,
+<B>bash</B> assumes that it is running inside an Emacs shell buffer
+and may disable line editing, depending on the value of <B>TERM</B>.
<DT><B>LANG</B>
<DD>
<TT>set -o posix</TT>
had been executed.
+When the shell enters <I>posix mode</I>, it sets this variable if it was
+not already set.
<DT><B>PROMPT_COMMAND</B>
<DD>
<B>bash</B>
displays during an execution trace. The first character of
+the expanded value of
<FONT SIZE=-1><B>PS4</B>
</FONT>
<B>unset</B>
builtin is used to destroy arrays. <B>unset</B> <I>name</I>[<I>subscript</I>]
-destroys the array element at index <I>subscript</I>.
+destroys the array element at index <I>subscript</I>,
+for both indexed and associative arrays.
Negative subscripts to indexed arrays are interpreted as described above.
-Care must be taken to avoid unwanted side effects caused by pathname
-expansion.
+Unsetting the last element of an array variable does not unset the variable.
<B>unset</B> <I>name</I>, where <I>name</I> is an array, or
<B>unset</B> <I>name</I>[<I>subscript</I>], where
<I>subscript</I> is <B>*</B> or <B>@</B>, removes the entire array.
<P>
+When using a variable name with a subscript as an argument to a command,
+such as with <B>unset</B>, without using the word expansion syntax
+described above, the argument is subject to pathname expansion.
+If pathname expansion is not desired, the argument should be quoted.
+<P>
+
The
<B>declare</B>,
<P>
Only brace expansion, word splitting, and pathname expansion
-can change the number of words of the expansion; other expansions
+can increase the number of words of the expansion; other expansions
expand a single word to a single word.
The only exceptions to this are the expansions of
-"<B>$@</B>" and "<B>${</B><I>name</I><B>[@]}</B>"
+"<B>$@</B>" and "<B>${</B><I>name</I><B>[@]}</B>",
+and, in most cases, <B>$*</B> and <B>${</B><I>name</I><B>[*]}</B>
as explained above (see
<FONT SIZE=-1><B>PARAMETERS</B>).
A <B>{</B> or <B>,</B> may be quoted with a backslash to prevent its
being considered part of a brace expression.
To avoid conflicts with parameter expansion, the string <B>${</B>
-is not considered eligible for brace expansion.
+is not considered eligible for brace expansion, and inhibits brace
+expansion until the closing <B>}</B>.
<P>
This construct is typically used as shorthand when the common
</FONT>
and the shell assigns the expanded value.
+<P>
+
+Bash also performs tilde expansion on words satisfying the conditions of
+variable assignments (as described above under
+<FONT SIZE=-1><B>PARAMETERS</B>)
+
+</FONT>
+when they appear as arguments to simple commands.
+Bash does not do this, except for the <I>declaration</I> commands listed
+above, when in <I>posix mode</I>.
<A NAME="lbBB"> </A>
<H4>Parameter Expansion</H4>
If the first character of <I>parameter</I> is an exclamation point (<B>!</B>),
and <I>parameter</I> is not a <I>nameref</I>,
-it introduces a level of variable indirection.
-<B>Bash</B> uses the value of the variable formed from the rest of
-<I>parameter</I> 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 <I>parameter</I> itself.
+it introduces a level of indirection.
+<B>Bash</B> uses the value formed by expanding the rest of
+<I>parameter</I> as the new <I>parameter</I>; this is then
+expanded and that value is used in the rest of the expansion, rather
+than the expansion of the original <I>parameter</I>.
This is known as <I>indirect expansion</I>.
+The value is subject to tilde expansion,
+parameter expansion, command substitution, and arithmetic expansion.
If <I>parameter</I> is a nameref, this expands to the name of the
-variable referenced by <I>parameter</I> instead of performing the
+parameter referenced by <I>parameter</I> instead of performing the
complete indirect expansion.
The exceptions to this are the expansions of ${<B>!</B><I>prefix</I><B>*</B>} and
${<B>!</B><I>name</I>[<I>@</I>]} described below.
<I>word</I>
is expanded to produce a pattern just as in pathname
-expansion. If the pattern matches the beginning of
+expansion, and matched against the expanded value of
+<I>parameter</I>
+
+using the rules described under
+<B>Pattern Matching</B>
+
+below.
+If the pattern matches the beginning of
the value of
<I>parameter</I>,
<B>Remove matching suffix pattern</B>.
The <I>word</I> is expanded to produce a pattern just as in
-pathname expansion.
+pathname expansion, and matched against the expanded value of
+<I>parameter</I>
+
+using the rules described under
+<B>Pattern Matching</B>
+
+below.
If the pattern matches a trailing portion of the expanded value of
<I>parameter</I>,
<DT>${<I>parameter</I><B>/</B><I>pattern</I><B>/</B><I>string</I>}<DD>
<B>Pattern substitution</B>.
The <I>pattern</I> is expanded to produce a pattern just as in
-pathname expansion.
+pathname expansion,
<I>Parameter</I> is expanded and the longest match of <I>pattern</I>
against its value is replaced with <I>string</I>.
+The match is performed using the rules described under
+<B>Pattern Matching</B>
+
+below.
If <I>pattern</I> begins with <B>/</B>, all matches of <I>pattern</I> are
replaced with <I>string</I>. Normally only the first match is replaced.
If <I>pattern</I> begins with <B>#</B>, it must match at the beginning
<DD>
The expansion is a string that is the value of <I>parameter</I> with backslash
-escape sequences expanded as with the <B>$'...'</B> quoting mechansim.
+escape sequences expanded as with the <B>$'...'</B> quoting mechanism.
<DT><B>P</B>
<DD>
or
<B>*</B>,
-the case modification operation is applied to each member of the
+the operation is applied to each member of the
array in turn, and the expansion is the resultant list.
<P>
The result of the expansion is subject to word splitting and pathname
<B>dotglob</B>
is set.
-When matching a pathname, the slash character must always be
-matched explicitly.
+The filenames
+<B>``.''</B>
+
+and
+<B>``..''</B>
+
+must always be matched explicitly, even if
+<B>dotglob</B>
+
+is set.
In other cases, the
<B>``.''</B>
character is not treated specially.
+When matching a pathname, the slash character must always be
+matched explicitly by a slash in the pattern, but in other matching
+contexts it can be matched by a special pattern character as described
+below under
+<FONT SIZE=-1><B>Pattern Matching</B>.
+
+</FONT>
See the description of
<B>shopt</B>
<FONT SIZE=-1><B>GLOBIGNORE</B>
</FONT>
-shell variable may be used to restrict the set of filenames matching a
+shell variable may be used to restrict the set of file names matching a
<I>pattern</I>.
If
<FONT SIZE=-1><B>GLOBIGNORE</B>
</FONT>
-is set, each matching filename that also matches one of the patterns in
+is set, each matching file name that also matches one of the patterns in
<FONT SIZE=-1><B>GLOBIGNORE</B>
</FONT>
</DL></DL>
+<P>
+
+Complicated extended pattern matching against long strings is slow,
+especially when the patterns contain alternations and the strings
+contain multiple matches.
+Using separate matches against shorter strings, or using arrays of
+strings instead of a single long string, may be faster.
<A NAME="lbBH"> </A>
<H4>Quote Removal</H4>
If >&- or <&- is preceded
by {<I>varname</I>}, the value of <I>varname</I> defines the file
descriptor to close.
+If {<I>varname</I>} is supplied, the redirection persists beyond
+the scope of the command, allowing the shell programmer to manage
+the file descriptor himself.
<P>
In the following descriptions, if the file descriptor number is
<P>
The <I>word</I> undergoes
-brace expansion, tilde expansion, parameter and variable 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, with a newline appended,
somewhat confusing.
<B>Bash</B>
-always reads at least one complete line
-of input before executing any
-of the commands on that line. Aliases are expanded when a
+always reads at least one complete line of input,
+and all lines that make up a compound command,
+before executing any of the commands on that line or the compound command.
+Aliases are expanded when a
command is read, not when it is executed. Therefore, an
alias definition appearing on the same line as another
command does not take effect until the next line of input is read.
builtin command. Ordinarily, variables and their values
are shared between the function and its caller.
+If a variable is declared <B>local</B>, the variable's visible scope
+is restricted to that function and its children (including the functions
+it calls).
+Local variables "shadow" variables with the same name declared at
+previous scopes.
+For instance, a local variable declared in a function
+hides a global variable of the same name: references and assignments
+refer to the local variable, leaving the global variable unmodified.
+When the function returns, the global variable is once again visible.
+<P>
+
+The shell uses <I>dynamic scoping</I> to control a variable's visibility
+within functions.
+With dynamic scoping, visible variables and their values
+are a result of the sequence of function calls that caused execution
+to reach the current function.
+The value of a variable that a function sees depends
+on its value within its caller, if any, whether that caller is
+the "global" scope or another shell function.
+This is also the value that a local variable
+declaration "shadows", and the value that is restored when the function
+returns.
+<P>
+
+For example, if a variable <I>var</I> is declared as local in function
+<I>func1</I>, and <I>func1</I> calls another function <I>func2</I>,
+references to <I>var</I> made from within <I>func2</I> will resolve to the
+local variable <I>var</I> from <I>func1</I>, shadowing any global variable
+named <I>var</I>.
+<P>
+
+The <B>unset</B> builtin also acts using the same dynamic scope: if a
+variable is local to the current scope, <B>unset</B> will unset it;
+otherwise the unset will refer to the variable found in any calling scope
+as described above.
+If a variable at the current local scope is unset, it will remain so
+until it is reset in that scope or until the function returns.
+Once the function returns, any instance of the variable at a previous
+scope will become visible.
+If the unset acts on a variable at a previous scope, any instance of a
+variable with that name that had been shadowed will become visible.
<P>
The <B>FUNCNEST</B> variable, if set to a numeric value greater
<B>unset</B>
builtin.
-Note that shell functions and variables with the same name may result
-in multiple identically-named entries in the environment passed to the
-shell's children.
-Care should be taken in cases where this may cause a problem.
<P>
Functions may be recursive.
<DD>
variable post-increment and post-decrement
-<DT><B>++</B><I>id</I> --<I>id</I>
-
-<DD>
-variable pre-increment and pre-decrement
<DT><B>- +</B>
<DD>
unary minus and plus
+<DT><B>++</B><I>id</I> --<I>id</I>
+
+<DD>
+variable pre-increment and pre-decrement
<DT><B>! ~</B>
<DD>
Conditional expressions are used by the <B>[[</B> compound command and
the <B>test</B> and <B>[</B> builtin commands to test file attributes
and perform string and arithmetic comparisons.
+The <B>test</B> abd <B>[</B> commands determine their behavior based on
+the number of arguments; see the descriptions of those commands for any
+other command-specific actions.
+<P>
+
Expressions are formed from the following unary or binary primaries.
<B>Bash</B> handles several filenames specially when they are used in
expressions.
<I>arg2</I>
may be positive or negative integers.
+When used with the <B>[[</B> command,
+<I>Arg1</I>
+
+and
+<I>Arg2</I>
+
+are evaluated as arithmetic expressions (see
+<FONT SIZE=-1><B>ARITHMETIC EVALUATION</B>
+
+</FONT>
+above).
</DL>
<A NAME="lbBX"> </A>
is performed only if the command is not found in the hash table.
If the search is unsuccessful, the shell searches for a defined shell
function named <B>command_not_found_handle</B>.
-If that function exists, it is invoked with the original command and
+If that function exists, it is invoked in a separate execution environment
+with the original command and
the original command's arguments as its arguments, and the function's
-exit status becomes the exit status of the shell.
+exit status becomes the exit status of that subshell.
If that function is not defined, the shell prints an error
message and returns an exit status of 127.
<P>
<P>
Subshells spawned to execute command substitutions inherit the value of
-the <B>-e</B> option from the parent shell. When not in <I>posix</I> mode,
+the <B>-e</B> option from the parent shell. When not in <I>posix mode</I>,
<B>bash</B> clears the <B>-e</B> option in such subshells.
<P>
If a second attempt to exit is made without an intervening command,
the shell does not print another warning, and any stopped
jobs are terminated.
+<P>
+
+When the shell is waiting for a job or process using the <B>wait</B>
+builtin, and job control is enabled, <B>wait</B> will return when the
+job changes state. The <B>-f</B> option will force <B>wait</B> to wait
+until the job or process terminates before returning.
<A NAME="lbCE"> </A>
<H3>PROMPTING</H3>
<B>Bash</B>
displays
-<B>PS0</B>
+<FONT SIZE=-1><B>PS0</B>
+</FONT>
after it reads a command but before executing it.
<B>Bash</B>
+displays
+<FONT SIZE=-1><B>PS4</B>
+
+</FONT>
+as described above
+before tracing each command when the <B>-x</B> option is enabled.
+<B>Bash</B>
+
allows these prompt strings to be customized by inserting a number of
backslash-escaped special characters that are decoded as follows:
<DL COMPACT><DT><DD>
or
<B>vi</B>.
+<DT><B>emacs-mode-string (@)</B>
+
+<DD>
+If the <I>show-mode-in-prompt</I> variable is enabled,
+this string is displayed immediately before the last line of the primary
+prompt when emacs editing mode is active. The value is expanded like a
+key binding, so the standard set of meta- and control prefixes and
+backslash escape sequences is available.
+Use the \1 and \2 escapes to begin and end sequences of
+non-printing characters, which can be used to embed a terminal control
+sequence into the mode string.
<DT><B>enable-bracketed-paste (Off)</B>
<DD>
<B>editing-mode</B>
also affects the default keymap.
-<DT><B>emacs-mode-string (@)</B>
-
-<DD>
-This string is displayed immediately before the last line of the primary
-prompt when emacs editing mode is active. The value is expanded like a
-key binding, so the standard set of meta- and control prefixes and
-backslash escape sequences is available.
-Use the \1 and \2 escapes to begin and end sequences of
-non-printing characters, which can be used to embed a terminal control
-sequence into the mode string.
<DT><B>keyseq-timeout (500)</B>
<DD>
<DT><B>show-mode-in-prompt (Off)</B>
<DD>
-If set to <B>On</B>, add a character to the beginning of the prompt
-indicating the editing mode: emacs (@), vi command (:) or vi
-insertion (+).
+If set to <B>On</B>, add a string to the beginning of the prompt
+indicating the editing mode: emacs, vi command, or vi insertion.
+The mode strings are user-settable (e.g., <I>emacs-mode-string</I>).
<DT><B>skip-completed-text (Off)</B>
<DD>
<DT><B>vi-cmd-mode-string ((cmd))</B>
<DD>
-This string is displayed immediately before the last line of the primary
+If the <I>show-mode-in-prompt</I> variable is enabled,
+this string is displayed immediately before the last line of the primary
prompt when vi editing mode is active and in command mode.
The value is expanded like a
key binding, so the standard set of meta- and control prefixes and
<DT><B>vi-ins-mode-string ((ins))</B>
<DD>
-This string is displayed immediately before the last line of the primary
+If the <I>show-mode-in-prompt</I> variable is enabled,
+this string is displayed immediately before the last line of the primary
prompt when vi editing mode is active and in insertion mode.
The value is expanded like a
key binding, so the standard set of meta- and control prefixes and
construct allows bindings to be made based on the
editing mode, the terminal being used, or the application using
-readline. The text of the test extends to the end of the line;
-no characters are required to isolate it.
+readline. The text of the test, after any comparison operator,
+<BR> extends to the end of the line;
+unless otherwise noted, no characters are required to isolate it.
<DL COMPACT><DT><DD>
<DL COMPACT>
<DT><B>mode</B><DD>
<I>sun-cmd</I>,
for instance.
+<DT><B>version</B><DD>
+The <B>version</B> test may be used to perform comparisons against
+specific readline versions.
+The <B>version</B> expands to the current readline version.
+The set of comparison operators includes
+<B>=</B>,
+
+(and
+<B>==</B>),
+
+<B>!=</B>,
+
+<B><=</B>,
+
+<B>>=</B>,
+
+<B><</B>,
+
+and
+<B>></B>.
+
+The version number supplied on the right side of the operator consists
+of a major version number, an optional decimal point, and an optional
+minor version (e.g., <B>7.1</B>). If the minor version is omitted, it
+is assumed to be <B>0</B>.
+The operator may be separated from the string <B>version</B>
+and from the version number argument by whitespace.
<DT><B>application</B><DD>
The <B>application</B> construct is used to include
application-specific settings. Each program using the readline
</DL>
+<DT><I>variable</I><DD>
+The <I>variable</I> construct provides simple equality tests for readline
+variables and values.
+The permitted comparison operators are <I>=</I>, <I>==</I>, and <I>!=</I>.
+The variable name must be separated from the comparison operator by
+whitespace; the operator may be separated from the value on the right hand
+side by whitespace.
+Both string and boolean variables may be tested. Boolean variables must be
+tested against the values <I>on</I> and <I>off</I>.
</DL></DL>
<DT><B>$endif</B><DD>
<DD>
Move back to the start of the current or previous word.
Words are delimited by non-quoted shell metacharacters.
+<DT><B>previous-screen-line</B>
+
+<DD>
+Attempt to move point to the same physical screen column on the previous
+physical screen line. This will not have the desired effect if the current
+Readline line does not take up more than one physical line or if point is not
+greater than the length of the prompt plus the screen width.
+<DT><B>next-screen-line</B>
+
+<DD>
+Attempt to move point to the same physical screen column on the next
+physical screen line. This will not have the desired effect if the current
+Readline line does not take up more than one physical line or if the length
+of the current Readline line is not greater than the length of the prompt
+plus the screen width.
<DT><B>clear-screen (C-l)</B>
<DD>
Search backward through the history for the string of characters
between the start of the current line and the point.
This is a non-incremental search.
+<DT><B>history-substring-search-backward</B>
+
+<DD>
+Search backward through the history for the string of characters
+between the start of the current line and the current cursor
+position (the <I>point</I>).
+The search string may match anywhere in a history line.
+This is a non-incremental search.
+<DT><B>history-substring-search-forward</B>
+
+<DD>
+Search forward through the history for the string of characters
+between the start of the current line and the point.
+The search string may match anywhere in a history line.
+This is a non-incremental search.
<DT><B>yank-nth-arg (M-C-y)</B>
<DD>
<DD>
Accept the current line for execution and fetch the next line
-relative to the current line from the history for editing. Any
-argument is ignored.
-<DT><B>edit-and-execute-command (C-xC-e)</B>
+relative to the current line from the history for editing.
+A numeric argument, if supplied, specifies the history entry to use instead
+of the current line.
+<DT><B>edit-and-execute-command (C-x C-e)</B>
<DD>
Invoke an editor on the current command line, and execute the result as shell
ring the terminal's bell (subject to the setting of
<B>bell-style</B>).
-<DT><B>do-uppercase-version (M-a, M-b, M-</B><I>x</I>, ...)
+<DT><B>do-lowercase-version (M-A, M-B, M-</B><I>x</I>, ...)
<DD>
-If the metafied character <I>x</I> is lowercase, run the command
-that is bound to the corresponding uppercase character.
+If the metafied character <I>x</I> is uppercase, run the command
+that is bound to the corresponding metafied lowercase character.
+The behavior is undefined if <I>x</I> is already lowercase.
<DT><B>prefix-meta (ESC)</B>
<DD>
find a compspec for the portion following the final slash.
If those searches do not result in a compspec, any compspec defined with
the <B>-D</B> option to <B>complete</B> is used as the default.
+If there is no default compspec, <B>bash</B> attempts alias expansion
+on the command word as a final resort, and attempts to find a compspec
+for the command word from any successful expansion.
<P>
Once a compspec has been found, it is used to generate the list of
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.
+by a digit are interpreted as timestamps for the following history line.
These timestamps are optionally displayed depending on the value of the
<FONT SIZE=-1><B>HISTTIMEFORMAT</B>
The shell supports a history expansion feature that
is similar to the history expansion in
-<B>csh.</B>
+<B>csh</B>.
This section describes what syntax features are available. This
feature is enabled by default for interactive shells, and can be
<P>
History expansion is performed immediately after a complete line
-is read, before the shell breaks it into words.
+is read, before the shell breaks it into words, and is performed
+on each line individually without taking quoting on previous lines into
+account.
It takes place in two parts.
The first is to determine which line from the history list
to use during substitution.
<B>--</B>
to signify the end of the options.
-The <B>:</B>, <B>true</B>, <B>false</B>, and <B>test</B> builtins
+The <B>:</B>, <B>true</B>, <B>false</B>, and <B>test</B>/<B>[</B> builtins
do not accept options and do not treat <B>--</B> specially.
The <B>exit</B>, <B>logout</B>, <B>return</B>,
<B>break</B>, <B>continue</B>, <B>let</B>,
<P>
The return value is true unless an invalid option is supplied, or no
matches were generated.
-<DT><B>complete</B> [<B>-abcdefgjksuv</B>] [<B>-o</B> <I>comp-option</I>] [<B>-DE</B>] [<B>-A</B> <I>action</I>] [<B>-G</B> <I>globpat</I>] [<B>-W</B> <I>wordlist</I>] [<B>-F</B> <I>function</I>] [<B>-C</B> <I>command</I>]<DD>
+<DT><B>complete</B> [<B>-abcdefgjksuv</B>] [<B>-o</B> <I>comp-option</I>] [<B>-DEI</B>] [<B>-A</B> <I>action</I>] [<B>-G</B> <I>globpat</I>] [<B>-W</B> <I>wordlist</I>] [<B>-F</B> <I>function</I>] [<B>-C</B> <I>command</I>]<DD>
<BR>
[<B>-X</B> <I>filterpat</I>] [<B>-P</B> <I>prefix</I>] [<B>-S</B> <I>suffix</I>] <I>name</I> [<I>name ...</I>]
-<DT><B>complete</B> <B>-pr</B> [<B>-DE</B>] [<I>name</I> ...]<DD>
+<DT><B>complete</B> <B>-pr</B> [<B>-DEI</B>] [<I>name</I> ...]<DD>
Specify how arguments to each <I>name</I> should be completed.
If the <B>-p</B> option is supplied, or if no options are supplied,
The <B>-r</B> option removes a completion specification for
each <I>name</I>, or, if no <I>name</I>s are supplied, all
completion specifications.
-The <B>-D</B> option indicates that the remaining options and actions should
+The <B>-D</B> option indicates that other supplied 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 <B>-E</B> option indicates that the remaining options and actions should
+The <B>-E</B> option indicates that other supplied options and actions should
apply to ``empty'' command completion; that is, completion attempted on a
blank line.
+The <B>-I</B> option indicates that other supplied options and actions should
+apply to completion on the inital non-assignment word on the line, or after
+a command delimiter such as <B>;</B> or <B>|</B>, which is usually command
+name completion.
+If multiple options are supplied, the <B>-D</B> option takes precedence
+over <B>-E</B>, and both take precedence over <B>-I</B>.
+If any of <B>-D</B>, <B>-E</B>, or <B>-I</B> are supplied, any other
+<I>name</I> arguments are ignored; these completions only apply to the case
+specified by the option.
<P>
The process of applying these completion specifications when word completion
is attempted is described above under <B>Programmable Completion</B>.
</FONT>
special variable as delimiters, and each resultant word is expanded.
+Shell quoting is honored within <I>wordlist</I>,
+in order to provide a
+mechanism for the words to contain shell metacharacters or characters
+in the value of
+<FONT SIZE=-1><B>IFS</B>.
+
+</FONT>
The possible completions are the members of the resultant list which
match the word being completed.
<DT><B>-X</B> <I>filterpat</I><DD>
an error occurs adding a completion specification.
</DL>
-<DT><B>compopt</B> [<B>-o</B> <I>option</I>] [<B>-DE</B>] [<B>+o</B> <I>option</I>] [<I>name</I>]<DD>
+<DT><B>compopt</B> [<B>-o</B> <I>option</I>] [<B>-DEI</B>] [<B>+o</B> <I>option</I>] [<I>name</I>]<DD>
Modify completion options for each <I>name</I> according to the
<I>option</I>s, or for the
currently-executing completion if no <I>name</I>s are supplied.
<I>name</I> or the current completion.
The possible values of <I>option</I> are those valid for the <B>complete</B>
builtin described above.
-The <B>-D</B> option indicates that the remaining options should
+The <B>-D</B> option indicates that other supplied options should
apply to the ``default'' command completion; that is, completion attempted
on a command for which no completion has previously been defined.
-The <B>-E</B> option indicates that the remaining options should
+The <B>-E</B> option indicates that other supplied options should
apply to ``empty'' command completion; that is, completion attempted on a
blank line.
+The <B>-I</B> option indicates that other supplied options should
+apply to completion on the inital non-assignment word on the line,
+or after a command delimiter such as <B>;</B> or <B>|</B>, which is usually
+command name completion.
<P>
The return value is true unless an invalid option is supplied, an attempt
is made to modify the options for a <I>name</I> for which no completion
Using `+' instead of `-'
turns off the attribute instead,
-with the exceptions that <B>+a</B>
-may not be used to destroy an array variable and <B>+r</B> will not
+with the exceptions that <B>+a</B> and <B>+A</B>
+may not be used to destroy array variables and <B>+r</B> will not
remove the readonly attribute.
When used in a function,
<B>declare</B>
shell option
is enabled. In that case, it returns failure.
An interactive shell returns failure if the file cannot be executed.
+A subshell exits unconditionally if <B>exec</B> fails.
If
<I>command</I>
command number). If
<I>last</I>
-is not specified it is set to
+is not specified, it is set to
the current command for listing (so that
<TT>fc -l -10</TT>
If
<I>first</I>
-is not specified it is set to the previous
+is not specified, it is set to the previous
command for editing and -16 for listing.
<P>
The
<P>
In the second form, <I>command</I> is re-executed after each instance
of <I>pat</I> is replaced by <I>rep</I>.
-<I>Command</I> is intepreted the same as <I>first</I> above.
+<I>Command</I> is interpreted the same as <I>first</I> above.
A useful alias to use with this is
<TT>r='fc -s'</TT>,
<DT><B>history</B> <B>-c</B><DD>
<DT><B>history -d</B> <I>offset</I><DD>
+<DT><B>history -d</B> <I>start</I>-<I>end</I><DD>
<DT><B>history</B> <B>-anrw</B> [<I>filename</I>]<DD>
<DT><B>history</B> <B>-p</B> <I>arg</I> [<I>arg ...</I>]<DD>
<DT><B>history</B> <B>-s</B> <I>arg</I> [<I>arg ...</I>]<DD>
Clear the history list by deleting all the entries.
<DT><B>-d</B> <I>offset</I><DD>
Delete the history entry at position <I>offset</I>.
+If <I>offset</I> is negative, it is interpreted as relative to one greater
+than the last history position, so negative indices count back from the
+end of the history, and an index of -1 refers to the current
+<B>history -d</B> command.
+<DT><B>-d</B> <I>start</I>-<I>end</I><DD>
+Delete the history entries between positions <I>start</I> and <I>end</I>,
+inclusive. Positive and negative values for <I>start</I> and <I>end</I>
+are interpreted as described above.
<DT><B>-a</B>
<DD>
<DD>
The first character of <I>delim</I> is used to terminate each input line,
rather than newline.
+If <I>delim</I> is the empty string, <B>mapfile</B> will terminate a line
+when it reads a NUL character.
<DT><B>-n</B>
<DD>
<DD>
The first character of <I>delim</I> is used to terminate the input line,
rather than newline.
+If <I>delim</I> is the empty string, <B>read</B> will terminate a line
+when it reads a NUL character.
<DT><B>-e</B>
<DD>
</FONT>
above) is used to obtain the line.
Readline uses the current (or default, if line editing was not previously
-active) editing settings.
+active) editing settings, but uses Readline's default filename completion.
<DT><B>-i </B><I>text</I>
<DD>
<DD>
Backslash does not act as an escape character.
The backslash is considered to be part of the line.
-In particular, a backslash-newline pair may not be used as a line
+In particular, a backslash-newline pair may not then be used as a line
continuation.
<DT><B>-s</B>
executed in the function body.
If <B>return</B> is executed by a trap handler, the last command used to
determine the status is the last command executed before the trap handler.
-if <B>return</B> is executed during a <B>DEBUG</B> trap, the last command
+If <B>return</B> is executed during a <B>DEBUG</B> trap, the last command
used to determine the status is the last command executed by the trap
handler before <B>return</B> was invoked.
If
in a format that can be reused as input
for setting or resetting the currently-set variables.
Read-only variables cannot be reset.
-In <I>posix</I> mode, only shell variables are listed.
+In <I>posix mode</I>, 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
<B>-p</B>
option, a list of all settable options is displayed, with
-an indication of whether or not each is set.
+an indication of whether or not each is set;
+if <I>optnames</I> are supplied, the output is restricted to those options.
The <B>-p</B> option causes output to be displayed in a form that
may be reused as input.
Other options have the following meanings:
<DL COMPACT>
+<DT><B>assoc_expand_once</B>
+
+<DD>
+If set, the shell suppresses multiple evaluation of associative array
+subscripts during arithmetic expression evaluation, while executing
+builtins that can perform variable assignments,
+and while executing builtins that perform array dereferencing.
<DT><B>autocd</B>
<DD>
<DT><B>checkwinsize</B>
<DD>
-If set, <B>bash</B> checks the window size after each command
-and, if necessary, updates the values of
+If set, <B>bash</B> checks the window size after each external (non-builtin)
+command and, if necessary, updates the values of
<FONT SIZE=-1><B>LINES</B>
</FONT>
<FONT SIZE=-1><B>COLUMNS</B>.
</FONT>
+This option is enabled by default.
<DT><B>cmdhist</B>
<DD>
attempts to save all lines of a multiple-line
command in the same history entry. This allows
easy re-editing of multi-line commands.
+This option is enabled by default, but only has an effect if command
+history is enabled, as described above under
+<FONT SIZE=-1><B>HISTORY</B>.
+
+</FONT>
<DT><B>compat31</B>
<DD>
If set,
<B>bash</B>,
-when in <I>posix</I> mode, treats a single quote in a double-quoted
+when in <I>posix mode</I>, 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.
and does not reset the
loop state when a shell function is executed (this allows <B>break</B> or
<B>continue</B> in a shell function to affect loops in the caller's context).
+<DT><B>compat44</B>
+
+<DD>
+If set,
+<B>bash</B>
+
+saves the positional parameters to BASH_ARGV and BASH_ARGC before they are
+used, regardless of whether or not extended debugging mode is enabled.
<DT><B>complete_fullquote</B>
<DD>
includes filenames beginning with a `.' in the results of pathname
expansion.
+The filenames
+<B>``.''</B>
+
+and
+<B>``..''</B>
+
+must always be matched explicitly, even if
+<B>dotglob</B>
+
+is set.
<DT><B>execfail</B>
<DD>
option is enabled, multi-line commands are saved to the history with
embedded newlines rather than using semicolon separators where possible.
+<DT><B>localvar_inherit</B>
+
+<DD>
+If set, local variables inherit the value and attributes of a variable of
+the same name that exists at a previous scope before any new value is
+assigned. The nameref attribute is not inherited.
+<DT><B>localvar_unset</B>
+
+<DD>
+If set, calling <B>unset</B> on local variables in previous function scopes
+marks them so subsequent lookups find them unset until that function
+returns. This is identical to the behavior of unsetting local variables
+at the current function scope.
<DT><B>login_shell</B>
<DD>
If set, the programmable completion facilities (see
<B>Programmable Completion</B> above) are enabled.
This option is enabled by default.
+<DT><B>progcomp_alias</B>
+
+<DD>
+If set, and programmable completion is enabled, <B>bash</B> treats a command
+name that doesn't have any completions as a possible alias and attempts
+alias expansion. If it has an alias, <B>bash</B> attempts programmable
+completion using the command word resulting from the expanded alias.
<DT><B>promptvars</B>
<DD>
<B>-u</B>,
which are unscaled values;
-and, when in Posix mode,
+and, when in posix mode,
<B>-c</B>
and
<I>name</I>
is readonly.
-<DT><B>wait</B> [<B>-n</B>] [<I>n ...</I>]<DD>
+<DT><B>wait</B> [<B>-fn</B>] [<I>id ...</I>]<DD>
Wait for each specified child process and return its termination status.
Each
-<I>n</I>
+<I>id</I>
may be a process
ID or a job specification; if a job spec is given, all processes
in that job's pipeline are waited for. If
-<I>n</I>
+<I>id</I>
is not given, all currently active child processes
are waited for, and the return status is zero.
If the <B>-n</B> option is supplied, <B>wait</B> waits for any job to
terminate and returns its exit status.
+If the <B>-f</B> option is supplied, and job control is enabled,
+<B>wait</B> forces <I>id</I> to terminate before returning its status,
+instead of returning when it changes status.
If
-<I>n</I>
+<I>id</I>
specifies a non-existent process or job, the return status is
127. Otherwise, the return status is the exit status of the last
<HR>
<TABLE WIDTH=100%>
<TR>
-<TH ALIGN=LEFT width=33%>GNU Bash 4.4<TH ALIGN=CENTER width=33%>2016 August 26<TH ALIGN=RIGHT width=33%>BASH(1)
+<TH ALIGN=LEFT width=33%>GNU Bash 5.0<TH ALIGN=CENTER width=33%>2018 December 7<TH ALIGN=RIGHT width=33%>BASH(1)
</TR>
</TABLE>
<HR>
</DL>
<HR>
This document was created by man2html from bash.1.<BR>
-Time: 31 August 2016 10:24:30 EDT
+Time: 02 January 2019 09:14:47 EST
</BODY>
</HTML>
projects / thirdparty / bash.git / blobdiff