Introduction
============

The first public release of bash-3.1 is now available with the URLs

ftp://ftp.cwru.edu/pub/bash/bash-3.1.tar.gz
ftp://ftp.gnu.org/pub/gnu/bash/bash-3.1.tar.gz

and from the usual GNU mirror sites.

This tar file does not include the formatted documentation
(postscript, dvi, html, and nroffed versions of the manual pages);
that may be retrieved with the URLs

ftp://ftp.cwru.edu/pub/bash/bash-doc-3.1.tar.gz
ftp://ftp.gnu.org/pub/gnu/bash/bash-doc-3.1.tar.gz

When unpacking the documentation, make sure to extract the tar file
in the bash-3.1 source directory.

Diffs from bash-3.0 are not available.

Please use `bashbug' to report bugs with this version. It is built
and installed at the same time as bash.

Installation
============

Please read the README file first.

Installation instructions are provided in the INSTALL file.

New Features
============

This is the first maintenance release for the third major release of bash.

As with all odd-numbered minor releases, the focus is on bug fixes;
there are several dozen important fixes included. A few new features
have been added: the `+=' assignment operator, the `-v var' option to
printf, and the `nocasematch' shell option are the most notable.

Read the file NEWS in the bash-3.1 distribution for a complete description
of the new features. Here is a short list:

o This version of bash can be configured to provide strict POSIX conformance
by default using a new option to `configure'.

o The `+=' assignment operator (append to the value of a string or array) is
now supported for assignment statements and arguments to builtin commands
that accept assignment statements.

o The `printf' builtin takes a new option: -v var. That causes the output
to be placed into var instead of on stdout.

o New shell option: nocasematch. If non-zero, shell pattern matching ignores
case when used by `case' and `[[' commands.

Changes have been made to the Readline library being released at
the same time as bash-3.1, readline-5.1, so that Bash can be
linked against an already-installed Readline library rather than
the private version in lib/readline. Only readline-5.1 and later
versions are able to provide all of the symbols that bash-3.1
requires; earlier versions of the Readline library will not work
correctly.

A complete list of changes between bash-3.0 and bash-3.1 is
available in the file CHANGES; the relevant portions are appended.

Readline
========

Also available is a new release of the standalone Readline library,
version 5.1, with its own configuration scripts and Makefiles.
It can be retrieved with the URLs

ftp://ftp.cwru.edu/pub/bash/readline-5.1.tar.gz
ftp://ftp.gnu.org/pub/gnu/readline/readline-5.1.tar.gz

and from the usual GNU mirror sites.

Diffs from readline-5.0 are not available.

The formatted Readline documentation is included in the readline
distribution tar file.

A separate announcement listing the changes in Readline is being
distributed.

As always, thanks for your help.

Chet

+========== CHANGES ==========+
This document details the changes between this version, bash-3.1-release,
and the previous version, bash-3.1-rc2.

1. Changes to Readline

a. Several changes to the multibyte redisplay code to fix problems with
prompts containing invisible characters.

------------------------------------------------------------------------------
This document details the changes between this version, bash-3.1-rc2,
and the previous version, bash-3.1-rc1.

1. Changes to Bash

a. Fixed a bug that caused a DEBUG trap to overwrite a command string that's
eventually attached to a background job.

b. Changed some code so that filenames with leading tildes with spaces in the
name aren't tilde-expanded by the bash completion code.

c. Fixed a bug that caused the pushd builtin to fail to change to
directories with leading `-'.

d. Fixed a small memory leak in the programmable completion code.

2. Changes to Readline

a. Fixed a redisplay bug caused by moving the cursor vertically to a line
with invisible characters in the prompt in a multibyte locale.

b. Fixed a bug that could cause the terminal special chars to be bound in the
wrong keymap in vi mode.

3. New Features in Bash

a. If compiled for strict POSIX conformance, LINES and COLUMNS may now
override the true terminal size.

4. New Features in Readline

a. A new external application-controllable variable that allows the LINES
and COLUMNS environment variables to set the window size regardless of
what the kernel returns.

------------------------------------------------------------------------------
This document details the changes between this version, bash-3.1-rc1,
and the previous version, bash-3.1-beta1.

1. Changes to Bash

a. Fixed a bug that could cause core dumps due of accessing the current
pipeline while in the middle of modifying it.

b. Fixed a bug that caused pathnames with backslashes still quoting characters
to be passed to opendir().

c. Command word completion now obeys the setting of completion-ignore-case.

d. Fixed a problem with redirection that caused file descriptors greater than
2 to be inappropriately marked as close-on-exec.

e. In Posix mode, after `wait' is called to wait for a particular process
explicitly, that process is removed from the list of processes known to
the shell, and subsequent attempts to wait for it return errors.

f. Fixed a bug that caused extended pattern matching to incorrectly scan
backslash-escaped pattern characters.

g. Fixed a synchronization problem that could cause core dumps when handling
a SIGWINCH.

h. Fixed a bug that caused an unmatched backquote to be accepted without an
error when processing here documents.

i. Fixed a small memory leak in the `cd' builtin.

j. Fix for MacOS X so it gets the values for the HOSTTYPE, MACHTYPE, and
OSTYPE variables at build time, to support universal binaries.

k. Fixed a bug that could cause an exit trap to return the exit status of
the trap command rather than the status as it was before the trap was
run as the shell's exit status.

2. New Features in Bash

3. Changes to Readline

a. Fixed a bug that caused reversing the incremental search direction to
not work correctly.

b. Fixed the vi-mode `U' command to only undo up to the first time insert mode
was entered, as Posix specifies.

c. Fixed a bug in the vi-mode `r' command that left the cursor in the wrong
place.

4. New Features in Readline

a. New application-callable auxiliary function, rl_variable_value, returns
a string corresponding to a readline variable's value.

b. When parsing inputrc files and variable binding commands, the parser
strips trailing whitespace from values assigned to boolean variables
before checking them.


------------------------------------------------------------------------------
This document details the changes between this version, bash-3.1-beta1,
and the previous version, bash-3.1-alpha1.

1. Changes to Bash

a. Added some system-specific signal names.

b. Fixed a typo in the ulimit builtin to make `x' the right option to
maniuplate the limit on file locks.

c. Fixed a problem with using += to append to index 0 of an array variable
when not using subscript syntax.

d. A few changes to configure.in to remove calls to obsolete or outdated
macros.

e. Make sure changes to variables bash handles specially (e.g., LC_ALL) are
made when the variable is set in the temporary environment to a command.

f. Make sure changes to variables bash handles specially (e.g., LC_ALL) are
made when the variable is modified using `printf -v'.

g. The export environment is now remade on cygwin when HOME is changed, so
DLLs bash is linked against pick up the new value. This fixes problems
with tilde expansion when linking against and already-installed readline.

h. Small fix to the logic for performing tilde expansion in posix mode, so
expansion on the right-hand side of an assignment statement takes place.

i. Fixed a bug that prevented redirections associated with a shell function
from being executed when in a subshell.

j. Fixed `source' and `.' builtins to not require an executable file when
searching $PATH for a file to source.

k. Fixed a bug that caused incorrect word splitting in a function when IFS
was declared local, then unset.

l. Fixed a problem with the `kill' builtin that prevented sending signals
to a process group under certain circumstances when providing a pid < 0.

m. When in POSIX mode, `pwd' now checks that the value it prints is the same
directory as `.', even when displaying $PWD.

n. Fixed a problem with the `read' builtin when reading a script from standard
input and reading data from the same file.

o. Fixed a problem with the `type' and `command' builtins that caused absolute
pathnames to be displayed incorrectly.

p. Some changes to the `bg' builtin for POSIX conformance.

q. The `fc' builtin now removes the `fc' command that caused it to invoke an
editor on specified history entries from the history entirely, rather than
simply ignoring it.

r. When in POSIX mode, the `v' command in vi editing mode simply invokes vi
on the current command, rather than checking $FCEDIT and $EDITOR.

s. Fixed a small memory leak in the pathname canonicalization code.

t. Fixed a bug that caused the expanded value of a $'...' string to be
incorrectly re-quoted if it occurred within a double-quoted ${...}
parameter expansion.

u. Restored default emacs-mode key binding of M-TAB to dynamic-complete-history.

v. Fixed a bug that caused core dumps when interrupting loops running builtins
on some systems.

w. Make sure that some of the functions bash provides replacements for are
not cpp defines.

x. The code that scans embedded commands for the parser (`...` and $(...)) is
now more aware of embedded comments and their effect on quoted strings.

y. Changed the `-n' option to the `history' builtin to not reset the number of
history lines read in the current session after reading the new lines from
the history file if the history is being appended when it is written to
the file, since the appending takes care of the problem that the adjustment
was intended to solve.

z. Improved the error message displayed when a shell script fails to execute
because the environment and size of command line arguments are too large.

aa. A small fix to make sure that $HISTCMD is evaluated whenever the shell is
saving commands to the history list, not just when HISTSIZE is defined.

2. Changes to Readline

a. The `change-case' command now correctly changes the case of multibyte
characters.

b. Changes to the shared library construction scripts to deal with Windows
DLL naming conventions for Cygwin.

c. Fixed the redisplay code to avoid core dumps resulting from a poorly-timed
SIGWINCH.

d. Fixed the non-incremental search code in vi mode to dispose of any current
undo list when copying a line from the history into the current editing
buffer.

e. The variable assignment code now ignores whitespace at the end of lines
when assigning to boolean variables.

f. The `C-w' binding in incremental search now understands multibyte
characters.

3. New Features in Bash

a. A new configuration option, `--enable-strict-posix-default', which will
build bash to be POSIX conforming by default.

4. New Features in Readline

a. If the rl_completion_query_items is set to a value < 0, readline never
asks the user whether or not to view the possible completions.

------------------------------------------------------------------------------
This document details the changes between this version, bash-3.1-alpha1,
and the previous version, bash-3.0-release.

1. Changes to Bash

a. Fixed a bug that caused bash to crash if referencing an unset local array.

b. Fixed a problem that caused tilde expansion to not be performed before
attempting globbing word completion.

c. Fixed an incompatibility so that a first argument to trap that's a valid
signal number will be trated as a signal rather than a command to execute.

d. Fixed ${#word} expansion to correctly compute the length of a string
containing multibyte characters.

e. Fixed a bug that caused bash to not pass the correct flags for signal
disposition to child processes.

f. Fixed a bug that caused `fc -l' to list one too many history entries.

g. Some fixes to `fc' for POSIX conformance.

h. Some fixes to job status display for POSIX conformance.

i. Fixed a bug that caused `command -v' to display output if a command was not
found -- it should be silent.

j. In POSIX mode, `type' and `command -[vV]' do not report non-executable
files, even if the shell will attempt to execute them.

k. Fixed a bug that caused the `==' operator to the [[ command to not attempt
extended pattern matching.

l. Fixed the brace expansion code to handle characters whose value exceeds 128.

m. Fixed `printf' to handle strings with a leading `\0' whose length is
non-zero.

n. Fixed a couple of problems with brace expansion where `${' was handled
incorrectly.

o. Fixed off-by-one error when calculating the upper bound of `offset' when
processing the ${array[@]ffset:length} expansion.

p. System-specific configuration changes for: FreeBSD 5.x, Interix, MacOS X
10.4, Linux 2.4+ kernels, Linux 3.x kernels, Dragonfly BSD, QNX 6.x,
Cygwin

q. Fixed a bug that caused the shell to ignore the status of the rightmost
command in a pipeline when the `pipefail' option was enabled.

r. Fixed a completion bug that caused core dumps when expanding a directory
name.

s. Fixed a bug that prevented `hash -d' from removing commands from the hash
table.

t. Fixed word splitting to avoid really bad quadratic performance when
expanding long lists.

u. Fixed a bug that caused negative offsets in substring expansion to use the
wrong values.

v. Fixed a bug in printf that caused it to not return failure on write errors.

w. Fixed a bug that caused commands in subshells to not be properly timed.

x. The shell parser no longer attempts to parse a compound assignment specially
unless in a position where an assignment statement is acceptable or parsing
arguments to a builtin that accepts assignment statements.

y. Fixed a problem that caused a `case' statement to be added to the history
incorrectly as a single command if the `case word' was on one line and the
`in' on another.

z. Fixed a problem that caused internal shell quoting characters to be
incorrectly quoted with backslashes under some circumstances.

aa. The shell now performs correct word splitting when IFS contains multibyte
characters.

bb. The mail checking code now resets the cached file information if the size
drops to 0, even if the times don't change.

cc. A completed command name that is found in $PATH as well as the name of a
directory in the current directory no longer has a slash appended in certain
circumstances: a single instance found in $PATH when `.' is not in $PATH,
and multiple instances found in $PATH, even when `.' is in $PATH.

dd. Incorporated tilde expansion into the word expansion code rather than as a
separately-called function, fixing some cases where it was performed
inappropriately (e.g., after the second `=' in an assignment statement or
in a double-quoted parameter expansion).

ee. Fixed several bugs encountered when parsing compound assignment statements,
so that compound assignments appearing as arguments to builtins are no
longer double-expanded.

ff. Fixed a bug in the command execution code that caused asynchronous commands
containing command substitutions to not put the terminal in the wrong
process group.

gg. Bash now handles the case where the WCONTINUED flag causes waitpid() to
return -1/EINVAL at runtime as well as configuration time.

hh. Fixed parser to generate an error when the pipeline `argument' to `!' or
`time' is NULL.

ii. The shell now takes a little more care when manipulating file descriptors
greater than 9 with the `exec' builtin.

jj. Fixed a bug that caused variable assignments preceding the `command' builtin
preceding a special builtin to be preserved after the command completed in
POSIX mode.

kk. Fixed a bug that allowed variables beginning with a digit to be created.

ll. Fixed a bug that caused a \ to be removed when parsing a $'...'
construct.

mm. A shell whose name begins with `-' will now be a restricted shell if the
remainder of the name indicates it should be restricted.

nn. Fixed a bug that could cause a core dump if FUNCNAME were changed or unset
during a function's execution.

oo. Fixed a bug that caused executing a `return' in a function to not execute
a RETURN trap. The RETURN trap is inherited by shell functions only if
function tracing is globally enabled or has been enabled for that function.

pp. Fixed cases where var[@] was not handled exactly like var, when var is a
scalar variable.

qq. Fixed a bug that caused the first character after a SIGINT to be discarded
under certain circumstances.

rr. Fixed exit status code so that a suspended job returns 128+signal as its
exit status (preventing commands after it in `&&' lists from being
executed).

ss. Fixed a bug that caused the shell parser state to be changed by executing
a shell function as a result of word completion.

tt. Fixed a long-standing bug that caused '\177' characters in variable
values to be discarded when expanded in double-quoted strings.

uu. Fixed a bug that caused $RANDOM to be re-seeded multiple times in a
subshell environment.

vv. Extensive changes to the job management code to avoid the pid-reuse and
pid-aliasing problems caused by retaining the exit status of too many jobs,
but still retain as many background job statuses as POSIX requires.

ww. Fixed a parser bug in processing \ that caused things like

((echo 5) \
(echo 6))

to not work correctly.

xx. `pwd -P' now sets $PWD to a directory name containing no symbolic links
when in posix mode, as POSIX requires.

yy. In posix mode, bash no longer sets $PWD to a name containing no symbolic
links if a directory is chosen from $CDPATH.

zz. The word splitting code now treats an IFS character that is not space,
tab, or newline and any adjacent IFS white space as a single delimiter, as
SUSv3/XPG6 require.

aaa. The `read' builtin now checks whether or not the number of fields read is
exactly the same as the number of variables instead of just assigning the
rest of the line (minus any trailing IFS white space) to the last
variable. This is what POSIX/SUS/XPG all require.

bbb. Fixed a bug that caused `read' to always check whether or not fd 0 was a
pipe, even when reading from another file descriptor.

ccc. Fixed a bug that caused short-circuiting of execution even if the return
value was being inverted.

ddd. Fixed a bug that caused a core dump while decoding \W escapes in PS1 if
PWD was unset.

eee. Fixed a bug in `read' that counted internal quoting characters for the
purposes of `read -n'.

fff. Fixed a bug so that a function definition in a pipeline causes a child
process to be forked at the right time.

ggg. Bash will not attempt to link against a readline library that doesn't
have rl_gnu_readline_p == 1.

hhh. Fixed a bug that caused `read' to consume one too many characters when
reading a fixed number of characters and the Nth character is a backslash.

iii. Fixed a bug that caused `unset' on variables in the temporary environment
to leave them set when `unset' completed.

jjj. Fixed a bug that caused bash to close fd 2 if an `exec' failed and the
shell didn't exit.

kkk. The completion code is more careful to not turn `/' or `///' into `//',
for those systems on which `//' has special meaning.

lll. Fixed a bug that caused command substitution in asynchronous commands to
close the wrong file descriptors.

mmm. The shell no longer prints status messages about terminated background
processes unless job control is active.

nnn. Fixed a bug that prevented multiple consecutive invocations of `history -s'
from adding all the commands to the history list.

ooo. Added a couple of changes to make arithmetic expansion more consistent in
all its contexts (still not perfect).

ppp. Fixed a bug that caused the parser to occasionally not find the right
terminating "`" in an old-style command substitution.

qqq. Fixed a bug that caused core dumps when the shell was reading its non-
interactive input from fd 0 and fd 0 was duplicated and restored using a
combination of `exec' (to save) and redirection (to restore).

rrr. Fixed a problem that caused loops in sourced scripts to not be cleaned
up properly when a `return' is executed.

sss. Change internal command substitution completion function to append a slash
to directory names in the command.

2. Changes to Readline

a. Fixed a bug that caused multiliine prompts to be wrapped and displayed
incorrectly.

b. Fixed a bug that caused ^P/^N in emacs mode to fail to display the current
line correctly.

c. Fixed a problem in computing the number of invisible characters on the first
line of a prompt whose length exceeds the screen width.

d. Fixed vi-mode searching so that failure preserves the current line rather
than the last line in the history list.

e. Fixed the vi-mode `~' command (change-case) to have the correct behavior at
end-of-line when manipulating multibyte characters.

f. Fixed the vi-mode `r' command (change-char) to have the correct behavior at
end-of-line when manipulating multibyte characters.

g. Fixed multiple bugs in the redisplay of multibyte characters: displaying
prompts longer than the screen width containing multibyte characters,

h. Fix the calculation of the number of physical characters in the prompt
string when it contains multibyte characters.

i. A non-zero value for the `rl_complete_suppress_append' variable now causes
no `/' to be appended to a directory name.

j. Fixed forward-word and backward-word to work when words contained
multibyte characters.

k. Fixed a bug in finding the delimiter of a `?' substring when performing
history expansion in a locale that supports multibyte characters.

l. Fixed a memory leak caused by not freeing the timestamp in a history entry.

m. Fixed a bug that caused "\M-x" style key bindings to not obey the setting
of the `convert-meta' variable.

n. Fixed saving and restoring primary prompt when prompting for incremental
and non-incremental searches; search prompts now display multibyte
characters correctly.

o. Fixed a bug that caused keys originally bound to self-insert but shadowed
by a multi-character key sequence to not be inserted.

p. Fixed code so rl_prep_term_function and rl_deprep_term_function aren't
dereferenced if NULL (matching the documentation).

q. Extensive changes to readline to add enough state so that commands
requiring additional characters (searches, multi-key sequences, numeric
arguments, commands requiring an additional specifier character like
vi-mode change-char, etc.) work without synchronously waiting for
additional input.

r. Lots of changes so readline builds and runs on MinGW.

s. Readline no longer tries to modify the terminal settings when running in
callback mode.

t. The Readline display code no longer sets the location of the last invisible
character in the prompt if the \[\] sequence is empty.

3. New Features in Bash

a. Bash now understands LC_TIME as a special variable so that time display
tracks the current locale.

b. BASH_ARGC, BASH_ARGV, BASH_SOURCE, and BASH_LINENO are no longer created
as `invisible' variables and may not be unset.

c. In POSIX mode, if `xpg_echo' option is enabled, the `echo' builtin doesn't
try to interpret any options at all, as POSIX requires.

d. The `bg' builtin now accepts multiple arguments, as POSIX seems to specify.

e. Fixed vi-mode word completion and glob expansion to perform tilde
expansion.

f. The `**' mathematic exponentiation operator is now right-associative.

g. The `ulimit' builtin has new options: -i (max number of pending signals),
-q (max size of POSIX message queues), and -x (max number of file locks).

h. A bare `%' once again expands to the current job when used as a job
specifier.

i. The `+=' assignment operator (append to the value of a string or array) is
now supported for assignment statements and arguments to builtin commands
that accept assignment statements.

j. BASH_COMMAND now preserves its value when a DEBUG trap is executed.

k. The `gnu_errfmt' option is enabled automatically if the shell is running
in an emacs terminal window.

l. New configuration option: --single-help-strings. Causes long help text
to be written as a single string; intended to ease translation.

m. The COMP_WORDBREAKS variable now causes the list of word break characters
to be emptied when the variable is unset.

n. An unquoted expansion of $* when $IFS is empty now causes the positional
parameters to be concatenated if the expansion doesn't undergo word
splitting.

o. Bash now inherits $_ from the environment if it appears there at startup.

p. New shell option: nocasematch. If non-zero, shell pattern matching ignores
case when used by `case' and `[[' commands.

q. The `printf' builtin takes a new option: -v var. That causes the output
to be placed into var instead of on stdout.

r. By default, the shell no longer reports processes dying from SIGPIPE.

s. Bash now sets the extern variable `environ' to the export environment it
creates, so C library functions that call getenv() (and can't use the
shell-provided replacement) get current values of environment variables.

4. New Features in Readline

a. The key sequence sent by the keypad `delete' key is now automatically
bound to delete-char.

b. A negative argument to menu-complete now cycles backward through the
completion list.

c. A new bindable readline variable: bind-tty-special-chars. If non-zero,
readline will bind the terminal special characters to their readline
equivalents when it's called (on by default).

d. New bindable command: vi-rubout. Saves deleted text for possible
reinsertion, as with any vi-mode `text modification' command; `X' is bound
to this in vi command mode.
--
``The lyf so short, the craft so long to lerne.'' - Chaucer
( ``Discere est Dolere'' -- chet )
Live Strong.
Chet Ramey, ITS, CWRU chet@case.edu http://tiswww.tis.case.edu/~chet/