Imported from ../bash-3.2.tar.gz.

doc/bash.1

@@ -1,4 +1,4 @@
-\"
+.\"
 .\" MAN PAGE COMMENTS to
 .\"
 .\"	Chet Ramey
@@ -6,12 +6,12 @@
 .\"	Case Western Reserve University
 .\"	chet@po.cwru.edu
 .\"
-.\"	Last Change: Sat Aug 27 13:28:44 EDT 2005
+.\"	Last Change: Thu Sep 28 10:25:59 EDT 2006
 .\"
 .\" bash_builtins, strip all but Built-Ins section
 .if \n(zZ=1 .ig zZ
 .if \n(zY=1 .ig zY
-.TH BASH 1 "2005 Aug 27" "GNU Bash-3.1-beta1"
+.TH BASH 1 "2006 September 28" "GNU Bash-3.2"
 .\"
 .\" There's some problem with having a `@'
 .\" in a tagged paragraph with the BSD man macros.
@@ -62,8 +62,9 @@ also incorporates useful features from the \fIKorn\fP and \fIC\fP
 shells (\fBksh\fP and \fBcsh\fP).
 .PP
 .B Bash
-is intended to be a conformant implementation of the IEEE
-POSIX Shell and Tools specification (IEEE Working Group 1003\.2).
+is intended to be a conformant implementation of the
+Shell and Utilities portion of the IEEE POSIX specification
+(IEEE Standard 1003.1).
 .B Bash
 can be configured to be POSIX-conformant by default.
 .SH OPTIONS
@@ -223,7 +224,7 @@ This option is on by default if the shell is invoked as
 .TP
 .B \-\-posix
 Change the behavior of \fBbash\fP where the default operation differs
-from the POSIX 1003.2 standard to match the standard (\fIposix mode\fP).
+from the POSIX standard to match the standard (\fIposix mode\fP).
 .TP
 .B \-\-restricted
 The shell becomes restricted (see
@@ -677,8 +678,8 @@ If the shell option
 .B nocasematch
 is enabled, the match is performed without regard to the case
 of alphabetic characters.
-The return value is 0 if the string matches or does not match
-the pattern, respectively, and 1 otherwise.
+The return value is 0 if the string matches (\fB==\fP) or does not match
+(\fB!=\fP) the pattern, and 1 otherwise.
 Any part of the pattern may be quoted to force it to be matched as a
 string.
 .if t .sp 0.5
@@ -807,6 +808,12 @@ it against each \fIpattern\fP in turn, using the same matching rules
 as for pathname expansion (see
 .B Pathname Expansion
 below).
+The \fIword\fP is expanded using tilde
+expansion, parameter and variable expansion, arithmetic substitution,
+command substitution, process substitution and quote removal.
+Each \fIpattern\fP examined is expanded using tilde
+expansion, parameter and variable expansion, arithmetic substitution,
+command substitution, and process substitution.
 If the shell option
 .B nocasematch
 is enabled, the match is performed without regard to the case
@@ -971,7 +978,7 @@ quotes (see
 .B PARAMETERS
 below).
 .PP
-Words of the form \fB$\fP'\fIstring\fP' are treated specially.  The
+Words of the form \fB$\fP\(aq\fIstring\fP\(aq are treated specially.  The
 word expands to \fIstring\fP, with backslash-escaped characters replaced
 as specified by the ANSI C standard.  Backslash escape sequences, if
 present, are decoded as follows:
@@ -1005,7 +1012,7 @@ vertical tab
 .B \e\e
 backslash
 .TP
-.B \e'
+.B \e\(aq
 single quote
 .TP   
 .B \e\fInnn\fP
@@ -1368,6 +1375,8 @@ subsequently reset.
 .B COMP_WORDS
 An array variable (see \fBArrays\fP below) consisting of the individual
 words in the current command line.
+The words are split on shell metacharacters as the shell parser would
+separate them.
 This variable is available only in shell functions invoked by the
 programmable completion facilities (see \fBProgrammable Completion\fP
 below).
@@ -1686,7 +1695,8 @@ command history is not saved when an interactive shell exits.
 .B HISTFILESIZE
 The maximum number of lines contained in the history file.  When this
 variable is assigned a value, the history file is truncated, if
-necessary, to contain no more than that number of lines.  The default
+necessary, by removing the oldest entries,
+to contain no more than that number of lines.  The default
 value is 500.  The history file is also truncated to this size after
 writing it when an interactive shell exits.
 .TP
@@ -1839,7 +1849,7 @@ the current mailfile.
 Example:
 .RS
 .PP
-\fBMAILPATH\fP='/var/mail/bfox?"You have mail":~/shell\-mail?"$_ has mail!"'
+\fBMAILPATH\fP=\(aq/var/mail/bfox?"You have mail":~/shell\-mail?"$_ has mail!"\(aq
 .PP
 .B Bash
 supplies a default value for this variable, but the location of the user
@@ -1973,7 +1983,7 @@ The value of \fIp\fP determines whether or not the fraction is
 included.
 .IP
 If this variable is not set, \fBbash\fP acts as if it had the
-value \fB$'\enreal\et%3lR\enuser\et%3lU\ensys\t%3lS'\fP.
+value \fB$\(aq\enreal\et%3lR\enuser\et%3lU\ensys\t%3lS\(aq\fP.
 If the value is null, no timing information is displayed.
 A trailing newline is added when the format string is displayed.
 .TP
@@ -2525,17 +2535,12 @@ the pattern removal operation is applied to each member of the
 array in turn, and the expansion is the resultant list.
 .TP
 ${\fIparameter\fP\fB/\fP\fIpattern\fP\fB/\fP\fIstring\fP}
-.PD 0
-.TP
-${\fIparameter\fP\fB//\fP\fIpattern\fP\fB/\fP\fIstring\fP}
-.PD
 The \fIpattern\fP is expanded to produce a pattern just as in
 pathname expansion.
 \fIParameter\fP is expanded and the longest match of \fIpattern\fP
 against its value is replaced with \fIstring\fP.
-In the first form, only the first match is replaced.
-The second form causes all matches of \fIpattern\fP to be
-replaced with \fIstring\fP.
+If \Ipattern\fP begins with \fB/\fP, all matches of \fIpattern\fP are
+replaced with \fIstring\fP.  Normally only the first match is replaced.
 If \fIpattern\fP begins with \fB#\fP, it must match at the beginning
 of the expanded value of \fIparameter\fP.
 If \fIpattern\fP begins with \fB%\fP, it must match at the end
@@ -2702,7 +2707,7 @@ If the value of
 .B IFS
 is null, no word splitting occurs.
 .PP
-Explicit null arguments (\^\f3"\^"\fP or \^\f3'\^'\fP\^) are retained.
+Explicit null arguments (\^\f3"\^"\fP or \^\f3\(aq\^\(aq\fP\^) are retained.
 Unquoted implicit null arguments, resulting from the expansion of
 parameters that have no values, are removed.
 If a parameter with no value is expanded within double quotes, a
@@ -2861,7 +2866,7 @@ and
 .BR ] ,
 \fIcharacter classes\fP can be specified using the syntax
 \fB[:\fP\fIclass\fP\fB:]\fP, where \fIclass\fP is one of the
-following classes defined in the POSIX.2 standard:
+following classes defined in the POSIX standard:
 .PP
 .RS
 .B
@@ -2924,7 +2929,7 @@ Matches anything except one of the given patterns
 After the preceding expansions, all unquoted occurrences of the
 characters
 .BR \e ,
-.BR ' ,
+.BR \(aq ,
 and \^\f3"\fP\^ that did not result from one of the above
 expansions are removed.
 .SH REDIRECTION
@@ -3417,6 +3422,10 @@ automatically have them defined with the
 option to the 
 .B export
 builtin.
+A function definition may be deleted using the \fB\-f\fP option to
+the
+.B unset
+builtin.
 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.
@@ -4489,8 +4498,8 @@ backslash
 .B \e"
 literal "
 .TP
-.B \e'
-literal '
+.B \e\(aq
+literal \(aq
 .RE
 .PD
 .PP
@@ -4538,7 +4547,7 @@ be used to indicate a macro definition.
 Unquoted text is assumed to be a function name.
 In the macro body, the backslash escapes described above are expanded.
 Backslash will quote any other character in the macro text,
-including " and '.
+including " and \(aq.
 .PP
 .B Bash
 allows the current readline key bindings to be displayed or modified
@@ -6635,10 +6644,6 @@ backslash
 the eight-bit character whose value is the octal value \fInnn\fP
 (zero to three octal digits)
 .TP
-.B \e\fInnn\fP
-the eight-bit character whose value is the octal value \fInnn\fP
-(one to three octal digits)
-.TP
 .B \ex\fIHH\fP
 the eight-bit character whose value is the hexadecimal value \fIHH\fP
 (one or two hex digits)
@@ -7314,7 +7319,7 @@ format specifications, each of which causes printing of the next successive
 In addition to the standard \fIprintf\fP(1) formats, \fB%b\fP causes
 \fBprintf\fP to expand backslash escape sequences in the corresponding
 \fIargument\fP (except that \fB\ec\fP terminates output, backslashes in
-\fB\e'\fP, \fB\e"\fP, and \fB\e?\fP are not removed, and octal escapes
+\fB\e\(aq\fP, \fB\e"\fP, and \fB\e?\fP are not removed, and octal escapes
 beginning with \fB\e0\fP may contain up to four digits),
 and \fB%q\fP causes \fBprintf\fP to output the corresponding
 \fIargument\fP in a format that can be reused as shell input.
@@ -7712,7 +7717,7 @@ This option is disabled by default.
 Change the behavior of
 .B bash
 where the default operation differs
-from the POSIX 1003.2 standard to match the standard (\fIposix mode\fP).
+from the POSIX standard to match the standard (\fIposix mode\fP).
 .TP 8
 .B privileged
 Same as
@@ -8031,7 +8036,7 @@ If set, the extended pattern matching features described above under
 \fBPathname Expansion\fP are enabled.
 .TP 8
 .B extquote
-If set, \fB$\fP'\fIstring\fP' and \fB$\fP"\fIstring\fP" quoting is
+If set, \fB$\fP\(aq\fIstring\fP\(aq and \fB$\fP"\fIstring\fP" quoting is
 performed within \fB${\fP\fIparameter\fP\fB}\fP expansions
 enclosed in double quotes.  This option is enabled by default.
 .TP 8
@@ -8400,8 +8405,8 @@ the command
 is executed each time a shell function or a script executed with the
 \fB.\fP or \fBsource\fP 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
-process when it is created.
+Trapped signals that are not being ignored are reset to their original
+values in a child process when it is created.
 The return status is false if any
 .I sigspec
 is invalid; otherwise
@@ -8484,7 +8489,7 @@ option suppresses shell function lookup, as with the \fBcommand\fP builtin.
 returns true if any of the arguments are found, false if
 none are found.
 .TP
-\fBulimit\fP [\fB\-SHacdflmnpstuv\fP [\fIlimit\fP]]
+\fBulimit\fP [\fB\-SHacdefilmnpqrstuvx\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
@@ -8520,8 +8525,14 @@ The maximum size of core files created
 .B \-d
 The maximum size of a process's data segment
 .TP
+.B \-e
+The maximum scheduling priority ("nice")
+.TP
 .B \-f
-The maximum size of files created by the shell
+The maximum size of files written by the shell and its children
+.TP
+.B \-i
+The maximum number of pending signals
 .TP
 .B \-l
 The maximum size that may be locked into memory
@@ -8536,6 +8547,12 @@ allow this value to be set)
 .B \-p
 The pipe size in 512-byte blocks (this may not be set)
 .TP
+.B \-q
+The maximum number of bytes in POSIX message queues
+.TP
+.B \-r
+The maximum real-time scheduling priority
+.TP
 .B \-s
 The maximum stack size
 .TP
@@ -8547,6 +8564,9 @@ The maximum number of processes available to a single user
 .TP
 .B \-v
 The maximum amount of virtual memory available to the shell
+.TP
+.B \-x
+The maximum number of file locks
 .PD
 .PP
 If