dmbcs/i-bash
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

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

Browse source
This commit is contained in:
Jari Aalto 2005-12-07 14:08:12 +00:00
commit 95732b497d
267 changed files with 24541 additions and 18843 deletions
Download patch file Download diff file Expand all files Collapse all files

103
doc/FAQ
View file

@ -1,4 +1,4 @@
This is the Bash FAQ, version 3.27, for Bash version 3.0.
This is the Bash FAQ, version 3.32, for Bash version 3.1.
This document contains a set of frequently-asked questions concerning
Bash, the GNU Bourne-Again Shell. Bash is a freely-available command
@ -36,9 +36,9 @@ A10) What is the bash `posix mode'?
Section B: The latest version
B1) What's new in version 3.0?
B2) Are there any user-visible incompatibilities between bash-3.0 and
bash-1.14.7?
B1) What's new in version 3.1?
B2) Are there any user-visible incompatibilities between bash-3.1 and
bash-2.05b?
Section C: Differences from other Unix shells
@ -140,22 +140,26 @@ of Case Western Reserve University.
A2) What's the latest version?
The latest version is 3.0, first made available on 27 July, 2004.
The latest version is 3.1, first made available on 09 December, 2005.
A3) Where can I get it?
Bash is the GNU project's shell, and so is available from the
master GNU archive site, ftp.gnu.org, and its mirrors. The
latest version is also available for FTP from ftp.cwru.edu.
The following URLs tell how to get version 3.0:
The following URLs tell how to get version 3.1:
ftp://ftp.gnu.org/pub/gnu/bash/bash-3.0.tar.gz
ftp://ftp.cwru.edu/pub/bash/bash-3.0.tar.gz
ftp://ftp.gnu.org/pub/gnu/bash/bash-3.1.tar.gz
ftp://ftp.cwru.edu/pub/bash/bash-3.1.tar.gz
Formatted versions of the documentation are available with the URLs:
ftp://ftp.gnu.org/pub/gnu/bash/bash-doc-3.0.tar.gz
ftp://ftp.cwru.edu/pub/bash/bash-doc-3.0.tar.gz
ftp://ftp.gnu.org/pub/gnu/bash/bash-doc-3.1.tar.gz
ftp://ftp.cwru.edu/pub/bash/bash-doc-3.1.tar.gz
Any patches for the current version are available with the URL:
ftp://ftp.cwru.edu/pub/bash/bash-3.1-patches/
A4) On what machines will bash run?
@ -181,16 +185,15 @@ earlier Minix versions yet.
Bash has been ported to versions of Windows implementing the Win32
programming interface. This includes Windows 95 and Windows NT.
The port was done by Cygnus Solutions as part of their CYGWIN
project. For more information about the project, look at the URLs
http://www.cygwin.com/
http://sourceware.cygnus.com/cygwin
The port was done by Cygnus Solutions (now part of Red Hat) as part
of their CYGWIN project. For more information about the project, see
http://www.cygwin.com/.
Cygnus originally ported bash-1.14.7, and that port was part of their
early GNU-Win32 (the original name) releases. Cygnus has also done a
port of bash-2.05 to the CYGWIN environment, and it is available as
part of their current release.
early GNU-Win32 (the original name) releases. Cygnus has also done
ports of bash-2.05b and bash-3.0 to the CYGWIN environment, and both
are available as part of their current release. Bash-3.1 is currently
being tested and should be available soon.
Bash-2.05b and later versions should require no local Cygnus changes to
build and run under CYGWIN.
@ -212,7 +215,8 @@ ftp://ftp.simtel.net/pub/simtelnet/gnu/djgpp/v2gnu/bsh204s.zip source
Mark began to work with bash-2.05, but I don't know the current status.
Bash-3.0 compiles and runs with no modifications under Microsoft's Services
for Unix (SFU), once known as Interix.
for Unix (SFU), once known as Interix. I do not anticipate any problems
with building bash-3.1.
A6) How can I build bash with gcc?
@ -381,15 +385,25 @@ They are also listed in a section in the Bash Reference Manual
Section B: The latest version
B1) What's new in version 3.0?
B1) What's new in version 3.1?
Bash-3.0 is the third major release of bash. The features introduced
in the intermediate releases following bash-2.05 have been completed.
Support for the bash debugger (a separate project) has been integrated.
Bash-3.1 is the first maintenance release of the third major release of
bash. It contains the following significant new features (see the manual
page for complete descriptions and the CHANGES and NEWS files in the
bash-3.1 distribution).
Bash-3.0 contains the following new features (see the manual page for
complete descriptions and the CHANGES and NEWS files in the bash-3.0
distribution):
o Bash-3.1 may now be configured and built in a mode that enforces strict
POSIX compliance.
o The `+=' assignment operator, which appends to the value of a string or
array variable, has been implemented.
o It is now possible to ignore case when matching in contexts other than
filename generation using the new `nocasematch' shell option.
A short feature history dating from Bash-2.0:
Bash-3.0 contained the following new features:
o Features to support the bash debugger have been implemented, and there
is a new `extdebug' option to turn the non-default options on
@ -419,8 +433,6 @@ o The `jobs', `kill', and `wait' builtins now accept job control notation
o The `gettext' package and libintl have been integrated, and the shell
messages may be translated into other languages
A short feature history dating from Bash-2.0:
Bash-2.05b introduced the following new features:
o support for multibyte characters has been added to both bash and readline
@ -628,10 +640,10 @@ grammar tighter and smaller (66 reduce-reduce conflicts gone)
lots of code now smaller and faster
test suite greatly expanded
B2) Are there any user-visible incompatibilities between bash-3.0 and
bash-1.14.7?
B2) Are there any user-visible incompatibilities between bash-3.1 and
bash-2.05b?
There are a few incompatibilities between version 1.14.7 and version 3.0.
There are a few incompatibilities between version 2.05b and version 3.1.
They are detailed in the file COMPAT in the bash distribution. That file
is not meant to be all-encompassing; send mail to bash-maintainers@gnu.org
if if you find something that's not mentioned there.
@ -714,11 +726,12 @@ Things bash has that sh does not:
case-insensitive pattern matching and globbing
variable assignments preceding commands affect only that command,
even for builtins and functions
posix mode
posix mode and strict posix conformance
redirection to /dev/fd/N, /dev/stdin, /dev/stdout, /dev/stderr,
/dev/tcp/host/port, /dev/udp/host/port
debugger support, including `caller' builtin and new variables
RETURN trap
the `+=' assignment operator
Things sh has that bash does not:
@ -796,6 +809,7 @@ Things bash has or uses that ksh88 does not:
RETURN trap
Timestamps in history entries
{x..y} brace expansion
The `+=' assignment operator
Things ksh88 has or uses that bash does not:
tracked aliases (alias -t)
@ -842,7 +856,6 @@ New things in ksh-93 not in bash-3.0:
`fc' has been renamed to `hist'
`.' can execute shell functions
exit statuses between 0 and 255
`+=' variable assignment operator
FPATH and PATH mixing
getopts -a
-I invocation option
@ -876,6 +889,7 @@ New things in ksh-93 present in bash-3.0:
command name completion
ENV processed only for interactive shells
set -o pipefail
The `+=' assignment operator
Section D: Why does bash do some things differently than other Unix shells?
@ -1099,9 +1113,8 @@ will try to write on a pipe without a reader. In that case, bash
will print `Broken pipe' to stderr when ps is killed by a
SIGPIPE.
You can build a version of bash that will not report SIGPIPE errors
by uncommenting the definition of DONT_REPORT_SIGPIPE in the file
config-top.h.
As of bash-3.1, bash will not report SIGPIPE errors by default. You
can build a version of bash that will report such errors.
E3) When I have terminal escape sequences in my prompt, why does bash
wrap lines at the wrong column?
@ -1128,12 +1141,12 @@ simple calls to `read'. For example, piping a command's output
into a `while' loop that repeatedly calls `read' will result in
the same behavior.
Each element of a pipeline runs in a separate process, a child of
the shell running the pipeline. A subprocess cannot affect its
parent's environment. When the `read' command sets the variable
to the input, that variable is set only in the subshell, not the
parent shell. When the subshell exits, the value of the variable
is lost.
Each element of a pipeline, even a builtin or shell function,
runs in a separate process, a child of the shell running the
pipeline. A subprocess cannot affect its parent's environment.
When the `read' command sets the variable to the input, that
variable is set only in the subshell, not the parent shell. When
the subshell exits, the value of the variable is lost.
Many pipelines that end with `read variable' can be converted
into command substitutions, which will capture the output of
@ -1763,21 +1776,19 @@ These are features that may or may not appear in a future version of bash.
breaking some of the shell functionality into embeddable libraries
a module system like zsh's, using dynamic loading like builtins
date-stamped command history
a bash programmer's guide with a chapter on creating loadable builtins
a better loadable interface to perl with access to the shell builtins and
variables (contributions gratefully accepted)
ksh93-like `nameref' variables
ksh93-like `+=' variable assignment operator
ksh93-like `xx.yy' variables (including some of the .sh.* variables) and
associated disipline functions
Some of the new ksh93 pattern matching operators, like backreferencing
H5) When will the next release appear?
The next version will appear sometime in 2005. Never make predictions.
The next version will appear sometime in 2006. Never make predictions.
This document is Copyright 1995-2004 by Chester Ramey.
This document is Copyright 1995-2005 by Chester Ramey.
Permission is hereby granted, without written agreement and
without license or royalty fees, to use, copy, and distribute

1418
doc/article.ps Normal file
View file

File diff suppressed because it is too large Load diff

261
doc/bash.1
View file

@ -1,17 +1,17 @@
.\"
\"
.\" MAN PAGE COMMENTS to
.\"
.\" Chet Ramey
.\" Information Network Services
.\" Case Western Reserve University
.\" chet@po.CWRU.Edu
.\" chet@po.cwru.edu
.\"
.\" Last Change: Sat Jun 26 14:26:44 EDT 2004
.\" Last Change: Sat Aug 27 13:28:44 EDT 2005
.\"
.\" bash_builtins, strip all but Built-Ins section
.if \n(zZ=1 .ig zZ
.if \n(zY=1 .ig zY
.TH BASH 1 "2004 June 26" "GNU Bash-3.0"
.TH BASH 1 "2005 Aug 27" "GNU Bash-3.1-beta1"
.\"
.\" There's some problem with having a `@'
.\" in a tagged paragraph with the BSD man macros.
@ -51,8 +51,8 @@ bash \- GNU Bourne-Again SHell
[options]
[file]
.SH COPYRIGHT
.if n Bash is Copyright (C) 1989-2004 by the Free Software Foundation, Inc.
.if t Bash is Copyright \(co 1989-2004 by the Free Software Foundation, Inc.
.if n Bash is Copyright (C) 1989-2005 by the Free Software Foundation, Inc.
.if t Bash is Copyright \(co 1989-2005 by the Free Software Foundation, Inc.
.SH DESCRIPTION
.B Bash
is an \fBsh\fR-compatible command language interpreter that
@ -64,6 +64,8 @@ shells (\fBksh\fP and \fBcsh\fP).
.B Bash
is intended to be a conformant implementation of the IEEE
POSIX Shell and Tools specification (IEEE Working Group 1003\.2).
.B Bash
can be configured to be POSIX-conformant by default.
.SH OPTIONS
In addition to the single-character shell options documented in the
description of the \fBset\fR builtin command, \fBbash\fR
@ -115,7 +117,7 @@ when invoking an interactive shell.
.TP
.B \-D
A list of all double-quoted strings preceded by \fB$\fP
is printed on the standard ouput.
is printed on the standard output.
These are the strings that
are subject to language translation when the current locale
is not \fBC\fP or \fBPOSIX\fP.
@ -154,11 +156,13 @@ single-character options to be recognized.
.TP
.B \-\-debugger
Arrange for the debugger profile to be executed before the shell
starts. Turns on extended debugging mode (see the description of the
starts.
Turns on extended debugging mode (see the description of the
.B extdebug
option to the
.B shopt
builtin below) and shell function tracing (see the description of the
builtin below)
and shell function tracing (see the description of the
\fB\-o functrace\fP option to the
.B set
builtin below).
@ -669,6 +673,10 @@ as primaries.
When the \fB==\fP and \fB!=\fP operators are used, the string to the
right of the operator is considered a pattern and matched according
to the rules described below under \fBPattern Matching\fP.
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.
Any part of the pattern may be quoted to force it to be matched as a
@ -684,7 +692,7 @@ the pattern, and 1 otherwise.
If the regular expression is syntactically incorrect, the conditional
expression's return value is 2.
If the shell option
.B nocaseglob
.B nocasematch
is enabled, the match is performed without regard to the case
of alphabetic characters.
Substrings matched by parenthesized subexpressions within the regular
@ -798,7 +806,12 @@ A \fBcase\fP command first expands \fIword\fP, and tries to match
it against each \fIpattern\fP in turn, using the same matching rules
as for pathname expansion (see
.B Pathname Expansion
below). When a match is found, the
below).
If the shell option
.B nocasematch
is enabled, the match is performed without regard to the case
of alphabetic characters.
When a match is found, the
corresponding \fIlist\fP is executed. After the first match, no
subsequent matches are attempted. The exit status is zero if no
pattern matches. Otherwise, it is the exit status of the
@ -895,7 +908,11 @@ Each of the \fImetacharacters\fP listed above under
has special meaning to the shell and must be quoted if it is to
represent itself.
.PP
When the command history expansion facilities are being used, the
When the command history expansion facilities are being used
(see
.SM
.B HISTORY EXPANSION
below), the
\fIhistory expansion\fP character, usually \fB!\fP, must be quoted
to prevent history expansion.
.PP
@ -919,8 +936,9 @@ Enclosing characters in double quotes preserves the literal value
of all characters within the quotes, with the exception of
.BR $ ,
.BR ` ,
and
.BR \e .
.BR \e ,
and, when history expansion is enabled,
.BR ! .
The characters
.B $
and
@ -936,8 +954,12 @@ or
.BR <newline> .
A double quote may be quoted within double quotes by preceding it with
a backslash.
When command history is being used, the double quote may not be used to
quote the history expansion character.
If enabled, history expansion will be performed unless an
.B !
appearing in double quotes is escaped using a backslash.
The backslash preceding the
.B !
is not removed.
.PP
The special parameters
.B *
@ -951,7 +973,7 @@ below).
.PP
Words of the form \fB$\fP'\fIstring\fP' are treated specially. The
word expands to \fIstring\fP, with backslash-escaped characters replaced
as specifed by the ANSI C standard. Backslash escape sequences, if
as specified by the ANSI C standard. Backslash escape sequences, if
present, are decoded as follows:
.RS
.PD 0
@ -1076,6 +1098,20 @@ Assignment statements may also appear as arguments to the
and
.B local
builtin commands.
.PP
In the context where an assignment statement is assigning a value
to a shell variable or array index, the += operator can be used to
append to or add to the variable's previous value.
When += is applied to a variable for which the integer attribute has been
set, \fIvalue\fP is evaluated as an arithmetic expression and added to the
variable's current value, which is also evaluated.
When += is applied to an array variable using compound assignment (see
.B Arrays
below), the
variable's value is not unset (as it is when using =), and new values are
appended to the array beginning at one greater than the array's maximum index.
When applied to a string-valued variable, \fIvalue\fP is expanded and
appended to the variable's value.
.SS Positional Parameters
.PP
A
@ -1130,6 +1166,10 @@ Expands to the positional parameters, starting from one. When the
expansion occurs within double quotes, each parameter expands to a
separate word. That is, "\fB$@\fP" is equivalent to
"\fB$1\fP" "\fB$2\fP" ...
If the double-quoted expansion occurs within a word, the expansion of
the first parameter is joined with the beginning part of the original
word, and the expansion of the last parameter is joined with the last
part of the original word.
When there are no positional parameters, "\fB$@\fP" and
.B $@
expand to nothing (i.e., they are removed).
@ -1178,12 +1218,13 @@ to the file name used to invoke
as given by argument zero.
.TP
.B _
At shell startup, set to the absolute file name of the shell or shell
script being executed as passed in the argument list.
At shell startup, set to the absolute pathname used to invoke the
shell or shell script being executed as passed in the environment
or argument list.
Subsequently, expands to the last argument to the previous command,
after expansion.
Also set to the full file name of each command executed and placed in
the environment exported to that command.
Also set to the full pathname used to invoke each command executed
and placed in the environment exported to that command.
When checking mail, this parameter holds the name of the mail file
currently being checked.
.PD
@ -1199,11 +1240,18 @@ Expands to the full file name used to invoke this instance of
.TP
.B BASH_ARGC
An array variable whose values are the number of parameters in each
frame of the current bash execution call stack. The number of
frame of the current bash execution call stack.
The number of
parameters to the current subroutine (shell function or script executed
with \fB.\fP or \fBsource\fP) is at the top of the stack. When a
subroutine is executed, the number of parameters passed is pushed onto
with \fB.\fP or \fBsource\fP) is at the top of the stack.
When a subroutine is executed, the number of parameters passed is pushed onto
\fBBASH_ARGC\fP.
The shell sets \fBBASH_ARGC\fP only when in extended debugging mode
(see the description of the
.B extdebug
option to the
.B shopt
builtin below)
.TP
.B BASH_ARGV
An array variable containing all of the parameters in the current bash
@ -1211,6 +1259,12 @@ execution call stack. The final parameter of the last subroutine call
is at the top of the stack; the first parameter of the initial call is
at the bottom. When a subroutine is executed, the parameters supplied
are pushed onto \fBBASH_ARGV\fP.
The shell sets \fBBASH_ARGV\fP only when in extended debugging mode
(see the description of the
.B extdebug
option to the
.B shopt
builtin below)
.TP
.B BASH_COMMAND
The command currently being executed or about to be executed, unless the
@ -1222,10 +1276,10 @@ The command argument to the \fB\-c\fP invocation option.
.TP
.B BASH_LINENO
An array variable whose members are the line numbers in source files
corresponding to each member of @var{FUNCNAME}.
corresponding to each member of \fBFUNCNAME\fP.
\fB${BASH_LINENO[\fP\fI$i\fP\fB]}\fP is the line number in the source
file where \fB${FUNCNAME[\fP\fI$i + 1\fP\fB]}\fP was called.
The corresponding source file name is \fB${BASH_SOURCE[\fP\fI$i + 1\fP\fB]}\fB.
file where \fB${FUNCNAME[\fP\fI$ifP\fB]}\fP was called.
The corresponding source file name is \fB${BASH_SOURCE[\fP\fI$i\fP\fB]}\fB.
Use \fBLINENO\fP to obtain the current line number.
.TP
.B BASH_REMATCH
@ -1934,6 +1988,10 @@ number of seconds to wait for input after issuing the primary prompt.
terminates after waiting for that number of seconds if input does
not arrive.
.TP
.B TMPDIR
If set, \fBBash\fP uses its value as the name of a directory in which
\fBBash\fP creates temporary files for the shell's use.
.TP
.B auto_resume
This variable controls how the shell interacts with the user and
job control. If this variable is set, single word simple
@ -1959,9 +2017,7 @@ job identifier (see
.B JOB CONTROL
below). If set to any other value, the supplied string must
be a prefix of a stopped job's name; this provides functionality
analogous to the
.B %
job identifier.
analogous to the \fB%\fP\fIstring\fP job identifier.
.TP
.B histchars
The two or three characters which control history expansion
@ -2035,7 +2091,12 @@ character of the
.B IFS
special variable, and ${\fIname\fP[@]} expands each element of
\fIname\fP to a separate word. When there are no array members,
${\fIname\fP[@]} expands to nothing. This is analogous to the expansion
${\fIname\fP[@]} expands to nothing.
If the double-quoted expansion occurs within a word, the expansion of
the first parameter is joined with the beginning part of the original
word, and the expansion of the last parameter is joined with the last
part of the original word.
This is analogous to the expansion
of the special parameters \fB*\fP and \fB@\fP (see
.B Special Parameters
above). ${#\fIname\fP[\fIsubscript\fP]} expands to the length of
@ -2048,6 +2109,8 @@ The
.B unset
builtin is used to destroy arrays. \fBunset\fP \fIname\fP[\fIsubscript\fP]
destroys the array element at index \fIsubscript\fP.
Care must be taken to avoid unwanted side effects caused by filename
generation.
\fBunset\fP \fIname\fP, where \fIname\fP is an array, or
\fBunset\fP \fIname\fP[\fIsubscript\fP], where
\fIsubscript\fP is \fB*\fP or \fB@\fP, removes the entire array.
@ -2229,7 +2292,7 @@ is unchanged.
Each variable assignment is checked for unquoted tilde-prefixes immediately
following a
.B :
or
or the first
.BR = .
In these cases, tilde expansion is also performed.
Consequently, one may use file names with tildes in assignments to
@ -2252,7 +2315,7 @@ interpreted as part of the name.
.PP
When braces are used, the matching ending brace is the first `\fB}\fP'
not escaped by a backslash or within a quoted string, and not within an
embedded arithmetic expansion, command substitution, or paramter
embedded arithmetic expansion, command substitution, or parameter
expansion.
.PP
.PD 0
@ -2352,6 +2415,10 @@ parameters beginning at \fIoffset\fP.
If \fIparameter\fP is an array name indexed by @ or *,
the result is the \fIlength\fP
members of the array beginning with ${\fIparameter\fP[\fIoffset\fP]}.
A negative \fIoffset\fP is taken relative to one greater than the maximum
index of the specified array.
Note that a negative offset must be separated from the colon by at least
one space to avoid being confused with the :- expansion.
Substring indexing is zero-based unless the positional parameters
are used, in which case the indexing starts at 1.
.TP
@ -2846,7 +2913,7 @@ Matches zero or more occurrences of the given patterns
Matches one or more occurrences of the given patterns
.TP
\fB@(\fP\^\fIpattern-list\^\fP\fB)\fP
Matches exactly one of the given patterns
Matches one of the given patterns
.TP
\fB!(\fP\^\fIpattern-list\^\fP\fB)\fP
Matches anything except one of the given patterns
@ -2943,6 +3010,10 @@ a UDP connection to the corresponding socket.
.RE
.PP
A failure to open or create a file causes the redirection to fail.
.PP
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
@ -3291,19 +3362,21 @@ environment are identical between a function and its caller
with the exception that the
.SM
.B DEBUG
trap (see the description of the
and
.B RETURN
traps (see the description of the
.B trap
builtin under
.SM
.B SHELL BUILTIN COMMANDS
below) is not inherited unless the function has been given the
below) are not inherited unless the function has been given the
\fBtrace\fP attribute (see the description of the
.SM
.B declare
builtin below) or the
\fB\-o functrace\fP shell option has been enabled with
the \fBset\fP builtin
(in which case all functions inherit the \fBDEBUG\fP trap).
(in which case all functions inherit the \fBDEBUG\fP and \fBRETURN\fP traps).
.PP
Variables local to the function may be declared with the
.B local
@ -3442,7 +3515,7 @@ If \fIbase#\fP is omitted, then base 10 is used.
The digits greater than 9 are represented by the lowercase letters,
the uppercase letters, @, and _, in that order.
If \fIbase\fP is less than or equal to 36, lowercase and uppercase
letters may be used interchangably to represent numbers between 10
letters may be used interchangeably to represent numbers between 10
and 35.
.PP
Operators are evaluated in order of precedence. Sub-expressions in
@ -3458,6 +3531,9 @@ If any \fIfile\fP argument to one of the primaries is of the form
If the \fIfile\fP argument to one of the primaries is one of
\fI/dev/stdin\fP, \fI/dev/stdout\fP, or \fI/dev/stderr\fP, file
descriptor 0, 1, or 2, respectively, is checked.
.PP
Unless otherwise specified, primaries that operate on files follow symbolic
links and operate on the target of the link, rather than the link itself.
.sp 1
.PD 0
.TP
@ -3923,7 +3999,7 @@ sends a
.B SIGHUP
to all jobs when an interactive login shell exits.
.PP
If \Bbash\fP is waiting for a command to complete and receives a signal
If \fBbash\fP 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 \fBbash\fP is waiting for an asynchronous command via the \fBwait\fP
@ -4053,6 +4129,8 @@ command), the current job is always flagged with a
.BR + ,
and the previous job with a
.BR \- .
A single % (with no accompanying job specification) also refers to the
current job.
.PP
Simply naming a job can be used to bring it into the
foreground:
@ -4489,7 +4567,12 @@ file with a statement of the form
Except where noted, readline variables can take the values
.B On
or
.BR Off .
.B Off
(without regard to case).
Unrecognized variable names are ignored.
When a variable value is read, empty or null values, "on" (case-insensitive),
and "1" are equivalent to \fBOn\fP. All other values are equivalent to
\fBOff\fP.
The variables and their default values are:
.PP
.PD 0
@ -4500,6 +4583,11 @@ If set to \fBnone\fP, readline never rings the bell. If set to
\fBvisible\fP, readline uses a visible bell if one is available.
If set to \fBaudible\fP, readline attempts to ring the terminal's bell.
.TP
.B bind\-tty\-special\-chars (On)
If set to \fBOn\fP, readline attempts to bind the control characters
treated specially by the kernel's terminal driver to their readline
equivalents.
.TP
.B comment\-begin (``#'')
The string that is inserted when the readline
.B insert\-comment
@ -4553,9 +4641,9 @@ arrow keys.
If set to \fBon\fP, tilde expansion is performed when readline
attempts word completion.
.TP
.B history-preserve-point
.B history\-preserve\-point (Off)
If set to \fBon\fP, the history code attempts to place point at the
same location on each history line retrived with \fBprevious-history\fP
same location on each history line retrieved with \fBprevious-history\fP
or \fBnext-history\fP.
.TP
.B horizontal\-scroll\-mode (Off)
@ -4855,6 +4943,8 @@ With an argument
insert the \fIn\fPth word from the previous command (the words
in the previous command begin with word 0). A negative argument
inserts the \fIn\fPth word from the end of the previous command.
Once the argument \fIn\fP is computed, the argument is extracted
as if the "!\fIn\fP" history expansion had been specified.
.TP
.B
yank\-last\-arg (M\-.\^, M\-_\^)
@ -4863,6 +4953,8 @@ the previous history entry). With an argument,
behave exactly like \fByank\-nth\-arg\fP.
Successive calls to \fByank\-last\-arg\fP move back through the history
list, inserting the last argument of each line in turn.
The history expansion facilities are used to extract the last argument,
as if the "!$" history expansion had been specified.
.TP
.B shell\-expand\-line (M\-C\-e)
Expand the line as the shell does. This
@ -5275,7 +5367,7 @@ of an \fIinputrc\fP file.
.TP
.B dump\-macros
Print all of the readline key sequences bound to macros and the
strings they ouput. If a numeric argument is supplied,
strings they output. If a numeric argument is supplied,
the output is formatted in such a way that it can be made part
of an \fIinputrc\fP file.
.TP
@ -5339,7 +5431,7 @@ special variable as delimiters.
Shell quoting is honored.
Each word is then expanded using
brace expansion, tilde expansion, parameter and variable expansion,
command substitution, arithmetic expansion, and pathname expansion,
command substitution, and arithmetic expansion,
as described above under
.SM
.BR EXPANSION .
@ -5806,6 +5898,8 @@ section as accepting options preceded by
accepts
.B \-\-
to signify the end of the options.
For example, the \fB:\fP, \fBtrue\fP, \fBfalse\fP, and \fBtest\fP builtins
do not accept options.
.sp .5
.PD 0
.TP
@ -5872,8 +5966,8 @@ is supplied, the name and value of the alias is printed.
\fBAlias\fP returns true unless a \fIname\fP is given for which
no alias has been defined.
.TP
\fBbg\fP [\fIjobspec\fP]
Resume the suspended job \fIjobspec\fP in the background, as if it
\fBbg\fP [\fIjobspec\fP ...]
Resume each suspended job \fIjobspec\fP in the background, as if it
had been started with
.BR & .
If \fIjobspec\fP is not present, the shell's notion of the
@ -5881,8 +5975,8 @@ If \fIjobspec\fP is not present, the shell's notion of the
.B bg
.I jobspec
returns 0 unless run when job control is disabled or, when run with
job control enabled, if \fIjobspec\fP was not found or started without
job control.
job control enabled, any specified \fIjobspec\fP was not found
or was started without job control.
.TP
\fBbind\fP [\fB\-m\fP \fIkeymap\fP] [\fB\-lpsvPSV\fP]
.PD 0
@ -6174,6 +6268,11 @@ suppressing trailing spaces). Intended to be used with shell functions.
.B nospace
Tell readline not to append a space (the default) to words completed at
the end of the line.
.TP 8
.B plusdirs
After any matches defined by the compspec are generated,
directory name completion is attempted and any
matches are added to the results of the other actions.
.RE
.TP 8
\fB\-A\fP \fIaction\fP
@ -6376,7 +6475,8 @@ by subsequent assignment statements or unset.
.TP
.B \-t
Give each \fIname\fP the \fItrace\fP attribute.
Traced functions inherit the \fBDEBUG\fP trap from the calling shell.
Traced functions inherit the \fBDEBUG\fP and \fBRETURN\fP traps from
the calling shell.
The trace attribute has no special meaning for variables.
.TP
.B \-x
@ -6495,9 +6595,7 @@ The \fBxpg_echo\fP shell option may be used to
dynamically determine whether or not \fBecho\fP expands these
escape characters by default.
.B echo
does not interpret
.B \-\-
to mean the end of options.
does not interpret \fB\-\-\fP to mean the end of options.
.B echo
interprets the following escape sequences:
.RS
@ -7205,7 +7303,7 @@ is empty, a non-existent directory stack entry is specified, or the
directory change fails.
.RE
.TP
\fBprintf\fP \fIformat\fP [\fIarguments\fP]
\fBprintf\fP [\fB\-v\fP \fIvar\fP] \fIformat\fP [\fIarguments\fP]
Write the formatted \fIarguments\fP to the standard output under the
control of the \fIformat\fP.
The \fIformat\fP is a character string which contains three types of objects:
@ -7221,6 +7319,9 @@ 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.
.sp 1
The \fB\-v\fP option causes the output to be assigned to the variable
\fIvar\fP rather than being printed to the standard output.
.sp 1
The \fIformat\fP is reused as necessary to consume all of the \fIarguments\fP.
If the \fIformat\fP requires more \fIarguments\fP than are supplied, the
extra format specifications behave as if a zero value or null string, as
@ -7366,7 +7467,7 @@ input is not read within \fItimeout\fP seconds.
This option has no effect if \fBread\fP is not reading input from the
terminal or a pipe.
.TP
.B \-u \fIfd\FP
.B \-u \fIfd\fP
Read input from file descriptor \fIfd\fP.
.PD
.PP
@ -7435,7 +7536,10 @@ before execution resumes after the function or script.
.TP
\fBset\fP [\fB\-\-abefhkmnptuvxBCHP\fP] [\fB\-o\fP \fIoption\fP] [\fIarg\fP ...]
Without options, the name and value of each shell variable are displayed
in a format that can be reused as input.
in a format that can be reused as input
for setting or resetting the currently-set variables.
Read-only variables cannot be reset.
In \fIposix mode\fP, only shell variables are listed.
The output is sorted according to the current locale.
When options are specified, they set or unset shell attributes.
Any arguments remaining after the options are processed are treated
@ -7608,7 +7712,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 (\fI`posix mode\fP).
from the POSIX 1003.2 standard to match the standard (\fIposix mode\fP).
.TP 8
.B privileged
Same as
@ -7722,9 +7826,11 @@ follows the logical chain of directories when performing commands
which change the current directory.
.TP 8
.B \-T
If set, any trap on \fBDEBUG\fP is inherited by shell functions, command
substitutions, and commands executed in a subshell environment.
The \fBDEBUG\fP trap is normally not inherited in such cases.
If set, any traps on \fBDEBUG\fP and \fBRETURN\fP are inherited by shell
functions, command substitutions, and commands executed in a
subshell environment.
The \fBDEBUG\fP and \fBRETURN\fP traps are normally not inherited
in such cases.
.TP 8
.B \-\-
If no arguments follow this option, then the positional parameters are
@ -7904,6 +8010,20 @@ If the command run by the \fBDEBUG\fP trap returns a value of 2, and the
shell is executing in a subroutine (a shell function or a shell script
executed by the \fB.\fP or \fBsource\fP builtins), a call to
\fBreturn\fP is simulated.
.TP
.B 4.
\fBBASH_ARGC\fP and \fBBASH_ARGV\fP are updated as described in their
descriptions above.
.TP
.B 5.
Function tracing is enabled: command substitution, shell functions, and
subshells invoked with \fB(\fP \fIcommand\fP \fB)\fP inherit the
\fBDEBUG\fP and \fBRETURN\fP traps.
.TP
.B 6.
Error tracing is enabled: command substitution, shell functions, and
subshells invoked with \fB(\fP \fIcommand\fP \fB)\fP inherit the
\fBERROR\fP trap.
.RE
.TP 8
.B extglob
@ -8013,6 +8133,12 @@ expansion (see
.B Pathname Expansion
above).
.TP 8
.B nocasematch
If set,
.B bash
matches patterns in a case\-insensitive fashion when performing matching
while executing \fBcase\fP or \fB[[\fP conditional commands.
.TP 8
.B nullglob
If set,
.B bash
@ -8086,6 +8212,8 @@ Each operator and operand must be a separate argument.
Expressions are composed of the primaries described above under
.SM
.BR "CONDITIONAL EXPRESSIONS" .
\fBtest\fP does not accept any options, nor does it accept and ignore
an argument of \fB\-\-\fP as signifying the end of options.
.if t .sp 0.5
.if n .sp 1
Expressions may be combined using the following operators, listed
@ -8232,7 +8360,7 @@ command, and before the first command executes in a shell function (see
.SM
.B SHELL GRAMMAR
above).
Refer to the description of the \fBextglob\fP option to the
Refer to the description of the \fBextdebug\fP option to the
\fBshopt\fP builtin for details of its effect on the \fBDEBUG\fP trap.
If a
.I sigspec
@ -8487,8 +8615,7 @@ refers to a shell variable.
Read-only variables may not be unset.
If
.B \-f
is specifed,
each
is specified, each
.I name
refers to a shell function, and the function definition
is removed.
@ -8515,9 +8642,9 @@ subsequently reset. The exit status is true unless a
.I name
is readonly.
.TP
\fBwait\fP [\fIn\fP]
Wait for the specified process and return its termination
status.
\fBwait\fP [\fIn ...\fP]
Wait for each specified process and return its termination status.
Each
.I n
may be a process
ID or a job specification; if a job spec is given, all processes
@ -8661,7 +8788,7 @@ bfox@gnu.org
.PP
Chet Ramey, Case Western Reserve University
.br
chet@po.CWRU.Edu
chet@po.cwru.edu
.SH BUG REPORTS
If you find a bug in
.B bash,
@ -8702,7 +8829,7 @@ it provides for filing a bug report.
.PP
Comments and bug reports concerning
this manual page should be directed to
.IR chet@po.CWRU.Edu .
.IR chet@po.cwru.edu .
.SH BUGS
.PP
It's too big and too slow.

982
doc/bashref.info
View file

File diff suppressed because it is too large Load diff

362
doc/bashref.texi
View file

@ -16,7 +16,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-2004 Free Software Foundation, Inc.
Copyright @copyright{} 1988-2005 Free Software Foundation, Inc.
Permission is granted to make and distribute verbatim copies of
this manual provided the copyright notice and this permission notice
@ -94,46 +94,28 @@ reference on shell behavior.
@menu
* Introduction:: An introduction to the shell.
* Definitions:: Some definitions used in the rest of this
manual.
* Basic Shell Features:: The shell "building blocks".
* Shell Builtin Commands:: Commands that are a part of the shell.
* Shell Variables:: Variables used or set by Bash.
* Bash Features:: Features found only in Bash.
* Job Control:: A chapter describing what job control is
and how Bash allows you to use it.
* Using History Interactively:: Chapter dealing with history expansion
rules.
* Job Control:: What job control is and how Bash allows you
to use it.
* Using History Interactively:: Command History Expansion
* Command Line Editing:: Chapter describing the command line
editing features.
* Installing Bash:: How to build and install Bash on your system.
* Reporting Bugs:: How to report bugs in Bash.
* Major Differences From The Bourne Shell:: A terse list of the differences
between Bash and historical
versions of /bin/sh.
* Copying This Manual:: Copying this manual.
* Builtin Index:: Index of Bash builtin commands.
* Reserved Word Index:: Index of Bash reserved words.
* Variable Index:: Quick reference helps you find the
variable you want.
* Function Index:: Index of bindable Readline functions.
* Concept Index:: General index for concepts described in
this manual.
@end menu
@ -143,7 +125,6 @@ reference on shell behavior.
@chapter Introduction
@menu
* What is Bash?:: A short description of Bash.
* What is a shell?:: A brief introduction to shells.
@end menu
@ -371,9 +352,7 @@ and to named files, and how the shell executes commands.
@section Shell Syntax
@menu
* Shell Operation:: The basic operation of the shell.
* Quoting:: How to remove the special meaning from characters.
* Comments:: How to specify comments.
@end menu
@ -444,7 +423,6 @@ status (@pxref{Exit Status}).
* Double Quotes:: How to suppress most of the interpretation of a
sequence of characters.
* ANSI-C Quoting:: How to expand ANSI-C sequences in quoted strings.
* Locale Translation:: How to translate strings into different languages.
@end menu
@ -457,7 +435,8 @@ parameter expansion.
Each of the shell metacharacters (@pxref{Definitions})
has special meaning to the shell and must be quoted if it is to
represent itself.
When the command history expansion facilities are being used, the
When the command history expansion facilities are being used
(@pxref{History Interaction}), the
@var{history expansion} character, usually @samp{!}, must be quoted
to prevent history expansion. @xref{Bash History Facilities}, for
more details concerning history expansion.
@ -486,7 +465,8 @@ between single quotes, even when preceded by a backslash.
Enclosing characters in double quotes (@samp{"}) preserves the literal value
of all characters within the quotes, with the exception of
@samp{$}, @samp{`}, and @samp{\}.
@samp{$}, @samp{`}, @samp{\},
and, when history expansion is enabled, @samp{!}.
The characters @samp{$} and @samp{`}
retain their special meaning within double quotes (@pxref{Shell Expansions}).
The backslash retains its special meaning only when followed by one of
@ -497,8 +477,9 @@ characters are removed. Backslashes preceding characters without a
special meaning are left unmodified.
A double quote may be quoted within double quotes by preceding it with
a backslash.
When command history is being used, the double quote may not be used to
quote the history expansion character.
If enabled, history expansion will be performed unless an @samp{!}
appearing in double quotes is escaped using a backslash.
The backslash preceding the @samp{!} is not removed.
The special parameters @samp{*} and @samp{@@} have special meaning
when in double quotes (@pxref{Shell Parameter Expansion}).
@ -864,6 +845,10 @@ The syntax of the @code{case} command is:
@code{case} will selectively execute the @var{command-list} corresponding to
the first @var{pattern} that matches @var{word}.
If the shell option @code{nocasematch}
(see the description of @code{shopt} in @ref{Bash Builtins})
is enabled, the match is performed without regard to the case
of alphabetic characters.
The @samp{|} is used to separate multiple patterns, and the @samp{)}
operator terminates a pattern list.
A list of patterns and an associated command-list is known
@ -972,6 +957,10 @@ as primaries.
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}.
If the shell option @code{nocasematch}
(see the description of @code{shopt} in @ref{Bash Builtins})
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.
Any part of the pattern may be quoted to force it to be matched as a
@ -985,7 +974,7 @@ 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 @code{nocaseglob}
If the shell option @code{nocasematch}
(see the description of @code{shopt} in @ref{Bash Builtins})
is enabled, the match is performed without regard to the case
of alphabetic characters.
@ -1118,12 +1107,12 @@ 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} trap
below) is not inherited unless the function has been given the
with the exception that 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 @code{DEBUG} trap).
(in which case all functions inherit the @env{DEBUG} and @env{RETURN} traps).
@xref{Bourne Shell Builtins}, for the description of the
@code{trap} builtin.
@ -1208,6 +1197,21 @@ Assignment statements may also appear as arguments to the
@code{declare}, @code{typeset}, @code{export}, @code{readonly},
and @code{local} builtin commands.
In the context where an assignment statement is assigning a value
to a shell variable or array index (@pxref{Arrays}), the @samp{+=}
operator can be used to
append to or add to the variable's previous value.
When @samp{+=} is applied to a variable for which the integer attribute
has been set, @var{value} is evaluated as an arithmetic expression and
added to the variable's current value, which is also evaluated.
When @samp{+=} is applied to an array variable using compound assignment
(@pxref{Arrays}), the
variable's value is not unset (as it is when using @samp{=}), and new
values are appended to the array beginning at one greater than the array's
maximum index.
When applied to a string-valued variable, @var{value} is expanded and
appended to the variable's value.
@node Positional Parameters
@subsection Positional Parameters
@cindex parameters, positional
@ -1256,6 +1260,10 @@ Expands to the positional parameters, starting from one. When the
expansion occurs within double quotes, each parameter expands to a
separate word. That is, @code{"$@@"} is equivalent to
@code{"$1" "$2" @dots{}}.
If the double-quoted expansion occurs within a word, the expansion of
the first parameter is joined with the beginning part of the original
word, and the expansion of the last parameter is joined with the last
part of the original word.
When there are no positional parameters, @code{"$@@"} and
@code{$@@}
expand to nothing (i.e., they are removed).
@ -1292,12 +1300,13 @@ to the filename used to invoke Bash, as given by argument zero.
@item _
(An underscore.)
At shell startup, set to the absolute filename of the shell or shell
script being executed as passed in the argument list.
At shell startup, set to the absolute pathname used to invoke the
shell or shell script being executed as passed in the environment
or argument list.
Subsequently, expands to the last argument to the previous command,
after expansion.
Also set to the full pathname of each command executed and placed in
the environment exported to that command.
Also set to the full pathname used to invoke each command executed
and placed in the environment exported to that command.
When checking mail, this parameter holds the name of the mail file.
@end vtable
@ -1452,7 +1461,7 @@ If the login name is invalid, or the tilde expansion fails, the word is
left unchanged.
Each variable assignment is checked for unquoted tilde-prefixes immediately
following a @samp{:} or @samp{=}.
following a @samp{:} or the first @samp{=}.
In these cases, tilde expansion is also performed.
Consequently, one may use file names with tildes in assignments to
@env{PATH}, @env{MAILPATH}, and @env{CDPATH},
@ -1580,6 +1589,10 @@ parameters beginning at @var{offset}.
If @var{parameter} is an array name indexed by @samp{@@} or @samp{*},
the result is the @var{length}
members of the array beginning with @code{$@{@var{parameter}[@var{offset}]@}}.
A negative @var{offset} is taken relative to one greater than the maximum
index of the specified array.
Note that a negative offset must be separated from the colon by at least
one space to avoid being confused with the @samp{:-} expansion.
Substring indexing is zero-based unless the positional parameters
are used, in which case the indexing starts at 1.
@ -1927,7 +1940,7 @@ Matches zero or more occurrences of the given patterns.
Matches one or more occurrences of the given patterns.
@item @@(@var{pattern-list})
Matches exactly one of the given patterns.
Matches one of the given patterns.
@item !(@var{pattern-list})
Matches anything except one of the given patterns.
@ -2013,6 +2026,10 @@ connection to the corresponding socket.
A failure to open or create a file causes the redirection to fail.
Redirections using file descriptors greater than 9 should be used with
care, as they may conflict with file descriptors the shell uses
internally.
@subsection Redirecting Input
Redirection of input causes the file whose name results from
the expansion of @var{word}
@ -2188,21 +2205,15 @@ is not specified. If the file does not exist, it is created.
@menu
* Simple Command Expansion:: How Bash expands simple commands before
executing them.
* Command Search and Execution:: How Bash finds commands and runs them.
* Command Execution Environment:: The environment in which Bash
executes commands that are not
shell builtins.
* Environment:: The environment given to a command.
* Exit Status:: The status returned by commands and how Bash
interprets it.
* Signals:: What happens when Bash or a command it runs
receives a signal.
@end menu
@node Simple Command Expansion
@ -2603,6 +2614,8 @@ 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.
@node Bourne Shell Builtins
@section Bourne Shell Builtins
@ -2893,6 +2906,8 @@ Evaluate a conditional expression @var{expr}.
Each operator and operand must be a separate argument.
Expressions are composed of the primaries described below in
@ref{Bash Conditional Expressions}.
@code{test} does not accept any options, nor does it accept and ignore
an argument of @option{--} as signifying the end of options.
When the @code{[} form is used, the last argument to the command must
be a @code{]}.
@ -3256,7 +3271,8 @@ by subsequent assignment statements or unset.
@item -t
Give each @var{name} the @code{trace} attribute.
Traced functions inherit the @code{DEBUG} trap from the calling shell.
Traced functions inherit the @code{DEBUG} and @code{RETURN} traps from
the calling shell.
The trace attribute has no special meaning for variables.
@item -x
@ -3295,6 +3311,8 @@ even on systems where they are interpreted by default.
The @code{xpg_echo} shell option may be used to
dynamically determine whether or not @code{echo} expands these
escape characters by default.
@code{echo} does not interpret @option{--} to mean the end of options.
@code{echo} interprets the following escape sequences:
@table @code
@item \a
@ -3409,7 +3427,7 @@ parent.
@item printf
@btindex printf
@example
@code{printf} @var{format} [@var{arguments}]
@code{printf} [-v @var{var}] @var{format} [@var{arguments}]
@end example
Write the formatted @var{arguments} to the standard output under the
control of the @var{format}.
@ -3427,6 +3445,9 @@ beginning with @samp{\0} may contain up to four digits),
and @samp{%q} causes @code{printf} to output the
corresponding @var{argument} in a format that can be reused as shell input.
The @option{-v} option causes the output to be assigned to the variable
@var{var} rather than being printed to the standard output.
The @var{format} is reused as necessary to consume all of the @var{arguments}.
If the @var{format} requires more @var{arguments} than are supplied, the
extra format specifications behave as if a zero value or null string, as
@ -3610,6 +3631,20 @@ If the command run by the @code{DEBUG} trap returns a value of 2, and the
shell is executing in a subroutine (a shell function or a shell script
executed by the @code{.} or @code{source} builtins), a call to
@code{return} is simulated.
@item
@code{BASH_ARGC} and @code{BASH_ARGV} are updated as described in their
descriptions (@pxref{Bash Variables}).
@item
Function tracing is enabled: command substitution, shell functions, and
subshells invoked with @code{( @var{command} )} inherit the
@code{DEBUG} and @code{RETURN} traps.
@item
Error tracing is enabled: command substitution, shell functions, and
subshells invoked with @code{( @var{command} )} inherit the
@code{ERROR} trap.
@end enumerate
@item extglob
@ -3692,6 +3727,11 @@ on an empty line.
If set, Bash matches filenames in a case-insensitive fashion when
performing filename expansion.
@item nocasematch
If set, Bash matches patterns in a case-insensitive fashion when
performing matching while executing @code{case} or @code{[[}
conditional commands.
@item nullglob
If set, Bash allows filename patterns which match no
files to expand to a null string, rather than themselves.
@ -3885,7 +3925,10 @@ set [--abefhkmnptuvxBCHP] [-o @var{option}] [@var{argument} @dots{}]
If no options or arguments are supplied, @code{set} displays the names
and values of all shell variables and functions, sorted according to the
current locale, in a format that may be reused as input.
current locale, in a format that may be reused as input
for setting or resetting the currently-set variables.
Read-only variables cannot be reset.
In @sc{posix} mode, only shell variables are listed.
When options are supplied, they set or unset shell attributes.
Options, if specified, have the following meanings:
@ -4096,9 +4139,11 @@ $ cd ..; pwd
@end example
@item -T
If set, any trap on @code{DEBUG} is inherited by shell functions, command
substitutions, and commands executed in a subshell environment.
The @code{DEBUG} trap is normally not inherited in such cases.
If set, any trap on @code{DEBUG} and @code{RETURN} are inherited by
shell functions, command substitutions, and commands executed
in a subshell environment.
The @code{DEBUG} and @code{RETURN} traps are normally not inherited
in such cases.
@item --
If no arguments follow this option, then the positional parameters are
@ -4249,6 +4294,10 @@ parameters to the current subroutine (shell function or script executed
with @code{.} or @code{source}) is at the top of the stack. When a
subroutine is executed, the number of parameters passed is pushed onto
@code{BASH_ARGC}.
The shell sets @code{BASH_ARGC} only when in extended debugging mode
(see @ref{Bash Builtins}
for a description of the @code{extdebug} option to the @code{shopt}
builtin).
@item BASH_ARGV
An array variable containing all of the parameters in the current bash
@ -4256,6 +4305,10 @@ execution call stack. The final parameter of the last subroutine call
is at the top of the stack; the first parameter of the initial call is
at the bottom. When a subroutine is executed, the parameters supplied
are pushed onto @code{BASH_ARGV}.
The shell sets @code{BASH_ARGV} only when in extended debugging mode
(see @ref{Bash Builtins}
for a description of the @code{extdebug} option to the @code{shopt}
builtin).
@item BASH_COMMAND
The command currently being executed or about to be executed, unless the
@ -4274,8 +4327,8 @@ The command argument to the @option{-c} invocation option.
An array variable whose members are the line numbers in source files
corresponding to each member of @var{FUNCNAME}.
@code{$@{BASH_LINENO[$i]@}} is the line number in the source file where
@code{$@{FUNCNAME[$i + 1]@}} was called.
The corresponding source file name is @code{$@{BASH_SOURCE[$i + 1]@}}.
@code{$@{FUNCNAME[$i]@}} was called.
The corresponding source file name is @code{$@{BASH_SOURCE[$i]@}}.
Use @code{LINENO} to obtain the current line number.
@item BASH_REMATCH
@ -4731,6 +4784,10 @@ prompt when the shell is interactive.
Bash terminates after that number of seconds if input does
not arrive.
@item TMPDIR
If set, Bash uses its value as the name of a directory in which
Bash creates temporary files for the shell's use.
@item UID
The numeric real user id of the current user. This variable is readonly.
@ -4783,7 +4840,7 @@ option).
@item --dump-po-strings
A list of all double-quoted strings preceded by @samp{$}
is printed on the standard ouput
is printed on the standard output
in the @sc{gnu} @code{gettext} PO (portable object) file format.
Equivalent to @option{-D} except for the output format.
@ -4870,7 +4927,7 @@ when invoking an interactive shell.
@item -D
A list of all double-quoted strings preceded by @samp{$}
is printed on the standard ouput.
is printed on the standard output.
These are the strings that
are subject to language translation when the current locale
is not @code{C} or @code{POSIX} (@pxref{Locale Translation}).
@ -5166,6 +5223,7 @@ shell to exit.
@item
When running in @sc{posix} mode, a special builtin returning an error
status will not cause the shell to exit (@pxref{Bash POSIX Mode}).
@item
A failed @code{exec} will not cause the shell to exit
(@pxref{Bourne Shell Builtins}).
@ -5201,6 +5259,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.
Unless otherwise specified, primaries that operate on files follow symbolic
links and operate on the target of the link, rather than the link itself.
@table @code
@item -a @var{file}
True if @var{file} exists.
@ -5414,7 +5475,7 @@ omitted, then base 10 is used.
The digits greater than 9 are represented by the lowercase letters,
the uppercase letters, @samp{@@}, and @samp{_}, in that order.
If @var{base} is less than or equal to 36, lowercase and uppercase
letters may be used interchangably to represent numbers between 10
letters may be used interchangeably to represent numbers between 10
and 35.
Operators are evaluated in order of precedence. Sub-expressions in
@ -5534,12 +5595,18 @@ The braces are required to avoid
conflicts with the shell's filename expansion operators. If the
@var{subscript} is @samp{@@} or @samp{*}, the word expands to all members
of the array @var{name}. These subscripts differ only when the word
appears within double quotes. If the word is double-quoted,
appears within double quotes.
If the word is double-quoted,
@code{$@{name[*]@}} expands to a single word with
the value of each array member separated by the first character of the
@env{IFS} variable, and @code{$@{name[@@]@}} expands each element of
@var{name} to a separate word. When there are no array members,
@code{$@{name[@@]@}} expands to nothing. This is analogous to the
@code{$@{name[@@]@}} expands to nothing.
If the double-quoted expansion occurs within a word, the expansion of
the first parameter is joined with the beginning part of the original
word, and the expansion of the last parameter is joined with the last
part of the original word.
This is analogous to the
expansion of the special parameters @samp{@@} and @samp{*}.
@code{$@{#name[}@var{subscript}@code{]@}} expands to the length of
@code{$@{name[}@var{subscript}@code{]@}}.
@ -5551,6 +5618,8 @@ referencing element zero.
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.
@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.
@ -5843,7 +5912,13 @@ is stopped is `Stopped(@var{signame})', where @var{signame} is, for
example, @code{SIGTSTP}.
@item
Reserved words may not be aliased.
The @code{bg} builtin uses the required format to describe each job placed
in the background, which does not include an indication of whether the job
is the current or previous job.
@item
Reserved words appearing in a context where reserved words are recognized
do not undergo alias expansion.
@item
The @sc{posix} 1003.2 @env{PS1} and @env{PS2} expansions of @samp{!} to
@ -5894,7 +5969,7 @@ may not start with a digit. Declaring a function with an invalid name
causes a fatal syntax error in non-interactive shells.
@item
@sc{posix} 1003.2 `special' builtins are found before shell functions
@sc{posix} 1003.2 special builtins are found before shell functions
during command lookup.
@item
@ -5904,12 +5979,6 @@ the POSIX.2 standard, and include things like passing incorrect options,
redirection errors, variable assignment errors for assignments preceding
the command name, and so on.
@item
If the @code{cd} builtin finds a directory to change to
using @env{$CDPATH}, the
value it assigns to the @env{PWD} variable does not contain any
symbolic links, as if @samp{cd -P} had been executed.
@item
If @env{CDPATH} is set, the @code{cd} builtin will not implicitly
append the current directory to it. This means that @code{cd} will
@ -5989,29 +6058,61 @@ When the @code{cd} builtin is invoked in @var{logical} mode, and the pathname
constructed from @code{$PWD} and the directory name supplied as an argument
does not refer to an existing directory, @code{cd} will fail instead of
falling back to @var{physical} mode.
@item
When the @code{pwd} builtin is supplied the @option{-P} option, it resets
@code{$PWD} to a pathname containing no symlinks.
@item
The @code{pwd} builtin verifies that the value it prints is the same as the
current directory, even if it is not asked to check the file system with the
@option{-P} option.
@item
When listing the history, the @code{fc} builtin does not include an
indication of whether or not a history entry has been modified.
@item
The default editor used by @code{fc} is @code{ed}.
@item
The @code{type} and @code{command} builtins will not report a non-executable
file as having been found, though the shell will attempt to execute such a
file if it is the only so-named file found in @code{$PATH}.
@item
The @code{vi} editing mode will invoke the @code{vi} editor directly when
the @samp{v} command is run, instead of checking @code{$FCEDIT} and
@code{$EDITOR}.
@item
When the @code{xpg_echo} option is enabled, Bash does not attempt to interpret
any arguments to @code{echo} as options. Each argument is displayed, after
escape characters are converted.
@end enumerate
There is other @sc{posix} 1003.2 behavior that Bash does not implement.
There is other @sc{posix} 1003.2 behavior that Bash does not implement by
default even when in @sc{posix} mode.
Specifically:
@enumerate
@item
Assignment statements affect the execution environment of all
builtins, not just special ones.
@item
When a subshell is created to execute a shell script with execute permission,
but without a leading @samp{#!}, Bash sets @code{$0} to the full pathname of
the script as found by searching @code{$PATH}, rather than the command as
typed by the user.
The @code{fc} builtin checks @code{$EDITOR} as a program to edit history
entries if @code{FCEDIT} is unset, rather than defaulting directly to
@code{ed}. @code{fc} uses @code{ed} if @code{EDITOR} is unset.
@item
When using @samp{.} to source a shell script found in @code{$PATH}, bash
checks execute permission bits rather than read permission bits, just as
if it were searching for a command.
As noted above, Bash requires the @code{xpg_echo} option to be enabled for
the @code{echo} builtin to be fully conformant.
@end enumerate
Bash can be configured to be @sc{posix}-conformant by default, by specifying
the @option{--enable-strict-posix-default} to @code{configure} when building
(@pxref{Optional Features}).
@node Job Control
@chapter Job Control
@ -6087,11 +6188,12 @@ There are a number of ways to refer to a job in the shell. The
character @samp{%} introduces a job name.
Job number @code{n} may be referred to as @samp{%n}.
The symbols @samp{%%} and
@samp{%+} refer to the shell's notion of the current job, which
is the last job stopped while it was in the foreground or started
in the background. The
previous job may be referenced using @samp{%-}. In output
The symbols @samp{%%} and @samp{%+} refer to the shell's notion of the
current job, which is the last job stopped while it was in the foreground
or started in the background.
A single @samp{%} (with no accompanying job specification) also refers
to the current job.
The previous job may be referenced using @samp{%-}. In output
pertaining to jobs (e.g., the output of the @code{jobs} command),
the current job is always flagged with a @samp{+}, and the
previous job with a @samp{-}.
@ -6132,15 +6234,15 @@ Bash does not print another warning, and the stopped jobs are terminated.
@item bg
@btindex bg
@example
bg [@var{jobspec}]
bg [@var{jobspec} @dots{}]
@end example
Resume the suspended job @var{jobspec} in the background, as if it
Resume each suspended job @var{jobspec} in the background, as if it
had been started with @samp{&}.
If @var{jobspec} is not supplied, the current job is used.
The return status is zero unless it is run when job control is not
enabled, or, when run with job control enabled, if @var{jobspec} was
not found or @var{jobspec} specifies a job that was started without
job control.
enabled, or, when run with job control enabled, any
@var{jobspec} was not found or specifies a job
that was started without job control.
@item fg
@btindex fg
@ -6216,11 +6318,11 @@ or non-zero if an error occurs or an invalid option is encountered.
@item wait
@btindex wait
@example
wait [@var{jobspec} or @var{pid}]
wait [@var{jobspec} or @var{pid} ...]
@end example
Wait until the child process specified by process @sc{id} @var{pid} or job
specification @var{jobspec} exits and return the exit status of the last
command waited for.
Wait until the child process specified by each process @sc{id} @var{pid}
or job specification @var{jobspec} exits and return the exit status of the
last command waited for.
If a job spec is given, all processes in the job are waited for.
If no arguments are given, all currently active child processes are
waited for, and the return status is zero.
@ -6304,23 +6406,16 @@ Other independent ports exist for
@menu
* Basic Installation:: Installation instructions.
* Compilers and Options:: How to set special options for various
systems.
* Compiling For Multiple Architectures:: How to compile Bash for more
than one kind of system from
the same source tree.
* Installation Names:: How to set the various paths used by the installation.
* Specifying the System Type:: How to configure Bash for a particular system.
* Sharing Defaults:: How to share default configuration values among GNU
programs.
* Operation Controls:: Options recognized by the configuration program.
* Optional Features:: How to enable and disable optional features when
building Bash.
@end menu
@ -6561,10 +6656,10 @@ Define if you are using the Andrew File System from Transarc.
@item --with-bash-malloc
Use the Bash version of
@code{malloc} in @file{lib/malloc/malloc.c}. This is not the same
@code{malloc} in the directory @file{lib/malloc}. This is not the same
@code{malloc} that appears in @sc{gnu} libc, but an older version
derived from the 4.2 @sc{bsd} @code{malloc}. This @code{malloc} is
very fast, but wastes some space on each allocation.
originally derived from the 4.2 @sc{bsd} @code{malloc}. This @code{malloc}
is very fast, but wastes some space on each allocation.
This option is enabled by default.
The @file{NOTES} file contains a list of systems for
which this should be turned off, and @code{configure} disables this
@ -6581,7 +6676,7 @@ A synonym for @code{--with-bash-malloc}.
@item --with-installed-readline[=@var{PREFIX}]
Define this to make Bash link with a locally-installed version of Readline
rather than the version in @file{lib/readline}. This works only with
Readline 4.3 and later versions. If @var{PREFIX} is @code{yes} or not
Readline 5.0 and later versions. If @var{PREFIX} is @code{yes} or not
supplied, @code{configure} uses the values of the make variables
@code{includedir} and @code{libdir}, which are subdirectories of @code{prefix}
by default, to find the installed version of Readline if it is not in
@ -6669,6 +6764,9 @@ Include support for matching POSIX regular expressions using the
@samp{=~} binary operator in the @code{[[} conditional command.
(@pxref{Conditional Constructs}).
@item --enable-debugger
Include support for the bash debugger (distributed separately).
@item --enable-directory-stack
Include support for a @code{csh}-like directory stack and the
@code{pushd}, @code{popd}, and @code{dirs} builtins
@ -6714,17 +6812,17 @@ when used in redirections (@pxref{Redirections}).
This enables process substitution (@pxref{Process Substitution}) if
the operating system provides the necessary support.
@item --enable-progcomp
Enable the programmable completion facilities
(@pxref{Programmable Completion}).
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
strings. See @ref{Printing a Prompt}, for a complete list of prompt
string escape sequences.
@item --enable-progcomp
Enable the programmable completion facilities
(@pxref{Programmable Completion}).
If Readline is not enabled, this option has no effect.
@item --enable-readline
Include support for command-line editing and history with the Bash
version of the Readline library (@pxref{Command Line Editing}).
@ -6738,6 +6836,19 @@ when called as @code{rbash}, enters a restricted mode. See
Include the @code{select} builtin, which allows the generation of simple
menus (@pxref{Conditional Constructs}).
@item --enable-separate-helpfiles
Use external files for the documentation displayed by the @code{help} builtin
instead of storing the text internally.
@item --enable-single-help-strings
Store the text displayed by the @code{help} builtin as a single string for
each help topic. This aids in translating the text to different languages.
You may need to disable this if your compiler cannot handle very long string
literals.
@item --enable-strict-posix-default
Make Bash @sc{posix}-conformant by default (@pxref{Bash POSIX Mode}).
@item --enable-usg-echo-default
A synonym for @code{--enable-xpg-echo-default}.
@ -6746,7 +6857,7 @@ Make the @code{echo} builtin expand backslash-escaped characters by default,
without requiring the @option{-e} option.
This sets the default value of the @code{xpg_echo} shell option to @code{on},
which makes the Bash @code{echo} behave more like the version specified in
the Single Unix Specification, version 2.
the Single Unix Specification, version 3.
@xref{Bash Builtins}, for a description of the escape sequences that
@code{echo} recognizes.
@ -6810,8 +6921,8 @@ differences between the traditional Bourne shell and Bash; this
section quickly details the differences of significance. A
number of these differences are explained in greater depth in
previous sections.
This section uses the version of @code{sh} included in SVR4.2 as
the baseline reference.
This section uses the version of @code{sh} included in SVR4.2 (the
last version of the historical Bourne shell) as the baseline reference.
@itemize @bullet
@ -6863,6 +6974,8 @@ invocation options list the translatable strings found in a script
Bash implements the @code{!} keyword to negate the return value of
a pipeline (@pxref{Pipelines}).
Very useful when an @code{if} statement needs to act only if a test fails.
The Bash @samp{-o pipefail} option to @code{set} will cause a pipeline to
return a failure status if any command fails.
@item
Bash has the @code{time} reserved word and command timing (@pxref{Pipelines}).
@ -6879,7 +6992,12 @@ generation of simple menus (@pxref{Conditional Constructs}).
@item
Bash includes the @code{[[} compound command, which makes conditional
testing part of the shell grammar (@pxref{Conditional Constructs}).
testing part of the shell grammar (@pxref{Conditional Constructs}), including
optional regular expression matching.
@item
Bash provides optional case-insensitive matching for the @code{case} and
@code{[[} constructs.
@item
Bash includes brace expansion (@pxref{Brace Expansion}) and tilde
@ -6900,6 +7018,10 @@ exported to child processes. The Bourne shell does not normally do
this unless the variables are explicitly marked using the @code{export}
command.
@item
Bash supports the @samp{+=} assignment operator, which appends to the value
of the variable named on the left hand side.
@item
Bash includes the @sc{posix} pattern removal @samp{%}, @samp{#}, @samp{%%}
and @samp{##} expansions to remove leading or trailing substrings from
@ -6991,6 +7113,14 @@ opened for both reading and writing, and the @samp{&>} redirection
operator, for directing standard output and standard error to the same
file (@pxref{Redirections}).
@item
Bash includes the @samp{<<<} redirection operator, allowing a string to
be used as the standard input to a command.
@item
Bash implements the @samp{[n]<&@var{word}} and @samp{[n]>&@var{word}}
redirection operators, which move one file descriptor to another.
@item
Bash treats a number of filenames specially when they are
used in redirection operators (@pxref{Redirections}).
@ -7126,7 +7256,9 @@ The @code{trap} builtin (@pxref{Bourne Shell Builtins}) allows a
Commands specified with an @code{RETURN} trap are executed before
execution resumes after a shell function or a shell script executed with
@code{.} or @code{source} returns.
The @code{RETURN} trap is not inherited by shell functions.
The @code{RETURN} trap is not inherited by shell functions unless the
function has been given the @code{trace} attribute or the
@code{functrace} option has been enabled using the @code{shopt} builtin.
@item
The Bash @code{type} builtin is more extensive and gives more information
@ -7158,6 +7290,10 @@ job table (@pxref{Job Control Builtins}) or suppress the sending
of @code{SIGHUP} to a job when the shell exits as the result of a
@code{SIGHUP}.
@item
Bash includes a number of features to support a separate debugger for
shell scripts.
@item
The SVR4.2 shell has two privilege-related builtins
(@code{mldmode} and @code{priv}) not present in Bash.

1581
doc/rose94.ps Normal file
View file

File diff suppressed because it is too large Load diff

12
doc/version.texi
View file

@ -1,10 +1,10 @@
@ignore
Copyright (C) 1988-2004 Free Software Foundation, Inc.
Copyright (C) 1988-2005 Free Software Foundation, Inc.
@end ignore
@set EDITION 3.0
@set VERSION 3.0
@set UPDATED 27 July 2004
@set UPDATED-MONTH July 2004
@set LASTCHANGE Mon Sep 5 11:47:04 EDT 2005
@set LASTCHANGE Tue Jul 27 09:12:07 EDT 2004
@set EDITION 3.1-beta1
@set VERSION 3.1-beta1
@set UPDATED 5 September 2005
@set UPDATED-MONTH September 2005