@c %**end of header
@ignore
-last change: Mon Nov 25 11:47:06 EST 1996
+last change: Mon May 19 12:55:22 EDT 1997
@end ignore
@set EDITION 2.0
-@set VERSION 2.0
-@set UPDATED 25 November 1996
-@set UPDATE-MONTH November 1996
+@set VERSION 2.01
+@set UPDATED 19 May 1997
+@set UPDATE-MONTH May 1997
@iftex
@finalout
@item job control
@cindex job control
-A mechanism by which users can selectively start and stop execution
-of processes.
+A mechanism by which users can selectively stop (suspend) and restart
+(resume) execution of processes.
@item metacharacter
@cindex metacharacter
The syntax of the @code{case} command is:
@example
-@code{case @var{word} in [@var{pattern} [| @var{pattern}]@dots{}) @var{commands} ;;]@dots{} esac}
+@code{case @var{word} in [ ( @var{pattern} [| @var{pattern}]@dots{}) @var{commands} ;;]@dots{} esac}
@end example
Selectively execute @var{commands} based upon @var{word} matching
@end example
The @var{expression} is evaluated according to the rules described
-below ((@pxref{Arithmetic Evaluation}).
+below (@pxref{Arithmetic Evaluation}).
If the value of the expression is non-zero, the return status is 0;
otherwise the return status is 1. This is exactly equivalent to
@example
are @code{reserved words}, so they must be separated from the @var{list}
by @code{blank}s. The parentheses are @code{operators}, and are
recognized as separate tokens by the shell even if they are not separated
-from @code{list} by whitespace.
+from the @var{list} by whitespace.
The exit status of both of these constructs is the exit status of
@var{list}.
When a function is executed, the arguments to the
function become the positional parameters
during its execution (@pxref{Positional Parameters}).
-The special parameter
-@samp{#} that gives the number of positional parameters
-is updated to reflect the change. Positional parameter @code{0}
-is unchanged.
+The special parameter @samp{#} that expands to the number of
+positional parameters is updated to reflect the change.
+Positional parameter @code{0} is unchanged.
If the builtin command @code{return}
is executed in a function, the function completes and
special variable. That is, @code{"$*"} is equivalent
to @code{"$1@var{c}$2@var{c}@dots{}"}, where @var{c}
is the first character of the value of the @code{IFS}
-variable. If @code{IFS}
-is null or unset, the parameters are separated by spaces.
+variable.
+If @code{IFS} is unset, the parameters are separated by spaces.
+If @code{IFS} is null, the parameters are joined without intervening
+separators.
+
@item @@
Expands to the positional parameters, starting from one. When the
can change the number of words of the expansion; other expansions
expand a single word to a single word.
The only exceptions to this are the expansions of
-@code{"$@@"} (@pxref{Special Parameters}) and @code{"$@{[@@]@}"}
+@code{"$@@"} (@pxref{Special Parameters}) and @code{"$@{@var{name}[@@]@}"}
(@pxref{Arrays}).
After all expansions, @code{quote removal} (@pxref{Quote Removal})
a level of variable indirection is introduced.
Bash uses the value of the variable formed from the rest of
@var{parameter} as the name of the variable; this variable is then
-expanded and that value used in the rest of the substitution, rather
+expanded and that value is used in the rest of the substitution, rather
than the value of @var{parameter} itself.
This is known as @code{indirect expansion}.
@item trap
@btindex trap
@example
-trap [-lp] [@var{arg}] [@var{sigspec}]
+trap [-lp] [@var{arg}] [@var{sigspec} @dots{}]
@end example
The commands in @var{arg} are to be read and executed when the
shell receives signal @var{sigspec}. If @var{arg} is absent or
equal to @samp{-}, all specified signals are reset to the values
they had when the shell was started.
-If @var{arg} is the null string, then @var{sigspec} is ignored by
-the shell and commands it invokes.
+If @var{arg} is the null string, then the signal specified by
+each @var{sigspec} is ignored by the shell and commands it invokes.
If @var{arg} is @samp{-p}, the shell displays the trap commands
associated with each @var{sigspec}. If no arguments are supplied, or
only @samp{-p} is given, @code{trap} prints the list of commands
-associated with each signal number. @var{sigspec} is either a signal
-name such as @code{SIGINT} or a signal number. If @var{sigspec} is
-@code{0} or @code{EXIT}, @var{arg} is executed when the shell exits.
-If @var{sigspec} is @code{DEBUG}, the command @var{arg} is executed
+associated with each signal number.
+Each @var{sigspec} is either a signal name such as @code{SIGINT} (with
+or without the @code{SIG} prefix) or a signal number.
+If a @var{sigspec}
+is @code{0} or @code{EXIT}, @var{arg} is executed when the shell exits.
+If a @var{sigspec} is @code{DEBUG}, the command @var{arg} is executed
after every simple command.
The @samp{-l} option causes the shell to print a list of signal names
and their corresponding numbers.
list the translatable strings found in a script
(@pxref{Locale Translation}).
-The expansion @code{$@{var:}@var{length}@code{[:}@var{offset}@code{]@}},
+The expansion @code{$@{var:}@var{offset}@code{[:}@var{length}@code{]@}},
which expands to the substring of @code{var}'s value of length
@var{length}, optionally beginning at @var{offset}, is present
(@pxref{Shell Parameter Expansion}).
Bash has process substitution (@pxref{Process Substitution}).
Bash automatically assigns variables that provide information about the
-current user (@code{UID} and @code{EUID}), the current host
+current user (@code{UID}, @code{EUID}, and @code{GROUPS}), the current host
(@code{HOSTTYPE}, @code{OSTYPE}, @code{MACHTYPE}, and @code{HOSTNAME}),
and the instance of Bash that is running (@code{BASH},
@code{BASH_VERSION}, and @code{BASH_VERSINFO}. @xref{Bash Variables},
@code{local} builtin, and thus useful recursive functions may be written.
Variable assignments preceding commands affect only that command, even
-builtins and functions. In @code{sh}, all variable assignments
+builtins and functions (@pxref{Environment}).
+In @code{sh}, all variable assignments
preceding commands are global unless the command is executed from the
file system.
attributes, and @samp{name=value} arguments to set variable attributes
and values simultaneously.
-The Bash @code{cd} and @code{pwd} builtins each take @samp{-L} and
-@samp{-P} builtins to switch between logical and physical modes.
+The Bash @code{cd} and @code{pwd} builtins (@pxref{Bourne Shell Builtins})
+each take @samp{-L} and @samp{-P} builtins to switch between logical and
+physical modes.
The Bash @code{type} builtin is more extensive and gives more information
-about the names it finds.
+about the names it finds (@pxref{Bash Builtins}).
Bash implements a @code{csh}-like directory stack, and provides the
-@code{pushd}, @code{popd}, and @code{dirs} builtins to manipulate it.
+@code{pushd}, @code{popd}, and @code{dirs} builtins to manipulate it
+(@pxref{C Shell Builtins}).
Bash also makes the directory stack visible as the value of the
@code{DIRSTACK} shell variable.
function call), the shell misbehaves badly.
@item
-In a questionable attempt at security, the @sc{SVR4.2} shell
-will alter its real
+In a questionable attempt at security, the @sc{SVR4.2} shell,
+when invoked without the @samp{-p} option, will alter its real
and effective @sc{UID} and @sc{GID} if they are less than some
-threshold value, commonly 100. This can lead to unexpected results.
+magic threshold value, commonly 100.
+This can lead to unexpected results.
@item
The @sc{SVR4.2} shell does not allow users to trap @code{SIGALRM} or
@item
The @sc{SVR4.2} shell exits a script if any builtin fails; Bash exits
a script only if one of the @sc{POSIX.2} special builtins fails, and
-only for certain failures, as enumerated in the @code{POSIX.2} standard.
+only for certain failures, as enumerated in the @sc{POSIX.2} standard.
@item
The @sc{SVR4.2} shell behaves differently when invoked as @code{jsh}
@table @code
@item +@var{N}
Brings the @var{N}th directory (counting from the left of the
-list printed by @code{dirs}) to the top of the list by rotating
-the stack.
+list printed by @code{dirs}, starting with zero) to the top of
+the list by rotating the stack.
@item -@var{N}
Brings the @var{N}th directory (counting from the right of the
-list printed by @code{dirs}) to the top of the list by rotating
-the stack.
+list printed by @code{dirs}, starting with zero) to the top of
+the list by rotating the stack.
@item -n
Suppresses the normal change of directory when adding directories
to the stack, so that only the stack is manipulated.
point the @code{select} command completes.
Bash also has adopted command timing from the Korn shell. If the
-@code{time} reserved word precedes a pipeline or simple command,
-timing statistics for the pipeline are displayed when it completes.
+@code{time} reserved word precedes a pipeline, which may consist
+of a single command, timing statistics for the pipeline are displayed
+when it completes.
The statistics currently consist of elapsed (wall-clock) time and
user and system time consumed by the command's execution.
@item LINENO
The line number in the script or shell function currently executing.
-@item ENV
-If this variable is set when Bash is invoked to execute a shell
-script, its value is expanded and used as the name of a startup file
-to read before executing the script. @xref{Bash Startup Files}.
-
@item FCEDIT
The editor used as a default by the @code{fc} builtin command.
@section Bash Startup Files
@cindex startup files
-This section describs how bash executes its startup files.
-If any of the files exist but cannot be read, bash reports an error.
+This section describs how Bash executes its startup files.
+If any of the files exist but cannot be read, Bash reports an error.
Tildes are expanded in file names as described above under
Tilde Expansion (@pxref{Tilde Expansion}).
-When Bash is invoked as a login shell, it first reads and
+When Bash is invoked as an interactive login shell, it first reads and
executes commands from the file @file{/etc/profile}, if that file exists.
After reading that file, it looks for @file{~/.bash_profile},
@file{~/.bash_login}, and @file{~/.profile}, in that order, and reads
In this mode, the @code{ENV} variable is expanded and commands are read
and executed from the file whose name is the expanded value.
No other startup files are read.
-This is done by both interactive and non-interactive shells.
+This is done by interactive shells only.
Bash attempts to determine when it is being run by the remote shell
daemon, usually @code{rshd}. If Bash determines it is being run by
fi
@end example
+Alternatively, you may test the value of the @samp{-} special parameter.
+It contains @code{i} when the shell is interactive. For example:
+
+@example
+case "$-" in
+*i*) echo This shell is interactive ;;
+*) echo This shell is not interactive ;;
+esac
+@end example
+
@node Bash Builtins
@section Bash Builtin Commands
@example
builtin [@var{shell-builtin} [@var{args}]]
@end example
-Run a shell builtin. This is useful when you wish to rename a
-shell builtin to be a function, but need the functionality of the
-builtin within the function itself.
+Run a shell builtin. This is useful when you wish to define a
+shell function with the same name as a shell builtin, but need the
+functionality of the builtin within the function itself.
@item command
@btindex command
a missing character, and a character too many.
If a correction is found, the corrected path is printed,
and the command proceeds.
-This option is enabled by default, but is only used by interactive shells.
+This option is only used by interactive shells.
@item checkhash
If this is set, Bash checks that a command found in the hash
@item hostcomplete
If set, and Readline is being used, Bash will attempt to perform
hostname completion when a word beginning with @samp{@@} is being
-completed (@pxref{Commands For Completion}).
+completed (@pxref{Commands For Completion}). This option is enabled
+by default.
@item interactive_comments
Allow a word beginning with @samp{#}
@item -p
Turn on privileged mode.
-In this mode, the @code{$ENV}
+In this mode, the @code{$BASH_ENV}
file is not processed, and shell functions
are not inherited from the environment. This is enabled automatically
on startup if the effective user (group) id is not equal to the real
@vtable @code
+@item BASH_ENV
+If this variable is set when Bash is invoked to execute a shell
+script, its value is expanded and used as the name of a startup file
+to read before executing the script. @xref{Bash Startup Files}.
+
@item TIMEFORMAT
The value of this parameter is used as a format string specifying
how the timing information for pipelines prefixed with the @code{time}
The value of @var{p} determines whether or not the fraction is included.
If this variable is not set, bash acts as if it had the value
+@example
@code{$'\nreal\t%3lR\nuser\t%3lU\nsys\t%3lS'}.
+@end example
If the value is null, no timing information is displayed.
A trailing newline is added when the format string is displayed.
@item EUID
The numeric effective user id of the current user.
+@item GROUPS
+An array variable containing the list of groups of which the current
+user is a member.
+
@item PPID
The process id of the shell's parent process.
@item SHLVL
Incremented by one each time a new instance of Bash is started. This is
-intended to be an account of how deeply your Bash shells are nested.
+intended to be a count of how deeply your Bash shells are nested.
@item OPTERR
If set to the value 1, Bash displays error messages
This variable overrides the value of @code{LANG} and any other
@code{LC_} variable specifying a locale category.
+@item LC_COLLATE
+This variable determines the collation order used when sorting the
+results of filename expansion (@pxref{Filename Expansion}).
+
@item LC_MESSAGES
This variable determines the locale used to translate double-quoted
-strings preceded by a @samp{$}.
+strings preceded by a @samp{$} (@pxref{Locale Translation}).
@item IGNOREEOF
Controls the action of the shell on receipt of an @code{EOF} character
redirection errors, variable assignment errors for assignments preceding
the command name, and so on.
-@ignore
-@item
-The environment passed to executed commands is not sorted. Neither is
-the output of @code{set}. This is not strictly Posix.2 behavior, but
-@code{sh} does it this way. @code{ksh} does not. It's not necessary to
-sort the environment; no program should rely on it being sorted.
-@end ignore
-
@item
If the @code{cd} builtin finds a directory to change to
using @code{$CDPATH}, the
Assignment statements preceding @sc{POSIX.2} @code{special} builtins
persist in the shell environment after the builtin completes.
+@item
+The @code{export} and @code{readonly} builtin commands display their
+output in the format required by @sc{POSIX.2}.
+
@end enumerate
There is other @sc{POSIX.2} behavior that Bash does not implement.
kill -l [@var{sigspec}]
@end example
Send a signal specified by @var{sigspec} or @var{signum} to the process
-named by @var{jobspec}. @var{sigspec} is either a signal name such as
-@code{SIGINT} or a signal number; @var{signum} is a signal number. If
-@var{sigspec} and @var{signum} are not present, @code{SIGTERM} is used.
+named by @var{jobspec}.
+@var{sigspec} is either a signal name such as @code{SIGINT} (with or without
+the @code{SIG} prefix) or a signal number; @var{signum} is a signal number.
+If @var{sigspec} and @var{signum} are not present, @code{SIGTERM} is used.
The @samp{-l} option lists the signal names, or the signal name
corresponding to @var{sigspec}.
This variable controls how the shell interacts with the user and
job control. If this variable exists then single word simple
commands without redirects are treated as candidates for resumption
-of an existing job. There is no ambiguity allowed; if you have
-more than one job beginning with the string that you have typed, then
+of an existing job. There is no ambiguity allowed; if there is
+more than one job beginning with the string typed, then
the most recently accessed job will be selected.
The name of a stopped job, in this context, is the command line
used to start it. If this variable is set to the value @samp{exact},
@sc{OS/2}, Windows 95, and Windows @sc{NT}.
@menu
-* Basic Installation:: Generic installation instructions.
+* Basic Installation:: Installation instructions.
* Compilers and Options:: How to set special options for various
systems.
@cindex Bash installation
@cindex Bash configuration
-These are generic installation instructions for Bash.
+These are installation instructions for Bash.
The @code{configure} shell script attempts to guess correct
values for various system-dependent variables used during
by a program called Autoconf. You only need
@file{configure.in} if you want to change it or regenerate
@code{configure} using a newer version of Autoconf. If
-you do this, make sure you are using Autoconf version 2.9 or
-newer.
+you do this, make sure you are using Autoconf version 2.10 or
+newer.
+
+If you need to change @file{configure.in} or regenerate
+@code{configure}, you will need to create two files:
+@file{_distribution} and @file{_patchlevel}. @file{_distribution}
+should contain the major and minor version numbers of the Bash
+distribution, for example @samp{2.01}. @file{_patchlevel} should
+contain the patch level of the Bash distribution, @samp{0} for
+example. The script @file{support/mkconffiles} has been provided
+to automate the creation of these files.
The simplest way to compile Bash is:
@samp{--with-} options that the Bash @code{configure} recognizes.
@table @code
+@item --with-afs
+Define if you are using the Andrew File System from Transarc.
+
+@item --with-curses
+Use the curses library instead of the termcap library. This should
+be supplied if your system has an inadequate or incomplete termcap
+database.
+
+@item --with-glibc-malloc
+Use the @sc{GNU} libc version of @code{malloc} in
+@file{lib/malloc/gmalloc.c}. This is somewhat slower than the
+default @code{malloc}, but wastes considerably less space.
+
@item --with-gnu-malloc
Use the @sc{GNU} version of
@code{malloc} in @file{lib/malloc/malloc.c}. This is not the same
derived from the 4.2 @sc{BSD} @code{malloc}. This @code{malloc} is
very fast, but wastes a lot of space. This option is enabled by
default. The @file{NOTES} file contains a list of systems for
-which this should be turned off.
-
-@item --with-glibc-malloc
-Use the @sc{GNU} libc version of @code{malloc} in
-@file{lib/malloc/gmalloc.c}. This is somewhat slower than the
-default @code{malloc}, but wastes considerably less space.
-
-@item --with-afs
-Define if you are using the Andrew File System from Transarc.
+which this should be turned off, and @code{configure} disables this
+option automatically for a number of systems.
@item --with-purify
Define this to use the Purify memory allocation checker from Pure
necessary support.
@table @code
-@item --enable-job-control
-This enables job control features, if the @sc{OS} supports them.
-
@item --enable-alias
Allow alias expansion and include the @code{alias} and @code{unalias}
builtins.
-@item --enable-readline
-Include support for command-line editing and history with the Bash
-version of the Readline library.
-
-@item --enable-history
-Include command history and the @code{fc} and @code{history}
-builtin commands.
+@item --enable-array-variables
+Include support for one-dimensional array shell variables.
@item --enable-bang-history
Include support for @code{csh}-like history substitution.
+@item --enable-brace-expansion
+Include @code{csh}-like brace expansion
+( @code{b@{a,b@}c} @expansion{} @code{bac bbc} ).
+
+@item --enable-command-timing
+Include support for recognizing @code{time} as a reserved word and for
+displaying timing statistics for the pipeline following @code{time}. This
+allows pipelines as well as shell builtins and functions to be timed.
+
@item --enable-directory-stack
Include support for a @code{csh}-like directory stack and the
@code{pushd}, @code{popd}, and @code{dirs} builtins.
-@item --enable-restricted
-Include support for a @dfn{restricted shell}. If this is enabled, Bash,
-when called as @code{rbash}, enters a restricted mode. See
-@ref{The Restricted Shell}, for a description of restricted mode.
+@item --enable-disabled-builtins
+Allow builtin commands to be invoked via @samp{builtin xxx}
+even after @code{xxx} has been disabled using @samp{enable -n xxx}.
+See @ref{Bash Builtins}, for details of the @code{builtin} and
+@code{enable} builtin commands.
+
+@item --enable-dparen-arithmetic
+Include support for the @code{ksh} @code{((@dots{}))} command.
+
+@item --enable-help-builtin
+Include the @code{help} builtin, which displays help on shell builtins and
+variables.
+
+@item --enable-history
+Include command history and the @code{fc} and @code{history}
+builtin commands.
+
+@item --enable-job-control
+This enables job control features, if the @sc{OS} supports them.
@item --enable-process-substitution
This enables process substitution (@pxref{Process Substitution}) if
in the @code{$PS1}, @code{$PS2}, @code{$PS3}, and @code{$PS4} prompt
strings.
+@item --enable-readline
+Include support for command-line editing and history with the Bash
+version of the Readline library.
+
+@item --enable-restricted
+Include support for a @dfn{restricted shell}. If this is enabled, Bash,
+when called as @code{rbash}, enters a restricted mode. See
+@ref{The Restricted Shell}, for a description of restricted mode.
+
@item --enable-select
Include the @code{ksh} @code{select} builtin, which allows the
generation of simple menus.
-@item --enable-help-builtin
-Include the @code{help} builtin, which displays help on shell builtins and
-variables.
-
-@item --enable-array-variables
-Include support for one-dimensional array shell variables.
-
-@item --enable-dparen-arithmetic
-Include support for the @code{ksh} @code{((@dots{}))} command.
-
-@item --enable-brace-expansion
-Include @code{csh}-like brace expansion
-( @code{b@{a,b@}c} @expansion{} @code{bac bbc} ).
-
-@item --enable-disabled-builtins
-Allow builtin commands to be invoked via @samp{builtin xxx}
-even after @code{xxx} has been disabled using @samp{enable -n xxx}.
-See @ref{Bash Builtins}, for details of the @code{builtin} and
-@code{enable} builtin commands.
-
-@item --enable-command-timing
-Include support for recognizing @code{time} as a reserved word and for
-displaying timing statistics for the pipeline following @code{time}. This
-allows pipelines as well as shell builtins and functions to be timed.
-
@item --enable-usg-echo-default
Make the @code{echo} builtin expand backslash-escaped characters by default,
without requiring the @samp{-e} option. This makes the Bash @code{echo}
Once you have determined that a bug actually exists, use the
@code{bashbug} command to submit a bug report.
-If you have a fix, you are welcome to mail that as well!
+If you have a fix, you are encouraged to mail that as well!
Suggestions and `philosophical' bug reports may be mailed
to @code{bug-bash@@prep.ai.MIT.Edu} or posted to the Usenet
newsgroup @code{gnu.bash.bug}.
projects / platform / upstream / bash.git / blobdiff