diff options
Diffstat (limited to 'doc/bashref.texi')
| -rw-r--r-- | doc/bashref.texi | 317 |
1 files changed, 255 insertions, 62 deletions
diff --git a/doc/bashref.texi b/doc/bashref.texi index c0f4a2f8..c97e1175 100644 --- a/doc/bashref.texi +++ b/doc/bashref.texi @@ -14,7 +14,7 @@ This is Edition @value{EDITION}, last updated @value{UPDATED}, of @cite{The GNU Bash Reference Manual}, for @code{Bash}, Version @value{VERSION}. -Copyright @copyright{} 1988--2016 Free Software Foundation, Inc. +Copyright @copyright{} 1988--2018 Free Software Foundation, Inc. @quotation Permission is granted to copy, distribute and/or modify this document @@ -508,7 +508,7 @@ double quote question mark @item \@var{nnn} the eight-bit character whose value is the octal value @var{nnn} -(one to three digits) +(one to three octal digits) @item \x@var{HH} the eight-bit character whose value is the hexadecimal value @var{HH} (one or two hex digits) @@ -659,8 +659,13 @@ the time information. If the pipeline is not executed asynchronously (@pxref{Lists}), the shell waits for all commands in the pipeline to complete. -Each command in a pipeline is executed in its own subshell -(@pxref{Command Execution Environment}). The exit +Each command in a pipeline is executed in its own subshell, which is a +separate process (@pxref{Command Execution Environment}). +If the @code{lastpipe} option is enabled using the @code{shopt} builtin +(@pxref{The Shopt Builtin}), +the last element of a pipeline may be run by the shell process. + +The exit status of a pipeline is the exit status of the last command in the pipeline, unless the @code{pipefail} option is enabled (@pxref{The Set Builtin}). @@ -714,7 +719,7 @@ An @sc{and} list has the form @noindent @var{command2} is executed if, and only if, @var{command1} -returns an exit status of zero. +returns an exit status of zero (success). An @sc{or} list has the form @example @@ -739,7 +744,7 @@ executed in the list. * Command Grouping:: Ways to group commands. @end menu -Compound commands are the shell programming constructs. +Compound commands are the shell programming language constructs. Each construct begins with a reserved word or control operator and is terminated by a corresponding reserved word or operator. Any redirections (@pxref{Redirections}) associated with a compound command @@ -798,12 +803,14 @@ The syntax of the @code{for} command is: for @var{name} [ [in [@var{words} @dots{}] ] ; ] do @var{commands}; done @end example -Expand @var{words}, and execute @var{commands} once for each member +Expand @var{words} (@pxref{Shell Expansions}), and execute @var{commands} +once for each member in the resultant list, with @var{name} bound to the current member. If @samp{in @var{words}} is not present, the @code{for} command executes the @var{commands} once for each positional parameter that is set, as if @samp{in "$@@"} had been specified (@pxref{Special Parameters}). + The return status is the exit status of the last command that executes. If there are no items in the expansion of @var{words}, no commands are executed, and the return status is zero. @@ -874,6 +881,8 @@ case @var{word} in [ [(] @var{pattern} [| @var{pattern}]@dots{}) @var{command-li @code{case} will selectively execute the @var{command-list} corresponding to the first @var{pattern} that matches @var{word}. +The match is performed according +to the rules described below in @ref{Pattern Matching}. If the @code{nocasematch} shell option (see the description of @code{shopt} in @ref{The Shopt Builtin}) is enabled, the match is performed without regard to the case @@ -885,7 +894,9 @@ as a @var{clause}. Each clause must be terminated with @samp{;;}, @samp{;&}, or @samp{;;&}. The @var{word} undergoes tilde expansion, parameter expansion, command -substitution, arithmetic expansion, and quote removal before matching is +substitution, arithmetic expansion, and quote removal +(@pxref{Shell Parameter Expansion}) +before matching is attempted. Each @var{pattern} undergoes tilde expansion, parameter expansion, command substitution, and arithmetic expansion. @@ -1010,7 +1021,7 @@ If the @code{nocasematch} shell option is enabled, the match is performed without regard to the case of alphabetic characters. The return value is 0 if the string matches (@samp{==}) or does not -match (@samp{!=})the pattern, and 1 otherwise. +match (@samp{!=}) the pattern, and 1 otherwise. Any part of the pattern may be quoted to force the quoted portion to be matched as a string. @@ -1045,7 +1056,7 @@ if there is a sequence of characters in the value consisting of any number, including zero, of space characters, zero or one instances of @samp{a}, then a @samp{b}: @example -[[ $line =~ [[:space:]]*(a)?b ]] +[[ $line =~ [[:space:]]*?(a)b ]] @end example @noindent @@ -1061,7 +1072,7 @@ expressions while paying attention to the shell's quote removal. Using a shell variable to store the pattern decreases these problems. For example, the following is equivalent to the above: @example -pattern='[[:space:]]*(a)?b' +pattern='[[:space:]]*?(a)b' [[ $line =~ $pattern ]] @end example @@ -1197,7 +1208,8 @@ This pipe is established before any redirections specified by the command (@pxref{Redirections}). The file descriptors can be utilized as arguments to shell commands and redirections using standard word expansions. -The file descriptors are not available in subshells. +Other than those created to execute command and process substitutions, +the file descriptors are not available in subshells. The process ID of the shell spawned to execute the coprocess is available as the value of the variable @env{NAME}_PID. @@ -1308,7 +1320,7 @@ will ensure that the output of @code{traceroute foss.org.my} is displayed first. Finally, Parallel can be used to run a sequence of shell commands in parallel, similar to @samp{cat file | bash}. It is not uncommon to take a list of filenames, create a series of shell -commands to operate on them, and feed that list of commnds to a shell. +commands to operate on them, and feed that list of commands to a shell. Parallel can speed this up. Assuming that @file{file} contains a list of shell commands, one per line, @@ -1424,7 +1436,66 @@ before the @code{return}. Variables local to the function may be declared with the @code{local} builtin. These variables are visible only to -the function and the commands it invokes. +the function and the commands it invokes. This is particularly +important when a shell function calls other functions. + +Local variables "shadow" variables with the same name declared at +previous scopes. For instance, a local variable declared in a function +hides a global variable of the same name: references and assignments +refer to the local variable, leaving the global variable unmodified. +When the function returns, the global variable is once again visible. + +The shell uses @var{dynamic scoping} to control a variable's visibility +within functions. +With dynamic scoping, visible variables and their values +are a result of the sequence of function calls that caused execution +to reach the current function. +The value of a variable that a function sees depends +on its value within its caller, if any, whether that caller is +the "global" scope or another shell function. +This is also the value that a local variable +declaration "shadows", and the value that is restored when the function +returns. + +For example, if a variable @var{var} is declared as local in function +@var{func1}, and @var{func1} calls another function @var{func2}, +references to @var{var} made from within @var{func2} will resolve to the +local variable @var{var} from @var{func1}, shadowing any global variable +named @var{var}. + +The following script demonstrates this behavior. +When executed, the script displays + +@example +In func2, var = func1 local +@end example + +@example +func1() +@{ + local var='func1 local' + func2 +@} + +func2() +@{ + echo "In func2, var = $var" +@} + +var=global +func1 +@end example + +The @code{unset} builtin also acts using the same dynamic scope: if a +variable is local to the current scope, @code{unset} will unset it; +otherwise the unset will refer to the variable found in any calling scope +as described above. +If a variable at the current local scope is unset, it will remain so +until it is reset in that scope or until the function returns. +Once the function returns, any instance of the variable at a previous +scope will become visible. +If the unset acts on a variable at a previous scope, any instance of a +variable with that name that had been shadowed will become visible. Function names and definitions may be listed with the @option{-f} option to the @code{declare} (@code{typeset}) @@ -1437,10 +1508,6 @@ Functions may be exported so that subshells automatically have them defined with the @option{-f} option to the @code{export} builtin (@pxref{Bourne Shell Builtins}). -Note that shell functions and variables with the same name may result -in multiple identically-named entries in the environment passed to the -shell's children. -Care should be taken in cases where this may cause a problem. Functions may be recursive. The @code{FUNCNEST} variable may be used to limit the depth of the @@ -1708,10 +1775,11 @@ original word are removed unless they have been quoted themselves (@var{quote removal}). Only brace expansion, word splitting, and filename expansion -can change the number of words of the expansion; other expansions +can increase the number of words of the expansion; other expansions expand a single word to a single word. The only exceptions to this are the expansions of -@code{"$@@"} (@pxref{Special Parameters}) and @code{"$@{@var{name}[@@]@}"} +@code{"$@@"} and @code{$*} (@pxref{Special Parameters}), and +@code{"$@{@var{name}[@@]@}"} and @code{$@{@var{name}[*]@}} (@pxref{Arrays}). After all expansions, @code{quote removal} (@pxref{Quote Removal}) @@ -1765,8 +1833,6 @@ 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. -To avoid conflicts with parameter expansion, the string @samp{$@{} -is not considered eligible for brace expansion. A correctly-formed brace expansion must contain unquoted opening and closing braces, and at least one unquoted comma or a valid @@ -1776,7 +1842,8 @@ Any incorrectly formed brace expansion is left unchanged. A @{ or @samp{,} may be quoted with a backslash to prevent its being considered part of a brace expression. To avoid conflicts with parameter expansion, the string @samp{$@{} -is not considered eligible for brace expansion. +is not considered eligible for brace expansion, +and inhibits brace expansion until the closing @samp{@}}.. This construct is typically used as shorthand when the common prefix of the strings to be generated is longer than in the @@ -1893,6 +1960,8 @@ Bash uses the value of the variable formed from the rest of expanded and that value is used in the rest of the substitution, rather than the value of @var{parameter} itself. This is known as @code{indirect expansion}. +The value is subject to tilde expansion, +parameter expansion, command substitution, and arithmetic expansion. If @var{parameter} is a nameref, this expands to the name of the variable referenced by @var{parameter} instead of performing the complete indirect expansion. @@ -2120,8 +2189,8 @@ array, and an index of -1 references the last element. @item $@{@var{parameter}#@var{word}@} @itemx $@{@var{parameter}##@var{word}@} The @var{word} -is expanded to produce a pattern just as in filename -expansion (@pxref{Filename Expansion}). If the pattern matches +is expanded to produce a pattern and matched according to the rules +described below (@pxref{Pattern Matching}). If the pattern matches the beginning of the expanded value of @var{parameter}, then the result of the expansion is the expanded value of @var{parameter} with the shortest matching pattern (the @samp{#} case) or the @@ -2136,8 +2205,9 @@ array in turn, and the expansion is the resultant list. @item $@{@var{parameter}%@var{word}@} @itemx $@{@var{parameter}%%@var{word}@} -The @var{word} is expanded to produce a pattern just as in -filename expansion. +The @var{word} +is expanded to produce a pattern and matched according to the rules +described below (@pxref{Pattern Matching}). If the pattern matches If the pattern matches a trailing portion of the expanded value of @var{parameter}, then the result of the expansion is the value of @var{parameter} with the shortest matching pattern (the @samp{%} case) @@ -2156,6 +2226,8 @@ The @var{pattern} is expanded to produce a pattern just as in filename expansion. @var{Parameter} is expanded and the longest match of @var{pattern} against its value is replaced with @var{string}. +The match is performed according to the rules described below +(@pxref{Pattern Matching}). If @var{pattern} begins with @samp{/}, all matches of @var{pattern} are replaced with @var{string}. Normally only the first match is replaced. If @var{pattern} begins with @samp{#}, it must match at the beginning @@ -2213,7 +2285,7 @@ The expansion is a string that is the value of @var{parameter} quoted in a format that can be reused as input. @item E The expansion is a string that is the value of @var{parameter} with backslash -escape sequences expanded as with the @code{$'@dots{}'} quoting mechansim. +escape sequences expanded as with the @code{$'@dots{}'} quoting mechanism. @item P The expansion is a string that is the result of expanding the value of @var{parameter} as if it were a prompt string (@pxref{Controlling the Prompt}). @@ -2410,18 +2482,23 @@ without regard to the case of alphabetic characters. When a pattern is used for filename expansion, the character @samp{.} at the start of a filename or immediately following a slash must be matched explicitly, unless the shell option @code{dotglob} is set. -When matching a filename, the slash character must always be -matched explicitly. +The filenames @samp{.} and @samp{..} must always be matched explicitly, +even if @code{dotglob} is set. In other cases, the @samp{.} 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 (@pxref{Pattern Matching}). + See the description of @code{shopt} in @ref{The Shopt Builtin}, for a description of the @code{nocaseglob}, @code{nullglob}, @code{failglob}, and @code{dotglob} options. The @env{GLOBIGNORE} -shell variable may be used to restrict the set of filenames matching a +shell variable may be used to restrict the set of file names matching a pattern. If @env{GLOBIGNORE} -is set, each matching filename that also matches one of the patterns in +is set, each matching file name that also matches one of the patterns in @env{GLOBIGNORE} is removed from the list of matches. If the @code{nocaseglob} option is set, the matching against the patterns in @env{GLOBIGNORE} is performed without regard to case. @@ -2533,6 +2610,12 @@ Matches one of the given patterns. Matches anything except one of the given patterns. @end table +Complicated extended pattern matching against long strings is slow, +especially when the patterns contain alternations and the strings +contain multiple matches. +Using separate matches against shorter strings, or using arrays of +strings instead of a single long string, may be faster. + @node Quote Removal @subsection Quote Removal @@ -2565,6 +2648,9 @@ In this case, for each redirection operator except than 10 and assign it to @{@var{varname}@}. If >&- or <&- is preceded by @{@var{varname}@}, the value of @var{varname} defines the file descriptor to close. +If @{@var{varname}@} is supplied, the redirection persists beyond +the scope of the command, allowing the shell programmer to manage +the file descriptor himself. In the following descriptions, if the file descriptor number is omitted, and the first character of the redirection operator is @@ -2761,7 +2847,7 @@ A variant of here documents, the format is: @end example The @var{word} undergoes -brace expansion, tilde expansion, parameter and variable expansion, +tilde expansion, parameter and variable expansion, command substitution, arithmetic expansion, and quote removal. Pathname expansion and word splitting are not performed. The result is supplied as a single string, @@ -2922,9 +3008,10 @@ A full search of the directories in @env{$PATH} is performed only if the command is not found in the hash table. If the search is unsuccessful, the shell searches for a defined shell function named @code{command_not_found_handle}. -If that function exists, it is invoked with the original command and +If that function exists, it is invoked in a separate execution environment +with the original command and the original command's arguments as its arguments, and the function's -exit status becomes the exit status of the shell. +exit status becomes the exit status of that subshell. If that function is not defined, the shell prints an error message and returns an exit status of 127. @@ -3262,7 +3349,7 @@ Many of the builtins have been extended by @sc{posix} or Bash. Unless otherwise noted, each builtin command documented as accepting options preceded by @samp{-} accepts @samp{--} to signify the end of the options. -The @code{:}, @code{true}, @code{false}, and @code{test} +The @code{:}, @code{true}, @code{false}, and @code{test}/@code{[} builtins do not accept options and do not treat @samp{--} specially. The @code{exit}, @code{logout}, @code{return}, @code{break}, @code{continue}, @code{let}, @@ -3417,6 +3504,7 @@ cannot be executed for some reason, a non-interactive shell exits, unless the @code{execfail} shell option is enabled. In that case, it returns failure. An interactive shell returns failure if the file cannot be executed. +A subshell exits unconditionally if @code{exec} fails. If no @var{command} is specified, redirections may be used to affect the current shell environment. If there are no redirection errors, the return status is zero; otherwise the return status is non-zero. @@ -3525,7 +3613,7 @@ The @option{-d} option causes the shell to forget the remembered location of each @var{name}. If the @option{-t} option is supplied, the full pathname to which each @var{name} corresponds is printed. If multiple @var{name} arguments are -supplied with @option{-t} the @var{name} is printed before the hashed +supplied with @option{-t}, the @var{name} is printed before the hashed full pathname. The @option{-l} option causes output to be displayed in a format that may be reused as input. @@ -3587,7 +3675,7 @@ If @var{n} is not supplied, the return value is the exit status of the last command executed in the function. If @code{return} is executed by a trap handler, the last command used to determine the status is the last command executed before the trap handler. -if @code{return} is executed during a @code{DEBUG} trap, the last command +If @code{return} is executed during a @code{DEBUG} trap, the last command used to determine the status is the last command executed by the trap handler before @code{return} was invoked. @code{return} may also be used to terminate execution of a script @@ -3668,7 +3756,7 @@ expressions using a set of rules based on the number of arguments. The expression is false. @item 1 argument -The expression is true if and only if the argument is not null. +The expression is true if, and only if, the argument is not null. @item 2 arguments If the first argument is @samp{!}, the expression is true if and @@ -4280,6 +4368,8 @@ Options, if supplied, have the following meanings: @item -d The first character of @var{delim} is used to terminate each input line, rather than newline. +If @var{delim} is the empty string, @code{mapfile} will terminate a line +when it reads a NUL character. @item -n Copy at most @var{count} lines. If @var{count} is 0, all lines are copied. @item -O @@ -4292,7 +4382,7 @@ Remove a trailing @var{delim} (default newline) from each line read. @item -u Read lines from file descriptor @var{fd} instead of the standard input. @item -C -Evaluate @var{callback} each time @var{quantum}P lines are read. +Evaluate @var{callback} each time @var{quantum} lines are read. The @option{-c} option specifies @var{quantum}. @item -c Specify the number of lines read between each call to @var{callback}. @@ -4405,11 +4495,13 @@ Other @var{name} arguments are ignored. @item -d @var{delim} The first character of @var{delim} is used to terminate the input line, rather than newline. +If @var{delim} is the empty string, @code{read} will terminate a line +when it reads a NUL character. @item -e Readline (@pxref{Command Line Editing}) is used to obtain the line. Readline uses the current (or default, if line editing was not previously -active) editing settings. +active) editing settings, but uses Readline's default filename completion. @item -i @var{text} If Readline is being used to read the line, @var{text} is placed into @@ -4972,7 +5064,8 @@ The settings can be either those listed below, or, if the @option{-o} option is used, those available with the @option{-o} option to the @code{set} builtin command (@pxref{The Set Builtin}). With no options, or with the @option{-p} option, a list of all settable -options is displayed, with an indication of whether or not each is set. +options is displayed, with an indication of whether or not each is set; +if @var{optnames} are supplied, the output is restricted to those options. The @option{-p} option causes output to be displayed in a form that may be reused as input. Other options have the following meanings: @@ -5012,6 +5105,11 @@ option. The list of @code{shopt} options is: @table @code +@item assoc_expand_once +If set, the shell suppresses multiple evaluation of associative array +subscripts during arithmetic expression evaluation and while executing +builtins that can perform variable assignments. + @item autocd If set, a command name that is the name of a directory is executed as if it were the argument to the @code{cd} command. @@ -5044,8 +5142,8 @@ intervening command (@pxref{Job Control}). The shell always postpones exiting if any jobs are stopped. @item checkwinsize -If set, Bash checks the window size after each command - and, if necessary, updates the values of +If set, Bash checks the window size after each external (non-builtin) +command and, if necessary, updates the values of @env{LINES} and @env{COLUMNS}. @item cmdhist @@ -5053,6 +5151,8 @@ If set, Bash attempts to save all lines of a multiple-line command in the same history entry. This allows easy re-editing of multi-line commands. +This option is enabled by default, but only has an effect if command +history is enabled (@pxref{Bash History Facilities}). @item compat31 If set, Bash @@ -5106,6 +5206,11 @@ and does not reset the loop state when a shell function is executed (this allows @code{break} or @code{continue} in a shell function to affect loops in the caller's context). +@item compat44 +If set, Bash +saves the positional parameters to BASH_ARGV and BASH_ARGC before they are +used, regardless of whether or not extended debugging mode is enabled. + @item complete_fullquote If set, Bash quotes all shell metacharacters in filenames and directory names when @@ -5138,6 +5243,8 @@ if the directory name initially supplied does not exist. @item dotglob If set, Bash includes filenames beginning with a `.' in the results of filename expansion. +The filenames @samp{.} and @samp{..} must always be matched explicitly, +even if @code{dotglob} is set. @item execfail If this is set, a non-interactive shell will not exit if @@ -5271,6 +5378,11 @@ If enabled, and the @code{cmdhist} option is enabled, multi-line commands are saved to the history with embedded newlines rather than using semicolon separators where possible. +@item localvar_inherit +If set, local variables inherit the value and attributes of a variable of +the same name that exists at a previous scope before any new value is +assigned. The @var{nameref} attribute is not inherited. + @item login_shell The shell sets this option if it is started as a login shell (@pxref{Invoking Bash}). @@ -5444,6 +5556,8 @@ sequences that are expanded before @env{PS1} is displayed. @item PS2 The secondary prompt string. The default value is @samp{> }. +@env{PS2} is expanded in the same way as @env{PS1} before being +displayed. @end vtable @@ -5476,6 +5590,10 @@ reading any startup files. This variable is readonly. Expands to the process ID of the current Bash process. This differs from @code{$$} under certain circumstances, such as subshells that do not require Bash to be re-initialized. +Assignments to @env{BASHPID} have no effect. +If @code{BASHPID} +is unset, it loses its special properties, even if it is +subsequently reset. @item BASH_ALIASES An associative array variable whose members correspond to the internal @@ -5499,6 +5617,8 @@ The shell sets @code{BASH_ARGC} only when in extended debugging mode (see @ref{The Shopt Builtin} for a description of the @code{extdebug} option to the @code{shopt} builtin). +Setting @code{extdebug} after the shell has started to execute a script +may result in inconsistent values. @item BASH_ARGV An array variable containing all of the parameters in the current bash @@ -5510,6 +5630,18 @@ The shell sets @code{BASH_ARGV} only when in extended debugging mode (see @ref{The Shopt Builtin} for a description of the @code{extdebug} option to the @code{shopt} builtin). +Setting @code{extdebug} after the shell has started to execute a script +may result in inconsistent values. + +@item BASH_ARGV0 +When referenced, this variable expands to the name of the shell or shell +script (identical to @code{$0}; @xref{Special Parameters}, +for the description of special parameter 0). +Assignment to @code{BASH_ARGV0} +causes the value assigned to also be assigned to @code{$0}. +If @code{BASH_ARGV0} +is unset, it loses its special properties, even if it is +subsequently reset. @item BASH_CMDS An associative array variable whose members correspond to the internal @@ -5726,6 +5858,23 @@ Emacs shell buffer and disables line editing. Similar to @code{BASH_ENV}; used when the shell is invoked in @sc{posix} Mode (@pxref{Bash POSIX Mode}). +@item EPOCHREALTIME +Each time this parameter is referenced, it expands to the number of seconds +since the Unix Epoch as a floating point value with micro-second granularity +(see the documentation for the C library function @var{time} for the +definition of Epoch). +Assignments to @env{EPOCHREALTIME} are ignored. +If @env{EPOCHREALTIME} is unset, it loses its special properties, even if +it is subsequently reset. + +@item EPOCHSECONDS +Each time this parameter is referenced, it expands to the number of seconds +since the Unix Epoch (see the documentation for the C library function +@var{time} for the definition of Epoch). +Assignments to @env{EPOCHSECONDS} are ignored. +If @env{EPOCHSECONDS} is unset, it loses its special properties, even if +it is subsequently reset. + @item EUID The numeric effective user id of the current user. This variable is readonly. @@ -5783,9 +5932,9 @@ nesting level. Function invocations that exceed this nesting level will cause the current command to abort. @item GLOBIGNORE -A colon-separated list of patterns defining the set of filenames to +A colon-separated list of patterns defining the set of file names to be ignored by filename expansion. -If a filename matched by a filename expansion pattern also matches one +If a file name matched by a filename expansion pattern also matches one of the patterns in @env{GLOBIGNORE}, it is removed from the list of matches. The pattern matching honors the setting of the @code{extglob} shell @@ -5916,7 +6065,7 @@ as the sole input. If set, the value denotes the number of consecutive @code{EOF} characters that can be read as the first character on an input line before the shell will exit. If the variable exists but does not -have a numeric value (or has no value) then the default is 10. +have a numeric value, or has no value, then the default is 10. If the variable does not exist, then @code{EOF} signifies the end of input to the shell. This is only in effect for interactive shells. @@ -6034,10 +6183,11 @@ The value of this variable is used as the prompt for the @code{select} command prompts with @samp{#? } @item PS4 -The value is the prompt printed before the command line is echoed -when the @option{-x} option is set (@pxref{The Set Builtin}). -The first character of @env{PS4} is replicated multiple times, as -necessary, to indicate multiple levels of indirection. +The value of this parameter is expanded like @var{PS1} +and the expanded value is the prompt printed before the command line +is echoed when the @option{-x} option is set (@pxref{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 @samp{+ }. @item PWD @@ -6286,7 +6436,8 @@ Make the shell a restricted shell (@pxref{The Restricted Shell}). 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. +when invoking an interactive shell or when reading input +through a pipe. @item -D A list of all double-quoted strings preceded by @samp{$} @@ -6526,7 +6677,10 @@ signals @code{SIGTTIN}, @code{SIGTTOU}, and @code{SIGTSTP}. Bash expands and displays @env{PS1} before reading the first line of a command, and expands and displays @env{PS2} before reading the second and subsequent lines of a multi-line command. -Bash displays @env{PS0} after it reads a command but before executing it. +Bash expands and displays @env{PS0} after it reads a command but before +executing it. +See @ref{Controlling the Prompt}, for a complete list of prompt +string escape sequences. @item Bash executes the value of the @env{PROMPT_COMMAND} variable as a command @@ -6558,7 +6712,7 @@ In the absence of any traps, Bash ignores @code{SIGTERM} @item In the absence of any traps, @code{SIGINT} is caught and handled -((@pxref{Signals}). +(@pxref{Signals}). @code{SIGINT} will interrupt some shell builtins. @item @@ -6758,6 +6912,8 @@ is equal to, not equal to, less than, less than or equal to, greater than, or greater than or equal to @var{arg2}, respectively. @var{Arg1} and @var{arg2} may be positive or negative integers. +When used with the @code{[[} command, @var{Arg1} and @var{Arg2} +are evaluated as arithmetic expressions (@pxref{Shell Arithmetic}). @end table @node Shell Arithmetic @@ -7047,12 +7203,16 @@ The @code{unset} builtin is used to destroy arrays. @code{unset @var{name}[@var{subscript}]} destroys the array element at index @var{subscript}. Negative subscripts to indexed arrays are interpreted as described above. -Care must be taken to avoid unwanted side effects caused by filename -expansion. +Unsetting the last element of an array variable does not unset the variable. @code{unset @var{name}}, where @var{name} is an array, removes the entire array. A subscript of @samp{*} or @samp{@@} also removes the entire array. +When using a variable name with a subscript as an argument to a command, +such as with @code{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 @code{declare}, @code{local}, and @code{readonly} builtins each accept a @option{-a} option to specify an indexed array and a @option{-A} option to specify an associative array. @@ -7186,7 +7346,8 @@ has a non-null value, then the value is executed just as if it had been typed on the command line. In addition, the following table describes the special characters which -can appear in the prompt variables @env{PS1} to @env{PS4}: +can appear in the prompt variables @env{PS0}, @env{PS1}, @env{PS2}, and +@env{PS4}: @table @code @item \a @@ -7738,6 +7899,11 @@ The @code{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 @code{wait} +builtin, and job control is enabled, @code{wait} will return when the +job changes state. The @option{-f} option will force @code{wait} to wait +until the job or process terminates before returning. + @node Job Control Builtins @section Job Control Builtins @@ -7834,7 +8000,7 @@ or non-zero if an error occurs or an invalid option is encountered. @item wait @btindex wait @example -wait [-n] [@var{jobspec} or @var{pid} @dots{}] +wait [-fn] [@var{jobspec} or @var{pid} @dots{}] @end example Wait until the child process specified by each process @sc{id} @var{pid} @@ -7845,6 +8011,9 @@ If no arguments are given, all currently active child processes are waited for, and the return status is zero. If the @option{-n} option is supplied, @code{wait} waits for any job to terminate and returns its exit status. +If the @option{-f} option is supplied, and job control is enabled, +@code{wait} forces each @var{pid} or @var{jobspec} to terminate before +returning its status, intead of returning when it changes status. If neither @var{jobspec} nor @var{pid} specifies an active child process of the shell, the return status is 127. @@ -7997,12 +8166,28 @@ To find out more about the options and arguments that the @code{configure} script understands, type @example -bash-2.04$ ./configure --help +bash-4.2$ ./configure --help @end example @noindent at the Bash prompt in your Bash source directory. +If you want to build Bash in a directory separate from the source +directory -- to build for multiple architectures, for example -- +just use the full path to the configure script. The following commands +will build bash in a directory under @file{/usr/local/build} from +the source code in @file{/usr/local/src/bash-4.4}: + +@example +mkdir /usr/local/build/bash-4.4 +cd /usr/local/build/bash-4.4 +bash /usr/local/src/bash-4.4/configure +make +@end example + +See @ref{Compiling For Multiple Architectures} for more information +about building in a directory separate from the source. + If you need to do unusual things to compile Bash, please try to figure out how @code{configure} could check whether or not to do them, and mail diffs or instructions to @@ -8052,7 +8237,9 @@ own directory. To do this, you must use a version of @code{make} that supports the @code{VPATH} variable, such as GNU @code{make}. @code{cd} to the directory where you want the object files and executables to go and run -the @code{configure} script from the source directory. You may need to +the @code{configure} script from the source directory +(@pxref{Basic Installation}). +You may need to supply the @option{--srcdir=PATH} argument to tell @code{configure} where the source files are. @code{configure} automatically checks for the source code in the directory that @code{configure} is in and in `..'. @@ -8224,7 +8411,7 @@ compiled and linked, rather than changing run-time features. @table @code @item --enable-largefile -Enable support for @uref{http://www.sas.com/standards/large_file/x_open.20Mar96.html, +Enable support for @uref{http://www.unix.org/version2/whatsnew/lfs20mar.html, large files} if the operating system requires special compiler options to build programs which can access large files. This is enabled by default, if the operating system provides large file support. @@ -8301,6 +8488,12 @@ Include support for coprocesses and the @code{coproc} reserved word @item --enable-debugger Include support for the bash debugger (distributed separately). +@item --enable-dev-fd-stat-broken +If calling @code{stat} on /dev/fd/@var{N} returns different results than +calling @code{fstat} on file descriptor @var{N}, supply this option to +enable a workaround. +This has implications for conditional commands that test file attributes. + @item --enable-direxpand-default Cause the @code{direxpand} shell option (@pxref{The Shopt Builtin}) to be enabled by default when the shell starts. @@ -8373,7 +8566,7 @@ If Readline is not enabled, this option has no effect. @item --enable-prompt-string-decoding Turn on the interpretation of a number of backslash-escaped characters -in the @env{$PS1}, @env{$PS2}, @env{$PS3}, and @env{$PS4} prompt +in the @env{$PS0}, @env{$PS1}, @env{$PS2}, and @env{$PS4} prompt strings. See @ref{Controlling the Prompt}, for a complete list of prompt string escape sequences. |