Brace Expansion:    Expansion of expressions within braces. ? Tilde Expansion:    Expansion of the ~ character. ? Shell Parameter Expansion:    How Bash expands variables to their values. ? Command Substitution:    Using the output of a command as an argument. ? Arithmetic Expansion:    How to use arithmetic in shell expansions. ? Process Substitution:    A way to write and read to and from a command. ? Word Splitting:    How the results of expansion are split into separate arguments. ? Filename Expansion:    A shorthand for specifying filenames matching patterns. ? Quote Removal:    How and when quote characters are removed from words.

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 filename expansion.

On systems that can support it, there is an additional expansion available: process substitution. This is performed at the same time as tilde, parameter, variable, and arithmetic expansion and command substitution.

After these expansions are performed, quote characters present in the original word are removed unless they have been quoted themselves (quote removal).

Only brace expansion, word splitting, and filename expansion 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 "$@" and $* (see Special Parameters), and "${name[@]}" and ${name[*]} (see Arrays).

After all expansions, quote removal (see Quote Removal) is performed.

Tilde Expansion, Up: Shell Expansions   [Contents][Index]

Filename Expansion), but the filenames generated need not exist. Patterns to be brace expanded take the form of an optional preamble, followed by either a series of comma-separated strings or a sequence expression between a pair of braces, followed by an optional postscript. The preamble is prefixed to each string contained within the braces, and the postscript is then appended to each resulting string, expanding left to right.

Brace expansions may be nested. The results of each expanded string are not sorted; left to right order is preserved. For example,

bash$ echo a{d,c,b}e
ade ace abe

A sequence expression takes the form {x..y[..incr]}, where x and y are either integers or single characters, and incr, an optional increment, is an integer. When integers are supplied, the expression expands to each number between x and y, inclusive. Supplied integers may be prefixed with ‘0’ to force each term to have the same width. When either x or y 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 x and y, inclusive, using the default C locale. Note that both x and y 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.

Brace expansion is performed before any other expansions, and any characters special to other expansions are preserved in the result. It is strictly textual. Bash does not apply any syntactic interpretation to the context of the expansion or the text between the braces.

A correctly-formed brace expansion must contain unquoted opening and closing braces, and at least one unquoted comma or a valid sequence expression. Any incorrectly formed brace expansion is left unchanged.

A { or ‘,’ may be quoted with a backslash to prevent its being considered part of a brace expression. To avoid conflicts with parameter expansion, the string ‘${’ is not considered eligible for brace expansion, and inhibits brace expansion until the closing ‘}’..

This construct is typically used as shorthand when the common prefix of the strings to be generated is longer than in the above example:

mkdir /usr/local/src/bash/{old,new,dist,bugs}

or

chown root /usr/{ucb/{ex,edit},lib/{ex?.?*,how_ex}}

Shell Parameter Expansion, Previous: Brace Expansion, Up: Shell Expansions   [Contents][Index]

The Directory Stack). If the tilde-prefix, sans the tilde, consists of a number without a leading ‘+’ or ‘-’, ‘+’ is assumed.

If the login name is invalid, or the tilde expansion fails, the word is left unchanged.

Each variable assignment is checked for unquoted tilde-prefixes immediately following a ‘:’ or the first ‘=’. In these cases, tilde expansion is also performed. Consequently, one may use filenames with tildes in assignments to PATH, MAILPATH, and CDPATH, and the shell assigns the expanded value.

The following table shows how Bash treats unquoted tilde-prefixes:

~

The value of $HOME

~/foo

$HOME/foo

~fred/foo

The subdirectory foo of the home directory of the user fred

~+/foo

$PWD/foo

~-/foo

${OLDPWD-'~-'}/foo

~N

The string that would be displayed by ‘dirs +N’

~+N

The string that would be displayed by ‘dirs +N’

~-N

The string that would be displayed by ‘dirs -N’

Bash also performs tilde expansion on words satisfying the conditions of variable assignments (see Shell Parameters) when they appear as arguments to simple commands. Bash does not do this, except for the declaration commands listed above, when in POSIX mode.

Command Substitution, Previous: Tilde Expansion, Up: Shell Expansions   [Contents][Index]

Shell Parameters) or an array reference (see Arrays). The braces are required when parameter is a positional parameter with more than one digit, or when parameter is followed by a character that is not to be interpreted as part of its name.

If the first character of parameter is an exclamation point (!), and parameter is not a nameref, it introduces a level of indirection. Bash uses the value formed by expanding the rest of parameter as the new parameter; this is then expanded and that value is used in the rest of the expansion, rather than the expansion of the original parameter. This is known as indirect expansion. The value is subject to tilde expansion, parameter expansion, command substitution, and arithmetic expansion. If parameter is a nameref, this expands to the name of the variable referenced by parameter instead of performing the complete indirect expansion. The exceptions to this are the expansions of ${!prefix*} and ${!name[@]} described below. The exclamation point must immediately follow the left brace in order to introduce indirection.

In each of the cases below, word is subject to tilde expansion, parameter expansion, command substitution, and arithmetic expansion.

When not performing substring expansion, using the form described below (e.g., ‘:-’), Bash tests for a parameter that is unset or null. Omitting the colon results in a test only for a parameter that is unset. Put another way, if the colon is included, the operator tests for both parameter’s existence and that its value is not null; if the colon is omitted, the operator tests only for existence.

${parameter:-word}

If parameter is unset or null, the expansion of word is substituted. Otherwise, the value of parameter is substituted.

${parameter:=word}

If parameter is unset or null, the expansion of word is assigned to parameter. The value of parameter is then substituted. Positional parameters and special parameters may not be assigned to in this way.

${parameter:?word}

If parameter is null or unset, the expansion of word (or a message to that effect if word is not present) is written to the standard error and the shell, if it is not interactive, exits. Otherwise, the value of parameter is substituted.

${parameter:+word}

If parameter is null or unset, nothing is substituted, otherwise the expansion of word is substituted.

${parameter:offset}

${parameter:offset:length}

This is referred to as Substring Expansion. It expands to up to length characters of the value of parameter starting at the character specified by offset. If parameter is ‘@’, an indexed array subscripted by ‘@’ or ‘*’, or an associative array name, the results differ as described below. If length is omitted, it expands to the substring of the value of parameter starting at the character specified by offset and extending to the end of the value. length and offset are arithmetic expressions (see Shell Arithmetic).

If offset evaluates to a number less than zero, the value is used as an offset in characters from the end of the value of parameter. If length evaluates to a number less than zero, it is interpreted as an offset in characters from the end of the value of parameter rather than a number of characters, and the expansion is the characters between offset 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 ‘:-’ expansion.

Here are some examples illustrating substring expansion on parameters and subscripted arrays:

$ string=01234567890abcdefgh
$ echo ${string:7}
7890abcdefgh
$ echo ${string:7:0}

$ echo ${string:7:2}
78
$ echo ${string:7:-2}
7890abcdef
$ echo ${string: -7}
bcdefgh
$ echo ${string: -7:0}

$ echo ${string: -7:2}
bc
$ echo ${string: -7:-2}
bcdef
$ set -- 01234567890abcdefgh
$ echo ${1:7}
7890abcdefgh
$ echo ${1:7:0}

$ echo ${1:7:2}
78
$ echo ${1:7:-2}
7890abcdef
$ echo ${1: -7}
bcdefgh
$ echo ${1: -7:0}

$ echo ${1: -7:2}
bc
$ echo ${1: -7:-2}
bcdef
$ array[0]=01234567890abcdefgh
$ echo ${array[0]:7}
7890abcdefgh
$ echo ${array[0]:7:0}

$ echo ${array[0]:7:2}
78
$ echo ${array[0]:7:-2}
7890abcdef
$ echo ${array[0]: -7}
bcdefgh
$ echo ${array[0]: -7:0}

$ echo ${array[0]: -7:2}
bc
$ echo ${array[0]: -7:-2}
bcdef

If parameter is ‘@’, the result is length positional parameters beginning at offset. A negative offset 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 length evaluates to a number less than zero.

The following examples illustrate substring expansion using positional parameters:

$ set -- 1 2 3 4 5 6 7 8 9 0 a b c d e f g h
$ echo ${@:7}
7 8 9 0 a b c d e f g h
$ echo ${@:7:0}

$ echo ${@:7:2}
7 8
$ echo ${@:7:-2}
bash: -2: substring expression < 0
$ echo ${@: -7:2}
b c
$ echo ${@:0}
./bash 1 2 3 4 5 6 7 8 9 0 a b c d e f g h
$ echo ${@:0:2}
./bash 1
$ echo ${@: -7:0}

If parameter is an indexed array name subscripted by ‘@’ or ‘*’, the result is the length members of the array beginning with ${parameter[offset]}. A negative offset is taken relative to one greater than the maximum index of the specified array. It is an expansion error if length evaluates to a number less than zero.

These examples show how you can use substring expansion with indexed arrays:

$ array=(0 1 2 3 4 5 6 7 8 9 0 a b c d e f g h)
$ echo ${array[@]:7}
7 8 9 0 a b c d e f g h
$ echo ${array[@]:7:2}
7 8
$ echo ${array[@]: -7:2}
b c
$ echo ${array[@]: -7:-2}
bash: -2: substring expression < 0
$ echo ${array[@]:0}
0 1 2 3 4 5 6 7 8 9 0 a b c d e f g h
$ echo ${array[@]:0:2}
0 1
$ echo ${array[@]: -7:0}

Substring expansion applied to an associative array produces undefined results.

Substring indexing is zero-based unless the positional parameters are used, in which case the indexing starts at 1 by default. If offset is 0, and the positional parameters are used, $@ is prefixed to the list.

${!prefix*}

${!prefix@}

Expands to the names of variables whose names begin with prefix, separated by the first character of the IFS special variable. When ‘@’ is used and the expansion appears within double quotes, each variable name expands to a separate word.

${!name[@]}

${!name[*]}

If name is an array variable, expands to the list of array indices (keys) assigned in name. If name is not an array, expands to 0 if name is set and null otherwise. When ‘@’ is used and the expansion appears within double quotes, each key expands to a separate word.

${#parameter}

The length in characters of the expanded value of parameter is substituted. If parameter is ‘*’ or ‘@’, the value substituted is the number of positional parameters. If parameter is an array name subscripted by ‘*’ or ‘@’, the value substituted is the number of elements in the array. If 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 parameter, so negative indices count back from the end of the array, and an index of -1 references the last element.

${parameter#word}

${parameter##word}

The word is expanded to produce a pattern and matched according to the rules described below (see Pattern Matching). If the pattern matches the beginning of the expanded value of parameter, then the result of the expansion is the expanded value of parameter with the shortest matching pattern (the ‘#’ case) or the longest matching pattern (the ‘##’ case) deleted. If parameter is ‘@’ or ‘*’, the pattern removal operation is applied to each positional parameter in turn, and the expansion is the resultant list. If parameter is an array variable subscripted with ‘@’ or ‘*’, the pattern removal operation is applied to each member of the array in turn, and the expansion is the resultant list.

${parameter%word}

${parameter%%word}

The word is expanded to produce a pattern and matched according to the rules described below (see Pattern Matching). If the pattern matches If the pattern matches a trailing portion of the expanded value of parameter, then the result of the expansion is the value of parameter with the shortest matching pattern (the ‘%’ case) or the longest matching pattern (the ‘%%’ case) deleted. If parameter is ‘@’ or ‘*’, the pattern removal operation is applied to each positional parameter in turn, and the expansion is the resultant list. If parameter is an array variable subscripted with ‘@’ or ‘*’, the pattern removal operation is applied to each member of the array in turn, and the expansion is the resultant list.

${parameter/pattern/string}

The pattern is expanded to produce a pattern just as in filename expansion. Parameter is expanded and the longest match of pattern against its value is replaced with string. The match is performed according to the rules described below (see Pattern Matching). If pattern begins with ‘/’, all matches of pattern are replaced with string. Normally only the first match is replaced. If pattern begins with ‘#’, it must match at the beginning of the expanded value of parameter. If pattern begins with ‘%’, it must match at the end of the expanded value of parameter. If string is null, matches of pattern are deleted and the / following pattern may be omitted. If the nocasematch shell option (see the description of shopt in The Shopt Builtin) is enabled, the match is performed without regard to the case of alphabetic characters. If parameter is ‘@’ or ‘*’, the substitution operation is applied to each positional parameter in turn, and the expansion is the resultant list. If parameter is an array variable subscripted with ‘@’ or ‘*’, the substitution operation is applied to each member of the array in turn, and the expansion is the resultant list.

${parameter^pattern}

${parameter^^pattern}

${parameter,pattern}

${parameter,,pattern}

This expansion modifies the case of alphabetic characters in parameter. The pattern is expanded to produce a pattern just as in filename expansion. Each character in the expanded value of parameter is tested against pattern, and, if it matches the pattern, its case is converted. The pattern should not attempt to match more than one character. The ‘^’ operator converts lowercase letters matching pattern to uppercase; the ‘,’ operator converts matching uppercase letters to lowercase. The ‘^^’ and ‘,,’ expansions convert each matched character in the expanded value; the ‘^’ and ‘,’ expansions match and convert only the first character in the expanded value. If pattern is omitted, it is treated like a ‘?’, which matches every character. If parameter is ‘@’ or ‘*’, the case modification operation is applied to each positional parameter in turn, and the expansion is the resultant list. If parameter is an array variable subscripted with ‘@’ or ‘*’, the case modification operation is applied to each member of the array in turn, and the expansion is the resultant list.

${parameter@operator}

The expansion is either a transformation of the value of parameter or information about parameter itself, depending on the value of operator. Each operator is a single letter:

Q

The expansion is a string that is the value of parameter quoted in a format that can be reused as input.

E

The expansion is a string that is the value of parameter with backslash escape sequences expanded as with the $'…' quoting mechanism.

P

The expansion is a string that is the result of expanding the value of parameter as if it were a prompt string (see Controlling the Prompt).

A

The expansion is a string in the form of an assignment statement or declare command that, if evaluated, will recreate parameter with its attributes and value.

a

The expansion is a string consisting of flag values representing parameter’s attributes.

If parameter is ‘@’ or ‘*’, the operation is applied to each positional parameter in turn, and the expansion is the resultant list. If parameter is an array variable subscripted with ‘@’ or ‘*’, the operation is applied to each member of the array in turn, and the expansion is the resultant list.

The result of the expansion is subject to word splitting and pathname expansion as described below.

Arithmetic Expansion, Previous: Shell Parameter Expansion, Up: Shell Expansions   [Contents][Index]

Process Substitution, Previous: Command Substitution, Up: Shell Expansions   [Contents][Index]

Shell Arithmetic). If the expression is invalid, Bash prints a message indicating failure to the standard error and no substitution occurs.

Word Splitting, Previous: Arithmetic Expansion, Up: Shell Expansions   [Contents][Index]

Filename Expansion, Previous: Process Substitution, Up: Shell Expansions   [Contents][Index]

Quote Removal, Previous: Word Splitting, Up: Shell Expansions   [Contents][Index]

Pattern Matching:    How the shell matches patterns.

The Set Builtin), Bash scans each word for the characters ‘*’, ‘?’, and ‘[’. If one of these characters appears, then the word is regarded as a pattern, and replaced with an alphabetically sorted list of filenames matching the pattern (see Pattern Matching). If no matching filenames are found, and the shell option nullglob is disabled, the word is left unchanged. If the nullglob option is set, and no matches are found, the word is removed. If the failglob shell option is set, and no matches are found, an error message is printed and the command is not executed. If the shell option nocaseglob is enabled, the match is performed without regard to the case of alphabetic characters.

When a pattern is used for filename expansion, the character ‘.’ at the start of a filename or immediately following a slash must be matched explicitly, unless the shell option dotglob is set. The filenames ‘.’ and ‘..’ must always be matched explicitly, even if dotglob is set. In other cases, the ‘.’ character is not treated specially.

When matching a filename, 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 (see Pattern Matching).

See the description of shopt in The Shopt Builtin, for a description of the nocaseglob, nullglob, failglob, and dotglob options.

The GLOBIGNORE shell variable may be used to restrict the set of file names matching a pattern. If GLOBIGNORE is set, each matching file name that also matches one of the patterns in GLOBIGNORE is removed from the list of matches. If the nocaseglob option is set, the matching against the patterns in GLOBIGNORE is performed without regard to case. The filenames.and..are always ignored when GLOBIGNORE is set and not null. However, setting GLOBIGNORE to a non-null value has the effect of enabling the dotglob shell option, so all other filenames beginning with a ‘.’ will match. To get the old behavior of ignoring filenames beginning with a ‘.’, make ‘.*’ one of the patterns in GLOBIGNORE. The dotglob option is disabled when GLOBIGNORE is unset.

Filename Expansion   [Contents][Index]

Filename Expansion, Up: Shell Expansions   [Contents][Index]

Executing Commands, Previous: Shell Expansions, Up: Basic Shell Features   [Contents][Index]

Shell Scripts, Previous: Redirections, Up: Basic Shell Features   [Contents][Index]

Simple Command Expansion:    How Bash expands simple commands before executing them. ? Command Search and Execution:    How Bash finds commands and runs them. ? Command Execution Environment:    The environment in which Bash executes commands that are not shell builtins. ? Environment:    The environment given to a command. ? Exit Status:    The status returned by commands and how Bash interprets it. ? Signals:    What happens when Bash or a command it runs receives a signal.

Command Search and Execution, Up: Executing Commands   [Contents][Index]

Shell Expansions). If any words remain after expansion, the first word is taken to be the name of the command and the remaining words are the arguments.

If no command name results, the variable assignments affect the current shell environment. Otherwise, the variables are added to the environment of the executed command and do not affect the current shell environment. If any of the assignments attempts to assign a value to a readonly variable, an error occurs, and the command exits with a non-zero status.

If no command name results, redirections are performed, but do not affect the current shell environment. A redirection error causes the command to exit with a non-zero status.

If there is a command name left after expansion, execution proceeds as described below. Otherwise, the command exits. If one of the expansions contained a command substitution, the exit status of the command is the exit status of the last command substitution performed. If there were no command substitutions, the command exits with a status of zero.

Command Execution Environment, Previous: Simple Command Expansion, Up: Executing Commands   [Contents][Index]

Shell Functions.

Environment, Previous: Command Search and Execution, Up: Executing Commands   [Contents][Index]

The Shopt Builtin)

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.

• the shell’s open files, plus any modifications and additions specified by redirections to the command
• the current working directory
• the file creation mode mask
• shell variables and functions marked for export, along with variables exported for the command, passed in the environment (see Environment)
• traps caught by the shell are reset to the values inherited from the shell’s parent, and traps ignored by the shell are ignored

A command invoked in this separate environment cannot affect the shell’s execution environment.

Command substitution, commands grouped with parentheses, and asynchronous commands are invoked in a subshell environment that is a duplicate of the shell environment, except that traps caught by the shell are reset to the values that the shell inherited from its parent at invocation. Builtin commands that are invoked as part of a pipeline are also executed in a subshell environment. Changes made to the subshell environment cannot affect the shell’s execution environment.

Subshells spawned to execute command substitutions inherit the value of the-eoption from the parent shell. When not in POSIX mode, Bash clears the-eoption in such subshells.

If a command is followed by a ‘&’ and job control is not active, the default standard input for the command is the empty file/dev/null. Otherwise, the invoked command inherits the file descriptors of the calling shell as modified by redirections.

Exit Status, Previous: Command Execution Environment, Up: Executing Commands   [Contents][Index]

Shell Parameters. These assignment statements affect only the environment seen by that command.

If the-koption is set (see The Set Builtin), then all parameter assignments are placed in the environment for a command, not just those that precede the command name.

When Bash invokes an external command, the variable ‘$_’ is set to the full pathname of the command and passed to that command in its environment.

Signals, Previous: Environment, Up: Executing Commands   [Contents][Index]

Conditional Constructs) and some of the list constructs (see Lists).

All of the Bash builtins return an exit status of zero if they succeed and a non-zero status on failure, so they may be used by the conditional and list constructs. All builtins return an exit status of 2 to indicate incorrect usage, generally invalid options or missing arguments.

Exit Status, Up: Executing Commands   [Contents][Index]

Job Control), Bash ignores SIGTTIN, SIGTTOU, and SIGTSTP.

Non-builtin commands started by Bash have signal handlers set to the values inherited by the shell from its parent. When job control is not in effect, asynchronous commands ignore SIGINT and SIGQUIT in addition to these inherited handlers. Commands run as a result of command substitution ignore the keyboard-generated job control signals SIGTTIN, SIGTTOU, and SIGTSTP.

The shell exits by default upon receipt of a SIGHUP. Before exiting, an interactive shell resends the SIGHUP to all jobs, running or stopped. Stopped jobs are sent SIGCONT to ensure that they receive the SIGHUP. To prevent the shell from sending the SIGHUP signal to a particular job, it should be removed from the jobs table with the disown builtin (see Job Control Builtins) or marked to not receive SIGHUP using disown -h.

If the huponexit shell option has been set with shopt (see The Shopt Builtin), Bash sends a SIGHUP to all jobs when an interactive login shell exits.

If Bash is waiting for a command to complete and receives a signal for which a trap has been set, the trap will not be executed until the command completes. When Bash is waiting for an asynchronous command via the wait builtin, the reception of a signal for which a trap has been set will cause the wait builtin to return immediately with an exit status greater than 128, immediately after which the trap is executed.

Executing Commands, Up: Basic Shell Features   [Contents][Index]

Invoking Bash), Bash reads and executes commands from the file, then exits. This mode of operation creates a non-interactive shell. The shell first searches for the file in the current directory, and looks in the directories in $PATH if not found there.

When Bash runs a shell script, it sets the special parameter 0 to the name of the file, rather than the name of the shell, and the positional parameters are set to the remaining arguments, if any are given. If no additional arguments are supplied, the positional parameters are unset.

A shell script may be made executable by using the chmod command to turn on the execute bit. When Bash finds such a file while searching the $PATH for a command, it spawns a subshell to execute it. In other words, executing

filename arguments

is equivalent to executing

bash filename arguments

if filename is an executable shell script. This subshell reinitializes itself, so that the effect is as if a new shell had been invoked to interpret the script, with the exception that the locations of commands remembered by the parent (see the description of hash in Bourne Shell Builtins) are retained by the child.

Most versions of Unix make this a part of the operating system’s command execution mechanism. If the first line of a script begins with the two characters ‘#!’, the remainder of the line specifies an interpreter for the program. Thus, you can specify Bash, awk, Perl, or some other interpreter and write the rest of the script file in that language.

The arguments to the interpreter consist of a single optional argument following the interpreter name on the first line of the script file, followed by the name of the script file, followed by the rest of the arguments. Bash will perform this action on operating systems that do not handle it themselves. Note that some older versions of Unix limit the interpreter name and argument to a maximum of 32 characters.

Bash scripts often begin with #! /bin/bash (assuming that Bash has been installed in/bin), since this ensures that Bash will be used to interpret the script, even if it is executed under another shell.

Shell Variables, Previous: Basic Shell Features, Up: Top   [Contents][Index]

Bourne Shell Builtins:    Builtin commands inherited from the Bourne Shell. ? Bash Builtins:    Table of builtins specific to Bash. ? Modifying Shell Behavior:    Builtins to modify shell attributes and optional behavior. ? Special Builtins:    Builtin commands classified specially by POSIX.

Builtin commands are contained within the shell itself. When the name of a builtin command is used as the first word of a simple command (see Simple Commands), the shell executes the command directly, without invoking another program. Builtin commands are necessary to implement functionality impossible or inconvenient to obtain with separate utilities.

This section briefly describes the builtins which Bash inherits from the Bourne Shell, as well as the builtin commands which are unique to or have been extended in Bash.

Several builtin commands are described in other chapters: builtin commands which provide the Bash interface to the job control facilities (see Job Control Builtins), the directory stack (see Directory Stack Builtins), the command history (see Bash History Builtins), and the programmable completion facilities (see Programmable Completion Builtins).

Many of the builtins have been extended by POSIX or Bash.

Unless otherwise noted, each builtin command documented as accepting options preceded by ‘-’ accepts ‘--’ to signify the end of the options. The :, true, false, and test/[ builtins do not accept options and do not treat ‘--’ specially. The exit, logout, return, break, continue, let, and shift builtins accept and process arguments beginning with ‘-’ without requiring ‘--’. Other builtins that accept arguments but are not specified as accepting options interpret arguments beginning with ‘-’ as invalid options and require ‘--’ to prevent this interpretation.

Bash Builtins, Up: Shell Builtin Commands   [Contents][Index]

Bash Conditional Expressions. test does not accept any options, nor does it accept and ignore an argument of--as signifying the end of options.

When the [ form is used, the last argument to the command must be a ].

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.

! expr

True if expr is false.

( expr )

Returns the value of expr. This may be used to override the normal precedence of operators.

expr1 -a expr2

True if both expr1 and expr2 are true.

expr1 -o expr2

True if either expr1 or expr2 is true.

The test and [ builtins evaluate conditional expressions using a set of rules based on the number of arguments.

0 arguments

The expression is false.

1 argument

The expression is true if, and only if, the argument is not null.

2 arguments

If the first argument is ‘!’, the expression is true if and only if the second argument is null. If the first argument is one of the unary conditional operators (see Bash Conditional Expressions), the expression is true if the unary test is true. If the first argument is not a valid unary operator, the expression is false.

3 arguments

The following conditions are applied in the order listed.

1. If the second argument is one of the binary conditional operators (see Bash Conditional Expressions), the result of the expression is the result of the binary test using the first and third arguments as operands. The ‘-a’ and ‘-o’ operators are considered binary operators when there are three arguments.
2. If the first argument is ‘!’, the value is the negation of the two-argument test using the second and third arguments.
3. If the first argument is exactly ‘(’ and the third argument is exactly ‘)’, the result is the one-argument test of the second argument.
4. Otherwise, the expression is false.

4 arguments

If the first argument is ‘!’, the result is the negation of the three-argument expression composed of the remaining arguments. Otherwise, the expression is parsed and evaluated according to precedence using the rules listed above.

5 or more arguments

The expression is parsed and evaluated according to precedence using the rules listed above.

When used with test or ‘[’, the ‘<’ and ‘>’ operators sort lexicographically using ASCII ordering.

Job Control Variables).

BASH The Shopt Builtin). The options appearing in BASHOPTS are those reported as ‘on’ by ‘shopt’. If this variable is in the environment when Bash starts up, each shell option in the list will be enabled before reading any startup files. This variable is readonly.

BASHPID Bourne Shell Builtins). Elements added to this array appear in the alias list; however, unsetting array elements currently does not cause aliases to be removed from the alias list. If BASH_ALIASES is unset, it loses its special properties, even if it is subsequently reset.

BASH_ARGC The Shopt Builtin for a description of the extdebug option to the shopt builtin). Setting extdebug after the shell has started to execute a script, or referencing this variable when extdebug is not set, may result in inconsistent values.

BASH_ARGV The Shopt Builtin for a description of the extdebug option to the shopt builtin). Setting extdebug after the shell has started to execute a script, or referencing this variable when extdebug is not set, may result in inconsistent values.

BASH_ARGV0 Special Parameters, for the description of special parameter 0). Assignment to BASH_ARGV0 causes the value assigned to also be assigned to $0. If BASH_ARGV0 is unset, it loses its special properties, even if it is subsequently reset.

BASH_CMDS Bourne Shell Builtins). Elements added to this array appear in the hash table; however, unsetting array elements currently does not cause command names to be removed from the hash table. If BASH_CMDS is unset, it loses its special properties, even if it is subsequently reset.

BASH_COMMAND The Shopt Builtin, 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 BASH_COMPAT is unset or set to the empty string, the compatibility level is set to the default for the current version. If BASH_COMPAT 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 shopt builtin described above (for example, compat42 means that 4.2 and 42 are valid values). The current version is also a valid value.

BASH_ENV Bash Startup Files.

BASH_EXECUTION_STRING Conditional Constructs). The element with index 0 is the portion of the string matching the entire regular expression. The element with index n is the portion of the string matching the nth parenthesized subexpression. This variable is read-only.

BASH_SOURCE Arrays) whose members hold version information for this instance of Bash. The values assigned to the array members are as follows:

BASH_VERSINFO[0]

The major version number (the release).

BASH_VERSINFO[1]

The minor version number (the version).

BASH_VERSINFO[2]

The patch level.

BASH_VERSINFO[3]

The build version.

BASH_VERSINFO[4]

The release status (e.g., beta1).

BASH_VERSINFO[5]

The value of MACHTYPE.

BASH_VERSION The Shopt Builtin), or in an interactive shell upon receipt of a SIGWINCH.

COMP_CWORD Programmable Completion).

COMP_LINE Programmable Completion).

COMP_POINT Programmable Completion).

COMP_TYPE Programmable Completion).

COMP_KEY Programmable Completion).

COMPREPLY Programmable Completion). Each array element contains one possible completion.

COPROC Coprocesses).

DIRSTACK Bash POSIX Mode).

EPOCHREALTIME Pattern Matching) defining the list of filenames to be ignored by command search using PATH. Files whose full pathnames match one of these patterns are not considered executable files for the purposes of completion and command execution via PATH lookup. This does not affect the behavior of the [, test, and [[ commands. Full pathnames in the command hash table are not subject to EXECIGNORE. Use this variable to ignore shared library files that have the executable bit set, but are not executable files. The pattern matching honors the setting of the extglob shell option.

FCEDIT History Interaction). The first character is the history expansion character, that is, the character which signifies the start of a history expansion, normally ‘!’. The second character is the character which signifies ‘quick substitution’ when seen as the first character on a line, normally ‘^’. The optional third character is the character which indicates that the remainder of the line is a comment when found as the first character of a word, usually ‘#’. The history comment character causes history substitution to be skipped for the remaining words on the line. It does not necessarily cause the shell parser to treat the rest of the line as a comment.

HISTCMD Filename Expansion).

LC_CTYPE Filename Expansion).

LC_MESSAGES Locale Translation).

LC_NUMERIC The Shopt Builtin), or in an interactive shell upon receipt of a SIGWINCH.

MACHTYPE Arrays) containing a list of exit status values from the processes in the most-recently-executed foreground pipeline (which may contain only a single command).

POSIXLY_CORRECT Bash POSIX Mode) before reading the startup files, as if the--posixinvocation option had been supplied. If it is set while the shell is running, Bash enables POSIX mode, as if the command

set -o posix

had been executed. When the shell enters POSIX mode, it sets this variable if it was not already set.

PPID Controlling the Prompt). Characters removed are replaced with an ellipsis.

PS0 The Set Builtin). The first character of the expanded value is replicated multiple times, as necessary, to indicate multiple levels of indirection. The default is ‘+’.

PWD Bash Builtins).

READLINE_POINT Bash Builtins).

REPLY The Set Builtin). The options appearing in SHELLOPTS are those reported as ‘on’ by ‘set -o’. If this variable is in the environment when Bash starts up, each shell option in the list will be enabled before reading any startup files. This variable is readonly.

SHLVL Bash Builtins). The select command (see Conditional Constructs) terminates if input does not arrive after 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 a line of input after issuing the primary prompt. Bash terminates after waiting for that number of seconds if a complete line of input does not arrive.

TMPDIR Job Control, Previous: Shell Variables, Up: Top   [Contents][Index]

Invoking Bash:    Command line options that you can give to Bash. ? Bash Startup Files:    When and how Bash executes scripts. ? Interactive Shells:    What an interactive shell is. ? Bash Conditional Expressions:    Primitives used in composing expressions for the test builtin. ? Shell Arithmetic:    Arithmetic on shell variables. ? Aliases:    Substituting one command for another. ? Arrays:    Array Variables. ? The Directory Stack:    History of visited directories. ? Controlling the Prompt:    Customizing the various prompt strings. ? The Restricted Shell:    A more controlled mode of shell execution. ? Bash POSIX Mode:    Making Bash behave more closely to what the POSIX standard specifies.

---

Bash Startup Files, Up: Bash Features   [Contents][Index]

The Set Builtin) can be used as options when the shell is invoked. In addition, there are several multi-character options that you can use. These options must appear on the command line before the single-character options to be recognized.

--debugger

Arrange for the debugger profile to be executed before the shell starts. Turns on extended debugging mode (see The Shopt Builtin for a description of the extdebug option to the shopt builtin).

--dump-po-strings

A list of all double-quoted strings preceded by ‘$’ is printed on the standard output in the GNU gettext PO (portable object) file format. Equivalent to-Dexcept for the output format.

--dump-strings

Equivalent to-D.

--help

Display a usage message on standard output and exit successfully.

--init-file filename

--rcfile filename

Execute commands from filename (instead of~/.bashrc) in an interactive shell.

--login

Equivalent to-l.

--noediting

Do not use the GNU Readline library (see Command Line Editing) to read command lines when the shell is interactive.

--noprofile

Don’t load the system-wide startup file/etc/profileor any of the personal initialization files~/.bash_profile,~/.bash_login, or~/.profilewhen Bash is invoked as a login shell.

--norc

Don’t read the~/.bashrcinitialization file in an interactive shell. This is on by default if the shell is invoked as sh.

--posix

Change the behavior of Bash where the default operation differs from the POSIX standard to match the standard. This is intended to make Bash behave as a strict superset of that standard. See Bash POSIX Mode, for a description of the Bash POSIX mode.

--restricted

Make the shell a restricted shell (see The Restricted Shell).

--verbose

Equivalent to-v. Print shell input lines as they’re read.

--version

Show version information for this instance of Bash on the standard output and exit successfully.

There are several single-character options that may be supplied at invocation which are not available with the set builtin.

-c

Read and execute commands from the first non-option argument command_string, then exit. If there are arguments after the command_string, the first argument is assigned to $0 and any remaining arguments are assigned to the positional parameters. The assignment to $0 sets the name of the shell, which is used in warning and error messages.

-i

Force the shell to run interactively. Interactive shells are described in Interactive Shells.

-l

Make this shell act as if it had been directly invoked by login. When the shell is interactive, this is equivalent to starting a login shell with ‘exec -l bash’. When the shell is not interactive, the login shell startup files will be executed. ‘exec bash -l’ or ‘exec bash --login’ will replace the current shell with a Bash login shell. See Bash Startup Files, for a description of the special behavior of a login shell.

-r

Make the shell a restricted shell (see The Restricted Shell).

-s

If this 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 or when reading input through a pipe.

-D

A list of all double-quoted strings preceded by ‘$’ is printed on the standard output. These are the strings that are subject to language translation when the current locale is not C or POSIX (see Locale Translation). This implies the-noption; no commands will be executed.

[-+]O [shopt_option]

shopt_option is one of the shell options accepted by the shopt builtin (see The Shopt Builtin). If shopt_option is present,-Osets the value of that option;+Ounsets it. If shopt_option is not supplied, the names and values of the shell options accepted by shopt are printed on the standard output. If the invocation option is+O, the output is displayed in a format that may be reused as input.

--

A -- signals the end of options and disables further option processing. Any arguments after the -- are treated as filenames and arguments.

Interactive Shells, for more information.

If arguments remain after option processing, and neither the-cnor the-soption has been supplied, the first argument is assumed to be the name of a file containing shell commands (see Shell Scripts). When Bash is invoked in this fashion, $0 is set to the name of the file, and the positional parameters are set to the remaining arguments. Bash reads and executes commands from this file, then exits. Bash’s exit status is the exit status of the last command executed in the script. If no commands are executed, the exit status is 0.

---

Interactive Shells, Previous: Invoking Bash, Up: Bash Features   [Contents][Index]

Tilde Expansion).

Interactive shells are described in Interactive Shells.

Bash Conditional Expressions, Previous: Bash Startup Files, Up: Bash Features   [Contents][Index]

What is an Interactive Shell?:    What determines whether a shell is Interactive. ? Is this Shell Interactive?:    How to tell if a shell is interactive. ? Interactive Shell Behavior:    What changes in a interactive shell?

---

Is this Shell Interactive?, Up: Interactive Shells   [Contents][Index]

Interactive Shell Behavior, Previous: What is an Interactive Shell?, Up: Interactive Shells   [Contents][Index]

Is this Shell Interactive?, Up: Interactive Shells   [Contents][Index]

Bash Startup Files.

Job Control (see Job Control) is enabled by default. When job control is in effect, Bash ignores the keyboard-generated job control signals SIGTTIN, SIGTTOU, and SIGTSTP.

Bash expands and displays PS1 before reading the first line of a command, and expands and displays PS2 before reading the second and subsequent lines of a multi-line command. Bash expands and displays PS0 after it reads a command but before executing it. See Controlling the Prompt, for a complete list of prompt string escape sequences.

Bash executes the value of the PROMPT_COMMAND variable as a command before printing the primary prompt, $PS1 (see Bash Variables).

Readline (see Command Line Editing) is used to read commands from the user’s terminal.

Bash inspects the value of the ignoreeof option to set -o instead of exiting immediately when it receives an EOF on its standard input when reading a command (see The Set Builtin).

Command history (see Bash History Facilities) and history expansion (see History Interaction) are enabled by default. Bash will save the command history to the file named by $HISTFILE when a shell with history enabled exits.

Alias expansion (see Aliases) is performed by default.

In the absence of any traps, Bash ignores SIGTERM (see Signals).

In the absence of any traps, SIGINT is caught and handled (see Signals). SIGINT will interrupt some shell builtins.

An interactive login shell sends a SIGHUP to all jobs on exit if the huponexit shell option has been enabled (see Signals).

The-ninvocation option is ignored, and ‘set -n’ has no effect (see The Set Builtin).

Bash will check for mail periodically, depending on the values of the MAIL, MAILPATH, and MAILCHECK shell variables (see Bash Variables).

Expansion errors due to references to unbound shell variables after ‘set -u’ has been enabled will not cause the shell to exit (see The Set Builtin).

The shell will not exit on expansion errors caused by var being unset or null in ${var:?word} expansions (see Shell Parameter Expansion).

Redirection errors encountered by shell builtins will not cause the shell to exit.

When running in POSIX mode, a special builtin returning an error status will not cause the shell to exit (see Bash POSIX Mode).

A failed exec will not cause the shell to exit (see Bourne Shell Builtins).

Parser syntax errors will not cause the shell to exit.

Simple spelling correction for directory arguments to the cd builtin is enabled by default (see the description of the cdspell option to the shopt builtin in The Shopt Builtin).

The shell will check the value of the TMOUT variable and exit if a command is not read within the specified number of seconds after printing $PS1 (see Bash Variables).

---

Shell Arithmetic, Previous: Interactive Shells, Up: Bash Features   [Contents][Index]

The Set Builtin).

-v varname

True if the shell variable varname is set (has been assigned a value).

-R varname

True if the shell variable varname is set and is a name reference.

-z string

True if the length of string is zero.

-n string

string

True if the length of string is non-zero.

string1 == string2

string1 = string2

True if the strings are equal. When used with the [[ command, this performs pattern matching as described above (see Conditional Constructs).

‘=’ should be used with the test command for POSIX conformance.

string1 != string2

True if the strings are not equal.

string1 < string2

True if string1 sorts before string2 lexicographically.

string1 > string2

True if string1 sorts after string2 lexicographically.

arg1 OP arg2

OP is one of ‘-eq’, ‘-ne’, ‘-lt’, ‘-le’, ‘-gt’, or ‘-ge’. These arithmetic binary operators return true if arg1 is equal to, not equal to, less than, less than or equal to, greater than, or greater than or equal to arg2, respectively. Arg1 and arg2 may be positive or negative integers. When used with the [[ command, Arg1 and Arg2 are evaluated as arithmetic expressions (see Shell Arithmetic).

Aliases, Previous: Bash Conditional Expressions, Up: Bash Features   [Contents][Index]

Arrays, Previous: Shell Arithmetic, Up: Bash Features   [Contents][Index]

Shell Functions).

Aliases are not expanded when the shell is not interactive, unless the expand_aliases shell option is set using shopt (see The Shopt Builtin).

The rules concerning the definition and use of aliases are somewhat confusing. Bash 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. The commands following the alias definition on that line are not affected by the new alias. This behavior is also an issue when functions are executed. Aliases are expanded when a function definition is read, not when the function is executed, because a function definition is itself a command. As a consequence, aliases defined in a function are not available until after that function is executed. To be safe, always put alias definitions on a separate line, and do not use alias in compound commands.

For almost every purpose, shell functions are preferred over aliases.

The Directory Stack, Previous: Aliases, Up: Bash Features   [Contents][Index]

Shell Arithmetic)) and are zero-based; associative arrays use arbitrary strings. Unless otherwise noted, indexed array indices must be non-negative integers.

An indexed array is created automatically if any variable is assigned to using the syntax

name[subscript]=value

The subscript is treated as an arithmetic expression that must evaluate to a number. To explicitly declare an array, use

declare -a name

The syntax

declare -a name[subscript]

is also accepted; the subscript is ignored.

Associative arrays are created using

declare -A name.

Attributes may be specified for an array variable using the declare and readonly builtins. Each attribute applies to all members of an array.

Arrays are assigned to using compound assignments of the form

name=(value1 value2 … )

where each value is of the form [subscript]=string. Indexed array assignments do not require anything but string. When assigning to indexed arrays, if the optional subscript is supplied, that index is assigned to; otherwise the index of the element assigned is the last index assigned to by the statement plus one. Indexing starts at zero.

When assigning to an associative array, the subscript is required.

This syntax is also accepted by the declare builtin. Individual array elements may be assigned to using the name[subscript]=value syntax introduced above.

When assigning to an indexed array, if name is subscripted by a negative number, that number is interpreted as relative to one greater than the maximum index of name, so negative indices count back from the end of the array, and an index of -1 references the last element.

Any element of an array may be referenced using ${name[subscript]}. The braces are required to avoid conflicts with the shell’s filename expansion operators. If the subscript is ‘@’ or ‘*’, the word expands to all members of the array name. These subscripts differ only when the word appears within double quotes. If the word is double-quoted, ${name[*]} expands to a single word with the value of each array member separated by the first character of the IFS variable, and ${name[@]} expands each element of name to a separate word. When there are no array members, ${name[@]} expands to nothing. If the double-quoted expansion occurs within a word, the expansion of the first parameter is joined with the beginning part of the original word, and the expansion of the last parameter is joined with the last part of the original word. This is analogous to the expansion of the special parameters ‘@’ and ‘*’. ${#name[subscript]} expands to the length of ${name[subscript]}. If subscript is ‘@’ or ‘*’, the expansion is the number of elements in the array. If the 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 refers to the last element.

Referencing an array variable without a subscript is equivalent to referencing with a subscript of 0. Any reference to a variable using a valid subscript is legal, and bash will create an array if necessary.

An array variable is considered set if a subscript has been assigned a value. The null string is a valid value.

It is possible to obtain the keys (indices) of an array as well as the values. ${!name[@]} and ${!name[*]} expand to the indices assigned in array variable name. The treatment when in double quotes is similar to the expansion of the special parameters ‘@’ and ‘*’ within double quotes.

The unset builtin is used to destroy arrays. unset name[subscript] destroys the array element at index subscript. Negative subscripts to indexed arrays are interpreted as described above. Unsetting the last element of an array variable does not unset the variable. unset name, where name is an array, removes the entire array. A subscript of ‘*’ or ‘@’ also removes the entire array.

When using a variable name with a subscript as an argument to a command, such as with unset, without using the word expansion syntax described above, the argument is subject to the shell’s filename expansion. If filename expansion is not desired, the argument should be quoted.

The declare, local, and readonly builtins each accept a-aoption to specify an indexed array and a-Aoption to specify an associative array. If both options are supplied,-Atakes precedence. The read builtin accepts a-aoption to assign a list of words read from the standard input to an array, and can read values from the standard input into individual array elements. The set and declare builtins display array values in a way that allows them to be reused as input.

Controlling the Prompt, Previous: Arrays, Up: Bash Features   [Contents][Index]

Directory Stack Builtins:    Bash builtin commands to manipulate the directory stack.

The directory stack is a list of recently-visited directories. The pushd builtin adds directories to the stack as it changes the current directory, and the popd builtin removes specified directories from the stack and changes the current directory to the directory removed. The dirs builtin displays the contents of the directory stack. The current directory is always the "top" of the directory stack.

The contents of the directory stack are also visible as the value of the DIRSTACK shell variable.

The Directory Stack   [Contents][Index]

The Restricted Shell, Previous: The Directory Stack, Up: Bash Features   [Contents][Index]

Bash History Facilities), while the command number is the position in the sequence of commands executed during the current shell session.

After the string is decoded, it is expanded via parameter expansion, command substitution, arithmetic expansion, and quote removal, subject to the value of the promptvars shell option (see The Shopt Builtin).

Bash POSIX Mode, Previous: Controlling the Prompt, Up: Bash Features   [Contents][Index]

Shell Scripts), rbash turns off any restrictions in the shell spawned to execute the script.

The Restricted Shell, Up: Bash Features   [Contents][Index]

Tilde Expansion.

There is other POSIX behavior that Bash does not implement by default even when in POSIX mode. Specifically:

1. The fc builtin checks $EDITOR as a program to edit history entries if FCEDIT is unset, rather than defaulting directly to ed. fc uses ed if EDITOR is unset.
2. As noted above, Bash requires the xpg_echo option to be enabled for the echo builtin to be fully conformant.

Bash can be configured to be POSIX-conformant by default, by specifying the--enable-strict-posix-defaultto configure when building (see Optional Features).

Command Line Editing, Previous: Bash Features, Up: Top   [Contents][Index]

Job Control Basics:    How job control works. ? Job Control Builtins:    Bash builtin commands used to interact with job control. ? Job Control Variables:    Variables Bash uses to customize job control.

Job Control Builtins, Up: Job Control   [Contents][Index]

The Set Builtin). Any trap on SIGCHLD is executed for each child process that exits.

If an attempt to exit Bash is made while jobs are stopped, (or running, if the checkjobs option is enabled – see The Shopt Builtin), the shell prints a warning message, and if the checkjobs option is enabled, lists the jobs and their statuses. The jobs command may then be used to inspect their status. If a second attempt to exit is made without an intervening command, Bash does not print another warning, and any stopped jobs are terminated.

When the shell is waiting for a job or process using the wait builtin, and job control is enabled, wait will return when the job changes state. The-foption will force wait to wait until the job or process terminates before returning.

Job Control Variables, Previous: Job Control Basics, Up: Job Control   [Contents][Index]

Job Control Builtins, Up: Job Control   [Contents][Index]

Job Control Basics). If set to any other value, the supplied string must be a prefix of a stopped job’s name; this provides functionality analogous to the ‘%’ job ID.

Using History Interactively, Previous: Job Control, Up: Top   [Contents][Index]

Bash Builtins). 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-o emacsor-o vioptions to the set builtin command (see The Set Builtin), or disabled using the+o emacsor+o vioptions to set.

Readline Interaction, Up: Command Line Editing   [Contents][Index]

Readline Init File). If your keyboard lacks a LFD key, typing C-j will produce the desired character. The RET key may be labeled Return or Enter on some keyboards.

Readline Init File, Previous: Introduction and Notation, Up: Command Line Editing   [Contents][Index]

Readline Bare Essentials:    The least you need to know about Readline. ? Readline Movement Commands:    Moving about the input line. ? Readline Killing Commands:    How to delete text, and how to get it back! ? Readline Arguments:    Giving numeric arguments to commands. ? Searching:    Searching through previous lines.

Readline Movement Commands, Up: Readline Interaction   [Contents][Index]

Readline Killing Commands, Previous: Readline Bare Essentials, Up: Readline Interaction   [Contents][Index]

Readline Arguments, Previous: Readline Movement Commands, Up: Readline Interaction   [Contents][Index]

Searching, Previous: Readline Killing Commands, Up: Readline Interaction   [Contents][Index]

Readline Arguments, Up: Readline Interaction   [Contents][Index]

Bash History Facilities) for lines containing a specified string. There are two search modes: incremental and non-incremental.

Incremental searches begin before the user has finished typing the search string. As each character of the search string is typed, Readline displays the next entry from the history matching the string typed so far. An incremental search requires only as many characters as needed to find the desired history entry. To search backward in the history for a particular string, type C-r. Typing C-s searches forward through the history. The characters present in the value of the isearch-terminators variable are used to terminate an incremental search. If that variable has not been assigned a value, the ESC and C-J characters will terminate an incremental search. C-g will abort an incremental search and restore the original line. When the search is terminated, the history entry containing the search string becomes the current line.

To find other matching entries in the history list, type C-r or C-s as appropriate. This will search backward or forward in the history for the next entry matching the search string typed so far. Any other key sequence bound to a Readline command will terminate the search and execute that command. For instance, a RET will terminate the search and accept the line, thereby executing the command from the history list. A movement command will terminate the search, make the last line found the current line, and begin editing.

Readline remembers the last incremental search string. If two C-rs are typed without any intervening characters defining a new search string, any remembered search string is used.

Non-incremental searches read the entire search string before starting to search for matching history lines. The search string may be typed by the user or be part of the contents of the current line.

Bindable Readline Commands, Previous: Readline Interaction, Up: Command Line Editing   [Contents][Index]

Readline Init File Syntax:    Syntax for the commands in the inputrc file.   ? Conditional Init Constructs:    Conditional key bindings in the inputrc file.   ? Sample Init File:    An example inputrc file.

Conditional Init Constructs, Up: Readline Init File   [Contents][Index]

Conditional Init Constructs). Other lines denote variable settings and key bindings.

Variable Settings

You can modify the run-time behavior of Readline by altering the values of variables in Readline using the set command within the init file. The syntax is simple:

set variable value

Here, for example, is how to change from the default Emacs-like key binding to use vi line editing commands:

set editing-mode vi

Variable names and values, where appropriate, are recognized without regard to case. Unrecognized variable names are ignored.

Boolean variables (those that can be set to on or off) are set to on if the value is null or empty, on (case-insensitive), or 1. Any other value results in the variable being set to off.

The bind -V command lists the current Readline variable names and values. See Bash Builtins.

A great deal of run-time behavior is changeable with the following variables.

Searching). If this variable has not been given a value, the characters ESC and C-J will terminate an incremental search.

keymap

Bash Builtins.

keyname: function-name or macro

keyname is the name of a key spelled out in English. For example:

Control-u: universal-argument
Meta-Rubout: backward-kill-word
Control-o: "> output"

In the example above, C-u is bound to the function universal-argument, M-DEL is bound to the function backward-kill-word, and C-o is bound to run the macro expressed on the right hand side (that is, to insert the text ‘> output’ into the line).

A number of symbolic character names are recognized while processing this key binding syntax: DEL, ESC, ESCAPE, LFD, NEWLINE, RET, RETURN, RUBOUT, SPACE, SPC, and TAB.

"keyseq": function-name or macro

keyseq differs from keyname above in that strings denoting an entire key sequence can be specified, by placing the key sequence in double quotes. Some GNU Emacs style key escapes can be used, as in the following example, but the special character names are not recognized.

"\C-u": universal-argument
"\C-x\C-r": re-read-init-file
"\e[11~": "Function Key 1"

In the above example, C-u is again bound to the function universal-argument (just as it was in the first example), ‘C-x C-r’ is bound to the function re-read-init-file, and ‘ESC [ 1 1 ~’ is bound to insert the text ‘Function Key 1’.

The following GNU Emacs style escape sequences are available when specifying key sequences:

\C-

control prefix

\M-

meta prefix

\e

an escape character

\\

backslash

\"

", a double quotation mark

\'

', a single quote or apostrophe

In addition to the GNU Emacs style escape sequences, a second set of backslash escapes is available:

\a

alert (bell)

\b

backspace

\d

delete

\f

form feed

\n

newline

\r

carriage return

\t

horizontal tab

\v

vertical tab

\nnn

the eight-bit character whose value is the octal value nnn (one to three digits)

\xHH

the eight-bit character whose value is the hexadecimal value HH (one or two hex digits)

When entering the text of a macro, single or double quotes must be used to indicate a macro definition. Unquoted text is assumed to be a function name. In the macro body, the backslash escapes described above are expanded. Backslash will quote any other character in the macro text, including ‘"’ and ‘'’. For example, the following binding will make ‘C-x \’ insert a single ‘\’ into the line:

"\C-x\\": "\\"

Sample Init File, Previous: Readline Init File Syntax, Up: Readline Init File   [Contents][Index]

Conditional Init Constructs, Up: Readline Init File   [Contents][Index]

Readline vi Mode, Previous: Readline Init File, Up: Command Line Editing   [Contents][Index]

Commands For Moving:    Moving about the line. ? Commands For History:    Getting at previous lines. ? Commands For Text:    Commands for changing text. ? Commands For Killing:    Commands for killing and yanking. ? Numeric Arguments:    Specifying numeric arguments, repeat counts. ? Commands For Completion:    Getting Readline to do the typing for you. ? Keyboard Macros:    Saving and re-executing typed characters ? Miscellaneous Commands:    Other miscellaneous commands.

This section describes Readline commands that may be bound to key sequences. You can list your key bindings by executing bind -P or, for a more terse format, suitable for an inputrc file, bind -p. (See Bash Builtins.) Command names without an accompanying key sequence are unbound by default.

In the following descriptions, point refers to the current cursor position, and mark refers to a cursor position saved by the set-mark command. The text between the point and mark is referred to as the region.

Commands For History, Up: Bindable Readline Commands   [Contents][Index]

Commands For Text, Previous: Commands For Moving, Up: Bindable Readline Commands   [Contents][Index]

Commands For Killing, Previous: Commands For History, Up: Bindable Readline Commands   [Contents][Index]

Numeric Arguments, Previous: Commands For Text, Up: Bindable Readline Commands   [Contents][Index]

Commands For Completion, Previous: Commands For Killing, Up: Bindable Readline Commands   [Contents][Index]

Keyboard Macros, Previous: Numeric Arguments, Up: Bindable Readline Commands   [Contents][Index]

Brace Expansion).

Miscellaneous Commands, Previous: Commands For Completion, Up: Bindable Readline Commands   [Contents][Index]

Keyboard Macros, Up: Bindable Readline Commands   [Contents][Index]

Shell Expansions).

The Set Builtin). The Readline default is emacs mode.

When you enter a line in vi mode, you are already placed in ‘insertion’ mode, as if you had typed an ‘i’. Pressing ESC switches you into ‘command’ mode, where you can edit the text of the line with the standard vi movement keys, move to previous history lines with ‘k’ and subsequent lines with ‘j’, and so forth.

Programmable Completion Builtins, Previous: Readline vi Mode, Up: Command Line Editing   [Contents][Index]

Programmable Completion Builtins), the programmable completion facilities are invoked.

First, the command name is identified. 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 the empty string (completion attempted at the beginning of an empty line), any compspec defined with the-Eoption to complete is used. 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-Doption to complete is used as the default. If there is no default compspec, Bash 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

Once a compspec has been found, it is used to generate the list of matching words. If a compspec is not found, the default Bash completion described above (see Commands For Completion) is performed.

First, the actions specified by the compspec are used. Only matches which are prefixed by the word being completed are returned. When the-for-doption is used for filename or directory name completion, the shell variable FIGNORE is used to filter the matches. See Bash Variables, for a description of FIGNORE.

Any completions specified by a filename expansion pattern to the-Goption are generated next. The words generated by the pattern need not match the word being completed. The GLOBIGNORE shell variable is not used to filter the matches, but the FIGNORE shell variable is used.

Next, the string specified as the argument to the-Woption is considered. The string is first split using the characters in the IFS special variable as delimiters. Shell quoting is honored within the string, in order to provide a mechanism for the words to contain shell metacharacters or characters in the value of IFS. Each word is then expanded using brace expansion, tilde expansion, parameter and variable expansion, command substitution, and arithmetic expansion, as described above (see Shell Expansions). The results are split using the rules described above (see Word Splitting). The results of the expansion are prefix-matched against the word being completed, and the matching words become the possible completions.

After these matches have been generated, any shell function or command specified with the-Fand-Coptions is invoked. When the command or function is invoked, the COMP_LINE, COMP_POINT, COMP_KEY, and COMP_TYPE variables are assigned values as described above (see Bash Variables). If a shell function is being invoked, the COMP_WORDS and COMP_CWORD variables are also set. When the function or command is invoked, the first argument ($1) is the name of the command whose arguments are being completed, the second argument ($2) is the word being completed, and the third argument ($3) 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.

Any function specified with-Fis invoked first. The function may use any of the shell facilities, including the compgen and compopt builtins described below (see Programmable Completion Builtins), to generate the matches. It must put the possible completions in the COMPREPLY array variable, one per array element.

Next, any command specified with the-Coption is invoked in an environment equivalent to command substitution. It should print a list of completions, one per line, to the standard output. Backslash may be used to escape a newline, if necessary.

After all of the possible completions are generated, any filter specified with the-Xoption is applied to the list. The filter is a pattern as used for pathname expansion; a ‘&’ in the pattern is replaced with the text of the word being completed. A literal ‘&’ may be escaped with a backslash; the backslash is removed before attempting a match. Any completion that matches the pattern will be removed from the list. A leading ‘!’ negates the pattern; in this case any completion not matching the pattern will be removed. If the nocasematch shell option (see the description of shopt in The Shopt Builtin) is enabled, the match is performed without regard to the case of alphabetic characters.

Finally, any prefix and suffix specified with the-Pand-Soptions are added to each member of the completion list, and the result is returned to the Readline completion code as the list of possible completions.

If the previously-applied actions do not generate any matches, and the-o dirnamesoption was supplied to complete when the compspec was defined, directory name completion is attempted.

If the-o plusdirsoption was supplied to complete when the compspec was defined, directory name completion is attempted and any matches are added to the results of the other actions.

By default, if a compspec is found, whatever it generates is returned to the completion code as the full set of possible completions. The default Bash completions are not attempted, and the Readline default of filename completion is disabled. If the-o bashdefaultoption was supplied to complete when the compspec was defined, the default Bash completions are attempted if the compspec generates no matches. If the-o defaultoption was supplied to complete when the compspec was defined, Readline’s default completion will be performed if the compspec (and, if attempted, the default Bash completions) generate no matches.

When a compspec indicates that directory name completion is desired, the programmable completion functions force Readline to append a slash to completed names which are symbolic links to directories, subject to the value of the mark-directories Readline variable, regardless of the setting of the mark-symlinked-directories Readline variable.

There is some support for dynamically modifying completions. This is most useful when used in combination with a default completion specified with-D. 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.

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:

_completion_loader()
{
    . "/etc/bash_completion.d/$1.sh" >/dev/null 2>&1 && return 124
}
complete -D -F _completion_loader -o bashdefault -o default

A Programmable Completion Example, Previous: Programmable Completion, Up: Command Line Editing   [Contents][Index]

Programmable Completion).

Other options, if specified, have the following meanings. The arguments to the-G,-W, and-Xoptions (and, if necessary, the-Pand-Soptions) should be quoted to protect them from expansion before the complete builtin is invoked.

-o comp-option

The comp-option controls several aspects of the compspec’s behavior beyond the simple generation of completions. comp-option may be one of:

bashdefault

Perform the rest of the default Bash completions if the compspec generates no matches.

default

Use Readline’s default filename completion if the compspec generates no matches.

dirnames

Perform directory name completion if the compspec generates no matches.

filenames

Tell Readline that the compspec generates filenames, so it can perform any filename-specific processing (like adding a slash to directory names, quoting special characters, or suppressing trailing spaces). This option is intended to be used with shell functions specified with-F.

noquote

Tell Readline not to quote the completed words if they are filenames (quoting filenames is the default).

nosort

Tell Readline not to sort the list of possible completions alphabetically.

nospace

Tell Readline not to append a space (the default) to words completed at the end of the line.

plusdirs

After any matches defined by the compspec are generated, directory name completion is attempted and any matches are added to the results of the other actions.

-A action

The action may be one of the following to generate a list of possible completions:

alias

Alias names. May also be specified as-a.

arrayvar

Array variable names.

binding

Readline key binding names (see Bindable Readline Commands).

builtin

Names of shell builtin commands. May also be specified as-b.

command

Command names. May also be specified as-c.

directory

Directory names. May also be specified as-d.

disabled

Names of disabled shell builtins.

enabled

Names of enabled shell builtins.

export

Names of exported shell variables. May also be specified as-e.

file

File names. May also be specified as-f.

function

Names of shell functions.

group

Group names. May also be specified as-g.

helptopic

Help topics as accepted by the help builtin (see Bash Builtins).

hostname

Hostnames, as taken from the file specified by the HOSTFILE shell variable (see Bash Variables).

job

Job names, if job control is active. May also be specified as-j.

keyword

Shell reserved words. May also be specified as-k.

running

Names of running jobs, if job control is active.

service

Service names. May also be specified as-s.

setopt

Valid arguments for the-ooption to the set builtin (see The Set Builtin).

shopt

Shell option names as accepted by the shopt builtin (see Bash Builtins).

signal

Signal names.

stopped

Names of stopped jobs, if job control is active.

user

User names. May also be specified as-u.

variable

Names of all shell variables. May also be specified as-v.

-C command

command is executed in a subshell environment, and its output is used as the possible completions.

-F function

The shell function function is executed in the current shell environment. When it is executed, $1 is the name of the command whose arguments are being completed, $2 is the word being completed, and $3 is the word preceding the word being completed, as described above (see Programmable Completion). When it finishes, the possible completions are retrieved from the value of the COMPREPLY array variable.

-G globpat

The filename expansion pattern globpat is expanded to generate the possible completions.

-P prefix

prefix is added at the beginning of each possible completion after all other options have been applied.

-S suffix

suffix is appended to each possible completion after all other options have been applied.

-W wordlist

The wordlist is split using the characters in the 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.

-X filterpat

filterpat 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 filterpat is removed from the list. A leading ‘!’ in filterpat negates the pattern; in this case, any completion not matching filterpat is removed.

The return value is true unless an invalid option is supplied, an option other than-por-ris supplied without a name argument, an attempt is made to remove a completion specification for a name for which no specification exists, or an error occurs adding a completion specification.