commit bash-20200323 snapshot

doc/bash.1

@@ -5,12 +5,12 @@
 .\"	Case Western Reserve University
 .\"	chet.ramey@case.edu
 .\"
-.\"	Last Change: Tue Mar 17 18:27:36 EDT 2020
+.\"	Last Change: Tue Mar 24 16:38:43 EDT 2020
 .\"
 .\" bash_builtins, strip all but Built-Ins section
 .if \n(zZ=1 .ig zZ
 .if \n(zY=1 .ig zY
-.TH BASH 1 "2020 March 17" "GNU Bash 5.0"
+.TH BASH 1 "2020 March 24" "GNU Bash 5.0"
 .\"
 .\" There's some problem with having a `@'
 .\" in a tagged paragraph with the BSD man macros.
@@ -396,7 +396,7 @@ files, the
 option has no effect.
 A non-interactive shell invoked with the name
 .B sh
-does not attempt to read any other startup files. 
+does not attempt to read any other startup files.
 When invoked as
 .BR sh ,
 .B bash
@@ -452,7 +452,6 @@ and the effective user id is set to the real user id.
 If the \fB\-p\fP option is supplied at invocation, the startup behavior is
 the same, but the effective user id is not reset.
 .SH DEFINITIONS
-.PP
 The following definitions are used throughout the rest of this
 document.
 .PD 0
@@ -481,7 +480,6 @@ A character that, when unquoted, separates words.  One of the following:
 .if t \fB|  &  ;  (  )  <  >  space  tab  newline\fP
 .if n \fB|  & ; ( ) < > space tab newline\fP
 .RE
-.PP
 .TP
 .B control operator
 A \fItoken\fP that performs a control function.  It is one of the following
@@ -511,7 +509,6 @@ command:
 .if t .RE
 .SH "SHELL GRAMMAR"
 .SS Simple Commands
-.PP
 A \fIsimple command\fP is a sequence of optional variable assignments
 followed by \fBblank\fP-separated words and redirections, and
 terminated by a \fIcontrol operator\fP.  The first word
@@ -522,7 +519,6 @@ The return value of a \fIsimple command\fP is its exit status, or
 128+\fIn\^\fP if the command is terminated by signal
 .IR n .
 .SS Pipelines
-.PP
 A \fIpipeline\fP is a sequence of one or more commands separated by
 one of the control operators
 .B |
@@ -599,7 +595,6 @@ If the \fBlastpipe\fP option is enabled using the \fBshopt\fP builtin
 (see the description of \fBshopt\fP below),
 the last element of a pipeline may be run by the shell process.
 .SS Lists
-.PP
 A \fIlist\fP is a sequence of one or more pipelines separated by one
 of the operators
 .BR ; ,
@@ -657,7 +652,6 @@ An OR list has the form
 .RS
 .PP
 \fIcommand1\fP \fB||\fP \fIcommand2\fP
-.PP
 .RE
 .PP
 .I command2
@@ -668,7 +662,6 @@ The return status of
 AND and OR lists is the exit status of the last command
 executed in the list.
 .SS Compound Commands
-.PP
 A \fIcompound command\fP is one of the following.
 In most cases a \fIlist\fP in a command's description may be separated from
 the rest of the command by one or more newlines, and may be followed by a
@@ -942,7 +935,6 @@ is the exit status
 of the last command executed in \fIlist-2\fP, or zero if
 none was executed.
 .SS Coprocesses
-.PP
 A \fIcoprocess\fP is a shell command preceded by the \fBcoproc\fP reserved
 word.
 A coprocess is executed asynchronously in a subshell, as if the command
@@ -989,7 +981,6 @@ Since the coprocess is created as an asynchronous command,
 the \fBcoproc\fP command always returns success.
 The return status of a coprocess is the exit status of \fIcommand\fP.
 .SS Shell Function Definitions
-.PP
 A shell function is an object that is called like a simple command and
 executes a compound command with a new set of positional parameters.
 Shell functions are declared as follows:
@@ -1323,7 +1314,6 @@ Namerefs can be unset using the \fB\-n\fP option to the \fBunset\fP builtin.
 Otherwise, if \fBunset\fP is executed with the name of a nameref variable
 as an argument, the variable referenced by the nameref variable will be unset.
 .SS Positional Parameters
-.PP
 A
 .I positional parameter
 is a parameter denoted by one or more
@@ -1344,7 +1334,6 @@ digit is expanded, it must be enclosed in braces (see
 .B EXPANSION
 below).
 .SS Special Parameters
-.PP
 The shell treats several parameters specially.  These parameters may
 only be referenced; assignment to them is not allowed.
 .PD 0
@@ -1402,7 +1391,7 @@ Expands to the exit status of the most recently executed foreground
 pipeline.
 .TP
 .B \-
-Expands to the current option flags as specified upon invocation, 
+Expands to the current option flags as specified upon invocation,
 by the
 .B set
 builtin command, or those set by the shell itself
@@ -1442,7 +1431,6 @@ to the filename used to invoke
 as given by argument zero.
 .PD
 .SS Shell Variables
-.PP
 The following variables are set by the shell:
 .PP
 .PD 0
@@ -2161,7 +2149,7 @@ filename completion (see
 .SM
 .B READLINE
 below).
-A filename whose suffix matches one of the entries in 
+A filename whose suffix matches one of the entries in
 .SM
 .B FIGNORE
 is excluded from the list of matched filenames.
@@ -2469,9 +2457,13 @@ had been executed.
 When the shell enters \fIposix mode\fP, it sets this variable if it was
 not already set.
 .TP
+.B PROMPT_COMMANDS
+If this array variable is set,
+the value of each set element is executed as a command
+prior to issuing each primary prompt.
+If this is not set, but
 .B PROMPT_COMMAND
-If set, the value is executed as a command prior to issuing each primary
-prompt.
+is set to a value, its value is used as a command to execute instead.
 .TP
 .B PROMPT_DIRTRIM
 If set to a number greater than zero, the value is used as the number of
@@ -2684,14 +2676,24 @@ builtins.  Each attribute applies to all members of an array.
 .PP
 Arrays are assigned to using compound assignments of the form
 \fIname\fP=\fB(\fPvalue\fI1\fP ... value\fIn\fP\fB)\fP, where each
-\fIvalue\fP is of the form [\fIsubscript\fP]=\fIstring\fP.
+\fIvalue\fP may be of the form [\fIsubscript\fP]=\fIstring\fP.
 Indexed array assignments do not require anything but \fIstring\fP.
 When assigning to indexed arrays, if the optional brackets and subscript
 are 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.
 .PP
-When assigning to an associative array, the subscript is required.
+When assigning to an associative array, the words in a compound assignment
+may be either assignment statements, for which the subscript is required,
+or a list of words that is interpreted as a sequence of alternating keys
+and values:
+\fIname\fP=\fB( \fP\fIkey1 value1 key2 value2\fP ...\fB)\fP.
+These are treated identically to
+\fIname\fP=\fB(\fP [\fIkey1\fP]=\fIvalue1\fP [\fIkey2\fP]=\fIvalue2\fP ...\fB)\fP.
+The first word in the list determines how the remaining words
+are interpreted; all assignments in a list must be of the same type.
+When using key/value pairs, the keys may not be missing or empty;
+a final missing value is treated like the empty string.
 .PP
 This syntax is also accepted by the
 .B declare
@@ -2830,7 +2832,6 @@ as explained above (see
 .SM
 .BR PARAMETERS ).
 .SS Brace Expansion
-.PP
 .I "Brace expansion"
 is a mechanism by which arbitrary strings
 may be generated.  This mechanism is similar to
@@ -2928,7 +2929,6 @@ command (see
 .B SHELL BUILTIN COMMANDS
 below).
 .SS Tilde Expansion
-.PP
 If a word begins with an unquoted tilde character (`\fB~\fP'), all of
 the characters preceding the first unquoted slash (or all characters,
 if there is no unquoted slash) are considered a \fItilde-prefix\fP.
@@ -2991,7 +2991,6 @@ when they appear as arguments to simple commands.
 Bash does not do this, except for the \fIdeclaration\fP commands listed
 above, when in \fIposix mode\fP.
 .SS Parameter Expansion
-.PP
 The `\fB$\fP' character introduces parameter expansion,
 command substitution, or arithmetic expansion.  The parameter name
 or symbol to be expanded may be enclosed in braces, which
@@ -3355,6 +3354,18 @@ or information about \fIparameter\fP itself, depending on the value of
 .RS
 .PD 0
 .TP
+.B U
+The expansion is a string that is the value of \fIparameter\fP with lowercase
+alphabetic characters converted to uppercase.
+.TP
+.B u
+The expansion is a string that is the value of \fIparameter\fP with the first
+character converted to uppercase, if it is alphabetic.
+.TP
+.B L
+The expansion is a string that is the value of \fIparameter\fP with uppercase
+alphabetic characters converted to lowercase.
+.TP
 .B Q
 The expansion is a string that is the value of \fIparameter\fP quoted in a
 format that can be reused as input.
@@ -3372,6 +3383,12 @@ The expansion is a string in the form of
 an assignment statement or \fBdeclare\fP command that, if
 evaluated, will recreate \fIparameter\fP with its attributes and value.
 .TP
+.B K
+Produces a possibly-quoted version of the value of \fIparameter\fP,
+except that it prints the values of
+indexed and associative arrays as a sequence of quoted key-value pairs
+(see \fBArrays\fP above).
+.TP
 .B a
 The expansion is a string consisting of flag values representing
 \fIparameter\fP's attributes.
@@ -3398,7 +3415,6 @@ The result of the expansion is subject to word splitting and pathname
 expansion as described below.
 .RE
 .SS Command Substitution
-.PP
 \fICommand substitution\fP allows the output of a command to replace
 the command name.  There are two forms:
 .RS
@@ -3436,7 +3452,6 @@ escape the inner backquotes with backslashes.
 If the substitution appears within double quotes, word splitting and
 pathname expansion are not performed on the results.
 .SS Arithmetic Expansion
-.PP
 Arithmetic expansion allows the evaluation of an arithmetic expression
 and the substitution of the result.  The format for arithmetic expansion is:
 .RS
@@ -3462,7 +3477,6 @@ is invalid,
 .B bash
 prints a message indicating failure and no substitution occurs.
 .SS Process Substitution
-.PP
 \fIProcess substitution\fP allows a process's input or output to be
 referred to using a filename.
 It takes the form of
@@ -3486,7 +3500,6 @@ simultaneously with parameter and variable expansion,
 command substitution,
 and arithmetic expansion.
 .SS Word Splitting
-.PP
 The shell scans the results of
 parameter expansion,
 command substitution,
@@ -3571,7 +3584,6 @@ null argument removal.
 Note that if no expansion occurs, no splitting
 is performed.
 .SS Pathname Expansion
-.PP
 After word splitting,
 unless the
 .B \-f
@@ -3831,7 +3843,6 @@ contain multiple matches.
 Using separate matches against shorter strings, or using arrays of
 strings instead of a single long string, may be faster.
 .SS Quote Removal
-.PP
 After the preceding expansions, all unquoted occurrences of the
 characters
 .BR \e ,
@@ -3947,7 +3958,6 @@ Redirections using file descriptors greater than 9 should be used with
 care, as they may conflict with file descriptors the shell uses
 internally.
 .SS Redirecting Input
-.PP
 Redirection of input causes the file whose name results from
 the expansion of
 .I word
@@ -3963,7 +3973,6 @@ The general format for redirecting input is:
 [\fIn\fP]\fB<\fP\fIword\fP
 .RE
 .SS Redirecting Output
-.PP
 Redirection of output causes the file whose name results from
 the expansion of
 .I word
@@ -4000,7 +4009,6 @@ option to the
 builtin command is not enabled, the redirection is attempted even
 if the file named by \fIword\fP exists.
 .SS Appending Redirected Output
-.PP
 Redirection of output in this fashion
 causes the file whose name results from
 the expansion of
@@ -4016,9 +4024,7 @@ The general format for appending output is:
 .PP
 [\fIn\fP]\fB>>\fP\fIword\fP
 .RE
-.PP
 .SS Redirecting Standard Output and Standard Error
-.PP
 This construct allows both the
 standard output (file descriptor 1) and
 the standard error output (file descriptor 2)
@@ -4049,7 +4055,6 @@ When using the second form, \fIword\fP may not expand to a number or
 (see \fBDuplicating File Descriptors\fP below) for compatibility
 reasons.
 .SS Appending Standard Output and Standard Error
-.PP
 This construct allows both the
 standard output (file descriptor 1) and
 the standard error output (file descriptor 2)
@@ -4071,7 +4076,6 @@ This is semantically equivalent to
 .PP
 (see \fBDuplicating File Descriptors\fP below).
 .SS Here Documents
-.PP
 This type of redirection instructs the shell to read input from the
 current source until a line containing only
 .I delimiter
@@ -4138,7 +4142,6 @@ The result is supplied as a single string, with a newline appended,
 to the command on its
 standard input (or file descriptor \fIn\fP if \fIn\fP is specified).
 .SS "Duplicating File Descriptors"
-.PP
 The redirection operator
 .RS
 .PP
@@ -4187,7 +4190,6 @@ As a special case, if \fIn\fP is omitted, and \fIword\fP does not
 expand to one or more digits or \fB\-\fP, the standard output and standard
 error are redirected as described previously.
 .SS "Moving File Descriptors"
-.PP
 The redirection operator
 .RS
 .PP
@@ -4209,7 +4211,6 @@ moves the file descriptor \fIdigit\fP to file descriptor
 .IR n ,
 or the standard output (file descriptor 1) if \fIn\fP is not specified.
 .SS "Opening File Descriptors for Reading and Writing"
-.PP
 The redirection operator
 .RS
 .PP
@@ -4433,7 +4434,7 @@ shell option is enabled).
 Functions may be exported so that subshells
 automatically have them defined with the
 .B \-f
-option to the 
+option to the
 .B export
 builtin.
 A function definition may be deleted using the \fB\-f\fP option to
@@ -4726,7 +4727,7 @@ When used with the \fB[[\fP command,
 .I Arg1
 and
 .I Arg2
-are evaluated as arithmetic expressions  (see
+are evaluated as arithmetic expressions (see
 .SM
 .B "ARITHMETIC EVALUATION"
 above).
@@ -4970,7 +4971,6 @@ invokes an external command, the variable
 is set to the full filename of the command and passed to that
 command in its environment.
 .SH "EXIT STATUS"
-.PP
 The exit status of an executed command is the value returned by the
 \fIwaitpid\fP system call or equivalent function.  Exit statuses
 fall between 0 and 255, though, as explained below, the shell may
@@ -5141,7 +5141,7 @@ Background processes which attempt to read from (write to when
 terminal are sent a
 .SM
 .B SIGTTIN (SIGTTOU)
-signal by the kernel's terminal driver, 
+signal by the kernel's terminal driver,
 which, unless caught, suspends the process.
 .PP
 If the operating system on which
@@ -5442,7 +5442,6 @@ options to the
 .B set
 builtin.
 .SS "Readline Notation"
-.PP
 In this section, the Emacs-style notation is used to denote
 keystrokes.  Control keys are denoted by C\-\fIkey\fR, e.g., C\-n
 means Control\-N.  Similarly,
@@ -5478,7 +5477,6 @@ accumulated into one unit, which can be yanked all at once.
 Commands which do not kill text separate the chunks of text
 on the kill ring.
 .SS "Readline Initialization"
-.PP
 Readline is customized by putting commands in an initialization
 file (the \fIinputrc\fP file).
 The name of this file is taken from the value of the
@@ -5532,7 +5530,6 @@ and
 In addition to command names, readline allows keys to be bound
 to a string that is inserted when the key is pressed (a \fImacro\fP).
 .SS "Readline Key Bindings"
-.PP
 The syntax for controlling key bindings in the
 .I inputrc
 file is simple.  All that is required is the name of the
@@ -5683,7 +5680,6 @@ builtin command (see
 .B SHELL BUILTIN COMMANDS
 below).
 .SS "Readline Variables"
-.PP
 Readline has variables that can be used to further customize its
 behavior.  A variable may be set in the
 .I inputrc
@@ -6004,7 +6000,6 @@ by \fIstat\fP(2) is appended to the filename when listing possible
 completions.
 .PD
 .SS "Readline Conditional Constructs"
-.PP
 Readline implements a facility similar in spirit to the conditional
 compilation features of the C preprocessor which allows key
 bindings and variable settings to be performed as the result
@@ -6056,7 +6051,7 @@ The version number supplied on the right side of the operator consists
 of a major version number, an optional decimal point, and an optional
 minor version (e.g., \fB7.1\fP). If the minor version is omitted, it
 is assumed to be \fB0\fP.
-The operator may be separated from the string \fBversion\fP   
+The operator may be separated from the string \fBversion\fP
 and from the version number argument by whitespace.
 .IP \fBapplication\fP
 The \fBapplication\fP construct is used to include
@@ -6102,7 +6097,6 @@ would read \fI/etc/inputrc\fP:
 .fi
 .RE
 .SS Searching
-.PP
 Readline provides commands for searching through the command history
 (see
 .SM
@@ -6145,7 +6139,6 @@ 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.
 .SS "Readline Command Names"
-.PP
 The following is a list of the names of the commands and the default
 key sequences to which they are bound.
 Command names without an accompanying key sequence are unbound by default.
@@ -6154,7 +6147,6 @@ position, and \fImark\fP refers to a cursor position saved by the
 \fBset\-mark\fP command.
 The text between the point and mark is referred to as the \fIregion\fP.
 .SS Commands for Moving
-.PP
 .PD 0
 .TP
 .B beginning\-of\-line (C\-a)
@@ -6188,7 +6180,7 @@ Words are delimited by non-quoted shell metacharacters.
 .B previous\-screen\-line
 Attempt to move point to the same physical screen column on the previous
 physical screen line. This will not have the desired effect if the current
-Readline line does not take up more than one physical line or if point is not  
+Readline line does not take up more than one physical line or if point is not
 greater than the length of the prompt plus the screen width.
 .TP
 .B next\-screen\-line
@@ -6198,8 +6190,15 @@ Readline line does not take up more than one physical line or if the length
 of the current Readline line is not greater than the length of the prompt
 plus the screen width.
 .TP
+.B clear\-display (M\-C\-l)
+Clear the screen and, if possible, the terminal's scrollback buffer,
+then redraw the current line,
+leaving the current line at the top of the screen.
+.TP
 .B clear\-screen (C\-l)
-Clear the screen leaving the current line at the top of the screen.
+Clear the screen,
+then redraw the current line,
+leaving the current line at the top of the screen.
 With an argument, refresh the current line without clearing the
 screen.
 .TP
@@ -6207,7 +6206,6 @@ screen.
 Refresh the current line.
 .PD
 .SS Commands for Manipulating the History
-.PP
 .PD 0
 .TP
 .B accept\-line (Newline, Return)
@@ -6260,7 +6258,7 @@ between the start of the current line and the point.
 This is a non-incremental search.
 .TP
 .B history\-substring\-search\-backward
-Search backward through the history for the string of characters   
+Search backward through the history for the string of characters
 between the start of the current line and the current cursor
 position (the \fIpoint\fP).
 The search string may match anywhere in a history line.
@@ -6349,7 +6347,6 @@ commands.
 and \fIemacs\fP as the editor, in that order.
 .PD
 .SS Commands for Changing Text
-.PP
 .PD 0
 .TP
 .B \fIend\-of\-file\fP (usually C\-d)
@@ -6424,7 +6421,6 @@ Characters bound to \fBbackward\-delete\-char\fP replace the character
 before point with a space.  By default, this command is unbound.
 .PD
 .SS Killing and Yanking
-.PP
 .PD 0
 .TP
 .B kill\-line (C\-k)
@@ -6495,7 +6491,6 @@ or
 .BR yank\-pop .
 .PD
 .SS Numeric Arguments
-.PP
 .PD 0
 .TP
 .B digit\-argument (M\-0, M\-1, ..., M\-\-)
@@ -6517,7 +6512,6 @@ first time makes the argument count four, a second time makes the
 argument count sixteen, and so on.
 .PD
 .SS Completing
-.PP
 .PD 0
 .TP
 .B complete (TAB)
@@ -6622,7 +6616,6 @@ enclosed within braces so the list is available to the shell (see
 above).
 .PD
 .SS Keyboard Macros
-.PP
 .PD 0
 .TP
 .B start\-kbd\-macro (C\-x (\^)
@@ -6641,7 +6634,6 @@ Print the last keyboard macro defined in a format suitable for the
 \fIinputrc\fP file.
 .PD
 .SS Miscellaneous
-.PP
 .PD 0
 .TP
 .B re\-read\-init\-file (C\-x C\-r)
@@ -6655,8 +6647,8 @@ ring the terminal's bell (subject to the setting of
 .TP
 .B do\-lowercase\-version (M\-A, M\-B, M\-\fIx\fP, ...)
 If the metafied character \fIx\fP is uppercase, run the command
-that is bound to the corresponding metafied lowercase character. 
-The behavior is undefined if \fIx\fP is already lowercase. 
+that is bound to the corresponding metafied lowercase character.
+The behavior is undefined if \fIx\fP is already lowercase.
 .TP
 .B prefix\-meta (ESC)
 Metafy the next character typed.
@@ -6759,7 +6751,6 @@ Display version information about the current instance of
 .BR bash .
 .PD
 .SS Programmable Completion
-.PP
 When word completion is attempted for an argument to a command for
 which a completion specification (a \fIcompspec\fP) has been defined
 using the \fBcomplete\fP builtin (see
@@ -7077,7 +7068,6 @@ builtin below under
 .B "SHELL BUILTIN COMMANDS"
 for information on setting and unsetting shell options.
 .SH "HISTORY EXPANSION"
-.PP
 The shell supports a history expansion feature that
 is similar to the history expansion in
 .BR csh .
@@ -7171,7 +7161,6 @@ The shell uses
 the history comment character to mark history timestamps when
 writing the history file.
 .SS Event Designators
-.PP
 An event designator is a reference to a command line entry in the
 history list.
 Unless the reference is absolute, events are relative to the current
@@ -7225,7 +7214,6 @@ Equivalent to
 The entire command line typed so far.
 .PD
 .SS Word Designators
-.PP
 Word designators are used to select desired words from the event.
 A
 .B :
@@ -7282,13 +7270,11 @@ If \fBx\fP is missing, it defaults to 0.
 If a word designator is supplied without an event specification, the
 previous command is used as the event.
 .SS Modifiers
-.PP
 After the optional word designator, there may appear a sequence of
 one or more of the following modifiers, each preceded by a `:'.
 These modify, or edit, the word or words selected from the history event.
 .PP
 .PD 0
-.PP
 .TP
 .B h
 Remove a trailing filename component, leaving only the head.
@@ -10630,7 +10616,7 @@ option suppresses shell function lookup, as with the \fBcommand\fP builtin.
 returns true if all of the arguments are found, false if
 any are not found.
 .TP
-\fBulimit\fP [\fB\-HSabcdefiklmnpqrstuvxPT\fP [\fIlimit\fP]]
+\fBulimit\fP [\fB\-HSabcdefiklmnpqrstuvxPRT\fP [\fIlimit\fP]]
 Provides control over the resources available to the shell and to
 processes started by it, on systems that allow such control.
 The \fB\-H\fP and \fB\-S\fP options specify that the hard or soft limit is
@@ -10720,6 +10706,9 @@ The maximum number of file locks
 .B \-P
 The maximum number of pseudoterminals
 .TP
+.B \-R
+The maximum time a real-time process can run before blocking, in microseconds
+.TP
 .B \-T
 The maximum number of threads
 .PD
@@ -10735,6 +10724,8 @@ If no option is given, then
 is assumed.  Values are in 1024-byte increments, except for
 .BR \-t ,
 which is in seconds;
+.BR \-R ,
+which is in microseconds;
 .BR \-p ,
 which is in units of 512-byte blocks;
 .BR \-P ,
@@ -11068,7 +11059,6 @@ Comments and bug reports concerning
 this manual page should be directed to
 .IR chet.ramey@case.edu .
 .SH BUGS
-.PP
 It's too big and too slow.
 .PP
 There are some subtle differences between