diff options
Diffstat (limited to 'doc/bashref.texi')
| -rw-r--r-- | doc/bashref.texi | 162 |
1 files changed, 120 insertions, 42 deletions
diff --git a/doc/bashref.texi b/doc/bashref.texi index c310664c..bf8e3d03 100644 --- a/doc/bashref.texi +++ b/doc/bashref.texi @@ -24,7 +24,7 @@ are preserved on all copies. @quotation Permission is granted to copy, distribute and/or modify this document -under the terms of the GNU Free Documentation License, Version 1.2 or +under the terms of the GNU Free Documentation License, Version 1.3 or any later version published by the Free Software Foundation; with no Invariant Sections, with the Front-Cover texts being ``A GNU Manual'', and with the Back-Cover Texts as in (a) below. A copy of the license is @@ -498,6 +498,7 @@ alert (bell) @item \b backspace @item \e +@itemx \E an escape character (not ANSI C) @item \f form feed @@ -513,6 +514,8 @@ vertical tab backslash @item \' single quote +@item \" +double quote @item \@var{nnn} the eight-bit character whose value is the octal value @var{nnn} (one to three digits) @@ -777,7 +780,7 @@ in @var{consequent-commands}, or zero if none was executed. The syntax of the @code{for} command is: @example -for @var{name} [in @var{words} @dots{}]; do @var{commands}; done +for @var{name} [ [in [@var{words} @dots{}] ] ; ] do @var{commands}; done @end example Expand @var{words}, and execute @var{commands} once for each member in the resultant list, with @var{name} bound to the current member. @@ -864,7 +867,7 @@ operator terminates a pattern list. A list of patterns and an associated command-list is known as a @var{clause}. -Each clause must be terminated with @samp{;;}, @samp{,&}, or @samp{;;&}. +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 attempted. Each @var{pattern} undergoes tilde expansion, parameter @@ -976,6 +979,9 @@ substitution, and quote removal are performed. Conditional operators such as @samp{-f} must be unquoted to be recognized as primaries. +When used with @samp{[[}, The @samp{<} and @samp{>} operators sort +lexicographically using the current locale. + When the @samp{==} and @samp{!=} operators are used, the string to the right of the operator is considered a pattern and matched according to the rules described below in @ref{Pattern Matching}. @@ -1177,14 +1183,18 @@ positional parameters is updated to reflect the change. Special parameter @code{0} is unchanged. The first element of the @env{FUNCNAME} variable is set to the name of the function while the function is executing. + All other aspects of the shell execution environment are identical between a function and its caller -with the exception that the @env{DEBUG} and @env{RETURN} traps +with these exceptions: +the @env{DEBUG} and @env{RETURN} traps are not inherited unless the function has been given the @code{trace} attribute using the @code{declare} builtin or the @code{-o functrace} option has been enabled with the @code{set} builtin, -(in which case all functions inherit the @env{DEBUG} and @env{RETURN} traps). +(in which case all functions inherit the @env{DEBUG} and @env{RETURN} traps), +and the @env{ERR} trap is not inherited unless the @code{-o errtrace} +shell option has been enabled. @xref{Bourne Shell Builtins}, for the description of the @code{trap} builtin. @@ -1461,7 +1471,7 @@ bash$ echo a@{d,c,b@}e ade ace abe @end example -A sequence expression takes the form @code{@{@var{x}..@var{y}[@var{incr}]@}}, +A sequence expression takes the form @code{@{@var{x}..@var{y}[..@var{incr}]@}}, where @var{x} and @var{y} are either integers or single characters, and @var{incr}, an optional increment, is an integer. When integers are supplied, the expression expands to each number between @@ -1601,7 +1611,7 @@ or when @var{parameter} is followed by a character that is not to be interpreted as part of its name. -If the first character of @var{parameter} is an exclamation point, +If the first character of @var{parameter} is an exclamation point (!), a level of variable indirection is introduced. Bash uses the value of the variable formed from the rest of @var{parameter} as the name of the variable; this variable is then @@ -1767,7 +1777,7 @@ array in turn, and the expansion is the resultant list. @itemx $@{@var{parameter},,@var{pattern}@} This expansion modifies the case of alphabetic characters in @var{parameter}. The @var{pattern} is expanded to produce a pattern just as in -pathname expansion. +filename expansion. The @samp{^} operator converts lowercase letters matching @var{pattern} to uppercase; the @samp{,} operator converts matching uppercase letters to lowercase. @@ -1941,7 +1951,7 @@ an error message is printed and the command is not executed. If the shell option @code{nocaseglob} is enabled, the match is performed without regard to the case of alphabetic characters. -When a pattern is used for filename generation, the character @samp{.} +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 file name, the slash character must always be @@ -2084,6 +2094,14 @@ simple command or may follow a command. Redirections are processed in the order they appear, from left to right. +Each redirection that may be preceded by a file descriptor number +may instead be preceded by a word of the form @{@var{varname}@}. +In this case, for each redirection operator except +>&- and <&-, the shell will allocate a file descriptor greater +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. + In the following descriptions, if the file descriptor number is omitted, and the first character of the redirection operator is @samp{<}, the redirection refers to the standard input (file @@ -2765,8 +2783,14 @@ 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. -For example, the @code{:}, @code{true}, @code{false}, and @code{test} -builtins do not accept options. +The @code{:}, @code{true}, @code{false}, and @code{test} +builtins do not accept options and do not treat @samp{--} specially. +The @code{exit}, @code{logout}, @code{break}, @code{continue}, @code{let}, +and @code{shift} builtins accept and process arguments beginning +with @samp{-} without requiring @samp{--}. +Other builtins that accept arguments but are not specified as accepting +options interpret arguments beginning with @samp{-} as invalid options and +require @samp{--} to prevent this interpretation. @node Bourne Shell Builtins @section Bourne Shell Builtins @@ -3159,15 +3183,20 @@ The @option{-l} option causes the shell to print a list of signal names and their corresponding numbers. Each @var{sigspec} is either a signal name or a signal number. Signal names are case insensitive and the @code{SIG} prefix is optional. + If a @var{sigspec} is @code{0} or @code{EXIT}, @var{arg} is executed when the shell exits. If a @var{sigspec} is @code{DEBUG}, the command @var{arg} is executed before every simple command, @code{for} command, @code{case} command, @code{select} command, every arithmetic @code{for} command, and before the first command executes in a shell function. -Refer to the description of the @code{extglob} option to the +Refer to the description of the @code{extdebug} option to the @code{shopt} builtin (@pxref{The Shopt Builtin}) for details of its effect on the @code{DEBUG} trap. +If a @var{sigspec} is @code{RETURN}, the command @var{arg} is executed +each time a shell function or a script executed with the @code{.} or +@code{source} builtins finishes executing. + If a @var{sigspec} is @code{ERR}, the command @var{arg} is executed whenever a simple command has a non-zero exit status, subject to the following conditions. @@ -3178,13 +3207,10 @@ part of a command executed in a @code{&&} or @code{||} list, or if the command's return status is being inverted using @code{!}. These are the same conditions obeyed by the @code{errexit} option. -If a @var{sigspec} is @code{RETURN}, the command @var{arg} is executed -each time a shell function or a script executed with the @code{.} or -@code{source} builtins finishes executing. Signals ignored upon entry to the shell cannot be trapped or reset. Trapped signals that are not being ignored are reset to their original -values in a child process when it is created. +values in a subshell or subshell environment when one is created. The return status is zero unless a @var{sigspec} does not specify a valid signal. @@ -3625,7 +3651,7 @@ parent. mapfile [-n @var{count}] [-O @var{origin}] [-s @var{count}] [-t] [-u @var{fd}] [ -C @var{callback}] [-c @var{quantum}] [@var{array}] @end example -Read lines from the standard input into array variable @var{array}, +Read lines from the standard input into the indexed array variable @var{array}, or from file descriptor @var{fd} if the @option{-u} option is supplied. The variable @code{MAPFILE} is the default @var{array}. @@ -3640,7 +3666,7 @@ The default index is 0. @item -s Discard the first @var{count} lines read. @item -t -Remove a trailing line from each line read. +Remove a trailing newline from each line read. @item -u Read lines from file descriptor @var{fd} instead of the standard input. @item -C @@ -3661,7 +3687,8 @@ If not supplied with an explicit origin, @code{mapfile} will clear @var{array} before assigning to it. @code{mapfile} returns successfully unless an invalid option or option -argument is supplied, or @var{array} is invalid or unassignable. +argument is supplied, @var{array} is invalid or unassignable, or @var{array} +is not an indexed array. @item printf @btindex printf @@ -3696,7 +3723,7 @@ non-zero on failure. @item read @btindex read @example -read [-ers] [-a @var{aname}] [-d @var{delim}] [-i @var{text}] [-n @var{nchars}] [-p @var{prompt}] [-t @var{timeout}] [-u @var{fd}] [@var{name} @dots{}] +read [-ers] [-a @var{aname}] [-d @var{delim}] [-i @var{text}] [-n @var{nchars}] [-N @var{nchars}] [-p @var{prompt}] [-t @var{timeout}] [-u @var{fd}] [@var{name} @dots{}] @end example One line is read from the standard input, or from the file descriptor @var{fd} supplied as an argument to the @option{-u} option, and the first word @@ -3739,7 +3766,16 @@ the editing buffer before editing begins. @item -n @var{nchars} @code{read} returns after reading @var{nchars} characters rather than -waiting for a complete line of input. +waiting for a complete line of input, but honor a delimiter if fewer +than @var{nchars} characters are read before the delimiter. + +@item -N @var{nchars} +@code{read} returns after reading exactly @var{nchars} characters rather +than waiting for a complete line of input, unless EOF is encountered or +@code{read} times out. +Delimiter characters encountered in the input are +not treated specially and do not cause @code{read} to return until +@var{nchars} characters are read. @item -p @var{prompt} Display @var{prompt}, without a trailing newline, before attempting @@ -3779,7 +3815,7 @@ Read input from file descriptor @var{fd}. readarray [-n @var{count}] [-O @var{origin}] [-s @var{count}] [-t] [-u @var{fd}] [ -C @var{callback}] [-c @var{quantum}] [@var{array}] @end example -Read lines from the standard input into array variable @var{array}, +Read lines from the standard input into the indexed array variable @var{array}, or from file descriptor @var{fd} if the @option{-u} option is supplied. @@ -4007,7 +4043,7 @@ separately (@pxref{Command Execution Environment}), and may cause subshells to exit before executing all the commands in the subshell. @item -f -Disable file name generation (globbing). +Disable filename expansion (globbing). @item -h Locate and remember (hash) commands as they are looked up for execution. @@ -4124,8 +4160,8 @@ Same as @code{-x}. Turn on privileged mode. In this mode, the @env{$BASH_ENV} and @env{$ENV} files are not processed, shell functions are not inherited from the environment, -and the @env{SHELLOPTS}, @env{CDPATH} and @env{GLOBIGNORE} variables, -if they appear in the environment, are ignored. +and the @env{SHELLOPTS}, @env{BASHOPTS}, @env{CDPATH} and @env{GLOBIGNORE} +variables, if they appear in the environment, are ignored. If the shell is started with the effective user (group) id not equal to the real user (group) id, and the @code{-p} option is not supplied, these actions are taken and the effective user id is set to the real user id. @@ -4391,7 +4427,7 @@ performed within @code{$@{@var{parameter}@}} expansions enclosed in double quotes. This option is enabled by default. @item failglob -If set, patterns which fail to match filenames during pathname expansion +If set, patterns which fail to match filenames during filename expansion result in an expansion error. @item force_fignore @@ -4638,6 +4674,16 @@ variables for controlling the job control facilities @item BASH The full pathname used to execute the current instance of Bash. +@item BASHOPTS +A colon-separated list of enabled shell options. Each word in +the list is a valid argument for the @option{-s} option to the +@code{shopt} builtin command (@pxref{The Shopt Builtin}). +The options appearing in @env{BASHOPTS} are those reported +as @samp{on} by @samp{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. + @item BASHPID Expands to the process id of the current Bash process. This differs from @code{$$} under certain circumstances, such as subshells @@ -4750,6 +4796,20 @@ The value of @env{MACHTYPE}. @item BASH_VERSION The version number of the current instance of Bash. +@item BASH_XTRACEFD +If set to an integer corresponding to a valid file descriptor, Bash +will write the trace output generated when @samp{set -x} +is enabled to that file descriptor. +This allows tracing output to be separated from diagnostic and error +messages. +The file descriptor is closed when @code{BASH_XTRACEFD} is unset or assigned +a new value. +Unsetting @code{BASH_XTRACEFD} or assigning it the empty string causes the +trace output to be sent to the standard error. +Note that setting @code{BASH_XTRACEFD} to 2 (the standard error file +descriptor) and then unsetting it will result in the standard error +being closed. + @item COLUMNS Used by the @code{select} builtin command to determine the terminal width when printing selection lists. Automatically set upon receipt of a @@ -4962,7 +5022,8 @@ is running; the next time hostname completion is attempted after the value is changed, Bash adds the contents of the new file to the existing list. -If @env{HOSTFILE} is set, but has no value, Bash attempts to read +If @env{HOSTFILE} is set, but has no value, or does not name a readable file, +Bash attempts to read @file{/etc/hosts} to obtain the list of possible hostname completions. When @env{HOSTFILE} is unset, the hostname list is cleared. @@ -5482,8 +5543,9 @@ allow them to be specified. If Bash is started with the effective user (group) id not equal to the real user (group) id, and the @code{-p} option is not supplied, no startup files are read, shell functions are not inherited from the environment, -the @env{SHELLOPTS} variable, if it appears in the environment, is ignored, -and the effective user id is set to the real user id. +the @env{SHELLOPTS}, @env{BASHOPTS}, @env{CDPATH}, and @env{GLOBIGNORE} +variables, if they appear in the environment, are ignored, and the effective +user id is set to the real user id. If the @code{-p} option is supplied at invocation, the startup behavior is the same, but the effective user id is not reset. @@ -5660,6 +5722,9 @@ If the @var{file} argument to one of the primaries is one of @file{/dev/stdin}, @file{/dev/stdout}, or @file{/dev/stderr}, file descriptor 0, 1, or 2, respectively, is checked. +When used with @samp{[[}, The @samp{<} and @samp{>} operators sort +lexicographically using the current locale. + Unless otherwise specified, primaries that operate on files follow symbolic links and operate on the target of the link, rather than the link itself. @@ -5752,19 +5817,18 @@ True if the length of @var{string} is zero. True if the length of @var{string} is non-zero. @item @var{string1} == @var{string2} +@itemx @var{string1} = @var{string2} True if the strings are equal. -@samp{=} may be used in place of @samp{==} for strict @sc{posix} compliance. +@samp{=} should be used with the @code{test} command for @sc{posix} conformance. @item @var{string1} != @var{string2} True if the strings are not equal. @item @var{string1} < @var{string2} -True if @var{string1} sorts before @var{string2} lexicographically -in the current locale. +True if @var{string1} sorts before @var{string2} lexicographically. @item @var{string1} > @var{string2} -True if @var{string1} sorts after @var{string2} lexicographically -in the current locale. +True if @var{string1} sorts after @var{string2} lexicographically. @item @var{arg1} OP @var{arg2} @code{OP} is one of @@ -6032,11 +6096,14 @@ If @var{subscript} is @samp{@@} or Referencing an array variable without a subscript is equivalent to referencing with a subscript of 0. +An array variable is considered set if a subscript has been assigned a +value. The null string is a valid value. + The @code{unset} builtin is used to destroy arrays. @code{unset} @var{name}[@var{subscript}] destroys the array element at index @var{subscript}. Care must be taken to avoid unwanted side effects caused by filename -generation. +expansion. @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. @@ -6512,6 +6579,11 @@ escape characters are converted. The @code{ulimit} builtin uses a block size of 512 bytes for the @option{-c} and @option{-f} options. +@item +The arrival of @code{SIGCHLD} when a trap is set on @code{SIGCHLD} does +not interrupt the @code{wait} builtin and cause it to return immediately. +The trap command is run once for each child that exits. + @end enumerate There is other @sc{posix} behavior that Bash does not implement by @@ -6561,7 +6633,7 @@ refers to the ability to selectively stop (suspend) the execution of processes and continue (resume) their execution at a later point. A user typically employs this facility via an interactive interface supplied jointly -by the system's terminal driver and Bash. +by the operating system kernel's terminal driver and Bash. The shell associates a @var{job} with each pipeline. It keeps a table of currently executing jobs, which may be listed with the @@ -6586,11 +6658,13 @@ process group @sc{id} is equal to the current terminal process group These processes are said to be in the foreground. Background processes are those whose process group @sc{id} differs from the terminal's; such processes are immune to keyboard-generated -signals. Only foreground processes are allowed to read from or -write to the terminal. Background processes which attempt to -read from (write to) the terminal are sent a @code{SIGTTIN} -(@code{SIGTTOU}) signal by the terminal driver, which, unless -caught, suspends the process. +signals. Only foreground processes are allowed to read from or, if +the user so specifies with @code{stty tostop}, write to the terminal. +Background processes which attempt to +read from (write to when @code{stty tostop} is in effect) the +terminal are sent a @code{SIGTTIN} (@code{SIGTTOU}) +signal by the kernel's terminal driver, +which, unless caught, suspends the process. If the operating system on which Bash is running supports job control, Bash contains facilities to use it. Typing the @@ -7225,6 +7299,10 @@ Include support for the @code{((@dots{}))} command Include support for the extended pattern matching features described above under @ref{Pattern Matching}. +@item --enable-extended-glob-default +Set the default value of the @var{extglob} shell option described +above under @ref{The Shopt Builtin} to be enabled. + @item --enable-help-builtin Include the @code{help} builtin, which displays help on shell builtins and variables (@pxref{Bash Builtins}). @@ -7318,7 +7396,7 @@ But first, you should make sure that it really is a bug, and that it appears in the latest version of Bash. The latest version of Bash is always available for FTP from -@uref{ftp://ftp.gnu.org/pub/bash/}. +@uref{ftp://ftp.gnu.org/pub/gnu/bash/}. Once you have determined that a bug actually exists, use the @code{bashbug} command to submit a bug report. |