diff options
Diffstat (limited to 'doc/bashref.texi')
| -rw-r--r-- | doc/bashref.texi | 7931 |
1 files changed, 7931 insertions, 0 deletions
diff --git a/doc/bashref.texi b/doc/bashref.texi new file mode 100644 index 0000000..bf8e3d0 --- /dev/null +++ b/doc/bashref.texi @@ -0,0 +1,7931 @@ +\input texinfo.tex @c -*- texinfo -*- +@c %**start of header +@setfilename bashref.info +@settitle Bash Reference Manual +@c %**end of header + +@setchapternewpage odd + +@include version.texi + +@copying +This text is a brief description of the features that are present in +the Bash shell (version @value{VERSION}, @value{UPDATED}). + +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--2009 Free Software Foundation, Inc. + +Permission is granted to make and distribute verbatim copies of +this manual provided the copyright notice and this permission notice +are preserved on all copies. + +@quotation +Permission is granted to copy, distribute and/or modify this document +under the terms of the GNU Free Documentation License, Version 1.3 or +any later version published by the Free Software Foundation; with no +Invariant Sections, with the Front-Cover texts being ``A GNU Manual'', +and with the Back-Cover Texts as in (a) below. A copy of the license is +included in the section entitled ``GNU Free Documentation License''. + +(a) The FSF's Back-Cover Text is: You are free to copy and modify +this GNU manual. Buying copies from GNU Press supports the FSF in +developing GNU and promoting software freedom.'' + +@end quotation +@end copying + +@defcodeindex bt +@defcodeindex rw +@set BashFeatures + +@dircategory Basics +@direntry +* Bash: (bash). The GNU Bourne-Again SHell. +@end direntry + +@finalout + +@titlepage +@title Bash Reference Manual +@subtitle Reference Documentation for Bash +@subtitle Edition @value{EDITION}, for @code{Bash} Version @value{VERSION}. +@subtitle @value{UPDATED-MONTH} +@author Chet Ramey, Case Western Reserve University +@author Brian Fox, Free Software Foundation + +@page +@vskip 0pt plus 1filll +@insertcopying + +@sp 1 +Published by the Free Software Foundation @* +59 Temple Place, Suite 330, @* +Boston, MA 02111-1307 @* +USA @* + +@end titlepage + +@contents + +@ifnottex +@node Top, Introduction, (dir), (dir) +@top Bash Features + +This text is a brief description of the features that are present in +the Bash shell (version @value{VERSION}, @value{UPDATED}). + +This is Edition @value{EDITION}, last updated @value{UPDATED}, +of @cite{The GNU Bash Reference Manual}, +for @code{Bash}, Version @value{VERSION}. + +Bash contains features that appear in other popular shells, and some +features that only appear in Bash. Some of the shells that Bash has +borrowed concepts from are the Bourne Shell (@file{sh}), the Korn Shell +(@file{ksh}), and the C-shell (@file{csh} and its successor, +@file{tcsh}). The following menu breaks the features up into +categories based upon which one of these other shells inspired the +feature. + +This manual is meant as a brief introduction to features found in +Bash. The Bash manual page should be used as the definitive +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:: What job control is and how Bash allows you + to use it. +* Command Line Editing:: Chapter describing the command line + editing features. +* Using History Interactively:: Command History Expansion +* 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. +* GNU Free Documentation License:: Copying and sharing this documentation. +* Indexes:: Various indexes for this manual. +@end menu +@end ifnottex + +@node Introduction +@chapter Introduction +@menu +* What is Bash?:: A short description of Bash. +* What is a shell?:: A brief introduction to shells. +@end menu + +@node What is Bash? +@section What is Bash? + +Bash is the shell, or command language interpreter, +for the @sc{gnu} operating system. +The name is an acronym for the @samp{Bourne-Again SHell}, +a pun on Stephen Bourne, the author of the direct ancestor of +the current Unix shell @code{sh}, +which appeared in the Seventh Edition Bell Labs Research version +of Unix. + +Bash is largely compatible with @code{sh} and incorporates useful +features from the Korn shell @code{ksh} and the C shell @code{csh}. +It is intended to be a conformant implementation of the @sc{ieee} +@sc{posix} Shell and Tools portion of the @sc{ieee} @sc{posix} +specification (@sc{ieee} Standard 1003.1). +It offers functional improvements over @code{sh} for both interactive and +programming use. + +While the @sc{gnu} operating system provides other shells, including +a version of @code{csh}, Bash is the default shell. +Like other @sc{gnu} software, Bash is quite portable. It currently runs +on nearly every version of Unix and a few other operating systems @minus{} +independently-supported ports exist for @sc{ms-dos}, @sc{os/2}, +and Windows platforms. + +@node What is a shell? +@section What is a shell? + +At its base, a shell is simply a macro processor that executes +commands. The term macro processor means functionality where text +and symbols are expanded to create larger expressions. + +A Unix shell is both a command interpreter and a programming +language. As a command interpreter, the shell provides the user +interface to the rich set of @sc{gnu} utilities. The programming +language features allow these utilities to be combined. +Files containing commands can be created, and become +commands themselves. These new commands have the same status as +system commands in directories such as @file{/bin}, allowing users +or groups to establish custom environments to automate their common +tasks. + +Shells may be used interactively or non-interactively. In +interactive mode, they accept input typed from the keyboard. +When executing non-interactively, shells execute commands read +from a file. + +A shell allows execution of @sc{gnu} commands, both synchronously and +asynchronously. +The shell waits for synchronous commands to complete before accepting +more input; asynchronous commands continue to execute in parallel +with the shell while it reads and executes additional commands. +The @dfn{redirection} constructs permit +fine-grained control of the input and output of those commands. +Moreover, the shell allows control over the contents of commands' +environments. + +Shells also provide a small set of built-in +commands (@dfn{builtins}) implementing functionality impossible +or inconvenient to obtain via separate utilities. +For example, @code{cd}, @code{break}, @code{continue}, and +@code{exec}) cannot be implemented outside of the shell because +they directly manipulate the shell itself. +The @code{history}, @code{getopts}, @code{kill}, or @code{pwd} +builtins, among others, could be implemented in separate utilities, +but they are more convenient to use as builtin commands. +All of the shell builtins are described in +subsequent sections. + +While executing commands is essential, most of the power (and +complexity) of shells is due to their embedded programming +languages. Like any high-level language, the shell provides +variables, flow control constructs, quoting, and functions. + +Shells offer features geared specifically for +interactive use rather than to augment the programming language. +These interactive features include job control, command line +editing, command history and aliases. Each of these features is +described in this manual. + +@node Definitions +@chapter Definitions +These definitions are used throughout the remainder of this manual. + +@table @code + +@item POSIX +@cindex POSIX +A family of open system standards based on Unix. Bash +is primarily concerned with the Shell and Utilities portion of the +@sc{posix} 1003.1 standard. + +@item blank +A space or tab character. + +@item builtin +@cindex builtin +A command that is implemented internally by the shell itself, rather +than by an executable program somewhere in the file system. + +@item control operator +@cindex control operator +A @code{token} that performs a control function. It is a @code{newline} +or one of the following: +@samp{||}, @samp{&&}, @samp{&}, @samp{;}, @samp{;;}, +@samp{|}, @samp{|&}, @samp{(}, or @samp{)}. + +@item exit status +@cindex exit status +The value returned by a command to its caller. The value is restricted +to eight bits, so the maximum value is 255. + +@item field +@cindex field +A unit of text that is the result of one of the shell expansions. After +expansion, when executing a command, the resulting fields are used as +the command name and arguments. + +@item filename +@cindex filename +A string of characters used to identify a file. + +@item job +@cindex job +A set of processes comprising a pipeline, and any processes descended +from it, that are all in the same process group. + +@item job control +@cindex job control +A mechanism by which users can selectively stop (suspend) and restart +(resume) execution of processes. + +@item metacharacter +@cindex metacharacter +A character that, when unquoted, separates words. A metacharacter is +a @code{blank} or one of the following characters: +@samp{|}, @samp{&}, @samp{;}, @samp{(}, @samp{)}, @samp{<}, or +@samp{>}. + +@item name +@cindex name +@cindex identifier +A @code{word} consisting solely of letters, numbers, and underscores, +and beginning with a letter or underscore. @code{Name}s are used as +shell variable and function names. +Also referred to as an @code{identifier}. + +@item operator +@cindex operator, shell +A @code{control operator} or a @code{redirection operator}. +@xref{Redirections}, for a list of redirection operators. +Operators contain at least one unquoted @code{metacharacter}. + +@item process group +@cindex process group +A collection of related processes each having the same process +group @sc{id}. + +@item process group ID +@cindex process group ID +A unique identifier that represents a @code{process group} +during its lifetime. + +@item reserved word +@cindex reserved word +A @code{word} that has a special meaning to the shell. Most reserved +words introduce shell flow control constructs, such as @code{for} and +@code{while}. + +@item return status +@cindex return status +A synonym for @code{exit status}. + +@item signal +@cindex signal +A mechanism by which a process may be notified by the kernel +of an event occurring in the system. + +@item special builtin +@cindex special builtin +A shell builtin command that has been classified as special by the +@sc{posix} standard. + +@item token +@cindex token +A sequence of characters considered a single unit by the shell. +It is either a @code{word} or an @code{operator}. + +@item word +@cindex word +A sequence of characters treated as a unit by the shell. +Words may not include unquoted @code{metacharacters}. +@end table + +@node Basic Shell Features +@chapter Basic Shell Features +@cindex Bourne shell + +Bash is an acronym for @samp{Bourne-Again SHell}. +The Bourne shell is +the traditional Unix shell originally written by Stephen Bourne. +All of the Bourne shell builtin commands are available in Bash, +The rules for evaluation and quoting are taken from the @sc{posix} +specification for the `standard' Unix shell. + +This chapter briefly summarizes the shell's `building blocks': +commands, control structures, shell functions, shell @i{parameters}, +shell expansions, +@i{redirections}, which are a way to direct input and output from +and to named files, and how the shell executes commands. + +@menu +* Shell Syntax:: What your input means to the shell. +* Shell Commands:: The types of commands you can use. +* Shell Functions:: Grouping commands by name. +* Shell Parameters:: How the shell stores values. +* Shell Expansions:: How Bash expands parameters and the various + expansions available. +* Redirections:: A way to control where input and output go. +* Executing Commands:: What happens when you run a command. +* Shell Scripts:: Executing files of shell commands. +@end menu + +@node Shell Syntax +@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 + +When the shell reads input, it proceeds through a +sequence of operations. If the input indicates the beginning of a +comment, the shell ignores the comment symbol (@samp{#}), and the rest +of that line. + +Otherwise, roughly speaking, the shell reads its input and +divides the input into words and operators, employing the quoting rules +to select which meanings to assign various words and characters. + +The shell then parses these tokens into commands and other constructs, +removes the special meaning of certain words or characters, expands +others, redirects input and output as needed, executes the specified +command, waits for the command's exit status, and makes that exit status +available for further inspection or processing. + +@node Shell Operation +@subsection Shell Operation + +The following is a brief description of the shell's operation when it +reads and executes a command. Basically, the shell does the +following: + +@enumerate +@item +Reads its input from a file (@pxref{Shell Scripts}), from a string +supplied as an argument to the @option{-c} invocation option +(@pxref{Invoking Bash}), or from the user's terminal. + +@item +Breaks the input into words and operators, obeying the quoting rules +described in @ref{Quoting}. These tokens are separated by +@code{metacharacters}. Alias expansion is performed by this step +(@pxref{Aliases}). + +@item +Parses the tokens into simple and compound commands +(@pxref{Shell Commands}). + +@item +Performs the various shell expansions (@pxref{Shell Expansions}), breaking +the expanded tokens into lists of filenames (@pxref{Filename Expansion}) +and commands and arguments. + +@item +Performs any necessary redirections (@pxref{Redirections}) and removes +the redirection operators and their operands from the argument list. + +@item +Executes the command (@pxref{Executing Commands}). + +@item +Optionally waits for the command to complete and collects its exit +status (@pxref{Exit Status}). + +@end enumerate + +@node Quoting +@subsection Quoting +@cindex quoting +@menu +* Escape Character:: How to remove the special meaning from a single + character. +* Single Quotes:: How to inhibit all interpretation of a sequence + of characters. +* 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 + +Quoting is used to remove the special meaning of certain +characters or words to the shell. Quoting can be used to +disable special treatment for special characters, to prevent +reserved words from being recognized as such, and to prevent +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 +(@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. + +There are three quoting mechanisms: the +@var{escape character}, single quotes, and double quotes. + +@node Escape Character +@subsubsection Escape Character +A non-quoted backslash @samp{\} is the Bash escape character. +It preserves the literal value of the next character that follows, +with the exception of @code{newline}. If a @code{\newline} pair +appears, and the backslash itself is not quoted, the @code{\newline} +is treated as a line continuation (that is, it is removed from +the input stream and effectively ignored). + +@node Single Quotes +@subsubsection Single Quotes + +Enclosing characters in single quotes (@samp{'}) preserves the literal value +of each character within the quotes. A single quote may not occur +between single quotes, even when preceded by a backslash. + +@node Double Quotes +@subsubsection Double Quotes + +Enclosing characters in double quotes (@samp{"}) preserves the literal value +of all characters within the quotes, with the exception of +@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 +the following characters: +@samp{$}, @samp{`}, @samp{"}, @samp{\}, or @code{newline}. +Within double quotes, backslashes that are followed by one of these +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. +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}). + +@node ANSI-C Quoting +@subsubsection ANSI-C Quoting +@cindex quoting, ANSI + +Words of the form @code{$'@var{string}'} are treated specially. The +word expands to @var{string}, with backslash-escaped characters replaced +as specified by the ANSI C standard. Backslash escape sequences, if +present, are decoded as follows: + +@table @code +@item \a +alert (bell) +@item \b +backspace +@item \e +@itemx \E +an escape character (not ANSI C) +@item \f +form feed +@item \n +newline +@item \r +carriage return +@item \t +horizontal tab +@item \v +vertical tab +@item \\ +backslash +@item \' +single quote +@item \" +double quote +@item \@var{nnn} +the eight-bit character whose value is the octal value @var{nnn} +(one to three digits) +@item \x@var{HH} +the eight-bit character whose value is the hexadecimal value @var{HH} +(one or two hex digits) +@item \c@var{x} +a control-@var{x} character +@end table + +@noindent +The expanded result is single-quoted, as if the dollar sign had not +been present. + +@node Locale Translation +@subsubsection Locale-Specific Translation +@cindex localization +@cindex internationalization +@cindex native languages +@cindex translation, native languages + +A double-quoted string preceded by a dollar sign (@samp{$}) will cause +the string to be translated according to the current locale. +If the current locale is @code{C} or @code{POSIX}, the dollar sign +is ignored. +If the string is translated and replaced, the replacement is +double-quoted. + +@vindex LC_MESSAGES +@vindex TEXTDOMAIN +@vindex TEXTDOMAINDIR +Some systems use the message catalog selected by the @env{LC_MESSAGES} +shell variable. Others create the name of the message catalog from the +value of the @env{TEXTDOMAIN} shell variable, possibly adding a +suffix of @samp{.mo}. If you use the @env{TEXTDOMAIN} variable, you +may need to set the @env{TEXTDOMAINDIR} variable to the location of +the message catalog files. Still others use both variables in this +fashion: +@env{TEXTDOMAINDIR}/@env{LC_MESSAGES}/LC_MESSAGES/@env{TEXTDOMAIN}.mo. + +@node Comments +@subsection Comments +@cindex comments, shell + +In a non-interactive shell, or an interactive shell in which the +@code{interactive_comments} option to the @code{shopt} +builtin is enabled (@pxref{The Shopt Builtin}), +a word beginning with @samp{#} +causes that word and all remaining characters on that line to +be ignored. An interactive shell without the @code{interactive_comments} +option enabled does not allow comments. The @code{interactive_comments} +option is on by default in interactive shells. +@xref{Interactive Shells}, for a description of what makes +a shell interactive. + +@node Shell Commands +@section Shell Commands +@cindex commands, shell + +A simple shell command such as @code{echo a b c} consists of the command +itself followed by arguments, separated by spaces. + +More complex shell commands are composed of simple commands arranged together +in a variety of ways: in a pipeline in which the output of one command +becomes the input of a second, in a loop or conditional construct, or in +some other grouping. + +@menu +* Simple Commands:: The most common type of command. +* Pipelines:: Connecting the input and output of several + commands. +* Lists:: How to execute commands sequentially. +* Compound Commands:: Shell commands for control flow. +* Coprocesses:: Two-way communication between commands. +@end menu + +@node Simple Commands +@subsection Simple Commands +@cindex commands, simple + +A simple command is the kind of command encountered most often. +It's just a sequence of words separated by @code{blank}s, terminated +by one of the shell's control operators (@pxref{Definitions}). The +first word generally specifies a command to be executed, with the +rest of the words being that command's arguments. + +The return status (@pxref{Exit Status}) of a simple command is +its exit status as provided +by the @sc{posix} 1003.1 @code{waitpid} function, or 128+@var{n} if +the command was terminated by signal @var{n}. + +@node Pipelines +@subsection Pipelines +@cindex pipeline +@cindex commands, pipelines + +A @code{pipeline} is a sequence of simple commands separated by one of +the control operators @samp{|} or @samp{|&}. + +@rwindex time +@rwindex ! +@cindex command timing +The format for a pipeline is +@example +[@code{time} [@code{-p}]] [@code{!}] @var{command1} [ [@code{|} or @code{|&}] @var{command2} @dots{}] +@end example + +@noindent +The output of each command in the pipeline is connected via a pipe +to the input of the next command. +That is, each command reads the previous command's output. This +connection is performed before any redirections specified by the +command. + +If @samp{|&} is used, the standard error of @var{command1} is connected to +@var{command2}'s standard input through the pipe; it is shorthand for +@code{2>&1 |}. This implicit redirection of the standard error is +performed after any redirections specified by the command. + +The reserved word @code{time} causes timing statistics +to be printed for the pipeline once it finishes. +The statistics currently consist of elapsed (wall-clock) time and +user and system time consumed by the command's execution. +The @option{-p} option changes the output format to that specified +by @sc{posix}. +The @env{TIMEFORMAT} variable may be set to a format string that +specifies how the timing information should be displayed. +@xref{Bash Variables}, for a description of the available formats. +The use of @code{time} as a reserved word permits the timing of +shell builtins, shell functions, and pipelines. An external +@code{time} command cannot time these easily. + +If the pipeline is not executed asynchronously (@pxref{Lists}), the +shell waits for all commands in the pipeline to complete. + +Each command in a pipeline is executed in its own subshell +(@pxref{Command Execution Environment}). The exit +status of a pipeline is the exit status of the last command in the +pipeline, unless the @code{pipefail} option is enabled +(@pxref{The Set Builtin}). +If @code{pipefail} is enabled, the pipeline's return status is the +value of the last (rightmost) command to exit with a non-zero status, +or zero if all commands exit successfully. +If the reserved word @samp{!} precedes the pipeline, the +exit status is the logical negation of the exit status as described +above. +The shell waits for all commands in the pipeline to terminate before +returning a value. + +@node Lists +@subsection Lists of Commands +@cindex commands, lists + +A @code{list} is a sequence of one or more pipelines separated by one +of the operators @samp{;}, @samp{&}, @samp{&&}, or @samp{||}, +and optionally terminated by one of @samp{;}, @samp{&}, or a +@code{newline}. + +Of these list operators, @samp{&&} and @samp{||} +have equal precedence, followed by @samp{;} and @samp{&}, +which have equal precedence. + +A sequence of one or more newlines may appear in a @code{list} +to delimit commands, equivalent to a semicolon. + +If a command is terminated by the control operator @samp{&}, +the shell executes the command asynchronously in a subshell. +This is known as executing the command in the @var{background}. +The shell does not wait for the command to finish, and the return +status is 0 (true). +When job control is not active (@pxref{Job Control}), +the standard input for asynchronous commands, in the absence of any +explicit redirections, is redirected from @code{/dev/null}. + +Commands separated by a @samp{;} are executed sequentially; the shell +waits for each command to terminate in turn. The return status is the +exit status of the last command executed. + +@sc{and} and @sc{or} lists are sequences of one or more pipelines +separated by the control operators @samp{&&} and @samp{||}, +respectively. @sc{and} and @sc{or} lists are executed with left +associativity. + +An @sc{and} list has the form +@example +@var{command1} && @var{command2} +@end example + +@noindent +@var{command2} is executed if, and only if, @var{command1} +returns an exit status of zero. + +An @sc{or} list has the form +@example +@var{command1} || @var{command2} +@end example + +@noindent +@var{command2} is executed if, and only if, @var{command1} +returns a non-zero exit status. + +The return status of +@sc{and} and @sc{or} lists is the exit status of the last command +executed in the list. + +@node Compound Commands +@subsection Compound Commands +@cindex commands, compound + +@menu +* Looping Constructs:: Shell commands for iterative action. +* Conditional Constructs:: Shell commands for conditional execution. +* Command Grouping:: Ways to group commands. +@end menu + +Compound commands are the shell programming constructs. +Each construct begins with a reserved word or control operator and is +terminated by a corresponding reserved word or operator. +Any redirections (@pxref{Redirections}) associated with a compound command +apply to all commands within that compound command unless explicitly overridden. + +Bash provides looping constructs, conditional commands, and mechanisms +to group commands and execute them as a unit. + +@node Looping Constructs +@subsubsection Looping Constructs +@cindex commands, looping + +Bash supports the following looping constructs. + +Note that wherever a @samp{;} appears in the description of a +command's syntax, it may be replaced with one or more newlines. + +@table @code +@item until +@rwindex until +@rwindex do +@rwindex done +The syntax of the @code{until} command is: +@example +until @var{test-commands}; do @var{consequent-commands}; done +@end example +Execute @var{consequent-commands} as long as +@var{test-commands} has an exit status which is not zero. +The return status is the exit status of the last command executed +in @var{consequent-commands}, or zero if none was executed. + +@item while +@rwindex while +The syntax of the @code{while} command is: +@example +while @var{test-commands}; do @var{consequent-commands}; done +@end example + +Execute @var{consequent-commands} as long as +@var{test-commands} has an exit status of zero. +The return status is the exit status of the last command executed +in @var{consequent-commands}, or zero if none was executed. + +@item for +@rwindex for +The syntax of the @code{for} command is: + +@example +for @var{name} [ [in [@var{words} @dots{}] ] ; ] do @var{commands}; done +@end example +Expand @var{words}, and execute @var{commands} once for each member +in the resultant list, with @var{name} bound to the current member. +If @samp{in @var{words}} is not present, the @code{for} command +executes the @var{commands} once for each positional parameter that is +set, as if @samp{in "$@@"} had been specified +(@pxref{Special Parameters}). +The return status is the exit status of the last command that executes. +If there are no items in the expansion of @var{words}, no commands are +executed, and the return status is zero. + +An alternate form of the @code{for} command is also supported: + +@example +for (( @var{expr1} ; @var{expr2} ; @var{expr3} )) ; do @var{commands} ; done +@end example +First, the arithmetic expression @var{expr1} is evaluated according +to the rules described below (@pxref{Shell Arithmetic}). +The arithmetic expression @var{expr2} is then evaluated repeatedly +until it evaluates to zero. +Each time @var{expr2} evaluates to a non-zero value, @var{commands} are +executed and the arithmetic expression @var{expr3} is evaluated. +If any expression is omitted, it behaves as if it evaluates to 1. +The return value is the exit status of the last command in @var{list} +that is executed, or false if any of the expressions is invalid. + +@end table + +The @code{break} and @code{continue} builtins (@pxref{Bourne Shell Builtins}) +may be used to control loop execution. + +@node Conditional Constructs +@subsubsection Conditional Constructs +@cindex commands, conditional + +@table @code +@item if +@rwindex if +@rwindex then +@rwindex else +@rwindex elif +@rwindex fi +The syntax of the @code{if} command is: + +@example +if @var{test-commands}; then + @var{consequent-commands}; +[elif @var{more-test-commands}; then + @var{more-consequents};] +[else @var{alternate-consequents};] +fi +@end example + +The @var{test-commands} list is executed, and if its return status is zero, +the @var{consequent-commands} list is executed. +If @var{test-commands} returns a non-zero status, each @code{elif} list +is executed in turn, and if its exit status is zero, +the corresponding @var{more-consequents} is executed and the +command completes. +If @samp{else @var{alternate-consequents}} is present, and +the final command in the final @code{if} or @code{elif} clause +has a non-zero exit status, then @var{alternate-consequents} is executed. +The return status is the exit status of the last command executed, or +zero if no condition tested true. + +@item case +@rwindex case +@rwindex in +@rwindex esac +The syntax of the @code{case} command is: + +@example +@code{case @var{word} in [ [(] @var{pattern} [| @var{pattern}]@dots{}) @var{command-list} ;;]@dots{} esac} +@end example + +@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{The Shopt Builtin}) +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 +as a @var{clause}. + +Each clause must be terminated with @samp{;;}, @samp{;&}, or @samp{;;&}. +The @var{word} undergoes tilde expansion, parameter expansion, command +substitution, arithmetic expansion, and quote removal before matching is +attempted. Each @var{pattern} undergoes tilde expansion, parameter +expansion, command substitution, and arithmetic expansion. + +There may be an arbitrary number of @code{case} clauses, each terminated +by a @samp{;;}, @samp{;&}, or @samp{;;&}. +The first pattern that matches determines the +command-list that is executed. + +Here is an example using @code{case} in a script that could be used to +describe one interesting feature of an animal: + +@example +echo -n "Enter the name of an animal: " +read ANIMAL +echo -n "The $ANIMAL has " +case $ANIMAL in + horse | dog | cat) echo -n "four";; + man | kangaroo ) echo -n "two";; + *) echo -n "an unknown number of";; +esac +echo " legs." +@end example + +@noindent + +If the @samp{;;} operator is used, no subsequent matches are attempted after +the first pattern match. +Using @samp{;&} in place of @samp{;;} causes execution to continue with +the @var{command-list} associated with the next clause, if any. +Using @samp{;;&} in place of @samp{;;} causes the shell to test the patterns +in the next clause, if any, and execute any associated @var{command-list} +on a successful match. + +The return status is zero if no @var{pattern} is matched. Otherwise, the +return status is the exit status of the @var{command-list} executed. + +@item select +@rwindex select + +The @code{select} construct allows the easy generation of menus. +It has almost the same syntax as the @code{for} command: + +@example +select @var{name} [in @var{words} @dots{}]; do @var{commands}; done +@end example + +The list of words following @code{in} is expanded, generating a list +of items. The set of expanded words is printed on the standard +error output stream, each preceded by a number. If the +@samp{in @var{words}} is omitted, the positional parameters are printed, +as if @samp{in "$@@"} had been specified. +The @env{PS3} prompt is then displayed and a line is read from the +standard input. +If the line consists of a number corresponding to one of the displayed +words, then the value of @var{name} is set to that word. +If the line is empty, the words and prompt are displayed again. +If @code{EOF} is read, the @code{select} command completes. +Any other value read causes @var{name} to be set to null. +The line read is saved in the variable @env{REPLY}. + +The @var{commands} are executed after each selection until a +@code{break} command is executed, at which +point the @code{select} command completes. + +Here is an example that allows the user to pick a filename from the +current directory, and displays the name and index of the file +selected. + +@example +select fname in *; +do + echo you picked $fname \($REPLY\) + break; +done +@end example + +@item ((@dots{})) +@example +(( @var{expression} )) +@end example + +The arithmetic @var{expression} is evaluated according to the rules +described below (@pxref{Shell Arithmetic}). +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 +let "@var{expression}" +@end example +@noindent +@xref{Bash Builtins}, for a full description of the @code{let} builtin. + +@item [[@dots{}]] +@rwindex [[ +@rwindex ]] +@example +[[ @var{expression} ]] +@end example + +Return a status of 0 or 1 depending on the evaluation of +the conditional expression @var{expression}. +Expressions are composed of the primaries described below in +@ref{Bash Conditional Expressions}. +Word splitting and filename expansion are not performed on the words +between the @samp{[[} and @samp{]]}; tilde expansion, parameter and +variable expansion, arithmetic expansion, command substitution, process +substitution, and quote removal are performed. +Conditional operators such as @samp{-f} must be unquoted to be recognized +as primaries. + +When used with @samp{[[}, The @samp{<} and @samp{>} operators sort +lexicographically using the current locale. + +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{The Shopt Builtin}) +is enabled, the match is performed without regard to the case +of alphabetic characters. +The return value is 0 if the string matches (@samp{==}) or does not +match (@samp{!=})the pattern, and 1 otherwise. +Any part of the pattern may be quoted to force it to be matched as a +string. + +An additional binary operator, @samp{=~}, is available, with the same +precedence as @samp{==} and @samp{!=}. +When it is used, the string to the right of the operator is considered +an extended regular expression and matched accordingly (as in @i{regex}3)). +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{nocasematch} +(see the description of @code{shopt} in @ref{The Shopt Builtin}) +is enabled, the match is performed without regard to the case +of alphabetic characters. +Any part of the pattern may be quoted to force it to be matched as a +string. +Substrings matched by parenthesized subexpressions within the regular +expression are saved in the array variable @code{BASH_REMATCH}. +The element of @code{BASH_REMATCH} with index 0 is the portion of the string +matching the entire regular expression. +The element of @code{BASH_REMATCH} with index @var{n} is the portion of the +string matching the @var{n}th parenthesized subexpression. + +Expressions may be combined using the following operators, listed +in decreasing order of precedence: + +@table @code +@item ( @var{expression} ) +Returns the value of @var{expression}. +This may be used to override the normal precedence of operators. + +@item ! @var{expression} +True if @var{expression} is false. + +@item @var{expression1} && @var{expression2} +True if both @var{expression1} and @var{expression2} are true. + +@item @var{expression1} || @var{expression2} +True if either @var{expression1} or @var{expression2} is true. +@end table +@noindent +The @code{&&} and @code{||} operators do not evaluate @var{expression2} if the +value of @var{expression1} is sufficient to determine the return +value of the entire conditional expression. + +@end table + +@node Command Grouping +@subsubsection Grouping Commands +@cindex commands, grouping + +Bash provides two ways to group a list of commands to be executed +as a unit. When commands are grouped, redirections may be applied +to the entire command list. For example, the output of all the +commands in the list may be redirected to a single stream. + +@table @code +@item () +@example +( @var{list} ) +@end example + +Placing a list of commands between parentheses causes a subshell +environment to be created (@pxref{Command Execution Environment}), and each +of the commands in @var{list} to be executed in that subshell. Since the +@var{list} is executed in a subshell, variable assignments do not remain in +effect after the subshell completes. + +@item @{@} +@rwindex @{ +@rwindex @} +@example +@{ @var{list}; @} +@end example + +Placing a list of commands between curly braces causes the list to +be executed in the current shell context. No subshell is created. +The semicolon (or newline) following @var{list} is required. +@end table + +In addition to the creation of a subshell, there is a subtle difference +between these two constructs due to historical reasons. The braces +are @code{reserved words}, so they must be separated from the @var{list} +by @code{blank}s or other shell metacharacters. +The parentheses are @code{operators}, and are +recognized as separate tokens by the shell even if they are not separated +from the @var{list} by whitespace. + +The exit status of both of these constructs is the exit status of +@var{list}. + +@node Coprocesses +@subsection Coprocesses +@cindex coprocess + +A @code{coprocess} is a shell command preceded by the @code{coproc} +reserved word. +A coprocess is executed asynchronously in a subshell, as if the command +had been terminated with the @samp{&} control operator, with a two-way pipe +established between the executing shell and the coprocess. + +The format for a coprocess is: +@example +@code{coproc} [@var{NAME}] @var{command} [@var{redirections}] +@end example + +@noindent +This creates a coprocess named @var{NAME}. +If @var{NAME} is not supplied, the default name is @var{COPROC}. +@var{NAME} must not be supplied if @var{command} is a simple +command (@pxref{Simple Commands}); otherwise, it is interpreted as +the first word of the simple command. + +When the coproc is executed, the shell creates an array variable +(@pxref{Arrays}) +named @var{NAME} in the context of the executing shell. +The standard output of @var{command} +is connected via a pipe to a file descriptor in the executing shell, +and that file descriptor is assigned to @var{NAME}[0]. +The standard input of @var{command} +is connected via a pipe to a file descriptor in the executing shell, +and that file descriptor is assigned to @var{NAME}[1]. +This pipe is established before any redirections specified by the +command (@pxref{Redirections}). +The file descriptors can be utilized as arguments to shell commands +and redirections using standard word expansions. + +The process id of the shell spawned to execute the coprocess is +available as the value of the variable @var{NAME}_PID. +The @code{wait} +builtin command may be used to wait for the coprocess to terminate. + +The return status of a coprocess is the exit status of @var{command}. + +@node Shell Functions +@section Shell Functions +@cindex shell function +@cindex functions, shell + +Shell functions are a way to group commands for later execution +using a single name for the group. They are executed just like +a "regular" command. +When the name of a shell function is used as a simple command name, +the list of commands associated with that function name is executed. +Shell functions are executed in the current +shell context; no new process is created to interpret them. + +Functions are declared using this syntax: +@rwindex function +@example +[ @code{function} ] @var{name} () @var{compound-command} [ @var{redirections} ] +@end example + +This defines a shell function named @var{name}. The reserved +word @code{function} is optional. +If the @code{function} reserved +word is supplied, the parentheses are optional. +The @var{body} of the function is the compound command +@var{compound-command} (@pxref{Compound Commands}). +That command is usually a @var{list} enclosed between @{ and @}, but +may be any compound command listed above. +@var{compound-command} is executed whenever @var{name} is specified as the +name of a command. +Any redirections (@pxref{Redirections}) associated with the shell function +are performed when the function is executed. + +A function definition may be deleted using the @option{-f} option to the +@code{unset} builtin (@pxref{Bourne Shell Builtins}). + +The exit status of a function definition is zero unless a syntax error +occurs or a readonly function with the same name already exists. +When executed, the exit status of a function is the exit status of the +last command executed in the body. + +Note that for historical reasons, in the most common usage the curly braces +that surround the body of the function must be separated from the body by +@code{blank}s or newlines. +This is because the braces are reserved words and are only recognized +as such when they are separated from the command list +by whitespace or another shell metacharacter. +Also, when using the braces, the @var{list} must be terminated by a semicolon, +a @samp{&}, or a newline. + +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 expands to the number of +positional parameters is updated to reflect the change. +Special parameter @code{0} is unchanged. +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 these exceptions: +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 @env{DEBUG} and @env{RETURN} traps), +and the @env{ERR} trap is not inherited unless the @code{-o errtrace} +shell option has been enabled. +@xref{Bourne Shell Builtins}, for the description of the +@code{trap} builtin. + +If the builtin command @code{return} +is executed in a function, the function completes and +execution resumes with the next command after the function +call. +Any command associated with the @code{RETURN} trap is executed +before execution resumes. +When a function completes, the values of the +positional parameters and the special parameter @samp{#} +are restored to the values they had prior to the function's +execution. If a numeric argument is given to @code{return}, +that is the function's return status; otherwise the function's +return status is the exit status of the last command executed +before the @code{return}. + +Variables local to the function may be declared with the +@code{local} builtin. These variables are visible only to +the function and the commands it invokes. + +Function names and definitions may be listed with the +@option{-f} option to the @code{declare} or @code{typeset} +builtin commands (@pxref{Bash Builtins}). +The @option{-F} option to @code{declare} or @code{typeset} +will list the function names only +(and optionally the source file and line number, if the @code{extdebug} +shell option is enabled). +Functions may be exported so that subshells +automatically have them defined with the +@option{-f} option to the @code{export} builtin +(@pxref{Bourne Shell Builtins}). +Note that shell functions and variables with the same name may result +in multiple identically-named entries in the environment passed to the +shell's children. +Care should be taken in cases where this may cause a problem. + +Functions may be recursive. No limit is placed on the number of +recursive calls. + +@node Shell Parameters +@section Shell Parameters +@cindex parameters +@cindex variable, shell +@cindex shell variable + +@menu +* Positional Parameters:: The shell's command-line arguments. +* Special Parameters:: Parameters denoted by special characters. +@end menu + +A @var{parameter} is an entity that stores values. +It can be a @code{name}, a number, or one of the special characters +listed below. +A @var{variable} is a parameter denoted by a @code{name}. +A variable has a @var{value} and zero or more @var{attributes}. +Attributes are assigned using the @code{declare} builtin command +(see the description of the @code{declare} builtin in @ref{Bash Builtins}). + +A parameter is set if it has been assigned a value. The null string is +a valid value. Once a variable is set, it may be unset only by using +the @code{unset} builtin command. + +A variable may be assigned to by a statement of the form +@example +@var{name}=[@var{value}] +@end example +@noindent +If @var{value} +is not given, the variable is assigned the null string. All +@var{value}s undergo tilde expansion, parameter and variable expansion, +command substitution, arithmetic expansion, and quote +removal (detailed below). If the variable has its @code{integer} +attribute set, then @var{value} +is evaluated as an arithmetic expression even if the @code{$((@dots{}))} +expansion is not used (@pxref{Arithmetic Expansion}). +Word splitting is not performed, with the exception +of @code{"$@@"} as explained below. +Filename expansion is not performed. +Assignment statements may also appear as arguments to the +@code{alias}, +@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 (for indexed arrays), or added as additional key-value pairs +in an associative array. +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 + +A @var{positional parameter} is a parameter denoted by one or more +digits, other than the single digit @code{0}. Positional parameters are +assigned from the shell's arguments when it is invoked, +and may be reassigned using the @code{set} builtin command. +Positional parameter @code{N} may be referenced as @code{$@{N@}}, or +as @code{$N} when @code{N} consists of a single digit. +Positional parameters may not be assigned to with assignment statements. +The @code{set} and @code{shift} builtins are used to set and +unset them (@pxref{Shell Builtin Commands}). +The positional parameters are +temporarily replaced when a shell function is executed +(@pxref{Shell Functions}). + +When a positional parameter consisting of more than a single +digit is expanded, it must be enclosed in braces. + +@node Special Parameters +@subsection Special Parameters +@cindex parameters, special + +The shell treats several parameters specially. These parameters may +only be referenced; assignment to them is not allowed. + +@vtable @code + +@item * +Expands to the positional parameters, starting from one. When the +expansion occurs within double quotes, it expands to a single word +with the value of each parameter separated by the first character +of the @env{IFS} +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 @env{IFS} is unset, the parameters are separated by spaces. +If @env{IFS} is null, the parameters are joined without intervening +separators. + + +@item @@ +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). + +@item # +Expands to the number of positional parameters in decimal. + +@item ? +Expands to the exit status of the most recently executed foreground +pipeline. + +@item - +(A hyphen.) Expands to the current option flags as specified upon +invocation, by the @code{set} +builtin command, or those set by the shell itself +(such as the @option{-i} option). + +@item $ +Expands to the process @sc{id} of the shell. In a @code{()} subshell, it +expands to the process @sc{id} of the invoking shell, not the subshell. + +@item ! +Expands to the process @sc{id} of the most recently executed background +(asynchronous) command. + +@item 0 +Expands to the name of the shell or shell script. This is set at +shell initialization. If Bash is invoked with a file of commands +(@pxref{Shell Scripts}), @code{$0} is set to the name of that file. +If Bash is started with the @option{-c} option (@pxref{Invoking Bash}), +then @code{$0} is set to the first argument after the string to be +executed, if one is present. Otherwise, it is set +to the filename used to invoke Bash, as given by argument zero. + +@item _ +(An underscore.) +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 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 + +@node Shell Expansions +@section Shell Expansions +@cindex expansion + +Expansion is performed on the command line after it has been split into +@code{token}s. There are seven kinds of expansion performed: +@itemize @bullet +@item brace expansion +@item tilde expansion +@item parameter and variable expansion +@item command substitution +@item arithmetic expansion +@item word splitting +@item filename expansion +@end itemize + +@menu +* Brace Expansion:: Expansion of expressions within braces. +* Tilde Expansion:: Expansion of the ~ character. +* Shell Parameter Expansion:: How Bash expands variables to their values. +* Command Substitution:: Using the output of a command as an argument. +* Arithmetic Expansion:: How to use arithmetic in shell expansions. +* Process Substitution:: A way to write and read to and from a + command. +* Word Splitting:: How the results of expansion are split into separate + arguments. +* Filename Expansion:: A shorthand for specifying filenames matching patterns. +* Quote Removal:: How and when quote characters are removed from + words. +@end menu + +The order of expansions is: brace expansion, tilde expansion, +parameter, variable, and arithmetic expansion and +command substitution +(done in a left-to-right fashion), word splitting, and filename +expansion. + +On systems that can support it, there is an additional expansion +available: @var{process substitution}. This is performed at the +same time as parameter, variable, and arithmetic expansion and +command substitution. + +Only brace expansion, word splitting, and filename expansion +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{"$@{@var{name}[@@]@}"} +(@pxref{Arrays}). + +After all expansions, @code{quote removal} (@pxref{Quote Removal}) +is performed. + +@node Brace Expansion +@subsection Brace Expansion +@cindex brace expansion +@cindex expansion, brace + +Brace expansion is a mechanism by which arbitrary strings may be generated. +This mechanism is similar to +@var{filename expansion} (@pxref{Filename Expansion}), +but the file names generated need not exist. +Patterns to be brace expanded take the form of an optional @var{preamble}, +followed by either a series of comma-separated strings or a seqeunce expression +between a pair of braces, +followed by an optional @var{postscript}. +The preamble is prefixed to each string contained within the braces, and +the postscript is then appended to each resulting string, expanding left +to right. + +Brace expansions may be nested. +The results of each expanded string are not sorted; left to right order +is preserved. +For example, +@example +bash$ echo a@{d,c,b@}e +ade ace abe +@end example + +A sequence expression takes the form @code{@{@var{x}..@var{y}[..@var{incr}]@}}, +where @var{x} and @var{y} are either integers or single characters, +and @var{incr}, an optional increment, is an integer. +When integers are supplied, the expression expands to each number between +@var{x} and @var{y}, inclusive. +Supplied integers may be prefixed with @samp{0} to force each term to have the +same width. When either @var{x} or @var{y} begins with a zero, the shell +attempts to force all generated terms to contain the same number of digits, +zero-padding where necessary. +When characters are supplied, the expression expands to each character +lexicographically between @var{x} and @var{y}, inclusive. Note that +both @var{x} and @var{y} must be of the same type. +When the increment is supplied, it is used as the difference between +each term. The default increment is 1 or -1 as appropriate. + +Brace expansion is performed before any other expansions, +and any characters special to other expansions are preserved +in the result. It is strictly textual. Bash +does not apply any syntactic interpretation to the context of the +expansion or the text between the braces. +To avoid conflicts with parameter expansion, the string @samp{$@{} +is not considered eligible for brace expansion. + +A correctly-formed brace expansion must contain unquoted opening +and closing braces, and at least one unquoted comma or a valid +sequence expression. +Any incorrectly formed brace expansion is left unchanged. + +A @{ or @samp{,} may be quoted with a backslash to prevent its +being considered part of a brace expression. +To avoid conflicts with parameter expansion, the string @samp{$@{} +is not considered eligible for brace expansion. + +This construct is typically used as shorthand when the common +prefix of the strings to be generated is longer than in the +above example: +@example +mkdir /usr/local/src/bash/@{old,new,dist,bugs@} +@end example +or +@example +chown root /usr/@{ucb/@{ex,edit@},lib/@{ex?.?*,how_ex@}@} +@end example + +@node Tilde Expansion +@subsection Tilde Expansion +@cindex tilde expansion +@cindex expansion, tilde + +If a word begins with an unquoted tilde character (@samp{~}), all of the +characters up to the first unquoted slash (or all characters, +if there is no unquoted slash) are considered a @var{tilde-prefix}. +If none of the characters in the tilde-prefix are quoted, the +characters in the tilde-prefix following the tilde are treated as a +possible @var{login name}. +If this login name is the null string, the tilde is replaced with the +value of the @env{HOME} shell variable. +If @env{HOME} is unset, the home directory of the user executing the +shell is substituted instead. +Otherwise, the tilde-prefix is replaced with the home directory +associated with the specified login name. + +If the tilde-prefix is @samp{~+}, the value of +the shell variable @env{PWD} replaces the tilde-prefix. +If the tilde-prefix is @samp{~-}, the value of the shell variable +@env{OLDPWD}, if it is set, is substituted. + +If the characters following the tilde in the tilde-prefix consist of a +number @var{N}, optionally prefixed by a @samp{+} or a @samp{-}, +the tilde-prefix is replaced with the +corresponding element from the directory stack, as it would be displayed +by the @code{dirs} builtin invoked with the characters following tilde +in the tilde-prefix as an argument (@pxref{The Directory Stack}). +If the tilde-prefix, sans the tilde, consists of a number without a +leading @samp{+} or @samp{-}, @samp{+} is assumed. + +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 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}, +and the shell assigns the expanded value. + +The following table shows how Bash treats unquoted tilde-prefixes: + +@table @code +@item ~ +The value of @code{$HOME} +@item ~/foo +@file{$HOME/foo} + +@item ~fred/foo +The subdirectory @code{foo} of the home directory of the user +@code{fred} + +@item ~+/foo +@file{$PWD/foo} + +@item ~-/foo +@file{$@{OLDPWD-'~-'@}/foo} + +@item ~@var{N} +The string that would be displayed by @samp{dirs +@var{N}} + +@item ~+@var{N} +The string that would be displayed by @samp{dirs +@var{N}} + +@item ~-@var{N} +The string that would be displayed by @samp{dirs -@var{N}} + +@end table + +@node Shell Parameter Expansion +@subsection Shell Parameter Expansion +@cindex parameter expansion +@cindex expansion, parameter + +The @samp{$} character introduces parameter expansion, +command substitution, or arithmetic expansion. The parameter name +or symbol to be expanded may be enclosed in braces, which +are optional but serve to protect the variable to be expanded from +characters immediately following it which could be +interpreted as part of the name. + +When braces are used, the matching ending brace is the first @samp{@}} +not escaped by a backslash or within a quoted string, and not within an +embedded arithmetic expansion, command substitution, or parameter +expansion. + +The basic form of parameter expansion is $@{@var{parameter}@}. +The value of @var{parameter} is substituted. The braces are required +when @var{parameter} +is a positional parameter with more than one digit, +or when @var{parameter} +is followed by a character that is not to be +interpreted as part of its name. + +If the first character of @var{parameter} is an exclamation point (!), +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 is used in the rest of the substitution, rather +than the value of @var{parameter} itself. +This is known as @code{indirect expansion}. +The exceptions to this are the expansions of $@{!@var{prefix*}@} +and $@{!@var{name}[@@]@} +described below. +The exclamation point must immediately follow the left brace in order to +introduce indirection. + +In each of the cases below, @var{word} is subject to tilde expansion, +parameter expansion, command substitution, and arithmetic expansion. + +When not performing substring expansion, using the form described +below, Bash tests for a parameter that is unset or null. +Omitting the colon results in a test only for a parameter that is unset. +Put another way, if the colon is included, +the operator tests for both @var{parameter}'s existence and that its value +is not null; if the colon is omitted, the operator tests only for existence. + +@table @code + +@item $@{@var{parameter}:@minus{}@var{word}@} +If @var{parameter} is unset or null, the expansion of +@var{word} is substituted. Otherwise, the value of +@var{parameter} is substituted. + +@item $@{@var{parameter}:=@var{word}@} +If @var{parameter} +is unset or null, the expansion of @var{word} +is assigned to @var{parameter}. +The value of @var{parameter} is then substituted. +Positional parameters and special parameters may not be assigned to +in this way. + +@item $@{@var{parameter}:?@var{word}@} +If @var{parameter} +is null or unset, the expansion of @var{word} (or a message +to that effect if @var{word} +is not present) is written to the standard error and the shell, if it +is not interactive, exits. Otherwise, the value of @var{parameter} is +substituted. + +@item $@{@var{parameter}:+@var{word}@} +If @var{parameter} +is null or unset, nothing is substituted, otherwise the expansion of +@var{word} is substituted. + +@item $@{@var{parameter}:@var{offset}@} +@itemx $@{@var{parameter}:@var{offset}:@var{length}@} +Expands to up to @var{length} characters of @var{parameter} +starting at the character specified by @var{offset}. +If @var{length} is omitted, expands to the substring of +@var{parameter} starting at the character specified by @var{offset}. +@var{length} and @var{offset} are arithmetic expressions +(@pxref{Shell Arithmetic}). +This is referred to as Substring Expansion. + +@var{length} must evaluate to a number greater than or equal to zero. +If @var{offset} evaluates to a number less than zero, the value +is used as an offset from the end of the value of @var{parameter}. +If @var{parameter} is @samp{@@}, the result is @var{length} positional +parameters beginning at @var{offset}. +If @var{parameter} is an indexed array name subscripted +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. +Substring expansion applied to an associative array produces undefined +results. + +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 by default. +If @var{offset} is 0, and the positional parameters are used, @code{$@@} is +prefixed to the list. + +@item $@{!@var{prefix}*@} +@itemx $@{!@var{prefix}@@@} +Expands to the names of variables whose names begin with @var{prefix}, +separated by the first character of the @env{IFS} special variable. +When @samp{@@} is used and the expansion appears within double quotes, each +variable name expands to a separate word. + +@item $@{!@var{name}[@@]@} +@itemx $@{!@var{name}[*]@} +If @var{name} is an array variable, expands to the list of array indices +(keys) assigned in @var{name}. +If @var{name} is not an array, expands to 0 if @var{name} is set and null +otherwise. +When @samp{@@} is used and the expansion appears within double quotes, each +key expands to a separate word. + +@item $@{#@var{parameter}@} +The length in characters of the expanded value of @var{parameter} is +substituted. +If @var{parameter} is @samp{*} or @samp{@@}, the value substituted +is the number of positional parameters. +If @var{parameter} is an array name subscripted by @samp{*} or @samp{@@}, +the value substituted is the number of elements in the array. + +@item $@{@var{parameter}#@var{word}@} +@itemx $@{@var{parameter}##@var{word}@} +The @var{word} +is expanded to produce a pattern just as in filename +expansion (@pxref{Filename Expansion}). If the pattern matches +the beginning of the expanded value of @var{parameter}, +then the result of the expansion is the expanded value of @var{parameter} +with the shortest matching pattern (the @samp{#} case) or the +longest matching pattern (the @samp{##} case) deleted. +If @var{parameter} is @samp{@@} or @samp{*}, +the pattern removal operation is applied to each positional +parameter in turn, and the expansion is the resultant list. +If @var{parameter} is an array variable subscripted with +@samp{@@} or @samp{*}, +the pattern removal operation is applied to each member of the +array in turn, and the expansion is the resultant list. + +@item $@{@var{parameter}%@var{word}@} +@itemx $@{@var{parameter}%%@var{word}@} +The @var{word} is expanded to produce a pattern just as in +filename expansion. +If the pattern matches a trailing portion of the expanded value of +@var{parameter}, then the result of the expansion is the value of +@var{parameter} with the shortest matching pattern (the @samp{%} case) +or the longest matching pattern (the @samp{%%} case) deleted. +If @var{parameter} is @samp{@@} or @samp{*}, +the pattern removal operation is applied to each positional +parameter in turn, and the expansion is the resultant list. +If @var{parameter} +is an array variable subscripted with @samp{@@} or @samp{*}, +the pattern removal operation is applied to each member of the +array in turn, and the expansion is the resultant list. + +@item $@{@var{parameter}/@var{pattern}/@var{string}@} + +The @var{pattern} is expanded to produce a pattern just as in +filename expansion. +@var{Parameter} is expanded and the longest match of @var{pattern} +against its value is replaced with @var{string}. +If @var{pattern} begins with @samp{/}, all matches of @var{pattern} are +replaced with @var{string}. Normally only the first match is replaced. +If @var{pattern} begins with @samp{#}, it must match at the beginning +of the expanded value of @var{parameter}. +If @var{pattern} begins with @samp{%}, it must match at the end +of the expanded value of @var{parameter}. +If @var{string} is null, matches of @var{pattern} are deleted +and the @code{/} following @var{pattern} may be omitted. +If @var{parameter} is @samp{@@} or @samp{*}, +the substitution operation is applied to each positional +parameter in turn, and the expansion is the resultant list. +If @var{parameter} +is an array variable subscripted with @samp{@@} or @samp{*}, +the substitution operation is applied to each member of the +array in turn, and the expansion is the resultant list. + +@item $@{@var{parameter}^@var{pattern}@} +@itemx $@{@var{parameter}^^@var{pattern}@} +@itemx $@{@var{parameter},@var{pattern}@} +@itemx $@{@var{parameter},,@var{pattern}@} +This expansion modifies the case of alphabetic characters in @var{parameter}. +The @var{pattern} is expanded to produce a pattern just as in +filename expansion. +The @samp{^} operator converts lowercase letters matching @var{pattern} +to uppercase; the @samp{,} operator converts matching uppercase letters +to lowercase. +The @samp{^^} and @samp{,,} expansions convert each matched character in the +expanded value; the @samp{^} and @samp{,} expansions match and convert only +the first character in the expanded value. +If @var{pattern} is omitted, it is treated like a @samp{?}, which matches +every character. +If @var{parameter} is @samp{@@} or @samp{*}, +the case modification operation is applied to each positional +parameter in turn, and the expansion is the resultant list. +If @var{parameter} +is an array variable subscripted with @samp{@@} or @samp{*}, +the case modification operation is applied to each member of the +array in turn, and the expansion is the resultant list. + +@end table + +@node Command Substitution +@subsection Command Substitution +@cindex command substitution + +Command substitution allows the output of a command to replace +the command itself. +Command substitution occurs when a command is enclosed as follows: +@example +$(@var{command}) +@end example +@noindent +or +@example +`@var{command}` +@end example + +@noindent +Bash performs the expansion by executing @var{command} and +replacing the command substitution with the standard output of the +command, with any trailing newlines deleted. +Embedded newlines are not deleted, but they may be removed during +word splitting. +The command substitution @code{$(cat @var{file})} can be +replaced by the equivalent but faster @code{$(< @var{file})}. + +When the old-style backquote form of substitution is used, +backslash retains its literal meaning except when followed by +@samp{$}, @samp{`}, or @samp{\}. +The first backquote not preceded by a backslash terminates the +command substitution. +When using the @code{$(@var{command})} form, all characters between +the parentheses make up the command; none are treated specially. + +Command substitutions may be nested. To nest when using the backquoted +form, escape the inner backquotes with backslashes. + +If the substitution appears within double quotes, word splitting and +filename expansion are not performed on the results. + +@node Arithmetic Expansion +@subsection Arithmetic Expansion +@cindex expansion, arithmetic +@cindex arithmetic expansion + +Arithmetic expansion allows the evaluation of an arithmetic expression +and the substitution of the result. The format for arithmetic expansion is: + +@example +$(( @var{expression} )) +@end example + +The expression is treated as if it were within double quotes, but +a double quote inside the parentheses is not treated specially. +All tokens in the expression undergo parameter expansion, command +substitution, and quote removal. +Arithmetic expansions may be nested. + +The evaluation is performed according to the rules listed below +(@pxref{Shell Arithmetic}). +If the expression is invalid, Bash prints a message indicating +failure to the standard error and no substitution occurs. + +@node Process Substitution +@subsection Process Substitution +@cindex process substitution + +Process substitution is supported on systems that support named +pipes (@sc{fifo}s) or the @file{/dev/fd} method of naming open files. +It takes the form of +@example +<(@var{list}) +@end example +@noindent +or +@example +>(@var{list}) +@end example +@noindent +The process @var{list} is run with its input or output connected to a +@sc{fifo} or some file in @file{/dev/fd}. The name of this file is +passed as an argument to the current command as the result of the +expansion. If the @code{>(@var{list})} form is used, writing to +the file will provide input for @var{list}. If the +@code{<(@var{list})} form is used, the file passed as an +argument should be read to obtain the output of @var{list}. +Note that no space may appear between the @code{<} or @code{>} +and the left parenthesis, otherwise the construct would be interpreted +as a redirection. + +When available, process substitution is performed simultaneously with +parameter and variable expansion, command substitution, and arithmetic +expansion. + +@node Word Splitting +@subsection Word Splitting +@cindex word splitting + +The shell scans the results of parameter expansion, command substitution, +and arithmetic expansion that did not occur within double quotes for +word splitting. + +The shell treats each character of @env{$IFS} as a delimiter, and splits +the results of the other expansions into words on these characters. +If @env{IFS} is unset, or its value is exactly @code{<space><tab><newline>}, +the default, then sequences of +@code{ <space>}, @code{<tab>}, and @code{<newline>} +at the beginning and end of the results of the previous +expansions are ignored, and any sequence of @env{IFS} +characters not at the beginning or end serves to delimit words. +If @env{IFS} has a value other than the default, then sequences of +the whitespace characters @code{space} and @code{tab} +are ignored at the beginning and end of the +word, as long as the whitespace character is in the +value of @env{IFS} (an @env{IFS} whitespace character). +Any character in @env{IFS} that is not @env{IFS} +whitespace, along with any adjacent @env{IFS} +whitespace characters, delimits a field. A sequence of @env{IFS} +whitespace characters is also treated as a delimiter. +If the value of @env{IFS} is null, no word splitting occurs. + +Explicit null arguments (@code{""} or @code{''}) are retained. +Unquoted implicit null arguments, resulting from the expansion of +parameters that have no values, are removed. +If a parameter with no value is expanded within double quotes, a +null argument results and is retained. + +Note that if no expansion occurs, no splitting +is performed. + +@node Filename Expansion +@subsection Filename Expansion +@menu +* Pattern Matching:: How the shell matches patterns. +@end menu +@cindex expansion, filename +@cindex expansion, pathname +@cindex filename expansion +@cindex pathname expansion + +After word splitting, unless the @option{-f} option has been set +(@pxref{The Set Builtin}), Bash scans each word for the characters +@samp{*}, @samp{?}, and @samp{[}. +If one of these characters appears, then the word is +regarded as a @var{pattern}, +and replaced with an alphabetically sorted list of +file names matching the pattern. If no matching file names are found, +and the shell option @code{nullglob} is disabled, the word is left +unchanged. +If the @code{nullglob} option is set, and no matches are found, the word +is removed. +If the @code{failglob} shell option is set, and no matches are found, +an error message is printed and the command is not executed. +If the shell option @code{nocaseglob} is enabled, the match is performed +without regard to the case of alphabetic characters. + +When a pattern is used for filename expansion, the character @samp{.} +at the start of a filename or immediately following a slash +must be matched explicitly, unless the shell option @code{dotglob} is set. +When matching a file name, the slash character must always be +matched explicitly. +In other cases, the @samp{.} character is not treated specially. + +See the description of @code{shopt} in @ref{The Shopt Builtin}, +for a description of the @code{nocaseglob}, @code{nullglob}, +@code{failglob}, and @code{dotglob} options. + +The @env{GLOBIGNORE} +shell variable may be used to restrict the set of filenames matching a +pattern. If @env{GLOBIGNORE} +is set, each matching filename that also matches one of the patterns in +@env{GLOBIGNORE} is removed from the list of matches. The filenames +@file{.} and @file{..} +are always ignored when @env{GLOBIGNORE} +is set and not null. +However, setting @env{GLOBIGNORE} to a non-null value has the effect of +enabling the @code{dotglob} +shell option, so all other filenames beginning with a +@samp{.} will match. +To get the old behavior of ignoring filenames beginning with a +@samp{.}, make @samp{.*} one of the patterns in @env{GLOBIGNORE}. +The @code{dotglob} option is disabled when @env{GLOBIGNORE} +is unset. + +@node Pattern Matching +@subsubsection Pattern Matching +@cindex pattern matching +@cindex matching, pattern + +Any character that appears in a pattern, other than the special pattern +characters described below, matches itself. +The @sc{nul} character may not occur in a pattern. +A backslash escapes the following character; the +escaping backslash is discarded when matching. +The special pattern characters must be quoted if they are to be matched +literally. + +The special pattern characters have the following meanings: +@table @code +@item * +Matches any string, including the null string. +When the @code{globstar} shell option is enabled, and @samp{*} is used in +a filename expansion context, two adjacent @samp{*}s used as a single +pattern will match all files and zero or more directories and +subdirectories. +If followed by a @samp{/}, two adjacent @samp{*}s will match only +directories and subdirectories. +@item ? +Matches any single character. +@item [@dots{}] +Matches any one of the enclosed characters. A pair of characters +separated by a hyphen denotes a @var{range expression}; +any character that sorts between those two characters, inclusive, +using the current locale's collating sequence and character set, +is matched. If the first character following the +@samp{[} is a @samp{!} or a @samp{^} +then any character not enclosed is matched. A @samp{@minus{}} +may be matched by including it as the first or last character +in the set. A @samp{]} may be matched by including it as the first +character in the set. +The sorting order of characters in range expressions is determined by +the current locale and the value of the @env{LC_COLLATE} shell variable, +if set. + +For example, in the default C locale, @samp{[a-dx-z]} is equivalent to +@samp{[abcdxyz]}. Many locales sort characters in dictionary order, and in +these locales @samp{[a-dx-z]} is typically not equivalent to @samp{[abcdxyz]}; +it might be equivalent to @samp{[aBbCcDdxXyYz]}, for example. To obtain +the traditional interpretation of ranges in bracket expressions, you can +force the use of the C locale by setting the @env{LC_COLLATE} or +@env{LC_ALL} environment variable to the value @samp{C}. + +Within @samp{[} and @samp{]}, @var{character classes} can be specified +using the syntax +@code{[:}@var{class}@code{:]}, where @var{class} is one of the +following classes defined in the @sc{posix} standard: +@example +alnum alpha ascii blank cntrl digit graph lower +print punct space upper word xdigit +@end example +@noindent +A character class matches any character belonging to that class. +The @code{word} character class matches letters, digits, and the character +@samp{_}. + +Within @samp{[} and @samp{]}, an @var{equivalence class} can be +specified using the syntax @code{[=}@var{c}@code{=]}, which +matches all characters with the same collation weight (as defined +by the current locale) as the character @var{c}. + +Within @samp{[} and @samp{]}, the syntax @code{[.}@var{symbol}@code{.]} +matches the collating symbol @var{symbol}. +@end table + +If the @code{extglob} shell option is enabled using the @code{shopt} +builtin, several extended pattern matching operators are recognized. +In the following description, a @var{pattern-list} is a list of one +or more patterns separated by a @samp{|}. +Composite patterns may be formed using one or more of the following +sub-patterns: + +@table @code +@item ?(@var{pattern-list}) +Matches zero or one occurrence of the given patterns. + +@item *(@var{pattern-list}) +Matches zero or more occurrences of the given patterns. + +@item +(@var{pattern-list}) +Matches one or more occurrences of the given patterns. + +@item @@(@var{pattern-list}) +Matches one of the given patterns. + +@item !(@var{pattern-list}) +Matches anything except one of the given patterns. +@end table + +@node Quote Removal +@subsection Quote Removal + +After the preceding expansions, all unquoted occurrences of the +characters @samp{\}, @samp{'}, and @samp{"} that did not +result from one of the above expansions are removed. + +@node Redirections +@section Redirections +@cindex redirection + +Before a command is executed, its input and output +may be @var{redirected} +using a special notation interpreted by the shell. +Redirection may also be used to open and close files for the +current shell execution environment. The following redirection +operators may precede or appear anywhere within a +simple command or may follow a command. +Redirections are processed in the order they appear, from +left to right. + +Each redirection that may be preceded by a file descriptor number +may instead be preceded by a word of the form @{@var{varname}@}. +In this case, for each redirection operator except +>&- and <&-, the shell will allocate a file descriptor greater +than 10 and assign it to @{@var{varname}@}. If >&- or <&- is preceded +by @{@var{varname}@}, the value of @var{varname} defines the file +descriptor to close. + +In the following descriptions, if the file descriptor number is +omitted, and the first character of the redirection operator is +@samp{<}, the redirection refers to the standard input (file +descriptor 0). If the first character of the redirection operator +is @samp{>}, the redirection refers to the standard output (file +descriptor 1). + +The word following the redirection operator in the following +descriptions, unless otherwise noted, is subjected to brace expansion, +tilde expansion, parameter expansion, command substitution, arithmetic +expansion, quote removal, filename expansion, and word splitting. +If it expands to more than one word, Bash reports an error. + +Note that the order of redirections is significant. For example, +the command +@example +ls > @var{dirlist} 2>&1 +@end example +@noindent +directs both standard output (file descriptor 1) and standard error +(file descriptor 2) to the file @var{dirlist}, while the command +@example +ls 2>&1 > @var{dirlist} +@end example +@noindent +directs only the standard output to file @var{dirlist}, +because the standard error was made a copy of the standard output +before the standard output was redirected to @var{dirlist}. + +Bash handles several filenames specially when they are used in +redirections, as described in the following table: + +@table @code +@item /dev/fd/@var{fd} +If @var{fd} is a valid integer, file descriptor @var{fd} is duplicated. + +@item /dev/stdin +File descriptor 0 is duplicated. + +@item /dev/stdout +File descriptor 1 is duplicated. + +@item /dev/stderr +File descriptor 2 is duplicated. + +@item /dev/tcp/@var{host}/@var{port} +If @var{host} is a valid hostname or Internet address, and @var{port} +is an integer port number or service name, Bash attempts to open a TCP +connection to the corresponding socket. + +@item /dev/udp/@var{host}/@var{port} +If @var{host} is a valid hostname or Internet address, and @var{port} +is an integer port number or service name, Bash attempts to open a UDP +connection to the corresponding socket. + +@end table + +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} +to be opened for reading on file descriptor @code{n}, +or the standard input (file descriptor 0) if @code{n} +is not specified. + +The general format for redirecting input is: +@example +[@var{n}]<@var{word} +@end example + +@subsection Redirecting Output +Redirection of output causes the file whose name results from +the expansion of @var{word} +to be opened for writing on file descriptor @var{n}, +or the standard output (file descriptor 1) if @var{n} +is not specified. If the file does not exist it is created; +if it does exist it is truncated to zero size. + +The general format for redirecting output is: +@example +[@var{n}]>[|]@var{word} +@end example + +If the redirection operator is @samp{>}, and the @code{noclobber} +option to the @code{set} builtin has been enabled, the redirection +will fail if the file whose name results from the expansion of +@var{word} exists and is a regular file. +If the redirection operator is @samp{>|}, or the redirection operator is +@samp{>} and the @code{noclobber} option is not enabled, the redirection +is attempted even if the file named by @var{word} exists. + +@subsection Appending Redirected Output +Redirection of output in this fashion +causes the file whose name results from +the expansion of @var{word} +to be opened for appending on file descriptor @var{n}, +or the standard output (file descriptor 1) if @var{n} +is not specified. If the file does not exist it is created. + +The general format for appending output is: +@example +[@var{n}]>>@var{word} +@end example + +@subsection Redirecting Standard Output and Standard Error +This construct allows both the +standard output (file descriptor 1) and +the standard error output (file descriptor 2) +to be redirected to the file whose name is the +expansion of @var{word}. + +There are two formats for redirecting standard output and +standard error: +@example +&>@var{word} +@end example +@noindent +and +@example +>&@var{word} +@end example +@noindent +Of the two forms, the first is preferred. +This is semantically equivalent to +@example +>@var{word} 2>&1 +@end example + +@subsection Appending Standard Output and Standard Error +This construct allows both the +standard output (file descriptor 1) and +the standard error output (file descriptor 2) +to be appended to the file whose name is the +expansion of @var{word}. + +The format for appending standard output and standard error is: +@example +&>>@var{word} +@end example +@noindent +This is semantically equivalent to +@example +>>@var{word} 2>&1 +@end example + +@subsection Here Documents +This type of redirection instructs the shell to read input from the +current source until a line containing only @var{word} +(with no trailing blanks) is seen. All of +the lines read up to that point are then used as the standard +input for a command. + +The format of here-documents is: +@example +<<[@minus{}]@var{word} + @var{here-document} +@var{delimiter} +@end example + +No parameter expansion, command substitution, arithmetic expansion, +or filename expansion is performed on +@var{word}. If any characters in @var{word} are quoted, the +@var{delimiter} is the result of quote removal on @var{word}, +and the lines in the here-document are not expanded. +If @var{word} is unquoted, +all lines of the here-document are subjected to parameter expansion, +command substitution, and arithmetic expansion. In the latter +case, the character sequence @code{\newline} is ignored, and @samp{\} +must be used to quote the characters +@samp{\}, @samp{$}, and @samp{`}. + +If the redirection operator is @samp{<<-}, +then all leading tab characters are stripped from input lines and the +line containing @var{delimiter}. +This allows here-documents within shell scripts to be indented in a +natural fashion. + +@subsection Here Strings +A variant of here documents, the format is: +@example +<<< @var{word} +@end example + +The @var{word} is expanded and supplied to the command on its standard +input. + +@subsection Duplicating File Descriptors +The redirection operator +@example +[@var{n}]<&@var{word} +@end example +@noindent +is used to duplicate input file descriptors. +If @var{word} +expands to one or more digits, the file descriptor denoted by @var{n} +is made to be a copy of that file descriptor. +If the digits in @var{word} do not specify a file descriptor open for +input, a redirection error occurs. +If @var{word} +evaluates to @samp{-}, file descriptor @var{n} is closed. If +@var{n} is not specified, the standard input (file descriptor 0) is used. + +The operator +@example +[@var{n}]>&@var{word} +@end example +@noindent +is used similarly to duplicate output file descriptors. If +@var{n} is not specified, the standard output (file descriptor 1) is used. +If the digits in @var{word} do not specify a file descriptor open for +output, a redirection error occurs. +As a special case, if @var{n} is omitted, and @var{word} does not +expand to one or more digits, the standard output and standard +error are redirected as described previously. + +@subsection Moving File Descriptors +The redirection operator +@example +[@var{n}]<&@var{digit}- +@end example +@noindent +moves the file descriptor @var{digit} to file descriptor @var{n}, +or the standard input (file descriptor 0) if @var{n} is not specified. +@var{digit} is closed after being duplicated to @var{n}. + +Similarly, the redirection operator +@example +[@var{n}]>&@var{digit}- +@end example +@noindent +moves the file descriptor @var{digit} to file descriptor @var{n}, +or the standard output (file descriptor 1) if @var{n} is not specified. + +@subsection Opening File Descriptors for Reading and Writing +The redirection operator +@example +[@var{n}]<>@var{word} +@end example +@noindent +causes the file whose name is the expansion of @var{word} +to be opened for both reading and writing on file descriptor +@var{n}, or on file descriptor 0 if @var{n} +is not specified. If the file does not exist, it is created. + +@node Executing Commands +@section Executing Commands + +@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 +@subsection Simple Command Expansion +@cindex command expansion + +When a simple command is executed, the shell performs the following +expansions, assignments, and redirections, from left to right. + +@enumerate +@item +The words that the parser has marked as variable assignments (those +preceding the command name) and redirections are saved for later +processing. + +@item +The words that are not variable assignments or redirections are +expanded (@pxref{Shell Expansions}). +If any words remain after expansion, the first word +is taken to be the name of the command and the remaining words are +the arguments. + +@item +Redirections are performed as described above (@pxref{Redirections}). + +@item +The text after the @samp{=} in each variable assignment undergoes tilde +expansion, parameter expansion, command substitution, arithmetic expansion, +and quote removal before being assigned to the variable. +@end enumerate + +If no command name results, the variable assignments affect the current +shell environment. Otherwise, the variables are added to the environment +of the executed command and do not affect the current shell environment. +If any of the assignments attempts to assign a value to a readonly variable, +an error occurs, and the command exits with a non-zero status. + +If no command name results, redirections are performed, but do not +affect the current shell environment. A redirection error causes the +command to exit with a non-zero status. + +If there is a command name left after expansion, execution proceeds as +described below. Otherwise, the command exits. If one of the expansions +contained a command substitution, the exit status of the command is +the exit status of the last command substitution performed. If there +were no command substitutions, the command exits with a status of zero. + +@node Command Search and Execution +@subsection Command Search and Execution +@cindex command execution +@cindex command search + +After a command has been split into words, if it results in a +simple command and an optional list of arguments, the following +actions are taken. + +@enumerate +@item +If the command name contains no slashes, the shell attempts to +locate it. If there exists a shell function by that name, that +function is invoked as described in @ref{Shell Functions}. + +@item +If the name does not match a function, the shell searches for +it in the list of shell builtins. If a match is found, that +builtin is invoked. + +@item +If the name is neither a shell function nor a builtin, +and contains no slashes, Bash searches each element of +@env{$PATH} for a directory containing an executable file +by that name. Bash uses a hash table to remember the full +pathnames of executable files to avoid multiple @env{PATH} searches +(see the description of @code{hash} in @ref{Bourne Shell Builtins}). +A full search of the directories in @env{$PATH} +is performed only if the command is not found in the hash table. +If the search is unsuccessful, the shell searches for a defined shell +function named @code{command_not_found_handle}. +If that function exists, it is invoked with the original command and +the original command's arguments as its arguments, and the function's +exit status becomes the exit status of the shell. +If that function is not defined, the shell prints an error +message and returns an exit status of 127. + +@item +If the search is successful, or if the command name contains +one or more slashes, the shell executes the named program in +a separate execution environment. +Argument 0 is set to the name given, and the remaining arguments +to the command are set to the arguments supplied, if any. + +@item +If this execution fails because the file is not in executable +format, and the file is not a directory, it is assumed to be a +@var{shell script} and the shell executes it as described in +@ref{Shell Scripts}. + +@item +If the command was not begun asynchronously, the shell waits for +the command to complete and collects its exit status. + +@end enumerate + +@node Command Execution Environment +@subsection Command Execution Environment +@cindex execution environment + +The shell has an @var{execution environment}, which consists of the +following: + +@itemize @bullet +@item +open files inherited by the shell at invocation, as modified by +redirections supplied to the @code{exec} builtin + +@item +the current working directory as set by @code{cd}, @code{pushd}, or +@code{popd}, or inherited by the shell at invocation + +@item +the file creation mode mask as set by @code{umask} or inherited from +the shell's parent + +@item +current traps set by @code{trap} + +@item +shell parameters that are set by variable assignment or with @code{set} +or inherited from the shell's parent in the environment + +@item +shell functions defined during execution or inherited from the shell's +parent in the environment + +@item +options enabled at invocation (either by default or with command-line +arguments) or by @code{set} + +@item +options enabled by @code{shopt} (@pxref{The Shopt Builtin}) + +@item +shell aliases defined with @code{alias} (@pxref{Aliases}) + +@item +various process @sc{id}s, including those of background jobs +(@pxref{Lists}), the value of @code{$$}, and the value of +@env{$PPID} + +@end itemize + +When a simple command other than a builtin or shell function +is to be executed, it +is invoked in a separate execution environment that consists of +the following. Unless otherwise noted, the values are inherited +from the shell. + +@itemize @bullet +@item +the shell's open files, plus any modifications and additions specified +by redirections to the command + +@item +the current working directory + +@item +the file creation mode mask + +@item +shell variables and functions marked for export, along with variables +exported for the command, passed in the environment (@pxref{Environment}) + +@item +traps caught by the shell are reset to the values inherited from the +shell's parent, and traps ignored by the shell are ignored + +@end itemize + +A command invoked in this separate environment cannot affect the +shell's execution environment. + +Command substitution, commands grouped with parentheses, +and asynchronous commands are invoked in a +subshell environment that is a duplicate of the shell environment, +except that traps caught by the shell are reset to the values +that the shell inherited from its parent at invocation. Builtin +commands that are invoked as part of a pipeline are also executed +in a subshell environment. Changes made to the subshell environment +cannot affect the shell's execution environment. + +Subshells spawned to execute command substitutions inherit the value of +the @option{-e} option from the parent shell. When not in @sc{posix} mode, +Bash clears the @option{-e} option in such subshells. + +If a command is followed by a @samp{&} and job control is not active, the +default standard input for the command is the empty file @file{/dev/null}. +Otherwise, the invoked command inherits the file descriptors of the calling +shell as modified by redirections. + +@node Environment +@subsection Environment +@cindex environment + +When a program is invoked it is given an array of strings +called the @var{environment}. +This is a list of name-value pairs, of the form @code{name=value}. + +Bash provides several ways to manipulate the environment. +On invocation, the shell scans its own environment and +creates a parameter for each name found, automatically marking +it for @var{export} +to child processes. Executed commands inherit the environment. +The @code{export} and @samp{declare -x} +commands allow parameters and functions to be added to and +deleted from the environment. If the value of a parameter +in the environment is modified, the new value becomes part +of the environment, replacing the old. The environment +inherited by any executed command consists of the shell's +initial environment, whose values may be modified in the shell, +less any pairs removed by the @code{unset} and @samp{export -n} +commands, plus any additions via the @code{export} and +@samp{declare -x} commands. + +The environment for any simple command +or function may be augmented temporarily by prefixing it with +parameter assignments, as described in @ref{Shell Parameters}. +These assignment statements affect only the environment seen +by that command. + +If the @option{-k} option is set (@pxref{The Set Builtin}), then all +parameter assignments are placed in the environment for a command, +not just those that precede the command name. + +When Bash invokes an external command, the variable @samp{$_} +is set to the full path name of the command and passed to that +command in its environment. + +@node Exit Status +@subsection Exit Status +@cindex exit status + +The exit status of an executed command is the value returned by the +@var{waitpid} system call or equivalent function. Exit statuses +fall between 0 and 255, though, as explained below, the shell may +use values above 125 specially. Exit statuses from shell builtins and +compound commands are also limited to this range. Under certain +circumstances, the shell will use special values to indicate specific +failure modes. + +For the shell's purposes, a command which exits with a +zero exit status has succeeded. +A non-zero exit status indicates failure. +This seemingly counter-intuitive scheme is used so there +is one well-defined way to indicate success and a variety of +ways to indicate various failure modes. +When a command terminates on a fatal signal whose number is @var{N}, +Bash uses the value 128+@var{N} as the exit status. + +If a command is not found, the child process created to +execute it returns a status of 127. If a command is found +but is not executable, the return status is 126. + +If a command fails because of an error during expansion or redirection, +the exit status is greater than zero. + +The exit status is used by the Bash conditional commands +(@pxref{Conditional Constructs}) and some of the list +constructs (@pxref{Lists}). + +All of the Bash builtins return an exit status of zero if they succeed +and a non-zero status on failure, so they may be used by the +conditional and list constructs. +All builtins return an exit status of 2 to indicate incorrect usage. + +@node Signals +@subsection Signals +@cindex signal handling + +When Bash is interactive, in the absence of any traps, it ignores +@code{SIGTERM} (so that @samp{kill 0} does not kill an interactive shell), +and @code{SIGINT} +is caught and handled (so that the @code{wait} builtin is interruptible). +When Bash receives a @code{SIGINT}, it breaks out of any executing loops. +In all cases, Bash ignores @code{SIGQUIT}. +If job control is in effect (@pxref{Job Control}), Bash +ignores @code{SIGTTIN}, @code{SIGTTOU}, and @code{SIGTSTP}. + +Non-builtin commands started by Bash have signal handlers set to the +values inherited by the shell from its parent. +When job control is not in effect, asynchronous commands +ignore @code{SIGINT} and @code{SIGQUIT} in addition to these inherited +handlers. +Commands run as a result of +command substitution ignore the keyboard-generated job control signals +@code{SIGTTIN}, @code{SIGTTOU}, and @code{SIGTSTP}. + +The shell exits by default upon receipt of a @code{SIGHUP}. +Before exiting, an interactive shell resends the @code{SIGHUP} to +all jobs, running or stopped. +Stopped jobs are sent @code{SIGCONT} to ensure that they receive +the @code{SIGHUP}. +To prevent the shell from sending the @code{SIGHUP} signal to a +particular job, it should be removed +from the jobs table with the @code{disown} +builtin (@pxref{Job Control Builtins}) or marked +to not receive @code{SIGHUP} using @code{disown -h}. + +If the @code{huponexit} shell option has been set with @code{shopt} +(@pxref{The Shopt Builtin}), Bash sends a @code{SIGHUP} to all jobs when +an interactive login shell exits. + +If Bash 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 Bash is waiting for an asynchronous +command via the @code{wait} builtin, the reception of a signal for +which a trap has been set will cause the @code{wait} builtin to return +immediately with an exit status greater than 128, immediately after +which the trap is executed. + +@node Shell Scripts +@section Shell Scripts +@cindex shell script + +A shell script is a text file containing shell commands. When such +a file is used as the first non-option argument when invoking Bash, +and neither the @option{-c} nor @option{-s} option is supplied +(@pxref{Invoking Bash}), +Bash reads and executes commands from the file, then exits. This +mode of operation creates a non-interactive shell. The shell first +searches for the file in the current directory, and looks in the +directories in @env{$PATH} if not found there. + +When Bash runs +a shell script, it sets the special parameter @code{0} to the name +of the file, rather than the name of the shell, and the positional +parameters are set to the remaining arguments, if any are given. +If no additional arguments are supplied, the positional parameters +are unset. + +A shell script may be made executable by using the @code{chmod} command +to turn on the execute bit. When Bash finds such a file while +searching the @env{$PATH} for a command, it spawns a subshell to +execute it. In other words, executing +@example +filename @var{arguments} +@end example +@noindent +is equivalent to executing +@example +bash filename @var{arguments} +@end example + +@noindent +if @code{filename} is an executable shell script. +This subshell reinitializes itself, so that the effect is as if a +new shell had been invoked to interpret the script, with the +exception that the locations of commands remembered by the parent +(see the description of @code{hash} in @ref{Bourne Shell Builtins}) +are retained by the child. + +Most versions of Unix make this a part of the operating system's command +execution mechanism. If the first line of a script begins with +the two characters @samp{#!}, the remainder of the line specifies +an interpreter for the program. +Thus, you can specify Bash, @code{awk}, Perl, or some other +interpreter and write the rest of the script file in that language. + +The arguments to the interpreter +consist of a single optional argument following the interpreter +name on the first line of the script file, followed by the name of +the script file, followed by the rest of the arguments. Bash +will perform this action on operating systems that do not handle it +themselves. Note that some older versions of Unix limit the interpreter +name and argument to a maximum of 32 characters. + +Bash scripts often begin with @code{#! /bin/bash} (assuming that +Bash has been installed in @file{/bin}), since this ensures that +Bash will be used to interpret the script, even if it is executed +under another shell. + +@node Shell Builtin Commands +@chapter Shell Builtin Commands + +@menu +* Bourne Shell Builtins:: Builtin commands inherited from the Bourne + Shell. +* Bash Builtins:: Table of builtins specific to Bash. +* Modifying Shell Behavior:: Builtins to modify shell attributes and + optional behavior. +* Special Builtins:: Builtin commands classified specially by + POSIX. +@end menu + +Builtin commands are contained within the shell itself. +When the name of a builtin command is used as the first word of +a simple command (@pxref{Simple Commands}), the shell executes +the command directly, without invoking another program. +Builtin commands are necessary to implement functionality impossible +or inconvenient to obtain with separate utilities. + +This section briefly describes the builtins which Bash inherits from +the Bourne Shell, as well as the builtin commands which are unique +to or have been extended in Bash. + +Several builtin commands are described in other chapters: builtin +commands which provide the Bash interface to the job control +facilities (@pxref{Job Control Builtins}), the directory stack +(@pxref{Directory Stack Builtins}), the command history +(@pxref{Bash History Builtins}), and the programmable completion +facilities (@pxref{Programmable Completion Builtins}). + +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. +The @code{:}, @code{true}, @code{false}, and @code{test} +builtins do not accept options and do not treat @samp{--} specially. +The @code{exit}, @code{logout}, @code{break}, @code{continue}, @code{let}, +and @code{shift} builtins accept and process arguments beginning +with @samp{-} without requiring @samp{--}. +Other builtins that accept arguments but are not specified as accepting +options interpret arguments beginning with @samp{-} as invalid options and +require @samp{--} to prevent this interpretation. + +@node Bourne Shell Builtins +@section Bourne Shell Builtins + +The following shell builtin commands are inherited from the Bourne Shell. +These commands are implemented as specified by the @sc{posix} standard. + +@table @code +@item : @r{(a colon)} +@btindex : +@example +: [@var{arguments}] +@end example +Do nothing beyond expanding @var{arguments} and performing redirections. +The return status is zero. + +@item . @r{(a period)} +@btindex . +@example +. @var{filename} [@var{arguments}] +@end example +Read and execute commands from the @var{filename} argument in the +current shell context. If @var{filename} does not contain a slash, +the @env{PATH} variable is used to find @var{filename}. +When Bash is not in @sc{posix} mode, the current directory is searched +if @var{filename} is not found in @env{$PATH}. +If any @var{arguments} are supplied, they become the positional +parameters when @var{filename} is executed. Otherwise the positional +parameters are unchanged. +The return status is the exit status of the last command executed, or +zero if no commands are executed. If @var{filename} is not found, or +cannot be read, the return status is non-zero. +This builtin is equivalent to @code{source}. + +@item break +@btindex break +@example +break [@var{n}] +@end example +Exit from a @code{for}, @code{while}, @code{until}, or @code{select} loop. +If @var{n} is supplied, the @var{n}th enclosing loop is exited. +@var{n} must be greater than or equal to 1. +The return status is zero unless @var{n} is not greater than or equal to 1. + +@item cd +@btindex cd +@example +cd [-L|-P] [@var{directory}] +@end example +Change the current working directory to @var{directory}. +If @var{directory} is not given, the value of the @env{HOME} shell +variable is used. +If the shell variable @env{CDPATH} exists, it is used as a search path. +If @var{directory} begins with a slash, @env{CDPATH} is not used. + +The @option{-P} option means to not follow symbolic links; symbolic +links are followed by default or with the @option{-L} option. +If @var{directory} is @samp{-}, it is equivalent to @env{$OLDPWD}. + +If a non-empty directory name from @env{CDPATH} is used, or if +@samp{-} is the first argument, and the directory change is +successful, the absolute pathname of the new working directory is +written to the standard output. + +The return status is zero if the directory is successfully changed, +non-zero otherwise. + +@item continue +@btindex continue +@example +continue [@var{n}] +@end example +Resume the next iteration of an enclosing @code{for}, @code{while}, +@code{until}, or @code{select} loop. +If @var{n} is supplied, the execution of the @var{n}th enclosing loop +is resumed. +@var{n} must be greater than or equal to 1. +The return status is zero unless @var{n} is not greater than or equal to 1. + +@item eval +@btindex eval +@example +eval [@var{arguments}] +@end example +The arguments are concatenated together into a single command, which is +then read and executed, and its exit status returned as the exit status +of @code{eval}. +If there are no arguments or only empty arguments, the return status is +zero. + +@item exec +@btindex exec +@example +exec [-cl] [-a @var{name}] [@var{command} [@var{arguments}]] +@end example +If @var{command} +is supplied, it replaces the shell without creating a new process. +If the @option{-l} option is supplied, the shell places a dash at the +beginning of the zeroth argument passed to @var{command}. +This is what the @code{login} program does. +The @option{-c} option causes @var{command} to be executed with an empty +environment. +If @option{-a} is supplied, the shell passes @var{name} as the zeroth +argument to @var{command}. +If no @var{command} is specified, redirections may be used to affect +the current shell environment. If there are no redirection errors, the +return status is zero; otherwise the return status is non-zero. + +@item exit +@btindex exit +@example +exit [@var{n}] +@end example +Exit the shell, returning a status of @var{n} to the shell's parent. +If @var{n} is omitted, the exit status is that of the last command executed. +Any trap on @code{EXIT} is executed before the shell terminates. + +@item export +@btindex export +@example +export [-fn] [-p] [@var{name}[=@var{value}]] +@end example +Mark each @var{name} to be passed to child processes +in the environment. If the @option{-f} option is supplied, the @var{name}s +refer to shell functions; otherwise the names refer to shell variables. +The @option{-n} option means to no longer mark each @var{name} for export. +If no @var{names} are supplied, or if the @option{-p} option is given, a +list of exported names is displayed. +The @option{-p} option displays output in a form that may be reused as input. +If a variable name is followed by =@var{value}, the value of +the variable is set to @var{value}. + +The return status is zero unless an invalid option is supplied, one of +the names is not a valid shell variable name, or @option{-f} is supplied +with a name that is not a shell function. + +@item getopts +@btindex getopts +@example +getopts @var{optstring} @var{name} [@var{args}] +@end example +@code{getopts} is used by shell scripts to parse positional parameters. +@var{optstring} contains the option characters to be recognized; if a +character is followed by a colon, the option is expected to have an +argument, which should be separated from it by white space. +The colon (@samp{:}) and question mark (@samp{?}) may not be +used as option characters. +Each time it is invoked, @code{getopts} +places the next option in the shell variable @var{name}, initializing +@var{name} if it does not exist, +and the index of the next argument to be processed into the +variable @env{OPTIND}. +@env{OPTIND} is initialized to 1 each time the shell or a shell script +is invoked. +When an option requires an argument, +@code{getopts} places that argument into the variable @env{OPTARG}. +The shell does not reset @env{OPTIND} automatically; it must be manually +reset between multiple calls to @code{getopts} within the same shell +invocation if a new set of parameters is to be used. + +When the end of options is encountered, @code{getopts} exits with a +return value greater than zero. +@env{OPTIND} is set to the index of the first non-option argument, +and @code{name} is set to @samp{?}. + +@code{getopts} +normally parses the positional parameters, but if more arguments are +given in @var{args}, @code{getopts} parses those instead. + +@code{getopts} can report errors in two ways. If the first character of +@var{optstring} is a colon, @var{silent} +error reporting is used. In normal operation diagnostic messages +are printed when invalid options or missing option arguments are +encountered. +If the variable @env{OPTERR} +is set to 0, no error messages will be displayed, even if the first +character of @code{optstring} is not a colon. + +If an invalid option is seen, +@code{getopts} places @samp{?} into @var{name} and, if not silent, +prints an error message and unsets @env{OPTARG}. +If @code{getopts} is silent, the option character found is placed in +@env{OPTARG} and no diagnostic message is printed. + +If a required argument is not found, and @code{getopts} +is not silent, a question mark (@samp{?}) is placed in @var{name}, +@code{OPTARG} is unset, and a diagnostic message is printed. +If @code{getopts} is silent, then a colon (@samp{:}) is placed in +@var{name} and @env{OPTARG} is set to the option character found. + +@item hash +@btindex hash +@example +hash [-r] [-p @var{filename}] [-dt] [@var{name}] +@end example +Remember the full pathnames of commands specified as @var{name} arguments, +so they need not be searched for on subsequent invocations. +The commands are found by searching through the directories listed in +@env{$PATH}. +The @option{-p} option inhibits the path search, and @var{filename} is +used as the location of @var{name}. +The @option{-r} option causes the shell to forget all remembered locations. +The @option{-d} option causes the shell to forget the remembered location +of each @var{name}. +If the @option{-t} option is supplied, the full pathname to which each +@var{name} corresponds is printed. If multiple @var{name} arguments are +supplied with @option{-t} the @var{name} is printed before the hashed +full pathname. +The @option{-l} option causes output to be displayed in a format +that may be reused as input. +If no arguments are given, or if only @option{-l} is supplied, +information about remembered commands is printed. +The return status is zero unless a @var{name} is not found or an invalid +option is supplied. + +@item pwd +@btindex pwd +@example +pwd [-LP] +@end example +Print the absolute pathname of the current working directory. +If the @option{-P} option is supplied, the pathname printed will not +contain symbolic links. +If the @option{-L} option is supplied, the pathname printed may contain +symbolic links. +The return status is zero unless an error is encountered while +determining the name of the current directory or an invalid option +is supplied. + +@item readonly +@btindex readonly +@example +readonly [-aApf] [@var{name}[=@var{value}]] @dots{} +@end example +Mark each @var{name} as readonly. +The values of these names may not be changed by subsequent assignment. +If the @option{-f} option is supplied, each @var{name} refers to a shell +function. +The @option{-a} option means each @var{name} refers to an indexed +array variable; the @option{-A} option means each @var{name} refers +to an associative array variable. +If no @var{name} arguments are given, or if the @option{-p} +option is supplied, a list of all readonly names is printed. +The @option{-p} option causes output to be displayed in a format that +may be reused as input. +If a variable name is followed by =@var{value}, the value of +the variable is set to @var{value}. +The return status is zero unless an invalid option is supplied, one of +the @var{name} arguments is not a valid shell variable or function name, +or the @option{-f} option is supplied with a name that is not a shell function. + +@item return +@btindex return +@example +return [@var{n}] +@end example +Cause a shell function to exit with the return value @var{n}. +If @var{n} is not supplied, the return value is the exit status of the +last command executed in the function. +This may also be used to terminate execution of a script being executed +with the @code{.} (or @code{source}) builtin, returning either @var{n} or +the exit status of the last command executed within the script as the exit +status of the script. +Any command associated with the @code{RETURN} trap is executed +before execution resumes after the function or script. +The return status is non-zero if @code{return} is used outside a function +and not during the execution of a script by @code{.} or @code{source}. + +@item shift +@btindex shift +@example +shift [@var{n}] +@end example +Shift the positional parameters to the left by @var{n}. +The positional parameters from @var{n}+1 @dots{} @code{$#} are +renamed to @code{$1} @dots{} @code{$#}-@var{n}. +Parameters represented by the numbers @code{$#} to @code{$#}-@var{n}+1 +are unset. +@var{n} must be a non-negative number less than or equal to @code{$#}. +If @var{n} is zero or greater than @code{$#}, the positional parameters +are not changed. +If @var{n} is not supplied, it is assumed to be 1. +The return status is zero unless @var{n} is greater than @code{$#} or +less than zero, non-zero otherwise. + +@item test +@itemx [ +@btindex test +@btindex [ +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{]}. + +Expressions may be combined using the following operators, listed in +decreasing order of precedence. +The evaluation depends on the number of arguments; see below. + +@table @code +@item ! @var{expr} +True if @var{expr} is false. + +@item ( @var{expr} ) +Returns the value of @var{expr}. +This may be used to override the normal precedence of operators. + +@item @var{expr1} -a @var{expr2} +True if both @var{expr1} and @var{expr2} are true. + +@item @var{expr1} -o @var{expr2} +True if either @var{expr1} or @var{expr2} is true. +@end table + +The @code{test} and @code{[} builtins evaluate conditional +expressions using a set of rules based on the number of arguments. + +@table @asis +@item 0 arguments +The expression is false. + +@item 1 argument +The expression is true if and only if the argument is not null. + +@item 2 arguments +If the first argument is @samp{!}, the expression is true if and +only if the second argument is null. +If the first argument is one of the unary conditional operators +(@pxref{Bash Conditional Expressions}), the expression +is true if the unary test is true. +If the first argument is not a valid unary operator, the expression is +false. + +@item 3 arguments +If the second argument is one of the binary conditional +operators (@pxref{Bash Conditional Expressions}), the +result of the expression is the result of the binary test using the +first and third arguments as operands. +The @samp{-a} and @samp{-o} operators are considered binary operators +when there are three arguments. +If the first argument is @samp{!}, the value is the negation of +the two-argument test using the second and third arguments. +If the first argument is exactly @samp{(} and the third argument is +exactly @samp{)}, the result is the one-argument test of the second +argument. +Otherwise, the expression is false. + +@item 4 arguments +If the first argument is @samp{!}, the result is the negation of +the three-argument expression composed of the remaining arguments. +Otherwise, the expression is parsed and evaluated according to +precedence using the rules listed above. + +@item 5 or more arguments +The expression is parsed and evaluated according to precedence +using the rules listed above. +@end table + +@item times +@btindex times +@example +times +@end example +Print out the user and system times used by the shell and its children. +The return status is zero. + +@item trap +@btindex trap +@example +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 (and +there is a single @var{sigspec}) or +equal to @samp{-}, each specified signal's disposition is reset +to the value it had when the shell was started. +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 not present and @option{-p} has been supplied, +the shell displays the trap commands associated with each @var{sigspec}. +If no arguments are supplied, or +only @option{-p} is given, @code{trap} prints the list of commands +associated with each signal number in a form that may be reused as +shell input. +The @option{-l} option causes the shell to print a list of signal names +and their corresponding numbers. +Each @var{sigspec} is either a signal name or a signal number. +Signal names are case insensitive and the @code{SIG} prefix is optional. + +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 +before every simple command, @code{for} command, @code{case} command, +@code{select} command, every arithmetic @code{for} command, and before +the first command executes in a shell function. +Refer to the description of the @code{extdebug} option to the +@code{shopt} builtin (@pxref{The Shopt Builtin}) for details of its +effect on the @code{DEBUG} trap. +If a @var{sigspec} is @code{RETURN}, the command @var{arg} is executed +each time a shell function or a script executed with the @code{.} or +@code{source} builtins finishes executing. + +If a @var{sigspec} is @code{ERR}, the command @var{arg} +is executed whenever a simple command has a non-zero exit status, +subject to the following conditions. +The @code{ERR} trap is not executed if the failed command is part of the +command list immediately following an @code{until} or @code{while} keyword, +part of the test following the @code{if} or @code{elif} reserved words, +part of a command executed in a @code{&&} or @code{||} list, +or if the command's return +status is being inverted using @code{!}. +These are the same conditions obeyed by the @code{errexit} option. + +Signals ignored upon entry to the shell cannot be trapped or reset. +Trapped signals that are not being ignored are reset to their original +values in a subshell or subshell environment when one is created. + +The return status is zero unless a @var{sigspec} does not specify a +valid signal. + +@item umask +@btindex umask +@example +umask [-p] [-S] [@var{mode}] +@end example +Set the shell process's file creation mask to @var{mode}. If +@var{mode} begins with a digit, it is interpreted as an octal number; +if not, it is interpreted as a symbolic mode mask similar +to that accepted by the @code{chmod} command. If @var{mode} is +omitted, the current value of the mask is printed. If the @option{-S} +option is supplied without a @var{mode} argument, the mask is printed +in a symbolic format. +If the @option{-p} option is supplied, and @var{mode} +is omitted, the output is in a form that may be reused as input. +The return status is zero if the mode is successfully changed or if +no @var{mode} argument is supplied, and non-zero otherwise. + +Note that when the mode is interpreted as an octal number, each number +of the umask is subtracted from @code{7}. Thus, a umask of @code{022} +results in permissions of @code{755}. + +@item unset +@btindex unset +@example +unset [-fv] [@var{name}] +@end example +Each variable or function @var{name} is removed. +If no options are supplied, or the @option{-v} option is given, each +@var{name} refers to a shell variable. +If the @option{-f} option is given, the @var{name}s refer to shell +functions, and the function definition is removed. +Readonly variables and functions may not be unset. +The return status is zero unless a @var{name} is readonly. +@end table + +@node Bash Builtins +@section Bash Builtin Commands + +This section describes builtin commands which are unique to +or have been extended in Bash. +Some of these commands are specified in the @sc{posix} standard. + +@table @code + +@item alias +@btindex alias +@example +alias [@code{-p}] [@var{name}[=@var{value}] @dots{}] +@end example + +Without arguments or with the @option{-p} option, @code{alias} prints +the list of aliases on the standard output in a form that allows +them to be reused as input. +If arguments are supplied, an alias is defined for each @var{name} +whose @var{value} is given. If no @var{value} is given, the name +and value of the alias is printed. +Aliases are described in @ref{Aliases}. + +@item bind +@btindex bind +@example +bind [-m @var{keymap}] [-lpsvPSV] +bind [-m @var{keymap}] [-q @var{function}] [-u @var{function}] [-r @var{keyseq}] +bind [-m @var{keymap}] -f @var{filename} +bind [-m @var{keymap}] -x @var{keyseq:shell-command} +bind [-m @var{keymap}] @var{keyseq:function-name} +bind @var{readline-command} +@end example + +Display current Readline (@pxref{Command Line Editing}) +key and function bindings, +bind a key sequence to a Readline function or macro, +or set a Readline variable. +Each non-option argument is a command as it would appear in a +Readline initialization file (@pxref{Readline Init File}), +but each binding or command must be passed as a separate argument; e.g., +@samp{"\C-x\C-r":re-read-init-file}. + +Options, if supplied, have the following meanings: + +@table @code +@item -m @var{keymap} +Use @var{keymap} as the keymap to be affected by +the subsequent bindings. Acceptable @var{keymap} +names are +@code{emacs}, +@code{emacs-standard}, +@code{emacs-meta}, +@code{emacs-ctlx}, +@code{vi}, +@code{vi-move}, +@code{vi-command}, and +@code{vi-insert}. +@code{vi} is equivalent to @code{vi-command}; +@code{emacs} is equivalent to @code{emacs-standard}. + +@item -l +List the names of all Readline functions. + +@item -p +Display Readline function names and bindings in such a way that they +can be used as input or in a Readline initialization file. + +@item -P +List current Readline function names and bindings. + +@item -v +Display Readline variable names and values in such a way that they +can be used as input or in a Readline initialization file. + +@item -V +List current Readline variable names and values. + +@item -s +Display Readline key sequences bound to macros and the strings they output +in such a way that they can be used as input or in a Readline +initialization file. + +@item -S +Display Readline key sequences bound to macros and the strings they output. + +@item -f @var{filename} +Read key bindings from @var{filename}. + +@item -q @var{function} +Query about which keys invoke the named @var{function}. + +@item -u @var{function} +Unbind all keys bound to the named @var{function}. + +@item -r @var{keyseq} +Remove any current binding for @var{keyseq}. + +@item -x @var{keyseq:shell-command} +Cause @var{shell-command} to be executed whenever @var{keyseq} is +entered. +When @var{shell-command} is executed, the shell sets the +@code{READLINE_LINE} variable to the contents of the Readline line +buffer and the @code{READLINE_POINT} variable to the current location +of the insertion point. +If the executed command changes the value of @code{READLINE_LINE} or +@code{READLINE_POINT}, those new values will be reflected in the +editing state. +@end table + +@noindent +The return status is zero unless an invalid option is supplied or an +error occurs. + +@item builtin +@btindex builtin +@example +builtin [@var{shell-builtin} [@var{args}]] +@end example +Run a shell builtin, passing it @var{args}, and return its exit status. +This is useful when defining a shell function with the same +name as a shell builtin, retaining the functionality of the builtin within +the function. +The return status is non-zero if @var{shell-builtin} is not a shell +builtin command. + +@item caller +@btindex caller +@example +caller [@var{expr}] +@end example +Returns the context of any active subroutine call (a shell function or +a script executed with the @code{.} or @code{source} builtins). + +Without @var{expr}, @code{caller} displays the line number and source +filename of the current subroutine call. +If a non-negative integer is supplied as @var{expr}, @code{caller} +displays the line number, subroutine name, and source file corresponding +to that position in the current execution call stack. This extra +information may be used, for example, to print a stack trace. The +current frame is frame 0. + +The return value is 0 unless the shell is not executing a subroutine +call or @var{expr} does not correspond to a valid position in the +call stack. + +@item command +@btindex command +@example +command [-pVv] @var{command} [@var{arguments} @dots{}] +@end example +Runs @var{command} with @var{arguments} ignoring any shell function +named @var{command}. +Only shell builtin commands or commands found by searching the +@env{PATH} are executed. +If there is a shell function named @code{ls}, running @samp{command ls} +within the function will execute the external command @code{ls} +instead of calling the function recursively. +The @option{-p} option means to use a default value for @env{PATH} +that is guaranteed to find all of the standard utilities. +The return status in this case is 127 if @var{command} cannot be +found or an error occurred, and the exit status of @var{command} +otherwise. + +If either the @option{-V} or @option{-v} option is supplied, a +description of @var{command} is printed. The @option{-v} option +causes a single word indicating the command or file name used to +invoke @var{command} to be displayed; the @option{-V} option produces +a more verbose description. In this case, the return status is +zero if @var{command} is found, and non-zero if not. + +@item declare +@btindex declare +@example +declare [-aAfFilrtux] [-p] [@var{name}[=@var{value}] @dots{}] +@end example + +Declare variables and give them attributes. If no @var{name}s +are given, then display the values of variables instead. + +The @option{-p} option will display the attributes and values of each +@var{name}. +When @option{-p} is used with @var{name} arguments, additional options +are ignored. + +When @option{-p} is supplied without @var{name} arguments, @code{declare} +will display the attributes and values of all variables having the +attributes specified by the additional options. +If no other options are supplied with @option{-p}, @code{declare} will +display the attributes and values of all shell variables. The @option{-f} +option will restrict the display to shell functions. + +The @option{-F} option inhibits the display of function definitions; +only the function name and attributes are printed. +If the @code{extdebug} shell option is enabled using @code{shopt} +(@pxref{The Shopt Builtin}), the source file name and line number where +the function is defined are displayed as well. +@option{-F} implies @option{-f}. +The following options can be used to restrict output to variables with +the specified attributes or to give variables attributes: + +@table @code +@item -a +Each @var{name} is an indexed array variable (@pxref{Arrays}). + +@item -A +Each @var{name} is an associative array variable (@pxref{Arrays}). + +@item -f +Use function names only. + +@item -i +The variable is to be treated as +an integer; arithmetic evaluation (@pxref{Shell Arithmetic}) is +performed when the variable is assigned a value. + +@item -l +When the variable is assigned a value, all upper-case characters are +converted to lower-case. +The upper-case attribute is disabled. + +@item -r +Make @var{name}s readonly. These names cannot then be assigned values +by subsequent assignment statements or unset. + +@item -t +Give each @var{name} the @code{trace} attribute. +Traced functions inherit the @code{DEBUG} and @code{RETURN} traps from +the calling shell. +The trace attribute has no special meaning for variables. + +@item -u +When the variable is assigned a value, all lower-case characters are +converted to upper-case. +The lower-case attribute is disabled. + +@item -x +Mark each @var{name} for export to subsequent commands via +the environment. +@end table + +Using @samp{+} instead of @samp{-} turns off the attribute instead, +with the exceptions that @samp{+a} +may not be used to destroy an array variable and @samp{+r} will not +remove the readonly attribute. +When used in a function, @code{declare} makes each @var{name} local, +as with the @code{local} command. If a variable name is followed by +=@var{value}, the value of the variable is set to @var{value}. + +The return status is zero unless an invalid option is encountered, +an attempt is made to define a function using @samp{-f foo=bar}, +an attempt is made to assign a value to a readonly variable, +an attempt is made to assign a value to an array variable without +using the compound assignment syntax (@pxref{Arrays}), +one of the @var{names} is not a valid shell variable name, +an attempt is made to turn off readonly status for a readonly variable, +an attempt is made to turn off array status for an array variable, +or an attempt is made to display a non-existent function with @option{-f}. + +@item echo +@btindex echo +@example +echo [-neE] [@var{arg} @dots{}] +@end example +Output the @var{arg}s, separated by spaces, terminated with a +newline. +The return status is always 0. +If @option{-n} is specified, the trailing newline is suppressed. +If the @option{-e} option is given, interpretation of the following +backslash-escaped characters is enabled. +The @option{-E} option disables the interpretation of these escape characters, +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 +alert (bell) +@item \b +backspace +@item \c +suppress further output +@item \e +escape +@item \f +form feed +@item \n +new line +@item \r +carriage return +@item \t +horizontal tab +@item \v +vertical tab +@item \\ +backslash +@item \0@var{nnn} +the eight-bit character whose value is the octal value @var{nnn} +(zero to three octal digits) +@item \x@var{HH} +the eight-bit character whose value is the hexadecimal value @var{HH} +(one or two hex digits) +@end table + +@item enable +@btindex enable +@example +enable [-a] [-dnps] [-f @var{filename}] [@var{name} @dots{}] +@end example +Enable and disable builtin shell commands. +Disabling a builtin allows a disk command which has the same name +as a shell builtin to be executed without specifying a full pathname, +even though the shell normally searches for builtins before disk commands. +If @option{-n} is used, the @var{name}s become disabled. Otherwise +@var{name}s are enabled. For example, to use the @code{test} binary +found via @env{$PATH} instead of the shell builtin version, type +@samp{enable -n test}. + +If the @option{-p} option is supplied, or no @var{name} arguments appear, +a list of shell builtins is printed. With no other arguments, the list +consists of all enabled shell builtins. +The @option{-a} option means to list +each builtin with an indication of whether or not it is enabled. + +The @option{-f} option means to load the new builtin command @var{name} +from shared object @var{filename}, on systems that support dynamic loading. +The @option{-d} option will delete a builtin loaded with @option{-f}. + +If there are no options, a list of the shell builtins is displayed. +The @option{-s} option restricts @code{enable} to the @sc{posix} special +builtins. If @option{-s} is used with @option{-f}, the new builtin becomes +a special builtin (@pxref{Special Builtins}). + +The return status is zero unless a @var{name} is not a shell builtin +or there is an error loading a new builtin from a shared object. + +@item help +@btindex help +@example +help [-dms] [@var{pattern}] +@end example +Display helpful information about builtin commands. +If @var{pattern} is specified, @code{help} gives detailed help +on all commands matching @var{pattern}, otherwise a list of +the builtins is printed. + +Options, if supplied, have the following meanings: + +@table @code +@item -d +Display a short description of each @var{pattern} +@item -m +Display the description of each @var{pattern} in a manpage-like format +@item -s +Display only a short usage synopsis for each @var{pattern} +@end table + +The return status is zero unless no command matches @var{pattern}. + +@item let +@btindex let +@example +let @var{expression} [@var{expression}] +@end example +The @code{let} builtin allows arithmetic to be performed on shell +variables. Each @var{expression} is evaluated according to the +rules given below in @ref{Shell Arithmetic}. If the +last @var{expression} evaluates to 0, @code{let} returns 1; +otherwise 0 is returned. + +@item local +@btindex local +@example +local [@var{option}] @var{name}[=@var{value}] @dots{} +@end example +For each argument, a local variable named @var{name} is created, +and assigned @var{value}. +The @var{option} can be any of the options accepted by @code{declare}. +@code{local} can only be used within a function; it makes the variable +@var{name} have a visible scope restricted to that function and its +children. The return status is zero unless @code{local} is used outside +a function, an invalid @var{name} is supplied, or @var{name} is a +readonly variable. + +@item logout +@btindex logout +@example +logout [@var{n}] +@end example +Exit a login shell, returning a status of @var{n} to the shell's +parent. + +@item mapfile +@btindex mapfile +@example +mapfile [-n @var{count}] [-O @var{origin}] [-s @var{count}] [-t] [-u @var{fd}] [ +-C @var{callback}] [-c @var{quantum}] [@var{array}] +@end example +Read lines from the standard input into the indexed array variable @var{array}, +or from file descriptor @var{fd} +if the @option{-u} option is supplied. +The variable @code{MAPFILE} is the default @var{array}. +Options, if supplied, have the following meanings: +@table @code + +@item -n +Copy at most @var{count} lines. If @var{count} is 0, all lines are copied. +@item -O +Begin assigning to @var{array} at index @var{origin}. +The default index is 0. +@item -s +Discard the first @var{count} lines read. +@item -t +Remove a trailing newline from each line read. +@item -u +Read lines from file descriptor @var{fd} instead of the standard input. +@item -C +Evaluate @var{callback} each time @var{quantum}P lines are read. +The @option{-c} option specifies @var{quantum}. +@item -c +Specify the number of lines read between each call to @var{callback}. +@end table + +If @option{-C} is specified without @option{-c}, +the default quantum is 5000. +When @var{callback} is evaluated, it is supplied the index of the next +array element to be assigned as an additional argument. +@var{callback} is evaluated after the line is read but before the +array element is assigned. + +If not supplied with an explicit origin, @code{mapfile} will clear @var{array} +before assigning to it. + +@code{mapfile} returns successfully unless an invalid option or option +argument is supplied, @var{array} is invalid or unassignable, or @var{array} +is not an indexed array. + +@item printf +@btindex printf +@example +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}. +The @var{format} is a character string which contains three types of objects: +plain characters, which are simply copied to standard output, character +escape sequences, which are converted and copied to the standard output, and +format specifications, each of which causes printing of the next successive +@var{argument}. +In addition to the standard @code{printf(1)} formats, @samp{%b} causes +@code{printf} to expand backslash escape sequences in the corresponding +@var{argument}, +(except that @samp{\c} terminates output, backslashes in +@samp{\'}, @samp{\"}, and @samp{\?} are not removed, and octal escapes +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 +appropriate, had been supplied. The return value is zero on success, +non-zero on failure. + +@item read +@btindex read +@example +read [-ers] [-a @var{aname}] [-d @var{delim}] [-i @var{text}] [-n @var{nchars}] [-N @var{nchars}] [-p @var{prompt}] [-t @var{timeout}] [-u @var{fd}] [@var{name} @dots{}] +@end example +One line is read from the standard input, or from the file descriptor +@var{fd} supplied as an argument to the @option{-u} option, and the first word +is assigned to the first @var{name}, the second word to the second @var{name}, +and so on, with leftover words and their intervening separators assigned +to the last @var{name}. +If there are fewer words read from the input stream than names, +the remaining names are assigned empty values. +The characters in the value of the @env{IFS} variable +are used to split the line into words. +The backslash character @samp{\} may be used to remove any special +meaning for the next character read and for line continuation. +If no names are supplied, the line read is assigned to the +variable @env{REPLY}. +The return code is zero, unless end-of-file is encountered, @code{read} +times out (in which case the return code is greater than 128), or an +invalid file descriptor is supplied as the argument to @option{-u}. + +Options, if supplied, have the following meanings: + +@table @code +@item -a @var{aname} +The words are assigned to sequential indices of the array variable +@var{aname}, starting at 0. +All elements are removed from @var{aname} before the assignment. +Other @var{name} arguments are ignored. + +@item -d @var{delim} +The first character of @var{delim} is used to terminate the input line, +rather than newline. + +@item -e +Readline (@pxref{Command Line Editing}) is used to obtain the line. +Readline uses the current (or default, if line editing was not previously +active) editing settings. + +@item -i @var{text} +If Readline is being used to read the line, @var{text} is placed into +the editing buffer before editing begins. + +@item -n @var{nchars} +@code{read} returns after reading @var{nchars} characters rather than +waiting for a complete line of input, but honor a delimiter if fewer +than @var{nchars} characters are read before the delimiter. + +@item -N @var{nchars} +@code{read} returns after reading exactly @var{nchars} characters rather +than waiting for a complete line of input, unless EOF is encountered or +@code{read} times out. +Delimiter characters encountered in the input are +not treated specially and do not cause @code{read} to return until +@var{nchars} characters are read. + +@item -p @var{prompt} +Display @var{prompt}, without a trailing newline, before attempting +to read any input. +The prompt is displayed only if input is coming from a terminal. + +@item -r +If this option is given, backslash does not act as an escape character. +The backslash is considered to be part of the line. +In particular, a backslash-newline pair may not be used as a line +continuation. + +@item -s +Silent mode. If input is coming from a terminal, characters are +not echoed. + +@item -t @var{timeout} +Cause @code{read} to time out and return failure if a complete line of +input is not read within @var{timeout} seconds. +@var{timeout} may be a decimal number with a fractional portion following +the decimal point. +This option is only effective if @code{read} is reading input from a +terminal, pipe, or other special file; it has no effect when reading +from regular files. +If @var{timeout} is 0, @code{read} returns success if input is available on +the specified file descriptor, failure otherwise. +The exit status is greater than 128 if the timeout is exceeded. + +@item -u @var{fd} +Read input from file descriptor @var{fd}. + +@end table + +@item readarray +@btindex readarray +@example +readarray [-n @var{count}] [-O @var{origin}] [-s @var{count}] [-t] [-u @var{fd}] [ +-C @var{callback}] [-c @var{quantum}] [@var{array}] +@end example +Read lines from the standard input into the indexed array variable @var{array}, +or from file descriptor @var{fd} +if the @option{-u} option is supplied. + +A synonym for @code{mapfile}. + +@item source +@btindex source +@example +source @var{filename} +@end example +A synonym for @code{.} (@pxref{Bourne Shell Builtins}). + +@item type +@btindex type +@example +type [-afptP] [@var{name} @dots{}] +@end example +For each @var{name}, indicate how it would be interpreted if used as a +command name. + +If the @option{-t} option is used, @code{type} prints a single word +which is one of @samp{alias}, @samp{function}, @samp{builtin}, +@samp{file} or @samp{keyword}, +if @var{name} is an alias, shell function, shell builtin, +disk file, or shell reserved word, respectively. +If the @var{name} is not found, then nothing is printed, and +@code{type} returns a failure status. + +If the @option{-p} option is used, @code{type} either returns the name +of the disk file that would be executed, or nothing if @option{-t} +would not return @samp{file}. + +The @option{-P} option forces a path search for each @var{name}, even if +@option{-t} would not return @samp{file}. + +If a command is hashed, @option{-p} and @option{-P} print the hashed value, +not necessarily the file that appears first in @code{$PATH}. + +If the @option{-a} option is used, @code{type} returns all of the places +that contain an executable named @var{file}. +This includes aliases and functions, if and only if the @option{-p} option +is not also used. + +If the @option{-f} option is used, @code{type} does not attempt to find +shell functions, as with the @code{command} builtin. + +The return status is zero if all of the @var{names} are found, non-zero +if any are not found. + +@item typeset +@btindex typeset +@example +typeset [-afFrxi] [-p] [@var{name}[=@var{value}] @dots{}] +@end example +The @code{typeset} command is supplied for compatibility with the Korn +shell; however, it has been deprecated in favor of the @code{declare} +builtin command. + +@item ulimit +@btindex ulimit +@example +ulimit [-abcdefilmnpqrstuvxHST] [@var{limit}] +@end example +@code{ulimit} provides control over the resources available to processes +started by the shell, on systems that allow such control. If an +option is given, it is interpreted as follows: +@table @code +@item -S +Change and report the soft limit associated with a resource. + +@item -H +Change and report the hard limit associated with a resource. + +@item -a +All current limits are reported. + +@item -b +The maximum socket buffer size. + +@item -c +The maximum size of core files created. + +@item -d +The maximum size of a process's data segment. + +@item -e +The maximum scheduling priority ("nice"). + +@item -f +The maximum size of files written by the shell and its children. + +@item -i +The maximum number of pending signals. + +@item -l +The maximum size that may be locked into memory. + +@item -m +The maximum resident set size (many systems do not honor this limit). + +@item -n +The maximum number of open file descriptors (most systems do not +allow this value to be set). + +@item -p +The pipe buffer size. + +@item -q +The maximum number of bytes in POSIX message queues. + +@item -r +The maximum real-time scheduling priority. + +@item -s +The maximum stack size. + +@item -t +The maximum amount of cpu time in seconds. + +@item -u +The maximum number of processes available to a single user. + +@item -v +The maximum amount of virtual memory available to the process. + +@item -x +The maximum number of file locks. + +@item -T +The maximum number of threads. + +@end table + +If @var{limit} is given, it is the new value of the specified resource; +the special @var{limit} values @code{hard}, @code{soft}, and +@code{unlimited} stand for the current hard limit, the current soft limit, +and no limit, respectively. +A hard limit cannot be increased by a non-root user once it is set; +a soft limit may be increased up to the value of the hard limit. +Otherwise, the current value of the soft limit for the specified resource +is printed, unless the @option{-H} option is supplied. +When setting new limits, if neither @option{-H} nor @option{-S} is supplied, +both the hard and soft limits are set. +If no option is given, then @option{-f} is assumed. Values are in 1024-byte +increments, except for @option{-t}, which is in seconds, @option{-p}, +which is in units of 512-byte blocks, and @option{-n} and @option{-u}, which +are unscaled values. + +The return status is zero unless an invalid option or argument is supplied, +or an error occurs while setting a new limit. + +@item unalias +@btindex unalias +@example +unalias [-a] [@var{name} @dots{} ] +@end example + +Remove each @var{name} from the list of aliases. If @option{-a} is +supplied, all aliases are removed. +Aliases are described in @ref{Aliases}. + +@end table + +@node Modifying Shell Behavior +@section Modifying Shell Behavior + +@menu +* The Set Builtin:: Change the values of shell attributes and + positional parameters. +* The Shopt Builtin:: Modify shell optional behavior. +@end menu + +@node The Set Builtin +@subsection The Set Builtin + +This builtin is so complicated that it deserves its own section. @code{set} +allows you to change the values of shell options and set the positional +parameters, or to display the names and values of shell variables. + +@table @code +@item set +@btindex set +@example +set [--abefhkmnptuvxBCEHPT] [-o @var{option}] [@var{argument} @dots{}] +set [+abefhkmnptuvxBCEHPT] [+o @var{option}] [@var{argument} @dots{}] +@end example + +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 +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: + +@table @code +@item -a +Mark variables and function which are modified or created for export +to the environment of subsequent commands. + +@item -b +Cause the status of terminated background jobs to be reported +immediately, rather than before printing the next primary prompt. + +@item -e +Exit immediately if a pipeline (@pxref{Pipelines}), which may consist +of a single simple command (@pxref{Simple Commands}), +a subshell command enclosed in parentheses (@pxref{Command Grouping}), +or one of the commands executed as part of a command list enclosed +by braces (@pxref{Command Grouping}) +returns a non-zero status. +The shell does not exit if the command that fails is part of the +command list immediately following a @code{while} or @code{until} keyword, +part of the test in an @code{if} statement, +part of any command executed in a @code{&&} or @code{||} list except +the command following the final @code{&&} or @code{||}, +any command in a pipeline but the last, +or if the command's return status is being inverted with @code{!}. +A trap on @code{ERR}, if set, is executed before the shell exits. + +This option applies to the shell environment and each subshell environment +separately (@pxref{Command Execution Environment}), and may cause +subshells to exit before executing all the commands in the subshell. + +@item -f +Disable filename expansion (globbing). + +@item -h +Locate and remember (hash) commands as they are looked up for execution. +This option is enabled by default. + +@item -k +All arguments in the form of assignment statements are placed +in the environment for a command, not just those that precede +the command name. + +@item -m +Job control is enabled (@pxref{Job Control}). + +@item -n +Read commands but do not execute them; this may be used to check a +script for syntax errors. +This option is ignored by interactive shells. + +@item -o @var{option-name} + +Set the option corresponding to @var{option-name}: + +@table @code +@item allexport +Same as @code{-a}. + +@item braceexpand +Same as @code{-B}. + +@item emacs +Use an @code{emacs}-style line editing interface (@pxref{Command Line Editing}). +This also affects the editing interface used for @code{read -e}. + +@item errexit +Same as @code{-e}. + +@item errtrace +Same as @code{-E}. + +@item functrace +Same as @code{-T}. + +@item hashall +Same as @code{-h}. + +@item histexpand +Same as @code{-H}. + +@item history +Enable command history, as described in @ref{Bash History Facilities}. +This option is on by default in interactive shells. + +@item ignoreeof +An interactive shell will not exit upon reading EOF. + +@item keyword +Same as @code{-k}. + +@item monitor +Same as @code{-m}. + +@item noclobber +Same as @code{-C}. + +@item noexec +Same as @code{-n}. + +@item noglob +Same as @code{-f}. + +@item nolog +Currently ignored. + +@item notify +Same as @code{-b}. + +@item nounset +Same as @code{-u}. + +@item onecmd +Same as @code{-t}. + +@item physical +Same as @code{-P}. + +@item pipefail +If set, the return value of a pipeline is the value of the last +(rightmost) command to exit with a non-zero status, or zero if all +commands in the pipeline exit successfully. +This option is disabled by default. + +@item posix +Change the behavior of Bash where the default operation differs +from the @sc{posix} standard to match the standard +(@pxref{Bash POSIX Mode}). +This is intended to make Bash behave as a strict superset of that +standard. + +@item privileged +Same as @code{-p}. + +@item verbose +Same as @code{-v}. + +@item vi +Use a @code{vi}-style line editing interface. +This also affects the editing interface used for @code{read -e}. + +@item xtrace +Same as @code{-x}. +@end table + +@item -p +Turn on privileged mode. +In this mode, the @env{$BASH_ENV} and @env{$ENV} files are not +processed, shell functions are not inherited from the environment, +and the @env{SHELLOPTS}, @env{BASHOPTS}, @env{CDPATH} and @env{GLOBIGNORE} +variables, if they appear in the environment, are ignored. +If the shell is started with the effective user (group) id not equal to the +real user (group) id, and the @code{-p} option is not supplied, these actions +are taken and the effective user id is set to the real user id. +If the @code{-p} option is supplied at startup, the effective user id is +not reset. +Turning this option off causes the effective user +and group ids to be set to the real user and group ids. + +@item -t +Exit after reading and executing one command. + +@item -u +Treat unset variables and parameters other than the special parameters +@samp{@@} or @samp{*} as an error when performing parameter expansion. +An error message will be written to the standard error, and a non-interactive +shell will exit. + +@item -v +Print shell input lines as they are read. + +@item -x +Print a trace of simple commands, @code{for} commands, @code{case} +commands, @code{select} commands, and arithmetic @code{for} commands +and their arguments or associated word lists after they are +expanded and before they are executed. The value of the @env{PS4} +variable is expanded and the resultant value is printed before +the command and its expanded arguments. + +@item -B +The shell will perform brace expansion (@pxref{Brace Expansion}). +This option is on by default. + +@item -C +Prevent output redirection using @samp{>}, @samp{>&}, and @samp{<>} +from overwriting existing files. + +@item -E +If set, any trap on @code{ERR} is inherited by shell functions, command +substitutions, and commands executed in a subshell environment. +The @code{ERR} trap is normally not inherited in such cases. + +@item -H +Enable @samp{!} style history substitution (@pxref{History Interaction}). +This option is on by default for interactive shells. + +@item -P +If set, do not follow symbolic links when performing commands such as +@code{cd} which change the current directory. The physical directory +is used instead. By default, Bash follows +the logical chain of directories when performing commands +which change the current directory. + +For example, if @file{/usr/sys} is a symbolic link to @file{/usr/local/sys} +then: +@example +$ cd /usr/sys; echo $PWD +/usr/sys +$ cd ..; pwd +/usr +@end example + +@noindent +If @code{set -P} is on, then: +@example +$ cd /usr/sys; echo $PWD +/usr/local/sys +$ cd ..; pwd +/usr/local +@end example + +@item -T +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 +unset. Otherwise, the positional parameters are set to the +@var{arguments}, even if some of them begin with a @samp{-}. + +@item - +Signal the end of options, cause all remaining @var{arguments} +to be assigned to the positional parameters. The @option{-x} +and @option{-v} options are turned off. +If there are no arguments, the positional parameters remain unchanged. +@end table + +Using @samp{+} rather than @samp{-} causes these options to be +turned off. The options can also be used upon invocation of the +shell. The current set of options may be found in @code{$-}. + +The remaining N @var{arguments} are positional parameters and are +assigned, in order, to @code{$1}, @code{$2}, @dots{} @code{$N}. +The special parameter @code{#} is set to N. + +The return status is always zero unless an invalid option is supplied. +@end table + +@node The Shopt Builtin +@subsection The Shopt Builtin + +This builtin allows you to change additional shell optional behavior. + +@table @code + +@item shopt +@btindex shopt +@example +shopt [-pqsu] [-o] [@var{optname} @dots{}] +@end example +Toggle the values of variables controlling optional shell behavior. +With no options, or with the @option{-p} option, a list of all settable +options is displayed, with an indication of whether or not each is set. +The @option{-p} option causes output to be displayed in a form that +may be reused as input. +Other options have the following meanings: + +@table @code +@item -s +Enable (set) each @var{optname}. + +@item -u +Disable (unset) each @var{optname}. + +@item -q +Suppresses normal output; the return status +indicates whether the @var{optname} is set or unset. +If multiple @var{optname} arguments are given with @option{-q}, +the return status is zero if all @var{optnames} are enabled; +non-zero otherwise. + +@item -o +Restricts the values of +@var{optname} to be those defined for the @option{-o} option to the +@code{set} builtin (@pxref{The Set Builtin}). +@end table + +If either @option{-s} or @option{-u} +is used with no @var{optname} arguments, the display is limited to +those options which are set or unset, respectively. + +Unless otherwise noted, the @code{shopt} options are disabled (off) +by default. + +The return status when listing options is zero if all @var{optnames} +are enabled, non-zero otherwise. When setting or unsetting options, +the return status is zero unless an @var{optname} is not a valid shell +option. + +The list of @code{shopt} options is: +@table @code + +@item autocd +If set, a command name that is the name of a directory is executed as if +it were the argument to the @code{cd} command. +This option is only used by interactive shells. + +@item cdable_vars +If this is set, an argument to the @code{cd} builtin command that +is not a directory is assumed to be the name of a variable whose +value is the directory to change to. + +@item cdspell +If set, minor errors in the spelling of a directory component in a +@code{cd} command will be corrected. +The errors checked for are transposed characters, +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 only used by interactive shells. + +@item checkhash +If this is set, Bash checks that a command found in the hash +table exists before trying to execute it. If a hashed command no +longer exists, a normal path search is performed. + +@item checkjobs +If set, Bash lists the status of any stopped and running jobs before +exiting an interactive shell. If any jobs are running, this causes +the exit to be deferred until a second exit is attempted without an +intervening command (@pxref{Job Control}). +The shell always postpones exiting if any jobs are stopped. + +@item checkwinsize +If set, Bash checks the window size after each command +and, if necessary, updates the values of +@env{LINES} and @env{COLUMNS}. + +@item cmdhist +If set, Bash +attempts to save all lines of a multiple-line +command in the same history entry. This allows +easy re-editing of multi-line commands. + +@item compat31 +If set, Bash +changes its behavior to that of version 3.1 with respect to quoted +arguments to the conditional command's =~ operator. + +@item dirspell +If set, Bash +attempts spelling correction on directory names during word completion +if the directory name initially supplied does not exist. + +@item dotglob +If set, Bash includes filenames beginning with a `.' in +the results of filename expansion. + +@item execfail +If this is set, a non-interactive shell will not exit if +it cannot execute the file specified as an argument to the @code{exec} +builtin command. An interactive shell does not exit if @code{exec} +fails. + +@item expand_aliases +If set, aliases are expanded as described below under Aliases, +@ref{Aliases}. +This option is enabled by default for interactive shells. + +@item extdebug +If set, behavior intended for use by debuggers is enabled: + +@enumerate +@item +The @option{-F} option to the @code{declare} builtin (@pxref{Bash Builtins}) +displays the source file name and line number corresponding to each function +name supplied as an argument. + +@item +If the command run by the @code{DEBUG} trap returns a non-zero value, the +next command is skipped and not executed. + +@item +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 +If set, the extended pattern matching features described above +(@pxref{Pattern Matching}) are enabled. + +@item extquote +If set, @code{$'@var{string}'} and @code{$"@var{string}"} quoting is +performed within @code{$@{@var{parameter}@}} expansions +enclosed in double quotes. This option is enabled by default. + +@item failglob +If set, patterns which fail to match filenames during filename expansion +result in an expansion error. + +@item force_fignore +If set, the suffixes specified by the @env{FIGNORE} shell variable +cause words to be ignored when performing word completion even if +the ignored words are the only possible completions. +@xref{Bash Variables}, for a description of @env{FIGNORE}. +This option is enabled by default. + +@item globstar +If set, the pattern @samp{**} used in a filename expansion context will +match a files and zero or more directories and subdirectories. +If the pattern is followed by a @samp{/}, only directories and +subdirectories match. + +@item gnu_errfmt +If set, shell error messages are written in the standard @sc{gnu} error +message format. + +@item histappend +If set, the history list is appended to the file named by the value +of the @env{HISTFILE} +variable when the shell exits, rather than overwriting the file. + +@item histreedit +If set, and Readline +is being used, a user is given the opportunity to re-edit a +failed history substitution. + +@item histverify +If set, and Readline +is being used, the results of history substitution are not immediately +passed to the shell parser. Instead, the resulting line is loaded into +the Readline editing buffer, allowing further modification. + +@item hostcomplete +If set, and Readline is being used, Bash will attempt to perform +hostname completion when a word containing a @samp{@@} is being +completed (@pxref{Commands For Completion}). This option is enabled +by default. + +@item huponexit +If set, Bash will send @code{SIGHUP} to all jobs when an interactive +login shell exits (@pxref{Signals}). + +@item interactive_comments +Allow a word beginning with @samp{#} +to cause that word and all remaining characters on that +line to be ignored in an interactive shell. +This option is enabled by default. + +@item lithist +If enabled, and the @code{cmdhist} +option is enabled, multi-line commands are saved to the history with +embedded newlines rather than using semicolon separators where possible. + +@item login_shell +The shell sets this option if it is started as a login shell +(@pxref{Invoking Bash}). +The value may not be changed. + +@item mailwarn +If set, and a file that Bash is checking for mail has been +accessed since the last time it was checked, the message +@code{"The mail in @var{mailfile} has been read"} is displayed. + +@item no_empty_cmd_completion +If set, and Readline is being used, Bash will not attempt to search +the @env{PATH} for possible completions when completion is attempted +on an empty line. + +@item nocaseglob +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. + +@item progcomp +If set, the programmable completion facilities +(@pxref{Programmable Completion}) are enabled. +This option is enabled by default. + +@item promptvars +If set, prompt strings undergo +parameter expansion, command substitution, arithmetic +expansion, and quote removal after being expanded +as described below (@pxref{Printing a Prompt}). +This option is enabled by default. + +@item restricted_shell +The shell sets this option if it is started in restricted mode +(@pxref{The Restricted Shell}). +The value may not be changed. +This is not reset when the startup files are executed, allowing +the startup files to discover whether or not a shell is restricted. + +@item shift_verbose +If this is set, the @code{shift} +builtin prints an error message when the shift count exceeds the +number of positional parameters. + +@item sourcepath +If set, the @code{source} builtin uses the value of @env{PATH} +to find the directory containing the file supplied as an argument. +This option is enabled by default. + +@item xpg_echo +If set, the @code{echo} builtin expands backslash-escape sequences +by default. + +@end table + +@noindent +The return status when listing options is zero if all @var{optnames} +are enabled, non-zero otherwise. +When setting or unsetting options, the return status is zero unless an +@var{optname} is not a valid shell option. + +@end table + +@node Special Builtins +@section Special Builtins +@cindex special builtin + +For historical reasons, the @sc{posix} standard has classified +several builtin commands as @emph{special}. +When Bash is executing in @sc{posix} mode, the special builtins +differ from other builtin commands in three respects: + +@enumerate +@item +Special builtins are found before shell functions during command lookup. + +@item +If a special builtin returns an error status, a non-interactive shell exits. + +@item +Assignment statements preceding the command stay in effect in the shell +environment after the command completes. +@end enumerate + +When Bash is not executing in @sc{posix} mode, these builtins behave no +differently than the rest of the Bash builtin commands. +The Bash @sc{posix} mode is described in @ref{Bash POSIX Mode}. + +These are the @sc{posix} special builtins: +@example +@w{break : . continue eval exec exit export readonly return set} +@w{shift trap unset} +@end example + +@node Shell Variables +@chapter Shell Variables + +@menu +* Bourne Shell Variables:: Variables which Bash uses in the same way + as the Bourne Shell. +* Bash Variables:: List of variables that exist in Bash. +@end menu + +This chapter describes the shell variables that Bash uses. +Bash automatically assigns default values to a number of variables. + +@node Bourne Shell Variables +@section Bourne Shell Variables + +Bash uses certain shell variables in the same way as the Bourne shell. +In some cases, Bash assigns a default value to the variable. + +@vtable @code + +@item CDPATH +A colon-separated list of directories used as a search path for +the @code{cd} builtin command. + +@item HOME +The current user's home directory; the default for the @code{cd} builtin +command. +The value of this variable is also used by tilde expansion +(@pxref{Tilde Expansion}). + +@item IFS +A list of characters that separate fields; used when the shell splits +words as part of expansion. + +@item MAIL +If this parameter is set to a filename and the @env{MAILPATH} variable +is not set, Bash informs the user of the arrival of mail in +the specified file. + +@item MAILPATH +A colon-separated list of filenames which the shell periodically checks +for new mail. +Each list entry can specify the message that is printed when new mail +arrives in the mail file by separating the file name from the message with +a @samp{?}. +When used in the text of the message, @code{$_} expands to the name of +the current mail file. + +@item OPTARG +The value of the last option argument processed by the @code{getopts} builtin. + +@item OPTIND +The index of the last option argument processed by the @code{getopts} builtin. + +@item PATH +A colon-separated list of directories in which the shell looks for +commands. +A zero-length (null) directory name in the value of @code{PATH} indicates the +current directory. +A null directory name may appear as two adjacent colons, or as an initial +or trailing colon. + + +@item PS1 +The primary prompt string. The default value is @samp{\s-\v\$ }. +@xref{Printing a Prompt}, for the complete list of escape +sequences that are expanded before @env{PS1} is displayed. + +@item PS2 +The secondary prompt string. The default value is @samp{> }. + +@end vtable + +@node Bash Variables +@section Bash Variables + +These variables are set or used by Bash, but other shells +do not normally treat them specially. + +A few variables used by Bash are described in different chapters: +variables for controlling the job control facilities +(@pxref{Job Control Variables}). + +@vtable @code + +@item BASH +The full pathname used to execute the current instance of Bash. + +@item BASHOPTS +A colon-separated list of enabled shell options. Each word in +the list is a valid argument for the @option{-s} option to the +@code{shopt} builtin command (@pxref{The Shopt Builtin}). +The options appearing in @env{BASHOPTS} are those reported +as @samp{on} by @samp{shopt}. +If this variable is in the environment when Bash +starts up, each shell option in the list will be enabled before +reading any startup files. This variable is readonly. + +@item BASHPID +Expands to the process id of the current Bash process. +This differs from @code{$$} under certain circumstances, such as subshells +that do not require Bash to be re-initialized. + +@item BASH_ALIASES +An associative array variable whose members correspond to the internal +list of aliases as maintained by the @code{alias} builtin +(@pxref{Bourne Shell Builtins}). +Elements added to this array appear in the alias list; unsetting array +elements cause aliases to be removed from the alias list. + +@item 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 +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{The Shopt Builtin} +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 +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{The Shopt Builtin} +for a description of the @code{extdebug} option to the @code{shopt} +builtin). + +@item BASH_CMDS +An associative array variable whose members correspond to the internal +hash table of commands as maintained by the @code{hash} builtin +(@pxref{Bourne Shell Builtins}). +Elements added to this array appear in the hash table; unsetting array +elements cause commands to be removed from the hash table. + +@item BASH_COMMAND +The command currently being executed or about to be executed, unless the +shell is executing a command as the result of a trap, +in which case it is the command executing at the time of the trap. + +@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 BASH_EXECUTION_STRING +The command argument to the @option{-c} invocation option. + +@item BASH_LINENO +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]@}} was called (or @code{$@{BASH_LINENO[$i-1]@}} if +referenced within another shell function). +The corresponding source file name is @code{$@{BASH_SOURCE[$i]@}}. +Use @code{LINENO} to obtain the current line number. + +@item BASH_REMATCH +An array variable whose members are assigned by the @samp{=~} binary +operator to the @code{[[} conditional command +(@pxref{Conditional Constructs}). +The element with index 0 is the portion of the string +matching the entire regular expression. +The element with index @var{n} is the portion of the +string matching the @var{n}th parenthesized subexpression. +This variable is read-only. + +@item BASH_SOURCE +An array variable whose members are the source filenames corresponding +to the elements in the @code{FUNCNAME} array variable. + +@item BASH_SUBSHELL +Incremented by one each time a subshell or subshell environment is spawned. +The initial value is 0. + +@item BASH_VERSINFO +A readonly array variable (@pxref{Arrays}) +whose members hold version information for this instance of Bash. +The values assigned to the array members are as follows: + +@table @code + +@item BASH_VERSINFO[0] +The major version number (the @var{release}). + +@item BASH_VERSINFO[1] +The minor version number (the @var{version}). + +@item BASH_VERSINFO[2] +The patch level. + +@item BASH_VERSINFO[3] +The build version. + +@item BASH_VERSINFO[4] +The release status (e.g., @var{beta1}). + +@item BASH_VERSINFO[5] +The value of @env{MACHTYPE}. + +@end table + +@item BASH_VERSION +The version number of the current instance of Bash. + +@item BASH_XTRACEFD +If set to an integer corresponding to a valid file descriptor, Bash +will write the trace output generated when @samp{set -x} +is enabled to that file descriptor. +This allows tracing output to be separated from diagnostic and error +messages. +The file descriptor is closed when @code{BASH_XTRACEFD} is unset or assigned +a new value. +Unsetting @code{BASH_XTRACEFD} or assigning it the empty string causes the +trace output to be sent to the standard error. +Note that setting @code{BASH_XTRACEFD} to 2 (the standard error file +descriptor) and then unsetting it will result in the standard error +being closed. + +@item COLUMNS +Used by the @code{select} builtin command to determine the terminal width +when printing selection lists. Automatically set upon receipt of a +@code{SIGWINCH}. + +@item COMP_CWORD +An index into @env{$@{COMP_WORDS@}} of the word containing the current +cursor position. +This variable is available only in shell functions invoked by the +programmable completion facilities (@pxref{Programmable Completion}). + +@item COMP_LINE +The current command line. +This variable is available only in shell functions and external +commands invoked by the +programmable completion facilities (@pxref{Programmable Completion}). + +@item COMP_POINT +The index of the current cursor position relative to the beginning of +the current command. +If the current cursor position is at the end of the current command, +the value of this variable is equal to @code{$@{#COMP_LINE@}}. +This variable is available only in shell functions and external +commands invoked by the +programmable completion facilities (@pxref{Programmable Completion}). + +@item COMP_TYPE +Set to an integer value corresponding to the type of completion attempted +that caused a completion function to be called: +@var{TAB}, for normal completion, +@samp{?}, for listing completions after successive tabs, +@samp{!}, for listing alternatives on partial word completion, +@samp{@@}, to list completions if the word is not unmodified, +or +@samp{%}, for menu completion. +This variable is available only in shell functions and external +commands invoked by the +programmable completion facilities (@pxref{Programmable Completion}). + +@item COMP_KEY +The key (or final key of a key sequence) used to invoke the current +completion function. + +@item COMP_WORDBREAKS +The set of characters that the Readline library treats as word +separators when performing word completion. +If @code{COMP_WORDBREAKS} is unset, it loses its special properties, +even if it is subsequently reset. + +@item COMP_WORDS +An array variable consisting of the individual +words in the current command line. +The line is split into words as Readline would split it, using +@code{COMP_WORDBREAKS} as described above. +This variable is available only in shell functions invoked by the +programmable completion facilities (@pxref{Programmable Completion}). + +@item COMPREPLY +An array variable from which Bash reads the possible completions +generated by a shell function invoked by the programmable completion +facility (@pxref{Programmable Completion}). + +@item DIRSTACK +An array variable containing the current contents of the directory stack. +Directories appear in the stack in the order they are displayed by the +@code{dirs} builtin. +Assigning to members of this array variable may be used to modify +directories already in the stack, but the @code{pushd} and @code{popd} +builtins must be used to add and remove directories. +Assignment to this variable will not change the current directory. +If @env{DIRSTACK} is unset, it loses its special properties, even if +it is subsequently reset. + +@item EMACS +If Bash finds this variable in the environment when the shell +starts with value @samp{t}, it assumes that the shell is running in an +emacs shell buffer and disables line editing. + +@item EUID +The numeric effective user id of the current user. This variable +is readonly. + +@item FCEDIT +The editor used as a default by the @option{-e} option to the @code{fc} +builtin command. + +@item FIGNORE +A colon-separated list of suffixes to ignore when performing +filename completion. +A file name whose suffix matches one of the entries in +@env{FIGNORE} +is excluded from the list of matched file names. A sample +value is @samp{.o:~} + +@item FUNCNAME +An array variable containing the names of all shell functions +currently in the execution call stack. +The element with index 0 is the name of any currently-executing +shell function. +The bottom-most element is @code{"main"}. +This variable exists only when a shell function is executing. +Assignments to @env{FUNCNAME} have no effect and return an error status. +If @env{FUNCNAME} is unset, it loses its special properties, even if +it is subsequently reset. + +@item GLOBIGNORE +A colon-separated list of patterns defining the set of filenames to +be ignored by filename expansion. +If a filename matched by a filename expansion pattern also matches one +of the patterns in @env{GLOBIGNORE}, it is removed from the list +of matches. + +@item GROUPS +An array variable containing the list of groups of which the current +user is a member. +Assignments to @env{GROUPS} have no effect and return an error status. +If @env{GROUPS} is unset, it loses its special properties, even if it is +subsequently reset. + +@item histchars +Up to three characters which control history expansion, quick +substitution, and tokenization (@pxref{History Interaction}). +The first character is the +@var{history expansion} character, that is, the character which signifies the +start of a history expansion, normally @samp{!}. The second character is the +character which signifies `quick substitution' when seen as the first +character on a line, normally @samp{^}. The optional third character is the +character which indicates that the remainder of the line is a comment when +found as the first character of a word, usually @samp{#}. The history +comment character causes history substitution to be skipped for the +remaining words on the line. It does not necessarily cause the shell +parser to treat the rest of the line as a comment. + +@item HISTCMD +The history number, or index in the history list, of the current +command. If @env{HISTCMD} is unset, it loses its special properties, +even if it is subsequently reset. + +@item HISTCONTROL +A colon-separated list of values controlling how commands are saved on +the history list. +If the list of values includes @samp{ignorespace}, lines which begin +with a space character are not saved in the history list. +A value of @samp{ignoredups} causes lines which match the previous +history entry to not be saved. +A value of @samp{ignoreboth} is shorthand for +@samp{ignorespace} and @samp{ignoredups}. +A value of @samp{erasedups} causes all previous lines matching the +current line to be removed from the history list before that line +is saved. +Any value not in the above list is ignored. +If @env{HISTCONTROL} is unset, or does not include a valid value, +all lines read by the shell parser are saved on the history list, +subject to the value of @env{HISTIGNORE}. +The second and subsequent lines of a multi-line compound command are +not tested, and are added to the history regardless of the value of +@env{HISTCONTROL}. + +@item HISTFILE +The name of the file to which the command history is saved. The +default value is @file{~/.bash_history}. + +@item HISTFILESIZE +The maximum number of lines contained in the history file. When this +variable is assigned a value, the history file is truncated, if +necessary, by removing the oldest entries, +to contain no more than that number of lines. +The history file is also truncated to this size after +writing it when an interactive shell exits. +The default value is 500. + +@item HISTIGNORE +A colon-separated list of patterns used to decide which command +lines should be saved on the history list. Each pattern is +anchored at the beginning of the line and must match the complete +line (no implicit @samp{*} is appended). Each pattern is tested +against the line after the checks specified by @env{HISTCONTROL} +are applied. In addition to the normal shell pattern matching +characters, @samp{&} matches the previous history line. @samp{&} +may be escaped using a backslash; the backslash is removed +before attempting a match. +The second and subsequent lines of a multi-line compound command are +not tested, and are added to the history regardless of the value of +@env{HISTIGNORE}. + +@env{HISTIGNORE} subsumes the function of @env{HISTCONTROL}. A +pattern of @samp{&} is identical to @code{ignoredups}, and a +pattern of @samp{[ ]*} is identical to @code{ignorespace}. +Combining these two patterns, separating them with a colon, +provides the functionality of @code{ignoreboth}. + +@item HISTSIZE +The maximum number of commands to remember on the history list. +The default value is 500. + +@item HISTTIMEFORMAT +If this variable is set and not null, its value is used as a format string +for @var{strftime} to print the time stamp associated with each history +entry displayed by the @code{history} builtin. +If this variable is set, time stamps are written to the history file so +they may be preserved across shell sessions. +This uses the history comment character to distinguish timestamps from +other history lines. + +@item HOSTFILE +Contains the name of a file in the same format as @file{/etc/hosts} that +should be read when the shell needs to complete a hostname. +The list of possible hostname completions may be changed while the shell +is running; +the next time hostname completion is attempted after the +value is changed, Bash adds the contents of the new file to the +existing list. +If @env{HOSTFILE} is set, but has no value, or does not name a readable file, +Bash attempts to read +@file{/etc/hosts} to obtain the list of possible hostname completions. +When @env{HOSTFILE} is unset, the hostname list is cleared. + +@item HOSTNAME +The name of the current host. + +@item HOSTTYPE +A string describing the machine Bash is running on. + +@item IGNOREEOF +Controls the action of the shell on receipt of an @code{EOF} character +as the sole input. If set, the value denotes the number +of consecutive @code{EOF} characters that can be read as the +first character on an input line +before the shell will exit. If the variable exists but does not +have a numeric value (or has no value) then the default is 10. +If the variable does not exist, then @code{EOF} signifies the end of +input to the shell. This is only in effect for interactive shells. + +@item INPUTRC +The name of the Readline initialization file, overriding the default +of @file{~/.inputrc}. + +@item LANG +Used to determine the locale category for any category not specifically +selected with a variable starting with @code{LC_}. + +@item LC_ALL +This variable overrides the value of @env{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, and +determines the behavior of range expressions, equivalence classes, +and collating sequences within filename expansion and pattern matching +(@pxref{Filename Expansion}). + +@item LC_CTYPE +This variable determines the interpretation of characters and the +behavior of character classes within filename expansion and pattern +matching (@pxref{Filename Expansion}). + +@item LC_MESSAGES +This variable determines the locale used to translate double-quoted +strings preceded by a @samp{$} (@pxref{Locale Translation}). + +@item LC_NUMERIC +This variable determines the locale category used for number formatting. + +@item LINENO +The line number in the script or shell function currently executing. + +@item LINES +Used by the @code{select} builtin command to determine the column length +for printing selection lists. Automatically set upon receipt of a +@code{SIGWINCH}. + +@item MACHTYPE +A string that fully describes the system type on which Bash +is executing, in the standard @sc{gnu} @var{cpu-company-system} format. + +@item MAILCHECK +How often (in seconds) that the shell should check for mail in the +files specified in the @env{MAILPATH} or @env{MAIL} variables. +The default is 60 seconds. When it is time to check +for mail, the shell does so before displaying the primary prompt. +If this variable is unset, or set to a value that is not a number +greater than or equal to zero, the shell disables mail checking. + +@item OLDPWD +The previous working directory as set by the @code{cd} builtin. + +@item OPTERR +If set to the value 1, Bash displays error messages +generated by the @code{getopts} builtin command. + +@item OSTYPE +A string describing the operating system Bash is running on. + +@item PIPESTATUS +An array variable (@pxref{Arrays}) +containing a list of exit status values from the processes +in the most-recently-executed foreground pipeline (which may +contain only a single command). + +@item POSIXLY_CORRECT +If this variable is in the environment when @code{bash} starts, the shell +enters @sc{posix} mode (@pxref{Bash POSIX Mode}) before reading the +startup files, as if the @option{--posix} invocation option had been supplied. +If it is set while the shell is running, @code{bash} enables @sc{posix} mode, +as if the command +@example +@code{set -o posix} +@end example +@noindent +had been executed. + +@item PPID +The process @sc{id} of the shell's parent process. This variable +is readonly. + +@item PROMPT_COMMAND +If set, the value is interpreted as a command to execute +before the printing of each primary prompt (@env{$PS1}). + +@item PROMPT_DIRTRIM +If set to a number greater than zero, the value is used as the number of +trailing directory components to retain when expanding the @code{\w} and +@code{\W} prompt string escapes (@pxref{Printing a Prompt}). +Characters removed are replaced with an ellipsis. + +@item PS3 +The value of this variable is used as the prompt for the +@code{select} command. If this variable is not set, the +@code{select} command prompts with @samp{#? } + +@item PS4 +The value is the prompt printed before the command line is echoed +when the @option{-x} option is set (@pxref{The Set Builtin}). +The first character of @env{PS4} is replicated multiple times, as +necessary, to indicate multiple levels of indirection. +The default is @samp{+ }. + +@item PWD +The current working directory as set by the @code{cd} builtin. + +@item RANDOM +Each time this parameter is referenced, a random integer +between 0 and 32767 is generated. Assigning a value to this +variable seeds the random number generator. + +@item REPLY +The default variable for the @code{read} builtin. + +@item SECONDS +This variable expands to the number of seconds since the +shell was started. Assignment to this variable resets +the count to the value assigned, and the expanded value +becomes the value assigned plus the number of seconds +since the assignment. + +@item SHELL +The full pathname to the shell is kept in this environment variable. +If it is not set when the shell starts, +Bash assigns to it the full pathname of the current user's login shell. + +@item SHELLOPTS +A colon-separated list of enabled shell options. Each word in +the list is a valid argument for the @option{-o} option to the +@code{set} builtin command (@pxref{The Set Builtin}). +The options appearing in @env{SHELLOPTS} are those reported +as @samp{on} by @samp{set -o}. +If this variable is in the environment when Bash +starts up, each shell option in the list will be enabled before +reading any startup files. This variable is readonly. + +@item SHLVL +Incremented by one each time a new instance of Bash is started. This is +intended to be a count of how deeply your Bash shells are nested. + +@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} +reserved word should be displayed. +The @samp{%} character introduces an +escape sequence that is expanded to a time value or other +information. +The escape sequences and their meanings are as +follows; the braces denote optional portions. + +@table @code + +@item %% +A literal @samp{%}. + +@item %[@var{p}][l]R +The elapsed time in seconds. + +@item %[@var{p}][l]U +The number of CPU seconds spent in user mode. + +@item %[@var{p}][l]S +The number of CPU seconds spent in system mode. + +@item %P +The CPU percentage, computed as (%U + %S) / %R. +@end table + +The optional @var{p} is a digit specifying the precision, the number of +fractional digits after a decimal point. +A value of 0 causes no decimal point or fraction to be output. +At most three places after the decimal point may be specified; values +of @var{p} greater than 3 are changed to 3. +If @var{p} is not specified, the value 3 is used. + +The optional @code{l} specifies a longer format, including minutes, of +the form @var{MM}m@var{SS}.@var{FF}s. +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 TMOUT +If set to a value greater than zero, @code{TMOUT} is treated as the +default timeout for the @code{read} builtin (@pxref{Bash Builtins}). +The @code{select} command (@pxref{Conditional Constructs}) terminates +if input does not arrive after @code{TMOUT} seconds when input is coming +from a terminal. + +In an interactive shell, the value is interpreted as +the number of seconds to wait for input after issuing the primary +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. + +@end vtable + +@node Bash Features +@chapter Bash Features + +This section describes features unique to Bash. + +@menu +* Invoking Bash:: Command line options that you can give + to Bash. +* Bash Startup Files:: When and how Bash executes scripts. +* Interactive Shells:: What an interactive shell is. +* Bash Conditional Expressions:: Primitives used in composing expressions for + the @code{test} builtin. +* Shell Arithmetic:: Arithmetic on shell variables. +* Aliases:: Substituting one command for another. +* Arrays:: Array Variables. +* The Directory Stack:: History of visited directories. +* Printing a Prompt:: Controlling the PS1 string. +* The Restricted Shell:: A more controlled mode of shell execution. +* Bash POSIX Mode:: Making Bash behave more closely to what + the POSIX standard specifies. +@end menu + +@node Invoking Bash +@section Invoking Bash + +@example +bash [long-opt] [-ir] [-abefhkmnptuvxdBCDHP] [-o @var{option}] [-O @var{shopt_option}] [@var{argument} @dots{}] +bash [long-opt] [-abefhkmnptuvxdBCDHP] [-o @var{option}] [-O @var{shopt_option}] -c @var{string} [@var{argument} @dots{}] +bash [long-opt] -s [-abefhkmnptuvxdBCDHP] [-o @var{option}] [-O @var{shopt_option}] [@var{argument} @dots{}] +@end example + +In addition to the single-character shell command-line options +(@pxref{The Set Builtin}), there are several multi-character +options that you can use. These options must appear on the command +line before the single-character options to be recognized. + +@table @code +@item --debugger +Arrange for the debugger profile to be executed before the shell +starts. Turns on extended debugging mode (see @ref{The Shopt Builtin} +for a description of the @code{extdebug} option to the @code{shopt} +builtin) and shell function tracing +(see @ref{The Set Builtin} for a description of the @code{-o functrace} +option). + +@item --dump-po-strings +A list of all double-quoted strings preceded by @samp{$} +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. + +@item --dump-strings +Equivalent to @option{-D}. + +@item --help +Display a usage message on standard output and exit successfully. + +@item --init-file @var{filename} +@itemx --rcfile @var{filename} +Execute commands from @var{filename} (instead of @file{~/.bashrc}) +in an interactive shell. + +@item --login +Equivalent to @option{-l}. + +@item --noediting +Do not use the @sc{gnu} Readline library (@pxref{Command Line Editing}) +to read command lines when the shell is interactive. + +@item --noprofile +Don't load the system-wide startup file @file{/etc/profile} +or any of the personal initialization files +@file{~/.bash_profile}, @file{~/.bash_login}, or @file{~/.profile} +when Bash is invoked as a login shell. + +@item --norc +Don't read the @file{~/.bashrc} initialization file in an +interactive shell. This is on by default if the shell is +invoked as @code{sh}. + +@item --posix +Change the behavior of Bash where the default operation differs +from the @sc{posix} standard to match the standard. This +is intended to make Bash behave as a strict superset of that +standard. @xref{Bash POSIX Mode}, for a description of the Bash +@sc{posix} mode. + +@item --restricted +Make the shell a restricted shell (@pxref{The Restricted Shell}). + +@item --verbose +Equivalent to @option{-v}. Print shell input lines as they're read. + +@item --version +Show version information for this instance of +Bash on the standard output and exit successfully. + +@end table + +There are several single-character options that may be supplied at +invocation which are not available with the @code{set} builtin. + +@table @code +@item -c @var{string} +Read and execute commands from @var{string} after processing the +options, then exit. Any remaining arguments are assigned to the +positional parameters, starting with @code{$0}. + +@item -i +Force the shell to run interactively. Interactive shells are +described in @ref{Interactive Shells}. + +@item -l +Make this shell act as if it had been directly invoked by login. +When the shell is interactive, this is equivalent to starting a +login shell with @samp{exec -l bash}. +When the shell is not interactive, the login shell startup files will +be executed. +@samp{exec bash -l} or @samp{exec bash --login} +will replace the current shell with a Bash login shell. +@xref{Bash Startup Files}, for a description of the special behavior +of a login shell. + +@item -r +Make the shell a restricted shell (@pxref{The Restricted Shell}). + +@item -s +If this option is present, or if no arguments remain after option +processing, then commands are read from the standard input. +This option allows the positional parameters to be set +when invoking an interactive shell. + +@item -D +A list of all double-quoted strings preceded by @samp{$} +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}). +This implies the @option{-n} option; no commands will be executed. + +@item [-+]O [@var{shopt_option}] +@var{shopt_option} is one of the shell options accepted by the +@code{shopt} builtin (@pxref{The Shopt Builtin}). +If @var{shopt_option} is present, @option{-O} sets the value of that option; +@option{+O} unsets it. +If @var{shopt_option} is not supplied, the names and values of the shell +options accepted by @code{shopt} are printed on the standard output. +If the invocation option is @option{+O}, the output is displayed in a format +that may be reused as input. + +@item -- +A @code{--} signals the end of options and disables further option +processing. +Any arguments after the @code{--} are treated as filenames and arguments. + +@end table + +@cindex login shell +A @emph{login} shell is one whose first character of argument zero is +@samp{-}, or one invoked with the @option{--login} option. + +@cindex interactive shell +An @emph{interactive} shell is one started without non-option arguments, +unless @option{-s} is specified, +without specifying the @option{-c} option, and whose input and output are both +connected to terminals (as determined by @code{isatty(3)}), or one +started with the @option{-i} option. @xref{Interactive Shells}, for more +information. + +If arguments remain after option processing, and neither the +@option{-c} nor the @option{-s} +option has been supplied, the first argument is assumed to +be the name of a file containing shell commands (@pxref{Shell Scripts}). +When Bash is invoked in this fashion, @code{$0} +is set to the name of the file, and the positional parameters +are set to the remaining arguments. +Bash reads and executes commands from this file, then exits. +Bash's exit status is the exit status of the last command executed +in the script. If no commands are executed, the exit status is 0. + +@node Bash Startup Files +@section Bash Startup Files +@cindex startup files + +This section describes 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}). + +Interactive shells are described in @ref{Interactive Shells}. + +@subsubheading Invoked as an interactive login shell, or with @option{--login} + +When Bash is invoked as an interactive login shell, or as a +non-interactive shell with the @option{--login} option, 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 +and executes commands from the first one that exists and is readable. +The @option{--noprofile} option may be used when the shell is started to +inhibit this behavior. + +When a login shell exits, Bash reads and executes commands from +the file @file{~/.bash_logout}, if it exists. + +@subsubheading Invoked as an interactive non-login shell + +When an interactive shell that is not a login shell is started, Bash +reads and executes commands from @file{~/.bashrc}, if that file exists. +This may be inhibited by using the @option{--norc} option. +The @option{--rcfile @var{file}} option will force Bash to read and +execute commands from @var{file} instead of @file{~/.bashrc}. + +So, typically, your @file{~/.bash_profile} contains the line +@example +@code{if [ -f ~/.bashrc ]; then . ~/.bashrc; fi} +@end example +@noindent +after (or before) any login-specific initializations. + +@subsubheading Invoked non-interactively + +When Bash is started non-interactively, to run a shell script, +for example, it looks for the variable @env{BASH_ENV} in the environment, +expands its value if it appears there, and uses the expanded value as +the name of a file to read and execute. Bash behaves as if the +following command were executed: +@example +@code{if [ -n "$BASH_ENV" ]; then . "$BASH_ENV"; fi} +@end example +@noindent +but the value of the @env{PATH} variable is not used to search for the +file name. + +As noted above, if a non-interactive shell is invoked with the +@option{--login} option, Bash attempts to read and execute commands from the +login shell startup files. + +@subsubheading Invoked with name @code{sh} + +If Bash is invoked with the name @code{sh}, it tries to mimic the +startup behavior of historical versions of @code{sh} as closely as +possible, while conforming to the @sc{posix} standard as well. + +When invoked as an interactive login shell, or as a non-interactive +shell with the @option{--login} option, it first attempts to read +and execute commands from @file{/etc/profile} and @file{~/.profile}, in +that order. +The @option{--noprofile} option may be used to inhibit this behavior. +When invoked as an interactive shell with the name @code{sh}, Bash +looks for the variable @env{ENV}, expands its value if it is defined, +and uses the expanded value as the name of a file to read and execute. +Since a shell invoked as @code{sh} does not attempt to read and execute +commands from any other startup files, the @option{--rcfile} option has +no effect. +A non-interactive shell invoked with the name @code{sh} does not attempt +to read any other startup files. + +When invoked as @code{sh}, Bash enters @sc{posix} mode after +the startup files are read. + +@subsubheading Invoked in @sc{posix} mode + +When Bash is started in @sc{posix} mode, as with the +@option{--posix} command line option, it follows the @sc{posix} standard +for startup files. +In this mode, interactive shells expand the @env{ENV} variable +and commands are read and executed from the file whose name is the +expanded value. +No other startup files are read. + +@subsubheading Invoked by remote shell daemon + +Bash attempts to determine when it is being run with its standard input +connected to a a network connection, as if by the remote shell +daemon, usually @code{rshd}, or the secure shell daemon @code{sshd}. +If Bash determines it is being run in +this fashion, it reads and executes commands from @file{~/.bashrc}, if that +file exists and is readable. +It will not do this if invoked as @code{sh}. +The @option{--norc} option may be used to inhibit this behavior, and the +@option{--rcfile} option may be used to force another file to be read, but +@code{rshd} does not generally invoke the shell with those options or +allow them to be specified. + +@subsubheading Invoked with unequal effective and real @sc{uid/gid}s + +If Bash is started with the effective user (group) id not equal to the +real user (group) id, and the @code{-p} option is not supplied, no startup +files are read, shell functions are not inherited from the environment, +the @env{SHELLOPTS}, @env{BASHOPTS}, @env{CDPATH}, and @env{GLOBIGNORE} +variables, if they appear in the environment, are ignored, and the effective +user id is set to the real user id. +If the @code{-p} option is supplied at invocation, the startup behavior is +the same, but the effective user id is not reset. + +@node Interactive Shells +@section Interactive Shells +@cindex interactive shell +@cindex shell, interactive + +@menu +* What is an Interactive Shell?:: What determines whether a shell is Interactive. +* Is this Shell Interactive?:: How to tell if a shell is interactive. +* Interactive Shell Behavior:: What changes in a interactive shell? +@end menu + +@node What is an Interactive Shell? +@subsection What is an Interactive Shell? + +An interactive shell +is one started without non-option arguments, unless @option{-s} is +specified, without specifying the @option{-c} option, and +whose input and error output are both +connected to terminals (as determined by @code{isatty(3)}), +or one started with the @option{-i} option. + +An interactive shell generally reads from and writes to a user's +terminal. + +The @option{-s} invocation option may be used to set the positional parameters +when an interactive shell is started. + +@node Is this Shell Interactive? +@subsection Is this Shell Interactive? + +To determine within a startup script whether or not Bash is +running interactively, +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 + +Alternatively, startup scripts may examine the variable +@env{PS1}; it is unset in non-interactive shells, and set in +interactive shells. Thus: + +@example +if [ -z "$PS1" ]; then + echo This shell is not interactive +else + echo This shell is interactive +fi +@end example + +@node Interactive Shell Behavior +@subsection Interactive Shell Behavior + +When the shell is running interactively, it changes its behavior in +several ways. + +@enumerate +@item +Startup files are read and executed as described in @ref{Bash Startup Files}. + +@item +Job Control (@pxref{Job Control}) is enabled by default. When job +control is in effect, Bash ignores the keyboard-generated job control +signals @code{SIGTTIN}, @code{SIGTTOU}, and @code{SIGTSTP}. + +@item +Bash expands and displays @env{PS1} before reading the first line +of a command, and expands and displays @env{PS2} before reading the +second and subsequent lines of a multi-line command. + +@item +Bash executes the value of the @env{PROMPT_COMMAND} variable as a command +before printing the primary prompt, @env{$PS1} +(@pxref{Bash Variables}). + +@item +Readline (@pxref{Command Line Editing}) is used to read commands from +the user's terminal. + +@item +Bash inspects the value of the @code{ignoreeof} option to @code{set -o} +instead of exiting immediately when it receives an @code{EOF} on its +standard input when reading a command (@pxref{The Set Builtin}). + +@item +Command history (@pxref{Bash History Facilities}) +and history expansion (@pxref{History Interaction}) +are enabled by default. +Bash will save the command history to the file named by @env{$HISTFILE} +when an interactive shell exits. + +@item +Alias expansion (@pxref{Aliases}) is performed by default. + +@item +In the absence of any traps, Bash ignores @code{SIGTERM} +(@pxref{Signals}). + +@item +In the absence of any traps, @code{SIGINT} is caught and handled +((@pxref{Signals}). +@code{SIGINT} will interrupt some shell builtins. + +@item +An interactive login shell sends a @code{SIGHUP} to all jobs on exit +if the @code{huponexit} shell option has been enabled (@pxref{Signals}). + +@item +The @option{-n} invocation option is ignored, and @samp{set -n} has +no effect (@pxref{The Set Builtin}). + +@item +Bash will check for mail periodically, depending on the values of the +@env{MAIL}, @env{MAILPATH}, and @env{MAILCHECK} shell variables +(@pxref{Bash Variables}). + +@item +Expansion errors due to references to unbound shell variables after +@samp{set -u} has been enabled will not cause the shell to exit +(@pxref{The Set Builtin}). + +@item +The shell will not exit on expansion errors caused by @var{var} being unset +or null in @code{$@{@var{var}:?@var{word}@}} expansions +(@pxref{Shell Parameter Expansion}). + +@item +Redirection errors encountered by shell builtins will not cause the +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}). + +@item +Parser syntax errors will not cause the shell to exit. + +@item +Simple spelling correction for directory arguments to the @code{cd} +builtin is enabled by default (see the description of the @code{cdspell} +option to the @code{shopt} builtin in @ref{The Shopt Builtin}). + +@item +The shell will check the value of the @env{TMOUT} variable and exit +if a command is not read within the specified number of seconds after +printing @env{$PS1} (@pxref{Bash Variables}). + +@end enumerate + +@node Bash Conditional Expressions +@section Bash Conditional Expressions +@cindex expressions, conditional + +Conditional expressions are used by the @code{[[} compound command +and the @code{test} and @code{[} builtin commands. + +Expressions may be unary or binary. +Unary expressions are often used to examine the status of a file. +There are string operators and numeric comparison operators as well. +If the @var{file} argument to one of the primaries is of the form +@file{/dev/fd/@var{N}}, then file descriptor @var{N} is checked. +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. + +When used with @samp{[[}, The @samp{<} and @samp{>} operators sort +lexicographically using the current locale. + +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. + +@item -b @var{file} +True if @var{file} exists and is a block special file. + +@item -c @var{file} +True if @var{file} exists and is a character special file. + +@item -d @var{file} +True if @var{file} exists and is a directory. + +@item -e @var{file} +True if @var{file} exists. + +@item -f @var{file} +True if @var{file} exists and is a regular file. + +@item -g @var{file} +True if @var{file} exists and its set-group-id bit is set. + +@item -h @var{file} +True if @var{file} exists and is a symbolic link. + +@item -k @var{file} +True if @var{file} exists and its "sticky" bit is set. + +@item -p @var{file} +True if @var{file} exists and is a named pipe (FIFO). + +@item -r @var{file} +True if @var{file} exists and is readable. + +@item -s @var{file} +True if @var{file} exists and has a size greater than zero. + +@item -t @var{fd} +True if file descriptor @var{fd} is open and refers to a terminal. + +@item -u @var{file} +True if @var{file} exists and its set-user-id bit is set. + +@item -w @var{file} +True if @var{file} exists and is writable. + +@item -x @var{file} +True if @var{file} exists and is executable. + +@item -O @var{file} +True if @var{file} exists and is owned by the effective user id. + +@item -G @var{file} +True if @var{file} exists and is owned by the effective group id. + +@item -L @var{file} +True if @var{file} exists and is a symbolic link. + +@item -S @var{file} +True if @var{file} exists and is a socket. + +@item -N @var{file} +True if @var{file} exists and has been modified since it was last read. + +@item @var{file1} -nt @var{file2} +True if @var{file1} is newer (according to modification date) +than @var{file2}, or if @var{file1} exists and @var{file2} does not. + +@item @var{file1} -ot @var{file2} +True if @var{file1} is older than @var{file2}, +or if @var{file2} exists and @var{file1} does not. + +@item @var{file1} -ef @var{file2} +True if @var{file1} and @var{file2} refer to the same device and +inode numbers. + +@item -o @var{optname} +True if shell option @var{optname} is enabled. +The list of options appears in the description of the @option{-o} +option to the @code{set} builtin (@pxref{The Set Builtin}). + +@item -z @var{string} +True if the length of @var{string} is zero. + +@item -n @var{string} +@itemx @var{string} +True if the length of @var{string} is non-zero. + +@item @var{string1} == @var{string2} +@itemx @var{string1} = @var{string2} +True if the strings are equal. +@samp{=} should be used with the @code{test} command for @sc{posix} conformance. + +@item @var{string1} != @var{string2} +True if the strings are not equal. + +@item @var{string1} < @var{string2} +True if @var{string1} sorts before @var{string2} lexicographically. + +@item @var{string1} > @var{string2} +True if @var{string1} sorts after @var{string2} lexicographically. + +@item @var{arg1} OP @var{arg2} +@code{OP} is one of +@samp{-eq}, @samp{-ne}, @samp{-lt}, @samp{-le}, @samp{-gt}, or @samp{-ge}. +These arithmetic binary operators return true if @var{arg1} +is equal to, not equal to, less than, less than or equal to, +greater than, or greater than or equal to @var{arg2}, +respectively. @var{Arg1} and @var{arg2} +may be positive or negative integers. + +@end table + +@node Shell Arithmetic +@section Shell Arithmetic +@cindex arithmetic, shell +@cindex shell arithmetic +@cindex expressions, arithmetic +@cindex evaluation, arithmetic +@cindex arithmetic evaluation + +The shell allows arithmetic expressions to be evaluated, as one of +the shell expansions or by the @code{let} and the @option{-i} option +to the @code{declare} builtins. + +Evaluation is done in fixed-width integers with no check for overflow, +though division by 0 is trapped and flagged as an error. +The operators and their precedence, associativity, and values +are the same as in the C language. +The following list of operators is grouped into levels of +equal-precedence operators. +The levels are listed in order of decreasing precedence. + +@table @code + +@item @var{id}++ @var{id}-- +variable post-increment and post-decrement + +@item ++@var{id} --@var{id} +variable pre-increment and pre-decrement + +@item - + +unary minus and plus + +@item ! ~ +logical and bitwise negation + +@item ** +exponentiation + +@item * / % +multiplication, division, remainder + +@item + - +addition, subtraction + +@item << >> +left and right bitwise shifts + +@item <= >= < > +comparison + +@item == != +equality and inequality + +@item & +bitwise AND + +@item ^ +bitwise exclusive OR + +@item | +bitwise OR + +@item && +logical AND + +@item || +logical OR + +@item expr ? expr : expr +conditional operator + +@item = *= /= %= += -= <<= >>= &= ^= |= +assignment + +@item expr1 , expr2 +comma +@end table + +Shell variables are allowed as operands; parameter expansion is +performed before the expression is evaluated. +Within an expression, shell variables may also be referenced by name +without using the parameter expansion syntax. +A shell variable that is null or unset evaluates to 0 when referenced +by name without using the parameter expansion syntax. +The value of a variable is evaluated as an arithmetic expression +when it is referenced, or when a variable which has been given the +@var{integer} attribute using @samp{declare -i} is assigned a value. +A null value evaluates to 0. +A shell variable need not have its integer attribute turned on +to be used in an expression. + +Constants with a leading 0 are interpreted as octal numbers. +A leading @samp{0x} or @samp{0X} denotes hexadecimal. Otherwise, +numbers take the form [@var{base}@code{#}]@var{n}, where @var{base} +is a decimal number between 2 and 64 representing the arithmetic +base, and @var{n} is a number in that base. If @var{base}@code{#} is +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 interchangeably to represent numbers between 10 +and 35. + +Operators are evaluated in order of precedence. Sub-expressions in +parentheses are evaluated first and may override the precedence +rules above. + +@node Aliases +@section Aliases +@cindex alias expansion + +@var{Aliases} allow a string to be substituted for a word when it is used +as the first word of a simple command. +The shell maintains a list of aliases that may be set and unset with +the @code{alias} and @code{unalias} builtin commands. + +The first word of each simple command, if unquoted, is checked to see +if it has an alias. +If so, that word is replaced by the text of the alias. +The characters @samp{/}, @samp{$}, @samp{`}, @samp{=} and any of the +shell metacharacters or quoting characters listed above may not appear +in an alias name. +The replacement text may contain any valid +shell input, including shell metacharacters. +The first word of the replacement text is tested for +aliases, but a word that is identical to an alias being expanded +is not expanded a second time. +This means that one may alias @code{ls} to @code{"ls -F"}, +for instance, and Bash does not try to recursively expand the +replacement text. If the last character of the alias value is a +space or tab character, then the next command word following the +alias is also checked for alias expansion. + +Aliases are created and listed with the @code{alias} +command, and removed with the @code{unalias} command. + +There is no mechanism for using arguments in the replacement text, +as in @code{csh}. +If arguments are needed, a shell function should be used +(@pxref{Shell Functions}). + +Aliases are not expanded when the shell is not interactive, +unless the @code{expand_aliases} shell option is set using +@code{shopt} (@pxref{The Shopt Builtin}). + +The rules concerning the definition and use of aliases are +somewhat confusing. Bash +always reads at least one complete line +of input before executing any +of the commands on that line. Aliases are expanded when a +command is read, not when it is executed. Therefore, an +alias definition appearing on the same line as another +command does not take effect until the next line of input is read. +The commands following the alias definition +on that line are not affected by the new alias. +This behavior is also an issue when functions are executed. +Aliases are expanded when a function definition is read, +not when the function is executed, because a function definition +is itself a compound command. As a consequence, aliases +defined in a function are not available until after that +function is executed. To be safe, always put +alias definitions on a separate line, and do not use @code{alias} +in compound commands. + +For almost every purpose, shell functions are preferred over aliases. + +@node Arrays +@section Arrays +@cindex arrays + +Bash provides one-dimensional indexed and associative array variables. +Any variable may be used as an indexed array; +the @code{declare} builtin will explicitly declare an array. +There is no maximum +limit on the size of an array, nor any requirement that members +be indexed or assigned contiguously. +Indexed arrays are referenced using integers (including arithmetic +expressions (@pxref{Shell Arithmetic}) and are zero-based; +associative arrays use arbitrary strings. + +An indexed array is created automatically if any variable is assigned to +using the syntax +@example +name[@var{subscript}]=@var{value} +@end example + +@noindent +The @var{subscript} +is treated as an arithmetic expression that must evaluate to a number +greater than or equal to zero. To explicitly declare an array, use +@example +declare -a @var{name} +@end example +@noindent +The syntax +@example +declare -a @var{name}[@var{subscript}] +@end example +@noindent +is also accepted; the @var{subscript} is ignored. + +Associative arrays are created using +@example +declare -A @var{name}. +@end example + +Attributes may be +specified for an array variable using the @code{declare} and +@code{readonly} builtins. Each attribute applies to all members of +an array. + +Arrays are assigned to using compound assignments of the form +@example +name=(value@var{1} @dots{} value@var{n}) +@end example +@noindent +where each +@var{value} is of the form @code{[@var{subscript}]=}@var{string}. +Indexed array assignments do not require the bracket and subscript. +When assigning to indexed arrays, if +the optional subscript is supplied, that index is assigned to; +otherwise the index of the element assigned is the last index assigned +to by the statement plus one. Indexing starts at zero. + +When assigning to an associative array, the subscript is required. + +This syntax is also accepted by the @code{declare} +builtin. Individual array elements may be assigned to using the +@code{name[}@var{subscript}@code{]=}@var{value} syntax introduced above. + +Any element of an array may be referenced using +@code{$@{name[}@var{subscript}@code{]@}}. +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, +@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. +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{]@}}. +If @var{subscript} is @samp{@@} or +@samp{*}, the expansion is the number of elements in the array. +Referencing an array variable without a subscript is equivalent to +referencing with a subscript of 0. + +An array variable is considered set if a subscript has been assigned a +value. The null string is a valid value. + +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 +expansion. +@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. + +The @code{declare}, @code{local}, and @code{readonly} +builtins each accept a @option{-a} option to specify an indexed +array and a @option{-A} option to specify an associative array. +The @code{read} builtin accepts a @option{-a} +option to assign a list of words read from the standard input +to an array, and can read values from the standard input into +individual array elements. The @code{set} and @code{declare} +builtins display array values in a way that allows them to be +reused as input. + +@node The Directory Stack +@section The Directory Stack +@cindex directory stack + +@menu +* Directory Stack Builtins:: Bash builtin commands to manipulate + the directory stack. +@end menu + +The directory stack is a list of recently-visited directories. The +@code{pushd} builtin adds directories to the stack as it changes +the current directory, and the @code{popd} builtin removes specified +directories from the stack and changes the current directory to +the directory removed. The @code{dirs} builtin displays the contents +of the directory stack. + +The contents of the directory stack are also visible +as the value of the @env{DIRSTACK} shell variable. + +@node Directory Stack Builtins +@subsection Directory Stack Builtins + +@table @code + +@item dirs +@btindex dirs +@example +dirs [+@var{N} | -@var{N}] [-clpv] +@end example +Display the list of currently remembered directories. Directories +are added to the list with the @code{pushd} command; the +@code{popd} command removes directories from the list. +@table @code +@item +@var{N} +Displays the @var{N}th directory (counting from the left of the +list printed by @code{dirs} when invoked without options), starting +with zero. +@item -@var{N} +Displays the @var{N}th directory (counting from the right of the +list printed by @code{dirs} when invoked without options), starting +with zero. +@item -c +Clears the directory stack by deleting all of the elements. +@item -l +Produces a longer listing; the default listing format uses a +tilde to denote the home directory. +@item -p +Causes @code{dirs} to print the directory stack with one entry per +line. +@item -v +Causes @code{dirs} to print the directory stack with one entry per +line, prefixing each entry with its index in the stack. +@end table + +@item popd +@btindex popd +@example +popd [+@var{N} | -@var{N}] [-n] +@end example + +Remove the top entry from the directory stack, and @code{cd} +to the new top directory. +When no arguments are given, @code{popd} +removes the top directory from the stack and +performs a @code{cd} to the new top directory. The +elements are numbered from 0 starting at the first directory listed with +@code{dirs}; i.e., @code{popd} is equivalent to @code{popd +0}. +@table @code +@item +@var{N} +Removes the @var{N}th directory (counting from the left of the +list printed by @code{dirs}), starting with zero. +@item -@var{N} +Removes the @var{N}th directory (counting from the right of the +list printed by @code{dirs}), starting with zero. +@item -n +Suppresses the normal change of directory when removing directories +from the stack, so that only the stack is manipulated. +@end table + +@btindex pushd +@item pushd +@example +pushd [-n] [@var{+N} | @var{-N} | @var{dir} ] +@end example + +Save the current directory on the top of the directory stack +and then @code{cd} to @var{dir}. +With no arguments, @code{pushd} exchanges the top two directories. + +@table @code +@item -n +Suppresses the normal change of directory when adding directories +to the stack, so that only the stack is manipulated. +@item +@var{N} +Brings the @var{N}th directory (counting from the left of the +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}, starting with zero) to the top of +the list by rotating the stack. +@item @var{dir} +Makes the current working directory be the top of the stack, and then +executes the equivalent of `@code{cd} @var{dir}'. +@code{cd}s to @var{dir}. +@end table + +@end table + +@node Printing a Prompt +@section Controlling the Prompt +@cindex prompting + +The value of the variable @env{PROMPT_COMMAND} is examined just before +Bash prints each primary prompt. If @env{PROMPT_COMMAND} is set and +has a non-null value, then the +value is executed just as if it had been typed on the command line. + +In addition, the following table describes the special characters which +can appear in the prompt variables: + +@table @code +@item \a +A bell character. +@item \d +The date, in "Weekday Month Date" format (e.g., "Tue May 26"). +@item \D@{@var{format}@} +The @var{format} is passed to @code{strftime}(3) and the result is inserted +into the prompt string; an empty @var{format} results in a locale-specific +time representation. The braces are required. +@item \e +An escape character. +@item \h +The hostname, up to the first `.'. +@item \H +The hostname. +@item \j +The number of jobs currently managed by the shell. +@item \l +The basename of the shell's terminal device name. +@item \n +A newline. +@item \r +A carriage return. +@item \s +The name of the shell, the basename of @code{$0} (the portion +following the final slash). +@item \t +The time, in 24-hour HH:MM:SS format. +@item \T +The time, in 12-hour HH:MM:SS format. +@item \@@ +The time, in 12-hour am/pm format. +@item \A +The time, in 24-hour HH:MM format. +@item \u +The username of the current user. +@item \v +The version of Bash (e.g., 2.00) +@item \V +The release of Bash, version + patchlevel (e.g., 2.00.0) +@item \w +The current working directory, with @env{$HOME} abbreviated with a tilde +(uses the @env{$PROMPT_DIRTRIM} variable). +@item \W +The basename of @env{$PWD}, with @env{$HOME} abbreviated with a tilde. +@item \! +The history number of this command. +@item \# +The command number of this command. +@item \$ +If the effective uid is 0, @code{#}, otherwise @code{$}. +@item \@var{nnn} +The character whose ASCII code is the octal value @var{nnn}. +@item \\ +A backslash. +@item \[ +Begin a sequence of non-printing characters. This could be used to +embed a terminal control sequence into the prompt. +@item \] +End a sequence of non-printing characters. +@end table + +The command number and the history number are usually different: +the history number of a command is its position in the history +list, which may include commands restored from the history file +(@pxref{Bash History Facilities}), while the command number is +the position in the sequence of commands executed during the current +shell session. + +After the string is decoded, it is expanded via +parameter expansion, command substitution, arithmetic +expansion, and quote removal, subject to the value of the +@code{promptvars} shell option (@pxref{Bash Builtins}). + +@node The Restricted Shell +@section The Restricted Shell +@cindex restricted shell + +If Bash is started with the name @code{rbash}, or the +@option{--restricted} +or +@option{-r} +option is supplied at invocation, the shell becomes restricted. +A restricted shell is used to +set up an environment more controlled than the standard shell. +A restricted shell behaves identically to @code{bash} +with the exception that the following are disallowed or not performed: + +@itemize @bullet +@item +Changing directories with the @code{cd} builtin. +@item +Setting or unsetting the values of the @env{SHELL}, @env{PATH}, +@env{ENV}, or @env{BASH_ENV} variables. +@item +Specifying command names containing slashes. +@item +Specifying a filename containing a slash as an argument to the @code{.} +builtin command. +@item +Specifying a filename containing a slash as an argument to the @option{-p} +option to the @code{hash} builtin command. +@item +Importing function definitions from the shell environment at startup. +@item +Parsing the value of @env{SHELLOPTS} from the shell environment at startup. +@item +Redirecting output using the @samp{>}, @samp{>|}, @samp{<>}, @samp{>&}, +@samp{&>}, and @samp{>>} redirection operators. +@item +Using the @code{exec} builtin to replace the shell with another command. +@item +Adding or deleting builtin commands with the +@option{-f} and @option{-d} options to the @code{enable} builtin. +@item +Using the @code{enable} builtin command to enable disabled shell builtins. +@item +Specifying the @option{-p} option to the @code{command} builtin. +@item +Turning off restricted mode with @samp{set +r} or @samp{set +o restricted}. +@end itemize + +These restrictions are enforced after any startup files are read. + +When a command that is found to be a shell script is executed +(@pxref{Shell Scripts}), @code{rbash} turns off any restrictions in +the shell spawned to execute the script. + +@node Bash POSIX Mode +@section Bash POSIX Mode +@cindex POSIX Mode + +Starting Bash with the @option{--posix} command-line option or executing +@samp{set -o posix} while Bash is running will cause Bash to conform more +closely to the @sc{posix} standard by changing the behavior to +match that specified by @sc{posix} in areas where the Bash default differs. + +When invoked as @code{sh}, Bash enters @sc{posix} mode after reading the +startup files. + +The following list is what's changed when `@sc{posix} mode' is in effect: + +@enumerate +@item +When a command in the hash table no longer exists, Bash will re-search +@env{$PATH} to find the new location. This is also available with +@samp{shopt -s checkhash}. + +@item +The message printed by the job control code and builtins when a job +exits with a non-zero status is `Done(status)'. + +@item +The message printed by the job control code and builtins when a job +is stopped is `Stopped(@var{signame})', where @var{signame} is, for +example, @code{SIGTSTP}. + +@item +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} @env{PS1} and @env{PS2} expansions of @samp{!} to +the history number and @samp{!!} to @samp{!} are enabled, +and parameter expansion is performed on the values of @env{PS1} and +@env{PS2} regardless of the setting of the @code{promptvars} option. + +@item +The @sc{posix} startup files are executed (@env{$ENV}) rather than +the normal Bash files. + +@item +Tilde expansion is only performed on assignments preceding a command +name, rather than on all assignment statements on the line. + +@item +The default history file is @file{~/.sh_history} (this is the +default value of @env{$HISTFILE}). + +@item +The output of @samp{kill -l} prints all the signal names on a single line, +separated by spaces, without the @samp{SIG} prefix. + +@item +The @code{kill} builtin does not accept signal names with a @samp{SIG} +prefix. + +@item +Non-interactive shells exit if @var{filename} in @code{.} @var{filename} +is not found. + +@item +Non-interactive shells exit if a syntax error in an arithmetic expansion +results in an invalid expression. + +@item +Redirection operators do not perform filename expansion on the word +in the redirection unless the shell is interactive. + +@item +Redirection operators do not perform word splitting on the word in the +redirection. + +@item +Function names must be valid shell @code{name}s. That is, they may not +contain characters other than letters, digits, and underscores, and +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} special builtins are found before shell functions +during command lookup. + +@item +If a @sc{posix} special builtin returns an error status, a +non-interactive shell exits. The fatal errors are those listed in +the POSIX standard, and include things like passing incorrect options, +redirection errors, variable assignment errors for assignments preceding +the command name, and so on. + +@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 +fail if no valid directory name can be constructed from +any of the entries in @env{$CDPATH}, even if the a directory with +the same name as the name given as an argument to @code{cd} exists +in the current directory. + +@item +A non-interactive shell exits with an error status if a variable +assignment error occurs when no command name follows the assignment +statements. +A variable assignment error occurs, for example, when trying to assign +a value to a readonly variable. + +@item +A non-interactive shell exits with an error status if the iteration +variable in a @code{for} statement or the selection variable in a +@code{select} statement is a readonly variable. + +@item +Process substitution is not available. + +@item +Assignment statements preceding @sc{posix} special builtins +persist in the shell environment after the builtin completes. + +@item +Assignment statements preceding shell function calls persist in the +shell environment after the function returns, as if a @sc{posix} +special builtin command had been executed. + +@item +The @code{export} and @code{readonly} builtin commands display their +output in the format required by @sc{posix}. + +@item +The @code{trap} builtin displays signal names without the leading +@code{SIG}. + +@item +The @code{trap} builtin doesn't check the first argument for a possible +signal specification and revert the signal handling to the original +disposition if it is, unless that argument consists solely of digits and +is a valid signal number. If users want to reset the handler for a given +signal to the original disposition, they should use @samp{-} as the +first argument. + +@item +The @code{.} and @code{source} builtins do not search the current directory +for the filename argument if it is not found by searching @env{PATH}. + +@item +Subshells spawned to execute command substitutions inherit the value of +the @option{-e} option from the parent shell. When not in @sc{posix} mode, +Bash clears the @option{-e} option in such subshells. + +@item +Alias expansion is always enabled, even in non-interactive shells. + +@item +When the @code{alias} builtin displays alias definitions, it does not +display them with a leading @samp{alias } unless the @option{-p} option +is supplied. + +@item +When the @code{set} builtin is invoked without options, it does not display +shell function names and definitions. + +@item +When the @code{set} builtin is invoked without options, it displays +variable values without quotes, unless they contain shell metacharacters, +even if the result contains nonprinting characters. + +@item +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{$VISUAL} 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. + +@item +The @code{ulimit} builtin uses a block size of 512 bytes for the @option{-c} +and @option{-f} options. + +@item +The arrival of @code{SIGCHLD} when a trap is set on @code{SIGCHLD} does +not interrupt the @code{wait} builtin and cause it to return immediately. +The trap command is run once for each child that exits. + +@end enumerate + +There is other @sc{posix} behavior that Bash does not implement by +default even when in @sc{posix} mode. +Specifically: + +@enumerate + +@item +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 +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 + +This chapter discusses what job control is, how it works, and how +Bash allows you to access its facilities. + +@menu +* Job Control Basics:: How job control works. +* Job Control Builtins:: Bash builtin commands used to interact + with job control. +* Job Control Variables:: Variables Bash uses to customize job + control. +@end menu + +@node Job Control Basics +@section Job Control Basics +@cindex job control +@cindex foreground +@cindex background +@cindex suspending jobs + +Job control +refers to the ability to selectively stop (suspend) +the execution of processes and continue (resume) +their execution at a later point. A user typically employs +this facility via an interactive interface supplied jointly +by the operating system kernel's terminal driver and Bash. + +The shell associates a @var{job} with each pipeline. It keeps a +table of currently executing jobs, which may be listed with the +@code{jobs} command. When Bash starts a job +asynchronously, it prints a line that looks +like: +@example +[1] 25647 +@end example +@noindent +indicating that this job is job number 1 and that the process @sc{id} +of the last process in the pipeline associated with this job is +25647. All of the processes in a single pipeline are members of +the same job. Bash uses the @var{job} abstraction as the +basis for job control. + +To facilitate the implementation of the user interface to job +control, the operating system maintains the notion of a current terminal +process group @sc{id}. Members of this process group (processes whose +process group @sc{id} is equal to the current terminal process group +@sc{id}) receive keyboard-generated signals such as @code{SIGINT}. +These processes are said to be in the foreground. Background +processes are those whose process group @sc{id} differs from the +terminal's; such processes are immune to keyboard-generated +signals. Only foreground processes are allowed to read from or, if +the user so specifies with @code{stty tostop}, write to the terminal. +Background processes which attempt to +read from (write to when @code{stty tostop} is in effect) the +terminal are sent a @code{SIGTTIN} (@code{SIGTTOU}) +signal by the kernel's terminal driver, +which, unless caught, suspends the process. + +If the operating system on which Bash is running supports +job control, Bash contains facilities to use it. Typing the +@var{suspend} character (typically @samp{^Z}, Control-Z) while a +process is running causes that process to be stopped and returns +control to Bash. Typing the @var{delayed suspend} character +(typically @samp{^Y}, Control-Y) causes the process to be stopped +when it attempts to read input from the terminal, and control to +be returned to Bash. The user then manipulates the state of +this job, using the @code{bg} command to continue it in the +background, the @code{fg} command to continue it in the +foreground, or the @code{kill} command to kill it. A @samp{^Z} +takes effect immediately, and has the additional side effect of +causing pending output and typeahead to be discarded. + +There are a number of ways to refer to a job in the shell. The +character @samp{%} introduces a job specification (@var{jobspec}). + +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. +A single @samp{%} (with no accompanying job specification) also refers +to the current job. +The previous job may be referenced using @samp{%-}. +If there is only a single job, @samp{%+} and @samp{%-} can both be used +to refer to that job. +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{-}. + +A job may also be referred to +using a prefix of the name used to start it, or using a substring +that appears in its command line. For example, @samp{%ce} refers +to a stopped @code{ce} job. Using @samp{%?ce}, on the +other hand, refers to any job containing the string @samp{ce} in +its command line. If the prefix or substring matches more than one job, +Bash reports an error. + +Simply naming a job can be used to bring it into the foreground: +@samp{%1} is a synonym for @samp{fg %1}, bringing job 1 from the +background into the foreground. Similarly, @samp{%1 &} resumes +job 1 in the background, equivalent to @samp{bg %1} + +The shell learns immediately whenever a job changes state. +Normally, Bash waits until it is about to print a prompt +before reporting changes in a job's status so as to not interrupt +any other output. +If the @option{-b} option to the @code{set} builtin is enabled, +Bash reports such changes immediately (@pxref{The Set Builtin}). +Any trap on @code{SIGCHLD} is executed for each child process +that exits. + +If an attempt to exit Bash is made while jobs are stopped, (or running, if +the @code{checkjobs} option is enabled -- see @ref{The Shopt Builtin}), the +shell prints a warning message, and if the @code{checkjobs} option is +enabled, lists the jobs and their statuses. +The @code{jobs} command may then be used to inspect their status. +If a second attempt to exit is made without an intervening command, +Bash does not print another warning, and any stopped jobs are terminated. + +@node Job Control Builtins +@section Job Control Builtins + +@table @code + +@item bg +@btindex bg +@example +bg [@var{jobspec} @dots{}] +@end example +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, any +@var{jobspec} was not found or specifies a job +that was started without job control. + +@item fg +@btindex fg +@example +fg [@var{jobspec}] +@end example +Resume the job @var{jobspec} in the foreground and make it the current job. +If @var{jobspec} is not supplied, the current job is used. +The return status is that of the command placed into the foreground, +or non-zero if run when job control is disabled or, when run with +job control enabled, @var{jobspec} does not specify a valid job or +@var{jobspec} specifies a job that was started without job control. + +@item jobs +@btindex jobs +@example +jobs [-lnprs] [@var{jobspec}] +jobs -x @var{command} [@var{arguments}] +@end example + +The first form lists the active jobs. The options have the +following meanings: + +@table @code +@item -l +List process @sc{id}s in addition to the normal information. + +@item -n +Display information only about jobs that have changed status since +the user was last notified of their status. + +@item -p +List only the process @sc{id} of the job's process group leader. + +@item -r +Restrict output to running jobs. + +@item -s +Restrict output to stopped jobs. +@end table + +If @var{jobspec} is given, +output is restricted to information about that job. +If @var{jobspec} is not supplied, the status of all jobs is +listed. + +If the @option{-x} option is supplied, @code{jobs} replaces any +@var{jobspec} found in @var{command} or @var{arguments} with the +corresponding process group @sc{id}, and executes @var{command}, +passing it @var{argument}s, returning its exit status. + +@item kill +@btindex kill +@example +kill [-s @var{sigspec}] [-n @var{signum}] [-@var{sigspec}] @var{jobspec} or @var{pid} +kill -l [@var{exit_status}] +@end example +Send a signal specified by @var{sigspec} or @var{signum} to the process +named by job specification @var{jobspec} or process @sc{id} @var{pid}. +@var{sigspec} is either a case-insensitive 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 @option{-l} option lists the signal names. +If any arguments are supplied when @option{-l} is given, the names of the +signals corresponding to the arguments are listed, and the return status +is zero. +@var{exit_status} is a number specifying a signal number or the exit +status of a process terminated by a signal. +The return status is zero if at least one signal was successfully sent, +or non-zero if an error occurs or an invalid option is encountered. + +@item wait +@btindex wait +@example +wait [@var{jobspec} or @var{pid} ...] +@end example +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. +If neither @var{jobspec} nor @var{pid} specifies an active child process +of the shell, the return status is 127. + +@item disown +@btindex disown +@example +disown [-ar] [-h] [@var{jobspec} @dots{}] +@end example +Without options, each @var{jobspec} is removed from the table of +active jobs. +If the @option{-h} option is given, the job is not removed from the table, +but is marked so that @code{SIGHUP} is not sent to the job if the shell +receives a @code{SIGHUP}. +If @var{jobspec} is not present, and neither the @option{-a} nor @option{-r} +option is supplied, the current job is used. +If no @var{jobspec} is supplied, the @option{-a} option means to remove or +mark all jobs; the @option{-r} option without a @var{jobspec} +argument restricts operation to running jobs. + +@item suspend +@btindex suspend +@example +suspend [-f] +@end example +Suspend the execution of this shell until it receives a +@code{SIGCONT} signal. +A login shell cannot be suspended; the @option{-f} +option can be used to override this and force the suspension. + +@end table + +When job control is not active, the @code{kill} and @code{wait} +builtins do not accept @var{jobspec} arguments. They must be +supplied process @sc{id}s. + +@node Job Control Variables +@section Job Control Variables + +@vtable @code + +@item auto_resume +This variable controls how the shell interacts with the user and +job control. If this variable exists then single word simple +commands without redirections are treated as candidates for resumption +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}, +the string supplied must match the name of a stopped job exactly; +if set to @samp{substring}, +the string supplied needs to match a substring of the name of a +stopped job. The @samp{substring} value provides functionality +analogous to the @samp{%?} job @sc{id} (@pxref{Job Control Basics}). +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 @samp{%} job @sc{id}. + +@end vtable + +@set readline-appendix +@set history-appendix +@cindex Readline, how to use +@include rluser.texi +@cindex History, how to use +@include hsuser.texi +@clear readline-appendix +@clear history-appendix + +@node Installing Bash +@chapter Installing Bash + +This chapter provides basic instructions for installing Bash on +the various supported platforms. The distribution supports the +@sc{gnu} operating systems, nearly every version of Unix, and several +non-Unix systems such as BeOS and Interix. +Other independent ports exist for +@sc{ms-dos}, @sc{os/2}, and Windows platforms. + +@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 + +@node Basic Installation +@section Basic Installation +@cindex installation +@cindex configuration +@cindex Bash installation +@cindex Bash configuration + +These are installation instructions for Bash. + +The simplest way to compile Bash is: + +@enumerate +@item +@code{cd} to the directory containing the source code and type +@samp{./configure} to configure Bash for your system. If you're +using @code{csh} on an old version of System V, you might need to +type @samp{sh ./configure} instead to prevent @code{csh} from trying +to execute @code{configure} itself. + +Running @code{configure} takes some time. +While running, it prints messages telling which features it is +checking for. + +@item +Type @samp{make} to compile Bash and build the @code{bashbug} bug +reporting script. + +@item +Optionally, type @samp{make tests} to run the Bash test suite. + +@item +Type @samp{make install} to install @code{bash} and @code{bashbug}. +This will also install the manual pages and Info file. + +@end enumerate + +The @code{configure} shell script attempts to guess correct +values for various system-dependent variables used during +compilation. It uses those values to create a @file{Makefile} in +each directory of the package (the top directory, the +@file{builtins}, @file{doc}, and @file{support} directories, +each directory under @file{lib}, and several others). It also creates a +@file{config.h} file containing system-dependent definitions. +Finally, it creates a shell script named @code{config.status} that you +can run in the future to recreate the current configuration, a +file @file{config.cache} that saves the results of its tests to +speed up reconfiguring, and a file @file{config.log} containing +compiler output (useful mainly for debugging @code{configure}). +If at some point +@file{config.cache} contains results you don't want to keep, you +may remove or edit it. + +To find out more about the options and arguments that the +@code{configure} script understands, type + +@example +bash-2.04$ ./configure --help +@end example + +@noindent +at the Bash prompt in your Bash source directory. + +If you need to do unusual things to compile Bash, please +try to figure out how @code{configure} could check whether or not +to do them, and mail diffs or instructions to +@email{bash-maintainers@@gnu.org} so they can be +considered for the next release. + +The file @file{configure.in} is used to create @code{configure} +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.50 or +newer. + +You can remove the program binaries and object files from the +source code directory by typing @samp{make clean}. To also remove the +files that @code{configure} created (so you can compile Bash for +a different kind of computer), type @samp{make distclean}. + +@node Compilers and Options +@section Compilers and Options + +Some systems require unusual options for compilation or linking +that the @code{configure} script does not know about. You can +give @code{configure} initial values for variables by setting +them in the environment. Using a Bourne-compatible shell, you +can do that on the command line like this: + +@example +CC=c89 CFLAGS=-O2 LIBS=-lposix ./configure +@end example + +On systems that have the @code{env} program, you can do it like this: + +@example +env CPPFLAGS=-I/usr/local/include LDFLAGS=-s ./configure +@end example + +The configuration process uses GCC to build Bash if it +is available. + +@node Compiling For Multiple Architectures +@section Compiling For Multiple Architectures + +You can compile Bash for more than one kind of computer at the +same time, by placing the object files for each architecture in their +own directory. To do this, you must use a version of @code{make} that +supports the @code{VPATH} variable, such as GNU @code{make}. +@code{cd} to the +directory where you want the object files and executables to go and run +the @code{configure} script from the source directory. You may need to +supply the @option{--srcdir=PATH} argument to tell @code{configure} where the +source files are. @code{configure} automatically checks for the +source code in the directory that @code{configure} is in and in `..'. + +If you have to use a @code{make} that does not supports the @code{VPATH} +variable, you can compile Bash for one architecture at a +time in the source code directory. After you have installed +Bash for one architecture, use @samp{make distclean} before +reconfiguring for another architecture. + +Alternatively, if your system supports symbolic links, you can use the +@file{support/mkclone} script to create a build tree which has +symbolic links back to each file in the source directory. Here's an +example that creates a build directory in the current directory from a +source directory @file{/usr/gnu/src/bash-2.0}: + +@example +bash /usr/gnu/src/bash-2.0/support/mkclone -s /usr/gnu/src/bash-2.0 . +@end example + +@noindent +The @code{mkclone} script requires Bash, so you must have already built +Bash for at least one architecture before you can create build +directories for other architectures. + +@node Installation Names +@section Installation Names + +By default, @samp{make install} will install into +@file{/usr/local/bin}, @file{/usr/local/man}, etc. You can +specify an installation prefix other than @file{/usr/local} by +giving @code{configure} the option @option{--prefix=@var{PATH}}, +or by specifying a value for the @code{DESTDIR} @samp{make} +variable when running @samp{make install}. + +You can specify separate installation prefixes for +architecture-specific files and architecture-independent files. +If you give @code{configure} the option +@option{--exec-prefix=@var{PATH}}, @samp{make install} will use +@var{PATH} as the prefix for installing programs and libraries. +Documentation and other data files will still use the regular prefix. + +@node Specifying the System Type +@section Specifying the System Type + +There may be some features @code{configure} can not figure out +automatically, but need to determine by the type of host Bash +will run on. Usually @code{configure} can figure that +out, but if it prints a message saying it can not guess the host +type, give it the @option{--host=TYPE} option. @samp{TYPE} can +either be a short name for the system type, such as @samp{sun4}, +or a canonical name with three fields: @samp{CPU-COMPANY-SYSTEM} +(e.g., @samp{i386-unknown-freebsd4.2}). + +See the file @file{support/config.sub} for the possible +values of each field. + +@node Sharing Defaults +@section Sharing Defaults + +If you want to set default values for @code{configure} scripts to +share, you can create a site shell script called +@code{config.site} that gives default values for variables like +@code{CC}, @code{cache_file}, and @code{prefix}. @code{configure} +looks for @file{PREFIX/share/config.site} if it exists, then +@file{PREFIX/etc/config.site} if it exists. Or, you can set the +@code{CONFIG_SITE} environment variable to the location of the site +script. A warning: the Bash @code{configure} looks for a site script, +but not all @code{configure} scripts do. + +@node Operation Controls +@section Operation Controls + +@code{configure} recognizes the following options to control how it +operates. + +@table @code + +@item --cache-file=@var{file} +Use and save the results of the tests in +@var{file} instead of @file{./config.cache}. Set @var{file} to +@file{/dev/null} to disable caching, for debugging +@code{configure}. + +@item --help +Print a summary of the options to @code{configure}, and exit. + +@item --quiet +@itemx --silent +@itemx -q +Do not print messages saying which checks are being made. + +@item --srcdir=@var{dir} +Look for the Bash source code in directory @var{dir}. Usually +@code{configure} can determine that directory automatically. + +@item --version +Print the version of Autoconf used to generate the @code{configure} +script, and exit. +@end table + +@code{configure} also accepts some other, not widely used, boilerplate +options. @samp{configure --help} prints the complete list. + +@node Optional Features +@section Optional Features + +The Bash @code{configure} has a number of @option{--enable-@var{feature}} +options, where @var{feature} indicates an optional part of Bash. +There are also several @option{--with-@var{package}} options, +where @var{package} is something like @samp{bash-malloc} or @samp{purify}. +To turn off the default use of a package, use +@option{--without-@var{package}}. To configure Bash without a feature +that is enabled by default, use @option{--disable-@var{feature}}. + +Here is a complete list of the @option{--enable-} and +@option{--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-bash-malloc +Use the Bash version of +@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 +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 +option automatically for a number of systems. + +@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-gnu-malloc +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 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 +the standard system include and library directories. +If @var{PREFIX} is @code{no}, Bash links with the version in +@file{lib/readline}. +If @var{PREFIX} is set to any other value, @code{configure} treats it as +a directory pathname and looks for +the installed version of Readline in subdirectories of that directory +(include files in @var{PREFIX}/@code{include} and the library in +@var{PREFIX}/@code{lib}). + +@item --with-purify +Define this to use the Purify memory allocation checker from Rational +Software. + +@item --enable-minimal-config +This produces a shell with minimal features, close to the historical +Bourne shell. +@end table + +There are several @option{--enable-} options that alter how Bash is +compiled and linked, rather than changing run-time features. + +@table @code +@item --enable-largefile +Enable support for @uref{http://www.sas.com/standards/large_file/x_open.20Mar96.html, +large files} if the operating system requires special compiler options +to build programs which can access large files. This is enabled by +default, if the operating system provides large file support. + +@item --enable-profiling +This builds a Bash binary that produces profiling information to be +processed by @code{gprof} each time it is executed. + +@item --enable-static-link +This causes Bash to be linked statically, if @code{gcc} is being used. +This could be used to build a version to use as root's shell. +@end table + +The @samp{minimal-config} option can be used to disable all of +the following options, but it is processed first, so individual +options may be enabled using @samp{enable-@var{feature}}. + +All of the following options except for @samp{disabled-builtins} and +@samp{xpg-echo-default} are +enabled by default, unless the operating system does not provide the +necessary support. + +@table @code +@item --enable-alias +Allow alias expansion and include the @code{alias} and @code{unalias} +builtins (@pxref{Aliases}). + +@item --enable-arith-for-command +Include support for the alternate form of the @code{for} command +that behaves like the C language @code{for} statement +(@pxref{Looping Constructs}). + +@item --enable-array-variables +Include support for one-dimensional array shell variables +(@pxref{Arrays}). + +@item --enable-bang-history +Include support for @code{csh}-like history substitution +(@pxref{History Interaction}). + +@item --enable-brace-expansion +Include @code{csh}-like brace expansion +( @code{b@{a,b@}c} @expansion{} @code{bac bbc} ). +See @ref{Brace Expansion}, for a complete description. + +@item --enable-casemod-attributes +Include support for case-modifying attributes in the @code{declare} builtin +and assignment statements. Variables with the @var{uppercase} attribute, +for example, will have their values converted to uppercase upon assignment. + +@item --enable-casemod-expansion +Include support for case-modifying word expansions. + +@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} +(@pxref{Pipelines}). +This allows pipelines as well as shell builtins and functions to be timed. + +@item --enable-cond-command +Include support for the @code{[[} conditional command. +(@pxref{Conditional Constructs}). + +@item --enable-cond-regexp +Include support for matching POSIX regular expressions using the +@samp{=~} binary operator in the @code{[[} conditional command. +(@pxref{Conditional Constructs}). + +@item --enable-coprocesses +Include support for coprocesses and the @code{coproc} reserved word +(@pxref{Pipelines}). + +@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 +(@pxref{The Directory Stack}). + +@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{((@dots{}))} command +(@pxref{Conditional Constructs}). + +@item --enable-extended-glob +Include support for the extended pattern matching features described +above under @ref{Pattern Matching}. + +@item --enable-extended-glob-default +Set the default value of the @var{extglob} shell option described +above under @ref{The Shopt Builtin} to be enabled. + +@item --enable-help-builtin +Include the @code{help} builtin, which displays help on shell builtins and +variables (@pxref{Bash Builtins}). + +@item --enable-history +Include command history and the @code{fc} and @code{history} +builtin commands (@pxref{Bash History Facilities}). + +@item --enable-job-control +This enables the job control features (@pxref{Job Control}), +if the operating system supports them. + +@item --enable-multibyte +This enables support for multibyte characters if the operating +system provides the necessary support. + +@item --enable-net-redirections +This enables the special handling of filenames of the form +@code{/dev/tcp/@var{host}/@var{port}} and +@code{/dev/udp/@var{host}/@var{port}} +when used in redirections (@pxref{Redirections}). + +@item --enable-process-substitution +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-readline +Include support for command-line editing and history with the Bash +version of the Readline library (@pxref{Command Line Editing}). + +@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{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}. + +@item --enable-xpg-echo-default +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 3. +@xref{Bash Builtins}, for a description of the escape sequences that +@code{echo} recognizes. + +@end table + +The file @file{config-top.h} contains C Preprocessor +@samp{#define} statements for options which are not settable from +@code{configure}. +Some of these are not meant to be changed; beware of the consequences if +you do. +Read the comments associated with each definition for more +information about its effect. + +@node Reporting Bugs +@appendix Reporting Bugs + +Please report all bugs you find in Bash. +But first, you should +make sure that it really is a bug, and that it appears in the latest +version of Bash. +The latest version of Bash is always available for FTP from +@uref{ftp://ftp.gnu.org/pub/gnu/bash/}. + +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 encouraged to mail that as well! +Suggestions and `philosophical' bug reports may be mailed +to @email{bug-bash@@gnu.org} or posted to the Usenet +newsgroup @code{gnu.bash.bug}. + +All bug reports should include: +@itemize @bullet +@item +The version number of Bash. +@item +The hardware and operating system. +@item +The compiler used to compile Bash. +@item +A description of the bug behaviour. +@item +A short script or `recipe' which exercises the bug and may be used +to reproduce it. +@end itemize + +@noindent +@code{bashbug} inserts the first three items automatically into +the template it provides for filing a bug report. + +Please send all reports concerning this manual to +@email{chet.ramey@@case.edu}. + +@node Major Differences From The Bourne Shell +@appendix Major Differences From The Bourne Shell + +Bash implements essentially the same grammar, parameter and +variable expansion, redirection, and quoting as the Bourne Shell. +Bash uses the @sc{posix} standard as the specification of +how these features are to be implemented. There are some +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 (the +last version of the historical Bourne shell) as the baseline reference. + +@itemize @bullet + +@item +Bash is @sc{posix}-conformant, even where the @sc{posix} specification +differs from traditional @code{sh} behavior (@pxref{Bash POSIX Mode}). + +@item +Bash has multi-character invocation options (@pxref{Invoking Bash}). + +@item +Bash has command-line editing (@pxref{Command Line Editing}) and +the @code{bind} builtin. + +@item +Bash provides a programmable word completion mechanism +(@pxref{Programmable Completion}), and builtin commands +@code{complete}, @code{compgen}, and @code{compopt}, to +manipulate it. + +@item +Bash has command history (@pxref{Bash History Facilities}) and the +@code{history} and @code{fc} builtins to manipulate it. +The Bash history list maintains timestamp information and uses the +value of the @code{HISTTIMEFORMAT} variable to display it. + +@item +Bash implements @code{csh}-like history expansion +(@pxref{History Interaction}). + +@item +Bash has one-dimensional array variables (@pxref{Arrays}), and the +appropriate variable expansions and assignment syntax to use them. +Several of the Bash builtins take options to act on arrays. +Bash provides a number of built-in array variables. + +@item +The @code{$'@dots{}'} quoting syntax, which expands ANSI-C +backslash-escaped characters in the text between the single quotes, +is supported (@pxref{ANSI-C Quoting}). + +@item +Bash supports the @code{$"@dots{}"} quoting syntax to do +locale-specific translation of the characters between the double +quotes. The @option{-D}, @option{--dump-strings}, and @option{--dump-po-strings} +invocation options list the translatable strings found in a script +(@pxref{Locale Translation}). + +@item +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}). +The display of the timing statistics may be controlled with the +@env{TIMEFORMAT} variable. + +@item +Bash implements the @code{for (( @var{expr1} ; @var{expr2} ; @var{expr3} ))} +arithmetic for command, similar to the C language (@pxref{Looping Constructs}). + +@item +Bash includes the @code{select} compound command, which allows the +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}), 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 +expansion (@pxref{Tilde Expansion}). + +@item +Bash implements command aliases and the @code{alias} and @code{unalias} +builtins (@pxref{Aliases}). + +@item +Bash provides shell arithmetic, the @code{((} compound command +(@pxref{Conditional Constructs}), +and arithmetic expansion (@pxref{Shell Arithmetic}). + +@item +Variables present in the shell's initial environment are automatically +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 +variable values (@pxref{Shell Parameter Expansion}). + +@item +The expansion @code{$@{#xx@}}, which returns the length of @code{$@{xx@}}, +is supported (@pxref{Shell Parameter Expansion}). + +@item +The expansion @code{$@{var:}@var{offset}@code{[:}@var{length}@code{]@}}, +which expands to the substring of @code{var}'s value of length +@var{length}, beginning at @var{offset}, is present +(@pxref{Shell Parameter Expansion}). + +@item +The expansion +@code{$@{var/[/]}@var{pattern}@code{[/}@var{replacement}@code{]@}}, +which matches @var{pattern} and replaces it with @var{replacement} in +the value of @code{var}, is available (@pxref{Shell Parameter Expansion}). + +@item +The expansion @code{$@{!@var{prefix@}*}} expansion, which expands to +the names of all shell variables whose names begin with @var{prefix}, +is available (@pxref{Shell Parameter Expansion}). + +@item +Bash has @var{indirect} variable expansion using @code{$@{!word@}} +(@pxref{Shell Parameter Expansion}). + +@item +Bash can expand positional parameters beyond @code{$9} using +@code{$@{@var{num}@}}. + +@item +The @sc{posix} @code{$()} form of command substitution +is implemented (@pxref{Command Substitution}), +and preferred to the Bourne shell's @code{``} (which +is also implemented for backwards compatibility). + +@item +Bash has process substitution (@pxref{Process Substitution}). + +@item +Bash automatically assigns variables that provide information about the +current user (@env{UID}, @env{EUID}, and @env{GROUPS}), the current host +(@env{HOSTTYPE}, @env{OSTYPE}, @env{MACHTYPE}, and @env{HOSTNAME}), +and the instance of Bash that is running (@env{BASH}, +@env{BASH_VERSION}, and @env{BASH_VERSINFO}). @xref{Bash Variables}, +for details. + +@item +The @env{IFS} variable is used to split only the results of expansion, +not all words (@pxref{Word Splitting}). +This closes a longstanding shell security hole. + +@item +Bash implements the full set of @sc{posix} filename expansion operators, +including @var{character classes}, @var{equivalence classes}, and +@var{collating symbols} (@pxref{Filename Expansion}). + +@item +Bash implements extended pattern matching features when the @code{extglob} +shell option is enabled (@pxref{Pattern Matching}). + +@item +It is possible to have a variable and a function with the same name; +@code{sh} does not separate the two name spaces. + +@item +Bash functions are permitted to have local variables using the +@code{local} builtin, and thus useful recursive functions may be written +(@pxref{Bash Builtins}). + +@item +Variable assignments preceding commands affect only that command, even +builtins and functions (@pxref{Environment}). +In @code{sh}, all variable assignments +preceding commands are global unless the command is executed from the +file system. + +@item +Bash performs filename expansion on filenames specified as operands +to input and output redirection operators (@pxref{Redirections}). + +@item +Bash contains the @samp{<>} redirection operator, allowing a file to be +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}). + +@item +Bash can open network connections to arbitrary machines and services +with the redirection operators (@pxref{Redirections}). + +@item +The @code{noclobber} option is available to avoid overwriting existing +files with output redirection (@pxref{The Set Builtin}). +The @samp{>|} redirection operator may be used to override @code{noclobber}. + +@item +The Bash @code{cd} and @code{pwd} builtins (@pxref{Bourne Shell Builtins}) +each take @option{-L} and @option{-P} options to switch between logical and +physical modes. + +@item +Bash allows a function to override a builtin with the same name, and provides +access to that builtin's functionality within the function via the +@code{builtin} and @code{command} builtins (@pxref{Bash Builtins}). + +@item +The @code{command} builtin allows selective disabling of functions +when command lookup is performed (@pxref{Bash Builtins}). + +@item +Individual builtins may be enabled or disabled using the @code{enable} +builtin (@pxref{Bash Builtins}). + +@item +The Bash @code{exec} builtin takes additional options that allow users +to control the contents of the environment passed to the executed +command, and what the zeroth argument to the command is to be +(@pxref{Bourne Shell Builtins}). + +@item +Shell functions may be exported to children via the environment +using @code{export -f} (@pxref{Shell Functions}). + +@item +The Bash @code{export}, @code{readonly}, and @code{declare} builtins can +take a @option{-f} option to act on shell functions, a @option{-p} option to +display variables with various attributes set in a format that can be +used as shell input, a @option{-n} option to remove various variable +attributes, and @samp{name=value} arguments to set variable attributes +and values simultaneously. + +@item +The Bash @code{hash} builtin allows a name to be associated with +an arbitrary filename, even when that filename cannot be found by +searching the @env{$PATH}, using @samp{hash -p} +(@pxref{Bourne Shell Builtins}). + +@item +Bash includes a @code{help} builtin for quick reference to shell +facilities (@pxref{Bash Builtins}). + +@item +The @code{printf} builtin is available to display formatted output +(@pxref{Bash Builtins}). + +@item +The Bash @code{read} builtin (@pxref{Bash Builtins}) +will read a line ending in @samp{\} with +the @option{-r} option, and will use the @env{REPLY} variable as a +default if no non-option arguments are supplied. +The Bash @code{read} builtin +also accepts a prompt string with the @option{-p} option and will use +Readline to obtain the line when given the @option{-e} option. +The @code{read} builtin also has additional options to control input: +the @option{-s} option will turn off echoing of input characters as +they are read, the @option{-t} option will allow @code{read} to time out +if input does not arrive within a specified number of seconds, the +@option{-n} option will allow reading only a specified number of +characters rather than a full line, and the @option{-d} option will read +until a particular character rather than newline. + +@item +The @code{return} builtin may be used to abort execution of scripts +executed with the @code{.} or @code{source} builtins +(@pxref{Bourne Shell Builtins}). + +@item +Bash includes the @code{shopt} builtin, for finer control of shell +optional capabilities (@pxref{The Shopt Builtin}), and allows these options +to be set and unset at shell invocation (@pxref{Invoking Bash}). + +@item +Bash has much more optional behavior controllable with the @code{set} +builtin (@pxref{The Set Builtin}). + +@item +The @samp{-x} (@code{xtrace}) option displays commands other than +simple commands when performing an execution trace +(@pxref{The Set Builtin}). + +@item +The @code{test} builtin (@pxref{Bourne Shell Builtins}) +is slightly different, as it implements the @sc{posix} algorithm, +which specifies the behavior based on the number of arguments. + +@item +Bash includes the @code{caller} builtin, which displays the context of +any active subroutine call (a shell function or a script executed with +the @code{.} or @code{source} builtins). This supports the bash +debugger. + +@item +The @code{trap} builtin (@pxref{Bourne Shell Builtins}) allows a +@code{DEBUG} pseudo-signal specification, similar to @code{EXIT}. +Commands specified with a @code{DEBUG} trap are executed before every +simple command, @code{for} command, @code{case} command, +@code{select} command, every arithmetic @code{for} command, and before +the first command executes in a shell function. +The @code{DEBUG} 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. +The @code{extdebug} shell option has additional effects on the +@code{DEBUG} trap. + +The @code{trap} builtin (@pxref{Bourne Shell Builtins}) allows an +@code{ERR} pseudo-signal specification, similar to @code{EXIT} and @code{DEBUG}. +Commands specified with an @code{ERR} trap are executed after a simple +command fails, with a few exceptions. +The @code{ERR} trap is not inherited by shell functions unless the +@code{-o errtrace} option to the @code{set} builtin is enabled. + +The @code{trap} builtin (@pxref{Bourne Shell Builtins}) allows a +@code{RETURN} pseudo-signal specification, similar to +@code{EXIT} and @code{DEBUG}. +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 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 +about the names it finds (@pxref{Bash Builtins}). + +@item +The Bash @code{umask} builtin permits a @option{-p} option to cause +the output to be displayed in the form of a @code{umask} command +that may be reused as input (@pxref{Bourne Shell Builtins}). + +@item +Bash implements a @code{csh}-like directory stack, and provides the +@code{pushd}, @code{popd}, and @code{dirs} builtins to manipulate it +(@pxref{The Directory Stack}). +Bash also makes the directory stack visible as the value of the +@env{DIRSTACK} shell variable. + +@item +Bash interprets special backslash-escaped characters in the prompt +strings when interactive (@pxref{Printing a Prompt}). + +@item +The Bash restricted mode is more useful (@pxref{The Restricted Shell}); +the SVR4.2 shell restricted mode is too limited. + +@item +The @code{disown} builtin can remove a job from the internal shell +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. + +@item +Bash does not have the @code{stop} or @code{newgrp} builtins. + +@item +Bash does not use the @env{SHACCT} variable or perform shell accounting. + +@item +The SVR4.2 @code{sh} uses a @env{TIMEOUT} variable like Bash uses +@env{TMOUT}. + +@end itemize + +@noindent +More features unique to Bash may be found in @ref{Bash Features}. + + +@appendixsec Implementation Differences From The SVR4.2 Shell + +Since Bash is a completely new implementation, it does not suffer from +many of the limitations of the SVR4.2 shell. For instance: + +@itemize @bullet + +@item +Bash does not fork a subshell when redirecting into or out of +a shell control structure such as an @code{if} or @code{while} +statement. + +@item +Bash does not allow unbalanced quotes. The SVR4.2 shell will silently +insert a needed closing quote at @code{EOF} under certain circumstances. +This can be the cause of some hard-to-find errors. + +@item +The SVR4.2 shell uses a baroque memory management scheme based on +trapping @code{SIGSEGV}. If the shell is started from a process with +@code{SIGSEGV} blocked (e.g., by using the @code{system()} C library +function call), it misbehaves badly. + +@item +In a questionable attempt at security, the SVR4.2 shell, +when invoked without the @option{-p} option, will alter its real +and effective @sc{uid} and @sc{gid} if they are less than some +magic threshold value, commonly 100. +This can lead to unexpected results. + +@item +The SVR4.2 shell does not allow users to trap @code{SIGSEGV}, +@code{SIGALRM}, or @code{SIGCHLD}. + +@item +The SVR4.2 shell does not allow the @env{IFS}, @env{MAILCHECK}, +@env{PATH}, @env{PS1}, or @env{PS2} variables to be unset. + +@item +The SVR4.2 shell treats @samp{^} as the undocumented equivalent of +@samp{|}. + +@item +Bash allows multiple option arguments when it is invoked (@code{-x -v}); +the SVR4.2 shell allows only one option argument (@code{-xv}). In +fact, some versions of the shell dump core if the second argument begins +with a @samp{-}. + +@item +The SVR4.2 shell exits a script if any builtin fails; Bash exits +a script only if one of the @sc{posix} special builtins fails, and +only for certain failures, as enumerated in the @sc{posix} standard. + +@item +The SVR4.2 shell behaves differently when invoked as @code{jsh} +(it turns on job control). +@end itemize + +@node GNU Free Documentation License +@appendix GNU Free Documentation License + +@include fdl.texi + +@node Indexes +@appendix Indexes + +@menu +* 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 + +@node Builtin Index +@appendixsec Index of Shell Builtin Commands +@printindex bt + +@node Reserved Word Index +@appendixsec Index of Shell Reserved Words +@printindex rw + +@node Variable Index +@appendixsec Parameter and Variable Index +@printindex vr + +@node Function Index +@appendixsec Function Index +@printindex fn + +@node Concept Index +@appendixsec Concept Index +@printindex cp + +@bye |