1 \input texinfo.tex @c -*- texinfo -*-
3 @setfilename bashref.info
4 @settitle Bash Reference Manual
12 This text is a brief description of the features that are present in
13 the Bash shell (version @value{VERSION}, @value{UPDATED}).
15 This is Edition @value{EDITION}, last updated @value{UPDATED},
16 of @cite{The GNU Bash Reference Manual},
17 for @code{Bash}, Version @value{VERSION}.
19 Copyright @copyright{} 1988--2009 Free Software Foundation, Inc.
21 Permission is granted to make and distribute verbatim copies of
22 this manual provided the copyright notice and this permission notice
23 are preserved on all copies.
26 Permission is granted to copy, distribute and/or modify this document
27 under the terms of the GNU Free Documentation License, Version 1.3 or
28 any later version published by the Free Software Foundation; with no
29 Invariant Sections, with the Front-Cover texts being ``A GNU Manual'',
30 and with the Back-Cover Texts as in (a) below. A copy of the license is
31 included in the section entitled ``GNU Free Documentation License''.
33 (a) The FSF's Back-Cover Text is: You are free to copy and modify
34 this GNU manual. Buying copies from GNU Press supports the FSF in
35 developing GNU and promoting software freedom.''
46 * Bash: (bash). The GNU Bourne-Again SHell.
52 @title Bash Reference Manual
53 @subtitle Reference Documentation for Bash
54 @subtitle Edition @value{EDITION}, for @code{Bash} Version @value{VERSION}.
55 @subtitle @value{UPDATED-MONTH}
56 @author Chet Ramey, Case Western Reserve University
57 @author Brian Fox, Free Software Foundation
60 @vskip 0pt plus 1filll
64 Published by the Free Software Foundation @*
65 59 Temple Place, Suite 330, @*
66 Boston, MA 02111-1307 @*
74 @node Top, Introduction, (dir), (dir)
77 This text is a brief description of the features that are present in
78 the Bash shell (version @value{VERSION}, @value{UPDATED}).
80 This is Edition @value{EDITION}, last updated @value{UPDATED},
81 of @cite{The GNU Bash Reference Manual},
82 for @code{Bash}, Version @value{VERSION}.
84 Bash contains features that appear in other popular shells, and some
85 features that only appear in Bash. Some of the shells that Bash has
86 borrowed concepts from are the Bourne Shell (@file{sh}), the Korn Shell
87 (@file{ksh}), and the C-shell (@file{csh} and its successor,
88 @file{tcsh}). The following menu breaks the features up into
89 categories based upon which one of these other shells inspired the
92 This manual is meant as a brief introduction to features found in
93 Bash. The Bash manual page should be used as the definitive
94 reference on shell behavior.
97 * Introduction:: An introduction to the shell.
98 * Definitions:: Some definitions used in the rest of this
100 * Basic Shell Features:: The shell "building blocks".
101 * Shell Builtin Commands:: Commands that are a part of the shell.
102 * Shell Variables:: Variables used or set by Bash.
103 * Bash Features:: Features found only in Bash.
104 * Job Control:: What job control is and how Bash allows you
106 * Command Line Editing:: Chapter describing the command line
108 * Using History Interactively:: Command History Expansion
109 * Installing Bash:: How to build and install Bash on your system.
110 * Reporting Bugs:: How to report bugs in Bash.
111 * Major Differences From The Bourne Shell:: A terse list of the differences
112 between Bash and historical
114 * GNU Free Documentation License:: Copying and sharing this documentation.
115 * Indexes:: Various indexes for this manual.
120 @chapter Introduction
122 * What is Bash?:: A short description of Bash.
123 * What is a shell?:: A brief introduction to shells.
127 @section What is Bash?
129 Bash is the shell, or command language interpreter,
130 for the @sc{gnu} operating system.
131 The name is an acronym for the @samp{Bourne-Again SHell},
132 a pun on Stephen Bourne, the author of the direct ancestor of
133 the current Unix shell @code{sh},
134 which appeared in the Seventh Edition Bell Labs Research version
137 Bash is largely compatible with @code{sh} and incorporates useful
138 features from the Korn shell @code{ksh} and the C shell @code{csh}.
139 It is intended to be a conformant implementation of the @sc{ieee}
140 @sc{posix} Shell and Tools portion of the @sc{ieee} @sc{posix}
141 specification (@sc{ieee} Standard 1003.1).
142 It offers functional improvements over @code{sh} for both interactive and
145 While the @sc{gnu} operating system provides other shells, including
146 a version of @code{csh}, Bash is the default shell.
147 Like other @sc{gnu} software, Bash is quite portable. It currently runs
148 on nearly every version of Unix and a few other operating systems @minus{}
149 independently-supported ports exist for @sc{ms-dos}, @sc{os/2},
150 and Windows platforms.
152 @node What is a shell?
153 @section What is a shell?
155 At its base, a shell is simply a macro processor that executes
156 commands. The term macro processor means functionality where text
157 and symbols are expanded to create larger expressions.
159 A Unix shell is both a command interpreter and a programming
160 language. As a command interpreter, the shell provides the user
161 interface to the rich set of @sc{gnu} utilities. The programming
162 language features allow these utilities to be combined.
163 Files containing commands can be created, and become
164 commands themselves. These new commands have the same status as
165 system commands in directories such as @file{/bin}, allowing users
166 or groups to establish custom environments to automate their common
169 Shells may be used interactively or non-interactively. In
170 interactive mode, they accept input typed from the keyboard.
171 When executing non-interactively, shells execute commands read
174 A shell allows execution of @sc{gnu} commands, both synchronously and
176 The shell waits for synchronous commands to complete before accepting
177 more input; asynchronous commands continue to execute in parallel
178 with the shell while it reads and executes additional commands.
179 The @dfn{redirection} constructs permit
180 fine-grained control of the input and output of those commands.
181 Moreover, the shell allows control over the contents of commands'
184 Shells also provide a small set of built-in
185 commands (@dfn{builtins}) implementing functionality impossible
186 or inconvenient to obtain via separate utilities.
187 For example, @code{cd}, @code{break}, @code{continue}, and
188 @code{exec}) cannot be implemented outside of the shell because
189 they directly manipulate the shell itself.
190 The @code{history}, @code{getopts}, @code{kill}, or @code{pwd}
191 builtins, among others, could be implemented in separate utilities,
192 but they are more convenient to use as builtin commands.
193 All of the shell builtins are described in
196 While executing commands is essential, most of the power (and
197 complexity) of shells is due to their embedded programming
198 languages. Like any high-level language, the shell provides
199 variables, flow control constructs, quoting, and functions.
201 Shells offer features geared specifically for
202 interactive use rather than to augment the programming language.
203 These interactive features include job control, command line
204 editing, command history and aliases. Each of these features is
205 described in this manual.
209 These definitions are used throughout the remainder of this manual.
215 A family of open system standards based on Unix. Bash
216 is primarily concerned with the Shell and Utilities portion of the
217 @sc{posix} 1003.1 standard.
220 A space or tab character.
224 A command that is implemented internally by the shell itself, rather
225 than by an executable program somewhere in the file system.
227 @item control operator
228 @cindex control operator
229 A @code{token} that performs a control function. It is a @code{newline}
230 or one of the following:
231 @samp{||}, @samp{&&}, @samp{&}, @samp{;}, @samp{;;},
232 @samp{|}, @samp{|&}, @samp{(}, or @samp{)}.
236 The value returned by a command to its caller. The value is restricted
237 to eight bits, so the maximum value is 255.
241 A unit of text that is the result of one of the shell expansions. After
242 expansion, when executing a command, the resulting fields are used as
243 the command name and arguments.
247 A string of characters used to identify a file.
251 A set of processes comprising a pipeline, and any processes descended
252 from it, that are all in the same process group.
256 A mechanism by which users can selectively stop (suspend) and restart
257 (resume) execution of processes.
260 @cindex metacharacter
261 A character that, when unquoted, separates words. A metacharacter is
262 a @code{blank} or one of the following characters:
263 @samp{|}, @samp{&}, @samp{;}, @samp{(}, @samp{)}, @samp{<}, or
269 A @code{word} consisting solely of letters, numbers, and underscores,
270 and beginning with a letter or underscore. @code{Name}s are used as
271 shell variable and function names.
272 Also referred to as an @code{identifier}.
275 @cindex operator, shell
276 A @code{control operator} or a @code{redirection operator}.
277 @xref{Redirections}, for a list of redirection operators.
278 Operators contain at least one unquoted @code{metacharacter}.
281 @cindex process group
282 A collection of related processes each having the same process
285 @item process group ID
286 @cindex process group ID
287 A unique identifier that represents a @code{process group}
291 @cindex reserved word
292 A @code{word} that has a special meaning to the shell. Most reserved
293 words introduce shell flow control constructs, such as @code{for} and
297 @cindex return status
298 A synonym for @code{exit status}.
302 A mechanism by which a process may be notified by the kernel
303 of an event occurring in the system.
305 @item special builtin
306 @cindex special builtin
307 A shell builtin command that has been classified as special by the
312 A sequence of characters considered a single unit by the shell.
313 It is either a @code{word} or an @code{operator}.
317 A sequence of characters treated as a unit by the shell.
318 Words may not include unquoted @code{metacharacters}.
321 @node Basic Shell Features
322 @chapter Basic Shell Features
325 Bash is an acronym for @samp{Bourne-Again SHell}.
327 the traditional Unix shell originally written by Stephen Bourne.
328 All of the Bourne shell builtin commands are available in Bash,
329 The rules for evaluation and quoting are taken from the @sc{posix}
330 specification for the `standard' Unix shell.
332 This chapter briefly summarizes the shell's `building blocks':
333 commands, control structures, shell functions, shell @i{parameters},
335 @i{redirections}, which are a way to direct input and output from
336 and to named files, and how the shell executes commands.
339 * Shell Syntax:: What your input means to the shell.
340 * Shell Commands:: The types of commands you can use.
341 * Shell Functions:: Grouping commands by name.
342 * Shell Parameters:: How the shell stores values.
343 * Shell Expansions:: How Bash expands parameters and the various
344 expansions available.
345 * Redirections:: A way to control where input and output go.
346 * Executing Commands:: What happens when you run a command.
347 * Shell Scripts:: Executing files of shell commands.
351 @section Shell Syntax
353 * Shell Operation:: The basic operation of the shell.
354 * Quoting:: How to remove the special meaning from characters.
355 * Comments:: How to specify comments.
358 When the shell reads input, it proceeds through a
359 sequence of operations. If the input indicates the beginning of a
360 comment, the shell ignores the comment symbol (@samp{#}), and the rest
363 Otherwise, roughly speaking, the shell reads its input and
364 divides the input into words and operators, employing the quoting rules
365 to select which meanings to assign various words and characters.
367 The shell then parses these tokens into commands and other constructs,
368 removes the special meaning of certain words or characters, expands
369 others, redirects input and output as needed, executes the specified
370 command, waits for the command's exit status, and makes that exit status
371 available for further inspection or processing.
373 @node Shell Operation
374 @subsection Shell Operation
376 The following is a brief description of the shell's operation when it
377 reads and executes a command. Basically, the shell does the
382 Reads its input from a file (@pxref{Shell Scripts}), from a string
383 supplied as an argument to the @option{-c} invocation option
384 (@pxref{Invoking Bash}), or from the user's terminal.
387 Breaks the input into words and operators, obeying the quoting rules
388 described in @ref{Quoting}. These tokens are separated by
389 @code{metacharacters}. Alias expansion is performed by this step
393 Parses the tokens into simple and compound commands
394 (@pxref{Shell Commands}).
397 Performs the various shell expansions (@pxref{Shell Expansions}), breaking
398 the expanded tokens into lists of filenames (@pxref{Filename Expansion})
399 and commands and arguments.
402 Performs any necessary redirections (@pxref{Redirections}) and removes
403 the redirection operators and their operands from the argument list.
406 Executes the command (@pxref{Executing Commands}).
409 Optionally waits for the command to complete and collects its exit
410 status (@pxref{Exit Status}).
418 * Escape Character:: How to remove the special meaning from a single
420 * Single Quotes:: How to inhibit all interpretation of a sequence
422 * Double Quotes:: How to suppress most of the interpretation of a
423 sequence of characters.
424 * ANSI-C Quoting:: How to expand ANSI-C sequences in quoted strings.
425 * Locale Translation:: How to translate strings into different languages.
428 Quoting is used to remove the special meaning of certain
429 characters or words to the shell. Quoting can be used to
430 disable special treatment for special characters, to prevent
431 reserved words from being recognized as such, and to prevent
434 Each of the shell metacharacters (@pxref{Definitions})
435 has special meaning to the shell and must be quoted if it is to
437 When the command history expansion facilities are being used
438 (@pxref{History Interaction}), the
439 @var{history expansion} character, usually @samp{!}, must be quoted
440 to prevent history expansion. @xref{Bash History Facilities}, for
441 more details concerning history expansion.
443 There are three quoting mechanisms: the
444 @var{escape character}, single quotes, and double quotes.
446 @node Escape Character
447 @subsubsection Escape Character
448 A non-quoted backslash @samp{\} is the Bash escape character.
449 It preserves the literal value of the next character that follows,
450 with the exception of @code{newline}. If a @code{\newline} pair
451 appears, and the backslash itself is not quoted, the @code{\newline}
452 is treated as a line continuation (that is, it is removed from
453 the input stream and effectively ignored).
456 @subsubsection Single Quotes
458 Enclosing characters in single quotes (@samp{'}) preserves the literal value
459 of each character within the quotes. A single quote may not occur
460 between single quotes, even when preceded by a backslash.
463 @subsubsection Double Quotes
465 Enclosing characters in double quotes (@samp{"}) preserves the literal value
466 of all characters within the quotes, with the exception of
467 @samp{$}, @samp{`}, @samp{\},
468 and, when history expansion is enabled, @samp{!}.
469 The characters @samp{$} and @samp{`}
470 retain their special meaning within double quotes (@pxref{Shell Expansions}).
471 The backslash retains its special meaning only when followed by one of
472 the following characters:
473 @samp{$}, @samp{`}, @samp{"}, @samp{\}, or @code{newline}.
474 Within double quotes, backslashes that are followed by one of these
475 characters are removed. Backslashes preceding characters without a
476 special meaning are left unmodified.
477 A double quote may be quoted within double quotes by preceding it with
479 If enabled, history expansion will be performed unless an @samp{!}
480 appearing in double quotes is escaped using a backslash.
481 The backslash preceding the @samp{!} is not removed.
483 The special parameters @samp{*} and @samp{@@} have special meaning
484 when in double quotes (@pxref{Shell Parameter Expansion}).
487 @subsubsection ANSI-C Quoting
488 @cindex quoting, ANSI
490 Words of the form @code{$'@var{string}'} are treated specially. The
491 word expands to @var{string}, with backslash-escaped characters replaced
492 as specified by the ANSI C standard. Backslash escape sequences, if
493 present, are decoded as follows:
501 an escape character (not ANSI C)
517 the eight-bit character whose value is the octal value @var{nnn}
518 (one to three digits)
520 the eight-bit character whose value is the hexadecimal value @var{HH}
521 (one or two hex digits)
523 a control-@var{x} character
527 The expanded result is single-quoted, as if the dollar sign had not
530 @node Locale Translation
531 @subsubsection Locale-Specific Translation
533 @cindex internationalization
534 @cindex native languages
535 @cindex translation, native languages
537 A double-quoted string preceded by a dollar sign (@samp{$}) will cause
538 the string to be translated according to the current locale.
539 If the current locale is @code{C} or @code{POSIX}, the dollar sign
541 If the string is translated and replaced, the replacement is
546 @vindex TEXTDOMAINDIR
547 Some systems use the message catalog selected by the @env{LC_MESSAGES}
548 shell variable. Others create the name of the message catalog from the
549 value of the @env{TEXTDOMAIN} shell variable, possibly adding a
550 suffix of @samp{.mo}. If you use the @env{TEXTDOMAIN} variable, you
551 may need to set the @env{TEXTDOMAINDIR} variable to the location of
552 the message catalog files. Still others use both variables in this
554 @env{TEXTDOMAINDIR}/@env{LC_MESSAGES}/LC_MESSAGES/@env{TEXTDOMAIN}.mo.
558 @cindex comments, shell
560 In a non-interactive shell, or an interactive shell in which the
561 @code{interactive_comments} option to the @code{shopt}
562 builtin is enabled (@pxref{The Shopt Builtin}),
563 a word beginning with @samp{#}
564 causes that word and all remaining characters on that line to
565 be ignored. An interactive shell without the @code{interactive_comments}
566 option enabled does not allow comments. The @code{interactive_comments}
567 option is on by default in interactive shells.
568 @xref{Interactive Shells}, for a description of what makes
572 @section Shell Commands
573 @cindex commands, shell
575 A simple shell command such as @code{echo a b c} consists of the command
576 itself followed by arguments, separated by spaces.
578 More complex shell commands are composed of simple commands arranged together
579 in a variety of ways: in a pipeline in which the output of one command
580 becomes the input of a second, in a loop or conditional construct, or in
584 * Simple Commands:: The most common type of command.
585 * Pipelines:: Connecting the input and output of several
587 * Lists:: How to execute commands sequentially.
588 * Compound Commands:: Shell commands for control flow.
589 * Coprocesses:: Two-way communication between commands.
592 @node Simple Commands
593 @subsection Simple Commands
594 @cindex commands, simple
596 A simple command is the kind of command encountered most often.
597 It's just a sequence of words separated by @code{blank}s, terminated
598 by one of the shell's control operators (@pxref{Definitions}). The
599 first word generally specifies a command to be executed, with the
600 rest of the words being that command's arguments.
602 The return status (@pxref{Exit Status}) of a simple command is
603 its exit status as provided
604 by the @sc{posix} 1003.1 @code{waitpid} function, or 128+@var{n} if
605 the command was terminated by signal @var{n}.
608 @subsection Pipelines
610 @cindex commands, pipelines
612 A @code{pipeline} is a sequence of simple commands separated by one of
613 the control operators @samp{|} or @samp{|&}.
617 @cindex command timing
618 The format for a pipeline is
620 [@code{time} [@code{-p}]] [@code{!}] @var{command1} [ [@code{|} or @code{|&}] @var{command2} @dots{}]
624 The output of each command in the pipeline is connected via a pipe
625 to the input of the next command.
626 That is, each command reads the previous command's output. This
627 connection is performed before any redirections specified by the
630 If @samp{|&} is used, the standard error of @var{command1} is connected to
631 @var{command2}'s standard input through the pipe; it is shorthand for
632 @code{2>&1 |}. This implicit redirection of the standard error is
633 performed after any redirections specified by the command.
635 The reserved word @code{time} causes timing statistics
636 to be printed for the pipeline once it finishes.
637 The statistics currently consist of elapsed (wall-clock) time and
638 user and system time consumed by the command's execution.
639 The @option{-p} option changes the output format to that specified
641 The @env{TIMEFORMAT} variable may be set to a format string that
642 specifies how the timing information should be displayed.
643 @xref{Bash Variables}, for a description of the available formats.
644 The use of @code{time} as a reserved word permits the timing of
645 shell builtins, shell functions, and pipelines. An external
646 @code{time} command cannot time these easily.
648 If the pipeline is not executed asynchronously (@pxref{Lists}), the
649 shell waits for all commands in the pipeline to complete.
651 Each command in a pipeline is executed in its own subshell
652 (@pxref{Command Execution Environment}). The exit
653 status of a pipeline is the exit status of the last command in the
654 pipeline, unless the @code{pipefail} option is enabled
655 (@pxref{The Set Builtin}).
656 If @code{pipefail} is enabled, the pipeline's return status is the
657 value of the last (rightmost) command to exit with a non-zero status,
658 or zero if all commands exit successfully.
659 If the reserved word @samp{!} precedes the pipeline, the
660 exit status is the logical negation of the exit status as described
662 The shell waits for all commands in the pipeline to terminate before
666 @subsection Lists of Commands
667 @cindex commands, lists
669 A @code{list} is a sequence of one or more pipelines separated by one
670 of the operators @samp{;}, @samp{&}, @samp{&&}, or @samp{||},
671 and optionally terminated by one of @samp{;}, @samp{&}, or a
674 Of these list operators, @samp{&&} and @samp{||}
675 have equal precedence, followed by @samp{;} and @samp{&},
676 which have equal precedence.
678 A sequence of one or more newlines may appear in a @code{list}
679 to delimit commands, equivalent to a semicolon.
681 If a command is terminated by the control operator @samp{&},
682 the shell executes the command asynchronously in a subshell.
683 This is known as executing the command in the @var{background}.
684 The shell does not wait for the command to finish, and the return
686 When job control is not active (@pxref{Job Control}),
687 the standard input for asynchronous commands, in the absence of any
688 explicit redirections, is redirected from @code{/dev/null}.
690 Commands separated by a @samp{;} are executed sequentially; the shell
691 waits for each command to terminate in turn. The return status is the
692 exit status of the last command executed.
694 @sc{and} and @sc{or} lists are sequences of one or more pipelines
695 separated by the control operators @samp{&&} and @samp{||},
696 respectively. @sc{and} and @sc{or} lists are executed with left
699 An @sc{and} list has the form
701 @var{command1} && @var{command2}
705 @var{command2} is executed if, and only if, @var{command1}
706 returns an exit status of zero.
708 An @sc{or} list has the form
710 @var{command1} || @var{command2}
714 @var{command2} is executed if, and only if, @var{command1}
715 returns a non-zero exit status.
718 @sc{and} and @sc{or} lists is the exit status of the last command
719 executed in the list.
721 @node Compound Commands
722 @subsection Compound Commands
723 @cindex commands, compound
726 * Looping Constructs:: Shell commands for iterative action.
727 * Conditional Constructs:: Shell commands for conditional execution.
728 * Command Grouping:: Ways to group commands.
731 Compound commands are the shell programming constructs.
732 Each construct begins with a reserved word or control operator and is
733 terminated by a corresponding reserved word or operator.
734 Any redirections (@pxref{Redirections}) associated with a compound command
735 apply to all commands within that compound command unless explicitly overridden.
737 Bash provides looping constructs, conditional commands, and mechanisms
738 to group commands and execute them as a unit.
740 @node Looping Constructs
741 @subsubsection Looping Constructs
742 @cindex commands, looping
744 Bash supports the following looping constructs.
746 Note that wherever a @samp{;} appears in the description of a
747 command's syntax, it may be replaced with one or more newlines.
754 The syntax of the @code{until} command is:
756 until @var{test-commands}; do @var{consequent-commands}; done
758 Execute @var{consequent-commands} as long as
759 @var{test-commands} has an exit status which is not zero.
760 The return status is the exit status of the last command executed
761 in @var{consequent-commands}, or zero if none was executed.
765 The syntax of the @code{while} command is:
767 while @var{test-commands}; do @var{consequent-commands}; done
770 Execute @var{consequent-commands} as long as
771 @var{test-commands} has an exit status of zero.
772 The return status is the exit status of the last command executed
773 in @var{consequent-commands}, or zero if none was executed.
777 The syntax of the @code{for} command is:
780 for @var{name} [ [in [@var{words} @dots{}] ] ; ] do @var{commands}; done
782 Expand @var{words}, and execute @var{commands} once for each member
783 in the resultant list, with @var{name} bound to the current member.
784 If @samp{in @var{words}} is not present, the @code{for} command
785 executes the @var{commands} once for each positional parameter that is
786 set, as if @samp{in "$@@"} had been specified
787 (@pxref{Special Parameters}).
788 The return status is the exit status of the last command that executes.
789 If there are no items in the expansion of @var{words}, no commands are
790 executed, and the return status is zero.
792 An alternate form of the @code{for} command is also supported:
795 for (( @var{expr1} ; @var{expr2} ; @var{expr3} )) ; do @var{commands} ; done
797 First, the arithmetic expression @var{expr1} is evaluated according
798 to the rules described below (@pxref{Shell Arithmetic}).
799 The arithmetic expression @var{expr2} is then evaluated repeatedly
800 until it evaluates to zero.
801 Each time @var{expr2} evaluates to a non-zero value, @var{commands} are
802 executed and the arithmetic expression @var{expr3} is evaluated.
803 If any expression is omitted, it behaves as if it evaluates to 1.
804 The return value is the exit status of the last command in @var{list}
805 that is executed, or false if any of the expressions is invalid.
809 The @code{break} and @code{continue} builtins (@pxref{Bourne Shell Builtins})
810 may be used to control loop execution.
812 @node Conditional Constructs
813 @subsubsection Conditional Constructs
814 @cindex commands, conditional
823 The syntax of the @code{if} command is:
826 if @var{test-commands}; then
827 @var{consequent-commands};
828 [elif @var{more-test-commands}; then
829 @var{more-consequents};]
830 [else @var{alternate-consequents};]
834 The @var{test-commands} list is executed, and if its return status is zero,
835 the @var{consequent-commands} list is executed.
836 If @var{test-commands} returns a non-zero status, each @code{elif} list
837 is executed in turn, and if its exit status is zero,
838 the corresponding @var{more-consequents} is executed and the
840 If @samp{else @var{alternate-consequents}} is present, and
841 the final command in the final @code{if} or @code{elif} clause
842 has a non-zero exit status, then @var{alternate-consequents} is executed.
843 The return status is the exit status of the last command executed, or
844 zero if no condition tested true.
850 The syntax of the @code{case} command is:
853 @code{case @var{word} in [ [(] @var{pattern} [| @var{pattern}]@dots{}) @var{command-list} ;;]@dots{} esac}
856 @code{case} will selectively execute the @var{command-list} corresponding to
857 the first @var{pattern} that matches @var{word}.
858 If the shell option @code{nocasematch}
859 (see the description of @code{shopt} in @ref{The Shopt Builtin})
860 is enabled, the match is performed without regard to the case
861 of alphabetic characters.
862 The @samp{|} is used to separate multiple patterns, and the @samp{)}
863 operator terminates a pattern list.
864 A list of patterns and an associated command-list is known
867 Each clause must be terminated with @samp{;;}, @samp{;&}, or @samp{;;&}.
868 The @var{word} undergoes tilde expansion, parameter expansion, command
869 substitution, arithmetic expansion, and quote removal before matching is
870 attempted. Each @var{pattern} undergoes tilde expansion, parameter
871 expansion, command substitution, and arithmetic expansion.
873 There may be an arbitrary number of @code{case} clauses, each terminated
874 by a @samp{;;}, @samp{;&}, or @samp{;;&}.
875 The first pattern that matches determines the
876 command-list that is executed.
878 Here is an example using @code{case} in a script that could be used to
879 describe one interesting feature of an animal:
882 echo -n "Enter the name of an animal: "
884 echo -n "The $ANIMAL has "
886 horse | dog | cat) echo -n "four";;
887 man | kangaroo ) echo -n "two";;
888 *) echo -n "an unknown number of";;
895 If the @samp{;;} operator is used, no subsequent matches are attempted after
896 the first pattern match.
897 Using @samp{;&} in place of @samp{;;} causes execution to continue with
898 the @var{command-list} associated with the next clause, if any.
899 Using @samp{;;&} in place of @samp{;;} causes the shell to test the patterns
900 in the next clause, if any, and execute any associated @var{command-list}
901 on a successful match.
903 The return status is zero if no @var{pattern} is matched. Otherwise, the
904 return status is the exit status of the @var{command-list} executed.
909 The @code{select} construct allows the easy generation of menus.
910 It has almost the same syntax as the @code{for} command:
913 select @var{name} [in @var{words} @dots{}]; do @var{commands}; done
916 The list of words following @code{in} is expanded, generating a list
917 of items. The set of expanded words is printed on the standard
918 error output stream, each preceded by a number. If the
919 @samp{in @var{words}} is omitted, the positional parameters are printed,
920 as if @samp{in "$@@"} had been specified.
921 The @env{PS3} prompt is then displayed and a line is read from the
923 If the line consists of a number corresponding to one of the displayed
924 words, then the value of @var{name} is set to that word.
925 If the line is empty, the words and prompt are displayed again.
926 If @code{EOF} is read, the @code{select} command completes.
927 Any other value read causes @var{name} to be set to null.
928 The line read is saved in the variable @env{REPLY}.
930 The @var{commands} are executed after each selection until a
931 @code{break} command is executed, at which
932 point the @code{select} command completes.
934 Here is an example that allows the user to pick a filename from the
935 current directory, and displays the name and index of the file
941 echo you picked $fname \($REPLY\)
948 (( @var{expression} ))
951 The arithmetic @var{expression} is evaluated according to the rules
952 described below (@pxref{Shell Arithmetic}).
953 If the value of the expression is non-zero, the return status is 0;
954 otherwise the return status is 1. This is exactly equivalent to
956 let "@var{expression}"
959 @xref{Bash Builtins}, for a full description of the @code{let} builtin.
965 [[ @var{expression} ]]
968 Return a status of 0 or 1 depending on the evaluation of
969 the conditional expression @var{expression}.
970 Expressions are composed of the primaries described below in
971 @ref{Bash Conditional Expressions}.
972 Word splitting and filename expansion are not performed on the words
973 between the @samp{[[} and @samp{]]}; tilde expansion, parameter and
974 variable expansion, arithmetic expansion, command substitution, process
975 substitution, and quote removal are performed.
976 Conditional operators such as @samp{-f} must be unquoted to be recognized
979 When used with @samp{[[}, The @samp{<} and @samp{>} operators sort
980 lexicographically using the current locale.
982 When the @samp{==} and @samp{!=} operators are used, the string to the
983 right of the operator is considered a pattern and matched according
984 to the rules described below in @ref{Pattern Matching}.
985 If the shell option @code{nocasematch}
986 (see the description of @code{shopt} in @ref{The Shopt Builtin})
987 is enabled, the match is performed without regard to the case
988 of alphabetic characters.
989 The return value is 0 if the string matches (@samp{==}) or does not
990 match (@samp{!=})the pattern, and 1 otherwise.
991 Any part of the pattern may be quoted to force it to be matched as a
994 An additional binary operator, @samp{=~}, is available, with the same
995 precedence as @samp{==} and @samp{!=}.
996 When it is used, the string to the right of the operator is considered
997 an extended regular expression and matched accordingly (as in @i{regex}3)).
998 The return value is 0 if the string matches
999 the pattern, and 1 otherwise.
1000 If the regular expression is syntactically incorrect, the conditional
1001 expression's return value is 2.
1002 If the shell option @code{nocasematch}
1003 (see the description of @code{shopt} in @ref{The Shopt Builtin})
1004 is enabled, the match is performed without regard to the case
1005 of alphabetic characters.
1006 Any part of the pattern may be quoted to force it to be matched as a
1008 Substrings matched by parenthesized subexpressions within the regular
1009 expression are saved in the array variable @code{BASH_REMATCH}.
1010 The element of @code{BASH_REMATCH} with index 0 is the portion of the string
1011 matching the entire regular expression.
1012 The element of @code{BASH_REMATCH} with index @var{n} is the portion of the
1013 string matching the @var{n}th parenthesized subexpression.
1015 Expressions may be combined using the following operators, listed
1016 in decreasing order of precedence:
1019 @item ( @var{expression} )
1020 Returns the value of @var{expression}.
1021 This may be used to override the normal precedence of operators.
1023 @item ! @var{expression}
1024 True if @var{expression} is false.
1026 @item @var{expression1} && @var{expression2}
1027 True if both @var{expression1} and @var{expression2} are true.
1029 @item @var{expression1} || @var{expression2}
1030 True if either @var{expression1} or @var{expression2} is true.
1033 The @code{&&} and @code{||} operators do not evaluate @var{expression2} if the
1034 value of @var{expression1} is sufficient to determine the return
1035 value of the entire conditional expression.
1039 @node Command Grouping
1040 @subsubsection Grouping Commands
1041 @cindex commands, grouping
1043 Bash provides two ways to group a list of commands to be executed
1044 as a unit. When commands are grouped, redirections may be applied
1045 to the entire command list. For example, the output of all the
1046 commands in the list may be redirected to a single stream.
1054 Placing a list of commands between parentheses causes a subshell
1055 environment to be created (@pxref{Command Execution Environment}), and each
1056 of the commands in @var{list} to be executed in that subshell. Since the
1057 @var{list} is executed in a subshell, variable assignments do not remain in
1058 effect after the subshell completes.
1067 Placing a list of commands between curly braces causes the list to
1068 be executed in the current shell context. No subshell is created.
1069 The semicolon (or newline) following @var{list} is required.
1072 In addition to the creation of a subshell, there is a subtle difference
1073 between these two constructs due to historical reasons. The braces
1074 are @code{reserved words}, so they must be separated from the @var{list}
1075 by @code{blank}s or other shell metacharacters.
1076 The parentheses are @code{operators}, and are
1077 recognized as separate tokens by the shell even if they are not separated
1078 from the @var{list} by whitespace.
1080 The exit status of both of these constructs is the exit status of
1084 @subsection Coprocesses
1087 A @code{coprocess} is a shell command preceded by the @code{coproc}
1089 A coprocess is executed asynchronously in a subshell, as if the command
1090 had been terminated with the @samp{&} control operator, with a two-way pipe
1091 established between the executing shell and the coprocess.
1093 The format for a coprocess is:
1095 @code{coproc} [@var{NAME}] @var{command} [@var{redirections}]
1099 This creates a coprocess named @var{NAME}.
1100 If @var{NAME} is not supplied, the default name is @var{COPROC}.
1101 @var{NAME} must not be supplied if @var{command} is a simple
1102 command (@pxref{Simple Commands}); otherwise, it is interpreted as
1103 the first word of the simple command.
1105 When the coproc is executed, the shell creates an array variable
1107 named @var{NAME} in the context of the executing shell.
1108 The standard output of @var{command}
1109 is connected via a pipe to a file descriptor in the executing shell,
1110 and that file descriptor is assigned to @var{NAME}[0].
1111 The standard input of @var{command}
1112 is connected via a pipe to a file descriptor in the executing shell,
1113 and that file descriptor is assigned to @var{NAME}[1].
1114 This pipe is established before any redirections specified by the
1115 command (@pxref{Redirections}).
1116 The file descriptors can be utilized as arguments to shell commands
1117 and redirections using standard word expansions.
1119 The process id of the shell spawned to execute the coprocess is
1120 available as the value of the variable @var{NAME}_PID.
1122 builtin command may be used to wait for the coprocess to terminate.
1124 The return status of a coprocess is the exit status of @var{command}.
1126 @node Shell Functions
1127 @section Shell Functions
1128 @cindex shell function
1129 @cindex functions, shell
1131 Shell functions are a way to group commands for later execution
1132 using a single name for the group. They are executed just like
1133 a "regular" command.
1134 When the name of a shell function is used as a simple command name,
1135 the list of commands associated with that function name is executed.
1136 Shell functions are executed in the current
1137 shell context; no new process is created to interpret them.
1139 Functions are declared using this syntax:
1142 [ @code{function} ] @var{name} () @var{compound-command} [ @var{redirections} ]
1145 This defines a shell function named @var{name}. The reserved
1146 word @code{function} is optional.
1147 If the @code{function} reserved
1148 word is supplied, the parentheses are optional.
1149 The @var{body} of the function is the compound command
1150 @var{compound-command} (@pxref{Compound Commands}).
1151 That command is usually a @var{list} enclosed between @{ and @}, but
1152 may be any compound command listed above.
1153 @var{compound-command} is executed whenever @var{name} is specified as the
1155 Any redirections (@pxref{Redirections}) associated with the shell function
1156 are performed when the function is executed.
1158 A function definition may be deleted using the @option{-f} option to the
1159 @code{unset} builtin (@pxref{Bourne Shell Builtins}).
1161 The exit status of a function definition is zero unless a syntax error
1162 occurs or a readonly function with the same name already exists.
1163 When executed, the exit status of a function is the exit status of the
1164 last command executed in the body.
1166 Note that for historical reasons, in the most common usage the curly braces
1167 that surround the body of the function must be separated from the body by
1168 @code{blank}s or newlines.
1169 This is because the braces are reserved words and are only recognized
1170 as such when they are separated from the command list
1171 by whitespace or another shell metacharacter.
1172 Also, when using the braces, the @var{list} must be terminated by a semicolon,
1173 a @samp{&}, or a newline.
1175 When a function is executed, the arguments to the
1176 function become the positional parameters
1177 during its execution (@pxref{Positional Parameters}).
1178 The special parameter @samp{#} that expands to the number of
1179 positional parameters is updated to reflect the change.
1180 Special parameter @code{0} is unchanged.
1181 The first element of the @env{FUNCNAME} variable is set to the
1182 name of the function while the function is executing.
1184 All other aspects of the shell execution
1185 environment are identical between a function and its caller
1186 with these exceptions:
1187 the @env{DEBUG} and @env{RETURN} traps
1188 are not inherited unless the function has been given the
1189 @code{trace} attribute using the @code{declare} builtin or
1190 the @code{-o functrace} option has been enabled with
1191 the @code{set} builtin,
1192 (in which case all functions inherit the @env{DEBUG} and @env{RETURN} traps),
1193 and the @env{ERR} trap is not inherited unless the @code{-o errtrace}
1194 shell option has been enabled.
1195 @xref{Bourne Shell Builtins}, for the description of the
1196 @code{trap} builtin.
1198 If the builtin command @code{return}
1199 is executed in a function, the function completes and
1200 execution resumes with the next command after the function
1202 Any command associated with the @code{RETURN} trap is executed
1203 before execution resumes.
1204 When a function completes, the values of the
1205 positional parameters and the special parameter @samp{#}
1206 are restored to the values they had prior to the function's
1207 execution. If a numeric argument is given to @code{return},
1208 that is the function's return status; otherwise the function's
1209 return status is the exit status of the last command executed
1210 before the @code{return}.
1212 Variables local to the function may be declared with the
1213 @code{local} builtin. These variables are visible only to
1214 the function and the commands it invokes.
1216 Function names and definitions may be listed with the
1217 @option{-f} option to the @code{declare} or @code{typeset}
1218 builtin commands (@pxref{Bash Builtins}).
1219 The @option{-F} option to @code{declare} or @code{typeset}
1220 will list the function names only
1221 (and optionally the source file and line number, if the @code{extdebug}
1222 shell option is enabled).
1223 Functions may be exported so that subshells
1224 automatically have them defined with the
1225 @option{-f} option to the @code{export} builtin
1226 (@pxref{Bourne Shell Builtins}).
1227 Note that shell functions and variables with the same name may result
1228 in multiple identically-named entries in the environment passed to the
1230 Care should be taken in cases where this may cause a problem.
1232 Functions may be recursive. No limit is placed on the number of
1235 @node Shell Parameters
1236 @section Shell Parameters
1238 @cindex variable, shell
1239 @cindex shell variable
1242 * Positional Parameters:: The shell's command-line arguments.
1243 * Special Parameters:: Parameters denoted by special characters.
1246 A @var{parameter} is an entity that stores values.
1247 It can be a @code{name}, a number, or one of the special characters
1249 A @var{variable} is a parameter denoted by a @code{name}.
1250 A variable has a @var{value} and zero or more @var{attributes}.
1251 Attributes are assigned using the @code{declare} builtin command
1252 (see the description of the @code{declare} builtin in @ref{Bash Builtins}).
1254 A parameter is set if it has been assigned a value. The null string is
1255 a valid value. Once a variable is set, it may be unset only by using
1256 the @code{unset} builtin command.
1258 A variable may be assigned to by a statement of the form
1260 @var{name}=[@var{value}]
1264 is not given, the variable is assigned the null string. All
1265 @var{value}s undergo tilde expansion, parameter and variable expansion,
1266 command substitution, arithmetic expansion, and quote
1267 removal (detailed below). If the variable has its @code{integer}
1268 attribute set, then @var{value}
1269 is evaluated as an arithmetic expression even if the @code{$((@dots{}))}
1270 expansion is not used (@pxref{Arithmetic Expansion}).
1271 Word splitting is not performed, with the exception
1272 of @code{"$@@"} as explained below.
1273 Filename expansion is not performed.
1274 Assignment statements may also appear as arguments to the
1276 @code{declare}, @code{typeset}, @code{export}, @code{readonly},
1277 and @code{local} builtin commands.
1279 In the context where an assignment statement is assigning a value
1280 to a shell variable or array index (@pxref{Arrays}), the @samp{+=}
1281 operator can be used to
1282 append to or add to the variable's previous value.
1283 When @samp{+=} is applied to a variable for which the integer attribute
1284 has been set, @var{value} is evaluated as an arithmetic expression and
1285 added to the variable's current value, which is also evaluated.
1286 When @samp{+=} is applied to an array variable using compound assignment
1287 (@pxref{Arrays}), the
1288 variable's value is not unset (as it is when using @samp{=}), and new
1289 values are appended to the array beginning at one greater than the array's
1290 maximum index (for indexed arrays), or added as additional key-value pairs
1291 in an associative array.
1292 When applied to a string-valued variable, @var{value} is expanded and
1293 appended to the variable's value.
1295 @node Positional Parameters
1296 @subsection Positional Parameters
1297 @cindex parameters, positional
1299 A @var{positional parameter} is a parameter denoted by one or more
1300 digits, other than the single digit @code{0}. Positional parameters are
1301 assigned from the shell's arguments when it is invoked,
1302 and may be reassigned using the @code{set} builtin command.
1303 Positional parameter @code{N} may be referenced as @code{$@{N@}}, or
1304 as @code{$N} when @code{N} consists of a single digit.
1305 Positional parameters may not be assigned to with assignment statements.
1306 The @code{set} and @code{shift} builtins are used to set and
1307 unset them (@pxref{Shell Builtin Commands}).
1308 The positional parameters are
1309 temporarily replaced when a shell function is executed
1310 (@pxref{Shell Functions}).
1312 When a positional parameter consisting of more than a single
1313 digit is expanded, it must be enclosed in braces.
1315 @node Special Parameters
1316 @subsection Special Parameters
1317 @cindex parameters, special
1319 The shell treats several parameters specially. These parameters may
1320 only be referenced; assignment to them is not allowed.
1325 Expands to the positional parameters, starting from one. When the
1326 expansion occurs within double quotes, it expands to a single word
1327 with the value of each parameter separated by the first character
1329 special variable. That is, @code{"$*"} is equivalent
1330 to @code{"$1@var{c}$2@var{c}@dots{}"}, where @var{c}
1331 is the first character of the value of the @code{IFS}
1333 If @env{IFS} is unset, the parameters are separated by spaces.
1334 If @env{IFS} is null, the parameters are joined without intervening
1339 Expands to the positional parameters, starting from one. When the
1340 expansion occurs within double quotes, each parameter expands to a
1341 separate word. That is, @code{"$@@"} is equivalent to
1342 @code{"$1" "$2" @dots{}}.
1343 If the double-quoted expansion occurs within a word, the expansion of
1344 the first parameter is joined with the beginning part of the original
1345 word, and the expansion of the last parameter is joined with the last
1346 part of the original word.
1347 When there are no positional parameters, @code{"$@@"} and
1349 expand to nothing (i.e., they are removed).
1352 Expands to the number of positional parameters in decimal.
1355 Expands to the exit status of the most recently executed foreground
1359 (A hyphen.) Expands to the current option flags as specified upon
1360 invocation, by the @code{set}
1361 builtin command, or those set by the shell itself
1362 (such as the @option{-i} option).
1365 Expands to the process @sc{id} of the shell. In a @code{()} subshell, it
1366 expands to the process @sc{id} of the invoking shell, not the subshell.
1369 Expands to the process @sc{id} of the most recently executed background
1370 (asynchronous) command.
1373 Expands to the name of the shell or shell script. This is set at
1374 shell initialization. If Bash is invoked with a file of commands
1375 (@pxref{Shell Scripts}), @code{$0} is set to the name of that file.
1376 If Bash is started with the @option{-c} option (@pxref{Invoking Bash}),
1377 then @code{$0} is set to the first argument after the string to be
1378 executed, if one is present. Otherwise, it is set
1379 to the filename used to invoke Bash, as given by argument zero.
1383 At shell startup, set to the absolute pathname used to invoke the
1384 shell or shell script being executed as passed in the environment
1386 Subsequently, expands to the last argument to the previous command,
1388 Also set to the full pathname used to invoke each command executed
1389 and placed in the environment exported to that command.
1390 When checking mail, this parameter holds the name of the mail file.
1393 @node Shell Expansions
1394 @section Shell Expansions
1397 Expansion is performed on the command line after it has been split into
1398 @code{token}s. There are seven kinds of expansion performed:
1400 @item brace expansion
1401 @item tilde expansion
1402 @item parameter and variable expansion
1403 @item command substitution
1404 @item arithmetic expansion
1405 @item word splitting
1406 @item filename expansion
1410 * Brace Expansion:: Expansion of expressions within braces.
1411 * Tilde Expansion:: Expansion of the ~ character.
1412 * Shell Parameter Expansion:: How Bash expands variables to their values.
1413 * Command Substitution:: Using the output of a command as an argument.
1414 * Arithmetic Expansion:: How to use arithmetic in shell expansions.
1415 * Process Substitution:: A way to write and read to and from a
1417 * Word Splitting:: How the results of expansion are split into separate
1419 * Filename Expansion:: A shorthand for specifying filenames matching patterns.
1420 * Quote Removal:: How and when quote characters are removed from
1424 The order of expansions is: brace expansion, tilde expansion,
1425 parameter, variable, and arithmetic expansion and
1426 command substitution
1427 (done in a left-to-right fashion), word splitting, and filename
1430 On systems that can support it, there is an additional expansion
1431 available: @var{process substitution}. This is performed at the
1432 same time as parameter, variable, and arithmetic expansion and
1433 command substitution.
1435 Only brace expansion, word splitting, and filename expansion
1436 can change the number of words of the expansion; other expansions
1437 expand a single word to a single word.
1438 The only exceptions to this are the expansions of
1439 @code{"$@@"} (@pxref{Special Parameters}) and @code{"$@{@var{name}[@@]@}"}
1442 After all expansions, @code{quote removal} (@pxref{Quote Removal})
1445 @node Brace Expansion
1446 @subsection Brace Expansion
1447 @cindex brace expansion
1448 @cindex expansion, brace
1450 Brace expansion is a mechanism by which arbitrary strings may be generated.
1451 This mechanism is similar to
1452 @var{filename expansion} (@pxref{Filename Expansion}),
1453 but the file names generated need not exist.
1454 Patterns to be brace expanded take the form of an optional @var{preamble},
1455 followed by either a series of comma-separated strings or a seqeunce expression
1456 between a pair of braces,
1457 followed by an optional @var{postscript}.
1458 The preamble is prefixed to each string contained within the braces, and
1459 the postscript is then appended to each resulting string, expanding left
1462 Brace expansions may be nested.
1463 The results of each expanded string are not sorted; left to right order
1467 bash$ echo a@{d,c,b@}e
1471 A sequence expression takes the form @code{@{@var{x}..@var{y}[..@var{incr}]@}},
1472 where @var{x} and @var{y} are either integers or single characters,
1473 and @var{incr}, an optional increment, is an integer.
1474 When integers are supplied, the expression expands to each number between
1475 @var{x} and @var{y}, inclusive.
1476 Supplied integers may be prefixed with @samp{0} to force each term to have the
1477 same width. When either @var{x} or @var{y} begins with a zero, the shell
1478 attempts to force all generated terms to contain the same number of digits,
1479 zero-padding where necessary.
1480 When characters are supplied, the expression expands to each character
1481 lexicographically between @var{x} and @var{y}, inclusive. Note that
1482 both @var{x} and @var{y} must be of the same type.
1483 When the increment is supplied, it is used as the difference between
1484 each term. The default increment is 1 or -1 as appropriate.
1486 Brace expansion is performed before any other expansions,
1487 and any characters special to other expansions are preserved
1488 in the result. It is strictly textual. Bash
1489 does not apply any syntactic interpretation to the context of the
1490 expansion or the text between the braces.
1491 To avoid conflicts with parameter expansion, the string @samp{$@{}
1492 is not considered eligible for brace expansion.
1494 A correctly-formed brace expansion must contain unquoted opening
1495 and closing braces, and at least one unquoted comma or a valid
1496 sequence expression.
1497 Any incorrectly formed brace expansion is left unchanged.
1499 A @{ or @samp{,} may be quoted with a backslash to prevent its
1500 being considered part of a brace expression.
1501 To avoid conflicts with parameter expansion, the string @samp{$@{}
1502 is not considered eligible for brace expansion.
1504 This construct is typically used as shorthand when the common
1505 prefix of the strings to be generated is longer than in the
1508 mkdir /usr/local/src/bash/@{old,new,dist,bugs@}
1512 chown root /usr/@{ucb/@{ex,edit@},lib/@{ex?.?*,how_ex@}@}
1515 @node Tilde Expansion
1516 @subsection Tilde Expansion
1517 @cindex tilde expansion
1518 @cindex expansion, tilde
1520 If a word begins with an unquoted tilde character (@samp{~}), all of the
1521 characters up to the first unquoted slash (or all characters,
1522 if there is no unquoted slash) are considered a @var{tilde-prefix}.
1523 If none of the characters in the tilde-prefix are quoted, the
1524 characters in the tilde-prefix following the tilde are treated as a
1525 possible @var{login name}.
1526 If this login name is the null string, the tilde is replaced with the
1527 value of the @env{HOME} shell variable.
1528 If @env{HOME} is unset, the home directory of the user executing the
1529 shell is substituted instead.
1530 Otherwise, the tilde-prefix is replaced with the home directory
1531 associated with the specified login name.
1533 If the tilde-prefix is @samp{~+}, the value of
1534 the shell variable @env{PWD} replaces the tilde-prefix.
1535 If the tilde-prefix is @samp{~-}, the value of the shell variable
1536 @env{OLDPWD}, if it is set, is substituted.
1538 If the characters following the tilde in the tilde-prefix consist of a
1539 number @var{N}, optionally prefixed by a @samp{+} or a @samp{-},
1540 the tilde-prefix is replaced with the
1541 corresponding element from the directory stack, as it would be displayed
1542 by the @code{dirs} builtin invoked with the characters following tilde
1543 in the tilde-prefix as an argument (@pxref{The Directory Stack}).
1544 If the tilde-prefix, sans the tilde, consists of a number without a
1545 leading @samp{+} or @samp{-}, @samp{+} is assumed.
1547 If the login name is invalid, or the tilde expansion fails, the word is
1550 Each variable assignment is checked for unquoted tilde-prefixes immediately
1551 following a @samp{:} or the first @samp{=}.
1552 In these cases, tilde expansion is also performed.
1553 Consequently, one may use file names with tildes in assignments to
1554 @env{PATH}, @env{MAILPATH}, and @env{CDPATH},
1555 and the shell assigns the expanded value.
1557 The following table shows how Bash treats unquoted tilde-prefixes:
1561 The value of @code{$HOME}
1566 The subdirectory @code{foo} of the home directory of the user
1573 @file{$@{OLDPWD-'~-'@}/foo}
1576 The string that would be displayed by @samp{dirs +@var{N}}
1579 The string that would be displayed by @samp{dirs +@var{N}}
1582 The string that would be displayed by @samp{dirs -@var{N}}
1586 @node Shell Parameter Expansion
1587 @subsection Shell Parameter Expansion
1588 @cindex parameter expansion
1589 @cindex expansion, parameter
1591 The @samp{$} character introduces parameter expansion,
1592 command substitution, or arithmetic expansion. The parameter name
1593 or symbol to be expanded may be enclosed in braces, which
1594 are optional but serve to protect the variable to be expanded from
1595 characters immediately following it which could be
1596 interpreted as part of the name.
1598 When braces are used, the matching ending brace is the first @samp{@}}
1599 not escaped by a backslash or within a quoted string, and not within an
1600 embedded arithmetic expansion, command substitution, or parameter
1603 The basic form of parameter expansion is $@{@var{parameter}@}.
1604 The value of @var{parameter} is substituted. The braces are required
1605 when @var{parameter}
1606 is a positional parameter with more than one digit,
1607 or when @var{parameter}
1608 is followed by a character that is not to be
1609 interpreted as part of its name.
1611 If the first character of @var{parameter} is an exclamation point (!),
1612 a level of variable indirection is introduced.
1613 Bash uses the value of the variable formed from the rest of
1614 @var{parameter} as the name of the variable; this variable is then
1615 expanded and that value is used in the rest of the substitution, rather
1616 than the value of @var{parameter} itself.
1617 This is known as @code{indirect expansion}.
1618 The exceptions to this are the expansions of $@{!@var{prefix*}@}
1619 and $@{!@var{name}[@@]@}
1621 The exclamation point must immediately follow the left brace in order to
1622 introduce indirection.
1624 In each of the cases below, @var{word} is subject to tilde expansion,
1625 parameter expansion, command substitution, and arithmetic expansion.
1627 When not performing substring expansion, using the form described
1628 below, Bash tests for a parameter that is unset or null.
1629 Omitting the colon results in a test only for a parameter that is unset.
1630 Put another way, if the colon is included,
1631 the operator tests for both @var{parameter}'s existence and that its value
1632 is not null; if the colon is omitted, the operator tests only for existence.
1636 @item $@{@var{parameter}:@minus{}@var{word}@}
1637 If @var{parameter} is unset or null, the expansion of
1638 @var{word} is substituted. Otherwise, the value of
1639 @var{parameter} is substituted.
1641 @item $@{@var{parameter}:=@var{word}@}
1643 is unset or null, the expansion of @var{word}
1644 is assigned to @var{parameter}.
1645 The value of @var{parameter} is then substituted.
1646 Positional parameters and special parameters may not be assigned to
1649 @item $@{@var{parameter}:?@var{word}@}
1651 is null or unset, the expansion of @var{word} (or a message
1652 to that effect if @var{word}
1653 is not present) is written to the standard error and the shell, if it
1654 is not interactive, exits. Otherwise, the value of @var{parameter} is
1657 @item $@{@var{parameter}:+@var{word}@}
1659 is null or unset, nothing is substituted, otherwise the expansion of
1660 @var{word} is substituted.
1662 @item $@{@var{parameter}:@var{offset}@}
1663 @itemx $@{@var{parameter}:@var{offset}:@var{length}@}
1664 Expands to up to @var{length} characters of @var{parameter}
1665 starting at the character specified by @var{offset}.
1666 If @var{length} is omitted, expands to the substring of
1667 @var{parameter} starting at the character specified by @var{offset}.
1668 @var{length} and @var{offset} are arithmetic expressions
1669 (@pxref{Shell Arithmetic}).
1670 This is referred to as Substring Expansion.
1672 @var{length} must evaluate to a number greater than or equal to zero.
1673 If @var{offset} evaluates to a number less than zero, the value
1674 is used as an offset from the end of the value of @var{parameter}.
1675 If @var{parameter} is @samp{@@}, the result is @var{length} positional
1676 parameters beginning at @var{offset}.
1677 If @var{parameter} is an indexed array name subscripted
1678 by @samp{@@} or @samp{*}, the result is the @var{length}
1679 members of the array beginning with @code{$@{@var{parameter}[@var{offset}]@}}.
1680 A negative @var{offset} is taken relative to one greater than the maximum
1681 index of the specified array.
1682 Substring expansion applied to an associative array produces undefined
1685 Note that a negative offset must be separated from the colon by at least
1686 one space to avoid being confused with the @samp{:-} expansion.
1687 Substring indexing is zero-based unless the positional parameters
1688 are used, in which case the indexing starts at 1 by default.
1689 If @var{offset} is 0, and the positional parameters are used, @code{$@@} is
1690 prefixed to the list.
1692 @item $@{!@var{prefix}*@}
1693 @itemx $@{!@var{prefix}@@@}
1694 Expands to the names of variables whose names begin with @var{prefix},
1695 separated by the first character of the @env{IFS} special variable.
1696 When @samp{@@} is used and the expansion appears within double quotes, each
1697 variable name expands to a separate word.
1699 @item $@{!@var{name}[@@]@}
1700 @itemx $@{!@var{name}[*]@}
1701 If @var{name} is an array variable, expands to the list of array indices
1702 (keys) assigned in @var{name}.
1703 If @var{name} is not an array, expands to 0 if @var{name} is set and null
1705 When @samp{@@} is used and the expansion appears within double quotes, each
1706 key expands to a separate word.
1708 @item $@{#@var{parameter}@}
1709 The length in characters of the expanded value of @var{parameter} is
1711 If @var{parameter} is @samp{*} or @samp{@@}, the value substituted
1712 is the number of positional parameters.
1713 If @var{parameter} is an array name subscripted by @samp{*} or @samp{@@},
1714 the value substituted is the number of elements in the array.
1716 @item $@{@var{parameter}#@var{word}@}
1717 @itemx $@{@var{parameter}##@var{word}@}
1719 is expanded to produce a pattern just as in filename
1720 expansion (@pxref{Filename Expansion}). If the pattern matches
1721 the beginning of the expanded value of @var{parameter},
1722 then the result of the expansion is the expanded value of @var{parameter}
1723 with the shortest matching pattern (the @samp{#} case) or the
1724 longest matching pattern (the @samp{##} case) deleted.
1725 If @var{parameter} is @samp{@@} or @samp{*},
1726 the pattern removal operation is applied to each positional
1727 parameter in turn, and the expansion is the resultant list.
1728 If @var{parameter} is an array variable subscripted with
1729 @samp{@@} or @samp{*},
1730 the pattern removal operation is applied to each member of the
1731 array in turn, and the expansion is the resultant list.
1733 @item $@{@var{parameter}%@var{word}@}
1734 @itemx $@{@var{parameter}%%@var{word}@}
1735 The @var{word} is expanded to produce a pattern just as in
1737 If the pattern matches a trailing portion of the expanded value of
1738 @var{parameter}, then the result of the expansion is the value of
1739 @var{parameter} with the shortest matching pattern (the @samp{%} case)
1740 or the longest matching pattern (the @samp{%%} case) deleted.
1741 If @var{parameter} is @samp{@@} or @samp{*},
1742 the pattern removal operation is applied to each positional
1743 parameter in turn, and the expansion is the resultant list.
1745 is an array variable subscripted with @samp{@@} or @samp{*},
1746 the pattern removal operation is applied to each member of the
1747 array in turn, and the expansion is the resultant list.
1749 @item $@{@var{parameter}/@var{pattern}/@var{string}@}
1751 The @var{pattern} is expanded to produce a pattern just as in
1753 @var{Parameter} is expanded and the longest match of @var{pattern}
1754 against its value is replaced with @var{string}.
1755 If @var{pattern} begins with @samp{/}, all matches of @var{pattern} are
1756 replaced with @var{string}. Normally only the first match is replaced.
1757 If @var{pattern} begins with @samp{#}, it must match at the beginning
1758 of the expanded value of @var{parameter}.
1759 If @var{pattern} begins with @samp{%}, it must match at the end
1760 of the expanded value of @var{parameter}.
1761 If @var{string} is null, matches of @var{pattern} are deleted
1762 and the @code{/} following @var{pattern} may be omitted.
1763 If @var{parameter} is @samp{@@} or @samp{*},
1764 the substitution operation is applied to each positional
1765 parameter in turn, and the expansion is the resultant list.
1767 is an array variable subscripted with @samp{@@} or @samp{*},
1768 the substitution operation is applied to each member of the
1769 array in turn, and the expansion is the resultant list.
1771 @item $@{@var{parameter}^@var{pattern}@}
1772 @itemx $@{@var{parameter}^^@var{pattern}@}
1773 @itemx $@{@var{parameter},@var{pattern}@}
1774 @itemx $@{@var{parameter},,@var{pattern}@}
1775 This expansion modifies the case of alphabetic characters in @var{parameter}.
1776 The @var{pattern} is expanded to produce a pattern just as in
1778 The @samp{^} operator converts lowercase letters matching @var{pattern}
1779 to uppercase; the @samp{,} operator converts matching uppercase letters
1781 The @samp{^^} and @samp{,,} expansions convert each matched character in the
1782 expanded value; the @samp{^} and @samp{,} expansions match and convert only
1783 the first character in the expanded value.
1784 If @var{pattern} is omitted, it is treated like a @samp{?}, which matches
1786 If @var{parameter} is @samp{@@} or @samp{*},
1787 the case modification operation is applied to each positional
1788 parameter in turn, and the expansion is the resultant list.
1790 is an array variable subscripted with @samp{@@} or @samp{*},
1791 the case modification operation is applied to each member of the
1792 array in turn, and the expansion is the resultant list.
1796 @node Command Substitution
1797 @subsection Command Substitution
1798 @cindex command substitution
1800 Command substitution allows the output of a command to replace
1802 Command substitution occurs when a command is enclosed as follows:
1813 Bash performs the expansion by executing @var{command} and
1814 replacing the command substitution with the standard output of the
1815 command, with any trailing newlines deleted.
1816 Embedded newlines are not deleted, but they may be removed during
1818 The command substitution @code{$(cat @var{file})} can be
1819 replaced by the equivalent but faster @code{$(< @var{file})}.
1821 When the old-style backquote form of substitution is used,
1822 backslash retains its literal meaning except when followed by
1823 @samp{$}, @samp{`}, or @samp{\}.
1824 The first backquote not preceded by a backslash terminates the
1825 command substitution.
1826 When using the @code{$(@var{command})} form, all characters between
1827 the parentheses make up the command; none are treated specially.
1829 Command substitutions may be nested. To nest when using the backquoted
1830 form, escape the inner backquotes with backslashes.
1832 If the substitution appears within double quotes, word splitting and
1833 filename expansion are not performed on the results.
1835 @node Arithmetic Expansion
1836 @subsection Arithmetic Expansion
1837 @cindex expansion, arithmetic
1838 @cindex arithmetic expansion
1840 Arithmetic expansion allows the evaluation of an arithmetic expression
1841 and the substitution of the result. The format for arithmetic expansion is:
1844 $(( @var{expression} ))
1847 The expression is treated as if it were within double quotes, but
1848 a double quote inside the parentheses is not treated specially.
1849 All tokens in the expression undergo parameter expansion, command
1850 substitution, and quote removal.
1851 Arithmetic expansions may be nested.
1853 The evaluation is performed according to the rules listed below
1854 (@pxref{Shell Arithmetic}).
1855 If the expression is invalid, Bash prints a message indicating
1856 failure to the standard error and no substitution occurs.
1858 @node Process Substitution
1859 @subsection Process Substitution
1860 @cindex process substitution
1862 Process substitution is supported on systems that support named
1863 pipes (@sc{fifo}s) or the @file{/dev/fd} method of naming open files.
1864 It takes the form of
1874 The process @var{list} is run with its input or output connected to a
1875 @sc{fifo} or some file in @file{/dev/fd}. The name of this file is
1876 passed as an argument to the current command as the result of the
1877 expansion. If the @code{>(@var{list})} form is used, writing to
1878 the file will provide input for @var{list}. If the
1879 @code{<(@var{list})} form is used, the file passed as an
1880 argument should be read to obtain the output of @var{list}.
1881 Note that no space may appear between the @code{<} or @code{>}
1882 and the left parenthesis, otherwise the construct would be interpreted
1885 When available, process substitution is performed simultaneously with
1886 parameter and variable expansion, command substitution, and arithmetic
1889 @node Word Splitting
1890 @subsection Word Splitting
1891 @cindex word splitting
1893 The shell scans the results of parameter expansion, command substitution,
1894 and arithmetic expansion that did not occur within double quotes for
1897 The shell treats each character of @env{$IFS} as a delimiter, and splits
1898 the results of the other expansions into words on these characters.
1899 If @env{IFS} is unset, or its value is exactly @code{<space><tab><newline>},
1900 the default, then sequences of
1901 @code{ <space>}, @code{<tab>}, and @code{<newline>}
1902 at the beginning and end of the results of the previous
1903 expansions are ignored, and any sequence of @env{IFS}
1904 characters not at the beginning or end serves to delimit words.
1905 If @env{IFS} has a value other than the default, then sequences of
1906 the whitespace characters @code{space} and @code{tab}
1907 are ignored at the beginning and end of the
1908 word, as long as the whitespace character is in the
1909 value of @env{IFS} (an @env{IFS} whitespace character).
1910 Any character in @env{IFS} that is not @env{IFS}
1911 whitespace, along with any adjacent @env{IFS}
1912 whitespace characters, delimits a field. A sequence of @env{IFS}
1913 whitespace characters is also treated as a delimiter.
1914 If the value of @env{IFS} is null, no word splitting occurs.
1916 Explicit null arguments (@code{""} or @code{''}) are retained.
1917 Unquoted implicit null arguments, resulting from the expansion of
1918 parameters that have no values, are removed.
1919 If a parameter with no value is expanded within double quotes, a
1920 null argument results and is retained.
1922 Note that if no expansion occurs, no splitting
1925 @node Filename Expansion
1926 @subsection Filename Expansion
1928 * Pattern Matching:: How the shell matches patterns.
1930 @cindex expansion, filename
1931 @cindex expansion, pathname
1932 @cindex filename expansion
1933 @cindex pathname expansion
1935 After word splitting, unless the @option{-f} option has been set
1936 (@pxref{The Set Builtin}), Bash scans each word for the characters
1937 @samp{*}, @samp{?}, and @samp{[}.
1938 If one of these characters appears, then the word is
1939 regarded as a @var{pattern},
1940 and replaced with an alphabetically sorted list of
1941 file names matching the pattern. If no matching file names are found,
1942 and the shell option @code{nullglob} is disabled, the word is left
1944 If the @code{nullglob} option is set, and no matches are found, the word
1946 If the @code{failglob} shell option is set, and no matches are found,
1947 an error message is printed and the command is not executed.
1948 If the shell option @code{nocaseglob} is enabled, the match is performed
1949 without regard to the case of alphabetic characters.
1951 When a pattern is used for filename expansion, the character @samp{.}
1952 at the start of a filename or immediately following a slash
1953 must be matched explicitly, unless the shell option @code{dotglob} is set.
1954 When matching a file name, the slash character must always be
1956 In other cases, the @samp{.} character is not treated specially.
1958 See the description of @code{shopt} in @ref{The Shopt Builtin},
1959 for a description of the @code{nocaseglob}, @code{nullglob},
1960 @code{failglob}, and @code{dotglob} options.
1962 The @env{GLOBIGNORE}
1963 shell variable may be used to restrict the set of filenames matching a
1964 pattern. If @env{GLOBIGNORE}
1965 is set, each matching filename that also matches one of the patterns in
1966 @env{GLOBIGNORE} is removed from the list of matches. The filenames
1967 @file{.} and @file{..}
1968 are always ignored when @env{GLOBIGNORE}
1969 is set and not null.
1970 However, setting @env{GLOBIGNORE} to a non-null value has the effect of
1971 enabling the @code{dotglob}
1972 shell option, so all other filenames beginning with a
1973 @samp{.} will match.
1974 To get the old behavior of ignoring filenames beginning with a
1975 @samp{.}, make @samp{.*} one of the patterns in @env{GLOBIGNORE}.
1976 The @code{dotglob} option is disabled when @env{GLOBIGNORE}
1979 @node Pattern Matching
1980 @subsubsection Pattern Matching
1981 @cindex pattern matching
1982 @cindex matching, pattern
1984 Any character that appears in a pattern, other than the special pattern
1985 characters described below, matches itself.
1986 The @sc{nul} character may not occur in a pattern.
1987 A backslash escapes the following character; the
1988 escaping backslash is discarded when matching.
1989 The special pattern characters must be quoted if they are to be matched
1992 The special pattern characters have the following meanings:
1995 Matches any string, including the null string.
1996 When the @code{globstar} shell option is enabled, and @samp{*} is used in
1997 a filename expansion context, two adjacent @samp{*}s used as a single
1998 pattern will match all files and zero or more directories and
2000 If followed by a @samp{/}, two adjacent @samp{*}s will match only
2001 directories and subdirectories.
2003 Matches any single character.
2005 Matches any one of the enclosed characters. A pair of characters
2006 separated by a hyphen denotes a @var{range expression};
2007 any character that sorts between those two characters, inclusive,
2008 using the current locale's collating sequence and character set,
2009 is matched. If the first character following the
2010 @samp{[} is a @samp{!} or a @samp{^}
2011 then any character not enclosed is matched. A @samp{@minus{}}
2012 may be matched by including it as the first or last character
2013 in the set. A @samp{]} may be matched by including it as the first
2014 character in the set.
2015 The sorting order of characters in range expressions is determined by
2016 the current locale and the value of the @env{LC_COLLATE} shell variable,
2019 For example, in the default C locale, @samp{[a-dx-z]} is equivalent to
2020 @samp{[abcdxyz]}. Many locales sort characters in dictionary order, and in
2021 these locales @samp{[a-dx-z]} is typically not equivalent to @samp{[abcdxyz]};
2022 it might be equivalent to @samp{[aBbCcDdxXyYz]}, for example. To obtain
2023 the traditional interpretation of ranges in bracket expressions, you can
2024 force the use of the C locale by setting the @env{LC_COLLATE} or
2025 @env{LC_ALL} environment variable to the value @samp{C}.
2027 Within @samp{[} and @samp{]}, @var{character classes} can be specified
2029 @code{[:}@var{class}@code{:]}, where @var{class} is one of the
2030 following classes defined in the @sc{posix} standard:
2032 alnum alpha ascii blank cntrl digit graph lower
2033 print punct space upper word xdigit
2036 A character class matches any character belonging to that class.
2037 The @code{word} character class matches letters, digits, and the character
2040 Within @samp{[} and @samp{]}, an @var{equivalence class} can be
2041 specified using the syntax @code{[=}@var{c}@code{=]}, which
2042 matches all characters with the same collation weight (as defined
2043 by the current locale) as the character @var{c}.
2045 Within @samp{[} and @samp{]}, the syntax @code{[.}@var{symbol}@code{.]}
2046 matches the collating symbol @var{symbol}.
2049 If the @code{extglob} shell option is enabled using the @code{shopt}
2050 builtin, several extended pattern matching operators are recognized.
2051 In the following description, a @var{pattern-list} is a list of one
2052 or more patterns separated by a @samp{|}.
2053 Composite patterns may be formed using one or more of the following
2057 @item ?(@var{pattern-list})
2058 Matches zero or one occurrence of the given patterns.
2060 @item *(@var{pattern-list})
2061 Matches zero or more occurrences of the given patterns.
2063 @item +(@var{pattern-list})
2064 Matches one or more occurrences of the given patterns.
2066 @item @@(@var{pattern-list})
2067 Matches one of the given patterns.
2069 @item !(@var{pattern-list})
2070 Matches anything except one of the given patterns.
2074 @subsection Quote Removal
2076 After the preceding expansions, all unquoted occurrences of the
2077 characters @samp{\}, @samp{'}, and @samp{"} that did not
2078 result from one of the above expansions are removed.
2081 @section Redirections
2084 Before a command is executed, its input and output
2085 may be @var{redirected}
2086 using a special notation interpreted by the shell.
2087 Redirection may also be used to open and close files for the
2088 current shell execution environment. The following redirection
2089 operators may precede or appear anywhere within a
2090 simple command or may follow a command.
2091 Redirections are processed in the order they appear, from
2094 Each redirection that may be preceded by a file descriptor number
2095 may instead be preceded by a word of the form @{@var{varname}@}.
2096 In this case, for each redirection operator except
2097 >&- and <&-, the shell will allocate a file descriptor greater
2098 than 10 and assign it to @{@var{varname}@}. If >&- or <&- is preceded
2099 by @{@var{varname}@}, the value of @var{varname} defines the file
2100 descriptor to close.
2102 In the following descriptions, if the file descriptor number is
2103 omitted, and the first character of the redirection operator is
2104 @samp{<}, the redirection refers to the standard input (file
2105 descriptor 0). If the first character of the redirection operator
2106 is @samp{>}, the redirection refers to the standard output (file
2109 The word following the redirection operator in the following
2110 descriptions, unless otherwise noted, is subjected to brace expansion,
2111 tilde expansion, parameter expansion, command substitution, arithmetic
2112 expansion, quote removal, filename expansion, and word splitting.
2113 If it expands to more than one word, Bash reports an error.
2115 Note that the order of redirections is significant. For example,
2118 ls > @var{dirlist} 2>&1
2121 directs both standard output (file descriptor 1) and standard error
2122 (file descriptor 2) to the file @var{dirlist}, while the command
2124 ls 2>&1 > @var{dirlist}
2127 directs only the standard output to file @var{dirlist},
2128 because the standard error was made a copy of the standard output
2129 before the standard output was redirected to @var{dirlist}.
2131 Bash handles several filenames specially when they are used in
2132 redirections, as described in the following table:
2135 @item /dev/fd/@var{fd}
2136 If @var{fd} is a valid integer, file descriptor @var{fd} is duplicated.
2139 File descriptor 0 is duplicated.
2142 File descriptor 1 is duplicated.
2145 File descriptor 2 is duplicated.
2147 @item /dev/tcp/@var{host}/@var{port}
2148 If @var{host} is a valid hostname or Internet address, and @var{port}
2149 is an integer port number or service name, Bash attempts to open a TCP
2150 connection to the corresponding socket.
2152 @item /dev/udp/@var{host}/@var{port}
2153 If @var{host} is a valid hostname or Internet address, and @var{port}
2154 is an integer port number or service name, Bash attempts to open a UDP
2155 connection to the corresponding socket.
2159 A failure to open or create a file causes the redirection to fail.
2161 Redirections using file descriptors greater than 9 should be used with
2162 care, as they may conflict with file descriptors the shell uses
2165 @subsection Redirecting Input
2166 Redirection of input causes the file whose name results from
2167 the expansion of @var{word}
2168 to be opened for reading on file descriptor @code{n},
2169 or the standard input (file descriptor 0) if @code{n}
2172 The general format for redirecting input is:
2174 [@var{n}]<@var{word}
2177 @subsection Redirecting Output
2178 Redirection of output causes the file whose name results from
2179 the expansion of @var{word}
2180 to be opened for writing on file descriptor @var{n},
2181 or the standard output (file descriptor 1) if @var{n}
2182 is not specified. If the file does not exist it is created;
2183 if it does exist it is truncated to zero size.
2185 The general format for redirecting output is:
2187 [@var{n}]>[|]@var{word}
2190 If the redirection operator is @samp{>}, and the @code{noclobber}
2191 option to the @code{set} builtin has been enabled, the redirection
2192 will fail if the file whose name results from the expansion of
2193 @var{word} exists and is a regular file.
2194 If the redirection operator is @samp{>|}, or the redirection operator is
2195 @samp{>} and the @code{noclobber} option is not enabled, the redirection
2196 is attempted even if the file named by @var{word} exists.
2198 @subsection Appending Redirected Output
2199 Redirection of output in this fashion
2200 causes the file whose name results from
2201 the expansion of @var{word}
2202 to be opened for appending on file descriptor @var{n},
2203 or the standard output (file descriptor 1) if @var{n}
2204 is not specified. If the file does not exist it is created.
2206 The general format for appending output is:
2208 [@var{n}]>>@var{word}
2211 @subsection Redirecting Standard Output and Standard Error
2212 This construct allows both the
2213 standard output (file descriptor 1) and
2214 the standard error output (file descriptor 2)
2215 to be redirected to the file whose name is the
2216 expansion of @var{word}.
2218 There are two formats for redirecting standard output and
2229 Of the two forms, the first is preferred.
2230 This is semantically equivalent to
2235 @subsection Appending Standard Output and Standard Error
2236 This construct allows both the
2237 standard output (file descriptor 1) and
2238 the standard error output (file descriptor 2)
2239 to be appended to the file whose name is the
2240 expansion of @var{word}.
2242 The format for appending standard output and standard error is:
2247 This is semantically equivalent to
2252 @subsection Here Documents
2253 This type of redirection instructs the shell to read input from the
2254 current source until a line containing only @var{word}
2255 (with no trailing blanks) is seen. All of
2256 the lines read up to that point are then used as the standard
2257 input for a command.
2259 The format of here-documents is:
2261 <<[@minus{}]@var{word}
2266 No parameter expansion, command substitution, arithmetic expansion,
2267 or filename expansion is performed on
2268 @var{word}. If any characters in @var{word} are quoted, the
2269 @var{delimiter} is the result of quote removal on @var{word},
2270 and the lines in the here-document are not expanded.
2271 If @var{word} is unquoted,
2272 all lines of the here-document are subjected to parameter expansion,
2273 command substitution, and arithmetic expansion. In the latter
2274 case, the character sequence @code{\newline} is ignored, and @samp{\}
2275 must be used to quote the characters
2276 @samp{\}, @samp{$}, and @samp{`}.
2278 If the redirection operator is @samp{<<-},
2279 then all leading tab characters are stripped from input lines and the
2280 line containing @var{delimiter}.
2281 This allows here-documents within shell scripts to be indented in a
2284 @subsection Here Strings
2285 A variant of here documents, the format is:
2290 The @var{word} is expanded and supplied to the command on its standard
2293 @subsection Duplicating File Descriptors
2294 The redirection operator
2296 [@var{n}]<&@var{word}
2299 is used to duplicate input file descriptors.
2301 expands to one or more digits, the file descriptor denoted by @var{n}
2302 is made to be a copy of that file descriptor.
2303 If the digits in @var{word} do not specify a file descriptor open for
2304 input, a redirection error occurs.
2306 evaluates to @samp{-}, file descriptor @var{n} is closed. If
2307 @var{n} is not specified, the standard input (file descriptor 0) is used.
2311 [@var{n}]>&@var{word}
2314 is used similarly to duplicate output file descriptors. If
2315 @var{n} is not specified, the standard output (file descriptor 1) is used.
2316 If the digits in @var{word} do not specify a file descriptor open for
2317 output, a redirection error occurs.
2318 As a special case, if @var{n} is omitted, and @var{word} does not
2319 expand to one or more digits, the standard output and standard
2320 error are redirected as described previously.
2322 @subsection Moving File Descriptors
2323 The redirection operator
2325 [@var{n}]<&@var{digit}-
2328 moves the file descriptor @var{digit} to file descriptor @var{n},
2329 or the standard input (file descriptor 0) if @var{n} is not specified.
2330 @var{digit} is closed after being duplicated to @var{n}.
2332 Similarly, the redirection operator
2334 [@var{n}]>&@var{digit}-
2337 moves the file descriptor @var{digit} to file descriptor @var{n},
2338 or the standard output (file descriptor 1) if @var{n} is not specified.
2340 @subsection Opening File Descriptors for Reading and Writing
2341 The redirection operator
2343 [@var{n}]<>@var{word}
2346 causes the file whose name is the expansion of @var{word}
2347 to be opened for both reading and writing on file descriptor
2348 @var{n}, or on file descriptor 0 if @var{n}
2349 is not specified. If the file does not exist, it is created.
2351 @node Executing Commands
2352 @section Executing Commands
2355 * Simple Command Expansion:: How Bash expands simple commands before
2357 * Command Search and Execution:: How Bash finds commands and runs them.
2358 * Command Execution Environment:: The environment in which Bash
2359 executes commands that are not
2361 * Environment:: The environment given to a command.
2362 * Exit Status:: The status returned by commands and how Bash
2364 * Signals:: What happens when Bash or a command it runs
2368 @node Simple Command Expansion
2369 @subsection Simple Command Expansion
2370 @cindex command expansion
2372 When a simple command is executed, the shell performs the following
2373 expansions, assignments, and redirections, from left to right.
2377 The words that the parser has marked as variable assignments (those
2378 preceding the command name) and redirections are saved for later
2382 The words that are not variable assignments or redirections are
2383 expanded (@pxref{Shell Expansions}).
2384 If any words remain after expansion, the first word
2385 is taken to be the name of the command and the remaining words are
2389 Redirections are performed as described above (@pxref{Redirections}).
2392 The text after the @samp{=} in each variable assignment undergoes tilde
2393 expansion, parameter expansion, command substitution, arithmetic expansion,
2394 and quote removal before being assigned to the variable.
2397 If no command name results, the variable assignments affect the current
2398 shell environment. Otherwise, the variables are added to the environment
2399 of the executed command and do not affect the current shell environment.
2400 If any of the assignments attempts to assign a value to a readonly variable,
2401 an error occurs, and the command exits with a non-zero status.
2403 If no command name results, redirections are performed, but do not
2404 affect the current shell environment. A redirection error causes the
2405 command to exit with a non-zero status.
2407 If there is a command name left after expansion, execution proceeds as
2408 described below. Otherwise, the command exits. If one of the expansions
2409 contained a command substitution, the exit status of the command is
2410 the exit status of the last command substitution performed. If there
2411 were no command substitutions, the command exits with a status of zero.
2413 @node Command Search and Execution
2414 @subsection Command Search and Execution
2415 @cindex command execution
2416 @cindex command search
2418 After a command has been split into words, if it results in a
2419 simple command and an optional list of arguments, the following
2424 If the command name contains no slashes, the shell attempts to
2425 locate it. If there exists a shell function by that name, that
2426 function is invoked as described in @ref{Shell Functions}.
2429 If the name does not match a function, the shell searches for
2430 it in the list of shell builtins. If a match is found, that
2434 If the name is neither a shell function nor a builtin,
2435 and contains no slashes, Bash searches each element of
2436 @env{$PATH} for a directory containing an executable file
2437 by that name. Bash uses a hash table to remember the full
2438 pathnames of executable files to avoid multiple @env{PATH} searches
2439 (see the description of @code{hash} in @ref{Bourne Shell Builtins}).
2440 A full search of the directories in @env{$PATH}
2441 is performed only if the command is not found in the hash table.
2442 If the search is unsuccessful, the shell searches for a defined shell
2443 function named @code{command_not_found_handle}.
2444 If that function exists, it is invoked with the original command and
2445 the original command's arguments as its arguments, and the function's
2446 exit status becomes the exit status of the shell.
2447 If that function is not defined, the shell prints an error
2448 message and returns an exit status of 127.
2451 If the search is successful, or if the command name contains
2452 one or more slashes, the shell executes the named program in
2453 a separate execution environment.
2454 Argument 0 is set to the name given, and the remaining arguments
2455 to the command are set to the arguments supplied, if any.
2458 If this execution fails because the file is not in executable
2459 format, and the file is not a directory, it is assumed to be a
2460 @var{shell script} and the shell executes it as described in
2461 @ref{Shell Scripts}.
2464 If the command was not begun asynchronously, the shell waits for
2465 the command to complete and collects its exit status.
2469 @node Command Execution Environment
2470 @subsection Command Execution Environment
2471 @cindex execution environment
2473 The shell has an @var{execution environment}, which consists of the
2478 open files inherited by the shell at invocation, as modified by
2479 redirections supplied to the @code{exec} builtin
2482 the current working directory as set by @code{cd}, @code{pushd}, or
2483 @code{popd}, or inherited by the shell at invocation
2486 the file creation mode mask as set by @code{umask} or inherited from
2490 current traps set by @code{trap}
2493 shell parameters that are set by variable assignment or with @code{set}
2494 or inherited from the shell's parent in the environment
2497 shell functions defined during execution or inherited from the shell's
2498 parent in the environment
2501 options enabled at invocation (either by default or with command-line
2502 arguments) or by @code{set}
2505 options enabled by @code{shopt} (@pxref{The Shopt Builtin})
2508 shell aliases defined with @code{alias} (@pxref{Aliases})
2511 various process @sc{id}s, including those of background jobs
2512 (@pxref{Lists}), the value of @code{$$}, and the value of
2517 When a simple command other than a builtin or shell function
2518 is to be executed, it
2519 is invoked in a separate execution environment that consists of
2520 the following. Unless otherwise noted, the values are inherited
2525 the shell's open files, plus any modifications and additions specified
2526 by redirections to the command
2529 the current working directory
2532 the file creation mode mask
2535 shell variables and functions marked for export, along with variables
2536 exported for the command, passed in the environment (@pxref{Environment})
2539 traps caught by the shell are reset to the values inherited from the
2540 shell's parent, and traps ignored by the shell are ignored
2544 A command invoked in this separate environment cannot affect the
2545 shell's execution environment.
2547 Command substitution, commands grouped with parentheses,
2548 and asynchronous commands are invoked in a
2549 subshell environment that is a duplicate of the shell environment,
2550 except that traps caught by the shell are reset to the values
2551 that the shell inherited from its parent at invocation. Builtin
2552 commands that are invoked as part of a pipeline are also executed
2553 in a subshell environment. Changes made to the subshell environment
2554 cannot affect the shell's execution environment.
2556 Subshells spawned to execute command substitutions inherit the value of
2557 the @option{-e} option from the parent shell. When not in @sc{posix} mode,
2558 Bash clears the @option{-e} option in such subshells.
2560 If a command is followed by a @samp{&} and job control is not active, the
2561 default standard input for the command is the empty file @file{/dev/null}.
2562 Otherwise, the invoked command inherits the file descriptors of the calling
2563 shell as modified by redirections.
2566 @subsection Environment
2569 When a program is invoked it is given an array of strings
2570 called the @var{environment}.
2571 This is a list of name-value pairs, of the form @code{name=value}.
2573 Bash provides several ways to manipulate the environment.
2574 On invocation, the shell scans its own environment and
2575 creates a parameter for each name found, automatically marking
2577 to child processes. Executed commands inherit the environment.
2578 The @code{export} and @samp{declare -x}
2579 commands allow parameters and functions to be added to and
2580 deleted from the environment. If the value of a parameter
2581 in the environment is modified, the new value becomes part
2582 of the environment, replacing the old. The environment
2583 inherited by any executed command consists of the shell's
2584 initial environment, whose values may be modified in the shell,
2585 less any pairs removed by the @code{unset} and @samp{export -n}
2586 commands, plus any additions via the @code{export} and
2587 @samp{declare -x} commands.
2589 The environment for any simple command
2590 or function may be augmented temporarily by prefixing it with
2591 parameter assignments, as described in @ref{Shell Parameters}.
2592 These assignment statements affect only the environment seen
2595 If the @option{-k} option is set (@pxref{The Set Builtin}), then all
2596 parameter assignments are placed in the environment for a command,
2597 not just those that precede the command name.
2599 When Bash invokes an external command, the variable @samp{$_}
2600 is set to the full path name of the command and passed to that
2601 command in its environment.
2604 @subsection Exit Status
2607 The exit status of an executed command is the value returned by the
2608 @var{waitpid} system call or equivalent function. Exit statuses
2609 fall between 0 and 255, though, as explained below, the shell may
2610 use values above 125 specially. Exit statuses from shell builtins and
2611 compound commands are also limited to this range. Under certain
2612 circumstances, the shell will use special values to indicate specific
2615 For the shell's purposes, a command which exits with a
2616 zero exit status has succeeded.
2617 A non-zero exit status indicates failure.
2618 This seemingly counter-intuitive scheme is used so there
2619 is one well-defined way to indicate success and a variety of
2620 ways to indicate various failure modes.
2621 When a command terminates on a fatal signal whose number is @var{N},
2622 Bash uses the value 128+@var{N} as the exit status.
2624 If a command is not found, the child process created to
2625 execute it returns a status of 127. If a command is found
2626 but is not executable, the return status is 126.
2628 If a command fails because of an error during expansion or redirection,
2629 the exit status is greater than zero.
2631 The exit status is used by the Bash conditional commands
2632 (@pxref{Conditional Constructs}) and some of the list
2633 constructs (@pxref{Lists}).
2635 All of the Bash builtins return an exit status of zero if they succeed
2636 and a non-zero status on failure, so they may be used by the
2637 conditional and list constructs.
2638 All builtins return an exit status of 2 to indicate incorrect usage.
2642 @cindex signal handling
2644 When Bash is interactive, in the absence of any traps, it ignores
2645 @code{SIGTERM} (so that @samp{kill 0} does not kill an interactive shell),
2647 is caught and handled (so that the @code{wait} builtin is interruptible).
2648 When Bash receives a @code{SIGINT}, it breaks out of any executing loops.
2649 In all cases, Bash ignores @code{SIGQUIT}.
2650 If job control is in effect (@pxref{Job Control}), Bash
2651 ignores @code{SIGTTIN}, @code{SIGTTOU}, and @code{SIGTSTP}.
2653 Non-builtin commands started by Bash have signal handlers set to the
2654 values inherited by the shell from its parent.
2655 When job control is not in effect, asynchronous commands
2656 ignore @code{SIGINT} and @code{SIGQUIT} in addition to these inherited
2658 Commands run as a result of
2659 command substitution ignore the keyboard-generated job control signals
2660 @code{SIGTTIN}, @code{SIGTTOU}, and @code{SIGTSTP}.
2662 The shell exits by default upon receipt of a @code{SIGHUP}.
2663 Before exiting, an interactive shell resends the @code{SIGHUP} to
2664 all jobs, running or stopped.
2665 Stopped jobs are sent @code{SIGCONT} to ensure that they receive
2667 To prevent the shell from sending the @code{SIGHUP} signal to a
2668 particular job, it should be removed
2669 from the jobs table with the @code{disown}
2670 builtin (@pxref{Job Control Builtins}) or marked
2671 to not receive @code{SIGHUP} using @code{disown -h}.
2673 If the @code{huponexit} shell option has been set with @code{shopt}
2674 (@pxref{The Shopt Builtin}), Bash sends a @code{SIGHUP} to all jobs when
2675 an interactive login shell exits.
2677 If Bash is waiting for a command to complete and receives a signal
2678 for which a trap has been set, the trap will not be executed until
2679 the command completes.
2680 When Bash is waiting for an asynchronous
2681 command via the @code{wait} builtin, the reception of a signal for
2682 which a trap has been set will cause the @code{wait} builtin to return
2683 immediately with an exit status greater than 128, immediately after
2684 which the trap is executed.
2687 @section Shell Scripts
2688 @cindex shell script
2690 A shell script is a text file containing shell commands. When such
2691 a file is used as the first non-option argument when invoking Bash,
2692 and neither the @option{-c} nor @option{-s} option is supplied
2693 (@pxref{Invoking Bash}),
2694 Bash reads and executes commands from the file, then exits. This
2695 mode of operation creates a non-interactive shell. The shell first
2696 searches for the file in the current directory, and looks in the
2697 directories in @env{$PATH} if not found there.
2700 a shell script, it sets the special parameter @code{0} to the name
2701 of the file, rather than the name of the shell, and the positional
2702 parameters are set to the remaining arguments, if any are given.
2703 If no additional arguments are supplied, the positional parameters
2706 A shell script may be made executable by using the @code{chmod} command
2707 to turn on the execute bit. When Bash finds such a file while
2708 searching the @env{$PATH} for a command, it spawns a subshell to
2709 execute it. In other words, executing
2711 filename @var{arguments}
2714 is equivalent to executing
2716 bash filename @var{arguments}
2720 if @code{filename} is an executable shell script.
2721 This subshell reinitializes itself, so that the effect is as if a
2722 new shell had been invoked to interpret the script, with the
2723 exception that the locations of commands remembered by the parent
2724 (see the description of @code{hash} in @ref{Bourne Shell Builtins})
2725 are retained by the child.
2727 Most versions of Unix make this a part of the operating system's command
2728 execution mechanism. If the first line of a script begins with
2729 the two characters @samp{#!}, the remainder of the line specifies
2730 an interpreter for the program.
2731 Thus, you can specify Bash, @code{awk}, Perl, or some other
2732 interpreter and write the rest of the script file in that language.
2734 The arguments to the interpreter
2735 consist of a single optional argument following the interpreter
2736 name on the first line of the script file, followed by the name of
2737 the script file, followed by the rest of the arguments. Bash
2738 will perform this action on operating systems that do not handle it
2739 themselves. Note that some older versions of Unix limit the interpreter
2740 name and argument to a maximum of 32 characters.
2742 Bash scripts often begin with @code{#! /bin/bash} (assuming that
2743 Bash has been installed in @file{/bin}), since this ensures that
2744 Bash will be used to interpret the script, even if it is executed
2745 under another shell.
2747 @node Shell Builtin Commands
2748 @chapter Shell Builtin Commands
2751 * Bourne Shell Builtins:: Builtin commands inherited from the Bourne
2753 * Bash Builtins:: Table of builtins specific to Bash.
2754 * Modifying Shell Behavior:: Builtins to modify shell attributes and
2756 * Special Builtins:: Builtin commands classified specially by
2760 Builtin commands are contained within the shell itself.
2761 When the name of a builtin command is used as the first word of
2762 a simple command (@pxref{Simple Commands}), the shell executes
2763 the command directly, without invoking another program.
2764 Builtin commands are necessary to implement functionality impossible
2765 or inconvenient to obtain with separate utilities.
2767 This section briefly describes the builtins which Bash inherits from
2768 the Bourne Shell, as well as the builtin commands which are unique
2769 to or have been extended in Bash.
2771 Several builtin commands are described in other chapters: builtin
2772 commands which provide the Bash interface to the job control
2773 facilities (@pxref{Job Control Builtins}), the directory stack
2774 (@pxref{Directory Stack Builtins}), the command history
2775 (@pxref{Bash History Builtins}), and the programmable completion
2776 facilities (@pxref{Programmable Completion Builtins}).
2778 Many of the builtins have been extended by @sc{posix} or Bash.
2780 Unless otherwise noted, each builtin command documented as accepting
2781 options preceded by @samp{-} accepts @samp{--}
2782 to signify the end of the options.
2783 The @code{:}, @code{true}, @code{false}, and @code{test}
2784 builtins do not accept options and do not treat @samp{--} specially.
2785 The @code{exit}, @code{logout}, @code{break}, @code{continue}, @code{let},
2786 and @code{shift} builtins accept and process arguments beginning
2787 with @samp{-} without requiring @samp{--}.
2788 Other builtins that accept arguments but are not specified as accepting
2789 options interpret arguments beginning with @samp{-} as invalid options and
2790 require @samp{--} to prevent this interpretation.
2792 @node Bourne Shell Builtins
2793 @section Bourne Shell Builtins
2795 The following shell builtin commands are inherited from the Bourne Shell.
2796 These commands are implemented as specified by the @sc{posix} standard.
2799 @item : @r{(a colon)}
2804 Do nothing beyond expanding @var{arguments} and performing redirections.
2805 The return status is zero.
2807 @item . @r{(a period)}
2810 . @var{filename} [@var{arguments}]
2812 Read and execute commands from the @var{filename} argument in the
2813 current shell context. If @var{filename} does not contain a slash,
2814 the @env{PATH} variable is used to find @var{filename}.
2815 When Bash is not in @sc{posix} mode, the current directory is searched
2816 if @var{filename} is not found in @env{$PATH}.
2817 If any @var{arguments} are supplied, they become the positional
2818 parameters when @var{filename} is executed. Otherwise the positional
2819 parameters are unchanged.
2820 The return status is the exit status of the last command executed, or
2821 zero if no commands are executed. If @var{filename} is not found, or
2822 cannot be read, the return status is non-zero.
2823 This builtin is equivalent to @code{source}.
2830 Exit from a @code{for}, @code{while}, @code{until}, or @code{select} loop.
2831 If @var{n} is supplied, the @var{n}th enclosing loop is exited.
2832 @var{n} must be greater than or equal to 1.
2833 The return status is zero unless @var{n} is not greater than or equal to 1.
2838 cd [-L|-P] [@var{directory}]
2840 Change the current working directory to @var{directory}.
2841 If @var{directory} is not given, the value of the @env{HOME} shell
2843 If the shell variable @env{CDPATH} exists, it is used as a search path.
2844 If @var{directory} begins with a slash, @env{CDPATH} is not used.
2846 The @option{-P} option means to not follow symbolic links; symbolic
2847 links are followed by default or with the @option{-L} option.
2848 If @var{directory} is @samp{-}, it is equivalent to @env{$OLDPWD}.
2850 If a non-empty directory name from @env{CDPATH} is used, or if
2851 @samp{-} is the first argument, and the directory change is
2852 successful, the absolute pathname of the new working directory is
2853 written to the standard output.
2855 The return status is zero if the directory is successfully changed,
2863 Resume the next iteration of an enclosing @code{for}, @code{while},
2864 @code{until}, or @code{select} loop.
2865 If @var{n} is supplied, the execution of the @var{n}th enclosing loop
2867 @var{n} must be greater than or equal to 1.
2868 The return status is zero unless @var{n} is not greater than or equal to 1.
2873 eval [@var{arguments}]
2875 The arguments are concatenated together into a single command, which is
2876 then read and executed, and its exit status returned as the exit status
2878 If there are no arguments or only empty arguments, the return status is
2884 exec [-cl] [-a @var{name}] [@var{command} [@var{arguments}]]
2887 is supplied, it replaces the shell without creating a new process.
2888 If the @option{-l} option is supplied, the shell places a dash at the
2889 beginning of the zeroth argument passed to @var{command}.
2890 This is what the @code{login} program does.
2891 The @option{-c} option causes @var{command} to be executed with an empty
2893 If @option{-a} is supplied, the shell passes @var{name} as the zeroth
2894 argument to @var{command}.
2895 If no @var{command} is specified, redirections may be used to affect
2896 the current shell environment. If there are no redirection errors, the
2897 return status is zero; otherwise the return status is non-zero.
2904 Exit the shell, returning a status of @var{n} to the shell's parent.
2905 If @var{n} is omitted, the exit status is that of the last command executed.
2906 Any trap on @code{EXIT} is executed before the shell terminates.
2911 export [-fn] [-p] [@var{name}[=@var{value}]]
2913 Mark each @var{name} to be passed to child processes
2914 in the environment. If the @option{-f} option is supplied, the @var{name}s
2915 refer to shell functions; otherwise the names refer to shell variables.
2916 The @option{-n} option means to no longer mark each @var{name} for export.
2917 If no @var{names} are supplied, or if the @option{-p} option is given, a
2918 list of exported names is displayed.
2919 The @option{-p} option displays output in a form that may be reused as input.
2920 If a variable name is followed by =@var{value}, the value of
2921 the variable is set to @var{value}.
2923 The return status is zero unless an invalid option is supplied, one of
2924 the names is not a valid shell variable name, or @option{-f} is supplied
2925 with a name that is not a shell function.
2930 getopts @var{optstring} @var{name} [@var{args}]
2932 @code{getopts} is used by shell scripts to parse positional parameters.
2933 @var{optstring} contains the option characters to be recognized; if a
2934 character is followed by a colon, the option is expected to have an
2935 argument, which should be separated from it by white space.
2936 The colon (@samp{:}) and question mark (@samp{?}) may not be
2937 used as option characters.
2938 Each time it is invoked, @code{getopts}
2939 places the next option in the shell variable @var{name}, initializing
2940 @var{name} if it does not exist,
2941 and the index of the next argument to be processed into the
2942 variable @env{OPTIND}.
2943 @env{OPTIND} is initialized to 1 each time the shell or a shell script
2945 When an option requires an argument,
2946 @code{getopts} places that argument into the variable @env{OPTARG}.
2947 The shell does not reset @env{OPTIND} automatically; it must be manually
2948 reset between multiple calls to @code{getopts} within the same shell
2949 invocation if a new set of parameters is to be used.
2951 When the end of options is encountered, @code{getopts} exits with a
2952 return value greater than zero.
2953 @env{OPTIND} is set to the index of the first non-option argument,
2954 and @code{name} is set to @samp{?}.
2957 normally parses the positional parameters, but if more arguments are
2958 given in @var{args}, @code{getopts} parses those instead.
2960 @code{getopts} can report errors in two ways. If the first character of
2961 @var{optstring} is a colon, @var{silent}
2962 error reporting is used. In normal operation diagnostic messages
2963 are printed when invalid options or missing option arguments are
2965 If the variable @env{OPTERR}
2966 is set to 0, no error messages will be displayed, even if the first
2967 character of @code{optstring} is not a colon.
2969 If an invalid option is seen,
2970 @code{getopts} places @samp{?} into @var{name} and, if not silent,
2971 prints an error message and unsets @env{OPTARG}.
2972 If @code{getopts} is silent, the option character found is placed in
2973 @env{OPTARG} and no diagnostic message is printed.
2975 If a required argument is not found, and @code{getopts}
2976 is not silent, a question mark (@samp{?}) is placed in @var{name},
2977 @code{OPTARG} is unset, and a diagnostic message is printed.
2978 If @code{getopts} is silent, then a colon (@samp{:}) is placed in
2979 @var{name} and @env{OPTARG} is set to the option character found.
2984 hash [-r] [-p @var{filename}] [-dt] [@var{name}]
2986 Remember the full pathnames of commands specified as @var{name} arguments,
2987 so they need not be searched for on subsequent invocations.
2988 The commands are found by searching through the directories listed in
2990 The @option{-p} option inhibits the path search, and @var{filename} is
2991 used as the location of @var{name}.
2992 The @option{-r} option causes the shell to forget all remembered locations.
2993 The @option{-d} option causes the shell to forget the remembered location
2995 If the @option{-t} option is supplied, the full pathname to which each
2996 @var{name} corresponds is printed. If multiple @var{name} arguments are
2997 supplied with @option{-t} the @var{name} is printed before the hashed
2999 The @option{-l} option causes output to be displayed in a format
3000 that may be reused as input.
3001 If no arguments are given, or if only @option{-l} is supplied,
3002 information about remembered commands is printed.
3003 The return status is zero unless a @var{name} is not found or an invalid
3011 Print the absolute pathname of the current working directory.
3012 If the @option{-P} option is supplied, the pathname printed will not
3013 contain symbolic links.
3014 If the @option{-L} option is supplied, the pathname printed may contain
3016 The return status is zero unless an error is encountered while
3017 determining the name of the current directory or an invalid option
3023 readonly [-aApf] [@var{name}[=@var{value}]] @dots{}
3025 Mark each @var{name} as readonly.
3026 The values of these names may not be changed by subsequent assignment.
3027 If the @option{-f} option is supplied, each @var{name} refers to a shell
3029 The @option{-a} option means each @var{name} refers to an indexed
3030 array variable; the @option{-A} option means each @var{name} refers
3031 to an associative array variable.
3032 If no @var{name} arguments are given, or if the @option{-p}
3033 option is supplied, a list of all readonly names is printed.
3034 The @option{-p} option causes output to be displayed in a format that
3035 may be reused as input.
3036 If a variable name is followed by =@var{value}, the value of
3037 the variable is set to @var{value}.
3038 The return status is zero unless an invalid option is supplied, one of
3039 the @var{name} arguments is not a valid shell variable or function name,
3040 or the @option{-f} option is supplied with a name that is not a shell function.
3047 Cause a shell function to exit with the return value @var{n}.
3048 If @var{n} is not supplied, the return value is the exit status of the
3049 last command executed in the function.
3050 This may also be used to terminate execution of a script being executed
3051 with the @code{.} (or @code{source}) builtin, returning either @var{n} or
3052 the exit status of the last command executed within the script as the exit
3053 status of the script.
3054 Any command associated with the @code{RETURN} trap is executed
3055 before execution resumes after the function or script.
3056 The return status is non-zero if @code{return} is used outside a function
3057 and not during the execution of a script by @code{.} or @code{source}.
3064 Shift the positional parameters to the left by @var{n}.
3065 The positional parameters from @var{n}+1 @dots{} @code{$#} are
3066 renamed to @code{$1} @dots{} @code{$#}-@var{n}.
3067 Parameters represented by the numbers @code{$#} to @code{$#}-@var{n}+1
3069 @var{n} must be a non-negative number less than or equal to @code{$#}.
3070 If @var{n} is zero or greater than @code{$#}, the positional parameters
3072 If @var{n} is not supplied, it is assumed to be 1.
3073 The return status is zero unless @var{n} is greater than @code{$#} or
3074 less than zero, non-zero otherwise.
3080 Evaluate a conditional expression @var{expr}.
3081 Each operator and operand must be a separate argument.
3082 Expressions are composed of the primaries described below in
3083 @ref{Bash Conditional Expressions}.
3084 @code{test} does not accept any options, nor does it accept and ignore
3085 an argument of @option{--} as signifying the end of options.
3087 When the @code{[} form is used, the last argument to the command must
3090 Expressions may be combined using the following operators, listed in
3091 decreasing order of precedence.
3092 The evaluation depends on the number of arguments; see below.
3096 True if @var{expr} is false.
3098 @item ( @var{expr} )
3099 Returns the value of @var{expr}.
3100 This may be used to override the normal precedence of operators.
3102 @item @var{expr1} -a @var{expr2}
3103 True if both @var{expr1} and @var{expr2} are true.
3105 @item @var{expr1} -o @var{expr2}
3106 True if either @var{expr1} or @var{expr2} is true.
3109 The @code{test} and @code{[} builtins evaluate conditional
3110 expressions using a set of rules based on the number of arguments.
3114 The expression is false.
3117 The expression is true if and only if the argument is not null.
3120 If the first argument is @samp{!}, the expression is true if and
3121 only if the second argument is null.
3122 If the first argument is one of the unary conditional operators
3123 (@pxref{Bash Conditional Expressions}), the expression
3124 is true if the unary test is true.
3125 If the first argument is not a valid unary operator, the expression is
3129 If the second argument is one of the binary conditional
3130 operators (@pxref{Bash Conditional Expressions}), the
3131 result of the expression is the result of the binary test using the
3132 first and third arguments as operands.
3133 The @samp{-a} and @samp{-o} operators are considered binary operators
3134 when there are three arguments.
3135 If the first argument is @samp{!}, the value is the negation of
3136 the two-argument test using the second and third arguments.
3137 If the first argument is exactly @samp{(} and the third argument is
3138 exactly @samp{)}, the result is the one-argument test of the second
3140 Otherwise, the expression is false.
3143 If the first argument is @samp{!}, the result is the negation of
3144 the three-argument expression composed of the remaining arguments.
3145 Otherwise, the expression is parsed and evaluated according to
3146 precedence using the rules listed above.
3148 @item 5 or more arguments
3149 The expression is parsed and evaluated according to precedence
3150 using the rules listed above.
3158 Print out the user and system times used by the shell and its children.
3159 The return status is zero.
3164 trap [-lp] [@var{arg}] [@var{sigspec} @dots{}]
3166 The commands in @var{arg} are to be read and executed when the
3167 shell receives signal @var{sigspec}. If @var{arg} is absent (and
3168 there is a single @var{sigspec}) or
3169 equal to @samp{-}, each specified signal's disposition is reset
3170 to the value it had when the shell was started.
3171 If @var{arg} is the null string, then the signal specified by
3172 each @var{sigspec} is ignored by the shell and commands it invokes.
3173 If @var{arg} is not present and @option{-p} has been supplied,
3174 the shell displays the trap commands associated with each @var{sigspec}.
3175 If no arguments are supplied, or
3176 only @option{-p} is given, @code{trap} prints the list of commands
3177 associated with each signal number in a form that may be reused as
3179 The @option{-l} option causes the shell to print a list of signal names
3180 and their corresponding numbers.
3181 Each @var{sigspec} is either a signal name or a signal number.
3182 Signal names are case insensitive and the @code{SIG} prefix is optional.
3185 is @code{0} or @code{EXIT}, @var{arg} is executed when the shell exits.
3186 If a @var{sigspec} is @code{DEBUG}, the command @var{arg} is executed
3187 before every simple command, @code{for} command, @code{case} command,
3188 @code{select} command, every arithmetic @code{for} command, and before
3189 the first command executes in a shell function.
3190 Refer to the description of the @code{extdebug} option to the
3191 @code{shopt} builtin (@pxref{The Shopt Builtin}) for details of its
3192 effect on the @code{DEBUG} trap.
3193 If a @var{sigspec} is @code{RETURN}, the command @var{arg} is executed
3194 each time a shell function or a script executed with the @code{.} or
3195 @code{source} builtins finishes executing.
3197 If a @var{sigspec} is @code{ERR}, the command @var{arg}
3198 is executed whenever a simple command has a non-zero exit status,
3199 subject to the following conditions.
3200 The @code{ERR} trap is not executed if the failed command is part of the
3201 command list immediately following an @code{until} or @code{while} keyword,
3202 part of the test following the @code{if} or @code{elif} reserved words,
3203 part of a command executed in a @code{&&} or @code{||} list,
3204 or if the command's return
3205 status is being inverted using @code{!}.
3206 These are the same conditions obeyed by the @code{errexit} option.
3208 Signals ignored upon entry to the shell cannot be trapped or reset.
3209 Trapped signals that are not being ignored are reset to their original
3210 values in a subshell or subshell environment when one is created.
3212 The return status is zero unless a @var{sigspec} does not specify a
3218 umask [-p] [-S] [@var{mode}]
3220 Set the shell process's file creation mask to @var{mode}. If
3221 @var{mode} begins with a digit, it is interpreted as an octal number;
3222 if not, it is interpreted as a symbolic mode mask similar
3223 to that accepted by the @code{chmod} command. If @var{mode} is
3224 omitted, the current value of the mask is printed. If the @option{-S}
3225 option is supplied without a @var{mode} argument, the mask is printed
3226 in a symbolic format.
3227 If the @option{-p} option is supplied, and @var{mode}
3228 is omitted, the output is in a form that may be reused as input.
3229 The return status is zero if the mode is successfully changed or if
3230 no @var{mode} argument is supplied, and non-zero otherwise.
3232 Note that when the mode is interpreted as an octal number, each number
3233 of the umask is subtracted from @code{7}. Thus, a umask of @code{022}
3234 results in permissions of @code{755}.
3239 unset [-fv] [@var{name}]
3241 Each variable or function @var{name} is removed.
3242 If no options are supplied, or the @option{-v} option is given, each
3243 @var{name} refers to a shell variable.
3244 If the @option{-f} option is given, the @var{name}s refer to shell
3245 functions, and the function definition is removed.
3246 Readonly variables and functions may not be unset.
3247 The return status is zero unless a @var{name} is readonly.
3251 @section Bash Builtin Commands
3253 This section describes builtin commands which are unique to
3254 or have been extended in Bash.
3255 Some of these commands are specified in the @sc{posix} standard.
3262 alias [@code{-p}] [@var{name}[=@var{value}] @dots{}]
3265 Without arguments or with the @option{-p} option, @code{alias} prints
3266 the list of aliases on the standard output in a form that allows
3267 them to be reused as input.
3268 If arguments are supplied, an alias is defined for each @var{name}
3269 whose @var{value} is given. If no @var{value} is given, the name
3270 and value of the alias is printed.
3271 Aliases are described in @ref{Aliases}.
3276 bind [-m @var{keymap}] [-lpsvPSV]
3277 bind [-m @var{keymap}] [-q @var{function}] [-u @var{function}] [-r @var{keyseq}]
3278 bind [-m @var{keymap}] -f @var{filename}
3279 bind [-m @var{keymap}] -x @var{keyseq:shell-command}
3280 bind [-m @var{keymap}] @var{keyseq:function-name}
3281 bind @var{readline-command}
3284 Display current Readline (@pxref{Command Line Editing})
3285 key and function bindings,
3286 bind a key sequence to a Readline function or macro,
3287 or set a Readline variable.
3288 Each non-option argument is a command as it would appear in a
3289 Readline initialization file (@pxref{Readline Init File}),
3290 but each binding or command must be passed as a separate argument; e.g.,
3291 @samp{"\C-x\C-r":re-read-init-file}.
3293 Options, if supplied, have the following meanings:
3296 @item -m @var{keymap}
3297 Use @var{keymap} as the keymap to be affected by
3298 the subsequent bindings. Acceptable @var{keymap}
3301 @code{emacs-standard},
3306 @code{vi-command}, and
3308 @code{vi} is equivalent to @code{vi-command};
3309 @code{emacs} is equivalent to @code{emacs-standard}.
3312 List the names of all Readline functions.
3315 Display Readline function names and bindings in such a way that they
3316 can be used as input or in a Readline initialization file.
3319 List current Readline function names and bindings.
3322 Display Readline variable names and values in such a way that they
3323 can be used as input or in a Readline initialization file.
3326 List current Readline variable names and values.
3329 Display Readline key sequences bound to macros and the strings they output
3330 in such a way that they can be used as input or in a Readline
3331 initialization file.
3334 Display Readline key sequences bound to macros and the strings they output.
3336 @item -f @var{filename}
3337 Read key bindings from @var{filename}.
3339 @item -q @var{function}
3340 Query about which keys invoke the named @var{function}.
3342 @item -u @var{function}
3343 Unbind all keys bound to the named @var{function}.
3345 @item -r @var{keyseq}
3346 Remove any current binding for @var{keyseq}.
3348 @item -x @var{keyseq:shell-command}
3349 Cause @var{shell-command} to be executed whenever @var{keyseq} is
3351 When @var{shell-command} is executed, the shell sets the
3352 @code{READLINE_LINE} variable to the contents of the Readline line
3353 buffer and the @code{READLINE_POINT} variable to the current location
3354 of the insertion point.
3355 If the executed command changes the value of @code{READLINE_LINE} or
3356 @code{READLINE_POINT}, those new values will be reflected in the
3361 The return status is zero unless an invalid option is supplied or an
3367 builtin [@var{shell-builtin} [@var{args}]]
3369 Run a shell builtin, passing it @var{args}, and return its exit status.
3370 This is useful when defining a shell function with the same
3371 name as a shell builtin, retaining the functionality of the builtin within
3373 The return status is non-zero if @var{shell-builtin} is not a shell
3381 Returns the context of any active subroutine call (a shell function or
3382 a script executed with the @code{.} or @code{source} builtins).
3384 Without @var{expr}, @code{caller} displays the line number and source
3385 filename of the current subroutine call.
3386 If a non-negative integer is supplied as @var{expr}, @code{caller}
3387 displays the line number, subroutine name, and source file corresponding
3388 to that position in the current execution call stack. This extra
3389 information may be used, for example, to print a stack trace. The
3390 current frame is frame 0.
3392 The return value is 0 unless the shell is not executing a subroutine
3393 call or @var{expr} does not correspond to a valid position in the
3399 command [-pVv] @var{command} [@var{arguments} @dots{}]
3401 Runs @var{command} with @var{arguments} ignoring any shell function
3402 named @var{command}.
3403 Only shell builtin commands or commands found by searching the
3404 @env{PATH} are executed.
3405 If there is a shell function named @code{ls}, running @samp{command ls}
3406 within the function will execute the external command @code{ls}
3407 instead of calling the function recursively.
3408 The @option{-p} option means to use a default value for @env{PATH}
3409 that is guaranteed to find all of the standard utilities.
3410 The return status in this case is 127 if @var{command} cannot be
3411 found or an error occurred, and the exit status of @var{command}
3414 If either the @option{-V} or @option{-v} option is supplied, a
3415 description of @var{command} is printed. The @option{-v} option
3416 causes a single word indicating the command or file name used to
3417 invoke @var{command} to be displayed; the @option{-V} option produces
3418 a more verbose description. In this case, the return status is
3419 zero if @var{command} is found, and non-zero if not.
3424 declare [-aAfFilrtux] [-p] [@var{name}[=@var{value}] @dots{}]
3427 Declare variables and give them attributes. If no @var{name}s
3428 are given, then display the values of variables instead.
3430 The @option{-p} option will display the attributes and values of each
3432 When @option{-p} is used with @var{name} arguments, additional options
3435 When @option{-p} is supplied without @var{name} arguments, @code{declare}
3436 will display the attributes and values of all variables having the
3437 attributes specified by the additional options.
3438 If no other options are supplied with @option{-p}, @code{declare} will
3439 display the attributes and values of all shell variables. The @option{-f}
3440 option will restrict the display to shell functions.
3442 The @option{-F} option inhibits the display of function definitions;
3443 only the function name and attributes are printed.
3444 If the @code{extdebug} shell option is enabled using @code{shopt}
3445 (@pxref{The Shopt Builtin}), the source file name and line number where
3446 the function is defined are displayed as well.
3447 @option{-F} implies @option{-f}.
3448 The following options can be used to restrict output to variables with
3449 the specified attributes or to give variables attributes:
3453 Each @var{name} is an indexed array variable (@pxref{Arrays}).
3456 Each @var{name} is an associative array variable (@pxref{Arrays}).
3459 Use function names only.
3462 The variable is to be treated as
3463 an integer; arithmetic evaluation (@pxref{Shell Arithmetic}) is
3464 performed when the variable is assigned a value.
3467 When the variable is assigned a value, all upper-case characters are
3468 converted to lower-case.
3469 The upper-case attribute is disabled.
3472 Make @var{name}s readonly. These names cannot then be assigned values
3473 by subsequent assignment statements or unset.
3476 Give each @var{name} the @code{trace} attribute.
3477 Traced functions inherit the @code{DEBUG} and @code{RETURN} traps from
3479 The trace attribute has no special meaning for variables.
3482 When the variable is assigned a value, all lower-case characters are
3483 converted to upper-case.
3484 The lower-case attribute is disabled.
3487 Mark each @var{name} for export to subsequent commands via
3491 Using @samp{+} instead of @samp{-} turns off the attribute instead,
3492 with the exceptions that @samp{+a}
3493 may not be used to destroy an array variable and @samp{+r} will not
3494 remove the readonly attribute.
3495 When used in a function, @code{declare} makes each @var{name} local,
3496 as with the @code{local} command. If a variable name is followed by
3497 =@var{value}, the value of the variable is set to @var{value}.
3499 The return status is zero unless an invalid option is encountered,
3500 an attempt is made to define a function using @samp{-f foo=bar},
3501 an attempt is made to assign a value to a readonly variable,
3502 an attempt is made to assign a value to an array variable without
3503 using the compound assignment syntax (@pxref{Arrays}),
3504 one of the @var{names} is not a valid shell variable name,
3505 an attempt is made to turn off readonly status for a readonly variable,
3506 an attempt is made to turn off array status for an array variable,
3507 or an attempt is made to display a non-existent function with @option{-f}.
3512 echo [-neE] [@var{arg} @dots{}]
3514 Output the @var{arg}s, separated by spaces, terminated with a
3516 The return status is always 0.
3517 If @option{-n} is specified, the trailing newline is suppressed.
3518 If the @option{-e} option is given, interpretation of the following
3519 backslash-escaped characters is enabled.
3520 The @option{-E} option disables the interpretation of these escape characters,
3521 even on systems where they are interpreted by default.
3522 The @code{xpg_echo} shell option may be used to
3523 dynamically determine whether or not @code{echo} expands these
3524 escape characters by default.
3525 @code{echo} does not interpret @option{--} to mean the end of options.
3527 @code{echo} interprets the following escape sequences:
3534 suppress further output
3550 the eight-bit character whose value is the octal value @var{nnn}
3551 (zero to three octal digits)
3553 the eight-bit character whose value is the hexadecimal value @var{HH}
3554 (one or two hex digits)
3560 enable [-a] [-dnps] [-f @var{filename}] [@var{name} @dots{}]
3562 Enable and disable builtin shell commands.
3563 Disabling a builtin allows a disk command which has the same name
3564 as a shell builtin to be executed without specifying a full pathname,
3565 even though the shell normally searches for builtins before disk commands.
3566 If @option{-n} is used, the @var{name}s become disabled. Otherwise
3567 @var{name}s are enabled. For example, to use the @code{test} binary
3568 found via @env{$PATH} instead of the shell builtin version, type
3569 @samp{enable -n test}.
3571 If the @option{-p} option is supplied, or no @var{name} arguments appear,
3572 a list of shell builtins is printed. With no other arguments, the list
3573 consists of all enabled shell builtins.
3574 The @option{-a} option means to list
3575 each builtin with an indication of whether or not it is enabled.
3577 The @option{-f} option means to load the new builtin command @var{name}
3578 from shared object @var{filename}, on systems that support dynamic loading.
3579 The @option{-d} option will delete a builtin loaded with @option{-f}.
3581 If there are no options, a list of the shell builtins is displayed.
3582 The @option{-s} option restricts @code{enable} to the @sc{posix} special
3583 builtins. If @option{-s} is used with @option{-f}, the new builtin becomes
3584 a special builtin (@pxref{Special Builtins}).
3586 The return status is zero unless a @var{name} is not a shell builtin
3587 or there is an error loading a new builtin from a shared object.
3592 help [-dms] [@var{pattern}]
3594 Display helpful information about builtin commands.
3595 If @var{pattern} is specified, @code{help} gives detailed help
3596 on all commands matching @var{pattern}, otherwise a list of
3597 the builtins is printed.
3599 Options, if supplied, have the following meanings:
3603 Display a short description of each @var{pattern}
3605 Display the description of each @var{pattern} in a manpage-like format
3607 Display only a short usage synopsis for each @var{pattern}
3610 The return status is zero unless no command matches @var{pattern}.
3615 let @var{expression} [@var{expression}]
3617 The @code{let} builtin allows arithmetic to be performed on shell
3618 variables. Each @var{expression} is evaluated according to the
3619 rules given below in @ref{Shell Arithmetic}. If the
3620 last @var{expression} evaluates to 0, @code{let} returns 1;
3621 otherwise 0 is returned.
3626 local [@var{option}] @var{name}[=@var{value}] @dots{}
3628 For each argument, a local variable named @var{name} is created,
3629 and assigned @var{value}.
3630 The @var{option} can be any of the options accepted by @code{declare}.
3631 @code{local} can only be used within a function; it makes the variable
3632 @var{name} have a visible scope restricted to that function and its
3633 children. The return status is zero unless @code{local} is used outside
3634 a function, an invalid @var{name} is supplied, or @var{name} is a
3642 Exit a login shell, returning a status of @var{n} to the shell's
3648 mapfile [-n @var{count}] [-O @var{origin}] [-s @var{count}] [-t] [-u @var{fd}] [
3649 -C @var{callback}] [-c @var{quantum}] [@var{array}]
3651 Read lines from the standard input into array variable @var{array},
3652 or from file descriptor @var{fd}
3653 if the @option{-u} option is supplied.
3654 The variable @code{MAPFILE} is the default @var{array}.
3655 Options, if supplied, have the following meanings:
3659 Copy at most @var{count} lines. If @var{count} is 0, all lines are copied.
3661 Begin assigning to @var{array} at index @var{origin}.
3662 The default index is 0.
3664 Discard the first @var{count} lines read.
3666 Remove a trailing line from each line read.
3668 Read lines from file descriptor @var{fd} instead of the standard input.
3670 Evaluate @var{callback} each time @var{quantum}P lines are read.
3671 The @option{-c} option specifies @var{quantum}.
3673 Specify the number of lines read between each call to @var{callback}.
3676 If @option{-C} is specified without @option{-c},
3677 the default quantum is 5000.
3678 When @var{callback} is evaluated, it is supplied the index of the next
3679 array element to be assigned as an additional argument.
3680 @var{callback} is evaluated after the line is read but before the
3681 array element is assigned.
3683 If not supplied with an explicit origin, @code{mapfile} will clear @var{array}
3684 before assigning to it.
3686 @code{mapfile} returns successfully unless an invalid option or option
3687 argument is supplied, or @var{array} is invalid or unassignable.
3692 printf [-v @var{var}] @var{format} [@var{arguments}]
3694 Write the formatted @var{arguments} to the standard output under the
3695 control of the @var{format}.
3696 The @var{format} is a character string which contains three types of objects:
3697 plain characters, which are simply copied to standard output, character
3698 escape sequences, which are converted and copied to the standard output, and
3699 format specifications, each of which causes printing of the next successive
3701 In addition to the standard @code{printf(1)} formats, @samp{%b} causes
3702 @code{printf} to expand backslash escape sequences in the corresponding
3704 (except that @samp{\c} terminates output, backslashes in
3705 @samp{\'}, @samp{\"}, and @samp{\?} are not removed, and octal escapes
3706 beginning with @samp{\0} may contain up to four digits),
3707 and @samp{%q} causes @code{printf} to output the
3708 corresponding @var{argument} in a format that can be reused as shell input.
3710 The @option{-v} option causes the output to be assigned to the variable
3711 @var{var} rather than being printed to the standard output.
3713 The @var{format} is reused as necessary to consume all of the @var{arguments}.
3714 If the @var{format} requires more @var{arguments} than are supplied, the
3715 extra format specifications behave as if a zero value or null string, as
3716 appropriate, had been supplied. The return value is zero on success,
3717 non-zero on failure.
3722 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{}]
3724 One line is read from the standard input, or from the file descriptor
3725 @var{fd} supplied as an argument to the @option{-u} option, and the first word
3726 is assigned to the first @var{name}, the second word to the second @var{name},
3727 and so on, with leftover words and their intervening separators assigned
3728 to the last @var{name}.
3729 If there are fewer words read from the input stream than names,
3730 the remaining names are assigned empty values.
3731 The characters in the value of the @env{IFS} variable
3732 are used to split the line into words.
3733 The backslash character @samp{\} may be used to remove any special
3734 meaning for the next character read and for line continuation.
3735 If no names are supplied, the line read is assigned to the
3736 variable @env{REPLY}.
3737 The return code is zero, unless end-of-file is encountered, @code{read}
3738 times out (in which case the return code is greater than 128), or an
3739 invalid file descriptor is supplied as the argument to @option{-u}.
3741 Options, if supplied, have the following meanings:
3744 @item -a @var{aname}
3745 The words are assigned to sequential indices of the array variable
3746 @var{aname}, starting at 0.
3747 All elements are removed from @var{aname} before the assignment.
3748 Other @var{name} arguments are ignored.
3750 @item -d @var{delim}
3751 The first character of @var{delim} is used to terminate the input line,
3752 rather than newline.
3755 Readline (@pxref{Command Line Editing}) is used to obtain the line.
3756 Readline uses the current (or default, if line editing was not previously
3757 active) editing settings.
3760 If Readline is being used to read the line, @var{text} is placed into
3761 the editing buffer before editing begins.
3763 @item -n @var{nchars}
3764 @code{read} returns after reading @var{nchars} characters rather than
3765 waiting for a complete line of input, but honor a delimiter if fewer
3766 than @var{nchars} characters are read before the delimiter.
3768 @item -N @var{nchars}
3769 @code{read} returns after reading exactly @var{nchars} characters rather
3770 than waiting for a complete line of input, unless EOF is encountered or
3771 @code{read} times out. Any delimiter is ignored.
3773 @item -p @var{prompt}
3774 Display @var{prompt}, without a trailing newline, before attempting
3776 The prompt is displayed only if input is coming from a terminal.
3779 If this option is given, backslash does not act as an escape character.
3780 The backslash is considered to be part of the line.
3781 In particular, a backslash-newline pair may not be used as a line
3785 Silent mode. If input is coming from a terminal, characters are
3788 @item -t @var{timeout}
3789 Cause @code{read} to time out and return failure if a complete line of
3790 input is not read within @var{timeout} seconds.
3791 @var{timeout} may be a decimal number with a fractional portion following
3793 This option is only effective if @code{read} is reading input from a
3794 terminal, pipe, or other special file; it has no effect when reading
3796 If @var{timeout} is 0, @code{read} returns success if input is available on
3797 the specified file descriptor, failure otherwise.
3798 The exit status is greater than 128 if the timeout is exceeded.
3801 Read input from file descriptor @var{fd}.
3808 readarray [-n @var{count}] [-O @var{origin}] [-s @var{count}] [-t] [-u @var{fd}] [
3809 -C @var{callback}] [-c @var{quantum}] [@var{array}]
3811 Read lines from the standard input into array variable @var{array},
3812 or from file descriptor @var{fd}
3813 if the @option{-u} option is supplied.
3815 A synonym for @code{mapfile}.
3820 source @var{filename}
3822 A synonym for @code{.} (@pxref{Bourne Shell Builtins}).
3827 type [-afptP] [@var{name} @dots{}]
3829 For each @var{name}, indicate how it would be interpreted if used as a
3832 If the @option{-t} option is used, @code{type} prints a single word
3833 which is one of @samp{alias}, @samp{function}, @samp{builtin},
3834 @samp{file} or @samp{keyword},
3835 if @var{name} is an alias, shell function, shell builtin,
3836 disk file, or shell reserved word, respectively.
3837 If the @var{name} is not found, then nothing is printed, and
3838 @code{type} returns a failure status.
3840 If the @option{-p} option is used, @code{type} either returns the name
3841 of the disk file that would be executed, or nothing if @option{-t}
3842 would not return @samp{file}.
3844 The @option{-P} option forces a path search for each @var{name}, even if
3845 @option{-t} would not return @samp{file}.
3847 If a command is hashed, @option{-p} and @option{-P} print the hashed value,
3848 not necessarily the file that appears first in @code{$PATH}.
3850 If the @option{-a} option is used, @code{type} returns all of the places
3851 that contain an executable named @var{file}.
3852 This includes aliases and functions, if and only if the @option{-p} option
3855 If the @option{-f} option is used, @code{type} does not attempt to find
3856 shell functions, as with the @code{command} builtin.
3858 The return status is zero if all of the @var{names} are found, non-zero
3859 if any are not found.
3864 typeset [-afFrxi] [-p] [@var{name}[=@var{value}] @dots{}]
3866 The @code{typeset} command is supplied for compatibility with the Korn
3867 shell; however, it has been deprecated in favor of the @code{declare}
3873 ulimit [-abcdefilmnpqrstuvxHST] [@var{limit}]
3875 @code{ulimit} provides control over the resources available to processes
3876 started by the shell, on systems that allow such control. If an
3877 option is given, it is interpreted as follows:
3880 Change and report the soft limit associated with a resource.
3883 Change and report the hard limit associated with a resource.
3886 All current limits are reported.
3889 The maximum socket buffer size.
3892 The maximum size of core files created.
3895 The maximum size of a process's data segment.
3898 The maximum scheduling priority ("nice").
3901 The maximum size of files written by the shell and its children.
3904 The maximum number of pending signals.
3907 The maximum size that may be locked into memory.
3910 The maximum resident set size (many systems do not honor this limit).
3913 The maximum number of open file descriptors (most systems do not
3914 allow this value to be set).
3917 The pipe buffer size.
3920 The maximum number of bytes in POSIX message queues.
3923 The maximum real-time scheduling priority.
3926 The maximum stack size.
3929 The maximum amount of cpu time in seconds.
3932 The maximum number of processes available to a single user.
3935 The maximum amount of virtual memory available to the process.
3938 The maximum number of file locks.
3941 The maximum number of threads.
3945 If @var{limit} is given, it is the new value of the specified resource;
3946 the special @var{limit} values @code{hard}, @code{soft}, and
3947 @code{unlimited} stand for the current hard limit, the current soft limit,
3948 and no limit, respectively.
3949 A hard limit cannot be increased by a non-root user once it is set;
3950 a soft limit may be increased up to the value of the hard limit.
3951 Otherwise, the current value of the soft limit for the specified resource
3952 is printed, unless the @option{-H} option is supplied.
3953 When setting new limits, if neither @option{-H} nor @option{-S} is supplied,
3954 both the hard and soft limits are set.
3955 If no option is given, then @option{-f} is assumed. Values are in 1024-byte
3956 increments, except for @option{-t}, which is in seconds, @option{-p},
3957 which is in units of 512-byte blocks, and @option{-n} and @option{-u}, which
3958 are unscaled values.
3960 The return status is zero unless an invalid option or argument is supplied,
3961 or an error occurs while setting a new limit.
3966 unalias [-a] [@var{name} @dots{} ]
3969 Remove each @var{name} from the list of aliases. If @option{-a} is
3970 supplied, all aliases are removed.
3971 Aliases are described in @ref{Aliases}.
3975 @node Modifying Shell Behavior
3976 @section Modifying Shell Behavior
3979 * The Set Builtin:: Change the values of shell attributes and
3980 positional parameters.
3981 * The Shopt Builtin:: Modify shell optional behavior.
3984 @node The Set Builtin
3985 @subsection The Set Builtin
3987 This builtin is so complicated that it deserves its own section. @code{set}
3988 allows you to change the values of shell options and set the positional
3989 parameters, or to display the names and values of shell variables.
3995 set [--abefhkmnptuvxBCEHPT] [-o @var{option}] [@var{argument} @dots{}]
3996 set [+abefhkmnptuvxBCEHPT] [+o @var{option}] [@var{argument} @dots{}]
3999 If no options or arguments are supplied, @code{set} displays the names
4000 and values of all shell variables and functions, sorted according to the
4001 current locale, in a format that may be reused as input
4002 for setting or resetting the currently-set variables.
4003 Read-only variables cannot be reset.
4004 In @sc{posix} mode, only shell variables are listed.
4006 When options are supplied, they set or unset shell attributes.
4007 Options, if specified, have the following meanings:
4011 Mark variables and function which are modified or created for export
4012 to the environment of subsequent commands.
4015 Cause the status of terminated background jobs to be reported
4016 immediately, rather than before printing the next primary prompt.
4019 Exit immediately if a pipeline (@pxref{Pipelines}), which may consist
4020 of a single simple command (@pxref{Simple Commands}),
4021 a subshell command enclosed in parentheses (@pxref{Command Grouping}),
4022 or one of the commands executed as part of a command list enclosed
4023 by braces (@pxref{Command Grouping})
4024 returns a non-zero status.
4025 The shell does not exit if the command that fails is part of the
4026 command list immediately following a @code{while} or @code{until} keyword,
4027 part of the test in an @code{if} statement,
4028 part of any command executed in a @code{&&} or @code{||} list except
4029 the command following the final @code{&&} or @code{||},
4030 any command in a pipeline but the last,
4031 or if the command's return status is being inverted with @code{!}.
4032 A trap on @code{ERR}, if set, is executed before the shell exits.
4034 This option applies to the shell environment and each subshell environment
4035 separately (@pxref{Command Execution Environment}), and may cause
4036 subshells to exit before executing all the commands in the subshell.
4039 Disable filename expansion (globbing).
4042 Locate and remember (hash) commands as they are looked up for execution.
4043 This option is enabled by default.
4046 All arguments in the form of assignment statements are placed
4047 in the environment for a command, not just those that precede
4051 Job control is enabled (@pxref{Job Control}).
4054 Read commands but do not execute them; this may be used to check a
4055 script for syntax errors.
4056 This option is ignored by interactive shells.
4058 @item -o @var{option-name}
4060 Set the option corresponding to @var{option-name}:
4070 Use an @code{emacs}-style line editing interface (@pxref{Command Line Editing}).
4071 This also affects the editing interface used for @code{read -e}.
4089 Enable command history, as described in @ref{Bash History Facilities}.
4090 This option is on by default in interactive shells.
4093 An interactive shell will not exit upon reading EOF.
4126 If set, the return value of a pipeline is the value of the last
4127 (rightmost) command to exit with a non-zero status, or zero if all
4128 commands in the pipeline exit successfully.
4129 This option is disabled by default.
4132 Change the behavior of Bash where the default operation differs
4133 from the @sc{posix} standard to match the standard
4134 (@pxref{Bash POSIX Mode}).
4135 This is intended to make Bash behave as a strict superset of that
4145 Use a @code{vi}-style line editing interface.
4146 This also affects the editing interface used for @code{read -e}.
4153 Turn on privileged mode.
4154 In this mode, the @env{$BASH_ENV} and @env{$ENV} files are not
4155 processed, shell functions are not inherited from the environment,
4156 and the @env{SHELLOPTS}, @env{BASHOPTS}, @env{CDPATH} and @env{GLOBIGNORE}
4157 variables, if they appear in the environment, are ignored.
4158 If the shell is started with the effective user (group) id not equal to the
4159 real user (group) id, and the @code{-p} option is not supplied, these actions
4160 are taken and the effective user id is set to the real user id.
4161 If the @code{-p} option is supplied at startup, the effective user id is
4163 Turning this option off causes the effective user
4164 and group ids to be set to the real user and group ids.
4167 Exit after reading and executing one command.
4170 Treat unset variables and parameters other than the special parameters
4171 @samp{@@} or @samp{*} as an error when performing parameter expansion.
4172 An error message will be written to the standard error, and a non-interactive
4176 Print shell input lines as they are read.
4179 Print a trace of simple commands, @code{for} commands, @code{case}
4180 commands, @code{select} commands, and arithmetic @code{for} commands
4181 and their arguments or associated word lists after they are
4182 expanded and before they are executed. The value of the @env{PS4}
4183 variable is expanded and the resultant value is printed before
4184 the command and its expanded arguments.
4187 The shell will perform brace expansion (@pxref{Brace Expansion}).
4188 This option is on by default.
4191 Prevent output redirection using @samp{>}, @samp{>&}, and @samp{<>}
4192 from overwriting existing files.
4195 If set, any trap on @code{ERR} is inherited by shell functions, command
4196 substitutions, and commands executed in a subshell environment.
4197 The @code{ERR} trap is normally not inherited in such cases.
4200 Enable @samp{!} style history substitution (@pxref{History Interaction}).
4201 This option is on by default for interactive shells.
4204 If set, do not follow symbolic links when performing commands such as
4205 @code{cd} which change the current directory. The physical directory
4206 is used instead. By default, Bash follows
4207 the logical chain of directories when performing commands
4208 which change the current directory.
4210 For example, if @file{/usr/sys} is a symbolic link to @file{/usr/local/sys}
4213 $ cd /usr/sys; echo $PWD
4220 If @code{set -P} is on, then:
4222 $ cd /usr/sys; echo $PWD
4229 If set, any trap on @code{DEBUG} and @code{RETURN} are inherited by
4230 shell functions, command substitutions, and commands executed
4231 in a subshell environment.
4232 The @code{DEBUG} and @code{RETURN} traps are normally not inherited
4236 If no arguments follow this option, then the positional parameters are
4237 unset. Otherwise, the positional parameters are set to the
4238 @var{arguments}, even if some of them begin with a @samp{-}.
4241 Signal the end of options, cause all remaining @var{arguments}
4242 to be assigned to the positional parameters. The @option{-x}
4243 and @option{-v} options are turned off.
4244 If there are no arguments, the positional parameters remain unchanged.
4247 Using @samp{+} rather than @samp{-} causes these options to be
4248 turned off. The options can also be used upon invocation of the
4249 shell. The current set of options may be found in @code{$-}.
4251 The remaining N @var{arguments} are positional parameters and are
4252 assigned, in order, to @code{$1}, @code{$2}, @dots{} @code{$N}.
4253 The special parameter @code{#} is set to N.
4255 The return status is always zero unless an invalid option is supplied.
4258 @node The Shopt Builtin
4259 @subsection The Shopt Builtin
4261 This builtin allows you to change additional shell optional behavior.
4268 shopt [-pqsu] [-o] [@var{optname} @dots{}]
4270 Toggle the values of variables controlling optional shell behavior.
4271 With no options, or with the @option{-p} option, a list of all settable
4272 options is displayed, with an indication of whether or not each is set.
4273 The @option{-p} option causes output to be displayed in a form that
4274 may be reused as input.
4275 Other options have the following meanings:
4279 Enable (set) each @var{optname}.
4282 Disable (unset) each @var{optname}.
4285 Suppresses normal output; the return status
4286 indicates whether the @var{optname} is set or unset.
4287 If multiple @var{optname} arguments are given with @option{-q},
4288 the return status is zero if all @var{optnames} are enabled;
4292 Restricts the values of
4293 @var{optname} to be those defined for the @option{-o} option to the
4294 @code{set} builtin (@pxref{The Set Builtin}).
4297 If either @option{-s} or @option{-u}
4298 is used with no @var{optname} arguments, the display is limited to
4299 those options which are set or unset, respectively.
4301 Unless otherwise noted, the @code{shopt} options are disabled (off)
4304 The return status when listing options is zero if all @var{optnames}
4305 are enabled, non-zero otherwise. When setting or unsetting options,
4306 the return status is zero unless an @var{optname} is not a valid shell
4309 The list of @code{shopt} options is:
4313 If set, a command name that is the name of a directory is executed as if
4314 it were the argument to the @code{cd} command.
4315 This option is only used by interactive shells.
4318 If this is set, an argument to the @code{cd} builtin command that
4319 is not a directory is assumed to be the name of a variable whose
4320 value is the directory to change to.
4323 If set, minor errors in the spelling of a directory component in a
4324 @code{cd} command will be corrected.
4325 The errors checked for are transposed characters,
4326 a missing character, and a character too many.
4327 If a correction is found, the corrected path is printed,
4328 and the command proceeds.
4329 This option is only used by interactive shells.
4332 If this is set, Bash checks that a command found in the hash
4333 table exists before trying to execute it. If a hashed command no
4334 longer exists, a normal path search is performed.
4337 If set, Bash lists the status of any stopped and running jobs before
4338 exiting an interactive shell. If any jobs are running, this causes
4339 the exit to be deferred until a second exit is attempted without an
4340 intervening command (@pxref{Job Control}).
4341 The shell always postpones exiting if any jobs are stopped.
4344 If set, Bash checks the window size after each command
4345 and, if necessary, updates the values of
4346 @env{LINES} and @env{COLUMNS}.
4350 attempts to save all lines of a multiple-line
4351 command in the same history entry. This allows
4352 easy re-editing of multi-line commands.
4356 changes its behavior to that of version 3.1 with respect to quoted
4357 arguments to the conditional command's =~ operator.
4361 attempts spelling correction on directory names during word completion
4362 if the directory name initially supplied does not exist.
4365 If set, Bash includes filenames beginning with a `.' in
4366 the results of filename expansion.
4369 If this is set, a non-interactive shell will not exit if
4370 it cannot execute the file specified as an argument to the @code{exec}
4371 builtin command. An interactive shell does not exit if @code{exec}
4374 @item expand_aliases
4375 If set, aliases are expanded as described below under Aliases,
4377 This option is enabled by default for interactive shells.
4380 If set, behavior intended for use by debuggers is enabled:
4384 The @option{-F} option to the @code{declare} builtin (@pxref{Bash Builtins})
4385 displays the source file name and line number corresponding to each function
4386 name supplied as an argument.
4389 If the command run by the @code{DEBUG} trap returns a non-zero value, the
4390 next command is skipped and not executed.
4393 If the command run by the @code{DEBUG} trap returns a value of 2, and the
4394 shell is executing in a subroutine (a shell function or a shell script
4395 executed by the @code{.} or @code{source} builtins), a call to
4396 @code{return} is simulated.
4399 @code{BASH_ARGC} and @code{BASH_ARGV} are updated as described in their
4400 descriptions (@pxref{Bash Variables}).
4403 Function tracing is enabled: command substitution, shell functions, and
4404 subshells invoked with @code{( @var{command} )} inherit the
4405 @code{DEBUG} and @code{RETURN} traps.
4408 Error tracing is enabled: command substitution, shell functions, and
4409 subshells invoked with @code{( @var{command} )} inherit the
4414 If set, the extended pattern matching features described above
4415 (@pxref{Pattern Matching}) are enabled.
4418 If set, @code{$'@var{string}'} and @code{$"@var{string}"} quoting is
4419 performed within @code{$@{@var{parameter}@}} expansions
4420 enclosed in double quotes. This option is enabled by default.
4423 If set, patterns which fail to match filenames during filename expansion
4424 result in an expansion error.
4427 If set, the suffixes specified by the @env{FIGNORE} shell variable
4428 cause words to be ignored when performing word completion even if
4429 the ignored words are the only possible completions.
4430 @xref{Bash Variables}, for a description of @env{FIGNORE}.
4431 This option is enabled by default.
4434 If set, the pattern @samp{**} used in a filename expansion context will
4435 match a files and zero or more directories and subdirectories.
4436 If the pattern is followed by a @samp{/}, only directories and
4437 subdirectories match.
4440 If set, shell error messages are written in the standard @sc{gnu} error
4444 If set, the history list is appended to the file named by the value
4445 of the @env{HISTFILE}
4446 variable when the shell exits, rather than overwriting the file.
4449 If set, and Readline
4450 is being used, a user is given the opportunity to re-edit a
4451 failed history substitution.
4454 If set, and Readline
4455 is being used, the results of history substitution are not immediately
4456 passed to the shell parser. Instead, the resulting line is loaded into
4457 the Readline editing buffer, allowing further modification.
4460 If set, and Readline is being used, Bash will attempt to perform
4461 hostname completion when a word containing a @samp{@@} is being
4462 completed (@pxref{Commands For Completion}). This option is enabled
4466 If set, Bash will send @code{SIGHUP} to all jobs when an interactive
4467 login shell exits (@pxref{Signals}).
4469 @item interactive_comments
4470 Allow a word beginning with @samp{#}
4471 to cause that word and all remaining characters on that
4472 line to be ignored in an interactive shell.
4473 This option is enabled by default.
4476 If enabled, and the @code{cmdhist}
4477 option is enabled, multi-line commands are saved to the history with
4478 embedded newlines rather than using semicolon separators where possible.
4481 The shell sets this option if it is started as a login shell
4482 (@pxref{Invoking Bash}).
4483 The value may not be changed.
4486 If set, and a file that Bash is checking for mail has been
4487 accessed since the last time it was checked, the message
4488 @code{"The mail in @var{mailfile} has been read"} is displayed.
4490 @item no_empty_cmd_completion
4491 If set, and Readline is being used, Bash will not attempt to search
4492 the @env{PATH} for possible completions when completion is attempted
4496 If set, Bash matches filenames in a case-insensitive fashion when
4497 performing filename expansion.
4500 If set, Bash matches patterns in a case-insensitive fashion when
4501 performing matching while executing @code{case} or @code{[[}
4502 conditional commands.
4505 If set, Bash allows filename patterns which match no
4506 files to expand to a null string, rather than themselves.
4509 If set, the programmable completion facilities
4510 (@pxref{Programmable Completion}) are enabled.
4511 This option is enabled by default.
4514 If set, prompt strings undergo
4515 parameter expansion, command substitution, arithmetic
4516 expansion, and quote removal after being expanded
4517 as described below (@pxref{Printing a Prompt}).
4518 This option is enabled by default.
4520 @item restricted_shell
4521 The shell sets this option if it is started in restricted mode
4522 (@pxref{The Restricted Shell}).
4523 The value may not be changed.
4524 This is not reset when the startup files are executed, allowing
4525 the startup files to discover whether or not a shell is restricted.
4528 If this is set, the @code{shift}
4529 builtin prints an error message when the shift count exceeds the
4530 number of positional parameters.
4533 If set, the @code{source} builtin uses the value of @env{PATH}
4534 to find the directory containing the file supplied as an argument.
4535 This option is enabled by default.
4538 If set, the @code{echo} builtin expands backslash-escape sequences
4544 The return status when listing options is zero if all @var{optnames}
4545 are enabled, non-zero otherwise.
4546 When setting or unsetting options, the return status is zero unless an
4547 @var{optname} is not a valid shell option.
4551 @node Special Builtins
4552 @section Special Builtins
4553 @cindex special builtin
4555 For historical reasons, the @sc{posix} standard has classified
4556 several builtin commands as @emph{special}.
4557 When Bash is executing in @sc{posix} mode, the special builtins
4558 differ from other builtin commands in three respects:
4562 Special builtins are found before shell functions during command lookup.
4565 If a special builtin returns an error status, a non-interactive shell exits.
4568 Assignment statements preceding the command stay in effect in the shell
4569 environment after the command completes.
4572 When Bash is not executing in @sc{posix} mode, these builtins behave no
4573 differently than the rest of the Bash builtin commands.
4574 The Bash @sc{posix} mode is described in @ref{Bash POSIX Mode}.
4576 These are the @sc{posix} special builtins:
4578 @w{break : . continue eval exec exit export readonly return set}
4579 @w{shift trap unset}
4582 @node Shell Variables
4583 @chapter Shell Variables
4586 * Bourne Shell Variables:: Variables which Bash uses in the same way
4587 as the Bourne Shell.
4588 * Bash Variables:: List of variables that exist in Bash.
4591 This chapter describes the shell variables that Bash uses.
4592 Bash automatically assigns default values to a number of variables.
4594 @node Bourne Shell Variables
4595 @section Bourne Shell Variables
4597 Bash uses certain shell variables in the same way as the Bourne shell.
4598 In some cases, Bash assigns a default value to the variable.
4603 A colon-separated list of directories used as a search path for
4604 the @code{cd} builtin command.
4607 The current user's home directory; the default for the @code{cd} builtin
4609 The value of this variable is also used by tilde expansion
4610 (@pxref{Tilde Expansion}).
4613 A list of characters that separate fields; used when the shell splits
4614 words as part of expansion.
4617 If this parameter is set to a filename and the @env{MAILPATH} variable
4618 is not set, Bash informs the user of the arrival of mail in
4622 A colon-separated list of filenames which the shell periodically checks
4624 Each list entry can specify the message that is printed when new mail
4625 arrives in the mail file by separating the file name from the message with
4627 When used in the text of the message, @code{$_} expands to the name of
4628 the current mail file.
4631 The value of the last option argument processed by the @code{getopts} builtin.
4634 The index of the last option argument processed by the @code{getopts} builtin.
4637 A colon-separated list of directories in which the shell looks for
4639 A zero-length (null) directory name in the value of @code{PATH} indicates the
4641 A null directory name may appear as two adjacent colons, or as an initial
4646 The primary prompt string. The default value is @samp{\s-\v\$ }.
4647 @xref{Printing a Prompt}, for the complete list of escape
4648 sequences that are expanded before @env{PS1} is displayed.
4651 The secondary prompt string. The default value is @samp{> }.
4655 @node Bash Variables
4656 @section Bash Variables
4658 These variables are set or used by Bash, but other shells
4659 do not normally treat them specially.
4661 A few variables used by Bash are described in different chapters:
4662 variables for controlling the job control facilities
4663 (@pxref{Job Control Variables}).
4668 The full pathname used to execute the current instance of Bash.
4671 A colon-separated list of enabled shell options. Each word in
4672 the list is a valid argument for the @option{-s} option to the
4673 @code{shopt} builtin command (@pxref{The Shopt Builtin}).
4674 The options appearing in @env{BASHOPTS} are those reported
4675 as @samp{on} by @samp{shopt}.
4676 If this variable is in the environment when Bash
4677 starts up, each shell option in the list will be enabled before
4678 reading any startup files. This variable is readonly.
4681 Expands to the process id of the current Bash process.
4682 This differs from @code{$$} under certain circumstances, such as subshells
4683 that do not require Bash to be re-initialized.
4686 An associative array variable whose members correspond to the internal
4687 list of aliases as maintained by the @code{alias} builtin
4688 (@pxref{Bourne Shell Builtins}).
4689 Elements added to this array appear in the alias list; unsetting array
4690 elements cause aliases to be removed from the alias list.
4693 An array variable whose values are the number of parameters in each
4694 frame of the current bash execution call stack. The number of
4695 parameters to the current subroutine (shell function or script executed
4696 with @code{.} or @code{source}) is at the top of the stack. When a
4697 subroutine is executed, the number of parameters passed is pushed onto
4699 The shell sets @code{BASH_ARGC} only when in extended debugging mode
4700 (see @ref{The Shopt Builtin}
4701 for a description of the @code{extdebug} option to the @code{shopt}
4705 An array variable containing all of the parameters in the current bash
4706 execution call stack. The final parameter of the last subroutine call
4707 is at the top of the stack; the first parameter of the initial call is
4708 at the bottom. When a subroutine is executed, the parameters supplied
4709 are pushed onto @code{BASH_ARGV}.
4710 The shell sets @code{BASH_ARGV} only when in extended debugging mode
4711 (see @ref{The Shopt Builtin}
4712 for a description of the @code{extdebug} option to the @code{shopt}
4716 An associative array variable whose members correspond to the internal
4717 hash table of commands as maintained by the @code{hash} builtin
4718 (@pxref{Bourne Shell Builtins}).
4719 Elements added to this array appear in the hash table; unsetting array
4720 elements cause commands to be removed from the hash table.
4723 The command currently being executed or about to be executed, unless the
4724 shell is executing a command as the result of a trap,
4725 in which case it is the command executing at the time of the trap.
4728 If this variable is set when Bash is invoked to execute a shell
4729 script, its value is expanded and used as the name of a startup file
4730 to read before executing the script. @xref{Bash Startup Files}.
4732 @item BASH_EXECUTION_STRING
4733 The command argument to the @option{-c} invocation option.
4736 An array variable whose members are the line numbers in source files
4737 corresponding to each member of @var{FUNCNAME}.
4738 @code{$@{BASH_LINENO[$i]@}} is the line number in the source file where
4739 @code{$@{FUNCNAME[$i]@}} was called (or @code{$@{BASH_LINENO[$i-1]@}} if
4740 referenced within another shell function).
4741 The corresponding source file name is @code{$@{BASH_SOURCE[$i]@}}.
4742 Use @code{LINENO} to obtain the current line number.
4745 An array variable whose members are assigned by the @samp{=~} binary
4746 operator to the @code{[[} conditional command
4747 (@pxref{Conditional Constructs}).
4748 The element with index 0 is the portion of the string
4749 matching the entire regular expression.
4750 The element with index @var{n} is the portion of the
4751 string matching the @var{n}th parenthesized subexpression.
4752 This variable is read-only.
4755 An array variable whose members are the source filenames corresponding
4756 to the elements in the @code{FUNCNAME} array variable.
4759 Incremented by one each time a subshell or subshell environment is spawned.
4760 The initial value is 0.
4763 A readonly array variable (@pxref{Arrays})
4764 whose members hold version information for this instance of Bash.
4765 The values assigned to the array members are as follows:
4769 @item BASH_VERSINFO[0]
4770 The major version number (the @var{release}).
4772 @item BASH_VERSINFO[1]
4773 The minor version number (the @var{version}).
4775 @item BASH_VERSINFO[2]
4778 @item BASH_VERSINFO[3]
4781 @item BASH_VERSINFO[4]
4782 The release status (e.g., @var{beta1}).
4784 @item BASH_VERSINFO[5]
4785 The value of @env{MACHTYPE}.
4790 The version number of the current instance of Bash.
4793 If set to an integer corresponding to a valid file descriptor, Bash
4794 will write the trace output generated when @samp{set -x}
4795 is enabled to that file descriptor.
4796 This allows tracing output to be separated from diagnostic and error
4798 The file descriptor is closed when @code{BASH_XTRACEFD} is unset or assigned
4800 Unsetting @code{BASH_XTRACEFD} or assigning it the empty string causes the
4801 trace output to be sent to the standard error.
4802 Note that setting @code{BASH_XTRACEFD} to 2 (the standard error file
4803 descriptor) and then unsetting it will result in the standard error
4807 Used by the @code{select} builtin command to determine the terminal width
4808 when printing selection lists. Automatically set upon receipt of a
4812 An index into @env{$@{COMP_WORDS@}} of the word containing the current
4814 This variable is available only in shell functions invoked by the
4815 programmable completion facilities (@pxref{Programmable Completion}).
4818 The current command line.
4819 This variable is available only in shell functions and external
4820 commands invoked by the
4821 programmable completion facilities (@pxref{Programmable Completion}).
4824 The index of the current cursor position relative to the beginning of
4825 the current command.
4826 If the current cursor position is at the end of the current command,
4827 the value of this variable is equal to @code{$@{#COMP_LINE@}}.
4828 This variable is available only in shell functions and external
4829 commands invoked by the
4830 programmable completion facilities (@pxref{Programmable Completion}).
4833 Set to an integer value corresponding to the type of completion attempted
4834 that caused a completion function to be called:
4835 @var{TAB}, for normal completion,
4836 @samp{?}, for listing completions after successive tabs,
4837 @samp{!}, for listing alternatives on partial word completion,
4838 @samp{@@}, to list completions if the word is not unmodified,
4840 @samp{%}, for menu completion.
4841 This variable is available only in shell functions and external
4842 commands invoked by the
4843 programmable completion facilities (@pxref{Programmable Completion}).
4846 The key (or final key of a key sequence) used to invoke the current
4847 completion function.
4849 @item COMP_WORDBREAKS
4850 The set of characters that the Readline library treats as word
4851 separators when performing word completion.
4852 If @code{COMP_WORDBREAKS} is unset, it loses its special properties,
4853 even if it is subsequently reset.
4856 An array variable consisting of the individual
4857 words in the current command line.
4858 The line is split into words as Readline would split it, using
4859 @code{COMP_WORDBREAKS} as described above.
4860 This variable is available only in shell functions invoked by the
4861 programmable completion facilities (@pxref{Programmable Completion}).
4864 An array variable from which Bash reads the possible completions
4865 generated by a shell function invoked by the programmable completion
4866 facility (@pxref{Programmable Completion}).
4869 An array variable containing the current contents of the directory stack.
4870 Directories appear in the stack in the order they are displayed by the
4871 @code{dirs} builtin.
4872 Assigning to members of this array variable may be used to modify
4873 directories already in the stack, but the @code{pushd} and @code{popd}
4874 builtins must be used to add and remove directories.
4875 Assignment to this variable will not change the current directory.
4876 If @env{DIRSTACK} is unset, it loses its special properties, even if
4877 it is subsequently reset.
4880 If Bash finds this variable in the environment when the shell
4881 starts with value @samp{t}, it assumes that the shell is running in an
4882 emacs shell buffer and disables line editing.
4885 The numeric effective user id of the current user. This variable
4889 The editor used as a default by the @option{-e} option to the @code{fc}
4893 A colon-separated list of suffixes to ignore when performing
4894 filename completion.
4895 A file name whose suffix matches one of the entries in
4897 is excluded from the list of matched file names. A sample
4898 value is @samp{.o:~}
4901 An array variable containing the names of all shell functions
4902 currently in the execution call stack.
4903 The element with index 0 is the name of any currently-executing
4905 The bottom-most element is @code{"main"}.
4906 This variable exists only when a shell function is executing.
4907 Assignments to @env{FUNCNAME} have no effect and return an error status.
4908 If @env{FUNCNAME} is unset, it loses its special properties, even if
4909 it is subsequently reset.
4912 A colon-separated list of patterns defining the set of filenames to
4913 be ignored by filename expansion.
4914 If a filename matched by a filename expansion pattern also matches one
4915 of the patterns in @env{GLOBIGNORE}, it is removed from the list
4919 An array variable containing the list of groups of which the current
4921 Assignments to @env{GROUPS} have no effect and return an error status.
4922 If @env{GROUPS} is unset, it loses its special properties, even if it is
4926 Up to three characters which control history expansion, quick
4927 substitution, and tokenization (@pxref{History Interaction}).
4928 The first character is the
4929 @var{history expansion} character, that is, the character which signifies the
4930 start of a history expansion, normally @samp{!}. The second character is the
4931 character which signifies `quick substitution' when seen as the first
4932 character on a line, normally @samp{^}. The optional third character is the
4933 character which indicates that the remainder of the line is a comment when
4934 found as the first character of a word, usually @samp{#}. The history
4935 comment character causes history substitution to be skipped for the
4936 remaining words on the line. It does not necessarily cause the shell
4937 parser to treat the rest of the line as a comment.
4940 The history number, or index in the history list, of the current
4941 command. If @env{HISTCMD} is unset, it loses its special properties,
4942 even if it is subsequently reset.
4945 A colon-separated list of values controlling how commands are saved on
4947 If the list of values includes @samp{ignorespace}, lines which begin
4948 with a space character are not saved in the history list.
4949 A value of @samp{ignoredups} causes lines which match the previous
4950 history entry to not be saved.
4951 A value of @samp{ignoreboth} is shorthand for
4952 @samp{ignorespace} and @samp{ignoredups}.
4953 A value of @samp{erasedups} causes all previous lines matching the
4954 current line to be removed from the history list before that line
4956 Any value not in the above list is ignored.
4957 If @env{HISTCONTROL} is unset, or does not include a valid value,
4958 all lines read by the shell parser are saved on the history list,
4959 subject to the value of @env{HISTIGNORE}.
4960 The second and subsequent lines of a multi-line compound command are
4961 not tested, and are added to the history regardless of the value of
4965 The name of the file to which the command history is saved. The
4966 default value is @file{~/.bash_history}.
4969 The maximum number of lines contained in the history file. When this
4970 variable is assigned a value, the history file is truncated, if
4971 necessary, by removing the oldest entries,
4972 to contain no more than that number of lines.
4973 The history file is also truncated to this size after
4974 writing it when an interactive shell exits.
4975 The default value is 500.
4978 A colon-separated list of patterns used to decide which command
4979 lines should be saved on the history list. Each pattern is
4980 anchored at the beginning of the line and must match the complete
4981 line (no implicit @samp{*} is appended). Each pattern is tested
4982 against the line after the checks specified by @env{HISTCONTROL}
4983 are applied. In addition to the normal shell pattern matching
4984 characters, @samp{&} matches the previous history line. @samp{&}
4985 may be escaped using a backslash; the backslash is removed
4986 before attempting a match.
4987 The second and subsequent lines of a multi-line compound command are
4988 not tested, and are added to the history regardless of the value of
4991 @env{HISTIGNORE} subsumes the function of @env{HISTCONTROL}. A
4992 pattern of @samp{&} is identical to @code{ignoredups}, and a
4993 pattern of @samp{[ ]*} is identical to @code{ignorespace}.
4994 Combining these two patterns, separating them with a colon,
4995 provides the functionality of @code{ignoreboth}.
4998 The maximum number of commands to remember on the history list.
4999 The default value is 500.
5001 @item HISTTIMEFORMAT
5002 If this variable is set and not null, its value is used as a format string
5003 for @var{strftime} to print the time stamp associated with each history
5004 entry displayed by the @code{history} builtin.
5005 If this variable is set, time stamps are written to the history file so
5006 they may be preserved across shell sessions.
5007 This uses the history comment character to distinguish timestamps from
5008 other history lines.
5011 Contains the name of a file in the same format as @file{/etc/hosts} that
5012 should be read when the shell needs to complete a hostname.
5013 The list of possible hostname completions may be changed while the shell
5015 the next time hostname completion is attempted after the
5016 value is changed, Bash adds the contents of the new file to the
5018 If @env{HOSTFILE} is set, but has no value, or does not name a readable file,
5019 Bash attempts to read
5020 @file{/etc/hosts} to obtain the list of possible hostname completions.
5021 When @env{HOSTFILE} is unset, the hostname list is cleared.
5024 The name of the current host.
5027 A string describing the machine Bash is running on.
5030 Controls the action of the shell on receipt of an @code{EOF} character
5031 as the sole input. If set, the value denotes the number
5032 of consecutive @code{EOF} characters that can be read as the
5033 first character on an input line
5034 before the shell will exit. If the variable exists but does not
5035 have a numeric value (or has no value) then the default is 10.
5036 If the variable does not exist, then @code{EOF} signifies the end of
5037 input to the shell. This is only in effect for interactive shells.
5040 The name of the Readline initialization file, overriding the default
5041 of @file{~/.inputrc}.
5044 Used to determine the locale category for any category not specifically
5045 selected with a variable starting with @code{LC_}.
5048 This variable overrides the value of @env{LANG} and any other
5049 @code{LC_} variable specifying a locale category.
5052 This variable determines the collation order used when sorting the
5053 results of filename expansion, and
5054 determines the behavior of range expressions, equivalence classes,
5055 and collating sequences within filename expansion and pattern matching
5056 (@pxref{Filename Expansion}).
5059 This variable determines the interpretation of characters and the
5060 behavior of character classes within filename expansion and pattern
5061 matching (@pxref{Filename Expansion}).
5064 This variable determines the locale used to translate double-quoted
5065 strings preceded by a @samp{$} (@pxref{Locale Translation}).
5068 This variable determines the locale category used for number formatting.
5071 The line number in the script or shell function currently executing.
5074 Used by the @code{select} builtin command to determine the column length
5075 for printing selection lists. Automatically set upon receipt of a
5079 A string that fully describes the system type on which Bash
5080 is executing, in the standard @sc{gnu} @var{cpu-company-system} format.
5083 How often (in seconds) that the shell should check for mail in the
5084 files specified in the @env{MAILPATH} or @env{MAIL} variables.
5085 The default is 60 seconds. When it is time to check
5086 for mail, the shell does so before displaying the primary prompt.
5087 If this variable is unset, or set to a value that is not a number
5088 greater than or equal to zero, the shell disables mail checking.
5091 The previous working directory as set by the @code{cd} builtin.
5094 If set to the value 1, Bash displays error messages
5095 generated by the @code{getopts} builtin command.
5098 A string describing the operating system Bash is running on.
5101 An array variable (@pxref{Arrays})
5102 containing a list of exit status values from the processes
5103 in the most-recently-executed foreground pipeline (which may
5104 contain only a single command).
5106 @item POSIXLY_CORRECT
5107 If this variable is in the environment when @code{bash} starts, the shell
5108 enters @sc{posix} mode (@pxref{Bash POSIX Mode}) before reading the
5109 startup files, as if the @option{--posix} invocation option had been supplied.
5110 If it is set while the shell is running, @code{bash} enables @sc{posix} mode,
5119 The process @sc{id} of the shell's parent process. This variable
5122 @item PROMPT_COMMAND
5123 If set, the value is interpreted as a command to execute
5124 before the printing of each primary prompt (@env{$PS1}).
5126 @item PROMPT_DIRTRIM
5127 If set to a number greater than zero, the value is used as the number of
5128 trailing directory components to retain when expanding the @code{\w} and
5129 @code{\W} prompt string escapes (@pxref{Printing a Prompt}).
5130 Characters removed are replaced with an ellipsis.
5133 The value of this variable is used as the prompt for the
5134 @code{select} command. If this variable is not set, the
5135 @code{select} command prompts with @samp{#? }
5138 The value is the prompt printed before the command line is echoed
5139 when the @option{-x} option is set (@pxref{The Set Builtin}).
5140 The first character of @env{PS4} is replicated multiple times, as
5141 necessary, to indicate multiple levels of indirection.
5142 The default is @samp{+ }.
5145 The current working directory as set by the @code{cd} builtin.
5148 Each time this parameter is referenced, a random integer
5149 between 0 and 32767 is generated. Assigning a value to this
5150 variable seeds the random number generator.
5153 The default variable for the @code{read} builtin.
5156 This variable expands to the number of seconds since the
5157 shell was started. Assignment to this variable resets
5158 the count to the value assigned, and the expanded value
5159 becomes the value assigned plus the number of seconds
5160 since the assignment.
5163 The full pathname to the shell is kept in this environment variable.
5164 If it is not set when the shell starts,
5165 Bash assigns to it the full pathname of the current user's login shell.
5168 A colon-separated list of enabled shell options. Each word in
5169 the list is a valid argument for the @option{-o} option to the
5170 @code{set} builtin command (@pxref{The Set Builtin}).
5171 The options appearing in @env{SHELLOPTS} are those reported
5172 as @samp{on} by @samp{set -o}.
5173 If this variable is in the environment when Bash
5174 starts up, each shell option in the list will be enabled before
5175 reading any startup files. This variable is readonly.
5178 Incremented by one each time a new instance of Bash is started. This is
5179 intended to be a count of how deeply your Bash shells are nested.
5182 The value of this parameter is used as a format string specifying
5183 how the timing information for pipelines prefixed with the @code{time}
5184 reserved word should be displayed.
5185 The @samp{%} character introduces an
5186 escape sequence that is expanded to a time value or other
5188 The escape sequences and their meanings are as
5189 follows; the braces denote optional portions.
5196 @item %[@var{p}][l]R
5197 The elapsed time in seconds.
5199 @item %[@var{p}][l]U
5200 The number of CPU seconds spent in user mode.
5202 @item %[@var{p}][l]S
5203 The number of CPU seconds spent in system mode.
5206 The CPU percentage, computed as (%U + %S) / %R.
5209 The optional @var{p} is a digit specifying the precision, the number of
5210 fractional digits after a decimal point.
5211 A value of 0 causes no decimal point or fraction to be output.
5212 At most three places after the decimal point may be specified; values
5213 of @var{p} greater than 3 are changed to 3.
5214 If @var{p} is not specified, the value 3 is used.
5216 The optional @code{l} specifies a longer format, including minutes, of
5217 the form @var{MM}m@var{SS}.@var{FF}s.
5218 The value of @var{p} determines whether or not the fraction is included.
5220 If this variable is not set, Bash acts as if it had the value
5222 @code{$'\nreal\t%3lR\nuser\t%3lU\nsys\t%3lS'}
5224 If the value is null, no timing information is displayed.
5225 A trailing newline is added when the format string is displayed.
5228 If set to a value greater than zero, @code{TMOUT} is treated as the
5229 default timeout for the @code{read} builtin (@pxref{Bash Builtins}).
5230 The @code{select} command (@pxref{Conditional Constructs}) terminates
5231 if input does not arrive after @code{TMOUT} seconds when input is coming
5234 In an interactive shell, the value is interpreted as
5235 the number of seconds to wait for input after issuing the primary
5236 prompt when the shell is interactive.
5237 Bash terminates after that number of seconds if input does
5241 If set, Bash uses its value as the name of a directory in which
5242 Bash creates temporary files for the shell's use.
5245 The numeric real user id of the current user. This variable is readonly.
5250 @chapter Bash Features
5252 This section describes features unique to Bash.
5255 * Invoking Bash:: Command line options that you can give
5257 * Bash Startup Files:: When and how Bash executes scripts.
5258 * Interactive Shells:: What an interactive shell is.
5259 * Bash Conditional Expressions:: Primitives used in composing expressions for
5260 the @code{test} builtin.
5261 * Shell Arithmetic:: Arithmetic on shell variables.
5262 * Aliases:: Substituting one command for another.
5263 * Arrays:: Array Variables.
5264 * The Directory Stack:: History of visited directories.
5265 * Printing a Prompt:: Controlling the PS1 string.
5266 * The Restricted Shell:: A more controlled mode of shell execution.
5267 * Bash POSIX Mode:: Making Bash behave more closely to what
5268 the POSIX standard specifies.
5272 @section Invoking Bash
5275 bash [long-opt] [-ir] [-abefhkmnptuvxdBCDHP] [-o @var{option}] [-O @var{shopt_option}] [@var{argument} @dots{}]
5276 bash [long-opt] [-abefhkmnptuvxdBCDHP] [-o @var{option}] [-O @var{shopt_option}] -c @var{string} [@var{argument} @dots{}]
5277 bash [long-opt] -s [-abefhkmnptuvxdBCDHP] [-o @var{option}] [-O @var{shopt_option}] [@var{argument} @dots{}]
5280 In addition to the single-character shell command-line options
5281 (@pxref{The Set Builtin}), there are several multi-character
5282 options that you can use. These options must appear on the command
5283 line before the single-character options to be recognized.
5287 Arrange for the debugger profile to be executed before the shell
5288 starts. Turns on extended debugging mode (see @ref{The Shopt Builtin}
5289 for a description of the @code{extdebug} option to the @code{shopt}
5290 builtin) and shell function tracing
5291 (see @ref{The Set Builtin} for a description of the @code{-o functrace}
5294 @item --dump-po-strings
5295 A list of all double-quoted strings preceded by @samp{$}
5296 is printed on the standard output
5297 in the @sc{gnu} @code{gettext} PO (portable object) file format.
5298 Equivalent to @option{-D} except for the output format.
5300 @item --dump-strings
5301 Equivalent to @option{-D}.
5304 Display a usage message on standard output and exit successfully.
5306 @item --init-file @var{filename}
5307 @itemx --rcfile @var{filename}
5308 Execute commands from @var{filename} (instead of @file{~/.bashrc})
5309 in an interactive shell.
5312 Equivalent to @option{-l}.
5315 Do not use the @sc{gnu} Readline library (@pxref{Command Line Editing})
5316 to read command lines when the shell is interactive.
5319 Don't load the system-wide startup file @file{/etc/profile}
5320 or any of the personal initialization files
5321 @file{~/.bash_profile}, @file{~/.bash_login}, or @file{~/.profile}
5322 when Bash is invoked as a login shell.
5325 Don't read the @file{~/.bashrc} initialization file in an
5326 interactive shell. This is on by default if the shell is
5327 invoked as @code{sh}.
5330 Change the behavior of Bash where the default operation differs
5331 from the @sc{posix} standard to match the standard. This
5332 is intended to make Bash behave as a strict superset of that
5333 standard. @xref{Bash POSIX Mode}, for a description of the Bash
5337 Make the shell a restricted shell (@pxref{The Restricted Shell}).
5340 Equivalent to @option{-v}. Print shell input lines as they're read.
5343 Show version information for this instance of
5344 Bash on the standard output and exit successfully.
5348 There are several single-character options that may be supplied at
5349 invocation which are not available with the @code{set} builtin.
5352 @item -c @var{string}
5353 Read and execute commands from @var{string} after processing the
5354 options, then exit. Any remaining arguments are assigned to the
5355 positional parameters, starting with @code{$0}.
5358 Force the shell to run interactively. Interactive shells are
5359 described in @ref{Interactive Shells}.
5362 Make this shell act as if it had been directly invoked by login.
5363 When the shell is interactive, this is equivalent to starting a
5364 login shell with @samp{exec -l bash}.
5365 When the shell is not interactive, the login shell startup files will
5367 @samp{exec bash -l} or @samp{exec bash --login}
5368 will replace the current shell with a Bash login shell.
5369 @xref{Bash Startup Files}, for a description of the special behavior
5373 Make the shell a restricted shell (@pxref{The Restricted Shell}).
5376 If this option is present, or if no arguments remain after option
5377 processing, then commands are read from the standard input.
5378 This option allows the positional parameters to be set
5379 when invoking an interactive shell.
5382 A list of all double-quoted strings preceded by @samp{$}
5383 is printed on the standard output.
5384 These are the strings that
5385 are subject to language translation when the current locale
5386 is not @code{C} or @code{POSIX} (@pxref{Locale Translation}).
5387 This implies the @option{-n} option; no commands will be executed.
5389 @item [-+]O [@var{shopt_option}]
5390 @var{shopt_option} is one of the shell options accepted by the
5391 @code{shopt} builtin (@pxref{The Shopt Builtin}).
5392 If @var{shopt_option} is present, @option{-O} sets the value of that option;
5393 @option{+O} unsets it.
5394 If @var{shopt_option} is not supplied, the names and values of the shell
5395 options accepted by @code{shopt} are printed on the standard output.
5396 If the invocation option is @option{+O}, the output is displayed in a format
5397 that may be reused as input.
5400 A @code{--} signals the end of options and disables further option
5402 Any arguments after the @code{--} are treated as filenames and arguments.
5407 A @emph{login} shell is one whose first character of argument zero is
5408 @samp{-}, or one invoked with the @option{--login} option.
5410 @cindex interactive shell
5411 An @emph{interactive} shell is one started without non-option arguments,
5412 unless @option{-s} is specified,
5413 without specifying the @option{-c} option, and whose input and output are both
5414 connected to terminals (as determined by @code{isatty(3)}), or one
5415 started with the @option{-i} option. @xref{Interactive Shells}, for more
5418 If arguments remain after option processing, and neither the
5419 @option{-c} nor the @option{-s}
5420 option has been supplied, the first argument is assumed to
5421 be the name of a file containing shell commands (@pxref{Shell Scripts}).
5422 When Bash is invoked in this fashion, @code{$0}
5423 is set to the name of the file, and the positional parameters
5424 are set to the remaining arguments.
5425 Bash reads and executes commands from this file, then exits.
5426 Bash's exit status is the exit status of the last command executed
5427 in the script. If no commands are executed, the exit status is 0.
5429 @node Bash Startup Files
5430 @section Bash Startup Files
5431 @cindex startup files
5433 This section describes how Bash executes its startup files.
5434 If any of the files exist but cannot be read, Bash reports an error.
5435 Tildes are expanded in file names as described above under
5436 Tilde Expansion (@pxref{Tilde Expansion}).
5438 Interactive shells are described in @ref{Interactive Shells}.
5440 @subsubheading Invoked as an interactive login shell, or with @option{--login}
5442 When Bash is invoked as an interactive login shell, or as a
5443 non-interactive shell with the @option{--login} option, it first reads and
5444 executes commands from the file @file{/etc/profile}, if that file exists.
5445 After reading that file, it looks for @file{~/.bash_profile},
5446 @file{~/.bash_login}, and @file{~/.profile}, in that order, and reads
5447 and executes commands from the first one that exists and is readable.
5448 The @option{--noprofile} option may be used when the shell is started to
5449 inhibit this behavior.
5451 When a login shell exits, Bash reads and executes commands from
5452 the file @file{~/.bash_logout}, if it exists.
5454 @subsubheading Invoked as an interactive non-login shell
5456 When an interactive shell that is not a login shell is started, Bash
5457 reads and executes commands from @file{~/.bashrc}, if that file exists.
5458 This may be inhibited by using the @option{--norc} option.
5459 The @option{--rcfile @var{file}} option will force Bash to read and
5460 execute commands from @var{file} instead of @file{~/.bashrc}.
5462 So, typically, your @file{~/.bash_profile} contains the line
5464 @code{if [ -f ~/.bashrc ]; then . ~/.bashrc; fi}
5467 after (or before) any login-specific initializations.
5469 @subsubheading Invoked non-interactively
5471 When Bash is started non-interactively, to run a shell script,
5472 for example, it looks for the variable @env{BASH_ENV} in the environment,
5473 expands its value if it appears there, and uses the expanded value as
5474 the name of a file to read and execute. Bash behaves as if the
5475 following command were executed:
5477 @code{if [ -n "$BASH_ENV" ]; then . "$BASH_ENV"; fi}
5480 but the value of the @env{PATH} variable is not used to search for the
5483 As noted above, if a non-interactive shell is invoked with the
5484 @option{--login} option, Bash attempts to read and execute commands from the
5485 login shell startup files.
5487 @subsubheading Invoked with name @code{sh}
5489 If Bash is invoked with the name @code{sh}, it tries to mimic the
5490 startup behavior of historical versions of @code{sh} as closely as
5491 possible, while conforming to the @sc{posix} standard as well.
5493 When invoked as an interactive login shell, or as a non-interactive
5494 shell with the @option{--login} option, it first attempts to read
5495 and execute commands from @file{/etc/profile} and @file{~/.profile}, in
5497 The @option{--noprofile} option may be used to inhibit this behavior.
5498 When invoked as an interactive shell with the name @code{sh}, Bash
5499 looks for the variable @env{ENV}, expands its value if it is defined,
5500 and uses the expanded value as the name of a file to read and execute.
5501 Since a shell invoked as @code{sh} does not attempt to read and execute
5502 commands from any other startup files, the @option{--rcfile} option has
5504 A non-interactive shell invoked with the name @code{sh} does not attempt
5505 to read any other startup files.
5507 When invoked as @code{sh}, Bash enters @sc{posix} mode after
5508 the startup files are read.
5510 @subsubheading Invoked in @sc{posix} mode
5512 When Bash is started in @sc{posix} mode, as with the
5513 @option{--posix} command line option, it follows the @sc{posix} standard
5515 In this mode, interactive shells expand the @env{ENV} variable
5516 and commands are read and executed from the file whose name is the
5518 No other startup files are read.
5520 @subsubheading Invoked by remote shell daemon
5522 Bash attempts to determine when it is being run with its standard input
5523 connected to a a network connection, as if by the remote shell
5524 daemon, usually @code{rshd}, or the secure shell daemon @code{sshd}.
5525 If Bash determines it is being run in
5526 this fashion, it reads and executes commands from @file{~/.bashrc}, if that
5527 file exists and is readable.
5528 It will not do this if invoked as @code{sh}.
5529 The @option{--norc} option may be used to inhibit this behavior, and the
5530 @option{--rcfile} option may be used to force another file to be read, but
5531 @code{rshd} does not generally invoke the shell with those options or
5532 allow them to be specified.
5534 @subsubheading Invoked with unequal effective and real @sc{uid/gid}s
5536 If Bash is started with the effective user (group) id not equal to the
5537 real user (group) id, and the @code{-p} option is not supplied, no startup
5538 files are read, shell functions are not inherited from the environment,
5539 the @env{SHELLOPTS}, @env{BASHOPTS}, @env{CDPATH}, and @env{GLOBIGNORE}
5540 variables, if they appear in the environment, are ignored, and the effective
5541 user id is set to the real user id.
5542 If the @code{-p} option is supplied at invocation, the startup behavior is
5543 the same, but the effective user id is not reset.
5545 @node Interactive Shells
5546 @section Interactive Shells
5547 @cindex interactive shell
5548 @cindex shell, interactive
5551 * What is an Interactive Shell?:: What determines whether a shell is Interactive.
5552 * Is this Shell Interactive?:: How to tell if a shell is interactive.
5553 * Interactive Shell Behavior:: What changes in a interactive shell?
5556 @node What is an Interactive Shell?
5557 @subsection What is an Interactive Shell?
5559 An interactive shell
5560 is one started without non-option arguments, unless @option{-s} is
5561 specified, without specifying the @option{-c} option, and
5562 whose input and error output are both
5563 connected to terminals (as determined by @code{isatty(3)}),
5564 or one started with the @option{-i} option.
5566 An interactive shell generally reads from and writes to a user's
5569 The @option{-s} invocation option may be used to set the positional parameters
5570 when an interactive shell is started.
5572 @node Is this Shell Interactive?
5573 @subsection Is this Shell Interactive?
5575 To determine within a startup script whether or not Bash is
5576 running interactively,
5577 test the value of the @samp{-} special parameter.
5578 It contains @code{i} when the shell is interactive. For example:
5582 *i*) echo This shell is interactive ;;
5583 *) echo This shell is not interactive ;;
5587 Alternatively, startup scripts may examine the variable
5588 @env{PS1}; it is unset in non-interactive shells, and set in
5589 interactive shells. Thus:
5592 if [ -z "$PS1" ]; then
5593 echo This shell is not interactive
5595 echo This shell is interactive
5599 @node Interactive Shell Behavior
5600 @subsection Interactive Shell Behavior
5602 When the shell is running interactively, it changes its behavior in
5607 Startup files are read and executed as described in @ref{Bash Startup Files}.
5610 Job Control (@pxref{Job Control}) is enabled by default. When job
5611 control is in effect, Bash ignores the keyboard-generated job control
5612 signals @code{SIGTTIN}, @code{SIGTTOU}, and @code{SIGTSTP}.
5615 Bash expands and displays @env{PS1} before reading the first line
5616 of a command, and expands and displays @env{PS2} before reading the
5617 second and subsequent lines of a multi-line command.
5620 Bash executes the value of the @env{PROMPT_COMMAND} variable as a command
5621 before printing the primary prompt, @env{$PS1}
5622 (@pxref{Bash Variables}).
5625 Readline (@pxref{Command Line Editing}) is used to read commands from
5626 the user's terminal.
5629 Bash inspects the value of the @code{ignoreeof} option to @code{set -o}
5630 instead of exiting immediately when it receives an @code{EOF} on its
5631 standard input when reading a command (@pxref{The Set Builtin}).
5634 Command history (@pxref{Bash History Facilities})
5635 and history expansion (@pxref{History Interaction})
5636 are enabled by default.
5637 Bash will save the command history to the file named by @env{$HISTFILE}
5638 when an interactive shell exits.
5641 Alias expansion (@pxref{Aliases}) is performed by default.
5644 In the absence of any traps, Bash ignores @code{SIGTERM}
5648 In the absence of any traps, @code{SIGINT} is caught and handled
5650 @code{SIGINT} will interrupt some shell builtins.
5653 An interactive login shell sends a @code{SIGHUP} to all jobs on exit
5654 if the @code{huponexit} shell option has been enabled (@pxref{Signals}).
5657 The @option{-n} invocation option is ignored, and @samp{set -n} has
5658 no effect (@pxref{The Set Builtin}).
5661 Bash will check for mail periodically, depending on the values of the
5662 @env{MAIL}, @env{MAILPATH}, and @env{MAILCHECK} shell variables
5663 (@pxref{Bash Variables}).
5666 Expansion errors due to references to unbound shell variables after
5667 @samp{set -u} has been enabled will not cause the shell to exit
5668 (@pxref{The Set Builtin}).
5671 The shell will not exit on expansion errors caused by @var{var} being unset
5672 or null in @code{$@{@var{var}:?@var{word}@}} expansions
5673 (@pxref{Shell Parameter Expansion}).
5676 Redirection errors encountered by shell builtins will not cause the
5680 When running in @sc{posix} mode, a special builtin returning an error
5681 status will not cause the shell to exit (@pxref{Bash POSIX Mode}).
5684 A failed @code{exec} will not cause the shell to exit
5685 (@pxref{Bourne Shell Builtins}).
5688 Parser syntax errors will not cause the shell to exit.
5691 Simple spelling correction for directory arguments to the @code{cd}
5692 builtin is enabled by default (see the description of the @code{cdspell}
5693 option to the @code{shopt} builtin in @ref{The Shopt Builtin}).
5696 The shell will check the value of the @env{TMOUT} variable and exit
5697 if a command is not read within the specified number of seconds after
5698 printing @env{$PS1} (@pxref{Bash Variables}).
5702 @node Bash Conditional Expressions
5703 @section Bash Conditional Expressions
5704 @cindex expressions, conditional
5706 Conditional expressions are used by the @code{[[} compound command
5707 and the @code{test} and @code{[} builtin commands.
5709 Expressions may be unary or binary.
5710 Unary expressions are often used to examine the status of a file.
5711 There are string operators and numeric comparison operators as well.
5712 If the @var{file} argument to one of the primaries is of the form
5713 @file{/dev/fd/@var{N}}, then file descriptor @var{N} is checked.
5714 If the @var{file} argument to one of the primaries is one of
5715 @file{/dev/stdin}, @file{/dev/stdout}, or @file{/dev/stderr}, file
5716 descriptor 0, 1, or 2, respectively, is checked.
5718 Unless otherwise specified, primaries that operate on files follow symbolic
5719 links and operate on the target of the link, rather than the link itself.
5723 True if @var{file} exists.
5726 True if @var{file} exists and is a block special file.
5729 True if @var{file} exists and is a character special file.
5732 True if @var{file} exists and is a directory.
5735 True if @var{file} exists.
5738 True if @var{file} exists and is a regular file.
5741 True if @var{file} exists and its set-group-id bit is set.
5744 True if @var{file} exists and is a symbolic link.
5747 True if @var{file} exists and its "sticky" bit is set.
5750 True if @var{file} exists and is a named pipe (FIFO).
5753 True if @var{file} exists and is readable.
5756 True if @var{file} exists and has a size greater than zero.
5759 True if file descriptor @var{fd} is open and refers to a terminal.
5762 True if @var{file} exists and its set-user-id bit is set.
5765 True if @var{file} exists and is writable.
5768 True if @var{file} exists and is executable.
5771 True if @var{file} exists and is owned by the effective user id.
5774 True if @var{file} exists and is owned by the effective group id.
5777 True if @var{file} exists and is a symbolic link.
5780 True if @var{file} exists and is a socket.
5783 True if @var{file} exists and has been modified since it was last read.
5785 @item @var{file1} -nt @var{file2}
5786 True if @var{file1} is newer (according to modification date)
5787 than @var{file2}, or if @var{file1} exists and @var{file2} does not.
5789 @item @var{file1} -ot @var{file2}
5790 True if @var{file1} is older than @var{file2},
5791 or if @var{file2} exists and @var{file1} does not.
5793 @item @var{file1} -ef @var{file2}
5794 True if @var{file1} and @var{file2} refer to the same device and
5797 @item -o @var{optname}
5798 True if shell option @var{optname} is enabled.
5799 The list of options appears in the description of the @option{-o}
5800 option to the @code{set} builtin (@pxref{The Set Builtin}).
5802 @item -z @var{string}
5803 True if the length of @var{string} is zero.
5805 @item -n @var{string}
5807 True if the length of @var{string} is non-zero.
5809 @item @var{string1} == @var{string2}
5810 True if the strings are equal.
5811 @samp{=} may be used in place of @samp{==} for strict @sc{posix} compliance.
5813 @item @var{string1} != @var{string2}
5814 True if the strings are not equal.
5816 @item @var{string1} < @var{string2}
5817 True if @var{string1} sorts before @var{string2} lexicographically.
5819 @item @var{string1} > @var{string2}
5820 True if @var{string1} sorts after @var{string2} lexicographically.
5822 @item @var{arg1} OP @var{arg2}
5824 @samp{-eq}, @samp{-ne}, @samp{-lt}, @samp{-le}, @samp{-gt}, or @samp{-ge}.
5825 These arithmetic binary operators return true if @var{arg1}
5826 is equal to, not equal to, less than, less than or equal to,
5827 greater than, or greater than or equal to @var{arg2},
5828 respectively. @var{Arg1} and @var{arg2}
5829 may be positive or negative integers.
5833 @node Shell Arithmetic
5834 @section Shell Arithmetic
5835 @cindex arithmetic, shell
5836 @cindex shell arithmetic
5837 @cindex expressions, arithmetic
5838 @cindex evaluation, arithmetic
5839 @cindex arithmetic evaluation
5841 The shell allows arithmetic expressions to be evaluated, as one of
5842 the shell expansions or by the @code{let} and the @option{-i} option
5843 to the @code{declare} builtins.
5845 Evaluation is done in fixed-width integers with no check for overflow,
5846 though division by 0 is trapped and flagged as an error.
5847 The operators and their precedence, associativity, and values
5848 are the same as in the C language.
5849 The following list of operators is grouped into levels of
5850 equal-precedence operators.
5851 The levels are listed in order of decreasing precedence.
5855 @item @var{id}++ @var{id}--
5856 variable post-increment and post-decrement
5858 @item ++@var{id} --@var{id}
5859 variable pre-increment and pre-decrement
5862 unary minus and plus
5865 logical and bitwise negation
5871 multiplication, division, remainder
5874 addition, subtraction
5877 left and right bitwise shifts
5883 equality and inequality
5889 bitwise exclusive OR
5900 @item expr ? expr : expr
5901 conditional operator
5903 @item = *= /= %= += -= <<= >>= &= ^= |=
5910 Shell variables are allowed as operands; parameter expansion is
5911 performed before the expression is evaluated.
5912 Within an expression, shell variables may also be referenced by name
5913 without using the parameter expansion syntax.
5914 A shell variable that is null or unset evaluates to 0 when referenced
5915 by name without using the parameter expansion syntax.
5916 The value of a variable is evaluated as an arithmetic expression
5917 when it is referenced, or when a variable which has been given the
5918 @var{integer} attribute using @samp{declare -i} is assigned a value.
5919 A null value evaluates to 0.
5920 A shell variable need not have its integer attribute turned on
5921 to be used in an expression.
5923 Constants with a leading 0 are interpreted as octal numbers.
5924 A leading @samp{0x} or @samp{0X} denotes hexadecimal. Otherwise,
5925 numbers take the form [@var{base}@code{#}]@var{n}, where @var{base}
5926 is a decimal number between 2 and 64 representing the arithmetic
5927 base, and @var{n} is a number in that base. If @var{base}@code{#} is
5928 omitted, then base 10 is used.
5929 The digits greater than 9 are represented by the lowercase letters,
5930 the uppercase letters, @samp{@@}, and @samp{_}, in that order.
5931 If @var{base} is less than or equal to 36, lowercase and uppercase
5932 letters may be used interchangeably to represent numbers between 10
5935 Operators are evaluated in order of precedence. Sub-expressions in
5936 parentheses are evaluated first and may override the precedence
5941 @cindex alias expansion
5943 @var{Aliases} allow a string to be substituted for a word when it is used
5944 as the first word of a simple command.
5945 The shell maintains a list of aliases that may be set and unset with
5946 the @code{alias} and @code{unalias} builtin commands.
5948 The first word of each simple command, if unquoted, is checked to see
5950 If so, that word is replaced by the text of the alias.
5951 The characters @samp{/}, @samp{$}, @samp{`}, @samp{=} and any of the
5952 shell metacharacters or quoting characters listed above may not appear
5954 The replacement text may contain any valid
5955 shell input, including shell metacharacters.
5956 The first word of the replacement text is tested for
5957 aliases, but a word that is identical to an alias being expanded
5958 is not expanded a second time.
5959 This means that one may alias @code{ls} to @code{"ls -F"},
5960 for instance, and Bash does not try to recursively expand the
5961 replacement text. If the last character of the alias value is a
5962 space or tab character, then the next command word following the
5963 alias is also checked for alias expansion.
5965 Aliases are created and listed with the @code{alias}
5966 command, and removed with the @code{unalias} command.
5968 There is no mechanism for using arguments in the replacement text,
5970 If arguments are needed, a shell function should be used
5971 (@pxref{Shell Functions}).
5973 Aliases are not expanded when the shell is not interactive,
5974 unless the @code{expand_aliases} shell option is set using
5975 @code{shopt} (@pxref{The Shopt Builtin}).
5977 The rules concerning the definition and use of aliases are
5978 somewhat confusing. Bash
5979 always reads at least one complete line
5980 of input before executing any
5981 of the commands on that line. Aliases are expanded when a
5982 command is read, not when it is executed. Therefore, an
5983 alias definition appearing on the same line as another
5984 command does not take effect until the next line of input is read.
5985 The commands following the alias definition
5986 on that line are not affected by the new alias.
5987 This behavior is also an issue when functions are executed.
5988 Aliases are expanded when a function definition is read,
5989 not when the function is executed, because a function definition
5990 is itself a compound command. As a consequence, aliases
5991 defined in a function are not available until after that
5992 function is executed. To be safe, always put
5993 alias definitions on a separate line, and do not use @code{alias}
5994 in compound commands.
5996 For almost every purpose, shell functions are preferred over aliases.
6002 Bash provides one-dimensional indexed and associative array variables.
6003 Any variable may be used as an indexed array;
6004 the @code{declare} builtin will explicitly declare an array.
6006 limit on the size of an array, nor any requirement that members
6007 be indexed or assigned contiguously.
6008 Indexed arrays are referenced using integers (including arithmetic
6009 expressions (@pxref{Shell Arithmetic}) and are zero-based;
6010 associative arrays use arbitrary strings.
6012 An indexed array is created automatically if any variable is assigned to
6015 name[@var{subscript}]=@var{value}
6020 is treated as an arithmetic expression that must evaluate to a number
6021 greater than or equal to zero. To explicitly declare an array, use
6023 declare -a @var{name}
6028 declare -a @var{name}[@var{subscript}]
6031 is also accepted; the @var{subscript} is ignored.
6033 Associative arrays are created using
6035 declare -A @var{name}.
6039 specified for an array variable using the @code{declare} and
6040 @code{readonly} builtins. Each attribute applies to all members of
6043 Arrays are assigned to using compound assignments of the form
6045 name=(value@var{1} @dots{} value@var{n})
6049 @var{value} is of the form @code{[@var{subscript}]=}@var{string}.
6050 Indexed array assignments do not require the bracket and subscript.
6051 When assigning to indexed arrays, if
6052 the optional subscript is supplied, that index is assigned to;
6053 otherwise the index of the element assigned is the last index assigned
6054 to by the statement plus one. Indexing starts at zero.
6056 When assigning to an associative array, the subscript is required.
6058 This syntax is also accepted by the @code{declare}
6059 builtin. Individual array elements may be assigned to using the
6060 @code{name[}@var{subscript}@code{]=}@var{value} syntax introduced above.
6062 Any element of an array may be referenced using
6063 @code{$@{name[}@var{subscript}@code{]@}}.
6064 The braces are required to avoid
6065 conflicts with the shell's filename expansion operators. If the
6066 @var{subscript} is @samp{@@} or @samp{*}, the word expands to all members
6067 of the array @var{name}. These subscripts differ only when the word
6068 appears within double quotes.
6069 If the word is double-quoted,
6070 @code{$@{name[*]@}} expands to a single word with
6071 the value of each array member separated by the first character of the
6072 @env{IFS} variable, and @code{$@{name[@@]@}} expands each element of
6073 @var{name} to a separate word. When there are no array members,
6074 @code{$@{name[@@]@}} expands to nothing.
6075 If the double-quoted expansion occurs within a word, the expansion of
6076 the first parameter is joined with the beginning part of the original
6077 word, and the expansion of the last parameter is joined with the last
6078 part of the original word.
6079 This is analogous to the
6080 expansion of the special parameters @samp{@@} and @samp{*}.
6081 @code{$@{#name[}@var{subscript}@code{]@}} expands to the length of
6082 @code{$@{name[}@var{subscript}@code{]@}}.
6083 If @var{subscript} is @samp{@@} or
6084 @samp{*}, the expansion is the number of elements in the array.
6085 Referencing an array variable without a subscript is equivalent to
6086 referencing with a subscript of 0.
6088 An array variable is considered set if a subscript has been assigned a
6089 value. The null string is a valid value.
6091 The @code{unset} builtin is used to destroy arrays.
6092 @code{unset} @var{name}[@var{subscript}]
6093 destroys the array element at index @var{subscript}.
6094 Care must be taken to avoid unwanted side effects caused by filename
6096 @code{unset} @var{name}, where @var{name} is an array, removes the
6097 entire array. A subscript of @samp{*} or @samp{@@} also removes the
6100 The @code{declare}, @code{local}, and @code{readonly}
6101 builtins each accept a @option{-a} option to specify an indexed
6102 array and a @option{-A} option to specify an associative array.
6103 The @code{read} builtin accepts a @option{-a}
6104 option to assign a list of words read from the standard input
6105 to an array, and can read values from the standard input into
6106 individual array elements. The @code{set} and @code{declare}
6107 builtins display array values in a way that allows them to be
6110 @node The Directory Stack
6111 @section The Directory Stack
6112 @cindex directory stack
6115 * Directory Stack Builtins:: Bash builtin commands to manipulate
6116 the directory stack.
6119 The directory stack is a list of recently-visited directories. The
6120 @code{pushd} builtin adds directories to the stack as it changes
6121 the current directory, and the @code{popd} builtin removes specified
6122 directories from the stack and changes the current directory to
6123 the directory removed. The @code{dirs} builtin displays the contents
6124 of the directory stack.
6126 The contents of the directory stack are also visible
6127 as the value of the @env{DIRSTACK} shell variable.
6129 @node Directory Stack Builtins
6130 @subsection Directory Stack Builtins
6137 dirs [+@var{N} | -@var{N}] [-clpv]
6139 Display the list of currently remembered directories. Directories
6140 are added to the list with the @code{pushd} command; the
6141 @code{popd} command removes directories from the list.
6144 Displays the @var{N}th directory (counting from the left of the
6145 list printed by @code{dirs} when invoked without options), starting
6148 Displays the @var{N}th directory (counting from the right of the
6149 list printed by @code{dirs} when invoked without options), starting
6152 Clears the directory stack by deleting all of the elements.
6154 Produces a longer listing; the default listing format uses a
6155 tilde to denote the home directory.
6157 Causes @code{dirs} to print the directory stack with one entry per
6160 Causes @code{dirs} to print the directory stack with one entry per
6161 line, prefixing each entry with its index in the stack.
6167 popd [+@var{N} | -@var{N}] [-n]
6170 Remove the top entry from the directory stack, and @code{cd}
6171 to the new top directory.
6172 When no arguments are given, @code{popd}
6173 removes the top directory from the stack and
6174 performs a @code{cd} to the new top directory. The
6175 elements are numbered from 0 starting at the first directory listed with
6176 @code{dirs}; i.e., @code{popd} is equivalent to @code{popd +0}.
6179 Removes the @var{N}th directory (counting from the left of the
6180 list printed by @code{dirs}), starting with zero.
6182 Removes the @var{N}th directory (counting from the right of the
6183 list printed by @code{dirs}), starting with zero.
6185 Suppresses the normal change of directory when removing directories
6186 from the stack, so that only the stack is manipulated.
6192 pushd [-n] [@var{+N} | @var{-N} | @var{dir} ]
6195 Save the current directory on the top of the directory stack
6196 and then @code{cd} to @var{dir}.
6197 With no arguments, @code{pushd} exchanges the top two directories.
6201 Suppresses the normal change of directory when adding directories
6202 to the stack, so that only the stack is manipulated.
6204 Brings the @var{N}th directory (counting from the left of the
6205 list printed by @code{dirs}, starting with zero) to the top of
6206 the list by rotating the stack.
6208 Brings the @var{N}th directory (counting from the right of the
6209 list printed by @code{dirs}, starting with zero) to the top of
6210 the list by rotating the stack.
6212 Makes the current working directory be the top of the stack, and then
6213 executes the equivalent of `@code{cd} @var{dir}'.
6214 @code{cd}s to @var{dir}.
6219 @node Printing a Prompt
6220 @section Controlling the Prompt
6223 The value of the variable @env{PROMPT_COMMAND} is examined just before
6224 Bash prints each primary prompt. If @env{PROMPT_COMMAND} is set and
6225 has a non-null value, then the
6226 value is executed just as if it had been typed on the command line.
6228 In addition, the following table describes the special characters which
6229 can appear in the prompt variables:
6235 The date, in "Weekday Month Date" format (e.g., "Tue May 26").
6236 @item \D@{@var{format}@}
6237 The @var{format} is passed to @code{strftime}(3) and the result is inserted
6238 into the prompt string; an empty @var{format} results in a locale-specific
6239 time representation. The braces are required.
6241 An escape character.
6243 The hostname, up to the first `.'.
6247 The number of jobs currently managed by the shell.
6249 The basename of the shell's terminal device name.
6255 The name of the shell, the basename of @code{$0} (the portion
6256 following the final slash).
6258 The time, in 24-hour HH:MM:SS format.
6260 The time, in 12-hour HH:MM:SS format.
6262 The time, in 12-hour am/pm format.
6264 The time, in 24-hour HH:MM format.
6266 The username of the current user.
6268 The version of Bash (e.g., 2.00)
6270 The release of Bash, version + patchlevel (e.g., 2.00.0)
6272 The current working directory, with @env{$HOME} abbreviated with a tilde
6273 (uses the @env{$PROMPT_DIRTRIM} variable).
6275 The basename of @env{$PWD}, with @env{$HOME} abbreviated with a tilde.
6277 The history number of this command.
6279 The command number of this command.
6281 If the effective uid is 0, @code{#}, otherwise @code{$}.
6283 The character whose ASCII code is the octal value @var{nnn}.
6287 Begin a sequence of non-printing characters. This could be used to
6288 embed a terminal control sequence into the prompt.
6290 End a sequence of non-printing characters.
6293 The command number and the history number are usually different:
6294 the history number of a command is its position in the history
6295 list, which may include commands restored from the history file
6296 (@pxref{Bash History Facilities}), while the command number is
6297 the position in the sequence of commands executed during the current
6300 After the string is decoded, it is expanded via
6301 parameter expansion, command substitution, arithmetic
6302 expansion, and quote removal, subject to the value of the
6303 @code{promptvars} shell option (@pxref{Bash Builtins}).
6305 @node The Restricted Shell
6306 @section The Restricted Shell
6307 @cindex restricted shell
6309 If Bash is started with the name @code{rbash}, or the
6310 @option{--restricted}
6313 option is supplied at invocation, the shell becomes restricted.
6314 A restricted shell is used to
6315 set up an environment more controlled than the standard shell.
6316 A restricted shell behaves identically to @code{bash}
6317 with the exception that the following are disallowed or not performed:
6321 Changing directories with the @code{cd} builtin.
6323 Setting or unsetting the values of the @env{SHELL}, @env{PATH},
6324 @env{ENV}, or @env{BASH_ENV} variables.
6326 Specifying command names containing slashes.
6328 Specifying a filename containing a slash as an argument to the @code{.}
6331 Specifying a filename containing a slash as an argument to the @option{-p}
6332 option to the @code{hash} builtin command.
6334 Importing function definitions from the shell environment at startup.
6336 Parsing the value of @env{SHELLOPTS} from the shell environment at startup.
6338 Redirecting output using the @samp{>}, @samp{>|}, @samp{<>}, @samp{>&},
6339 @samp{&>}, and @samp{>>} redirection operators.
6341 Using the @code{exec} builtin to replace the shell with another command.
6343 Adding or deleting builtin commands with the
6344 @option{-f} and @option{-d} options to the @code{enable} builtin.
6346 Using the @code{enable} builtin command to enable disabled shell builtins.
6348 Specifying the @option{-p} option to the @code{command} builtin.
6350 Turning off restricted mode with @samp{set +r} or @samp{set +o restricted}.
6353 These restrictions are enforced after any startup files are read.
6355 When a command that is found to be a shell script is executed
6356 (@pxref{Shell Scripts}), @code{rbash} turns off any restrictions in
6357 the shell spawned to execute the script.
6359 @node Bash POSIX Mode
6360 @section Bash POSIX Mode
6363 Starting Bash with the @option{--posix} command-line option or executing
6364 @samp{set -o posix} while Bash is running will cause Bash to conform more
6365 closely to the @sc{posix} standard by changing the behavior to
6366 match that specified by @sc{posix} in areas where the Bash default differs.
6368 When invoked as @code{sh}, Bash enters @sc{posix} mode after reading the
6371 The following list is what's changed when `@sc{posix} mode' is in effect:
6375 When a command in the hash table no longer exists, Bash will re-search
6376 @env{$PATH} to find the new location. This is also available with
6377 @samp{shopt -s checkhash}.
6380 The message printed by the job control code and builtins when a job
6381 exits with a non-zero status is `Done(status)'.
6384 The message printed by the job control code and builtins when a job
6385 is stopped is `Stopped(@var{signame})', where @var{signame} is, for
6386 example, @code{SIGTSTP}.
6389 The @code{bg} builtin uses the required format to describe each job placed
6390 in the background, which does not include an indication of whether the job
6391 is the current or previous job.
6394 Reserved words appearing in a context where reserved words are recognized
6395 do not undergo alias expansion.
6398 The @sc{posix} @env{PS1} and @env{PS2} expansions of @samp{!} to
6399 the history number and @samp{!!} to @samp{!} are enabled,
6400 and parameter expansion is performed on the values of @env{PS1} and
6401 @env{PS2} regardless of the setting of the @code{promptvars} option.
6404 The @sc{posix} startup files are executed (@env{$ENV}) rather than
6405 the normal Bash files.
6408 Tilde expansion is only performed on assignments preceding a command
6409 name, rather than on all assignment statements on the line.
6412 The default history file is @file{~/.sh_history} (this is the
6413 default value of @env{$HISTFILE}).
6416 The output of @samp{kill -l} prints all the signal names on a single line,
6417 separated by spaces, without the @samp{SIG} prefix.
6420 The @code{kill} builtin does not accept signal names with a @samp{SIG}
6424 Non-interactive shells exit if @var{filename} in @code{.} @var{filename}
6428 Non-interactive shells exit if a syntax error in an arithmetic expansion
6429 results in an invalid expression.
6432 Redirection operators do not perform filename expansion on the word
6433 in the redirection unless the shell is interactive.
6436 Redirection operators do not perform word splitting on the word in the
6440 Function names must be valid shell @code{name}s. That is, they may not
6441 contain characters other than letters, digits, and underscores, and
6442 may not start with a digit. Declaring a function with an invalid name
6443 causes a fatal syntax error in non-interactive shells.
6446 @sc{posix} special builtins are found before shell functions
6447 during command lookup.
6450 If a @sc{posix} special builtin returns an error status, a
6451 non-interactive shell exits. The fatal errors are those listed in
6452 the POSIX standard, and include things like passing incorrect options,
6453 redirection errors, variable assignment errors for assignments preceding
6454 the command name, and so on.
6457 If @env{CDPATH} is set, the @code{cd} builtin will not implicitly
6458 append the current directory to it. This means that @code{cd} will
6459 fail if no valid directory name can be constructed from
6460 any of the entries in @env{$CDPATH}, even if the a directory with
6461 the same name as the name given as an argument to @code{cd} exists
6462 in the current directory.
6465 A non-interactive shell exits with an error status if a variable
6466 assignment error occurs when no command name follows the assignment
6468 A variable assignment error occurs, for example, when trying to assign
6469 a value to a readonly variable.
6472 A non-interactive shell exits with an error status if the iteration
6473 variable in a @code{for} statement or the selection variable in a
6474 @code{select} statement is a readonly variable.
6477 Process substitution is not available.
6480 Assignment statements preceding @sc{posix} special builtins
6481 persist in the shell environment after the builtin completes.
6484 Assignment statements preceding shell function calls persist in the
6485 shell environment after the function returns, as if a @sc{posix}
6486 special builtin command had been executed.
6489 The @code{export} and @code{readonly} builtin commands display their
6490 output in the format required by @sc{posix}.
6493 The @code{trap} builtin displays signal names without the leading
6497 The @code{trap} builtin doesn't check the first argument for a possible
6498 signal specification and revert the signal handling to the original
6499 disposition if it is, unless that argument consists solely of digits and
6500 is a valid signal number. If users want to reset the handler for a given
6501 signal to the original disposition, they should use @samp{-} as the
6505 The @code{.} and @code{source} builtins do not search the current directory
6506 for the filename argument if it is not found by searching @env{PATH}.
6509 Subshells spawned to execute command substitutions inherit the value of
6510 the @option{-e} option from the parent shell. When not in @sc{posix} mode,
6511 Bash clears the @option{-e} option in such subshells.
6514 Alias expansion is always enabled, even in non-interactive shells.
6517 When the @code{alias} builtin displays alias definitions, it does not
6518 display them with a leading @samp{alias } unless the @option{-p} option
6522 When the @code{set} builtin is invoked without options, it does not display
6523 shell function names and definitions.
6526 When the @code{set} builtin is invoked without options, it displays
6527 variable values without quotes, unless they contain shell metacharacters,
6528 even if the result contains nonprinting characters.
6531 When the @code{cd} builtin is invoked in @var{logical} mode, and the pathname
6532 constructed from @code{$PWD} and the directory name supplied as an argument
6533 does not refer to an existing directory, @code{cd} will fail instead of
6534 falling back to @var{physical} mode.
6537 When the @code{pwd} builtin is supplied the @option{-P} option, it resets
6538 @code{$PWD} to a pathname containing no symlinks.
6541 The @code{pwd} builtin verifies that the value it prints is the same as the
6542 current directory, even if it is not asked to check the file system with the
6546 When listing the history, the @code{fc} builtin does not include an
6547 indication of whether or not a history entry has been modified.
6550 The default editor used by @code{fc} is @code{ed}.
6553 The @code{type} and @code{command} builtins will not report a non-executable
6554 file as having been found, though the shell will attempt to execute such a
6555 file if it is the only so-named file found in @code{$PATH}.
6558 The @code{vi} editing mode will invoke the @code{vi} editor directly when
6559 the @samp{v} command is run, instead of checking @code{$VISUAL} and
6563 When the @code{xpg_echo} option is enabled, Bash does not attempt to interpret
6564 any arguments to @code{echo} as options. Each argument is displayed, after
6565 escape characters are converted.
6568 The @code{ulimit} builtin uses a block size of 512 bytes for the @option{-c}
6569 and @option{-f} options.
6572 The arrival of @code{SIGCHLD} when a trap is set on @code{SIGCHLD} does
6573 not interrupt the @code{wait} builtin and cause it to return immediately.
6574 The trap command is run once for each child that exits.
6578 There is other @sc{posix} behavior that Bash does not implement by
6579 default even when in @sc{posix} mode.
6585 The @code{fc} builtin checks @code{$EDITOR} as a program to edit history
6586 entries if @code{FCEDIT} is unset, rather than defaulting directly to
6587 @code{ed}. @code{fc} uses @code{ed} if @code{EDITOR} is unset.
6590 As noted above, Bash requires the @code{xpg_echo} option to be enabled for
6591 the @code{echo} builtin to be fully conformant.
6595 Bash can be configured to be @sc{posix}-conformant by default, by specifying
6596 the @option{--enable-strict-posix-default} to @code{configure} when building
6597 (@pxref{Optional Features}).
6600 @chapter Job Control
6602 This chapter discusses what job control is, how it works, and how
6603 Bash allows you to access its facilities.
6606 * Job Control Basics:: How job control works.
6607 * Job Control Builtins:: Bash builtin commands used to interact
6609 * Job Control Variables:: Variables Bash uses to customize job
6613 @node Job Control Basics
6614 @section Job Control Basics
6618 @cindex suspending jobs
6621 refers to the ability to selectively stop (suspend)
6622 the execution of processes and continue (resume)
6623 their execution at a later point. A user typically employs
6624 this facility via an interactive interface supplied jointly
6625 by the operating system kernel's terminal driver and Bash.
6627 The shell associates a @var{job} with each pipeline. It keeps a
6628 table of currently executing jobs, which may be listed with the
6629 @code{jobs} command. When Bash starts a job
6630 asynchronously, it prints a line that looks
6636 indicating that this job is job number 1 and that the process @sc{id}
6637 of the last process in the pipeline associated with this job is
6638 25647. All of the processes in a single pipeline are members of
6639 the same job. Bash uses the @var{job} abstraction as the
6640 basis for job control.
6642 To facilitate the implementation of the user interface to job
6643 control, the operating system maintains the notion of a current terminal
6644 process group @sc{id}. Members of this process group (processes whose
6645 process group @sc{id} is equal to the current terminal process group
6646 @sc{id}) receive keyboard-generated signals such as @code{SIGINT}.
6647 These processes are said to be in the foreground. Background
6648 processes are those whose process group @sc{id} differs from the
6649 terminal's; such processes are immune to keyboard-generated
6650 signals. Only foreground processes are allowed to read from or, if
6651 the user so specifies with @code{stty tostop}, write to the terminal.
6652 Background processes which attempt to
6653 read from (write to when @code{stty tostop} is in effect) the
6654 terminal are sent a @code{SIGTTIN} (@code{SIGTTOU})
6655 signal by the kernel's terminal driver,
6656 which, unless caught, suspends the process.
6658 If the operating system on which Bash is running supports
6659 job control, Bash contains facilities to use it. Typing the
6660 @var{suspend} character (typically @samp{^Z}, Control-Z) while a
6661 process is running causes that process to be stopped and returns
6662 control to Bash. Typing the @var{delayed suspend} character
6663 (typically @samp{^Y}, Control-Y) causes the process to be stopped
6664 when it attempts to read input from the terminal, and control to
6665 be returned to Bash. The user then manipulates the state of
6666 this job, using the @code{bg} command to continue it in the
6667 background, the @code{fg} command to continue it in the
6668 foreground, or the @code{kill} command to kill it. A @samp{^Z}
6669 takes effect immediately, and has the additional side effect of
6670 causing pending output and typeahead to be discarded.
6672 There are a number of ways to refer to a job in the shell. The
6673 character @samp{%} introduces a job specification (@var{jobspec}).
6675 Job number @code{n} may be referred to as @samp{%n}.
6676 The symbols @samp{%%} and @samp{%+} refer to the shell's notion of the
6677 current job, which is the last job stopped while it was in the foreground
6678 or started in the background.
6679 A single @samp{%} (with no accompanying job specification) also refers
6681 The previous job may be referenced using @samp{%-}.
6682 If there is only a single job, @samp{%+} and @samp{%-} can both be used
6683 to refer to that job.
6684 In output pertaining to jobs (e.g., the output of the @code{jobs}
6685 command), the current job is always flagged with a @samp{+}, and the
6686 previous job with a @samp{-}.
6688 A job may also be referred to
6689 using a prefix of the name used to start it, or using a substring
6690 that appears in its command line. For example, @samp{%ce} refers
6691 to a stopped @code{ce} job. Using @samp{%?ce}, on the
6692 other hand, refers to any job containing the string @samp{ce} in
6693 its command line. If the prefix or substring matches more than one job,
6694 Bash reports an error.
6696 Simply naming a job can be used to bring it into the foreground:
6697 @samp{%1} is a synonym for @samp{fg %1}, bringing job 1 from the
6698 background into the foreground. Similarly, @samp{%1 &} resumes
6699 job 1 in the background, equivalent to @samp{bg %1}
6701 The shell learns immediately whenever a job changes state.
6702 Normally, Bash waits until it is about to print a prompt
6703 before reporting changes in a job's status so as to not interrupt
6705 If the @option{-b} option to the @code{set} builtin is enabled,
6706 Bash reports such changes immediately (@pxref{The Set Builtin}).
6707 Any trap on @code{SIGCHLD} is executed for each child process
6710 If an attempt to exit Bash is made while jobs are stopped, (or running, if
6711 the @code{checkjobs} option is enabled -- see @ref{The Shopt Builtin}), the
6712 shell prints a warning message, and if the @code{checkjobs} option is
6713 enabled, lists the jobs and their statuses.
6714 The @code{jobs} command may then be used to inspect their status.
6715 If a second attempt to exit is made without an intervening command,
6716 Bash does not print another warning, and any stopped jobs are terminated.
6718 @node Job Control Builtins
6719 @section Job Control Builtins
6726 bg [@var{jobspec} @dots{}]
6728 Resume each suspended job @var{jobspec} in the background, as if it
6729 had been started with @samp{&}.
6730 If @var{jobspec} is not supplied, the current job is used.
6731 The return status is zero unless it is run when job control is not
6732 enabled, or, when run with job control enabled, any
6733 @var{jobspec} was not found or specifies a job
6734 that was started without job control.
6741 Resume the job @var{jobspec} in the foreground and make it the current job.
6742 If @var{jobspec} is not supplied, the current job is used.
6743 The return status is that of the command placed into the foreground,
6744 or non-zero if run when job control is disabled or, when run with
6745 job control enabled, @var{jobspec} does not specify a valid job or
6746 @var{jobspec} specifies a job that was started without job control.
6751 jobs [-lnprs] [@var{jobspec}]
6752 jobs -x @var{command} [@var{arguments}]
6755 The first form lists the active jobs. The options have the
6760 List process @sc{id}s in addition to the normal information.
6763 Display information only about jobs that have changed status since
6764 the user was last notified of their status.
6767 List only the process @sc{id} of the job's process group leader.
6770 Restrict output to running jobs.
6773 Restrict output to stopped jobs.
6776 If @var{jobspec} is given,
6777 output is restricted to information about that job.
6778 If @var{jobspec} is not supplied, the status of all jobs is
6781 If the @option{-x} option is supplied, @code{jobs} replaces any
6782 @var{jobspec} found in @var{command} or @var{arguments} with the
6783 corresponding process group @sc{id}, and executes @var{command},
6784 passing it @var{argument}s, returning its exit status.
6789 kill [-s @var{sigspec}] [-n @var{signum}] [-@var{sigspec}] @var{jobspec} or @var{pid}
6790 kill -l [@var{exit_status}]
6792 Send a signal specified by @var{sigspec} or @var{signum} to the process
6793 named by job specification @var{jobspec} or process @sc{id} @var{pid}.
6794 @var{sigspec} is either a case-insensitive signal name such as
6795 @code{SIGINT} (with or without the @code{SIG} prefix)
6796 or a signal number; @var{signum} is a signal number.
6797 If @var{sigspec} and @var{signum} are not present, @code{SIGTERM} is used.
6798 The @option{-l} option lists the signal names.
6799 If any arguments are supplied when @option{-l} is given, the names of the
6800 signals corresponding to the arguments are listed, and the return status
6802 @var{exit_status} is a number specifying a signal number or the exit
6803 status of a process terminated by a signal.
6804 The return status is zero if at least one signal was successfully sent,
6805 or non-zero if an error occurs or an invalid option is encountered.
6810 wait [@var{jobspec} or @var{pid} ...]
6812 Wait until the child process specified by each process @sc{id} @var{pid}
6813 or job specification @var{jobspec} exits and return the exit status of the
6814 last command waited for.
6815 If a job spec is given, all processes in the job are waited for.
6816 If no arguments are given, all currently active child processes are
6817 waited for, and the return status is zero.
6818 If neither @var{jobspec} nor @var{pid} specifies an active child process
6819 of the shell, the return status is 127.
6824 disown [-ar] [-h] [@var{jobspec} @dots{}]
6826 Without options, each @var{jobspec} is removed from the table of
6828 If the @option{-h} option is given, the job is not removed from the table,
6829 but is marked so that @code{SIGHUP} is not sent to the job if the shell
6830 receives a @code{SIGHUP}.
6831 If @var{jobspec} is not present, and neither the @option{-a} nor @option{-r}
6832 option is supplied, the current job is used.
6833 If no @var{jobspec} is supplied, the @option{-a} option means to remove or
6834 mark all jobs; the @option{-r} option without a @var{jobspec}
6835 argument restricts operation to running jobs.
6842 Suspend the execution of this shell until it receives a
6843 @code{SIGCONT} signal.
6844 A login shell cannot be suspended; the @option{-f}
6845 option can be used to override this and force the suspension.
6849 When job control is not active, the @code{kill} and @code{wait}
6850 builtins do not accept @var{jobspec} arguments. They must be
6851 supplied process @sc{id}s.
6853 @node Job Control Variables
6854 @section Job Control Variables
6859 This variable controls how the shell interacts with the user and
6860 job control. If this variable exists then single word simple
6861 commands without redirections are treated as candidates for resumption
6862 of an existing job. There is no ambiguity allowed; if there is
6863 more than one job beginning with the string typed, then
6864 the most recently accessed job will be selected.
6865 The name of a stopped job, in this context, is the command line
6866 used to start it. If this variable is set to the value @samp{exact},
6867 the string supplied must match the name of a stopped job exactly;
6868 if set to @samp{substring},
6869 the string supplied needs to match a substring of the name of a
6870 stopped job. The @samp{substring} value provides functionality
6871 analogous to the @samp{%?} job @sc{id} (@pxref{Job Control Basics}).
6872 If set to any other value, the supplied string must
6873 be a prefix of a stopped job's name; this provides functionality
6874 analogous to the @samp{%} job @sc{id}.
6878 @set readline-appendix
6879 @set history-appendix
6880 @cindex Readline, how to use
6881 @include rluser.texi
6882 @cindex History, how to use
6883 @include hsuser.texi
6884 @clear readline-appendix
6885 @clear history-appendix
6887 @node Installing Bash
6888 @chapter Installing Bash
6890 This chapter provides basic instructions for installing Bash on
6891 the various supported platforms. The distribution supports the
6892 @sc{gnu} operating systems, nearly every version of Unix, and several
6893 non-Unix systems such as BeOS and Interix.
6894 Other independent ports exist for
6895 @sc{ms-dos}, @sc{os/2}, and Windows platforms.
6898 * Basic Installation:: Installation instructions.
6899 * Compilers and Options:: How to set special options for various
6901 * Compiling For Multiple Architectures:: How to compile Bash for more
6902 than one kind of system from
6903 the same source tree.
6904 * Installation Names:: How to set the various paths used by the installation.
6905 * Specifying the System Type:: How to configure Bash for a particular system.
6906 * Sharing Defaults:: How to share default configuration values among GNU
6908 * Operation Controls:: Options recognized by the configuration program.
6909 * Optional Features:: How to enable and disable optional features when
6913 @node Basic Installation
6914 @section Basic Installation
6915 @cindex installation
6916 @cindex configuration
6917 @cindex Bash installation
6918 @cindex Bash configuration
6920 These are installation instructions for Bash.
6922 The simplest way to compile Bash is:
6926 @code{cd} to the directory containing the source code and type
6927 @samp{./configure} to configure Bash for your system. If you're
6928 using @code{csh} on an old version of System V, you might need to
6929 type @samp{sh ./configure} instead to prevent @code{csh} from trying
6930 to execute @code{configure} itself.
6932 Running @code{configure} takes some time.
6933 While running, it prints messages telling which features it is
6937 Type @samp{make} to compile Bash and build the @code{bashbug} bug
6941 Optionally, type @samp{make tests} to run the Bash test suite.
6944 Type @samp{make install} to install @code{bash} and @code{bashbug}.
6945 This will also install the manual pages and Info file.
6949 The @code{configure} shell script attempts to guess correct
6950 values for various system-dependent variables used during
6951 compilation. It uses those values to create a @file{Makefile} in
6952 each directory of the package (the top directory, the
6953 @file{builtins}, @file{doc}, and @file{support} directories,
6954 each directory under @file{lib}, and several others). It also creates a
6955 @file{config.h} file containing system-dependent definitions.
6956 Finally, it creates a shell script named @code{config.status} that you
6957 can run in the future to recreate the current configuration, a
6958 file @file{config.cache} that saves the results of its tests to
6959 speed up reconfiguring, and a file @file{config.log} containing
6960 compiler output (useful mainly for debugging @code{configure}).
6962 @file{config.cache} contains results you don't want to keep, you
6963 may remove or edit it.
6965 To find out more about the options and arguments that the
6966 @code{configure} script understands, type
6969 bash-2.04$ ./configure --help
6973 at the Bash prompt in your Bash source directory.
6975 If you need to do unusual things to compile Bash, please
6976 try to figure out how @code{configure} could check whether or not
6977 to do them, and mail diffs or instructions to
6978 @email{bash-maintainers@@gnu.org} so they can be
6979 considered for the next release.
6981 The file @file{configure.in} is used to create @code{configure}
6982 by a program called Autoconf. You only need
6983 @file{configure.in} if you want to change it or regenerate
6984 @code{configure} using a newer version of Autoconf. If
6985 you do this, make sure you are using Autoconf version 2.50 or
6988 You can remove the program binaries and object files from the
6989 source code directory by typing @samp{make clean}. To also remove the
6990 files that @code{configure} created (so you can compile Bash for
6991 a different kind of computer), type @samp{make distclean}.
6993 @node Compilers and Options
6994 @section Compilers and Options
6996 Some systems require unusual options for compilation or linking
6997 that the @code{configure} script does not know about. You can
6998 give @code{configure} initial values for variables by setting
6999 them in the environment. Using a Bourne-compatible shell, you
7000 can do that on the command line like this:
7003 CC=c89 CFLAGS=-O2 LIBS=-lposix ./configure
7006 On systems that have the @code{env} program, you can do it like this:
7009 env CPPFLAGS=-I/usr/local/include LDFLAGS=-s ./configure
7012 The configuration process uses GCC to build Bash if it
7015 @node Compiling For Multiple Architectures
7016 @section Compiling For Multiple Architectures
7018 You can compile Bash for more than one kind of computer at the
7019 same time, by placing the object files for each architecture in their
7020 own directory. To do this, you must use a version of @code{make} that
7021 supports the @code{VPATH} variable, such as GNU @code{make}.
7023 directory where you want the object files and executables to go and run
7024 the @code{configure} script from the source directory. You may need to
7025 supply the @option{--srcdir=PATH} argument to tell @code{configure} where the
7026 source files are. @code{configure} automatically checks for the
7027 source code in the directory that @code{configure} is in and in `..'.
7029 If you have to use a @code{make} that does not supports the @code{VPATH}
7030 variable, you can compile Bash for one architecture at a
7031 time in the source code directory. After you have installed
7032 Bash for one architecture, use @samp{make distclean} before
7033 reconfiguring for another architecture.
7035 Alternatively, if your system supports symbolic links, you can use the
7036 @file{support/mkclone} script to create a build tree which has
7037 symbolic links back to each file in the source directory. Here's an
7038 example that creates a build directory in the current directory from a
7039 source directory @file{/usr/gnu/src/bash-2.0}:
7042 bash /usr/gnu/src/bash-2.0/support/mkclone -s /usr/gnu/src/bash-2.0 .
7046 The @code{mkclone} script requires Bash, so you must have already built
7047 Bash for at least one architecture before you can create build
7048 directories for other architectures.
7050 @node Installation Names
7051 @section Installation Names
7053 By default, @samp{make install} will install into
7054 @file{/usr/local/bin}, @file{/usr/local/man}, etc. You can
7055 specify an installation prefix other than @file{/usr/local} by
7056 giving @code{configure} the option @option{--prefix=@var{PATH}},
7057 or by specifying a value for the @code{DESTDIR} @samp{make}
7058 variable when running @samp{make install}.
7060 You can specify separate installation prefixes for
7061 architecture-specific files and architecture-independent files.
7062 If you give @code{configure} the option
7063 @option{--exec-prefix=@var{PATH}}, @samp{make install} will use
7064 @var{PATH} as the prefix for installing programs and libraries.
7065 Documentation and other data files will still use the regular prefix.
7067 @node Specifying the System Type
7068 @section Specifying the System Type
7070 There may be some features @code{configure} can not figure out
7071 automatically, but need to determine by the type of host Bash
7072 will run on. Usually @code{configure} can figure that
7073 out, but if it prints a message saying it can not guess the host
7074 type, give it the @option{--host=TYPE} option. @samp{TYPE} can
7075 either be a short name for the system type, such as @samp{sun4},
7076 or a canonical name with three fields: @samp{CPU-COMPANY-SYSTEM}
7077 (e.g., @samp{i386-unknown-freebsd4.2}).
7079 See the file @file{support/config.sub} for the possible
7080 values of each field.
7082 @node Sharing Defaults
7083 @section Sharing Defaults
7085 If you want to set default values for @code{configure} scripts to
7086 share, you can create a site shell script called
7087 @code{config.site} that gives default values for variables like
7088 @code{CC}, @code{cache_file}, and @code{prefix}. @code{configure}
7089 looks for @file{PREFIX/share/config.site} if it exists, then
7090 @file{PREFIX/etc/config.site} if it exists. Or, you can set the
7091 @code{CONFIG_SITE} environment variable to the location of the site
7092 script. A warning: the Bash @code{configure} looks for a site script,
7093 but not all @code{configure} scripts do.
7095 @node Operation Controls
7096 @section Operation Controls
7098 @code{configure} recognizes the following options to control how it
7103 @item --cache-file=@var{file}
7104 Use and save the results of the tests in
7105 @var{file} instead of @file{./config.cache}. Set @var{file} to
7106 @file{/dev/null} to disable caching, for debugging
7110 Print a summary of the options to @code{configure}, and exit.
7115 Do not print messages saying which checks are being made.
7117 @item --srcdir=@var{dir}
7118 Look for the Bash source code in directory @var{dir}. Usually
7119 @code{configure} can determine that directory automatically.
7122 Print the version of Autoconf used to generate the @code{configure}
7126 @code{configure} also accepts some other, not widely used, boilerplate
7127 options. @samp{configure --help} prints the complete list.
7129 @node Optional Features
7130 @section Optional Features
7132 The Bash @code{configure} has a number of @option{--enable-@var{feature}}
7133 options, where @var{feature} indicates an optional part of Bash.
7134 There are also several @option{--with-@var{package}} options,
7135 where @var{package} is something like @samp{bash-malloc} or @samp{purify}.
7136 To turn off the default use of a package, use
7137 @option{--without-@var{package}}. To configure Bash without a feature
7138 that is enabled by default, use @option{--disable-@var{feature}}.
7140 Here is a complete list of the @option{--enable-} and
7141 @option{--with-} options that the Bash @code{configure} recognizes.
7145 Define if you are using the Andrew File System from Transarc.
7147 @item --with-bash-malloc
7148 Use the Bash version of
7149 @code{malloc} in the directory @file{lib/malloc}. This is not the same
7150 @code{malloc} that appears in @sc{gnu} libc, but an older version
7151 originally derived from the 4.2 @sc{bsd} @code{malloc}. This @code{malloc}
7152 is very fast, but wastes some space on each allocation.
7153 This option is enabled by default.
7154 The @file{NOTES} file contains a list of systems for
7155 which this should be turned off, and @code{configure} disables this
7156 option automatically for a number of systems.
7159 Use the curses library instead of the termcap library. This should
7160 be supplied if your system has an inadequate or incomplete termcap
7163 @item --with-gnu-malloc
7164 A synonym for @code{--with-bash-malloc}.
7166 @item --with-installed-readline[=@var{PREFIX}]
7167 Define this to make Bash link with a locally-installed version of Readline
7168 rather than the version in @file{lib/readline}. This works only with
7169 Readline 5.0 and later versions. If @var{PREFIX} is @code{yes} or not
7170 supplied, @code{configure} uses the values of the make variables
7171 @code{includedir} and @code{libdir}, which are subdirectories of @code{prefix}
7172 by default, to find the installed version of Readline if it is not in
7173 the standard system include and library directories.
7174 If @var{PREFIX} is @code{no}, Bash links with the version in
7175 @file{lib/readline}.
7176 If @var{PREFIX} is set to any other value, @code{configure} treats it as
7177 a directory pathname and looks for
7178 the installed version of Readline in subdirectories of that directory
7179 (include files in @var{PREFIX}/@code{include} and the library in
7180 @var{PREFIX}/@code{lib}).
7183 Define this to use the Purify memory allocation checker from Rational
7186 @item --enable-minimal-config
7187 This produces a shell with minimal features, close to the historical
7191 There are several @option{--enable-} options that alter how Bash is
7192 compiled and linked, rather than changing run-time features.
7195 @item --enable-largefile
7196 Enable support for @uref{http://www.sas.com/standards/large_file/x_open.20Mar96.html,
7197 large files} if the operating system requires special compiler options
7198 to build programs which can access large files. This is enabled by
7199 default, if the operating system provides large file support.
7201 @item --enable-profiling
7202 This builds a Bash binary that produces profiling information to be
7203 processed by @code{gprof} each time it is executed.
7205 @item --enable-static-link
7206 This causes Bash to be linked statically, if @code{gcc} is being used.
7207 This could be used to build a version to use as root's shell.
7210 The @samp{minimal-config} option can be used to disable all of
7211 the following options, but it is processed first, so individual
7212 options may be enabled using @samp{enable-@var{feature}}.
7214 All of the following options except for @samp{disabled-builtins} and
7215 @samp{xpg-echo-default} are
7216 enabled by default, unless the operating system does not provide the
7220 @item --enable-alias
7221 Allow alias expansion and include the @code{alias} and @code{unalias}
7222 builtins (@pxref{Aliases}).
7224 @item --enable-arith-for-command
7225 Include support for the alternate form of the @code{for} command
7226 that behaves like the C language @code{for} statement
7227 (@pxref{Looping Constructs}).
7229 @item --enable-array-variables
7230 Include support for one-dimensional array shell variables
7233 @item --enable-bang-history
7234 Include support for @code{csh}-like history substitution
7235 (@pxref{History Interaction}).
7237 @item --enable-brace-expansion
7238 Include @code{csh}-like brace expansion
7239 ( @code{b@{a,b@}c} @expansion{} @code{bac bbc} ).
7240 See @ref{Brace Expansion}, for a complete description.
7242 @item --enable-casemod-attributes
7243 Include support for case-modifying attributes in the @code{declare} builtin
7244 and assignment statements. Variables with the @var{uppercase} attribute,
7245 for example, will have their values converted to uppercase upon assignment.
7247 @item --enable-casemod-expansion
7248 Include support for case-modifying word expansions.
7250 @item --enable-command-timing
7251 Include support for recognizing @code{time} as a reserved word and for
7252 displaying timing statistics for the pipeline following @code{time}
7253 (@pxref{Pipelines}).
7254 This allows pipelines as well as shell builtins and functions to be timed.
7256 @item --enable-cond-command
7257 Include support for the @code{[[} conditional command.
7258 (@pxref{Conditional Constructs}).
7260 @item --enable-cond-regexp
7261 Include support for matching POSIX regular expressions using the
7262 @samp{=~} binary operator in the @code{[[} conditional command.
7263 (@pxref{Conditional Constructs}).
7265 @item --enable-coprocesses
7266 Include support for coprocesses and the @code{coproc} reserved word
7267 (@pxref{Pipelines}).
7269 @item --enable-debugger
7270 Include support for the bash debugger (distributed separately).
7272 @item --enable-directory-stack
7273 Include support for a @code{csh}-like directory stack and the
7274 @code{pushd}, @code{popd}, and @code{dirs} builtins
7275 (@pxref{The Directory Stack}).
7277 @item --enable-disabled-builtins
7278 Allow builtin commands to be invoked via @samp{builtin xxx}
7279 even after @code{xxx} has been disabled using @samp{enable -n xxx}.
7280 See @ref{Bash Builtins}, for details of the @code{builtin} and
7281 @code{enable} builtin commands.
7283 @item --enable-dparen-arithmetic
7284 Include support for the @code{((@dots{}))} command
7285 (@pxref{Conditional Constructs}).
7287 @item --enable-extended-glob
7288 Include support for the extended pattern matching features described
7289 above under @ref{Pattern Matching}.
7291 @item --enable-extended-glob-default
7292 Set the default value of the @var{extglob} shell option described
7293 above under @ref{The Shopt Builtin} to be enabled.
7295 @item --enable-help-builtin
7296 Include the @code{help} builtin, which displays help on shell builtins and
7297 variables (@pxref{Bash Builtins}).
7299 @item --enable-history
7300 Include command history and the @code{fc} and @code{history}
7301 builtin commands (@pxref{Bash History Facilities}).
7303 @item --enable-job-control
7304 This enables the job control features (@pxref{Job Control}),
7305 if the operating system supports them.
7307 @item --enable-multibyte
7308 This enables support for multibyte characters if the operating
7309 system provides the necessary support.
7311 @item --enable-net-redirections
7312 This enables the special handling of filenames of the form
7313 @code{/dev/tcp/@var{host}/@var{port}} and
7314 @code{/dev/udp/@var{host}/@var{port}}
7315 when used in redirections (@pxref{Redirections}).
7317 @item --enable-process-substitution
7318 This enables process substitution (@pxref{Process Substitution}) if
7319 the operating system provides the necessary support.
7321 @item --enable-progcomp
7322 Enable the programmable completion facilities
7323 (@pxref{Programmable Completion}).
7324 If Readline is not enabled, this option has no effect.
7326 @item --enable-prompt-string-decoding
7327 Turn on the interpretation of a number of backslash-escaped characters
7328 in the @env{$PS1}, @env{$PS2}, @env{$PS3}, and @env{$PS4} prompt
7329 strings. See @ref{Printing a Prompt}, for a complete list of prompt
7330 string escape sequences.
7332 @item --enable-readline
7333 Include support for command-line editing and history with the Bash
7334 version of the Readline library (@pxref{Command Line Editing}).
7336 @item --enable-restricted
7337 Include support for a @dfn{restricted shell}. If this is enabled, Bash,
7338 when called as @code{rbash}, enters a restricted mode. See
7339 @ref{The Restricted Shell}, for a description of restricted mode.
7341 @item --enable-select
7342 Include the @code{select} builtin, which allows the generation of simple
7343 menus (@pxref{Conditional Constructs}).
7345 @item --enable-separate-helpfiles
7346 Use external files for the documentation displayed by the @code{help} builtin
7347 instead of storing the text internally.
7349 @item --enable-single-help-strings
7350 Store the text displayed by the @code{help} builtin as a single string for
7351 each help topic. This aids in translating the text to different languages.
7352 You may need to disable this if your compiler cannot handle very long string
7355 @item --enable-strict-posix-default
7356 Make Bash @sc{posix}-conformant by default (@pxref{Bash POSIX Mode}).
7358 @item --enable-usg-echo-default
7359 A synonym for @code{--enable-xpg-echo-default}.
7361 @item --enable-xpg-echo-default
7362 Make the @code{echo} builtin expand backslash-escaped characters by default,
7363 without requiring the @option{-e} option.
7364 This sets the default value of the @code{xpg_echo} shell option to @code{on},
7365 which makes the Bash @code{echo} behave more like the version specified in
7366 the Single Unix Specification, version 3.
7367 @xref{Bash Builtins}, for a description of the escape sequences that
7368 @code{echo} recognizes.
7372 The file @file{config-top.h} contains C Preprocessor
7373 @samp{#define} statements for options which are not settable from
7375 Some of these are not meant to be changed; beware of the consequences if
7377 Read the comments associated with each definition for more
7378 information about its effect.
7380 @node Reporting Bugs
7381 @appendix Reporting Bugs
7383 Please report all bugs you find in Bash.
7384 But first, you should
7385 make sure that it really is a bug, and that it appears in the latest
7387 The latest version of Bash is always available for FTP from
7388 @uref{ftp://ftp.gnu.org/pub/gnu/bash/}.
7390 Once you have determined that a bug actually exists, use the
7391 @code{bashbug} command to submit a bug report.
7392 If you have a fix, you are encouraged to mail that as well!
7393 Suggestions and `philosophical' bug reports may be mailed
7394 to @email{bug-bash@@gnu.org} or posted to the Usenet
7395 newsgroup @code{gnu.bash.bug}.
7397 All bug reports should include:
7400 The version number of Bash.
7402 The hardware and operating system.
7404 The compiler used to compile Bash.
7406 A description of the bug behaviour.
7408 A short script or `recipe' which exercises the bug and may be used
7413 @code{bashbug} inserts the first three items automatically into
7414 the template it provides for filing a bug report.
7416 Please send all reports concerning this manual to
7417 @email{chet.ramey@@case.edu}.
7419 @node Major Differences From The Bourne Shell
7420 @appendix Major Differences From The Bourne Shell
7422 Bash implements essentially the same grammar, parameter and
7423 variable expansion, redirection, and quoting as the Bourne Shell.
7424 Bash uses the @sc{posix} standard as the specification of
7425 how these features are to be implemented. There are some
7426 differences between the traditional Bourne shell and Bash; this
7427 section quickly details the differences of significance. A
7428 number of these differences are explained in greater depth in
7430 This section uses the version of @code{sh} included in SVR4.2 (the
7431 last version of the historical Bourne shell) as the baseline reference.
7436 Bash is @sc{posix}-conformant, even where the @sc{posix} specification
7437 differs from traditional @code{sh} behavior (@pxref{Bash POSIX Mode}).
7440 Bash has multi-character invocation options (@pxref{Invoking Bash}).
7443 Bash has command-line editing (@pxref{Command Line Editing}) and
7444 the @code{bind} builtin.
7447 Bash provides a programmable word completion mechanism
7448 (@pxref{Programmable Completion}), and builtin commands
7449 @code{complete}, @code{compgen}, and @code{compopt}, to
7453 Bash has command history (@pxref{Bash History Facilities}) and the
7454 @code{history} and @code{fc} builtins to manipulate it.
7455 The Bash history list maintains timestamp information and uses the
7456 value of the @code{HISTTIMEFORMAT} variable to display it.
7459 Bash implements @code{csh}-like history expansion
7460 (@pxref{History Interaction}).
7463 Bash has one-dimensional array variables (@pxref{Arrays}), and the
7464 appropriate variable expansions and assignment syntax to use them.
7465 Several of the Bash builtins take options to act on arrays.
7466 Bash provides a number of built-in array variables.
7469 The @code{$'@dots{}'} quoting syntax, which expands ANSI-C
7470 backslash-escaped characters in the text between the single quotes,
7471 is supported (@pxref{ANSI-C Quoting}).
7474 Bash supports the @code{$"@dots{}"} quoting syntax to do
7475 locale-specific translation of the characters between the double
7476 quotes. The @option{-D}, @option{--dump-strings}, and @option{--dump-po-strings}
7477 invocation options list the translatable strings found in a script
7478 (@pxref{Locale Translation}).
7481 Bash implements the @code{!} keyword to negate the return value of
7482 a pipeline (@pxref{Pipelines}).
7483 Very useful when an @code{if} statement needs to act only if a test fails.
7484 The Bash @samp{-o pipefail} option to @code{set} will cause a pipeline to
7485 return a failure status if any command fails.
7488 Bash has the @code{time} reserved word and command timing (@pxref{Pipelines}).
7489 The display of the timing statistics may be controlled with the
7490 @env{TIMEFORMAT} variable.
7493 Bash implements the @code{for (( @var{expr1} ; @var{expr2} ; @var{expr3} ))}
7494 arithmetic for command, similar to the C language (@pxref{Looping Constructs}).
7497 Bash includes the @code{select} compound command, which allows the
7498 generation of simple menus (@pxref{Conditional Constructs}).
7501 Bash includes the @code{[[} compound command, which makes conditional
7502 testing part of the shell grammar (@pxref{Conditional Constructs}), including
7503 optional regular expression matching.
7506 Bash provides optional case-insensitive matching for the @code{case} and
7507 @code{[[} constructs.
7510 Bash includes brace expansion (@pxref{Brace Expansion}) and tilde
7511 expansion (@pxref{Tilde Expansion}).
7514 Bash implements command aliases and the @code{alias} and @code{unalias}
7515 builtins (@pxref{Aliases}).
7518 Bash provides shell arithmetic, the @code{((} compound command
7519 (@pxref{Conditional Constructs}),
7520 and arithmetic expansion (@pxref{Shell Arithmetic}).
7523 Variables present in the shell's initial environment are automatically
7524 exported to child processes. The Bourne shell does not normally do
7525 this unless the variables are explicitly marked using the @code{export}
7529 Bash supports the @samp{+=} assignment operator, which appends to the value
7530 of the variable named on the left hand side.
7533 Bash includes the @sc{posix} pattern removal @samp{%}, @samp{#}, @samp{%%}
7534 and @samp{##} expansions to remove leading or trailing substrings from
7535 variable values (@pxref{Shell Parameter Expansion}).
7538 The expansion @code{$@{#xx@}}, which returns the length of @code{$@{xx@}},
7539 is supported (@pxref{Shell Parameter Expansion}).
7542 The expansion @code{$@{var:}@var{offset}@code{[:}@var{length}@code{]@}},
7543 which expands to the substring of @code{var}'s value of length
7544 @var{length}, beginning at @var{offset}, is present
7545 (@pxref{Shell Parameter Expansion}).
7549 @code{$@{var/[/]}@var{pattern}@code{[/}@var{replacement}@code{]@}},
7550 which matches @var{pattern} and replaces it with @var{replacement} in
7551 the value of @code{var}, is available (@pxref{Shell Parameter Expansion}).
7554 The expansion @code{$@{!@var{prefix@}*}} expansion, which expands to
7555 the names of all shell variables whose names begin with @var{prefix},
7556 is available (@pxref{Shell Parameter Expansion}).
7559 Bash has @var{indirect} variable expansion using @code{$@{!word@}}
7560 (@pxref{Shell Parameter Expansion}).
7563 Bash can expand positional parameters beyond @code{$9} using
7564 @code{$@{@var{num}@}}.
7567 The @sc{posix} @code{$()} form of command substitution
7568 is implemented (@pxref{Command Substitution}),
7569 and preferred to the Bourne shell's @code{``} (which
7570 is also implemented for backwards compatibility).
7573 Bash has process substitution (@pxref{Process Substitution}).
7576 Bash automatically assigns variables that provide information about the
7577 current user (@env{UID}, @env{EUID}, and @env{GROUPS}), the current host
7578 (@env{HOSTTYPE}, @env{OSTYPE}, @env{MACHTYPE}, and @env{HOSTNAME}),
7579 and the instance of Bash that is running (@env{BASH},
7580 @env{BASH_VERSION}, and @env{BASH_VERSINFO}). @xref{Bash Variables},
7584 The @env{IFS} variable is used to split only the results of expansion,
7585 not all words (@pxref{Word Splitting}).
7586 This closes a longstanding shell security hole.
7589 Bash implements the full set of @sc{posix} filename expansion operators,
7590 including @var{character classes}, @var{equivalence classes}, and
7591 @var{collating symbols} (@pxref{Filename Expansion}).
7594 Bash implements extended pattern matching features when the @code{extglob}
7595 shell option is enabled (@pxref{Pattern Matching}).
7598 It is possible to have a variable and a function with the same name;
7599 @code{sh} does not separate the two name spaces.
7602 Bash functions are permitted to have local variables using the
7603 @code{local} builtin, and thus useful recursive functions may be written
7604 (@pxref{Bash Builtins}).
7607 Variable assignments preceding commands affect only that command, even
7608 builtins and functions (@pxref{Environment}).
7609 In @code{sh}, all variable assignments
7610 preceding commands are global unless the command is executed from the
7614 Bash performs filename expansion on filenames specified as operands
7615 to input and output redirection operators (@pxref{Redirections}).
7618 Bash contains the @samp{<>} redirection operator, allowing a file to be
7619 opened for both reading and writing, and the @samp{&>} redirection
7620 operator, for directing standard output and standard error to the same
7621 file (@pxref{Redirections}).
7624 Bash includes the @samp{<<<} redirection operator, allowing a string to
7625 be used as the standard input to a command.
7628 Bash implements the @samp{[n]<&@var{word}} and @samp{[n]>&@var{word}}
7629 redirection operators, which move one file descriptor to another.
7632 Bash treats a number of filenames specially when they are
7633 used in redirection operators (@pxref{Redirections}).
7636 Bash can open network connections to arbitrary machines and services
7637 with the redirection operators (@pxref{Redirections}).
7640 The @code{noclobber} option is available to avoid overwriting existing
7641 files with output redirection (@pxref{The Set Builtin}).
7642 The @samp{>|} redirection operator may be used to override @code{noclobber}.
7645 The Bash @code{cd} and @code{pwd} builtins (@pxref{Bourne Shell Builtins})
7646 each take @option{-L} and @option{-P} options to switch between logical and
7650 Bash allows a function to override a builtin with the same name, and provides
7651 access to that builtin's functionality within the function via the
7652 @code{builtin} and @code{command} builtins (@pxref{Bash Builtins}).
7655 The @code{command} builtin allows selective disabling of functions
7656 when command lookup is performed (@pxref{Bash Builtins}).
7659 Individual builtins may be enabled or disabled using the @code{enable}
7660 builtin (@pxref{Bash Builtins}).
7663 The Bash @code{exec} builtin takes additional options that allow users
7664 to control the contents of the environment passed to the executed
7665 command, and what the zeroth argument to the command is to be
7666 (@pxref{Bourne Shell Builtins}).
7669 Shell functions may be exported to children via the environment
7670 using @code{export -f} (@pxref{Shell Functions}).
7673 The Bash @code{export}, @code{readonly}, and @code{declare} builtins can
7674 take a @option{-f} option to act on shell functions, a @option{-p} option to
7675 display variables with various attributes set in a format that can be
7676 used as shell input, a @option{-n} option to remove various variable
7677 attributes, and @samp{name=value} arguments to set variable attributes
7678 and values simultaneously.
7681 The Bash @code{hash} builtin allows a name to be associated with
7682 an arbitrary filename, even when that filename cannot be found by
7683 searching the @env{$PATH}, using @samp{hash -p}
7684 (@pxref{Bourne Shell Builtins}).
7687 Bash includes a @code{help} builtin for quick reference to shell
7688 facilities (@pxref{Bash Builtins}).
7691 The @code{printf} builtin is available to display formatted output
7692 (@pxref{Bash Builtins}).
7695 The Bash @code{read} builtin (@pxref{Bash Builtins})
7696 will read a line ending in @samp{\} with
7697 the @option{-r} option, and will use the @env{REPLY} variable as a
7698 default if no non-option arguments are supplied.
7699 The Bash @code{read} builtin
7700 also accepts a prompt string with the @option{-p} option and will use
7701 Readline to obtain the line when given the @option{-e} option.
7702 The @code{read} builtin also has additional options to control input:
7703 the @option{-s} option will turn off echoing of input characters as
7704 they are read, the @option{-t} option will allow @code{read} to time out
7705 if input does not arrive within a specified number of seconds, the
7706 @option{-n} option will allow reading only a specified number of
7707 characters rather than a full line, and the @option{-d} option will read
7708 until a particular character rather than newline.
7711 The @code{return} builtin may be used to abort execution of scripts
7712 executed with the @code{.} or @code{source} builtins
7713 (@pxref{Bourne Shell Builtins}).
7716 Bash includes the @code{shopt} builtin, for finer control of shell
7717 optional capabilities (@pxref{The Shopt Builtin}), and allows these options
7718 to be set and unset at shell invocation (@pxref{Invoking Bash}).
7721 Bash has much more optional behavior controllable with the @code{set}
7722 builtin (@pxref{The Set Builtin}).
7725 The @samp{-x} (@code{xtrace}) option displays commands other than
7726 simple commands when performing an execution trace
7727 (@pxref{The Set Builtin}).
7730 The @code{test} builtin (@pxref{Bourne Shell Builtins})
7731 is slightly different, as it implements the @sc{posix} algorithm,
7732 which specifies the behavior based on the number of arguments.
7735 Bash includes the @code{caller} builtin, which displays the context of
7736 any active subroutine call (a shell function or a script executed with
7737 the @code{.} or @code{source} builtins). This supports the bash
7741 The @code{trap} builtin (@pxref{Bourne Shell Builtins}) allows a
7742 @code{DEBUG} pseudo-signal specification, similar to @code{EXIT}.
7743 Commands specified with a @code{DEBUG} trap are executed before every
7744 simple command, @code{for} command, @code{case} command,
7745 @code{select} command, every arithmetic @code{for} command, and before
7746 the first command executes in a shell function.
7747 The @code{DEBUG} trap is not inherited by shell functions unless the
7748 function has been given the @code{trace} attribute or the
7749 @code{functrace} option has been enabled using the @code{shopt} builtin.
7750 The @code{extdebug} shell option has additional effects on the
7753 The @code{trap} builtin (@pxref{Bourne Shell Builtins}) allows an
7754 @code{ERR} pseudo-signal specification, similar to @code{EXIT} and @code{DEBUG}.
7755 Commands specified with an @code{ERR} trap are executed after a simple
7756 command fails, with a few exceptions.
7757 The @code{ERR} trap is not inherited by shell functions unless the
7758 @code{-o errtrace} option to the @code{set} builtin is enabled.
7760 The @code{trap} builtin (@pxref{Bourne Shell Builtins}) allows a
7761 @code{RETURN} pseudo-signal specification, similar to
7762 @code{EXIT} and @code{DEBUG}.
7763 Commands specified with an @code{RETURN} trap are executed before
7764 execution resumes after a shell function or a shell script executed with
7765 @code{.} or @code{source} returns.
7766 The @code{RETURN} trap is not inherited by shell functions unless the
7767 function has been given the @code{trace} attribute or the
7768 @code{functrace} option has been enabled using the @code{shopt} builtin.
7771 The Bash @code{type} builtin is more extensive and gives more information
7772 about the names it finds (@pxref{Bash Builtins}).
7775 The Bash @code{umask} builtin permits a @option{-p} option to cause
7776 the output to be displayed in the form of a @code{umask} command
7777 that may be reused as input (@pxref{Bourne Shell Builtins}).
7780 Bash implements a @code{csh}-like directory stack, and provides the
7781 @code{pushd}, @code{popd}, and @code{dirs} builtins to manipulate it
7782 (@pxref{The Directory Stack}).
7783 Bash also makes the directory stack visible as the value of the
7784 @env{DIRSTACK} shell variable.
7787 Bash interprets special backslash-escaped characters in the prompt
7788 strings when interactive (@pxref{Printing a Prompt}).
7791 The Bash restricted mode is more useful (@pxref{The Restricted Shell});
7792 the SVR4.2 shell restricted mode is too limited.
7795 The @code{disown} builtin can remove a job from the internal shell
7796 job table (@pxref{Job Control Builtins}) or suppress the sending
7797 of @code{SIGHUP} to a job when the shell exits as the result of a
7801 Bash includes a number of features to support a separate debugger for
7805 The SVR4.2 shell has two privilege-related builtins
7806 (@code{mldmode} and @code{priv}) not present in Bash.
7809 Bash does not have the @code{stop} or @code{newgrp} builtins.
7812 Bash does not use the @env{SHACCT} variable or perform shell accounting.
7815 The SVR4.2 @code{sh} uses a @env{TIMEOUT} variable like Bash uses
7821 More features unique to Bash may be found in @ref{Bash Features}.
7824 @appendixsec Implementation Differences From The SVR4.2 Shell
7826 Since Bash is a completely new implementation, it does not suffer from
7827 many of the limitations of the SVR4.2 shell. For instance:
7832 Bash does not fork a subshell when redirecting into or out of
7833 a shell control structure such as an @code{if} or @code{while}
7837 Bash does not allow unbalanced quotes. The SVR4.2 shell will silently
7838 insert a needed closing quote at @code{EOF} under certain circumstances.
7839 This can be the cause of some hard-to-find errors.
7842 The SVR4.2 shell uses a baroque memory management scheme based on
7843 trapping @code{SIGSEGV}. If the shell is started from a process with
7844 @code{SIGSEGV} blocked (e.g., by using the @code{system()} C library
7845 function call), it misbehaves badly.
7848 In a questionable attempt at security, the SVR4.2 shell,
7849 when invoked without the @option{-p} option, will alter its real
7850 and effective @sc{uid} and @sc{gid} if they are less than some
7851 magic threshold value, commonly 100.
7852 This can lead to unexpected results.
7855 The SVR4.2 shell does not allow users to trap @code{SIGSEGV},
7856 @code{SIGALRM}, or @code{SIGCHLD}.
7859 The SVR4.2 shell does not allow the @env{IFS}, @env{MAILCHECK},
7860 @env{PATH}, @env{PS1}, or @env{PS2} variables to be unset.
7863 The SVR4.2 shell treats @samp{^} as the undocumented equivalent of
7867 Bash allows multiple option arguments when it is invoked (@code{-x -v});
7868 the SVR4.2 shell allows only one option argument (@code{-xv}). In
7869 fact, some versions of the shell dump core if the second argument begins
7873 The SVR4.2 shell exits a script if any builtin fails; Bash exits
7874 a script only if one of the @sc{posix} special builtins fails, and
7875 only for certain failures, as enumerated in the @sc{posix} standard.
7878 The SVR4.2 shell behaves differently when invoked as @code{jsh}
7879 (it turns on job control).
7882 @node GNU Free Documentation License
7883 @appendix GNU Free Documentation License
7891 * Builtin Index:: Index of Bash builtin commands.
7892 * Reserved Word Index:: Index of Bash reserved words.
7893 * Variable Index:: Quick reference helps you find the
7895 * Function Index:: Index of bindable Readline functions.
7896 * Concept Index:: General index for concepts described in
7901 @appendixsec Index of Shell Builtin Commands
7904 @node Reserved Word Index
7905 @appendixsec Index of Shell Reserved Words
7908 @node Variable Index
7909 @appendixsec Parameter and Variable Index
7912 @node Function Index
7913 @appendixsec Function Index
7917 @appendixsec Concept Index