</HEAD>
<BODY><TABLE WIDTH=100%>
<TR>
-<TH ALIGN=LEFT width=33%>BASH(1)<TH ALIGN=CENTER width=33%>2008 December 29<TH ALIGN=RIGHT width=33%>BASH(1)
+<TH ALIGN=LEFT width=33%>BASH(1)<TH ALIGN=CENTER width=33%>2009 December 29<TH ALIGN=RIGHT width=33%>BASH(1)
</TR>
</TABLE>
<BR><A HREF="#index">Index</A>
If the shell is started with the effective user (group) id not equal to the
real user (group) id, and the <B>-p</B> option is not supplied, no startup
files are read, shell functions are not inherited from the environment, the
-<FONT SIZE=-1><B>SHELLOPTS</B>
+<FONT SIZE=-1><B>SHELLOPTS</B>,
+
+</FONT>
+<FONT SIZE=-1><B>BASHOPTS</B>,
+
+</FONT>
+<FONT SIZE=-1><B>CDPATH</B>,
</FONT>
-variable, if it appears in the environment, is ignored,
+and
+<FONT SIZE=-1><B>GLOBIGNORE</B>
+
+</FONT>
+variables, if they appear in the environment, are ignored,
and the effective user id is set to the real user id.
If the <B>-p</B> option is supplied at invocation, the startup behavior is
the same, but the effective user id is not reset.
<P>
+When used with <B>[[</B>, The <B><</B> and <B>></B> operators sort
+lexicographically using the current locale.
+<P>
+
+
When the <B>==</B> and <B>!=</B> operators are used, the string to the
right of the operator is considered a pattern and matched according
to the rules described below under <B>Pattern Matching</B>.
Any part of the pattern may be quoted to force it to be matched as a
string.
Substrings matched by parenthesized subexpressions within the regular
-expression are saved in the array variable <B>BASH_REMATCH</B>.
-The element of <B>BASH_REMATCH</B> with index 0 is the portion of the string
+expression are saved in the array variable
+<FONT SIZE=-1><B>BASH_REMATCH</B>.
+
+</FONT>
+The element of
+<FONT SIZE=-1><B>BASH_REMATCH</B>
+
+</FONT>
+with index 0 is the portion of the string
matching the entire regular expression.
-The element of <B>BASH_REMATCH</B> with index <I>n</I> is the portion of the
+The element of
+<FONT SIZE=-1><B>BASH_REMATCH</B>
+
+</FONT>
+with index <I>n</I> is the portion of the
string matching the <I>n</I>th parenthesized subexpression.
<P>
the entire conditional expression.
</DL>
-<DT><B>for</B> <I>name</I> [ <B>in</B> <I>word</I> ] ; <B>do</B> <I>list</I> ; <B>done</B><DD>
+<DT><B>for</B> <I>name</I> [ [ <B>in</B> [ <I>word ...</I> ] ] ; ] <B>do</B> <I>list</I> ; <B>done</B><DD>
The list of words following <B>in</B> is expanded, generating a list
of items.
The variable <I>name</I> is set to each element of this list
</FONT>
below). The
-<B>PS3</B>
+<FONT SIZE=-1><B>PS3</B>
+</FONT>
prompt is then displayed and a line read from the standard input.
If the line consists of a number corresponding to one of
the displayed words, then the value of
<I>name</I>
to be set to null. The line read is saved in the variable
-<B>REPLY</B>.
+<FONT SIZE=-1><B>REPLY</B>.
+</FONT>
The
<I>list</I>
backspace
<DT><B>\e</B>
+<DD>
+<DT><B>\E</B>
+
<DD>
an escape character
<DT><B>\f</B>
<DD>
single quote
+<DT><B>\dq</B>
+
+<DD>
+double quote
<DT><B>\</B><I>nnn</I>
<DD>
not been present.
<P>
-A double-quoted string preceded by a dollar sign (<B>$</B>) will cause
-the string to be translated according to the current locale.
+A double-quoted string preceded by a dollar sign (<B>$</B>dq<I>string</I>dq)
+will cause the string to be translated according to the current locale.
If the current locale is <B>C</B> or <B>POSIX</B>, the dollar sign
is ignored.
If the string is translated and replaced, the replacement is
Expands to the full file name used to invoke this instance of
<B>bash</B>.
+<DT><B>BASHOPTS</B>
+
+<DD>
+A colon-separated list of enabled shell options. Each word in
+the list is a valid argument for the
+<B>-s</B>
+
+option to the
+<B>shopt</B>
+
+builtin command (see
+<FONT SIZE=-1><B>SHELL BUILTIN COMMANDS</B>
+
+</FONT>
+below). The options appearing in
+<FONT SIZE=-1><B>BASHOPTS</B>
+
+</FONT>
+are those reported as
+<I>on</I>
+
+by <B>shopt</B>.
+If this variable is in the environment when
+<B>bash</B>
+
+starts up, each shell option in the list will be enabled before
+reading any startup files.
+This variable is read-only.
<DT><B>BASHPID</B>
<DD>
parameters to the current subroutine (shell function or script executed
with <B>.</B> or <B>source</B>) is at the top of the stack.
When a subroutine is executed, the number of parameters passed is pushed onto
-<B>BASH_ARGC</B>.
-The shell sets <B>BASH_ARGC</B> only when in extended debugging mode
-(see the description of the
+<FONT SIZE=-1><B>BASH_ARGC</B>.
+
+</FONT>
+The shell sets
+<FONT SIZE=-1><B>BASH_ARGC</B>
+
+</FONT>
+only when in extended debugging mode (see the description of the
<B>extdebug</B>
option to the
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 <B>BASH_ARGV</B>.
-The shell sets <B>BASH_ARGV</B> only when in extended debugging mode
+are pushed onto
+<FONT SIZE=-1><B>BASH_ARGV</B>.
+
+</FONT>
+The shell sets
+<FONT SIZE=-1><B>BASH_ARGV</B>
+
+</FONT>
+only when in extended debugging mode
(see the description of the
<B>extdebug</B>
<DD>
An array variable whose members are the line numbers in source files
-corresponding to each member of <B>FUNCNAME</B>.
+corresponding to each member of
+<FONT SIZE=-1><B>FUNCNAME</B>.
+
+</FONT>
<B>${BASH_LINENO[</B><I>$i</I><B>]}</B> is the line number in the source
file where <B>${FUNCNAME[</B><I>$i</I><B>]}</B> was called
(or <B>${BASH_LINENO[</B><I>$i-1</I><B>]}</B> if referenced within another
shell function).
-The corresponding source file name is <B>${BASH_SOURCE[</B><I>$i</I><B>]}.
-Use LINENO</B> to obtain the current line number.
+The corresponding source file name is <B>${BASH_SOURCE[</B><I>$i</I><B>]}</B>.
+Use
+<FONT SIZE=-1><B>LINENO</B>
+
+</FONT>
+to obtain the current line number.
<DT><B>BASH_REMATCH</B>
<DD>
<DD>
An array variable whose members are the source filenames corresponding
-to the elements in the <B>FUNCNAME</B> array variable.
+to the elements in the
+<FONT SIZE=-1><B>FUNCNAME</B>
+
+</FONT>
+array variable.
<DT><B>BASH_SUBSHELL</B>
<DD>
<DT><B>BASH_VERSINFO[</B>5]
<DD>
-The value of <B>MACHTYPE</B>.
+The value of
+<FONT SIZE=-1><B>MACHTYPE</B>.
+
+</FONT>
</DL></DL>
<DT><B>COMP_WORDBREAKS</B>
<DD>
-The set of characters that the Readline library treats as word
+The set of characters that the <B>readline</B> library treats as word
separators when performing word completion.
If
<FONT SIZE=-1><B>COMP_WORDBREAKS</B>
<DD>
An array variable (see <B>Arrays</B> below) consisting of the individual
words in the current command line.
-The words are split on shell metacharacters as the shell parser would
-separate them.
+The line is split into words as <B>readline</B> would split it, using
+<FONT SIZE=-1><B>COMP_WORDBREAKS</B>
+
+</FONT>
+as described above.
This variable is available only in shell functions invoked by the
programmable completion facilities (see <B>Programmable Completion</B>
below).
A sample value is
<TT>".:~:/usr"</TT>.
+<DT><B>BASH_XTRACEFD</B>
+
+<DD>
+If set to an integer corresponding to a valid file descriptor, <B>bash</B>
+will write the trace output generated when
+<TT>set -x</TT>
+
+is enabled to that file descriptor.
+The file descriptor is closed when
+<FONT SIZE=-1><B>BASH_XTRACEFD</B>
+
+</FONT>
+is unset or assigned a new value.
+Unsetting
+<FONT SIZE=-1><B>BASH_XTRACEFD</B>
+
+</FONT>
+or assigning it the empty string causes the
+trace output to be sent to the standard error.
+Note that setting
+<FONT SIZE=-1><B>BASH_XTRACEFD</B>
+
+</FONT>
+to 2 (the standard error file
+descriptor) and then unsetting it will result in the standard error
+being closed.
<DT><B>COLUMNS</B>
<DD>
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 <B>HISTCONTROL</B> is unset, or does not include a valid value,
+If
+<FONT SIZE=-1><B>HISTCONTROL</B>
+
+</FONT>
+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
-<B>HISTIGNORE</B>.
+<FONT SIZE=-1><B>HISTIGNORE</B>.
+</FONT>
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
-<B>HISTCONTROL</B>.
+<FONT SIZE=-1><B>HISTCONTROL</B>.
+</FONT>
<DT><B>HISTFILE</B>
<DD>
beginning of the line and must match the complete line (no implicit
`<B>*</B>' is appended). Each pattern is tested against the line
after the checks specified by
-<B>HISTCONTROL</B>
+<FONT SIZE=-1><B>HISTCONTROL</B>
+</FONT>
are applied.
In addition to the normal shell pattern matching characters, `<B>&</B>'
matches the previous history line. `<B>&</B>' may be escaped using a
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
-<B>HISTIGNORE</B>.
+<FONT SIZE=-1><B>HISTIGNORE</B>.
+</FONT>
<DT><B>HISTSIZE</B>
<DD>
<FONT SIZE=-1><B>HOSTFILE</B>
</FONT>
-is set, but has no value, <B>bash</B> attempts to read
+is set, but has no value, or does not name a readable file,
+<B>bash</B> attempts to read
<I>/etc/hosts</I>
<DT><B>LC_ALL</B>
<DD>
-This variable overrides the value of <B>LANG</B> and any other
+This variable overrides the value of
+<FONT SIZE=-1><B>LANG</B>
+
+</FONT>
+and any other
<B>LC_</B> variable specifying a locale category.
<DT><B>LC_COLLATE</B>
<DD>
Used by the <B>select</B> builtin command to determine the column length
-for printing selection lists. Automatically set upon receipt of a SIGWINCH.
+for printing selection lists. Automatically set upon receipt of a
+<FONT SIZE=-1><B>SIGWINCH</B>.
+
+</FONT>
<DT><B>MAIL</B>
<DD>
</FONT>
below).
-A zero-length (null) directory name in the value of <B>PATH</B> indicates the
-current directory.
+A zero-length (null) directory name in the value of
+<FONT SIZE=-1><B>PATH</B>
+
+</FONT>
+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,
<DD>
If set to a number greater than zero, the value is used as the number of
-trailing directory components to retain when expanding the <B>\w and
-\W</B> prompt string escapes (see
+trailing directory components to retain when expanding the <B>\w</B> and
+<B>\W</B> prompt string escapes (see
<FONT SIZE=-1><B>PROMPTING</B>
</FONT>
<DD>
The value of this parameter is expanded as with
-<B>PS1</B>
+<FONT SIZE=-1><B>PS1</B>
+</FONT>
and used as the secondary prompt string. The default is
``<B>> </B>''.
<DT><B>PS3</B>
<DD>
The value of this parameter is expanded as with
-<B>PS1</B>
+<FONT SIZE=-1><B>PS1</B>
+</FONT>
and the value is printed before each command
<B>bash</B>
<DT><B>TMOUT</B>
<DD>
-If set to a value greater than zero, <B>TMOUT</B> is treated as the
+If set to a value greater than zero,
+<FONT SIZE=-1><B>TMOUT</B>
+
+</FONT>
+is treated as the
default timeout for the <B>read</B> builtin.
The <B>select</B> command terminates if input does not arrive
-after <B>TMOUT</B> seconds when input is coming from a terminal.
+after
+<FONT SIZE=-1><B>TMOUT</B>
+
+</FONT>
+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.
<B>Bash</B>
referencing the array with a subscript of 0.
<P>
+An array variable is considered set if a subscript has been assigned a
+value. The null string is a valid value.
+<P>
+
The
<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>.
-Care must be taken to avoid unwanted side effects caused by filename
-generation.
+Care must be taken to avoid unwanted side effects caused by pathname
+expansion.
<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.
</DL>
<P>
-If the first character of <I>parameter</I> is an exclamation point,
+If the first character of <I>parameter</I> is an exclamation point (<B>!</B>),
a level of variable indirection is introduced.
<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
<DD>
Matches any string, including the null string.
When the <B>globstar</B> shell option is enabled, and <B>*</B> is used in
-a filename expansion context, two adjacent <B>*</B>s used as a single
+a pathname expansion context, two adjacent <B>*</B>s used as a single
pattern will match all files and zero or more directories and
subdirectories.
If followed by a <B>/</B>, two adjacent <B>*</B>s will match only directories
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 <B>LC_COLLATE</B> shell variable,
+the current locale and the value of the
+<FONT SIZE=-1><B>LC_COLLATE</B>
+
+</FONT>
+shell variable,
if set.
A
<B>-</B>
left to right.
<P>
+Each redirection that may be preceded by a file descriptor number
+may instead be preceded by a word of the form {<I>varname</I>}.
+In this case, for each redirection operator except
+>&- and <&-, the shell will allocate a file descriptor greater
+than 10 and assign it to <I>varname</I>. If >&- or <&- is preceded
+by {<I>varname</I>}, the value of <I>varname</I> defines the file
+descriptor to close.
+<P>
+
In the following descriptions, if the file descriptor number is
omitted, and the first character of the redirection operator is
<B><</B>,
directs only the standard output to file
<I>dirlist</I>,
-because the standard error was duplicated as standard output
+because the standard error was duplicated from the standard output
before the standard output was redirected to
<I>dirlist</I>.
</FONT>
variable is set to the name of the function while the function
is executing.
+<P>
+
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
<FONT SIZE=-1><B>DEBUG</B>
</FONT>
builtin below) or the
<B>-o functrace</B> shell option has been enabled with
the <B>set</B> builtin
-(in which case all functions inherit the <B>DEBUG</B> and <B>RETURN</B> traps).
+(in which case all functions inherit the <B>DEBUG</B> and <B>RETURN</B> traps),
+and the
+<FONT SIZE=-1><B>ERR</B>
+
+</FONT>
+trap is not inherited unless the <B>-o errtrace</B> shell option has
+been enabled.
<P>
Variables local to the function may be declared with the
links and operate on the target of the link, rather than the link itself.
<P>
+
+When used with <B>[[</B>, The <B><</B> and <B>></B> operators sort
+lexicographically using the current locale.
+<P>
+
<DL COMPACT>
<DT><B>-a </B><I>file</I>
is non-zero.
<DT><I>string1</I> <B>==</B> <I>string2</I><DD>
-True if the strings are equal. <B>=</B> may be used in place of
-<B>==</B> for strict POSIX compliance.
+
+<DT><I>string1</I> <B>=</B> <I>string2</I><DD>
+
+True if the strings are equal. <B>=</B> should be used
+with the <B>test</B> command for POSIX conformance.
<DT><I>string1</I> <B>!=</B> <I>string2</I><DD>
True if the strings are not equal.
<DT><I>string1</I> <B><</B> <I>string2</I><DD>
-True if <I>string1</I> sorts before <I>string2</I> lexicographically
-in the current locale.
+True if <I>string1</I> sorts before <I>string2</I> lexicographically.
<DT><I>string1</I> <B>></B> <I>string2</I><DD>
-True if <I>string1</I> sorts after <I>string2</I> lexicographically
-in the current locale.
+True if <I>string1</I> sorts after <I>string2</I> lexicographically.
<DT><I>arg1</I> <B>OP</B> <I>arg2</I>
<DD>
The shell has an <I>execution environment</I>, which consists of the
following:
-<P>
+
<DL COMPACT>
<DT>*<DD>
open files inherited by the shell at invocation, as modified by
shell aliases defined with <B>alias</B>
<DT>*<DD>
various process IDs, including those of background jobs, the value
-of <B>$$</B>, and the value of <B>$PPID</B>
+of <B>$$</B>, and the value of
+<FONT SIZE=-1><B>PPID</B>
+
+</FONT>
</DL>
<P>
is invoked in a separate execution environment that consists of
the following. Unless otherwise noted, the values are inherited
from the shell.
-<P>
+
<DL COMPACT>
<DT>*<DD>
the shell's open files, plus any modifications and additions specified
the execution of processes and continue (<I>resume</I>)
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
<B>bash</B>.
<P>
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 <TT>stty tostop</TT>, write to the
+terminal.
+Background processes which attempt to read from (write to when
+<TT>stty tostop</TT> is in effect) the
terminal are sent a
<FONT SIZE=-1><B>SIGTTIN (SIGTTOU)</B>
</FONT>
-signal by the terminal driver,
+signal by the kernel's terminal driver,
which, unless caught, suspends the process.
<P>
<DT><B>\w</B>
<DD>
-the current working directory, with <B>$HOME</B> abbreviated with a tilde
-(uses the <B>$PROMPT_DIRTRIM</B> variable)
+the current working directory, with
+<FONT SIZE=-1><B>$HOME</B>
+
+</FONT>
+abbreviated with a tilde
+(uses the value of the
+<FONT SIZE=-1><B>PROMPT_DIRTRIM</B>
+
+</FONT>
+variable)
<DT><B>\W</B>
<DD>
-the basename of the current working directory, with <B>$HOME</B>
+the basename of the current working directory, with
+<FONT SIZE=-1><B>$HOME</B>
+
+</FONT>
abbreviated with a tilde
<DT><B>\!</B>
or
<B>vi</B>.
+<DT><B>echo-control-characters (On)</B>
+
+<DD>
+When set to <B>On</B>, on operating systems that indicate they support it,
+readline echoes a character corresponding to a signal generated from the
+keyboard.
<DT><B>enable-keypad (Off)</B>
<DD>
When set to <B>On</B>, readline will try to enable the application
keypad when it is called. Some systems need this to enable the
arrow keys.
+<DT><B>enable-meta-key (On)</B>
+
+<DD>
+When set to <B>On</B>, 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.
<DT><B>expand-tilde (Off)</B>
<DD>
possible partial completion (the possible completions don't share
a common prefix) cause the matches to be listed immediately instead
of ringing the bell.
+<DT><B>skip-completed-text (Off)</B>
+
+<DD>
+If set to <B>On</B>, 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.
<DT><B>visible-stats (Off)</B>
<DD>
through the list.
This command is intended to be bound to <B>TAB</B>, but is unbound
by default.
+<DT><B>menu-complete-rd</B>
+
+<DD>
+Identical to <B>menu-complete</B>, but moves backward through the list
+of possible completions, as if <B>menu-complete</B> had been given a
+negative argument. This command is unbound by default.
<DT><B>delete-char-or-list</B>
<DD>
<DD>
A character is read and point is moved to the previous occurrence of that
character. A negative count searches for subsequent occurrences.
+<DT><B>skip-csi-sequence ()</B>
+
+<DD>
+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 "\[", 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-[.
<DT><B>insert-comment (M-#)</B>
<DD>
<P>
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 <B>-E</B> option to <B>complete</B> 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 to not result in a compspec, any compspec defined with
+the <B>-D</B> option to <B>complete</B> is used as the default.
<P>
Once a compspec has been found, it is used to generate the list of
is used to filter the matches.
<P>
-Any completions specified by a filename expansion pattern to the
+Any completions specified by a pathname expansion pattern to the
<B>-G</B> option are generated next.
The words generated by the pattern need not match the word
being completed.
to completed names which are symbolic links to directories, subject to
the value of the <B>mark-directories</B> readline variable, regardless
of the setting of the <B>mark-symlinked-directories</B> readline variable.
+<P>
+
+There is some support for dynamically modifying completions. This is
+most useful when used in combination with a default completion specified
+with <B>complete -D</B>.
+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 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.
+<P>
+
+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:
+<P>
+
+<TT>_completion_loader()
+<BR>
+
+{
+<BR>
+
+<TT> </TT>. "/etc/bash_completion.d/$1.sh" >/dev/null 2>&1 && return 124<BR>
+<BR>
+
+}
+<BR>
+
+complete -D -F _completion_loader
+<BR>
+
+</TT>
<A NAME="lbCW"> </A>
<H3>HISTORY</H3>
builtin is enabled, the shell provides access to the
<I>command history</I>,
the list of commands previously typed.
-The value of the <B>HISTSIZE</B> variable is used as the
+The value of the
+<FONT SIZE=-1><B>HISTSIZE</B>
+
+</FONT>
+variable is used as the
number of commands to save in a history list.
The text of the last
<FONT SIZE=-1><B>HISTSIZE</B>
is unset, or if the history file is unwritable, the history is
not saved.
If the
-<FONT SIZE=-1>
+<FONT SIZE=-1><B>HISTTIMEFORMAT</B>
+
</FONT>
variable is set, time stamps are written to the history file, marked
with the history comment character, so
shell option is enabled (see the description of the
<B>shopt</B>
-builtin), and
+builtin below), and
<B>readline</B>
is being used, history substitutions are not immediately passed to
<B>--</B>
to signify the end of the options.
-For example, the <B>:</B>, <B>true</B>, <B>false</B>, and <B>test</B> builtins
-do not accept options.
+The <B>:</B>, <B>true</B>, <B>false</B>, and <B>test</B> builtins
+do not accept options and do not treat <B>--</B> specially.
+The <B>exit</B>, <B>logout</B>, <B>break</B>, <B>continue</B>, <B>let</B>,
+and <B>shift</B> builtins accept and process arguments beginning with
+<B>-</B> without requiring <B>--</B>.
+Other builtins that accept arguments but are not specified as accepting
+options interpret arguments beginning with <B>-</B> as invalid options and
+require <B>--</B> to prevent this interpretation.
<P>
<DL COMPACT>
Cause <I>shell-command</I> to be executed whenever <I>keyseq</I> is
entered.
When <I>shell-command</I> is executed, the shell sets the
-<B>READLINE_LINE</B>
+<FONT SIZE=-1><B>READLINE_LINE</B>
+</FONT>
variable to the contents of the <B>readline</B> line buffer and the
-<B>READLINE_POINT</B>
+<FONT SIZE=-1><B>READLINE_POINT</B>
+</FONT>
variable to the current location of the insertion point.
If the executed command changes the value of
-<B>READLINE_LINE</B>
+<FONT SIZE=-1><B>READLINE_LINE</B>
+</FONT>
or
-<B>READLINE_POINT</B>,
+<FONT SIZE=-1><B>READLINE_POINT</B>,
+</FONT>
those new values will be reflected in the editing state.
</DL>
<FONT SIZE=-1><B>$OLDPWD</B>.
</FONT>
-If a non-empty directory name from <B>CDPATH</B> is used, or if
+If a non-empty directory name from
+<FONT SIZE=-1><B>CDPATH</B>
+
+</FONT>
+is used, or if
<B>-</B> is the first argument, and the directory change is
successful, the absolute pathname of the new working directory is
written to the standard output.
<I>command</I>
is performed using a default value for
-<B>PATH</B>
+<FONT SIZE=-1><B>PATH</B>
+</FONT>
that is guaranteed to find all of the standard utilities.
If either the
<B>-V</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>-E</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>-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>
<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>-E</B>] [<I>name</I> ...]<DD>
+<DT><B>complete</B> <B>-pr</B> [<B>-DE</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
+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
apply to ``empty'' command completion; that is, completion attempted on a
blank line.
</DL></DL>
<DT><B>-G</B> <I>globpat</I><DD>
-The filename expansion pattern <I>globpat</I> is expanded to generate
+The pathname expansion pattern <I>globpat</I> is expanded to generate
the possible completions.
<DT><B>-W</B> <I>wordlist</I><DD>
The <I>wordlist</I> is split using the characters in the
</FONT>
array variable.
<DT><B>-X</B> <I>filterpat</I><DD>
-<I>filterpat</I> is a pattern as used for filename expansion.
+<I>filterpat</I> 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
<I>filterpat</I> is removed from the list.
an error occurs adding a completion specification.
</DL>
-<DT><B>compopt</B> [<B>-o</B> <I>option</I>] [<B>+o</B> <I>option</I>] [<I>name</I>]<DD>
+<DT><B>compopt</B> [<B>-o</B> <I>option</I>] [<B>-DE</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-execution 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
+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
+apply to ``empty'' command completion; that is, completion attempted on a
+blank line.
</DL>
<P>
<DD>
The variable is treated as an integer; arithmetic evaluation (see
-<FONT SIZE=-1><B>ARITHMETIC EVALUATION ) </B>
+<FONT SIZE=-1><B>ARITHMETIC EVALUATION</B>
</FONT>
-is performed when the variable is assigned a value.
+above) is performed when the variable is assigned a value.
<DT><B>-l</B>
<DD>
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 will not
+may not be used to destroy an array variable and <B>+r</B> will not
remove the readonly attribute.
When used in a function,
makes each
-</B><I>name</I> local, as with the
+<I>name</I> local, as with the
<B>local</B>
command.
If
<I>jobspec</I>
-is not present, and neither <B>-a nor -r</B> is supplied,
+is not present, and neither <B>-a</B> nor <B>-r</B> is supplied,
the shell's notion of the <I>current job</I> is used.
If the <B>-h</B> option is given, each
<I>jobspec</I>
<P>
When the end of options is encountered, <B>getopts</B> exits with a
return value greater than zero.
-<B>OPTIND</B> is set to the index of the first non-option argument,
+<FONT SIZE=-1><B>OPTIND</B>
+
+</FONT>
+is set to the index of the first non-option argument,
and <B>name</B> is set to ?.
<P>
<B>getopts</B>
<DD>
Display a short description of each <I>pattern</I>
-<DT><B> -m</B>
+<DT><B>-m</B>
<DD>
Display the description of each <I>pattern</I> in a manpage-like format
<I>n</I>
lines.
-If the shell variable <B>HISTTIMEFORMAT</B> is set and not null,
+If the shell variable
+<FONT SIZE=-1><B>HISTTIMEFORMAT</B>
+
+</FONT>
+is set and not null,
it is used as a format string for <I>strftime</I>(3) to display
the time stamp associated with each displayed history entry.
No intervening blank is printed between the formatted time stamp
</DL>
<P>
-If the <B>HISTTIMEFORMAT</B> is set, the time stamp information
+If the
+<FONT SIZE=-1><B>HISTTIMEFORMAT</B>
+
+</FONT>
+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
<I>arg</I>
is an arithmetic expression to be evaluated (see
-<FONT SIZE=-1><B>ARITHMETIC EVALUATION</B>).
+<FONT SIZE=-1><B>ARITHMETIC EVALUATION</B>
</FONT>
+above).
If the last
<I>arg</I>
<DT><B>readarray</B> [<B>-n</B> <I>count</I>] [<B>-O</B> <I>origin</I>] [<B>-s</B> <I>count</I>] [<B>-t</B>] [<B>-u</B> <I>fd</I>] [<B>-C</B> <I>callback</I>] [<B>-c</B> <I>quantum</I>] [<I>array</I>]<DD>
-Read lines from the standard input into array variable
+Read lines from the standard input into the indexed array variable
<I>array</I>,
or from file descriptor
<B>-u</B>
option is supplied.
-The variable <B>MAPFILE</B> is the default <I>array</I>.
+The variable
+<FONT SIZE=-1><B>MAPFILE</B>
+
+</FONT>
+is the default <I>array</I>.
Options, if supplied, have the following meanings:
<DL COMPACT><DT><DD>
<DT><B>-t</B>
<DD>
-Remove a trailing line from each line read.
+Remove a trailing newline from each line read.
<DT><B>-u</B>
<DD>
<P>
<B>mapfile</B> returns successfully unless an invalid option or option
-argument is supplied, or <I>array</I> is invalid or unassignable.
+argument is supplied, <I>array</I> is invalid or unassignable, or if
+<I>array</I> is not an indexed array.
</DL>
<DT><B>popd</B> [-<B>n</B>] [+<I>n</I>] [-<I>n</I>]<DD>
The return status is 0 unless an error occurs while
reading the name of the current directory or an
invalid option is supplied.
-<DT><B>read</B> [<B>-ers</B>] [<B>-a</B> <I>aname</I>] [<B>-d</B> <I>delim</I>] [<B>-</B> <I>text</I>] [<B>-n</B> <I>nchars</I>] [<B>-p</B> <I>prompt</I>] [<B>-t</B> <I>timeout</I>] [<B>-u</B> <I>fd</I>] [<I>name</I> ...]<DD>
+<DT><B>read</B> [<B>-ers</B>] [<B>-a</B> <I>aname</I>] [<B>-d</B> <I>delim</I>] [<B>-i</B> <I>text</I>] [<B>-n</B> <I>nchars</I>] [<B>-N</B> <I>nchars</I>] [<B>-p</B> <I>prompt</I>] [<B>-t</B> <I>timeout</I>] [<B>-u</B> <I>fd</I>] [<I>name</I> ...]<DD>
One line is read from the standard input, or from the file descriptor
<I>fd</I> supplied as an argument to the <B>-u</B> option, and the first word
is assigned to the first
<DD>
<B>read</B> returns after reading <I>nchars</I> characters rather than
-waiting for a complete line of input.
+waiting for a complete line of input, but honor a delimiter if fewer
+than <I>nchars</I> characters are read before the delimiter.
+<DT><B>-N </B><I>nchars</I>
+
+<DD>
+<B>read</B> returns after reading exactly <I>nchars</I> characters rather
+than waiting for a complete line of input, unless EOF is encountered or
+<B>read</B> times out.
+Delimiter characters encountered in the input are
+not treated specially and do not cause <B>read</B> to return until
+<I>nchars</I> characters are read.
<DT><B>-p </B><I>prompt</I>
<DD>
<DT><B>-e</B>
<DD>
-Exit immediately if a <I>simple command</I> (see
+Exit immediately if a <I>pipeline</I> (which may consist of a single
+<I>simple command</I>), a <I>subshell</I> command enclosed in parentheses,
+or one of the commands executed as part of a command list enclosed
+by braces (see
<FONT SIZE=-1><B>SHELL GRAMMAR</B>
</FONT>
<B>until</B>
keyword,
-part of the test in an
+part of the test following the
<B>if</B>
-statement, part of a command executed in a
+or
+<B>elif</B>
+
+reserved words, part of any command executed in a
<B>&&</B>
or
<B>||</B>
-list,
+list except the command following the final <B>&&</B> or <B>||</B>,
any command in a pipeline but the last,
or if the command's return value is
-being inverted via
+being inverted with
<B>!</B>.
-Failing simple commands that are part of shell functions or command lists
-enclosed in braces or parentheses satisfying the above conditions do not
-cause the shell to exit.
A trap on <B>ERR</B>, if set, is executed before the shell exits.
+This option applies to the shell environment and each subshell environment
+separately (see
+<FONT SIZE=-1><B>COMMAND EXECUTION ENVIRONMENT</B>
+
+</FONT>
+above), and may cause
+subshells to exit before executing all the commands in the subshell.
<DT><B>-f</B>
<DD>
option.
This also affects the editing interface used for <B>read -e</B>.
-<DT><B>errtrace</B>
+<DT><B>errexit</B>
<DD>
Same as
-<B>-E</B>.
+<B>-e</B>.
-<DT><B>functrace</B>
+<DT><B>errtrace</B>
<DD>
Same as
-<B>-T</B>.
+<B>-E</B>.
-<DT><B>errexit</B>
+<DT><B>functrace</B>
<DD>
Same as
-<B>-e</B>.
+<B>-T</B>.
<DT><B>hashall</B>
<FONT SIZE=-1><B>SHELLOPTS</B>,
</FONT>
-<B>CDPATH</B>,
+<FONT SIZE=-1><B>BASHOPTS</B>,
+
+</FONT>
+<FONT SIZE=-1><B>CDPATH</B>,
+</FONT>
and
-<B>GLOBIGNORE</B>
+<FONT SIZE=-1><B>GLOBIGNORE</B>
+</FONT>
variables, if they appear in the environment, are ignored.
If the shell is started with the effective user (group) id not equal to the
real user (group) id, and the <B>-p</B> option is not supplied, these actions
<DT><B>-u</B>
<DD>
-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.
<DT><B>-v</B>
If set, <B>bash</B> 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 <B>JOB CONTROL</B> above). The shell always
+intervening command (see
+<FONT SIZE=-1><B>JOB CONTROL</B>
+
+</FONT>
+above). The shell always
postpones exiting if any jobs are stopped.
<DT><B>checkwinsize</B>
changes its behavior to that of version 3.1 with respect to quoted
arguments to the conditional command's =~ operator.
+<DT><B>compat32</B>
+
+<DD>
+If set,
+<B>bash</B>
+
+changes its behavior to that of version 3.2 with respect to locale-specific
+string comparison when using the conditional command's < and > operators.
+<DT><B>compat40</B>
+
+<DD>
+If set,
+<B>bash</B>
+
+changes its behavior to that of version 4.0 with respect to locale-specific
+string comparison when using the conditional command's < and > operators
+and the effect of interrupting a command list.
<DT><B>dirspell</B>
<DD>
<DT><B>4.</B>
<DD>
-<B>BASH_ARGC</B> and <B>BASH_ARGV</B> are updated as described in their
-descriptions above.
+<FONT SIZE=-1><B>BASH_ARGC</B>
+
+</FONT>
+and
+<FONT SIZE=-1><B>BASH_ARGV</B>
+
+</FONT>
+are updated as described in their descriptions above.
<DT><B>5.</B>
<DD>
<DT><B>force_fignore</B>
<DD>
-If set, the suffixes specified by the <B>FIGNORE</B> shell variable
+If set, the suffixes specified by the
+<FONT SIZE=-1><B>FIGNORE</B>
+
+</FONT>
+shell variable
cause words to be ignored when performing word completion even if
the ignored words are the only possible completions.
See
<FONT SIZE=-1><B>SHELL VARIABLES</B></FONT>
-above for a description of <B>FIGNORE</B>.
+above for a description of
+<FONT SIZE=-1><B>FIGNORE</B>.
+
+</FONT>
This option is enabled by default.
<DT><B>globstar</B>
<DD>
-If set, the pattern <B>**</B> used in a filename expansion context will
+If set, the pattern <B>**</B> used in a pathname expansion context will
match a files and zero or more directories and subdirectories.
If the pattern is followed by a <B>/</B>, only directories and
subdirectories match.
<DD>
If set, the history list is appended to the file named by the value
of the
-<B>HISTFILE</B>
+<FONT SIZE=-1><B>HISTFILE</B>
+</FONT>
variable when the shell exits, rather than overwriting the file.
<DT><B>histreedit</B>
is being used,
<B>bash</B>
-will not attempt to search the <B>PATH</B> for possible completions when
+will not attempt to search the
+<FONT SIZE=-1><B>PATH</B>
+
+</FONT>
+for possible completions when
completion is attempted on an empty line.
<DT><B>nocaseglob</B>
is either
a signal name defined in <<I>signal.h</I>>, or a signal number.
Signal names are case insensitive and the SIG prefix is optional.
+<P>
+
+
If a
<I>sigspec</I>
If a
<I>sigspec</I>
+is
+<FONT SIZE=-1><B>RETURN</B>,
+
+</FONT>
+the command
+<I>arg</I>
+
+is executed each time a shell function or a script executed with the
+<B>.</B> or <B>source</B> builtins finishes executing.
+<P>
+
+
+If a
+<I>sigspec</I>
+
is
<FONT SIZE=-1><B>ERR</B>,
<B>!</B>.
These are the same conditions obeyed by the <B>errexit</B> option.
-If a
-<I>sigspec</I>
-
-is
-<FONT SIZE=-1><B>RETURN</B>,
+<P>
-</FONT>
-the command
-<I>arg</I>
-is executed each time a shell function or a script executed with the
-<B>.</B> or <B>source</B> builtins finishes executing.
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</I>
<DT><B>-m</B>
<DD>
-The maximum resident set size
+The maximum resident set size (many systems do not honor this limit)
<DT><B>-n</B>
<DD>
Each unset variable or function is removed from the environment
passed to subsequent commands.
If any of
+<FONT SIZE=-1><B>COMP_WORDBREAKS</B>,
+
+</FONT>
<FONT SIZE=-1><B>RANDOM</B>,
</FONT>
changing directories with <B>cd</B>
<DT>*<DD>
setting or unsetting the values of
-<B>SHELL</B>,
+<FONT SIZE=-1><B>SHELL</B>,
-<B>PATH</B>,
+</FONT>
+<FONT SIZE=-1><B>PATH</B>,
-<B>ENV</B>,
+</FONT>
+<FONT SIZE=-1><B>ENV</B>,
+</FONT>
or
-<B>BASH_ENV</B>
+<FONT SIZE=-1><B>BASH_ENV</B>
+</FONT>
<DT>*<DD>
specifying command names containing
<B>/</B>
<DT>*<DD>
importing function definitions from the shell environment at startup
<DT>*<DD>
-parsing the value of <B>SHELLOPTS</B> from the shell environment at startup
+parsing the value of
+<FONT SIZE=-1><B>SHELLOPTS</B>
+
+</FONT>
+from the shell environment at startup
<DT>*<DD>
redirecting output using the >, >|, <>, >&, &>, and >> redirection operators
<DT>*<DD>
Chet Ramey, Case Western Reserve University
<BR>
-<A HREF="mailto:chet@po.cwru.edu">chet@po.cwru.edu</A>
+<A HREF="mailto:chet.ramey@case.edu">chet.ramey@case.edu</A>
<A NAME="lbDG"> </A>
<H3>BUG REPORTS</H3>
<HR>
<TABLE WIDTH=100%>
<TR>
-<TH ALIGN=LEFT width=33%>GNU Bash-4.0<TH ALIGN=CENTER width=33%>2008 December 29<TH ALIGN=RIGHT width=33%>BASH(1)
+<TH ALIGN=LEFT width=33%>GNU Bash-4.1<TH ALIGN=CENTER width=33%>2009 December 29<TH ALIGN=RIGHT width=33%>BASH(1)
</TR>
</TABLE>
<HR>
</DL>
<HR>
This document was created by man2html from bash.1.<BR>
-Time: 05 February 2009 08:05:34 EST
+Time: 30 December 2009 13:07:38 EST
</BODY>
</HTML>
projects / thirdparty / bash.git / blobdiff