commit bash-20040107 snapshot

doc/bashref.info

@@ -2,9 +2,9 @@ This is bashref.info, produced by makeinfo version 4.5 from
 /usr/homes/chet/src/bash/src/doc/bashref.texi.
 
 This text is a brief description of the features that are present in
-the Bash shell (version 3.0-alpha, 5 August 2003).
+the Bash shell (version 3.0-alpha, 13 November 2003).
 
-   This is Edition 3.0, last updated 5 August 2003, of `The GNU Bash
+   This is Edition 3.0, last updated 13 November 2003, of `The GNU Bash
 Reference Manual', for `Bash', Version 3.0-alpha.
 
    Copyright (C) 1988-2003 Free Software Foundation, Inc.
@@ -37,9 +37,9 @@ Bash Features
 *************
 
    This text is a brief description of the features that are present in
-the Bash shell (version 3.0-alpha, 5 August 2003)..
+the Bash shell (version 3.0-alpha, 13 November 2003)..
 
-   This is Edition 3.0, last updated 5 August 2003, of `The GNU Bash
+   This is Edition 3.0, last updated 13 November 2003, of `The GNU Bash
 Reference Manual', for `Bash', Version 3.0-alpha.
 
    Bash contains features that appear in other popular shells, and some
@@ -602,9 +602,14 @@ shell waits for all commands in the pipeline to complete.
 
    Each command in a pipeline is executed in its own subshell (*note
 Command Execution Environment::).  The exit status of a pipeline is the
-exit status of the last command in the pipeline.  If the reserved word
-`!' precedes the pipeline, the exit status is the logical negation of
-the exit status of the last command.
+exit status of the last command in the pipeline, unless the `pipefail'
+option is enabled (*note The Set Builtin::).  If `pipefail' is enabled,
+the pipeline's return status is the value of the last (rightmost)
+command to exit with a non-zero status, or zero if all commands exit
+successfully.  If the reserved word `!' precedes the pipeline, the exit
+status is the logical negation of the exit status as described above.
+The shell waits for all commands in the pipeline to terminate before
+returning a value.
 
 
 File: bashref.info,  Node: Lists,  Next: Compound Commands,  Prev: Pipelines,  Up: Shell Commands
@@ -855,6 +860,22 @@ Conditional Constructs
      respectively, and 1 otherwise.  Any part of the pattern may be
      quoted to force it to be matched as a string.
 
+     An additional binary operator, `=~', is available, with the same
+     precedence as `==' and `!='.  When it is used, the string to the
+     right of the operator is considered an extended regular expression
+     and matched accordingly (as in regex3)).  The return value is 0 if
+     the string matches the pattern, and 1 otherwise.  If the regular
+     expression is syntactically incorrect, the conditional
+     expression's return value is 2.  If the shell option `nocaseglob'
+     (see the description of `shopt' in *Note Bash Builtins::) is
+     enabled, the match is performed without regard to the case of
+     alphabetic characters.  Substrings matched by parenthesized
+     subexpressions within the regular expression are saved in the
+     array variable `BASH_REMATCH'.  The element of `BASH_REMATCH' with
+     index 0 is the portion of the string matching the entire regular
+     expression.  The element of `BASH_REMATCH' with index N is the
+     portion of the string matching the Nth parenthesized subexpression.
+
      Expressions may be combined using the following operators, listed
      in decreasing order of precedence:
 
@@ -1025,8 +1046,8 @@ evaluated as an arithmetic expression even if the `$((...))' expansion
 is not used (*note Arithmetic Expansion::).  Word splitting is not
 performed, with the exception of `"$@"' as explained below.  Filename
 expansion is not performed.  Assignment statements may also appear as
-arguments to the `declare', `typeset', `export', `readonly', and
-`local' builtin commands.
+arguments to the `alias', `declare', `typeset', `export', `readonly',
+and `local' builtin commands.
 
 
 File: bashref.info,  Node: Positional Parameters,  Next: Special Parameters,  Up: Shell Parameters
@@ -1556,8 +1577,10 @@ a PATTERN, and replaced with an alphabetically sorted list of file
 names matching the pattern. If no matching file names 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 shell option `nocaseglob' is enabled, the match is
-performed without regard to the case of alphabetic characters.
+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 generation, the character `.' at
 the start of a filename or immediately following a slash must be
@@ -1566,7 +1589,8 @@ matching a file name, the slash character must always be matched
 explicitly.  In other cases, the `.' character is not treated specially.
 
    See the description of `shopt' in *Note Bash Builtins::, for a
-description of the `nocaseglob', `nullglob', and `dotglob' options.
+description of the `nocaseglob', `nullglob', `failglob', and `dotglob'
+options.
 
    The `GLOBIGNORE' shell variable may be used to restrict the set of
 filenames matching a pattern.  If `GLOBIGNORE' is set, each matching
@@ -2141,12 +2165,12 @@ executing loops.  In all cases, Bash ignores `SIGQUIT'.  If job control
 is in effect (*note Job Control::), Bash ignores `SIGTTIN', `SIGTTOU',
 and `SIGTSTP'.
 
-   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' as well.
-Commands run as a result of command substitution ignore the
-keyboard-generated job control signals `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
@@ -2160,13 +2184,13 @@ receive `SIGHUP' using `disown -h'.
 Bash Builtins::), Bash sends a `SIGHUP' to all jobs when an interactive
 login shell exits.
 
-   When Bash receives a signal for which a trap has been set while
-waiting for a command to complete, 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.
+   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.
 
 
 File: bashref.info,  Node: Shell Scripts,  Prev: Executing Commands,  Up: Basic Shell Features
@@ -2560,14 +2584,16 @@ standard.
      function.  Refer to the description of the `extglob' option to the
      `shopt' builtin (*note Bash Builtins::) for details of its effect
      on the `DEBUG' trap.  If a SIGSPEC is `ERR', the command ARG is
-     executed whenever a simple command has a non-zero exit status.
-     The `ERR' trap is not executed if the failed command is part of the
-     command list immediately following an `until' or `while' keyword,
-     part of the test in an `if' statement, part of a `&&' or `||'
-     list, or if the command's return status is being inverted using
-     `!'.  If a SIGSPEC is `RETURN', the command ARG is executed each
-     time a shell function or a script executed with the `.' or
-     `source' builtins finishes executing.
+     executed whenever a simple command has a non-zero exit status,
+     subject to the following conditions.  The `ERR' trap is not
+     executed if the failed command is part of the command list
+     immediately following an `until' or `while' keyword, part of the
+     test in an `if' statement, part of a `&&' or `||' list, or if the
+     command's return status is being inverted using `!'.  These are
+     the same conditions obeyed by the `errexit' option.  If a SIGSPEC
+     is `RETURN', the command ARG is executed each time a shell
+     function or a script executed with the `.' or `source' builtins
+     finishes executing.
 
      Signals ignored upon entry to the shell cannot be trapped or reset.
      Trapped signals are reset to their original values in a child
@@ -2704,7 +2730,7 @@ POSIX 1003.2 standard.
 `caller'
           caller [EXPR]
      Returns the context of any active subroutine call (a shell
-     function or a script executed with the `.' or `source' builtins.
+     function or a script executed with the `.' or `source' builtins).
 
      Without EXPR, `caller' displays the line number and source
      filename of the current subroutine call.  If a non-negative
@@ -2913,9 +2939,11 @@ POSIX 1003.2 standard.
      specifications, each of which causes printing of the next
      successive ARGUMENT.  In addition to the standard `printf(1)'
      formats, `%b' causes `printf' to expand backslash escape sequences
-     in the corresponding ARGUMENT, and `%q' causes `printf' to output
-     the corresponding ARGUMENT in a format that can be reused as shell
-     input.
+     in the corresponding ARGUMENT, (except that `\c' terminates
+     output, backslashes in `\'', `\"', and `\?' are not removed, and
+     octal escapes beginning with `\0' may contain up to four digits),
+     and `%q' causes `printf' to output the corresponding ARGUMENT in a
+     format that can be reused as shell input.
 
      The FORMAT is reused as necessary to consume all of the ARGUMENTS.
      If the FORMAT requires more ARGUMENTS than are supplied, the extra
@@ -3089,6 +3117,10 @@ POSIX 1003.2 standard.
           within `${PARAMETER}' expansions enclosed in double quotes.
           This option is enabled by default.
 
+    `failglob'
+          If set, patterns which fail to match filenames during
+          pathname expansion result in an expansion error.
+
     `force_fignore'
           If set, the suffixes specified by the `FIGNORE' shell variable
           cause words to be ignored when performing word completion
@@ -3427,6 +3459,12 @@ The Set Builtin
          `physical'
                Same as `-P'.
 
+         `pipefail'
+               If set, the return value of a pipeline is the value of
+               the last (rightmost) command to exit with a non-zero
+               status, or zero if all commands in the pipeline exit
+               successfully.  This option is disabled by default.
+
          `posix'
                Change the behavior of Bash where the default operation
                differs from the POSIX 1003.2 standard to match the
@@ -3699,6 +3737,14 @@ Variables::).
      name is `${BASH_SOURCE[$i + 1]}'.  Use `LINENO' to obtain the
      current line number.
 
+`BASH_REMATCH'
+     An array variable whose members are assigned by the `=~' binary
+     operator to the `[[' conditional command (*note 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'
      An array variable whose members are the source filenames
      corresponding to the elements in the `FUNCNAME' array variable.
@@ -7865,7 +7911,12 @@ does not provide the necessary support.
      builtins and functions to be timed.
 
 `--enable-cond-command'
-     Include support for the `[[' conditional command (*note
+     Include support for the `[[' conditional command.  (*note
+     Conditional Constructs::).
+
+`--enable-cond-regexp'
+     Include support for matching POSIX regular expressions using the
+     `=~' binary operator in the `[[' conditional command.  (*note
      Conditional Constructs::).
 
 `--enable-directory-stack'
@@ -8016,7 +8067,9 @@ included in SVR4.2 as the baseline reference.
      and `compgen', to manipulate it.
 
    * Bash has command history (*note Bash History Facilities::) and the
-     `history' and `fc' builtins to manipulate it.
+     `history' and `fc' builtins to manipulate it.  The Bash history
+     list maintains timestamp information and uses the value of the
+     `HISTTIMEFORMAT' variable to display it.
 
    * Bash implements `csh'-like history expansion (*note History
      Interaction::).
@@ -8212,10 +8265,19 @@ included in SVR4.2 as the baseline reference.
    * Bash has much more optional behavior controllable with the `set'
      builtin (*note The Set Builtin::).
 
+   * The `-x' (`xtrace') option displays commands other than simple
+     commands when performing an execution trace (*note The Set
+     Builtin::).
+
    * The `test' builtin (*note Bourne Shell Builtins::) is slightly
      different, as it implements the POSIX algorithm, which specifies
      the behavior based on the number of arguments.
 
+   * Bash includes the `caller' builtin, which displays the context of
+     any active subroutine call (a shell function or a script executed
+     with the `.' or `source' builtins).  This supports the bash
+     debugger.
+
    * The `trap' builtin (*note Bourne Shell Builtins::) allows a
      `DEBUG' pseudo-signal specification, similar to `EXIT'.  Commands
      specified with a `DEBUG' trap are executed before every simple
@@ -8881,6 +8943,7 @@ Parameter and Variable Index
 * BASH_ENV:                              Bash Variables.
 * BASH_EXECUTION_STRING:                 Bash Variables.
 * BASH_LINENO:                           Bash Variables.
+* BASH_REMATCH:                          Bash Variables.
 * BASH_SOURCE:                           Bash Variables.
 * BASH_SUBSHELL:                         Bash Variables.
 * BASH_VERSINFO:                         Bash Variables.
@@ -9186,129 +9249,129 @@ Concept Index
 
 
 Tag Table:
-Node: Top1367
-Node: Introduction3520
-Node: What is Bash?3745
-Node: What is a shell?4833
-Node: Definitions7369
-Node: Basic Shell Features10109
-Node: Shell Syntax11327
-Node: Shell Operation12351
-Node: Quoting13636
-Node: Escape Character14898
-Node: Single Quotes15370
-Node: Double Quotes15705
-Node: ANSI-C Quoting16718
-Node: Locale Translation17661
-Node: Comments18544
-Node: Shell Commands19149
-Node: Simple Commands19910
-Node: Pipelines20531
-Node: Lists22067
-Node: Compound Commands23689
-Node: Looping Constructs24461
-Node: Conditional Constructs26895
-Node: Command Grouping32914
-Node: Shell Functions34350
-Node: Shell Parameters38615
-Node: Positional Parameters40177
-Node: Special Parameters41068
-Node: Shell Expansions43726
-Node: Brace Expansion45646
-Node: Tilde Expansion47962
-Node: Shell Parameter Expansion50294
-Node: Command Substitution57548
-Node: Arithmetic Expansion58870
-Node: Process Substitution59711
-Node: Word Splitting60748
-Node: Filename Expansion62200
-Node: Pattern Matching64185
-Node: Quote Removal67506
-Node: Redirections67792
-Node: Executing Commands75267
-Node: Simple Command Expansion75934
-Node: Command Search and Execution77855
-Node: Command Execution Environment79852
-Node: Environment82614
-Node: Exit Status84265
-Node: Signals85460
-Node: Shell Scripts87371
-Node: Shell Builtin Commands89882
-Node: Bourne Shell Builtins91312
-Node: Bash Builtins108084
-Node: The Set Builtin135896
-Node: Special Builtins143821
-Node: Shell Variables144793
-Node: Bourne Shell Variables145229
-Node: Bash Variables147206
-Node: Bash Features166301
-Node: Invoking Bash167183
-Node: Bash Startup Files172994
-Node: Interactive Shells177864
-Node: What is an Interactive Shell?178266
-Node: Is this Shell Interactive?178901
-Node: Interactive Shell Behavior179707
-Node: Bash Conditional Expressions182974
-Node: Shell Arithmetic186394
-Node: Aliases189134
-Node: Arrays191637
-Node: The Directory Stack194657
-Node: Directory Stack Builtins195363
-Node: Printing a Prompt198242
-Node: The Restricted Shell200868
-Node: Bash POSIX Mode202693
-Node: Job Control209339
-Node: Job Control Basics209805
-Node: Job Control Builtins214085
-Node: Job Control Variables218381
-Node: Command Line Editing219531
-Node: Introduction and Notation220529
-Node: Readline Interaction222146
-Node: Readline Bare Essentials223332
-Node: Readline Movement Commands225112
-Node: Readline Killing Commands226068
-Node: Readline Arguments227977
-Node: Searching229012
-Node: Readline Init File231189
-Node: Readline Init File Syntax232243
-Node: Conditional Init Constructs243887
-Node: Sample Init File246411
-Node: Bindable Readline Commands249594
-Node: Commands For Moving250793
-Node: Commands For History251642
-Node: Commands For Text254531
-Node: Commands For Killing257192
-Node: Numeric Arguments259142
-Node: Commands For Completion260269
-Node: Keyboard Macros263850
-Node: Miscellaneous Commands264409
-Node: Readline vi Mode269708
-Node: Programmable Completion270617
-Node: Programmable Completion Builtins276424
-Node: Using History Interactively283786
-Node: Bash History Facilities284465
-Node: Bash History Builtins287155
-Node: History Interaction291007
-Node: Event Designators293558
-Node: Word Designators294562
-Node: Modifiers296192
-Node: Installing Bash297589
-Node: Basic Installation298723
-Node: Compilers and Options301408
-Node: Compiling For Multiple Architectures302142
-Node: Installation Names303799
-Node: Specifying the System Type304610
-Node: Sharing Defaults305319
-Node: Operation Controls305984
-Node: Optional Features306935
-Node: Reporting Bugs315012
-Node: Major Differences From The Bourne Shell316187
-Node: Copying This Manual331430
-Node: GNU Free Documentation License331684
-Node: Builtin Index354077
-Node: Reserved Word Index357704
-Node: Variable Index359180
-Node: Function Index366116
-Node: Concept Index370666
+Node: Top1373
+Node: Introduction3532
+Node: What is Bash?3757
+Node: What is a shell?4845
+Node: Definitions7381
+Node: Basic Shell Features10121
+Node: Shell Syntax11339
+Node: Shell Operation12363
+Node: Quoting13648
+Node: Escape Character14910
+Node: Single Quotes15382
+Node: Double Quotes15717
+Node: ANSI-C Quoting16730
+Node: Locale Translation17673
+Node: Comments18556
+Node: Shell Commands19161
+Node: Simple Commands19922
+Node: Pipelines20543
+Node: Lists22409
+Node: Compound Commands24031
+Node: Looping Constructs24803
+Node: Conditional Constructs27237
+Node: Command Grouping34290
+Node: Shell Functions35726
+Node: Shell Parameters39991
+Node: Positional Parameters41562
+Node: Special Parameters42453
+Node: Shell Expansions45111
+Node: Brace Expansion47031
+Node: Tilde Expansion49347
+Node: Shell Parameter Expansion51679
+Node: Command Substitution58933
+Node: Arithmetic Expansion60255
+Node: Process Substitution61096
+Node: Word Splitting62133
+Node: Filename Expansion63585
+Node: Pattern Matching65709
+Node: Quote Removal69030
+Node: Redirections69316
+Node: Executing Commands76791
+Node: Simple Command Expansion77458
+Node: Command Search and Execution79379
+Node: Command Execution Environment81376
+Node: Environment84138
+Node: Exit Status85789
+Node: Signals86984
+Node: Shell Scripts88939
+Node: Shell Builtin Commands91450
+Node: Bourne Shell Builtins92880
+Node: Bash Builtins109763
+Node: The Set Builtin137885
+Node: Special Builtins146103
+Node: Shell Variables147075
+Node: Bourne Shell Variables147511
+Node: Bash Variables149488
+Node: Bash Features168993
+Node: Invoking Bash169875
+Node: Bash Startup Files175686
+Node: Interactive Shells180556
+Node: What is an Interactive Shell?180958
+Node: Is this Shell Interactive?181593
+Node: Interactive Shell Behavior182399
+Node: Bash Conditional Expressions185666
+Node: Shell Arithmetic189086
+Node: Aliases191826
+Node: Arrays194329
+Node: The Directory Stack197349
+Node: Directory Stack Builtins198055
+Node: Printing a Prompt200934
+Node: The Restricted Shell203560
+Node: Bash POSIX Mode205385
+Node: Job Control212031
+Node: Job Control Basics212497
+Node: Job Control Builtins216777
+Node: Job Control Variables221073
+Node: Command Line Editing222223
+Node: Introduction and Notation223221
+Node: Readline Interaction224838
+Node: Readline Bare Essentials226024
+Node: Readline Movement Commands227804
+Node: Readline Killing Commands228760
+Node: Readline Arguments230669
+Node: Searching231704
+Node: Readline Init File233881
+Node: Readline Init File Syntax234935
+Node: Conditional Init Constructs246579
+Node: Sample Init File249103
+Node: Bindable Readline Commands252286
+Node: Commands For Moving253485
+Node: Commands For History254334
+Node: Commands For Text257223
+Node: Commands For Killing259884
+Node: Numeric Arguments261834
+Node: Commands For Completion262961
+Node: Keyboard Macros266542
+Node: Miscellaneous Commands267101
+Node: Readline vi Mode272400
+Node: Programmable Completion273309
+Node: Programmable Completion Builtins279116
+Node: Using History Interactively286478
+Node: Bash History Facilities287157
+Node: Bash History Builtins289847
+Node: History Interaction293699
+Node: Event Designators296250
+Node: Word Designators297254
+Node: Modifiers298884
+Node: Installing Bash300281
+Node: Basic Installation301415
+Node: Compilers and Options304100
+Node: Compiling For Multiple Architectures304834
+Node: Installation Names306491
+Node: Specifying the System Type307302
+Node: Sharing Defaults308011
+Node: Operation Controls308676
+Node: Optional Features309627
+Node: Reporting Bugs317899
+Node: Major Differences From The Bourne Shell319074
+Node: Copying This Manual334822
+Node: GNU Free Documentation License335076
+Node: Builtin Index357469
+Node: Reserved Word Index361096
+Node: Variable Index362572
+Node: Function Index369565
+Node: Concept Index374115
 
 End Tag Table