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-2004 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.1 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 have freedom to copy and modify
34 this GNU Manual, like GNU software. Copies published by the Free
35 Software Foundation raise funds for GNU development.''
45 * Bash: (bash). The GNU Bourne-Again SHell.
51 @title Bash Reference Manual
52 @subtitle Reference Documentation for Bash
53 @subtitle Edition @value{EDITION}, for @code{Bash} Version @value{VERSION}.
54 @subtitle @value{UPDATED-MONTH}
55 @author Chet Ramey, Case Western Reserve University
56 @author Brian Fox, Free Software Foundation
59 @vskip 0pt plus 1filll
63 Published by the Free Software Foundation @*
64 59 Temple Place, Suite 330, @*
65 Boston, MA 02111-1307 @*
73 @node Top, Introduction, (dir), (dir)
76 This text is a brief description of the features that are present in
77 the Bash shell (version @value{VERSION}, @value{UPDATED})..
79 This is Edition @value{EDITION}, last updated @value{UPDATED},
80 of @cite{The GNU Bash Reference Manual},
81 for @code{Bash}, Version @value{VERSION}.
83 Bash contains features that appear in other popular shells, and some
84 features that only appear in Bash. Some of the shells that Bash has
85 borrowed concepts from are the Bourne Shell (@file{sh}), the Korn Shell
86 (@file{ksh}), and the C-shell (@file{csh} and its successor,
87 @file{tcsh}). The following menu breaks the features up into
88 categories based upon which one of these other shells inspired the
91 This manual is meant as a brief introduction to features found in
92 Bash. The Bash manual page should be used as the definitive
93 reference on shell behavior.
96 * Introduction:: An introduction to the shell.
98 * Definitions:: Some definitions used in the rest of this
101 * Basic Shell Features:: The shell "building blocks".
103 * Shell Builtin Commands:: Commands that are a part of the shell.
105 * Shell Variables:: Variables used or set by Bash.
107 * Bash Features:: Features found only in Bash.
109 * Job Control:: A chapter describing what job control is
110 and how Bash allows you to use it.
112 * Using History Interactively:: Chapter dealing with history expansion
115 * Command Line Editing:: Chapter describing the command line
118 * Installing Bash:: How to build and install Bash on your system.
120 * Reporting Bugs:: How to report bugs in Bash.
122 * Major Differences From The Bourne Shell:: A terse list of the differences
123 between Bash and historical
126 * Copying This Manual:: Copying this manual.
128 * Builtin Index:: Index of Bash builtin commands.
130 * Reserved Word Index:: Index of Bash reserved words.
132 * Variable Index:: Quick reference helps you find the
135 * Function Index:: Index of bindable Readline functions.
137 * Concept Index:: General index for concepts described in
143 @chapter Introduction
145 * What is Bash?:: A short description of Bash.
147 * What is a shell?:: A brief introduction to shells.
151 @section What is Bash?
153 Bash is the shell, or command language interpreter,
154 for the @sc{gnu} operating system.
155 The name is an acronym for the @samp{Bourne-Again SHell},
156 a pun on Stephen Bourne, the author of the direct ancestor of
157 the current Unix shell @code{sh},
158 which appeared in the Seventh Edition Bell Labs Research version
161 Bash is largely compatible with @code{sh} and incorporates useful
162 features from the Korn shell @code{ksh} and the C shell @code{csh}.
163 It is intended to be a conformant implementation of the @sc{ieee}
164 @sc{posix} Shell and Tools specification (@sc{ieee} Working Group 1003.2).
165 It offers functional improvements over @code{sh} for both interactive and
168 While the @sc{gnu} operating system provides other shells, including
169 a version of @code{csh}, Bash is the default shell.
170 Like other @sc{gnu} software, Bash is quite portable. It currently runs
171 on nearly every version of Unix and a few other operating systems @minus{}
172 independently-supported ports exist for @sc{ms-dos}, @sc{os/2},
173 and Windows platforms.
175 @node What is a shell?
176 @section What is a shell?
178 At its base, a shell is simply a macro processor that executes
179 commands. The term macro processor means functionality where text
180 and symbols are expanded to create larger expressions.
182 A Unix shell is both a command interpreter and a programming
183 language. As a command interpreter, the shell provides the user
184 interface to the rich set of @sc{gnu} utilities. The programming
185 language features allow these utilitites to be combined.
186 Files containing commands can be created, and become
187 commands themselves. These new commands have the same status as
188 system commands in directories such as @file{/bin}, allowing users
189 or groups to establish custom environments to automate their common
192 Shells may be used interactively or non-interactively. In
193 interactive mode, they accept input typed from the keyboard.
194 When executing non-interactively, shells execute commands read
197 A shell allows execution of @sc{gnu} commands, both synchronously and
199 The shell waits for synchronous commands to complete before accepting
200 more input; asynchronous commands continue to execute in parallel
201 with the shell while it reads and executes additional commands.
202 The @dfn{redirection} constructs permit
203 fine-grained control of the input and output of those commands.
204 Moreover, the shell allows control over the contents of commands'
207 Shells also provide a small set of built-in
208 commands (@dfn{builtins}) implementing functionality impossible
209 or inconvenient to obtain via separate utilities.
210 For example, @code{cd}, @code{break}, @code{continue}, and
211 @code{exec}) cannot be implemented outside of the shell because
212 they directly manipulate the shell itself.
213 The @code{history}, @code{getopts}, @code{kill}, or @code{pwd}
214 builtins, among others, could be implemented in separate utilities,
215 but they are more convenient to use as builtin commands.
216 All of the shell builtins are described in
219 While executing commands is essential, most of the power (and
220 complexity) of shells is due to their embedded programming
221 languages. Like any high-level language, the shell provides
222 variables, flow control constructs, quoting, and functions.
224 Shells offer features geared specifically for
225 interactive use rather than to augment the programming language.
226 These interactive features include job control, command line
227 editing, command history and aliases. Each of these features is
228 described in this manual.
232 These definitions are used throughout the remainder of this manual.
238 A family of open system standards based on Unix. Bash
239 is concerned with @sc{posix} 1003.2, the Shell and Tools Standard.
242 A space or tab character.
246 A command that is implemented internally by the shell itself, rather
247 than by an executable program somewhere in the file system.
249 @item control operator
250 @cindex control operator
251 A @code{word} that performs a control function. It is a @code{newline}
252 or one of the following:
253 @samp{||}, @samp{&&}, @samp{&}, @samp{;}, @samp{;;},
254 @samp{|}, @samp{(}, or @samp{)}.
258 The value returned by a command to its caller. The value is restricted
259 to eight bits, so the maximum value is 255.
263 A unit of text that is the result of one of the shell expansions. After
264 expansion, when executing a command, the resulting fields are used as
265 the command name and arguments.
269 A string of characters used to identify a file.
273 A set of processes comprising a pipeline, and any processes descended
274 from it, that are all in the same process group.
278 A mechanism by which users can selectively stop (suspend) and restart
279 (resume) execution of processes.
282 @cindex metacharacter
283 A character that, when unquoted, separates words. A metacharacter is
284 a @code{blank} or one of the following characters:
285 @samp{|}, @samp{&}, @samp{;}, @samp{(}, @samp{)}, @samp{<}, or
291 A @code{word} consisting solely of letters, numbers, and underscores,
292 and beginning with a letter or underscore. @code{Name}s are used as
293 shell variable and function names.
294 Also referred to as an @code{identifier}.
297 @cindex operator, shell
298 A @code{control operator} or a @code{redirection operator}.
299 @xref{Redirections}, for a list of redirection operators.
302 @cindex process group
303 A collection of related processes each having the same process
306 @item process group ID
307 @cindex process group ID
308 A unique identifer that represents a @code{process group}
312 @cindex reserved word
313 A @code{word} that has a special meaning to the shell. Most reserved
314 words introduce shell flow control constructs, such as @code{for} and
318 @cindex return status
319 A synonym for @code{exit status}.
323 A mechanism by which a process may be notified by the kernel
324 of an event occurring in the system.
326 @item special builtin
327 @cindex special builtin
328 A shell builtin command that has been classified as special by the
329 @sc{posix} 1003.2 standard.
333 A sequence of characters considered a single unit by the shell. It is
334 either a @code{word} or an @code{operator}.
338 A @code{token} that is not an @code{operator}.
341 @node Basic Shell Features
342 @chapter Basic Shell Features
345 Bash is an acronym for @samp{Bourne-Again SHell}.
347 the traditional Unix shell originally written by Stephen Bourne.
348 All of the Bourne shell builtin commands are available in Bash,
349 The rules for evaluation and quoting are taken from the @sc{posix}
350 specification for the `standard' Unix shell.
352 This chapter briefly summarizes the shell's `building blocks':
353 commands, control structures, shell functions, shell @i{parameters},
355 @i{redirections}, which are a way to direct input and output from
356 and to named files, and how the shell executes commands.
359 * Shell Syntax:: What your input means to the shell.
360 * Shell Commands:: The types of commands you can use.
361 * Shell Functions:: Grouping commands by name.
362 * Shell Parameters:: How the shell stores values.
363 * Shell Expansions:: How Bash expands parameters and the various
364 expansions available.
365 * Redirections:: A way to control where input and output go.
366 * Executing Commands:: What happens when you run a command.
367 * Shell Scripts:: Executing files of shell commands.
371 @section Shell Syntax
373 * Shell Operation:: The basic operation of the shell.
375 * Quoting:: How to remove the special meaning from characters.
377 * Comments:: How to specify comments.
380 When the shell reads input, it proceeds through a
381 sequence of operations. If the input indicates the beginning of a
382 comment, the shell ignores the comment symbol (@samp{#}), and the rest
385 Otherwise, roughly speaking, the shell reads its input and
386 divides the input into words and operators, employing the quoting rules
387 to select which meanings to assign various words and characters.
389 The shell then parses these tokens into commands and other constructs,
390 removes the special meaning of certain words or characters, expands
391 others, redirects input and output as needed, executes the specified
392 command, waits for the command's exit status, and makes that exit status
393 available for further inspection or processing.
395 @node Shell Operation
396 @subsection Shell Operation
398 The following is a brief description of the shell's operation when it
399 reads and executes a command. Basically, the shell does the
404 Reads its input from a file (@pxref{Shell Scripts}), from a string
405 supplied as an argument to the @option{-c} invocation option
406 (@pxref{Invoking Bash}), or from the user's terminal.
409 Breaks the input into words and operators, obeying the quoting rules
410 described in @ref{Quoting}. These tokens are separated by
411 @code{metacharacters}. Alias expansion is performed by this step
415 Parses the tokens into simple and compound commands
416 (@pxref{Shell Commands}).
419 Performs the various shell expansions (@pxref{Shell Expansions}), breaking
420 the expanded tokens into lists of filenames (@pxref{Filename Expansion})
421 and commands and arguments.
424 Performs any necessary redirections (@pxref{Redirections}) and removes
425 the redirection operators and their operands from the argument list.
428 Executes the command (@pxref{Executing Commands}).
431 Optionally waits for the command to complete and collects its exit
432 status (@pxref{Exit Status}).
440 * Escape Character:: How to remove the special meaning from a single
442 * Single Quotes:: How to inhibit all interpretation of a sequence
444 * Double Quotes:: How to suppress most of the interpretation of a
445 sequence of characters.
446 * ANSI-C Quoting:: How to expand ANSI-C sequences in quoted strings.
448 * Locale Translation:: How to translate strings into different languages.
451 Quoting is used to remove the special meaning of certain
452 characters or words to the shell. Quoting can be used to
453 disable special treatment for special characters, to prevent
454 reserved words from being recognized as such, and to prevent
457 Each of the shell metacharacters (@pxref{Definitions})
458 has special meaning to the shell and must be quoted if it is to
460 When the command history expansion facilities are being used, the
461 @var{history expansion} character, usually @samp{!}, must be quoted
462 to prevent history expansion. @xref{Bash History Facilities}, for
463 more details concerning history expansion.
465 There are three quoting mechanisms: the
466 @var{escape character}, single quotes, and double quotes.
468 @node Escape Character
469 @subsubsection Escape Character
470 A non-quoted backslash @samp{\} is the Bash escape character.
471 It preserves the literal value of the next character that follows,
472 with the exception of @code{newline}. If a @code{\newline} pair
473 appears, and the backslash itself is not quoted, the @code{\newline}
474 is treated as a line continuation (that is, it is removed from
475 the input stream and effectively ignored).
478 @subsubsection Single Quotes
480 Enclosing characters in single quotes (@samp{'}) preserves the literal value
481 of each character within the quotes. A single quote may not occur
482 between single quotes, even when preceded by a backslash.
485 @subsubsection Double Quotes
487 Enclosing characters in double quotes (@samp{"}) preserves the literal value
488 of all characters within the quotes, with the exception of
489 @samp{$}, @samp{`}, and @samp{\}.
490 The characters @samp{$} and @samp{`}
491 retain their special meaning within double quotes (@pxref{Shell Expansions}).
492 The backslash retains its special meaning only when followed by one of
493 the following characters:
494 @samp{$}, @samp{`}, @samp{"}, @samp{\}, or @code{newline}.
495 Within double quotes, backslashes that are followed by one of these
496 characters are removed. Backslashes preceding characters without a
497 special meaning are left unmodified.
498 A double quote may be quoted within double quotes by preceding it with
500 When command history is being used, the double quote may not be used to
501 quote the history expansion character.
503 The special parameters @samp{*} and @samp{@@} have special meaning
504 when in double quotes (@pxref{Shell Parameter Expansion}).
507 @subsubsection ANSI-C Quoting
508 @cindex quoting, ANSI
510 Words of the form @code{$'@var{string}'} are treated specially. The
511 word expands to @var{string}, with backslash-escaped characters replaced
512 as specified by the ANSI C standard. Backslash escape sequences, if
513 present, are decoded as follows:
521 an escape character (not ANSI C)
537 the eight-bit character whose value is the octal value @var{nnn}
538 (one to three digits)
540 the eight-bit character whose value is the hexadecimal value @var{HH}
541 (one or two hex digits)
543 a control-@var{x} character
547 The expanded result is single-quoted, as if the dollar sign had not
550 @node Locale Translation
551 @subsubsection Locale-Specific Translation
553 @cindex internationalization
554 @cindex native languages
555 @cindex translation, native languages
557 A double-quoted string preceded by a dollar sign (@samp{$}) will cause
558 the string to be translated according to the current locale.
559 If the current locale is @code{C} or @code{POSIX}, the dollar sign
561 If the string is translated and replaced, the replacement is
566 @vindex TEXTDOMAINDIR
567 Some systems use the message catalog selected by the @env{LC_MESSAGES}
568 shell variable. Others create the name of the message catalog from the
569 value of the @env{TEXTDOMAIN} shell variable, possibly adding a
570 suffix of @samp{.mo}. If you use the @env{TEXTDOMAIN} variable, you
571 may need to set the @env{TEXTDOMAINDIR} variable to the location of
572 the message catalog files. Still others use both variables in this
574 @env{TEXTDOMAINDIR}/@env{LC_MESSAGES}/LC_MESSAGES/@env{TEXTDOMAIN}.mo.
578 @cindex comments, shell
580 In a non-interactive shell, or an interactive shell in which the
581 @code{interactive_comments} option to the @code{shopt}
582 builtin is enabled (@pxref{Bash Builtins}),
583 a word beginning with @samp{#}
584 causes that word and all remaining characters on that line to
585 be ignored. An interactive shell without the @code{interactive_comments}
586 option enabled does not allow comments. The @code{interactive_comments}
587 option is on by default in interactive shells.
588 @xref{Interactive Shells}, for a description of what makes
592 @section Shell Commands
593 @cindex commands, shell
595 A simple shell command such as @code{echo a b c} consists of the command
596 itself followed by arguments, separated by spaces.
598 More complex shell commands are composed of simple commands arranged together
599 in a variety of ways: in a pipeline in which the output of one command
600 becomes the input of a second, in a loop or conditional construct, or in
604 * Simple Commands:: The most common type of command.
605 * Pipelines:: Connecting the input and output of several
607 * Lists:: How to execute commands sequentially.
608 * Compound Commands:: Shell commands for control flow.
611 @node Simple Commands
612 @subsection Simple Commands
613 @cindex commands, simple
615 A simple command is the kind of command encountered most often.
616 It's just a sequence of words separated by @code{blank}s, terminated
617 by one of the shell's control operators (@pxref{Definitions}). The
618 first word generally specifies a command to be executed, with the
619 rest of the words being that command's arguments.
621 The return status (@pxref{Exit Status}) of a simple command is
622 its exit status as provided
623 by the @sc{posix} 1003.1 @code{waitpid} function, or 128+@var{n} if
624 the command was terminated by signal @var{n}.
627 @subsection Pipelines
629 @cindex commands, pipelines
631 A @code{pipeline} is a sequence of simple commands separated by
636 @cindex command timing
637 The format for a pipeline is
639 [@code{time} [@code{-p}]] [@code{!}] @var{command1} [@code{|} @var{command2} @dots{}]
643 The output of each command in the pipeline is connected via a pipe
644 to the input of the next command.
645 That is, each command reads the previous command's output.
647 The reserved word @code{time} causes timing statistics
648 to be printed for the pipeline once it finishes.
649 The statistics currently consist of elapsed (wall-clock) time and
650 user and system time consumed by the command's execution.
651 The @option{-p} option changes the output format to that specified
653 The @env{TIMEFORMAT} variable may be set to a format string that
654 specifies how the timing information should be displayed.
655 @xref{Bash Variables}, for a description of the available formats.
656 The use of @code{time} as a reserved word permits the timing of
657 shell builtins, shell functions, and pipelines. An external
658 @code{time} command cannot time these easily.
660 If the pipeline is not executed asynchronously (@pxref{Lists}), the
661 shell waits for all commands in the pipeline to complete.
663 Each command in a pipeline is executed in its own subshell
664 (@pxref{Command Execution Environment}). The exit
665 status of a pipeline is the exit status of the last command in the
666 pipeline, unless the @code{pipefail} option is enabled
667 (@pxref{The Set Builtin}).
668 If @code{pipefail} is enabled, the pipeline's return status is the
669 value of the last (rightmost) command to exit with a non-zero status,
670 or zero if all commands exit successfully.
671 If the reserved word @samp{!} precedes the pipeline, the
672 exit status is the logical negation of the exit status as described
674 The shell waits for all commands in the pipeline to terminate before
678 @subsection Lists of Commands
679 @cindex commands, lists
681 A @code{list} is a sequence of one or more pipelines separated by one
682 of the operators @samp{;}, @samp{&}, @samp{&&}, or @samp{||},
683 and optionally terminated by one of @samp{;}, @samp{&}, or a
686 Of these list operators, @samp{&&} and @samp{||}
687 have equal precedence, followed by @samp{;} and @samp{&},
688 which have equal precedence.
690 A sequence of one or more newlines may appear in a @code{list}
691 to delimit commands, equivalent to a semicolon.
693 If a command is terminated by the control operator @samp{&},
694 the shell executes the command asynchronously in a subshell.
695 This is known as executing the command in the @var{background}.
696 The shell does not wait for the command to finish, and the return
698 When job control is not active (@pxref{Job Control}),
699 the standard input for asynchronous commands, in the absence of any
700 explicit redirections, is redirected from @code{/dev/null}.
702 Commands separated by a @samp{;} are executed sequentially; the shell
703 waits for each command to terminate in turn. The return status is the
704 exit status of the last command executed.
706 The control operators @samp{&&} and @samp{||}
707 denote @sc{and} lists and @sc{or} lists, respectively.
708 An @sc{and} list has the form
710 @var{command1} && @var{command2}
714 @var{command2} is executed if, and only if, @var{command1}
715 returns an exit status of zero.
717 An @sc{or} list has the form
719 @var{command1} || @var{command2}
723 @var{command2} is executed if, and only if, @var{command1}
724 returns a non-zero exit status.
727 @sc{and} and @sc{or} lists is the exit status of the last command
728 executed in the list.
730 @node Compound Commands
731 @subsection Compound Commands
732 @cindex commands, compound
735 * Looping Constructs:: Shell commands for iterative action.
736 * Conditional Constructs:: Shell commands for conditional execution.
737 * Command Grouping:: Ways to group commands.
740 Compound commands are the shell programming constructs.
741 Each construct begins with a reserved word or control operator and is
742 terminated by a corresponding reserved word or operator.
743 Any redirections (@pxref{Redirections}) associated with a compound command
744 apply to all commands within that compound command unless explicitly overridden.
746 Bash provides looping constructs, conditional commands, and mechanisms
747 to group commands and execute them as a unit.
749 @node Looping Constructs
750 @subsubsection Looping Constructs
751 @cindex commands, looping
753 Bash supports the following looping constructs.
755 Note that wherever a @samp{;} appears in the description of a
756 command's syntax, it may be replaced with one or more newlines.
763 The syntax of the @code{until} command is:
765 until @var{test-commands}; do @var{consequent-commands}; done
767 Execute @var{consequent-commands} as long as
768 @var{test-commands} has an exit status which is not zero.
769 The return status is the exit status of the last command executed
770 in @var{consequent-commands}, or zero if none was executed.
774 The syntax of the @code{while} command is:
776 while @var{test-commands}; do @var{consequent-commands}; done
779 Execute @var{consequent-commands} as long as
780 @var{test-commands} has an exit status of zero.
781 The return status is the exit status of the last command executed
782 in @var{consequent-commands}, or zero if none was executed.
786 The syntax of the @code{for} command is:
789 for @var{name} [in @var{words} @dots{}]; do @var{commands}; done
791 Expand @var{words}, and execute @var{commands} once for each member
792 in the resultant list, with @var{name} bound to the current member.
793 If @samp{in @var{words}} is not present, the @code{for} command
794 executes the @var{commands} once for each positional parameter that is
795 set, as if @samp{in "$@@"} had been specified
796 (@pxref{Special Parameters}).
797 The return status is the exit status of the last command that executes.
798 If there are no items in the expansion of @var{words}, no commands are
799 executed, and the return status is zero.
801 An alternate form of the @code{for} command is also supported:
804 for (( @var{expr1} ; @var{expr2} ; @var{expr3} )) ; do @var{commands} ; done
806 First, the arithmetic expression @var{expr1} is evaluated according
807 to the rules described below (@pxref{Shell Arithmetic}).
808 The arithmetic expression @var{expr2} is then evaluated repeatedly
809 until it evaluates to zero.
810 Each time @var{expr2} evaluates to a non-zero value, @var{commands} are
811 executed and the arithmetic expression @var{expr3} is evaluated.
812 If any expression is omitted, it behaves as if it evaluates to 1.
813 The return value is the exit status of the last command in @var{list}
814 that is executed, or false if any of the expressions is invalid.
818 The @code{break} and @code{continue} builtins (@pxref{Bourne Shell Builtins})
819 may be used to control loop execution.
821 @node Conditional Constructs
822 @subsubsection Conditional Constructs
823 @cindex commands, conditional
832 The syntax of the @code{if} command is:
835 if @var{test-commands}; then
836 @var{consequent-commands};
837 [elif @var{more-test-commands}; then
838 @var{more-consequents};]
839 [else @var{alternate-consequents};]
843 The @var{test-commands} list is executed, and if its return status is zero,
844 the @var{consequent-commands} list is executed.
845 If @var{test-commands} returns a non-zero status, each @code{elif} list
846 is executed in turn, and if its exit status is zero,
847 the corresponding @var{more-consequents} is executed and the
849 If @samp{else @var{alternate-consequents}} is present, and
850 the final command in the final @code{if} or @code{elif} clause
851 has a non-zero exit status, then @var{alternate-consequents} is executed.
852 The return status is the exit status of the last command executed, or
853 zero if no condition tested true.
859 The syntax of the @code{case} command is:
862 @code{case @var{word} in [ [(] @var{pattern} [| @var{pattern}]@dots{}) @var{command-list} ;;]@dots{} esac}
865 @code{case} will selectively execute the @var{command-list} corresponding to
866 the first @var{pattern} that matches @var{word}.
867 The @samp{|} is used to separate multiple patterns, and the @samp{)}
868 operator terminates a pattern list.
869 A list of patterns and an associated command-list is known
870 as a @var{clause}. Each clause must be terminated with @samp{;;}.
871 The @var{word} undergoes tilde expansion, parameter expansion, command
872 substitution, arithmetic expansion, and quote removal before matching is
873 attempted. Each @var{pattern} undergoes tilde expansion, parameter
874 expansion, command substitution, and arithmetic expansion.
876 There may be an arbitrary number of @code{case} clauses, each terminated
877 by a @samp{;;}. The first pattern that matches determines the
878 command-list that is executed.
880 Here is an example using @code{case} in a script that could be used to
881 describe one interesting feature of an animal:
884 echo -n "Enter the name of an animal: "
886 echo -n "The $ANIMAL has "
888 horse | dog | cat) echo -n "four";;
889 man | kangaroo ) echo -n "two";;
890 *) echo -n "an unknown number of";;
896 The return status is zero if no @var{pattern} is matched. Otherwise, the
897 return status is the exit status of the @var{command-list} executed.
902 The @code{select} construct allows the easy generation of menus.
903 It has almost the same syntax as the @code{for} command:
906 select @var{name} [in @var{words} @dots{}]; do @var{commands}; done
909 The list of words following @code{in} is expanded, generating a list
910 of items. The set of expanded words is printed on the standard
911 error output stream, each preceded by a number. If the
912 @samp{in @var{words}} is omitted, the positional parameters are printed,
913 as if @samp{in "$@@"} had been specifed.
914 The @env{PS3} prompt is then displayed and a line is read from the
916 If the line consists of a number corresponding to one of the displayed
917 words, then the value of @var{name} is set to that word.
918 If the line is empty, the words and prompt are displayed again.
919 If @code{EOF} is read, the @code{select} command completes.
920 Any other value read causes @var{name} to be set to null.
921 The line read is saved in the variable @env{REPLY}.
923 The @var{commands} are executed after each selection until a
924 @code{break} command is executed, at which
925 point the @code{select} command completes.
927 Here is an example that allows the user to pick a filename from the
928 current directory, and displays the name and index of the file
934 echo you picked $fname \($REPLY\)
941 (( @var{expression} ))
944 The arithmetic @var{expression} is evaluated according to the rules
945 described below (@pxref{Shell Arithmetic}).
946 If the value of the expression is non-zero, the return status is 0;
947 otherwise the return status is 1. This is exactly equivalent to
949 let "@var{expression}"
952 @xref{Bash Builtins}, for a full description of the @code{let} builtin.
958 [[ @var{expression} ]]
961 Return a status of 0 or 1 depending on the evaluation of
962 the conditional expression @var{expression}.
963 Expressions are composed of the primaries described below in
964 @ref{Bash Conditional Expressions}.
965 Word splitting and filename expansion are not performed on the words
966 between the @samp{[[} and @samp{]]}; tilde expansion, parameter and
967 variable expansion, arithmetic expansion, command substitution, process
968 substitution, and quote removal are performed.
969 Conditional operators such as @samp{-f} must be unquoted to be recognized
972 When the @samp{==} and @samp{!=} operators are used, the string to the
973 right of the operator is considered a pattern and matched according
974 to the rules described below in @ref{Pattern Matching}.
975 The return value is 0 if the string matches or does not match
976 the pattern, respectively, and 1 otherwise.
977 Any part of the pattern may be quoted to force it to be matched as a
980 An additional binary operator, @samp{=~}, is available, with the same
981 precedence as @samp{==} and @samp{!=}.
982 When it is used, the string to the right of the operator is considered
983 an extended regular expression and matched accordingly (as in @i{regex}3)).
984 The return value is 0 if the string matches
985 the pattern, and 1 otherwise.
986 If the regular expression is syntactically incorrect, the conditional
987 expression's return value is 2.
988 If the shell option @code{nocaseglob}
989 (see the description of @code{shopt} in @ref{Bash Builtins})
990 is enabled, the match is performed without regard to the case
991 of alphabetic characters.
992 Substrings matched by parenthesized subexpressions within the regular
993 expression are saved in the array variable @code{BASH_REMATCH}.
994 The element of @code{BASH_REMATCH} with index 0 is the portion of the string
995 matching the entire regular expression.
996 The element of @code{BASH_REMATCH} with index @var{n} is the portion of the
997 string matching the @var{n}th parenthesized subexpression.
999 Expressions may be combined using the following operators, listed
1000 in decreasing order of precedence:
1003 @item ( @var{expression} )
1004 Returns the value of @var{expression}.
1005 This may be used to override the normal precedence of operators.
1007 @item ! @var{expression}
1008 True if @var{expression} is false.
1010 @item @var{expression1} && @var{expression2}
1011 True if both @var{expression1} and @var{expression2} are true.
1013 @item @var{expression1} || @var{expression2}
1014 True if either @var{expression1} or @var{expression2} is true.
1017 The @code{&&} and @code{||} operators do not evaluate @var{expression2} if the
1018 value of @var{expression1} is sufficient to determine the return
1019 value of the entire conditional expression.
1023 @node Command Grouping
1024 @subsubsection Grouping Commands
1025 @cindex commands, grouping
1027 Bash provides two ways to group a list of commands to be executed
1028 as a unit. When commands are grouped, redirections may be applied
1029 to the entire command list. For example, the output of all the
1030 commands in the list may be redirected to a single stream.
1038 Placing a list of commands between parentheses causes a subshell
1039 environment to be created (@pxref{Command Execution Environment}), and each
1040 of the commands in @var{list} to be executed in that subshell. Since the
1041 @var{list} is executed in a subshell, variable assignments do not remain in
1042 effect after the subshell completes.
1051 Placing a list of commands between curly braces causes the list to
1052 be executed in the current shell context. No subshell is created.
1053 The semicolon (or newline) following @var{list} is required.
1056 In addition to the creation of a subshell, there is a subtle difference
1057 between these two constructs due to historical reasons. The braces
1058 are @code{reserved words}, so they must be separated from the @var{list}
1059 by @code{blank}s. The parentheses are @code{operators}, and are
1060 recognized as separate tokens by the shell even if they are not separated
1061 from the @var{list} by whitespace.
1063 The exit status of both of these constructs is the exit status of
1066 @node Shell Functions
1067 @section Shell Functions
1068 @cindex shell function
1069 @cindex functions, shell
1071 Shell functions are a way to group commands for later execution
1072 using a single name for the group. They are executed just like
1073 a "regular" command.
1074 When the name of a shell function is used as a simple command name,
1075 the list of commands associated with that function name is executed.
1076 Shell functions are executed in the current
1077 shell context; no new process is created to interpret them.
1079 Functions are declared using this syntax:
1082 [ @code{function} ] @var{name} () @var{compound-command} [ @var{redirections} ]
1085 This defines a shell function named @var{name}. The reserved
1086 word @code{function} is optional.
1087 If the @code{function} reserved
1088 word is supplied, the parentheses are optional.
1089 The @var{body} of the function is the compound command
1090 @var{compound-command} (@pxref{Compound Commands}).
1091 That command is usually a @var{list} enclosed between @{ and @}, but
1092 may be any compound command listed above.
1093 @var{compound-command} is executed whenever @var{name} is specified as the
1095 Any redirections (@pxref{Redirections}) associated with the shell function
1096 are performed when the function is executed.
1098 The exit status of a function definition is zero unless a syntax error
1099 occurs or a readonly function with the same name already exists.
1100 When executed, the exit status of a function is the exit status of the
1101 last command executed in the body.
1103 Note that for historical reasons, in the most common usage the curly braces
1104 that surround the body of the function must be separated from the body by
1105 @code{blank}s or newlines.
1106 This is because the braces are reserved words and are only recognized
1107 as such when they are separated by whitespace.
1108 Also, when using the braces, the @var{list} must be terminated by a semicolon,
1109 a @samp{&}, or a newline.
1111 When a function is executed, the arguments to the
1112 function become the positional parameters
1113 during its execution (@pxref{Positional Parameters}).
1114 The special parameter @samp{#} that expands to the number of
1115 positional parameters is updated to reflect the change.
1116 Special parameter @code{0} is unchanged.
1117 The first element of the @env{FUNCNAME} variable is set to the
1118 name of the function while the function is executing.
1119 All other aspects of the shell execution
1120 environment are identical between a function and its caller
1121 with the exception that the @env{DEBUG} trap
1122 below) is not inherited unless the function has been given the
1123 @code{trace} attribute using the @code{declare} builtin or
1124 the @code{-o functrace} option has been enabled with
1125 the @code{set} builtin,
1126 (in which case all functions inherit the @code{DEBUG} trap).
1127 @xref{Bourne Shell Builtins}, for the description of the
1128 @code{trap} builtin.
1130 If the builtin command @code{return}
1131 is executed in a function, the function completes and
1132 execution resumes with the next command after the function
1134 Any command associated with the @code{RETURN} trap is executed
1135 before execution resumes.
1136 When a function completes, the values of the
1137 positional parameters and the special parameter @samp{#}
1138 are restored to the values they had prior to the function's
1139 execution. If a numeric argument is given to @code{return},
1140 that is the function's return status; otherwise the function's
1141 return status is the exit status of the last command executed
1142 before the @code{return}.
1144 Variables local to the function may be declared with the
1145 @code{local} builtin. These variables are visible only to
1146 the function and the commands it invokes.
1148 Function names and definitions may be listed with the
1149 @option{-f} option to the @code{declare} or @code{typeset}
1150 builtin commands (@pxref{Bash Builtins}).
1151 The @option{-F} option to @code{declare} or @code{typeset}
1152 will list the function names only
1153 (and optionally the source file and line number, if the @code{extdebug}
1154 shell option is enabled).
1155 Functions may be exported so that subshells
1156 automatically have them defined with the
1157 @option{-f} option to the @code{export} builtin
1158 (@pxref{Bourne Shell Builtins}).
1159 Note that shell functions and variables with the same name may result
1160 in multiple identically-named entries in the environment passed to the
1162 Care should be taken in cases where this may cause a problem.
1164 Functions may be recursive. No limit is placed on the number of
1167 @node Shell Parameters
1168 @section Shell Parameters
1170 @cindex variable, shell
1171 @cindex shell variable
1174 * Positional Parameters:: The shell's command-line arguments.
1175 * Special Parameters:: Parameters denoted by special characters.
1178 A @var{parameter} is an entity that stores values.
1179 It can be a @code{name}, a number, or one of the special characters
1181 A @var{variable} is a parameter denoted by a @code{name}.
1182 A variable has a @var{value} and zero or more @var{attributes}.
1183 Attributes are assigned using the @code{declare} builtin command
1184 (see the description of the @code{declare} builtin in @ref{Bash Builtins}).
1186 A parameter is set if it has been assigned a value. The null string is
1187 a valid value. Once a variable is set, it may be unset only by using
1188 the @code{unset} builtin command.
1190 A variable may be assigned to by a statement of the form
1192 @var{name}=[@var{value}]
1196 is not given, the variable is assigned the null string. All
1197 @var{value}s undergo tilde expansion, parameter and variable expansion,
1198 command substitution, arithmetic expansion, and quote
1199 removal (detailed below). If the variable has its @code{integer}
1200 attribute set, then @var{value}
1201 is evaluated as an arithmetic expression even if the @code{$((@dots{}))}
1202 expansion is not used (@pxref{Arithmetic Expansion}).
1203 Word splitting is not performed, with the exception
1204 of @code{"$@@"} as explained below.
1205 Filename expansion is not performed.
1206 Assignment statements may also appear as arguments to the
1208 @code{declare}, @code{typeset}, @code{export}, @code{readonly},
1209 and @code{local} builtin commands.
1211 @node Positional Parameters
1212 @subsection Positional Parameters
1213 @cindex parameters, positional
1215 A @var{positional parameter} is a parameter denoted by one or more
1216 digits, other than the single digit @code{0}. Positional parameters are
1217 assigned from the shell's arguments when it is invoked,
1218 and may be reassigned using the @code{set} builtin command.
1219 Positional parameter @code{N} may be referenced as @code{$@{N@}}, or
1220 as @code{$N} when @code{N} consists of a single digit.
1221 Positional parameters may not be assigned to with assignment statements.
1222 The @code{set} and @code{shift} builtins are used to set and
1223 unset them (@pxref{Shell Builtin Commands}).
1224 The positional parameters are
1225 temporarily replaced when a shell function is executed
1226 (@pxref{Shell Functions}).
1228 When a positional parameter consisting of more than a single
1229 digit is expanded, it must be enclosed in braces.
1231 @node Special Parameters
1232 @subsection Special Parameters
1233 @cindex parameters, special
1235 The shell treats several parameters specially. These parameters may
1236 only be referenced; assignment to them is not allowed.
1241 Expands to the positional parameters, starting from one. When the
1242 expansion occurs within double quotes, it expands to a single word
1243 with the value of each parameter separated by the first character
1245 special variable. That is, @code{"$*"} is equivalent
1246 to @code{"$1@var{c}$2@var{c}@dots{}"}, where @var{c}
1247 is the first character of the value of the @code{IFS}
1249 If @env{IFS} is unset, the parameters are separated by spaces.
1250 If @env{IFS} is null, the parameters are joined without intervening
1255 Expands to the positional parameters, starting from one. When the
1256 expansion occurs within double quotes, each parameter expands to a
1257 separate word. That is, @code{"$@@"} is equivalent to
1258 @code{"$1" "$2" @dots{}}.
1259 When there are no positional parameters, @code{"$@@"} and
1261 expand to nothing (i.e., they are removed).
1264 Expands to the number of positional parameters in decimal.
1267 Expands to the exit status of the most recently executed foreground
1271 (A hyphen.) Expands to the current option flags as specified upon
1272 invocation, by the @code{set}
1273 builtin command, or those set by the shell itself
1274 (such as the @option{-i} option).
1277 Expands to the process @sc{id} of the shell. In a @code{()} subshell, it
1278 expands to the process @sc{id} of the invoking shell, not the subshell.
1281 Expands to the process @sc{id} of the most recently executed background
1282 (asynchronous) command.
1285 Expands to the name of the shell or shell script. This is set at
1286 shell initialization. If Bash is invoked with a file of commands
1287 (@pxref{Shell Scripts}), @code{$0} is set to the name of that file.
1288 If Bash is started with the @option{-c} option (@pxref{Invoking Bash}),
1289 then @code{$0} is set to the first argument after the string to be
1290 executed, if one is present. Otherwise, it is set
1291 to the filename used to invoke Bash, as given by argument zero.
1295 At shell startup, set to the absolute filename of the shell or shell
1296 script being executed as passed in the argument list.
1297 Subsequently, expands to the last argument to the previous command,
1299 Also set to the full pathname of each command executed and placed in
1300 the environment exported to that command.
1301 When checking mail, this parameter holds the name of the mail file.
1304 @node Shell Expansions
1305 @section Shell Expansions
1308 Expansion is performed on the command line after it has been split into
1309 @code{token}s. There are seven kinds of expansion performed:
1311 @item brace expansion
1312 @item tilde expansion
1313 @item parameter and variable expansion
1314 @item command substitution
1315 @item arithmetic expansion
1316 @item word splitting
1317 @item filename expansion
1321 * Brace Expansion:: Expansion of expressions within braces.
1322 * Tilde Expansion:: Expansion of the ~ character.
1323 * Shell Parameter Expansion:: How Bash expands variables to their values.
1324 * Command Substitution:: Using the output of a command as an argument.
1325 * Arithmetic Expansion:: How to use arithmetic in shell expansions.
1326 * Process Substitution:: A way to write and read to and from a
1328 * Word Splitting:: How the results of expansion are split into separate
1330 * Filename Expansion:: A shorthand for specifying filenames matching patterns.
1331 * Quote Removal:: How and when quote characters are removed from
1335 The order of expansions is: brace expansion, tilde expansion,
1336 parameter, variable, and arithmetic expansion and
1337 command substitution
1338 (done in a left-to-right fashion), word splitting, and filename
1341 On systems that can support it, there is an additional expansion
1342 available: @var{process substitution}. This is performed at the
1343 same time as parameter, variable, and arithmetic expansion and
1344 command substitution.
1346 Only brace expansion, word splitting, and filename expansion
1347 can change the number of words of the expansion; other expansions
1348 expand a single word to a single word.
1349 The only exceptions to this are the expansions of
1350 @code{"$@@"} (@pxref{Special Parameters}) and @code{"$@{@var{name}[@@]@}"}
1353 After all expansions, @code{quote removal} (@pxref{Quote Removal})
1356 @node Brace Expansion
1357 @subsection Brace Expansion
1358 @cindex brace expansion
1359 @cindex expansion, brace
1361 Brace expansion is a mechanism by which arbitrary strings may be generated.
1362 This mechanism is similar to
1363 @var{filename expansion} (@pxref{Filename Expansion}),
1364 but the file names generated need not exist.
1365 Patterns to be brace expanded take the form of an optional @var{preamble},
1366 followed by either a series of comma-separated strings or a sequnce expression
1367 between a pair of braces,
1368 followed by an optional @var{postscript}.
1369 The preamble is prefixed to each string contained within the braces, and
1370 the postscript is then appended to each resulting string, expanding left
1373 Brace expansions may be nested.
1374 The results of each expanded string are not sorted; left to right order
1378 bash$ echo a@{d,c,b@}e
1382 A sequence expression takes the form @code{@{@var{x}..@var{y}@}},
1383 where @var{x} and @var{y} are either integers or single characters.
1384 When integers are supplied, the expression expands to each number between
1385 @var{x} and @var{y}, inclusive.
1386 When characters are supplied, the expression expands to each character
1387 lexicographically between @var{x} and @var{y}, inclusive. Note that
1388 both @var{x} and @var{y} must be of the same type.
1390 Brace expansion is performed before any other expansions,
1391 and any characters special to other expansions are preserved
1392 in the result. It is strictly textual. Bash
1393 does not apply any syntactic interpretation to the context of the
1394 expansion or the text between the braces.
1395 To avoid conflicts with parameter expansion, the string @samp{$@{}
1396 is not considered eligible for brace expansion.
1398 A correctly-formed brace expansion must contain unquoted opening
1399 and closing braces, and at least one unquoted comma or a valid
1400 sequence expression.
1401 Any incorrectly formed brace expansion is left unchanged.
1403 A @{ or @samp{,} may be quoted with a backslash to prevent its
1404 being considered part of a brace expression.
1405 To avoid conflicts with parameter expansion, the string @samp{$@{}
1406 is not considered eligible for brace expansion.
1408 This construct is typically used as shorthand when the common
1409 prefix of the strings to be generated is longer than in the
1412 mkdir /usr/local/src/bash/@{old,new,dist,bugs@}
1416 chown root /usr/@{ucb/@{ex,edit@},lib/@{ex?.?*,how_ex@}@}
1419 @node Tilde Expansion
1420 @subsection Tilde Expansion
1421 @cindex tilde expansion
1422 @cindex expansion, tilde
1424 If a word begins with an unquoted tilde character (@samp{~}), all of the
1425 characters up to the first unquoted slash (or all characters,
1426 if there is no unquoted slash) are considered a @var{tilde-prefix}.
1427 If none of the characters in the tilde-prefix are quoted, the
1428 characters in the tilde-prefix following the tilde are treated as a
1429 possible @var{login name}.
1430 If this login name is the null string, the tilde is replaced with the
1431 value of the @env{HOME} shell variable.
1432 If @env{HOME} is unset, the home directory of the user executing the
1433 shell is substituted instead.
1434 Otherwise, the tilde-prefix is replaced with the home directory
1435 associated with the specified login name.
1437 If the tilde-prefix is @samp{~+}, the value of
1438 the shell variable @env{PWD} replaces the tilde-prefix.
1439 If the tilde-prefix is @samp{~-}, the value of the shell variable
1440 @env{OLDPWD}, if it is set, is substituted.
1442 If the characters following the tilde in the tilde-prefix consist of a
1443 number @var{N}, optionally prefixed by a @samp{+} or a @samp{-},
1444 the tilde-prefix is replaced with the
1445 corresponding element from the directory stack, as it would be displayed
1446 by the @code{dirs} builtin invoked with the characters following tilde
1447 in the tilde-prefix as an argument (@pxref{The Directory Stack}).
1448 If the tilde-prefix, sans the tilde, consists of a number without a
1449 leading @samp{+} or @samp{-}, @samp{+} is assumed.
1451 If the login name is invalid, or the tilde expansion fails, the word is
1454 Each variable assignment is checked for unquoted tilde-prefixes immediately
1455 following a @samp{:} or @samp{=}.
1456 In these cases, tilde expansion is also performed.
1457 Consequently, one may use file names with tildes in assignments to
1458 @env{PATH}, @env{MAILPATH}, and @env{CDPATH},
1459 and the shell assigns the expanded value.
1461 The following table shows how Bash treats unquoted tilde-prefixes:
1465 The value of @code{$HOME}
1470 The subdirectory @code{foo} of the home directory of the user
1477 @file{$@{OLDPWD-'~-'@}/foo}
1480 The string that would be displayed by @samp{dirs +@var{N}}
1483 The string that would be displayed by @samp{dirs +@var{N}}
1486 The string that would be displayed by @samp{dirs -@var{N}}
1490 @node Shell Parameter Expansion
1491 @subsection Shell Parameter Expansion
1492 @cindex parameter expansion
1493 @cindex expansion, parameter
1495 The @samp{$} character introduces parameter expansion,
1496 command substitution, or arithmetic expansion. The parameter name
1497 or symbol to be expanded may be enclosed in braces, which
1498 are optional but serve to protect the variable to be expanded from
1499 characters immediately following it which could be
1500 interpreted as part of the name.
1502 When braces are used, the matching ending brace is the first @samp{@}}
1503 not escaped by a backslash or within a quoted string, and not within an
1504 embedded arithmetic expansion, command substitution, or parameter
1507 The basic form of parameter expansion is $@{@var{parameter}@}.
1508 The value of @var{parameter} is substituted. The braces are required
1509 when @var{parameter}
1510 is a positional parameter with more than one digit,
1511 or when @var{parameter}
1512 is followed by a character that is not to be
1513 interpreted as part of its name.
1515 If the first character of @var{parameter} is an exclamation point,
1516 a level of variable indirection is introduced.
1517 Bash uses the value of the variable formed from the rest of
1518 @var{parameter} as the name of the variable; this variable is then
1519 expanded and that value is used in the rest of the substitution, rather
1520 than the value of @var{parameter} itself.
1521 This is known as @code{indirect expansion}.
1522 The exceptions to this are the expansions of $@{!@var{prefix*}@}
1523 and $@{!@var{name}[@@]@}
1525 The exclamation point must immediately follow the left brace in order to
1526 introduce indirection.
1528 In each of the cases below, @var{word} is subject to tilde expansion,
1529 parameter expansion, command substitution, and arithmetic expansion.
1531 When not performing substring expansion, Bash tests for a parameter
1532 that is unset or null; omitting the colon results in a test only for a
1533 parameter that is unset. Put another way, if the colon is included,
1534 the operator tests for both existence and that the value is not null;
1535 if the colon is omitted, the operator tests only for existence.
1539 @item $@{@var{parameter}:@minus{}@var{word}@}
1540 If @var{parameter} is unset or null, the expansion of
1541 @var{word} is substituted. Otherwise, the value of
1542 @var{parameter} is substituted.
1544 @item $@{@var{parameter}:=@var{word}@}
1546 is unset or null, the expansion of @var{word}
1547 is assigned to @var{parameter}.
1548 The value of @var{parameter} is then substituted.
1549 Positional parameters and special parameters may not be assigned to
1552 @item $@{@var{parameter}:?@var{word}@}
1554 is null or unset, the expansion of @var{word} (or a message
1555 to that effect if @var{word}
1556 is not present) is written to the standard error and the shell, if it
1557 is not interactive, exits. Otherwise, the value of @var{parameter} is
1560 @item $@{@var{parameter}:+@var{word}@}
1562 is null or unset, nothing is substituted, otherwise the expansion of
1563 @var{word} is substituted.
1565 @item $@{@var{parameter}:@var{offset}@}
1566 @itemx $@{@var{parameter}:@var{offset}:@var{length}@}
1567 Expands to up to @var{length} characters of @var{parameter}
1568 starting at the character specified by @var{offset}.
1569 If @var{length} is omitted, expands to the substring of
1570 @var{parameter} starting at the character specified by @var{offset}.
1571 @var{length} and @var{offset} are arithmetic expressions
1572 (@pxref{Shell Arithmetic}).
1573 This is referred to as Substring Expansion.
1575 @var{length} must evaluate to a number greater than or equal to zero.
1576 If @var{offset} evaluates to a number less than zero, the value
1577 is used as an offset from the end of the value of @var{parameter}.
1578 If @var{parameter} is @samp{@@}, the result is @var{length} positional
1579 parameters beginning at @var{offset}.
1580 If @var{parameter} is an array name indexed by @samp{@@} or @samp{*},
1581 the result is the @var{length}
1582 members of the array beginning with @code{$@{@var{parameter}[@var{offset}]@}}.
1583 Substring indexing is zero-based unless the positional parameters
1584 are used, in which case the indexing starts at 1.
1586 @item $@{!@var{prefix}*@}
1587 @itemx $@{!@var{prefix}@@@}
1588 Expands to the names of variables whose names begin with @var{prefix},
1589 separated by the first character of the @env{IFS} special variable.
1591 @item $@{!@var{name}[@@]@}
1592 @itemx $@{!@var{name}[*]@}
1593 If @var{name} is an array variable, expands to the list of array indices
1594 (keys) assigned in @var{name}.
1595 If @var{name} is not an array, expands to 0 if @var{name} is set and null
1597 When @samp{@@} is used and the expansion appears within double quotes, each
1598 key expands to a separate word.
1600 @item $@{#@var{parameter}@}
1601 The length in characters of the expanded value of @var{parameter} is
1603 If @var{parameter} is @samp{*} or @samp{@@}, the value substituted
1604 is the number of positional parameters.
1605 If @var{parameter} is an array name subscripted by @samp{*} or @samp{@@},
1606 the value substituted is the number of elements in the array.
1608 @item $@{@var{parameter}#@var{word}@}
1609 @itemx $@{@var{parameter}##@var{word}@}
1611 is expanded to produce a pattern just as in filename
1612 expansion (@pxref{Filename Expansion}). If the pattern matches
1613 the beginning of the expanded value of @var{parameter},
1614 then the result of the expansion is the expanded value of @var{parameter}
1615 with the shortest matching pattern (the @samp{#} case) or the
1616 longest matching pattern (the @samp{##} case) deleted.
1617 If @var{parameter} is @samp{@@} or @samp{*},
1618 the pattern removal operation is applied to each positional
1619 parameter in turn, and the expansion is the resultant list.
1620 If @var{parameter} is an array variable subscripted with
1621 @samp{@@} or @samp{*},
1622 the pattern removal operation is applied to each member of the
1623 array in turn, and the expansion is the resultant list.
1625 @item $@{@var{parameter}%@var{word}@}
1626 @itemx $@{@var{parameter}%%@var{word}@}
1627 The @var{word} is expanded to produce a pattern just as in
1629 If the pattern matches a trailing portion of the expanded value of
1630 @var{parameter}, then the result of the expansion is the value of
1631 @var{parameter} with the shortest matching pattern (the @samp{%} case)
1632 or the longest matching pattern (the @samp{%%} case) deleted.
1633 If @var{parameter} is @samp{@@} or @samp{*},
1634 the pattern removal operation is applied to each positional
1635 parameter in turn, and the expansion is the resultant list.
1637 is an array variable subscripted with @samp{@@} or @samp{*},
1638 the pattern removal operation is applied to each member of the
1639 array in turn, and the expansion is the resultant list.
1641 @item $@{@var{parameter}/@var{pattern}/@var{string}@}
1642 @itemx $@{@var{parameter}//@var{pattern}/@var{string}@}
1644 The @var{pattern} is expanded to produce a pattern just as in
1646 @var{Parameter} is expanded and the longest match of @var{pattern}
1647 against its value is replaced with @var{string}.
1648 In the first form, only the first match is replaced.
1649 The second form causes all matches of @var{pattern} to be
1650 replaced with @var{string}.
1651 If @var{pattern} begins with @samp{#}, it must match at the beginning
1652 of the expanded value of @var{parameter}.
1653 If @var{pattern} begins with @samp{%}, it must match at the end
1654 of the expanded value of @var{parameter}.
1655 If @var{string} is null, matches of @var{pattern} are deleted
1656 and the @code{/} following @var{pattern} may be omitted.
1657 If @var{parameter} is @samp{@@} or @samp{*},
1658 the substitution operation is applied to each positional
1659 parameter in turn, and the expansion is the resultant list.
1661 is an array variable subscripted with @samp{@@} or @samp{*},
1662 the substitution operation is applied to each member of the
1663 array in turn, and the expansion is the resultant list.
1667 @node Command Substitution
1668 @subsection Command Substitution
1669 @cindex command substitution
1671 Command substitution allows the output of a command to replace
1673 Command substitution occurs when a command is enclosed as follows:
1684 Bash performs the expansion by executing @var{command} and
1685 replacing the command substitution with the standard output of the
1686 command, with any trailing newlines deleted.
1687 Embedded newlines are not deleted, but they may be removed during
1689 The command substitution @code{$(cat @var{file})} can be
1690 replaced by the equivalent but faster @code{$(< @var{file})}.
1692 When the old-style backquote form of substitution is used,
1693 backslash retains its literal meaning except when followed by
1694 @samp{$}, @samp{`}, or @samp{\}.
1695 The first backquote not preceded by a backslash terminates the
1696 command substitution.
1697 When using the @code{$(@var{command})} form, all characters between
1698 the parentheses make up the command; none are treated specially.
1700 Command substitutions may be nested. To nest when using the backquoted
1701 form, escape the inner backquotes with backslashes.
1703 If the substitution appears within double quotes, word splitting and
1704 filename expansion are not performed on the results.
1706 @node Arithmetic Expansion
1707 @subsection Arithmetic Expansion
1708 @cindex expansion, arithmetic
1709 @cindex arithmetic expansion
1711 Arithmetic expansion allows the evaluation of an arithmetic expression
1712 and the substitution of the result. The format for arithmetic expansion is:
1715 $(( @var{expression} ))
1718 The expression is treated as if it were within double quotes, but
1719 a double quote inside the parentheses is not treated specially.
1720 All tokens in the expression undergo parameter expansion, command
1721 substitution, and quote removal.
1722 Arithmetic expansions may be nested.
1724 The evaluation is performed according to the rules listed below
1725 (@pxref{Shell Arithmetic}).
1726 If the expression is invalid, Bash prints a message indicating
1727 failure to the standard error and no substitution occurs.
1729 @node Process Substitution
1730 @subsection Process Substitution
1731 @cindex process substitution
1733 Process substitution is supported on systems that support named
1734 pipes (@sc{fifo}s) or the @file{/dev/fd} method of naming open files.
1735 It takes the form of
1745 The process @var{list} is run with its input or output connected to a
1746 @sc{fifo} or some file in @file{/dev/fd}. The name of this file is
1747 passed as an argument to the current command as the result of the
1748 expansion. If the @code{>(@var{list})} form is used, writing to
1749 the file will provide input for @var{list}. If the
1750 @code{<(@var{list})} form is used, the file passed as an
1751 argument should be read to obtain the output of @var{list}.
1752 Note that no space may appear between the @code{<} or @code{>}
1753 and the left parenthesis, otherwise the construct would be interpreted
1756 When available, process substitution is performed simultaneously with
1757 parameter and variable expansion, command substitution, and arithmetic
1760 @node Word Splitting
1761 @subsection Word Splitting
1762 @cindex word splitting
1764 The shell scans the results of parameter expansion, command substitution,
1765 and arithmetic expansion that did not occur within double quotes for
1768 The shell treats each character of @env{$IFS}
1769 as a delimiter, and splits the results of the other
1770 expansions into words on these characters. If
1771 @env{IFS} is unset, or its value is exactly @code{<space><tab><newline>},
1772 the default, then any sequence of @env{IFS}
1773 characters serves to delimit words. If @env{IFS}
1774 has a value other than the default, then sequences of
1775 the whitespace characters @code{space} and @code{tab}
1776 are ignored at the beginning and end of the
1777 word, as long as the whitespace character is in the
1778 value of @env{IFS} (an @env{IFS} whitespace character).
1779 Any character in @env{IFS} that is not @env{IFS}
1780 whitespace, along with any adjacent @env{IFS}
1781 whitespace characters, delimits a field. A sequence of @env{IFS}
1782 whitespace characters is also treated as a delimiter.
1783 If the value of @env{IFS} is null, no word splitting occurs.
1785 Explicit null arguments (@code{""} or @code{''}) are retained.
1786 Unquoted implicit null arguments, resulting from the expansion of
1787 parameters that have no values, are removed.
1788 If a parameter with no value is expanded within double quotes, a
1789 null argument results and is retained.
1791 Note that if no expansion occurs, no splitting
1794 @node Filename Expansion
1795 @subsection Filename Expansion
1797 * Pattern Matching:: How the shell matches patterns.
1799 @cindex expansion, filename
1800 @cindex expansion, pathname
1801 @cindex filename expansion
1802 @cindex pathname expansion
1804 After word splitting, unless the @option{-f} option has been set
1805 (@pxref{The Set Builtin}), Bash scans each word for the characters
1806 @samp{*}, @samp{?}, and @samp{[}.
1807 If one of these characters appears, then the word is
1808 regarded as a @var{pattern},
1809 and replaced with an alphabetically sorted list of
1810 file names matching the pattern. If no matching file names are found,
1811 and the shell option @code{nullglob} is disabled, the word is left
1813 If the @code{nullglob} option is set, and no matches are found, the word
1815 If the @code{failglob} shell option is set, and no matches are found,
1816 an error message is printed and the command is not executed.
1817 If the shell option @code{nocaseglob} is enabled, the match is performed
1818 without regard to the case of alphabetic characters.
1820 When a pattern is used for filename generation, the character @samp{.}
1821 at the start of a filename or immediately following a slash
1822 must be matched explicitly, unless the shell option @code{dotglob} is set.
1823 When matching a file name, the slash character must always be
1825 In other cases, the @samp{.} character is not treated specially.
1827 See the description of @code{shopt} in @ref{Bash Builtins},
1828 for a description of the @code{nocaseglob}, @code{nullglob},
1829 @code{failglob}, and @code{dotglob} options.
1831 The @env{GLOBIGNORE}
1832 shell variable may be used to restrict the set of filenames matching a
1833 pattern. If @env{GLOBIGNORE}
1834 is set, each matching filename that also matches one of the patterns in
1835 @env{GLOBIGNORE} is removed from the list of matches. The filenames
1836 @file{.} and @file{..}
1837 are always ignored when @env{GLOBIGNORE}
1838 is set and not null.
1839 However, setting @env{GLOBIGNORE} to a non-null value has the effect of
1840 enabling the @code{dotglob}
1841 shell option, so all other filenames beginning with a
1842 @samp{.} will match.
1843 To get the old behavior of ignoring filenames beginning with a
1844 @samp{.}, make @samp{.*} one of the patterns in @env{GLOBIGNORE}.
1845 The @code{dotglob} option is disabled when @env{GLOBIGNORE}
1848 @node Pattern Matching
1849 @subsubsection Pattern Matching
1850 @cindex pattern matching
1851 @cindex matching, pattern
1853 Any character that appears in a pattern, other than the special pattern
1854 characters described below, matches itself.
1855 The @sc{nul} character may not occur in a pattern.
1856 A backslash escapes the following character; the
1857 escaping backslash is discarded when matching.
1858 The special pattern characters must be quoted if they are to be matched
1861 The special pattern characters have the following meanings:
1864 Matches any string, including the null string.
1866 Matches any single character.
1868 Matches any one of the enclosed characters. A pair of characters
1869 separated by a hyphen denotes a @var{range expression};
1870 any character that sorts between those two characters, inclusive,
1871 using the current locale's collating sequence and character set,
1872 is matched. If the first character following the
1873 @samp{[} is a @samp{!} or a @samp{^}
1874 then any character not enclosed is matched. A @samp{@minus{}}
1875 may be matched by including it as the first or last character
1876 in the set. A @samp{]} may be matched by including it as the first
1877 character in the set.
1878 The sorting order of characters in range expressions is determined by
1879 the current locale and the value of the @env{LC_COLLATE} shell variable,
1882 For example, in the default C locale, @samp{[a-dx-z]} is equivalent to
1883 @samp{[abcdxyz]}. Many locales sort characters in dictionary order, and in
1884 these locales @samp{[a-dx-z]} is typically not equivalent to @samp{[abcdxyz]};
1885 it might be equivalent to @samp{[aBbCcDdxXyYz]}, for example. To obtain
1886 the traditional interpretation of ranges in bracket expressions, you can
1887 force the use of the C locale by setting the @env{LC_COLLATE} or
1888 @env{LC_ALL} environment variable to the value @samp{C}.
1890 Within @samp{[} and @samp{]}, @var{character classes} can be specified
1892 @code{[:}@var{class}@code{:]}, where @var{class} is one of the
1893 following classes defined in the @sc{posix} 1003.2 standard:
1895 alnum alpha ascii blank cntrl digit graph lower
1896 print punct space upper word xdigit
1899 A character class matches any character belonging to that class.
1900 The @code{word} character class matches letters, digits, and the character
1903 Within @samp{[} and @samp{]}, an @var{equivalence class} can be
1904 specified using the syntax @code{[=}@var{c}@code{=]}, which
1905 matches all characters with the same collation weight (as defined
1906 by the current locale) as the character @var{c}.
1908 Within @samp{[} and @samp{]}, the syntax @code{[.}@var{symbol}@code{.]}
1909 matches the collating symbol @var{symbol}.
1912 If the @code{extglob} shell option is enabled using the @code{shopt}
1913 builtin, several extended pattern matching operators are recognized.
1914 In the following description, a @var{pattern-list} is a list of one
1915 or more patterns separated by a @samp{|}.
1916 Composite patterns may be formed using one or more of the following
1920 @item ?(@var{pattern-list})
1921 Matches zero or one occurrence of the given patterns.
1923 @item *(@var{pattern-list})
1924 Matches zero or more occurrences of the given patterns.
1926 @item +(@var{pattern-list})
1927 Matches one or more occurrences of the given patterns.
1929 @item @@(@var{pattern-list})
1930 Matches exactly one of the given patterns.
1932 @item !(@var{pattern-list})
1933 Matches anything except one of the given patterns.
1937 @subsection Quote Removal
1939 After the preceding expansions, all unquoted occurrences of the
1940 characters @samp{\}, @samp{'}, and @samp{"} that did not
1941 result from one of the above expansions are removed.
1944 @section Redirections
1947 Before a command is executed, its input and output
1948 may be @var{redirected}
1949 using a special notation interpreted by the shell.
1950 Redirection may also be used to open and close files for the
1951 current shell execution environment. The following redirection
1952 operators may precede or appear anywhere within a
1953 simple command or may follow a command.
1954 Redirections are processed in the order they appear, from
1957 In the following descriptions, if the file descriptor number is
1958 omitted, and the first character of the redirection operator is
1959 @samp{<}, the redirection refers to the standard input (file
1960 descriptor 0). If the first character of the redirection operator
1961 is @samp{>}, the redirection refers to the standard output (file
1964 The word following the redirection operator in the following
1965 descriptions, unless otherwise noted, is subjected to brace expansion,
1966 tilde expansion, parameter expansion, command substitution, arithmetic
1967 expansion, quote removal, filename expansion, and word splitting.
1968 If it expands to more than one word, Bash reports an error.
1970 Note that the order of redirections is significant. For example,
1973 ls > @var{dirlist} 2>&1
1976 directs both standard output (file descriptor 1) and standard error
1977 (file descriptor 2) to the file @var{dirlist}, while the command
1979 ls 2>&1 > @var{dirlist}
1982 directs only the standard output to file @var{dirlist},
1983 because the standard error was duplicated as standard output
1984 before the standard output was redirected to @var{dirlist}.
1986 Bash handles several filenames specially when they are used in
1987 redirections, as described in the following table:
1990 @item /dev/fd/@var{fd}
1991 If @var{fd} is a valid integer, file descriptor @var{fd} is duplicated.
1994 File descriptor 0 is duplicated.
1997 File descriptor 1 is duplicated.
2000 File descriptor 2 is duplicated.
2002 @item /dev/tcp/@var{host}/@var{port}
2003 If @var{host} is a valid hostname or Internet address, and @var{port}
2004 is an integer port number or service name, Bash attempts to open a TCP
2005 connection to the corresponding socket.
2007 @item /dev/udp/@var{host}/@var{port}
2008 If @var{host} is a valid hostname or Internet address, and @var{port}
2009 is an integer port number or service name, Bash attempts to open a UDP
2010 connection to the corresponding socket.
2014 A failure to open or create a file causes the redirection to fail.
2016 @subsection Redirecting Input
2017 Redirection of input causes the file whose name results from
2018 the expansion of @var{word}
2019 to be opened for reading on file descriptor @code{n},
2020 or the standard input (file descriptor 0) if @code{n}
2023 The general format for redirecting input is:
2025 [@var{n}]<@var{word}
2028 @subsection Redirecting Output
2029 Redirection of output causes the file whose name results from
2030 the expansion of @var{word}
2031 to be opened for writing on file descriptor @var{n},
2032 or the standard output (file descriptor 1) if @var{n}
2033 is not specified. If the file does not exist it is created;
2034 if it does exist it is truncated to zero size.
2036 The general format for redirecting output is:
2038 [@var{n}]>[|]@var{word}
2041 If the redirection operator is @samp{>}, and the @code{noclobber}
2042 option to the @code{set} builtin has been enabled, the redirection
2043 will fail if the file whose name results from the expansion of
2044 @var{word} exists and is a regular file.
2045 If the redirection operator is @samp{>|}, or the redirection operator is
2046 @samp{>} and the @code{noclobber} option is not enabled, the redirection
2047 is attempted even if the file named by @var{word} exists.
2049 @subsection Appending Redirected Output
2050 Redirection of output in this fashion
2051 causes the file whose name results from
2052 the expansion of @var{word}
2053 to be opened for appending on file descriptor @var{n},
2054 or the standard output (file descriptor 1) if @var{n}
2055 is not specified. If the file does not exist it is created.
2057 The general format for appending output is:
2059 [@var{n}]>>@var{word}
2062 @subsection Redirecting Standard Output and Standard Error
2063 Bash allows both the
2064 standard output (file descriptor 1) and
2065 the standard error output (file descriptor 2)
2066 to be redirected to the file whose name is the
2067 expansion of @var{word} with this construct.
2069 There are two formats for redirecting standard output and
2080 Of the two forms, the first is preferred.
2081 This is semantically equivalent to
2086 @subsection Here Documents
2087 This type of redirection instructs the shell to read input from the
2088 current source until a line containing only @var{word}
2089 (with no trailing blanks) is seen. All of
2090 the lines read up to that point are then used as the standard
2091 input for a command.
2093 The format of here-documents is:
2095 <<[@minus{}]@var{word}
2100 No parameter expansion, command substitution, arithmetic expansion,
2101 or filename expansion is performed on
2102 @var{word}. If any characters in @var{word} are quoted, the
2103 @var{delimiter} is the result of quote removal on @var{word},
2104 and the lines in the here-document are not expanded.
2105 If @var{word} is unquoted,
2106 all lines of the here-document are subjected to parameter expansion,
2107 command substitution, and arithmetic expansion. In the latter
2108 case, the character sequence @code{\newline} is ignored, and @samp{\}
2109 must be used to quote the characters
2110 @samp{\}, @samp{$}, and @samp{`}.
2112 If the redirection operator is @samp{<<-},
2113 then all leading tab characters are stripped from input lines and the
2114 line containing @var{delimiter}.
2115 This allows here-documents within shell scripts to be indented in a
2118 @subsection Here Strings
2119 A variant of here documents, the format is:
2124 The @var{word} is expanded and supplied to the command on its standard
2127 @subsection Duplicating File Descriptors
2128 The redirection operator
2130 [@var{n}]<&@var{word}
2133 is used to duplicate input file descriptors.
2135 expands to one or more digits, the file descriptor denoted by @var{n}
2136 is made to be a copy of that file descriptor.
2137 If the digits in @var{word} do not specify a file descriptor open for
2138 input, a redirection error occurs.
2140 evaluates to @samp{-}, file descriptor @var{n} is closed. If
2141 @var{n} is not specified, the standard input (file descriptor 0) is used.
2145 [@var{n}]>&@var{word}
2148 is used similarly to duplicate output file descriptors. If
2149 @var{n} is not specified, the standard output (file descriptor 1) is used.
2150 If the digits in @var{word} do not specify a file descriptor open for
2151 output, a redirection error occurs.
2152 As a special case, if @var{n} is omitted, and @var{word} does not
2153 expand to one or more digits, the standard output and standard
2154 error are redirected as described previously.
2156 @subsection Moving File Descriptors
2157 The redirection operator
2159 [@var{n}]<&@var{digit}-
2162 moves the file descriptor @var{digit} to file descriptor @var{n},
2163 or the standard input (file descriptor 0) if @var{n} is not specified.
2164 @var{digit} is closed after being duplicated to @var{n}.
2166 Similarly, the redirection operator
2168 [@var{n}]>&@var{digit}-
2171 moves the file descriptor @var{digit} to file descriptor @var{n},
2172 or the standard output (file descriptor 1) if @var{n} is not specified.
2174 @subsection Opening File Descriptors for Reading and Writing
2175 The redirection operator
2177 [@var{n}]<>@var{word}
2180 causes the file whose name is the expansion of @var{word}
2181 to be opened for both reading and writing on file descriptor
2182 @var{n}, or on file descriptor 0 if @var{n}
2183 is not specified. If the file does not exist, it is created.
2185 @node Executing Commands
2186 @section Executing Commands
2189 * Simple Command Expansion:: How Bash expands simple commands before
2192 * Command Search and Execution:: How Bash finds commands and runs them.
2194 * Command Execution Environment:: The environment in which Bash
2195 executes commands that are not
2198 * Environment:: The environment given to a command.
2200 * Exit Status:: The status returned by commands and how Bash
2203 * Signals:: What happens when Bash or a command it runs
2208 @node Simple Command Expansion
2209 @subsection Simple Command Expansion
2210 @cindex command expansion
2212 When a simple command is executed, the shell performs the following
2213 expansions, assignments, and redirections, from left to right.
2217 The words that the parser has marked as variable assignments (those
2218 preceding the command name) and redirections are saved for later
2222 The words that are not variable assignments or redirections are
2223 expanded (@pxref{Shell Expansions}).
2224 If any words remain after expansion, the first word
2225 is taken to be the name of the command and the remaining words are
2229 Redirections are performed as described above (@pxref{Redirections}).
2232 The text after the @samp{=} in each variable assignment undergoes tilde
2233 expansion, parameter expansion, command substitution, arithmetic expansion,
2234 and quote removal before being assigned to the variable.
2237 If no command name results, the variable assignments affect the current
2238 shell environment. Otherwise, the variables are added to the environment
2239 of the executed command and do not affect the current shell environment.
2240 If any of the assignments attempts to assign a value to a readonly variable,
2241 an error occurs, and the command exits with a non-zero status.
2243 If no command name results, redirections are performed, but do not
2244 affect the current shell environment. A redirection error causes the
2245 command to exit with a non-zero status.
2247 If there is a command name left after expansion, execution proceeds as
2248 described below. Otherwise, the command exits. If one of the expansions
2249 contained a command substitution, the exit status of the command is
2250 the exit status of the last command substitution performed. If there
2251 were no command substitutions, the command exits with a status of zero.
2253 @node Command Search and Execution
2254 @subsection Command Search and Execution
2255 @cindex command execution
2256 @cindex command search
2258 After a command has been split into words, if it results in a
2259 simple command and an optional list of arguments, the following
2264 If the command name contains no slashes, the shell attempts to
2265 locate it. If there exists a shell function by that name, that
2266 function is invoked as described in @ref{Shell Functions}.
2269 If the name does not match a function, the shell searches for
2270 it in the list of shell builtins. If a match is found, that
2274 If the name is neither a shell function nor a builtin,
2275 and contains no slashes, Bash searches each element of
2276 @env{$PATH} for a directory containing an executable file
2277 by that name. Bash uses a hash table to remember the full
2278 pathnames of executable files to avoid multiple @env{PATH} searches
2279 (see the description of @code{hash} in @ref{Bourne Shell Builtins}).
2280 A full search of the directories in @env{$PATH}
2281 is performed only if the command is not found in the hash table.
2282 If the search is unsuccessful, the shell prints an error
2283 message and returns an exit status of 127.
2286 If the search is successful, or if the command name contains
2287 one or more slashes, the shell executes the named program in
2288 a separate execution environment.
2289 Argument 0 is set to the name given, and the remaining arguments
2290 to the command are set to the arguments supplied, if any.
2293 If this execution fails because the file is not in executable
2294 format, and the file is not a directory, it is assumed to be a
2295 @var{shell script} and the shell executes it as described in
2296 @ref{Shell Scripts}.
2299 If the command was not begun asynchronously, the shell waits for
2300 the command to complete and collects its exit status.
2304 @node Command Execution Environment
2305 @subsection Command Execution Environment
2306 @cindex execution environment
2308 The shell has an @var{execution environment}, which consists of the
2313 open files inherited by the shell at invocation, as modified by
2314 redirections supplied to the @code{exec} builtin
2317 the current working directory as set by @code{cd}, @code{pushd}, or
2318 @code{popd}, or inherited by the shell at invocation
2321 the file creation mode mask as set by @code{umask} or inherited from
2325 current traps set by @code{trap}
2328 shell parameters that are set by variable assignment or with @code{set}
2329 or inherited from the shell's parent in the environment
2332 shell functions defined during execution or inherited from the shell's
2333 parent in the environment
2336 options enabled at invocation (either by default or with command-line
2337 arguments) or by @code{set}
2340 options enabled by @code{shopt}
2343 shell aliases defined with @code{alias} (@pxref{Aliases})
2346 various process @sc{id}s, including those of background jobs
2347 (@pxref{Lists}), the value of @code{$$}, and the value of
2352 When a simple command other than a builtin or shell function
2353 is to be executed, it
2354 is invoked in a separate execution environment that consists of
2355 the following. Unless otherwise noted, the values are inherited
2360 the shell's open files, plus any modifications and additions specified
2361 by redirections to the command
2364 the current working directory
2367 the file creation mode mask
2370 shell variables and functions marked for export, along with variables
2371 exported for the command, passed in the environment (@pxref{Environment})
2374 traps caught by the shell are reset to the values inherited from the
2375 shell's parent, and traps ignored by the shell are ignored
2379 A command invoked in this separate environment cannot affect the
2380 shell's execution environment.
2382 Command substitution, commands grouped with parentheses,
2383 and asynchronous commands are invoked in a
2384 subshell environment that is a duplicate of the shell environment,
2385 except that traps caught by the shell are reset to the values
2386 that the shell inherited from its parent at invocation. Builtin
2387 commands that are invoked as part of a pipeline are also executed
2388 in a subshell environment. Changes made to the subshell environment
2389 cannot affect the shell's execution environment.
2391 If a command is followed by a @samp{&} and job control is not active, the
2392 default standard input for the command is the empty file @file{/dev/null}.
2393 Otherwise, the invoked command inherits the file descriptors of the calling
2394 shell as modified by redirections.
2397 @subsection Environment
2400 When a program is invoked it is given an array of strings
2401 called the @var{environment}.
2402 This is a list of name-value pairs, of the form @code{name=value}.
2404 Bash provides several ways to manipulate the environment.
2405 On invocation, the shell scans its own environment and
2406 creates a parameter for each name found, automatically marking
2408 to child processes. Executed commands inherit the environment.
2409 The @code{export} and @samp{declare -x}
2410 commands allow parameters and functions to be added to and
2411 deleted from the environment. If the value of a parameter
2412 in the environment is modified, the new value becomes part
2413 of the environment, replacing the old. The environment
2414 inherited by any executed command consists of the shell's
2415 initial environment, whose values may be modified in the shell,
2416 less any pairs removed by the @code{unset} and @samp{export -n}
2417 commands, plus any additions via the @code{export} and
2418 @samp{declare -x} commands.
2420 The environment for any simple command
2421 or function may be augmented temporarily by prefixing it with
2422 parameter assignments, as described in @ref{Shell Parameters}.
2423 These assignment statements affect only the environment seen
2426 If the @option{-k} option is set (@pxref{The Set Builtin}), then all
2427 parameter assignments are placed in the environment for a command,
2428 not just those that precede the command name.
2430 When Bash invokes an external command, the variable @samp{$_}
2431 is set to the full path name of the command and passed to that
2432 command in its environment.
2435 @subsection Exit Status
2438 For the shell's purposes, a command which exits with a
2439 zero exit status has succeeded.
2440 A non-zero exit status indicates failure.
2441 This seemingly counter-intuitive scheme is used so there
2442 is one well-defined way to indicate success and a variety of
2443 ways to indicate various failure modes.
2444 When a command terminates on a fatal signal whose number is @var{N},
2445 Bash uses the value 128+@var{N} as the exit status.
2447 If a command is not found, the child process created to
2448 execute it returns a status of 127. If a command is found
2449 but is not executable, the return status is 126.
2451 If a command fails because of an error during expansion or redirection,
2452 the exit status is greater than zero.
2454 The exit status is used by the Bash conditional commands
2455 (@pxref{Conditional Constructs}) and some of the list
2456 constructs (@pxref{Lists}).
2458 All of the Bash builtins return an exit status of zero if they succeed
2459 and a non-zero status on failure, so they may be used by the
2460 conditional and list constructs.
2461 All builtins return an exit status of 2 to indicate incorrect usage.
2465 @cindex signal handling
2467 When Bash is interactive, in the absence of any traps, it ignores
2468 @code{SIGTERM} (so that @samp{kill 0} does not kill an interactive shell),
2470 is caught and handled (so that the @code{wait} builtin is interruptible).
2471 When Bash receives a @code{SIGINT}, it breaks out of any executing loops.
2472 In all cases, Bash ignores @code{SIGQUIT}.
2473 If job control is in effect (@pxref{Job Control}), Bash
2474 ignores @code{SIGTTIN}, @code{SIGTTOU}, and @code{SIGTSTP}.
2476 Non-builtin commands started by Bash have signal handlers set to the
2477 values inherited by the shell from its parent.
2478 When job control is not in effect, asynchronous commands
2479 ignore @code{SIGINT} and @code{SIGQUIT} in addition to these inherited
2481 Commands run as a result of
2482 command substitution ignore the keyboard-generated job control signals
2483 @code{SIGTTIN}, @code{SIGTTOU}, and @code{SIGTSTP}.
2485 The shell exits by default upon receipt of a @code{SIGHUP}.
2486 Before exiting, an interactive shell resends the @code{SIGHUP} to
2487 all jobs, running or stopped.
2488 Stopped jobs are sent @code{SIGCONT} to ensure that they receive
2490 To prevent the shell from sending the @code{SIGHUP} signal to a
2491 particular job, it should be removed
2492 from the jobs table with the @code{disown}
2493 builtin (@pxref{Job Control Builtins}) or marked
2494 to not receive @code{SIGHUP} using @code{disown -h}.
2496 If the @code{huponexit} shell option has been set with @code{shopt}
2497 (@pxref{Bash Builtins}), Bash sends a @code{SIGHUP} to all jobs when
2498 an interactive login shell exits.
2500 If Bash is waiting for a command to complete and receives a signal
2501 for which a trap has been set, the trap will not be executed until
2502 the command completes.
2503 When Bash is waiting for an asynchronous
2504 command via the @code{wait} builtin, the reception of a signal for
2505 which a trap has been set will cause the @code{wait} builtin to return
2506 immediately with an exit status greater than 128, immediately after
2507 which the trap is executed.
2510 @section Shell Scripts
2511 @cindex shell script
2513 A shell script is a text file containing shell commands. When such
2514 a file is used as the first non-option argument when invoking Bash,
2515 and neither the @option{-c} nor @option{-s} option is supplied
2516 (@pxref{Invoking Bash}),
2517 Bash reads and executes commands from the file, then exits. This
2518 mode of operation creates a non-interactive shell. The shell first
2519 searches for the file in the current directory, and looks in the
2520 directories in @env{$PATH} if not found there.
2523 a shell script, it sets the special parameter @code{0} to the name
2524 of the file, rather than the name of the shell, and the positional
2525 parameters are set to the remaining arguments, if any are given.
2526 If no additional arguments are supplied, the positional parameters
2529 A shell script may be made executable by using the @code{chmod} command
2530 to turn on the execute bit. When Bash finds such a file while
2531 searching the @env{$PATH} for a command, it spawns a subshell to
2532 execute it. In other words, executing
2534 filename @var{arguments}
2537 is equivalent to executing
2539 bash filename @var{arguments}
2543 if @code{filename} is an executable shell script.
2544 This subshell reinitializes itself, so that the effect is as if a
2545 new shell had been invoked to interpret the script, with the
2546 exception that the locations of commands remembered by the parent
2547 (see the description of @code{hash} in @ref{Bourne Shell Builtins})
2548 are retained by the child.
2550 Most versions of Unix make this a part of the operating system's command
2551 execution mechanism. If the first line of a script begins with
2552 the two characters @samp{#!}, the remainder of the line specifies
2553 an interpreter for the program.
2554 Thus, you can specify Bash, @code{awk}, Perl, or some other
2555 interpreter and write the rest of the script file in that language.
2557 The arguments to the interpreter
2558 consist of a single optional argument following the interpreter
2559 name on the first line of the script file, followed by the name of
2560 the script file, followed by the rest of the arguments. Bash
2561 will perform this action on operating systems that do not handle it
2562 themselves. Note that some older versions of Unix limit the interpreter
2563 name and argument to a maximum of 32 characters.
2565 Bash scripts often begin with @code{#! /bin/bash} (assuming that
2566 Bash has been installed in @file{/bin}), since this ensures that
2567 Bash will be used to interpret the script, even if it is executed
2568 under another shell.
2570 @node Shell Builtin Commands
2571 @chapter Shell Builtin Commands
2574 * Bourne Shell Builtins:: Builtin commands inherited from the Bourne
2576 * Bash Builtins:: Table of builtins specific to Bash.
2577 * The Set Builtin:: This builtin is so overloaded it
2578 deserves its own section.
2579 * Special Builtins:: Builtin commands classified specially by
2583 Builtin commands are contained within the shell itself.
2584 When the name of a builtin command is used as the first word of
2585 a simple command (@pxref{Simple Commands}), the shell executes
2586 the command directly, without invoking another program.
2587 Builtin commands are necessary to implement functionality impossible
2588 or inconvenient to obtain with separate utilities.
2590 This section briefly the builtins which Bash inherits from
2591 the Bourne Shell, as well as the builtin commands which are unique
2592 to or have been extended in Bash.
2594 Several builtin commands are described in other chapters: builtin
2595 commands which provide the Bash interface to the job control
2596 facilities (@pxref{Job Control Builtins}), the directory stack
2597 (@pxref{Directory Stack Builtins}), the command history
2598 (@pxref{Bash History Builtins}), and the programmable completion
2599 facilities (@pxref{Programmable Completion Builtins}).
2601 Many of the builtins have been extended by @sc{posix} or Bash.
2603 Unless otherwise noted, each builtin command documented as accepting
2604 options preceded by @samp{-} accepts @samp{--}
2605 to signify the end of the options.
2607 @node Bourne Shell Builtins
2608 @section Bourne Shell Builtins
2610 The following shell builtin commands are inherited from the Bourne Shell.
2611 These commands are implemented as specified by the @sc{posix} 1003.2 standard.
2614 @item : @r{(a colon)}
2619 Do nothing beyond expanding @var{arguments} and performing redirections.
2620 The return status is zero.
2622 @item . @r{(a period)}
2625 . @var{filename} [@var{arguments}]
2627 Read and execute commands from the @var{filename} argument in the
2628 current shell context. If @var{filename} does not contain a slash,
2629 the @env{PATH} variable is used to find @var{filename}.
2630 When Bash is not in @sc{posix} mode, the current directory is searched
2631 if @var{filename} is not found in @env{$PATH}.
2632 If any @var{arguments} are supplied, they become the positional
2633 parameters when @var{filename} is executed. Otherwise the positional
2634 parameters are unchanged.
2635 The return status is the exit status of the last command executed, or
2636 zero if no commands are executed. If @var{filename} is not found, or
2637 cannot be read, the return status is non-zero.
2638 This builtin is equivalent to @code{source}.
2645 Exit from a @code{for}, @code{while}, @code{until}, or @code{select} loop.
2646 If @var{n} is supplied, the @var{n}th enclosing loop is exited.
2647 @var{n} must be greater than or equal to 1.
2648 The return status is zero unless @var{n} is not greater than or equal to 1.
2653 cd [-L|-P] [@var{directory}]
2655 Change the current working directory to @var{directory}.
2656 If @var{directory} is not given, the value of the @env{HOME} shell
2658 If the shell variable @env{CDPATH} exists, it is used as a search path.
2659 If @var{directory} begins with a slash, @env{CDPATH} is not used.
2661 The @option{-P} option means to not follow symbolic links; symbolic
2662 links are followed by default or with the @option{-L} option.
2663 If @var{directory} is @samp{-}, it is equivalent to @env{$OLDPWD}.
2665 If a non-empty directory name from @env{CDPATH} is used, or if
2666 @samp{-} is the first argument, and the directory change is
2667 successful, the absolute pathname of the new working directory is
2668 written to the standard output.
2670 The return status is zero if the directory is successfully changed,
2678 Resume the next iteration of an enclosing @code{for}, @code{while},
2679 @code{until}, or @code{select} loop.
2680 If @var{n} is supplied, the execution of the @var{n}th enclosing loop
2682 @var{n} must be greater than or equal to 1.
2683 The return status is zero unless @var{n} is not greater than or equal to 1.
2688 eval [@var{arguments}]
2690 The arguments are concatenated together into a single command, which is
2691 then read and executed, and its exit status returned as the exit status
2693 If there are no arguments or only empty arguments, the return status is
2699 exec [-cl] [-a @var{name}] [@var{command} [@var{arguments}]]
2702 is supplied, it replaces the shell without creating a new process.
2703 If the @option{-l} option is supplied, the shell places a dash at the
2704 beginning of the zeroth arg passed to @var{command}.
2705 This is what the @code{login} program does.
2706 The @option{-c} option causes @var{command} to be executed with an empty
2708 If @option{-a} is supplied, the shell passes @var{name} as the zeroth
2709 argument to @var{command}.
2710 If no @var{command} is specified, redirections may be used to affect
2711 the current shell environment. If there are no redirection errors, the
2712 return status is zero; otherwise the return status is non-zero.
2719 Exit the shell, returning a status of @var{n} to the shell's parent.
2720 If @var{n} is omitted, the exit status is that of the last command executed.
2721 Any trap on @code{EXIT} is executed before the shell terminates.
2726 export [-fn] [-p] [@var{name}[=@var{value}]]
2728 Mark each @var{name} to be passed to child processes
2729 in the environment. If the @option{-f} option is supplied, the @var{name}s
2730 refer to shell functions; otherwise the names refer to shell variables.
2731 The @option{-n} option means to no longer mark each @var{name} for export.
2732 If no @var{names} are supplied, or if the @option{-p} option is given, a
2733 list of exported names is displayed.
2734 The @option{-p} option displays output in a form that may be reused as input.
2735 If a variable name is followed by =@var{value}, the value of
2736 the variable is set to @var{value}.
2738 The return status is zero unless an invalid option is supplied, one of
2739 the names is not a valid shell variable name, or @option{-f} is supplied
2740 with a name that is not a shell function.
2745 getopts @var{optstring} @var{name} [@var{args}]
2747 @code{getopts} is used by shell scripts to parse positional parameters.
2748 @var{optstring} contains the option characters to be recognized; if a
2749 character is followed by a colon, the option is expected to have an
2750 argument, which should be separated from it by white space.
2751 The colon (@samp{:}) and question mark (@samp{?}) may not be
2752 used as option characters.
2753 Each time it is invoked, @code{getopts}
2754 places the next option in the shell variable @var{name}, initializing
2755 @var{name} if it does not exist,
2756 and the index of the next argument to be processed into the
2757 variable @env{OPTIND}.
2758 @env{OPTIND} is initialized to 1 each time the shell or a shell script
2760 When an option requires an argument,
2761 @code{getopts} places that argument into the variable @env{OPTARG}.
2762 The shell does not reset @env{OPTIND} automatically; it must be manually
2763 reset between multiple calls to @code{getopts} within the same shell
2764 invocation if a new set of parameters is to be used.
2766 When the end of options is encountered, @code{getopts} exits with a
2767 return value greater than zero.
2768 @env{OPTIND} is set to the index of the first non-option argument,
2769 and @code{name} is set to @samp{?}.
2772 normally parses the positional parameters, but if more arguments are
2773 given in @var{args}, @code{getopts} parses those instead.
2775 @code{getopts} can report errors in two ways. If the first character of
2776 @var{optstring} is a colon, @var{silent}
2777 error reporting is used. In normal operation diagnostic messages
2778 are printed when invalid options or missing option arguments are
2780 If the variable @env{OPTERR}
2781 is set to 0, no error messages will be displayed, even if the first
2782 character of @code{optstring} is not a colon.
2784 If an invalid option is seen,
2785 @code{getopts} places @samp{?} into @var{name} and, if not silent,
2786 prints an error message and unsets @env{OPTARG}.
2787 If @code{getopts} is silent, the option character found is placed in
2788 @env{OPTARG} and no diagnostic message is printed.
2790 If a required argument is not found, and @code{getopts}
2791 is not silent, a question mark (@samp{?}) is placed in @var{name},
2792 @code{OPTARG} is unset, and a diagnostic message is printed.
2793 If @code{getopts} is silent, then a colon (@samp{:}) is placed in
2794 @var{name} and @env{OPTARG} is set to the option character found.
2799 hash [-'r] [-p @var{filename}] [-dt] [@var{name}]
2801 Remember the full pathnames of commands specified as @var{name} arguments,
2802 so they need not be searched for on subsequent invocations.
2803 The commands are found by searching through the directories listed in
2805 The @option{-p} option inhibits the path search, and @var{filename} is
2806 used as the location of @var{name}.
2807 The @option{-r} option causes the shell to forget all remembered locations.
2808 The @option{-d} option causes the shell to forget the remembered location
2810 If the @option{-t} option is supplied, the full pathname to which each
2811 @var{name} corresponds is printed. If multiple @var{name} arguments are
2812 supplied with @option{-t} the @var{name} is printed before the hashed
2814 The @option{-l} option causes output to be displayed in a format
2815 that may be reused as input.
2816 If no arguments are given, or if only @option{-l} is supplied,
2817 information about remembered commands is printed.
2818 The return status is zero unless a @var{name} is not found or an invalid
2826 Print the absolute pathname of the current working directory.
2827 If the @option{-P} option is supplied, the pathname printed will not
2828 contain symbolic links.
2829 If the @option{-L} option is supplied, the pathname printed may contain
2831 The return status is zero unless an error is encountered while
2832 determining the name of the current directory or an invalid option
2838 readonly [-apf] [@var{name}[=@var{value}]] @dots{}
2840 Mark each @var{name} as readonly.
2841 The values of these names may not be changed by subsequent assignment.
2842 If the @option{-f} option is supplied, each @var{name} refers to a shell
2844 The @option{-a} option means each @var{name} refers to an array variable.
2845 If no @var{name} arguments are given, or if the @option{-p}
2846 option is supplied, a list of all readonly names is printed.
2847 The @option{-p} option causes output to be displayed in a format that
2848 may be reused as input.
2849 If a variable name is followed by =@var{value}, the value of
2850 the variable is set to @var{value}.
2851 The return status is zero unless an invalid option is supplied, one of
2852 the @var{name} arguments is not a valid shell variable or function name,
2853 or the @option{-f} option is supplied with a name that is not a shell function.
2860 Cause a shell function to exit with the return value @var{n}.
2861 If @var{n} is not supplied, the return value is the exit status of the
2862 last command executed in the function.
2863 This may also be used to terminate execution of a script being executed
2864 with the @code{.} (or @code{source}) builtin, returning either @var{n} or
2865 the exit status of the last command executed within the script as the exit
2866 status of the script.
2867 Any command associated with the @code{RETURN} trap is executed
2868 before execution resumes after the function or script.
2869 The return status is non-zero if @code{return} is used outside a function
2870 and not during the execution of a script by @code{.} or @code{source}.
2877 Shift the positional parameters to the left by @var{n}.
2878 The positional parameters from @var{n}+1 @dots{} @code{$#} are
2879 renamed to @code{$1} @dots{} @code{$#}-@var{n}+1.
2880 Parameters represented by the numbers @code{$#} to @var{n}+1 are unset.
2881 @var{n} must be a non-negative number less than or equal to @code{$#}.
2882 If @var{n} is zero or greater than @code{$#}, the positional parameters
2884 If @var{n} is not supplied, it is assumed to be 1.
2885 The return status is zero unless @var{n} is greater than @code{$#} or
2886 less than zero, non-zero otherwise.
2892 Evaluate a conditional expression @var{expr}.
2893 Each operator and operand must be a separate argument.
2894 Expressions are composed of the primaries described below in
2895 @ref{Bash Conditional Expressions}.
2897 When the @code{[} form is used, the last argument to the command must
2900 Expressions may be combined using the following operators, listed in
2901 decreasing order of precedence.
2905 True if @var{expr} is false.
2907 @item ( @var{expr} )
2908 Returns the value of @var{expr}.
2909 This may be used to override the normal precedence of operators.
2911 @item @var{expr1} -a @var{expr2}
2912 True if both @var{expr1} and @var{expr2} are true.
2914 @item @var{expr1} -o @var{expr2}
2915 True if either @var{expr1} or @var{expr2} is true.
2918 The @code{test} and @code{[} builtins evaluate conditional
2919 expressions using a set of rules based on the number of arguments.
2923 The expression is false.
2926 The expression is true if and only if the argument is not null.
2929 If the first argument is @samp{!}, the expression is true if and
2930 only if the second argument is null.
2931 If the first argument is one of the unary conditional operators
2932 (@pxref{Bash Conditional Expressions}), the expression
2933 is true if the unary test is true.
2934 If the first argument is not a valid unary operator, the expression is
2938 If the second argument is one of the binary conditional
2939 operators (@pxref{Bash Conditional Expressions}), the
2940 result of the expression is the result of the binary test using the
2941 first and third arguments as operands.
2942 If the first argument is @samp{!}, the value is the negation of
2943 the two-argument test using the second and third arguments.
2944 If the first argument is exactly @samp{(} and the third argument is
2945 exactly @samp{)}, the result is the one-argument test of the second
2947 Otherwise, the expression is false.
2948 The @samp{-a} and @samp{-o} operators are considered binary operators
2952 If the first argument is @samp{!}, the result is the negation of
2953 the three-argument expression composed of the remaining arguments.
2954 Otherwise, the expression is parsed and evaluated according to
2955 precedence using the rules listed above.
2957 @item 5 or more arguments
2958 The expression is parsed and evaluated according to precedence
2959 using the rules listed above.
2967 Print out the user and system times used by the shell and its children.
2968 The return status is zero.
2973 trap [-lp] [@var{arg}] [@var{sigspec} @dots{}]
2975 The commands in @var{arg} are to be read and executed when the
2976 shell receives signal @var{sigspec}. If @var{arg} is absent (and
2977 there is a single @var{sigspec}) or
2978 equal to @samp{-}, each specified signal's disposition is reset
2979 to the value it had when the shell was started.
2980 If @var{arg} is the null string, then the signal specified by
2981 each @var{sigspec} is ignored by the shell and commands it invokes.
2982 If @var{arg} is not present and @option{-p} has been supplied,
2983 the shell displays the trap commands associated with each @var{sigspec}.
2984 If no arguments are supplied, or
2985 only @option{-p} is given, @code{trap} prints the list of commands
2986 associated with each signal number in a form that may be reused as
2988 The @option{-l} option causes the shell to print a list of signal names
2989 and their corresponding numbers.
2990 Each @var{sigspec} is either a signal name or a signal number.
2991 Signal names are case insensitive and the @code{SIG} prefix is optional.
2993 is @code{0} or @code{EXIT}, @var{arg} is executed when the shell exits.
2994 If a @var{sigspec} is @code{DEBUG}, the command @var{arg} is executed
2995 before every simple command, @code{for} command, @code{case} command,
2996 @code{select} command, every arithmetic @code{for} command, and before
2997 the first command executes in a shell function.
2998 Refer to the description of the @code{extglob} option to the
2999 @code{shopt} builtin (@pxref{Bash Builtins}) for details of its
3000 effect on the @code{DEBUG} trap.
3001 If a @var{sigspec} is @code{ERR}, the command @var{arg}
3002 is executed whenever a simple command has a non-zero exit status,
3003 subject to the following conditions.
3004 The @code{ERR} trap is not executed if the failed command is part of the
3005 command list immediately following an @code{until} or @code{while} keyword,
3006 part of the test in an @code{if} statement,
3007 part of a @code{&&} or @code{||} list, or if the command's return
3008 status is being inverted using @code{!}.
3009 These are the same conditions obeyed by the @code{errexit} option.
3010 If a @var{sigspec} is @code{RETURN}, the command @var{arg} is executed
3011 each time a shell function or a script executed with the @code{.} or
3012 @code{source} builtins finishes executing.
3014 Signals ignored upon entry to the shell cannot be trapped or reset.
3015 Trapped signals are reset to their original values in a child
3016 process when it is created.
3018 The return status is zero unless a @var{sigspec} does not specify a
3024 umask [-p] [-S] [@var{mode}]
3026 Set the shell process's file creation mask to @var{mode}. If
3027 @var{mode} begins with a digit, it is interpreted as an octal number;
3028 if not, it is interpreted as a symbolic mode mask similar
3029 to that accepted by the @code{chmod} command. If @var{mode} is
3030 omitted, the current value of the mask is printed. If the @option{-S}
3031 option is supplied without a @var{mode} argument, the mask is printed
3032 in a symbolic format.
3033 If the @option{-p} option is supplied, and @var{mode}
3034 is omitted, the output is in a form that may be reused as input.
3035 The return status is zero if the mode is successfully changed or if
3036 no @var{mode} argument is supplied, and non-zero otherwise.
3038 Note that when the mode is interpreted as an octal number, each number
3039 of the umask is subtracted from @code{7}. Thus, a umask of @code{022}
3040 results in permissions of @code{755}.
3045 unset [-fv] [@var{name}]
3047 Each variable or function @var{name} is removed.
3048 If no options are supplied, or the @option{-v} option is given, each
3049 @var{name} refers to a shell variable.
3050 If the @option{-f} option is given, the @var{name}s refer to shell
3051 functions, and the function definition is removed.
3052 Readonly variables and functions may not be unset.
3053 The return status is zero unless a @var{name} is readonly.
3057 @section Bash Builtin Commands
3059 This section describes builtin commands which are unique to
3060 or have been extended in Bash.
3061 Some of these commands are specified in the @sc{posix} 1003.2 standard.
3068 alias [@code{-p}] [@var{name}[=@var{value}] @dots{}]
3071 Without arguments or with the @option{-p} option, @code{alias} prints
3072 the list of aliases on the standard output in a form that allows
3073 them to be reused as input.
3074 If arguments are supplied, an alias is defined for each @var{name}
3075 whose @var{value} is given. If no @var{value} is given, the name
3076 and value of the alias is printed.
3077 Aliases are described in @ref{Aliases}.
3082 bind [-m @var{keymap}] [-lpsvPSV]
3083 bind [-m @var{keymap}] [-q @var{function}] [-u @var{function}] [-r @var{keyseq}]
3084 bind [-m @var{keymap}] -f @var{filename}
3085 bind [-m @var{keymap}] -x @var{keyseq:shell-command}
3086 bind [-m @var{keymap}] @var{keyseq:function-name}
3087 bind @var{readline-command}
3090 Display current Readline (@pxref{Command Line Editing})
3091 key and function bindings,
3092 bind a key sequence to a Readline function or macro,
3093 or set a Readline variable.
3094 Each non-option argument is a command as it would appear in a
3095 a Readline initialization file (@pxref{Readline Init File}),
3096 but each binding or command must be passed as a separate argument; e.g.,
3097 @samp{"\C-x\C-r":re-read-init-file}.
3098 Options, if supplied, have the following meanings:
3101 @item -m @var{keymap}
3102 Use @var{keymap} as the keymap to be affected by
3103 the subsequent bindings. Acceptable @var{keymap}
3106 @code{emacs-standard},
3111 @code{vi-command}, and
3113 @code{vi} is equivalent to @code{vi-command};
3114 @code{emacs} is equivalent to @code{emacs-standard}.
3117 List the names of all Readline functions.
3120 Display Readline function names and bindings in such a way that they
3121 can be used as input or in a Readline initialization file.
3124 List current Readline function names and bindings.
3127 Display Readline variable names and values in such a way that they
3128 can be used as input or in a Readline initialization file.
3131 List current Readline variable names and values.
3134 Display Readline key sequences bound to macros and the strings they output
3135 in such a way that they can be used as input or in a Readline
3136 initialization file.
3139 Display Readline key sequences bound to macros and the strings they output.
3141 @item -f @var{filename}
3142 Read key bindings from @var{filename}.
3144 @item -q @var{function}
3145 Query about which keys invoke the named @var{function}.
3147 @item -u @var{function}
3148 Unbind all keys bound to the named @var{function}.
3150 @item -r @var{keyseq}
3151 Remove any current binding for @var{keyseq}.
3153 @item -x @var{keyseq:shell-command}
3154 Cause @var{shell-command} to be executed whenever @var{keyseq} is
3160 The return status is zero unless an invalid option is supplied or an
3166 builtin [@var{shell-builtin} [@var{args}]]
3168 Run a shell builtin, passing it @var{args}, and return its exit status.
3169 This is useful when defining a shell function with the same
3170 name as a shell builtin, retaining the functionality of the builtin within
3172 The return status is non-zero if @var{shell-builtin} is not a shell
3180 Returns the context of any active subroutine call (a shell function or
3181 a script executed with the @code{.} or @code{source} builtins).
3183 Without @var{expr}, @code{caller} displays the line number and source
3184 filename of the current subroutine call.
3185 If a non-negative integer is supplied as @var{expr}, @code{caller}
3186 displays the line number, subroutine name, and source file corresponding
3187 to that position in the current execution call stack. This extra
3188 information may be used, for example, to print a stack trace. The
3189 current frame is frame 0.
3191 The return value is 0 unless the shell is not executing a subroutine
3192 call or @var{expr} does not correspond to a valid position in the
3198 command [-pVv] @var{command} [@var{arguments} @dots{}]
3200 Runs @var{command} with @var{arguments} ignoring any shell function
3201 named @var{command}.
3202 Only shell builtin commands or commands found by searching the
3203 @env{PATH} are executed.
3204 If there is a shell function named @code{ls}, running @samp{command ls}
3205 within the function will execute the external command @code{ls}
3206 instead of calling the function recursively.
3207 The @option{-p} option means to use a default value for @env{PATH}
3208 that is guaranteed to find all of the standard utilities.
3209 The return status in this case is 127 if @var{command} cannot be
3210 found or an error occurred, and the exit status of @var{command}
3213 If either the @option{-V} or @option{-v} option is supplied, a
3214 description of @var{command} is printed. The @option{-v} option
3215 causes a single word indicating the command or file name used to
3216 invoke @var{command} to be displayed; the @option{-V} option produces
3217 a more verbose description. In this case, the return status is
3218 zero if @var{command} is found, and non-zero if not.
3223 declare [-afFirtx] [-p] [@var{name}[=@var{value}] @dots{}]
3226 Declare variables and give them attributes. If no @var{name}s
3227 are given, then display the values of variables instead.
3229 The @option{-p} option will display the attributes and values of each
3231 When @option{-p} is used, additional options are ignored.
3232 The @option{-F} option inhibits the display of function definitions;
3233 only the function name and attributes are printed.
3234 If the @code{extdebug} shell option is enabled using @code{shopt}
3235 (@pxref{Bash Builtins}), the source file name and line number where
3236 the function is defined are displayed as well.
3237 @option{-F} implies @option{-f}.
3238 The following options can be used to restrict output to variables with
3239 the specified attributes or to give variables attributes:
3243 Each @var{name} is an array variable (@pxref{Arrays}).
3246 Use function names only.
3249 The variable is to be treated as
3250 an integer; arithmetic evaluation (@pxref{Shell Arithmetic}) is
3251 performed when the variable is assigned a value.
3254 Make @var{name}s readonly. These names cannot then be assigned values
3255 by subsequent assignment statements or unset.
3258 Give each @var{name} the @code{trace} attribute.
3259 Traced functions inherit the @code{DEBUG} trap from the calling shell.
3260 The trace attribute has no special meaning for variables.
3263 Mark each @var{name} for export to subsequent commands via
3267 Using @samp{+} instead of @samp{-} turns off the attribute instead.
3268 When used in a function, @code{declare} makes each @var{name} local,
3269 as with the @code{local} command. If a variable name is followed by
3270 =@var{value}, the value of the variable is set to @var{value}.
3272 The return status is zero unless an invalid option is encountered,
3273 an attempt is made to define a function using @samp{-f foo=bar},
3274 an attempt is made to assign a value to a readonly variable,
3275 an attempt is made to assign a value to an array variable without
3276 using the compound assignment syntax (@pxref{Arrays}),
3277 one of the @var{names} is not a valid shell variable name,
3278 an attempt is made to turn off readonly status for a readonly variable,
3279 an attempt is made to turn off array status for an array variable,
3280 or an attempt is made to display a non-existent function with @option{-f}.
3285 echo [-neE] [@var{arg} @dots{}]
3287 Output the @var{arg}s, separated by spaces, terminated with a
3289 The return status is always 0.
3290 If @option{-n} is specified, the trailing newline is suppressed.
3291 If the @option{-e} option is given, interpretation of the following
3292 backslash-escaped characters is enabled.
3293 The @option{-E} option disables the interpretation of these escape characters,
3294 even on systems where they are interpreted by default.
3295 The @code{xpg_echo} shell option may be used to
3296 dynamically determine whether or not @code{echo} expands these
3297 escape characters by default.
3298 @code{echo} interprets the following escape sequences:
3305 suppress trailing newline
3321 the eight-bit character whose value is the octal value @var{nnn}
3322 (zero to three octal digits)
3324 the eight-bit character whose value is the octal value @var{nnn}
3325 (one to three octal digits)
3327 the eight-bit character whose value is the hexadecimal value @var{HH}
3328 (one or two hex digits)
3334 enable [-n] [-p] [-f @var{filename}] [-ads] [@var{name} @dots{}]
3336 Enable and disable builtin shell commands.
3337 Disabling a builtin allows a disk command which has the same name
3338 as a shell builtin to be executed without specifying a full pathname,
3339 even though the shell normally searches for builtins before disk commands.
3340 If @option{-n} is used, the @var{name}s become disabled. Otherwise
3341 @var{name}s are enabled. For example, to use the @code{test} binary
3342 found via @env{$PATH} instead of the shell builtin version, type
3343 @samp{enable -n test}.
3345 If the @option{-p} option is supplied, or no @var{name} arguments appear,
3346 a list of shell builtins is printed. With no other arguments, the list
3347 consists of all enabled shell builtins.
3348 The @option{-a} option means to list
3349 each builtin with an indication of whether or not it is enabled.
3351 The @option{-f} option means to load the new builtin command @var{name}
3352 from shared object @var{filename}, on systems that support dynamic loading.
3353 The @option{-d} option will delete a builtin loaded with @option{-f}.
3355 If there are no options, a list of the shell builtins is displayed.
3356 The @option{-s} option restricts @code{enable} to the @sc{posix} special
3357 builtins. If @option{-s} is used with @option{-f}, the new builtin becomes
3358 a special builtin (@pxref{Special Builtins}).
3360 The return status is zero unless a @var{name} is not a shell builtin
3361 or there is an error loading a new builtin from a shared object.
3366 help [-s] [@var{pattern}]
3368 Display helpful information about builtin commands.
3369 If @var{pattern} is specified, @code{help} gives detailed help
3370 on all commands matching @var{pattern}, otherwise a list of
3371 the builtins is printed.
3372 The @option{-s} option restricts the information displayed to a short
3374 The return status is zero unless no command matches @var{pattern}.
3379 let @var{expression} [@var{expression}]
3381 The @code{let} builtin allows arithmetic to be performed on shell
3382 variables. Each @var{expression} is evaluated according to the
3383 rules given below in @ref{Shell Arithmetic}. If the
3384 last @var{expression} evaluates to 0, @code{let} returns 1;
3385 otherwise 0 is returned.
3390 local [@var{option}] @var{name}[=@var{value}] @dots{}
3392 For each argument, a local variable named @var{name} is created,
3393 and assigned @var{value}.
3394 The @var{option} can be any of the options accepted by @code{declare}.
3395 @code{local} can only be used within a function; it makes the variable
3396 @var{name} have a visible scope restricted to that function and its
3397 children. The return status is zero unless @code{local} is used outside
3398 a function, an invalid @var{name} is supplied, or @var{name} is a
3406 Exit a login shell, returning a status of @var{n} to the shell's
3412 @code{printf} @var{format} [@var{arguments}]
3414 Write the formatted @var{arguments} to the standard output under the
3415 control of the @var{format}.
3416 The @var{format} is a character string which contains three types of objects:
3417 plain characters, which are simply copied to standard output, character
3418 escape sequences, which are converted and copied to the standard output, and
3419 format specifications, each of which causes printing of the next successive
3421 In addition to the standard @code{printf(1)} formats, @samp{%b} causes
3422 @code{printf} to expand backslash escape sequences in the corresponding
3424 (except that @samp{\c} terminates output, backslashes in
3425 @samp{\'}, @samp{\"}, and @samp{\?} are not removed, and octal escapes
3426 beginning with @samp{\0} may contain up to four digits),
3427 and @samp{%q} causes @code{printf} to output the
3428 corresponding @var{argument} in a format that can be reused as shell input.
3430 The @var{format} is reused as necessary to consume all of the @var{arguments}.
3431 If the @var{format} requires more @var{arguments} than are supplied, the
3432 extra format specifications behave as if a zero value or null string, as
3433 appropriate, had been supplied. The return value is zero on success,
3434 non-zero on failure.
3439 read [-ers] [-a @var{aname}] [-d @var{delim}] [-n @var{nchars}] [-p @var{prompt}] [-t @var{timeout}] [-u @var{fd}] [@var{name} @dots{}]
3441 One line is read from the standard input, or from the file descriptor
3442 @var{fd} supplied as an argument to the @option{-u} option, and the first word
3443 is assigned to the first @var{name}, the second word to the second @var{name},
3444 and so on, with leftover words and their intervening separators assigned
3445 to the last @var{name}.
3446 If there are fewer words read from the input stream than names,
3447 the remaining names are assigned empty values.
3448 The characters in the value of the @env{IFS} variable
3449 are used to split the line into words.
3450 The backslash character @samp{\} may be used to remove any special
3451 meaning for the next character read and for line continuation.
3452 If no names are supplied, the line read is assigned to the
3453 variable @env{REPLY}.
3454 The return code is zero, unless end-of-file is encountered, @code{read}
3455 times out, or an invalid file descriptor is supplied as the argument to
3457 Options, if supplied, have the following meanings:
3460 @item -a @var{aname}
3461 The words are assigned to sequential indices of the array variable
3462 @var{aname}, starting at 0.
3463 All elements are removed from @var{aname} before the assignment.
3464 Other @var{name} arguments are ignored.
3466 @item -d @var{delim}
3467 The first character of @var{delim} is used to terminate the input line,
3468 rather than newline.
3471 Readline (@pxref{Command Line Editing}) is used to obtain the line.
3473 @item -n @var{nchars}
3474 @code{read} returns after reading @var{nchars} characters rather than
3475 waiting for a complete line of input.
3477 @item -p @var{prompt}
3478 Display @var{prompt}, without a trailing newline, before attempting
3480 The prompt is displayed only if input is coming from a terminal.
3483 If this option is given, backslash does not act as an escape character.
3484 The backslash is considered to be part of the line.
3485 In particular, a backslash-newline pair may not be used as a line
3489 Silent mode. If input is coming from a terminal, characters are
3492 @item -t @var{timeout}
3493 Cause @code{read} to time out and return failure if a complete line of
3494 input is not read within @var{timeout} seconds.
3495 This option has no effect if @code{read} is not reading input from the
3499 Read input from file descriptor @var{fd}.
3506 shopt [-pqsu] [-o] [@var{optname} @dots{}]
3508 Toggle the values of variables controlling optional shell behavior.
3509 With no options, or with the @option{-p} option, a list of all settable
3510 options is displayed, with an indication of whether or not each is set.
3511 The @option{-p} option causes output to be displayed in a form that
3512 may be reused as input.
3513 Other options have the following meanings:
3517 Enable (set) each @var{optname}.
3520 Disable (unset) each @var{optname}.
3523 Suppresses normal output; the return status
3524 indicates whether the @var{optname} is set or unset.
3525 If multiple @var{optname} arguments are given with @option{-q},
3526 the return status is zero if all @var{optnames} are enabled;
3530 Restricts the values of
3531 @var{optname} to be those defined for the @option{-o} option to the
3532 @code{set} builtin (@pxref{The Set Builtin}).
3535 If either @option{-s} or @option{-u}
3536 is used with no @var{optname} arguments, the display is limited to
3537 those options which are set or unset, respectively.
3539 Unless otherwise noted, the @code{shopt} options are disabled (off)
3542 The return status when listing options is zero if all @var{optnames}
3543 are enabled, non-zero otherwise. When setting or unsetting options,
3544 the return status is zero unless an @var{optname} is not a valid shell
3547 The list of @code{shopt} options is:
3550 If this is set, an argument to the @code{cd}
3551 builtin command that
3552 is not a directory is assumed to be the name of a variable whose
3553 value is the directory to change to.
3556 If set, minor errors in the spelling of a directory component in a
3557 @code{cd} command will be corrected.
3558 The errors checked for are transposed characters,
3559 a missing character, and a character too many.
3560 If a correction is found, the corrected path is printed,
3561 and the command proceeds.
3562 This option is only used by interactive shells.
3565 If this is set, Bash checks that a command found in the hash
3566 table exists before trying to execute it. If a hashed command no
3567 longer exists, a normal path search is performed.
3570 If set, Bash checks the window size after each command
3571 and, if necessary, updates the values of
3572 @env{LINES} and @env{COLUMNS}.
3576 attempts to save all lines of a multiple-line
3577 command in the same history entry. This allows
3578 easy re-editing of multi-line commands.
3581 If set, Bash includes filenames beginning with a `.' in
3582 the results of filename expansion.
3585 If this is set, a non-interactive shell will not exit if
3586 it cannot execute the file specified as an argument to the @code{exec}
3587 builtin command. An interactive shell does not exit if @code{exec}
3590 @item expand_aliases
3591 If set, aliases are expanded as described below under Aliases,
3593 This option is enabled by default for interactive shells.
3596 If set, behavior intended for use by debuggers is enabled:
3600 The @option{-F} option to the @code{declare} builtin (@pxref{Bash Builtins})
3601 displays the source file name and line number corresponding to each function
3602 name supplied as an argument.
3605 If the command run by the @code{DEBUG} trap returns a non-zero value, the
3606 next command is skipped and not executed.
3609 If the command run by the @code{DEBUG} trap returns a value of 2, and the
3610 shell is executing in a subroutine (a shell function or a shell script
3611 executed by the @code{.} or @code{source} builtins), a call to
3612 @code{return} is simulated.
3616 If set, the extended pattern matching features described above
3617 (@pxref{Pattern Matching}) are enabled.
3620 If set, @code{$'@var{string}'} and @code{$"@var{string}"} quoting is
3621 performed within @code{$@{@var{parameter}@}} expansions
3622 enclosed in double quotes. This option is enabled by default.
3625 If set, patterns which fail to match filenames during pathname expansion
3626 result in an expansion error.
3629 If set, the suffixes specified by the @env{FIGNORE} shell variable
3630 cause words to be ignored when performing word completion even if
3631 the ignored words are the only possible completions.
3632 @xref{Bash Variables}, for a description of @env{FIGNORE}.
3633 This option is enabled by default.
3636 If set, shell error messages are written in the standard @sc{gnu} error
3640 If set, the history list is appended to the file named by the value
3641 of the @env{HISTFILE}
3642 variable when the shell exits, rather than overwriting the file.
3645 If set, and Readline
3646 is being used, a user is given the opportunity to re-edit a
3647 failed history substitution.
3650 If set, and Readline
3651 is being used, the results of history substitution are not immediately
3652 passed to the shell parser. Instead, the resulting line is loaded into
3653 the Readline editing buffer, allowing further modification.
3656 If set, and Readline is being used, Bash will attempt to perform
3657 hostname completion when a word containing a @samp{@@} is being
3658 completed (@pxref{Commands For Completion}). This option is enabled
3662 If set, Bash will send @code{SIGHUP} to all jobs when an interactive
3663 login shell exits (@pxref{Signals}).
3665 @item interactive_comments
3666 Allow a word beginning with @samp{#}
3667 to cause that word and all remaining characters on that
3668 line to be ignored in an interactive shell.
3669 This option is enabled by default.
3672 If enabled, and the @code{cmdhist}
3673 option is enabled, multi-line commands are saved to the history with
3674 embedded newlines rather than using semicolon separators where possible.
3677 The shell sets this option if it is started as a login shell
3678 (@pxref{Invoking Bash}).
3679 The value may not be changed.
3682 If set, and a file that Bash is checking for mail has been
3683 accessed since the last time it was checked, the message
3684 @code{"The mail in @var{mailfile} has been read"} is displayed.
3686 @item no_empty_cmd_completion
3687 If set, and Readline is being used, Bash will not attempt to search
3688 the @env{PATH} for possible completions when completion is attempted
3692 If set, Bash matches filenames in a case-insensitive fashion when
3693 performing filename expansion.
3696 If set, Bash allows filename patterns which match no
3697 files to expand to a null string, rather than themselves.
3700 If set, the programmable completion facilities
3701 (@pxref{Programmable Completion}) are enabled.
3702 This option is enabled by default.
3705 If set, prompt strings undergo
3706 parameter expansion, command substitution, arithmetic
3707 expansion, and quote removal after being expanded
3708 as described below (@pxref{Printing a Prompt}).
3709 This option is enabled by default.
3711 @item restricted_shell
3712 The shell sets this option if it is started in restricted mode
3713 (@pxref{The Restricted Shell}).
3714 The value may not be changed.
3715 This is not reset when the startup files are executed, allowing
3716 the startup files to discover whether or not a shell is restricted.
3719 If this is set, the @code{shift}
3720 builtin prints an error message when the shift count exceeds the
3721 number of positional parameters.
3724 If set, the @code{source} builtin uses the value of @env{PATH}
3725 to find the directory containing the file supplied as an argument.
3726 This option is enabled by default.
3729 If set, the @code{echo} builtin expands backslash-escape sequences
3735 The return status when listing options is zero if all @var{optnames}
3736 are enabled, non-zero otherwise.
3737 When setting or unsetting options, the return status is zero unless an
3738 @var{optname} is not a valid shell option.
3743 source @var{filename}
3745 A synonym for @code{.} (@pxref{Bourne Shell Builtins}).
3750 type [-afptP] [@var{name} @dots{}]
3752 For each @var{name}, indicate how it would be interpreted if used as a
3755 If the @option{-t} option is used, @code{type} prints a single word
3756 which is one of @samp{alias}, @samp{function}, @samp{builtin},
3757 @samp{file} or @samp{keyword},
3758 if @var{name} is an alias, shell function, shell builtin,
3759 disk file, or shell reserved word, respectively.
3760 If the @var{name} is not found, then nothing is printed, and
3761 @code{type} returns a failure status.
3763 If the @option{-p} option is used, @code{type} either returns the name
3764 of the disk file that would be executed, or nothing if @option{-t}
3765 would not return @samp{file}.
3767 The @option{-P} option forces a path search for each @var{name}, even if
3768 @option{-t} would not return @samp{file}.
3770 If a command is hashed, @option{-p} and @option{-P} print the hashed value,
3771 not necessarily the file that appears first in @code{$PATH}.
3773 If the @option{-a} option is used, @code{type} returns all of the places
3774 that contain an executable named @var{file}.
3775 This includes aliases and functions, if and only if the @option{-p} option
3778 If the @option{-f} option is used, @code{type} does not attempt to find
3779 shell functions, as with the @code{command} builtin.
3781 The return status is zero if any of the @var{names} are found, non-zero
3787 typeset [-afFrxi] [-p] [@var{name}[=@var{value}] @dots{}]
3789 The @code{typeset} command is supplied for compatibility with the Korn
3790 shell; however, it has been deprecated in favor of the @code{declare}
3796 ulimit [-acdflmnpstuvSH] [@var{limit}]
3798 @code{ulimit} provides control over the resources available to processes
3799 started by the shell, on systems that allow such control. If an
3800 option is given, it is interpreted as follows:
3803 Change and report the soft limit associated with a resource.
3806 Change and report the hard limit associated with a resource.
3809 All current limits are reported.
3812 The maximum size of core files created.
3815 The maximum size of a process's data segment.
3818 The maximum size of files created by the shell.
3821 The maximum size that may be locked into memory.
3824 The maximum resident set size.
3827 The maximum number of open file descriptors.
3830 The pipe buffer size.
3833 The maximum stack size.
3836 The maximum amount of cpu time in seconds.
3839 The maximum number of processes available to a single user.
3842 The maximum amount of virtual memory available to the process.
3846 If @var{limit} is given, it is the new value of the specified resource;
3847 the special @var{limit} values @code{hard}, @code{soft}, and
3848 @code{unlimited} stand for the current hard limit, the current soft limit,
3849 and no limit, respectively.
3850 Otherwise, the current value of the soft limit for the specified resource
3851 is printed, unless the @option{-H} option is supplied.
3852 When setting new limits, if neither @option{-H} nor @option{-S} is supplied,
3853 both the hard and soft limits are set.
3854 If no option is given, then @option{-f} is assumed. Values are in 1024-byte
3855 increments, except for @option{-t}, which is in seconds, @option{-p},
3856 which is in units of 512-byte blocks, and @option{-n} and @option{-u}, which
3857 are unscaled values.
3859 The return status is zero unless an invalid option or argument is supplied,
3860 or an error occurs while setting a new limit.
3865 unalias [-a] [@var{name} @dots{} ]
3868 Remove each @var{name} from the list of aliases. If @option{-a} is
3869 supplied, all aliases are removed.
3870 Aliases are described in @ref{Aliases}.
3874 @node The Set Builtin
3875 @section The Set Builtin
3877 This builtin is so complicated that it deserves its own section.
3883 set [--abefhkmnptuvxBCHP] [-o @var{option}] [@var{argument} @dots{}]
3886 If no options or arguments are supplied, @code{set} displays the names
3887 and values of all shell variables and functions, sorted according to the
3888 current locale, in a format that may be reused as input.
3890 When options are supplied, they set or unset shell attributes.
3891 Options, if specified, have the following meanings:
3895 Mark variables and function which are modified or created for export
3896 to the environment of subsequent commands.
3899 Cause the status of terminated background jobs to be reported
3900 immediately, rather than before printing the next primary prompt.
3903 Exit immediately if a simple command (@pxref{Simple Commands}) exits
3904 with a non-zero status, unless the command that fails is part of the
3905 command list immediately following a @code{while} or @code{until}
3906 keyword, part of the test in an @code{if} statement,
3907 part of a @code{&&} or @code{||} list, or if the command's return
3908 status is being inverted using @code{!}.
3909 A trap on @code{ERR}, if set, is executed before the shell exits.
3912 Disable file name generation (globbing).
3915 Locate and remember (hash) commands as they are looked up for execution.
3916 This option is enabled by default.
3919 All arguments in the form of assignment statements are placed
3920 in the environment for a command, not just those that precede
3924 Job control is enabled (@pxref{Job Control}).
3927 Read commands but do not execute them; this may be used to check a
3928 script for syntax errors.
3929 This option is ignored by interactive shells.
3931 @item -o @var{option-name}
3933 Set the option corresponding to @var{option-name}:
3943 Use an @code{emacs}-style line editing interface (@pxref{Command Line Editing}).
3961 Enable command history, as described in @ref{Bash History Facilities}.
3962 This option is on by default in interactive shells.
3965 An interactive shell will not exit upon reading EOF.
3998 If set, the return value of a pipeline is the value of the last
3999 (rightmost) command to exit with a non-zero status, or zero if all
4000 commands in the pipeline exit successfully.
4001 This option is disabled by default.
4004 Change the behavior of Bash where the default operation differs
4005 from the @sc{posix} 1003.2 standard to match the standard
4006 (@pxref{Bash POSIX Mode}).
4007 This is intended to make Bash behave as a strict superset of that
4017 Use a @code{vi}-style line editing interface.
4024 Turn on privileged mode.
4025 In this mode, the @env{$BASH_ENV} and @env{$ENV} files are not
4026 processed, shell functions are not inherited from the environment,
4027 and the @env{SHELLOPTS} variable, if it appears in the environment,
4029 If the shell is started with the effective user (group) id not equal to the
4030 real user (group) id, and the @code{-p} option is not supplied, these actions
4031 are taken and the effective user id is set to the real user id.
4032 If the @code{-p} option is supplied at startup, the effective user id is
4034 Turning this option off causes the effective user
4035 and group ids to be set to the real user and group ids.
4038 Exit after reading and executing one command.
4041 Treat unset variables as an error when performing parameter expansion.
4042 An error message will be written to the standard error, and a non-interactive
4046 Print shell input lines as they are read.
4049 Print a trace of simple commands, \fBfor\fP commands, \fBcase\fP
4050 commands, \fBselect\fP commands, and arithmetic \fBfor\fP commands
4051 and their arguments or associated word lists after they are
4052 expanded and before they are executed. The value of the @env{PS4}
4053 variable is expanded and the resultant value is printed before
4054 the command and its expanded arguments.
4057 The shell will perform brace expansion (@pxref{Brace Expansion}).
4058 This option is on by default.
4061 Prevent output redirection using @samp{>}, @samp{>&}, and @samp{<>}
4062 from overwriting existing files.
4065 If set, any trap on @code{ERR} is inherited by shell functions, command
4066 substitutions, and commands executed in a subshell environment.
4067 The @code{ERR} trap is normally not inherited in such cases.
4070 Enable @samp{!} style history substitution (@pxref{History Interaction}).
4071 This option is on by default for interactive shells.
4074 If set, do not follow symbolic links when performing commands such as
4075 @code{cd} which change the current directory. The physical directory
4076 is used instead. By default, Bash follows
4077 the logical chain of directories when performing commands
4078 which change the current directory.
4080 For example, if @file{/usr/sys} is a symbolic link to @file{/usr/local/sys}
4083 $ cd /usr/sys; echo $PWD
4090 If @code{set -P} is on, then:
4092 $ cd /usr/sys; echo $PWD
4099 If set, any trap on @code{DEBUG} is inherited by shell functions, command
4100 substitutions, and commands executed in a subshell environment.
4101 The @code{DEBUG} trap is normally not inherited in such cases.
4104 If no arguments follow this option, then the positional parameters are
4105 unset. Otherwise, the positional parameters are set to the
4106 @var{arguments}, even if some of them begin with a @samp{-}.
4109 Signal the end of options, cause all remaining @var{arguments}
4110 to be assigned to the positional parameters. The @option{-x}
4111 and @option{-v} options are turned off.
4112 If there are no arguments, the positional parameters remain unchanged.
4115 Using @samp{+} rather than @samp{-} causes these options to be
4116 turned off. The options can also be used upon invocation of the
4117 shell. The current set of options may be found in @code{$-}.
4119 The remaining N @var{arguments} are positional parameters and are
4120 assigned, in order, to @code{$1}, @code{$2}, @dots{} @code{$N}.
4121 The special parameter @code{#} is set to N.
4123 The return status is always zero unless an invalid option is supplied.
4126 @node Special Builtins
4127 @section Special Builtins
4128 @cindex special builtin
4130 For historical reasons, the @sc{posix} 1003.2 standard has classified
4131 several builtin commands as @emph{special}.
4132 When Bash is executing in @sc{posix} mode, the special builtins
4133 differ from other builtin commands in three respects:
4137 Special builtins are found before shell functions during command lookup.
4140 If a special builtin returns an error status, a non-interactive shell exits.
4143 Assignment statements preceding the command stay in effect in the shell
4144 environment after the command completes.
4147 When Bash is not executing in @sc{posix} mode, these builtins behave no
4148 differently than the rest of the Bash builtin commands.
4149 The Bash @sc{posix} mode is described in @ref{Bash POSIX Mode}.
4151 These are the @sc{posix} special builtins:
4153 @w{break : . continue eval exec exit export readonly return set}
4154 @w{shift trap unset}
4157 @node Shell Variables
4158 @chapter Shell Variables
4161 * Bourne Shell Variables:: Variables which Bash uses in the same way
4162 as the Bourne Shell.
4163 * Bash Variables:: List of variables that exist in Bash.
4166 This chapter describes the shell variables that Bash uses.
4167 Bash automatically assigns default values to a number of variables.
4169 @node Bourne Shell Variables
4170 @section Bourne Shell Variables
4172 Bash uses certain shell variables in the same way as the Bourne shell.
4173 In some cases, Bash assigns a default value to the variable.
4178 A colon-separated list of directories used as a search path for
4179 the @code{cd} builtin command.
4182 The current user's home directory; the default for the @code{cd} builtin
4184 The value of this variable is also used by tilde expansion
4185 (@pxref{Tilde Expansion}).
4188 A list of characters that separate fields; used when the shell splits
4189 words as part of expansion.
4192 If this parameter is set to a filename and the @env{MAILPATH} variable
4193 is not set, Bash informs the user of the arrival of mail in
4197 A colon-separated list of filenames which the shell periodically checks
4199 Each list entry can specify the message that is printed when new mail
4200 arrives in the mail file by separating the file name from the message with
4202 When used in the text of the message, @code{$_} expands to the name of
4203 the current mail file.
4206 The value of the last option argument processed by the @code{getopts} builtin.
4209 The index of the last option argument processed by the @code{getopts} builtin.
4212 A colon-separated list of directories in which the shell looks for
4214 A zero-length (null) directory name in the value of @code{PATH} indicates the
4216 A null directory name may appear as two adjacent colons, or as an initial
4221 The primary prompt string. The default value is @samp{\s-\v\$ }.
4222 @xref{Printing a Prompt}, for the complete list of escape
4223 sequences that are expanded before @env{PS1} is displayed.
4226 The secondary prompt string. The default value is @samp{> }.
4230 @node Bash Variables
4231 @section Bash Variables
4233 These variables are set or used by Bash, but other shells
4234 do not normally treat them specially.
4236 A few variables used by Bash are described in different chapters:
4237 variables for controlling the job control facilities
4238 (@pxref{Job Control Variables}).
4243 The full pathname used to execute the current instance of Bash.
4246 An array variable whose values are the number of parameters in each
4247 frame of the current bash execution call stack. The number of
4248 parameters to the current subroutine (shell function or script executed
4249 with @code{.} or @code{source}) is at the top of the stack. When a
4250 subroutine is executed, the number of parameters passed is pushed onto
4254 An array variable containing all of the parameters in the current bash
4255 execution call stack. The final parameter of the last subroutine call
4256 is at the top of the stack; the first parameter of the initial call is
4257 at the bottom. When a subroutine is executed, the parameters supplied
4258 are pushed onto @code{BASH_ARGV}.
4261 The command currently being executed or about to be executed, unless the
4262 shell is executing a command as the result of a trap,
4263 in which case it is the command executing at the time of the trap.
4266 If this variable is set when Bash is invoked to execute a shell
4267 script, its value is expanded and used as the name of a startup file
4268 to read before executing the script. @xref{Bash Startup Files}.
4270 @item BASH_EXECUTION_STRING
4271 The command argument to the @option{-c} invocation option.
4274 An array variable whose members are the line numbers in source files
4275 corresponding to each member of @var{FUNCNAME}.
4276 @code{$@{BASH_LINENO[$i]@}} is the line number in the source file where
4277 @code{$@{FUNCNAME[$i + 1]@}} was called.
4278 The corresponding source file name is @code{$@{BASH_SOURCE[$i + 1]@}}.
4279 Use @code{LINENO} to obtain the current line number.
4282 An array variable whose members are assigned by the @samp{=~} binary
4283 operator to the @code{[[} conditional command
4284 (@pxref{Conditional Constructs}).
4285 The element with index 0 is the portion of the string
4286 matching the entire regular expression.
4287 The element with index @var{n} is the portion of the
4288 string matching the @var{n}th parenthesized subexpression.
4289 This variable is read-only.
4292 An array variable whose members are the source filenames corresponding
4293 to the elements in the @code{FUNCNAME} array variable.
4296 Incremented by one each time a subshell or subshell environment is spawned.
4297 The initial value is 0.
4300 A readonly array variable (@pxref{Arrays})
4301 whose members hold version information for this instance of Bash.
4302 The values assigned to the array members are as follows:
4306 @item BASH_VERSINFO[0]
4307 The major version number (the @var{release}).
4309 @item BASH_VERSINFO[1]
4310 The minor version number (the @var{version}).
4312 @item BASH_VERSINFO[2]
4315 @item BASH_VERSINFO[3]
4318 @item BASH_VERSINFO[4]
4319 The release status (e.g., @var{beta1}).
4321 @item BASH_VERSINFO[5]
4322 The value of @env{MACHTYPE}.
4327 The version number of the current instance of Bash.
4330 Used by the @code{select} builtin command to determine the terminal width
4331 when printing selection lists. Automatically set upon receipt of a
4335 An index into @env{$@{COMP_WORDS@}} of the word containing the current
4337 This variable is available only in shell functions invoked by the
4338 programmable completion facilities (@pxref{Programmable Completion}).
4341 The current command line.
4342 This variable is available only in shell functions and external
4343 commands invoked by the
4344 programmable completion facilities (@pxref{Programmable Completion}).
4347 The index of the current cursor position relative to the beginning of
4348 the current command.
4349 If the current cursor position is at the end of the current command,
4350 the value of this variable is equal to @code{$@{#COMP_LINE@}}.
4351 This variable is available only in shell functions and external
4352 commands invoked by the
4353 programmable completion facilities (@pxref{Programmable Completion}).
4355 @item COMP_WORDBREAKS
4356 The set of characters that the Readline library treats as word
4357 separators when performing word completion.
4358 If @code{COMP_WORDBREAKS} is unset, it loses its special properties,
4359 even if it is subsequently reset.
4362 An array variable consisting of the individual
4363 words in the current command line.
4364 This variable is available only in shell functions invoked by the
4365 programmable completion facilities (@pxref{Programmable Completion}).
4368 An array variable from which Bash reads the possible completions
4369 generated by a shell function invoked by the programmable completion
4370 facility (@pxref{Programmable Completion}).
4373 An array variable containing the current contents of the directory stack.
4374 Directories appear in the stack in the order they are displayed by the
4375 @code{dirs} builtin.
4376 Assigning to members of this array variable may be used to modify
4377 directories already in the stack, but the @code{pushd} and @code{popd}
4378 builtins must be used to add and remove directories.
4379 Assignment to this variable will not change the current directory.
4380 If @env{DIRSTACK} is unset, it loses its special properties, even if
4381 it is subsequently reset.
4384 If Bash finds this variable in the environment when the shell
4385 starts with value @samp{t}, it assumes that the shell is running in an
4386 emacs shell buffer and disables line editing.
4389 The numeric effective user id of the current user. This variable
4393 The editor used as a default by the @option{-e} option to the @code{fc}
4397 A colon-separated list of suffixes to ignore when performing
4398 filename completion.
4399 A file name whose suffix matches one of the entries in
4401 is excluded from the list of matched file names. A sample
4402 value is @samp{.o:~}
4405 An array variable containing the names of all shell functions
4406 currently in the execution call stack.
4407 The element with index 0 is the name of any currently-executing
4409 The bottom-most element is "main".
4410 This variable exists only when a shell function is executing.
4411 Assignments to @env{FUNCNAME} have no effect and return an error status.
4412 If @env{FUNCNAME} is unset, it loses its special properties, even if
4413 it is subsequently reset.
4416 A colon-separated list of patterns defining the set of filenames to
4417 be ignored by filename expansion.
4418 If a filename matched by a filename expansion pattern also matches one
4419 of the patterns in @env{GLOBIGNORE}, it is removed from the list
4423 An array variable containing the list of groups of which the current
4425 Assignments to @env{GROUPS} have no effect and return an error status.
4426 If @env{GROUPS} is unset, it loses its special properties, even if it is
4430 Up to three characters which control history expansion, quick
4431 substitution, and tokenization (@pxref{History Interaction}).
4432 The first character is the
4433 @var{history expansion} character, that is, the character which signifies the
4434 start of a history expansion, normally @samp{!}. The second character is the
4435 character which signifies `quick substitution' when seen as the first
4436 character on a line, normally @samp{^}. The optional third character is the
4437 character which indicates that the remainder of the line is a comment when
4438 found as the first character of a word, usually @samp{#}. The history
4439 comment character causes history substitution to be skipped for the
4440 remaining words on the line. It does not necessarily cause the shell
4441 parser to treat the rest of the line as a comment.
4444 The history number, or index in the history list, of the current
4445 command. If @env{HISTCMD} is unset, it loses its special properties,
4446 even if it is subsequently reset.
4449 A colon-separated list of values controlling how commands are saved on
4451 If the list of values includes @samp{ignorespace}, lines which begin
4452 with a space character are not saved in the history list.
4453 A value of @samp{ignoredups} causes lines which match the previous
4454 history entry to not be saved.
4455 A value of @samp{ignoreboth} is shorthand for
4456 @samp{ignorespace} and @samp{ignoredups}.
4457 A value of @samp{erasedups} causes all previous lines matching the
4458 current line to be removed from the history list before that line
4460 Any value not in the above list is ignored.
4461 If @env{HISTCONTROL} is unset, or does not include a valid value,
4462 all lines read by the shell parser are saved on the history list,
4463 subject to the value of @env{HISTIGNORE}.
4464 The second and subsequent lines of a multi-line compound command are
4465 not tested, and are added to the history regardless of the value of
4469 The name of the file to which the command history is saved. The
4470 default value is @file{~/.bash_history}.
4473 The maximum number of lines contained in the history file. When this
4474 variable is assigned a value, the history file is truncated, if
4475 necessary, to contain no more than that number of lines.
4476 The history file is also truncated to this size after
4477 writing it when an interactive shell exits.
4478 The default value is 500.
4481 A colon-separated list of patterns used to decide which command
4482 lines should be saved on the history list. Each pattern is
4483 anchored at the beginning of the line and must match the complete
4484 line (no implicit @samp{*} is appended). Each pattern is tested
4485 against the line after the checks specified by @env{HISTCONTROL}
4486 are applied. In addition to the normal shell pattern matching
4487 characters, @samp{&} matches the previous history line. @samp{&}
4488 may be escaped using a backslash; the backslash is removed
4489 before attempting a match.
4490 The second and subsequent lines of a multi-line compound command are
4491 not tested, and are added to the history regardless of the value of
4494 @env{HISTIGNORE} subsumes the function of @env{HISTCONTROL}. A
4495 pattern of @samp{&} is identical to @code{ignoredups}, and a
4496 pattern of @samp{[ ]*} is identical to @code{ignorespace}.
4497 Combining these two patterns, separating them with a colon,
4498 provides the functionality of @code{ignoreboth}.
4501 The maximum number of commands to remember on the history list.
4502 The default value is 500.
4504 @item HISTTIMEFORMAT
4505 If this variable is set and not null, its value is used as a format string
4506 for @var{strftime} to print the time stamp associated with each history
4507 entry displayed by the @code{history} builtin.
4508 If this variable is set, time stamps are written to the history file so
4509 they may be preserved across shell sessions.
4512 Contains the name of a file in the same format as @file{/etc/hosts} that
4513 should be read when the shell needs to complete a hostname.
4514 The list of possible hostname completions may be changed while the shell
4516 the next time hostname completion is attempted after the
4517 value is changed, Bash adds the contents of the new file to the
4519 If @env{HOSTFILE} is set, but has no value, Bash attempts to read
4520 @file{/etc/hosts} to obtain the list of possible hostname completions.
4521 When @env{HOSTFILE} is unset, the hostname list is cleared.
4524 The name of the current host.
4527 A string describing the machine Bash is running on.
4530 Controls the action of the shell on receipt of an @code{EOF} character
4531 as the sole input. If set, the value denotes the number
4532 of consecutive @code{EOF} characters that can be read as the
4533 first character on an input line
4534 before the shell will exit. If the variable exists but does not
4535 have a numeric value (or has no value) then the default is 10.
4536 If the variable does not exist, then @code{EOF} signifies the end of
4537 input to the shell. This is only in effect for interactive shells.
4540 The name of the Readline initialization file, overriding the default
4541 of @file{~/.inputrc}.
4544 Used to determine the locale category for any category not specifically
4545 selected with a variable starting with @code{LC_}.
4548 This variable overrides the value of @env{LANG} and any other
4549 @code{LC_} variable specifying a locale category.
4552 This variable determines the collation order used when sorting the
4553 results of filename expansion, and
4554 determines the behavior of range expressions, equivalence classes,
4555 and collating sequences within filename expansion and pattern matching
4556 (@pxref{Filename Expansion}).
4559 This variable determines the interpretation of characters and the
4560 behavior of character classes within filename expansion and pattern
4561 matching (@pxref{Filename Expansion}).
4564 This variable determines the locale used to translate double-quoted
4565 strings preceded by a @samp{$} (@pxref{Locale Translation}).
4568 This variable determines the locale category used for number formatting.
4571 The line number in the script or shell function currently executing.
4574 Used by the @code{select} builtin command to determine the column length
4575 for printing selection lists. Automatically set upon receipt of a
4579 A string that fully describes the system type on which Bash
4580 is executing, in the standard @sc{gnu} @var{cpu-company-system} format.
4583 How often (in seconds) that the shell should check for mail in the
4584 files specified in the @env{MAILPATH} or @env{MAIL} variables.
4585 The default is 60 seconds. When it is time to check
4586 for mail, the shell does so before displaying the primary prompt.
4587 If this variable is unset, or set to a value that is not a number
4588 greater than or equal to zero, the shell disables mail checking.
4591 The previous working directory as set by the @code{cd} builtin.
4594 If set to the value 1, Bash displays error messages
4595 generated by the @code{getopts} builtin command.
4598 A string describing the operating system Bash is running on.
4601 An array variable (@pxref{Arrays})
4602 containing a list of exit status values from the processes
4603 in the most-recently-executed foreground pipeline (which may
4604 contain only a single command).
4606 @item POSIXLY_CORRECT
4607 If this variable is in the environment when @code{bash} starts, the shell
4608 enters @sc{posix} mode (@pxref{Bash POSIX Mode}) before reading the
4609 startup files, as if the @option{--posix} invocation option had been supplied.
4610 If it is set while the shell is running, @code{bash} enables @sc{posix} mode,
4619 The process @sc{id} of the shell's parent process. This variable
4622 @item PROMPT_COMMAND
4623 If set, the value is interpreted as a command to execute
4624 before the printing of each primary prompt (@env{$PS1}).
4627 The value of this variable is used as the prompt for the
4628 @code{select} command. If this variable is not set, the
4629 @code{select} command prompts with @samp{#? }
4632 The value is the prompt printed before the command line is echoed
4633 when the @option{-x} option is set (@pxref{The Set Builtin}).
4634 The first character of @env{PS4} is replicated multiple times, as
4635 necessary, to indicate multiple levels of indirection.
4636 The default is @samp{+ }.
4639 The current working directory as set by the @code{cd} builtin.
4642 Each time this parameter is referenced, a random integer
4643 between 0 and 32767 is generated. Assigning a value to this
4644 variable seeds the random number generator.
4647 The default variable for the @code{read} builtin.
4650 This variable expands to the number of seconds since the
4651 shell was started. Assignment to this variable resets
4652 the count to the value assigned, and the expanded value
4653 becomes the value assigned plus the number of seconds
4654 since the assignment.
4657 The full pathname to the shell is kept in this environment variable.
4658 If it is not set when the shell starts,
4659 Bash assigns to it the full pathname of the current user's login shell.
4662 A colon-separated list of enabled shell options. Each word in
4663 the list is a valid argument for the @option{-o} option to the
4664 @code{set} builtin command (@pxref{The Set Builtin}).
4665 The options appearing in @env{SHELLOPTS} are those reported
4666 as @samp{on} by @samp{set -o}.
4667 If this variable is in the environment when Bash
4668 starts up, each shell option in the list will be enabled before
4669 reading any startup files. This variable is readonly.
4672 Incremented by one each time a new instance of Bash is started. This is
4673 intended to be a count of how deeply your Bash shells are nested.
4676 The value of this parameter is used as a format string specifying
4677 how the timing information for pipelines prefixed with the @code{time}
4678 reserved word should be displayed.
4679 The @samp{%} character introduces an
4680 escape sequence that is expanded to a time value or other
4682 The escape sequences and their meanings are as
4683 follows; the braces denote optional portions.
4690 @item %[@var{p}][l]R
4691 The elapsed time in seconds.
4693 @item %[@var{p}][l]U
4694 The number of CPU seconds spent in user mode.
4696 @item %[@var{p}][l]S
4697 The number of CPU seconds spent in system mode.
4700 The CPU percentage, computed as (%U + %S) / %R.
4703 The optional @var{p} is a digit specifying the precision, the number of
4704 fractional digits after a decimal point.
4705 A value of 0 causes no decimal point or fraction to be output.
4706 At most three places after the decimal point may be specified; values
4707 of @var{p} greater than 3 are changed to 3.
4708 If @var{p} is not specified, the value 3 is used.
4710 The optional @code{l} specifies a longer format, including minutes, of
4711 the form @var{MM}m@var{SS}.@var{FF}s.
4712 The value of @var{p} determines whether or not the fraction is included.
4714 If this variable is not set, Bash acts as if it had the value
4716 @code{$'\nreal\t%3lR\nuser\t%3lU\nsys\t%3lS'}
4718 If the value is null, no timing information is displayed.
4719 A trailing newline is added when the format string is displayed.
4722 If set to a value greater than zero, @code{TMOUT} is treated as the
4723 default timeout for the @code{read} builtin (@pxref{Bash Builtins}).
4724 The @code{select} command (@pxref{Conditional Constructs}) terminates
4725 if input does not arrive after @code{TMOUT} seconds when input is coming
4728 In an interative shell, the value is interpreted as
4729 the number of seconds to wait for input after issuing the primary
4730 prompt when the shell is interactive.
4731 Bash terminates after that number of seconds if input does
4735 The numeric real user id of the current user. This variable is readonly.
4740 @chapter Bash Features
4742 This section describes features unique to Bash.
4745 * Invoking Bash:: Command line options that you can give
4747 * Bash Startup Files:: When and how Bash executes scripts.
4748 * Interactive Shells:: What an interactive shell is.
4749 * Bash Conditional Expressions:: Primitives used in composing expressions for
4750 the @code{test} builtin.
4751 * Shell Arithmetic:: Arithmetic on shell variables.
4752 * Aliases:: Substituting one command for another.
4753 * Arrays:: Array Variables.
4754 * The Directory Stack:: History of visited directories.
4755 * Printing a Prompt:: Controlling the PS1 string.
4756 * The Restricted Shell:: A more controlled mode of shell execution.
4757 * Bash POSIX Mode:: Making Bash behave more closely to what
4758 the POSIX standard specifies.
4762 @section Invoking Bash
4765 bash [long-opt] [-ir] [-abefhkmnptuvxdBCDHP] [-o @var{option}] [-O @var{shopt_option}] [@var{argument} @dots{}]
4766 bash [long-opt] [-abefhkmnptuvxdBCDHP] [-o @var{option}] [-O @var{shopt_option}] -c @var{string} [@var{argument} @dots{}]
4767 bash [long-opt] -s [-abefhkmnptuvxdBCDHP] [-o @var{option}] [-O @var{shopt_option}] [@var{argument} @dots{}]
4770 In addition to the single-character shell command-line options
4771 (@pxref{The Set Builtin}), there are several multi-character
4772 options that you can use. These options must appear on the command
4773 line before the single-character options to be recognized.
4777 Arrange for the debugger profile to be executed before the shell
4778 starts. Turns on extended debugging mode (see @ref{Bash Builtins}
4779 for a description of the @code{extdebug} option to the @code{shopt}
4780 builtin) and shell function tracing
4781 (see @ref{The Set Builtin} for a description of the @code{-o functrace}
4784 @item --dump-po-strings
4785 A list of all double-quoted strings preceded by @samp{$}
4786 is printed on the standard ouput
4787 in the @sc{gnu} @code{gettext} PO (portable object) file format.
4788 Equivalent to @option{-D} except for the output format.
4790 @item --dump-strings
4791 Equivalent to @option{-D}.
4794 Display a usage message on standard output and exit sucessfully.
4796 @item --init-file @var{filename}
4797 @itemx --rcfile @var{filename}
4798 Execute commands from @var{filename} (instead of @file{~/.bashrc})
4799 in an interactive shell.
4802 Equivalent to @option{-l}.
4805 Do not use the @sc{gnu} Readline library (@pxref{Command Line Editing})
4806 to read command lines when the shell is interactive.
4809 Don't load the system-wide startup file @file{/etc/profile}
4810 or any of the personal initialization files
4811 @file{~/.bash_profile}, @file{~/.bash_login}, or @file{~/.profile}
4812 when Bash is invoked as a login shell.
4815 Don't read the @file{~/.bashrc} initialization file in an
4816 interactive shell. This is on by default if the shell is
4817 invoked as @code{sh}.
4820 Change the behavior of Bash where the default operation differs
4821 from the @sc{posix} 1003.2 standard to match the standard. This
4822 is intended to make Bash behave as a strict superset of that
4823 standard. @xref{Bash POSIX Mode}, for a description of the Bash
4827 Make the shell a restricted shell (@pxref{The Restricted Shell}).
4830 Equivalent to @option{-v}. Print shell input lines as they're read.
4833 Show version information for this instance of
4834 Bash on the standard output and exit successfully.
4838 There are several single-character options that may be supplied at
4839 invocation which are not available with the @code{set} builtin.
4842 @item -c @var{string}
4843 Read and execute commands from @var{string} after processing the
4844 options, then exit. Any remaining arguments are assigned to the
4845 positional parameters, starting with @code{$0}.
4848 Force the shell to run interactively. Interactive shells are
4849 described in @ref{Interactive Shells}.
4852 Make this shell act as if it had been directly invoked by login.
4853 When the shell is interactive, this is equivalent to starting a
4854 login shell with @samp{exec -l bash}.
4855 When the shell is not interactive, the login shell startup files will
4857 @samp{exec bash -l} or @samp{exec bash --login}
4858 will replace the current shell with a Bash login shell.
4859 @xref{Bash Startup Files}, for a description of the special behavior
4863 Make the shell a restricted shell (@pxref{The Restricted Shell}).
4866 If this option is present, or if no arguments remain after option
4867 processing, then commands are read from the standard input.
4868 This option allows the positional parameters to be set
4869 when invoking an interactive shell.
4872 A list of all double-quoted strings preceded by @samp{$}
4873 is printed on the standard ouput.
4874 These are the strings that
4875 are subject to language translation when the current locale
4876 is not @code{C} or @code{POSIX} (@pxref{Locale Translation}).
4877 This implies the @option{-n} option; no commands will be executed.
4879 @item [-+]O [@var{shopt_option}]
4880 @var{shopt_option} is one of the shell options accepted by the
4881 @code{shopt} builtin (@pxref{Shell Builtin Commands}).
4882 If @var{shopt_option} is present, @option{-O} sets the value of that option;
4883 @option{+O} unsets it.
4884 If @var{shopt_option} is not supplied, the names and values of the shell
4885 options accepted by @code{shopt} are printed on the standard output.
4886 If the invocation option is @option{+O}, the output is displayed in a format
4887 that may be reused as input.
4890 A @code{--} signals the end of options and disables further option
4892 Any arguments after the @code{--} are treated as filenames and arguments.
4897 A @emph{login} shell is one whose first character of argument zero is
4898 @samp{-}, or one invoked with the @option{--login} option.
4900 @cindex interactive shell
4901 An @emph{interactive} shell is one started without non-option arguments,
4902 unless @option{-s} is specified,
4903 without specifying the @option{-c} option, and whose input and output are both
4904 connected to terminals (as determined by @code{isatty(3)}), or one
4905 started with the @option{-i} option. @xref{Interactive Shells}, for more
4908 If arguments remain after option processing, and neither the
4909 @option{-c} nor the @option{-s}
4910 option has been supplied, the first argument is assumed to
4911 be the name of a file containing shell commands (@pxref{Shell Scripts}).
4912 When Bash is invoked in this fashion, @code{$0}
4913 is set to the name of the file, and the positional parameters
4914 are set to the remaining arguments.
4915 Bash reads and executes commands from this file, then exits.
4916 Bash's exit status is the exit status of the last command executed
4917 in the script. If no commands are executed, the exit status is 0.
4919 @node Bash Startup Files
4920 @section Bash Startup Files
4921 @cindex startup files
4923 This section describs how Bash executes its startup files.
4924 If any of the files exist but cannot be read, Bash reports an error.
4925 Tildes are expanded in file names as described above under
4926 Tilde Expansion (@pxref{Tilde Expansion}).
4928 Interactive shells are described in @ref{Interactive Shells}.
4930 @subsubheading Invoked as an interactive login shell, or with @option{--login}
4932 When Bash is invoked as an interactive login shell, or as a
4933 non-interactive shell with the @option{--login} option, it first reads and
4934 executes commands from the file @file{/etc/profile}, if that file exists.
4935 After reading that file, it looks for @file{~/.bash_profile},
4936 @file{~/.bash_login}, and @file{~/.profile}, in that order, and reads
4937 and executes commands from the first one that exists and is readable.
4938 The @option{--noprofile} option may be used when the shell is started to
4939 inhibit this behavior.
4941 When a login shell exits, Bash reads and executes commands from
4942 the file @file{~/.bash_logout}, if it exists.
4944 @subsubheading Invoked as an interactive non-login shell
4946 When an interactive shell that is not a login shell is started, Bash
4947 reads and executes commands from @file{~/.bashrc}, if that file exists.
4948 This may be inhibited by using the @option{--norc} option.
4949 The @option{--rcfile @var{file}} option will force Bash to read and
4950 execute commands from @var{file} instead of @file{~/.bashrc}.
4952 So, typically, your @file{~/.bash_profile} contains the line
4954 @code{if [ -f ~/.bashrc ]; then . ~/.bashrc; fi}
4957 after (or before) any login-specific initializations.
4959 @subsubheading Invoked non-interactively
4961 When Bash is started non-interactively, to run a shell script,
4962 for example, it looks for the variable @env{BASH_ENV} in the environment,
4963 expands its value if it appears there, and uses the expanded value as
4964 the name of a file to read and execute. Bash behaves as if the
4965 following command were executed:
4967 @code{if [ -n "$BASH_ENV" ]; then . "$BASH_ENV"; fi}
4970 but the value of the @env{PATH} variable is not used to search for the
4973 As noted above, if a non-interactive shell is invoked with the
4974 @option{--login} option, Bash attempts to read and execute commands from the
4975 login shell startup files.
4977 @subsubheading Invoked with name @code{sh}
4979 If Bash is invoked with the name @code{sh}, it tries to mimic the
4980 startup behavior of historical versions of @code{sh} as closely as
4981 possible, while conforming to the @sc{posix} standard as well.
4983 When invoked as an interactive login shell, or as a non-interactive
4984 shell with the @option{--login} option, it first attempts to read
4985 and execute commands from @file{/etc/profile} and @file{~/.profile}, in
4987 The @option{--noprofile} option may be used to inhibit this behavior.
4988 When invoked as an interactive shell with the name @code{sh}, Bash
4989 looks for the variable @env{ENV}, expands its value if it is defined,
4990 and uses the expanded value as the name of a file to read and execute.
4991 Since a shell invoked as @code{sh} does not attempt to read and execute
4992 commands from any other startup files, the @option{--rcfile} option has
4994 A non-interactive shell invoked with the name @code{sh} does not attempt
4995 to read any other startup files.
4997 When invoked as @code{sh}, Bash enters @sc{posix} mode after
4998 the startup files are read.
5000 @subsubheading Invoked in @sc{posix} mode
5002 When Bash is started in @sc{posix} mode, as with the
5003 @option{--posix} command line option, it follows the @sc{posix} standard
5005 In this mode, interactive shells expand the @env{ENV} variable
5006 and commands are read and executed from the file whose name is the
5008 No other startup files are read.
5010 @subsubheading Invoked by remote shell daemon
5012 Bash attempts to determine when it is being run by the remote shell
5013 daemon, usually @code{rshd}. If Bash determines it is being run by
5014 rshd, it reads and executes commands from @file{~/.bashrc}, if that
5015 file exists and is readable.
5016 It will not do this if invoked as @code{sh}.
5017 The @option{--norc} option may be used to inhibit this behavior, and the
5018 @option{--rcfile} option may be used to force another file to be read, but
5019 @code{rshd} does not generally invoke the shell with those options or
5020 allow them to be specified.
5022 @subsubheading Invoked with unequal effective and real @sc{uid/gid}s
5024 If Bash is started with the effective user (group) id not equal to the
5025 real user (group) id, and the @code{-p} option is not supplied, no startup
5026 files are read, shell functions are not inherited from the environment,
5027 the @env{SHELLOPTS} variable, if it appears in the environment, is ignored,
5028 and the effective user id is set to the real user id.
5029 If the @code{-p} option is supplied at invocation, the startup behavior is
5030 the same, but the effective user id is not reset.
5032 @node Interactive Shells
5033 @section Interactive Shells
5034 @cindex interactive shell
5035 @cindex shell, interactive
5038 * What is an Interactive Shell?:: What determines whether a shell is Interactive.
5039 * Is this Shell Interactive?:: How to tell if a shell is interactive.
5040 * Interactive Shell Behavior:: What changes in a interactive shell?
5043 @node What is an Interactive Shell?
5044 @subsection What is an Interactive Shell?
5046 An interactive shell
5047 is one started without non-option arguments, unless @option{-s} is
5048 specified, without specifiying the @option{-c} option, and
5049 whose input and error output are both
5050 connected to terminals (as determined by @code{isatty(3)}),
5051 or one started with the @option{-i} option.
5053 An interactive shell generally reads from and writes to a user's
5056 The @option{-s} invocation option may be used to set the positional parameters
5057 when an interactive shell is started.
5059 @node Is this Shell Interactive?
5060 @subsection Is this Shell Interactive?
5062 To determine within a startup script whether or not Bash is
5063 running interactively,
5064 test the value of the @samp{-} special parameter.
5065 It contains @code{i} when the shell is interactive. For example:
5069 *i*) echo This shell is interactive ;;
5070 *) echo This shell is not interactive ;;
5074 Alternatively, startup scripts may examine the variable
5075 @env{PS1}; it is unset in non-interactive shells, and set in
5076 interactive shells. Thus:
5079 if [ -z "$PS1" ]; then
5080 echo This shell is not interactive
5082 echo This shell is interactive
5086 @node Interactive Shell Behavior
5087 @subsection Interactive Shell Behavior
5089 When the shell is running interactively, it changes its behavior in
5094 Startup files are read and executed as described in @ref{Bash Startup Files}.
5097 Job Control (@pxref{Job Control}) is enabled by default. When job
5098 control is in effect, Bash ignores the keyboard-generated job control
5099 signals @code{SIGTTIN}, @code{SIGTTOU}, and @code{SIGTSTP}.
5102 Bash expands and displays @env{PS1} before reading the first line
5103 of a command, and expands and displays @env{PS2} before reading the
5104 second and subsequent lines of a multi-line command.
5107 Bash executes the value of the @env{PROMPT_COMMAND} variable as a command
5108 before printing the primary prompt, @env{$PS1}
5109 (@pxref{Bash Variables}).
5112 Readline (@pxref{Command Line Editing}) is used to read commands from
5113 the user's terminal.
5116 Bash inspects the value of the @code{ignoreeof} option to @code{set -o}
5117 instead of exiting immediately when it receives an @code{EOF} on its
5118 standard input when reading a command (@pxref{The Set Builtin}).
5121 Command history (@pxref{Bash History Facilities})
5122 and history expansion (@pxref{History Interaction})
5123 are enabled by default.
5124 Bash will save the command history to the file named by @env{$HISTFILE}
5125 when an interactive shell exits.
5128 Alias expansion (@pxref{Aliases}) is performed by default.
5131 In the absence of any traps, Bash ignores @code{SIGTERM}
5135 In the absence of any traps, @code{SIGINT} is caught and handled
5137 @code{SIGINT} will interrupt some shell builtins.
5140 An interactive login shell sends a @code{SIGHUP} to all jobs on exit
5141 if the @code{hupoxexit} shell option has been enabled (@pxref{Signals}).
5144 The @option{-n} invocation option is ignored, and @samp{set -n} has
5145 no effect (@pxref{The Set Builtin}).
5148 Bash will check for mail periodically, depending on the values of the
5149 @env{MAIL}, @env{MAILPATH}, and @env{MAILCHECK} shell variables
5150 (@pxref{Bash Variables}).
5153 Expansion errors due to references to unbound shell variables after
5154 @samp{set -u} has been enabled will not cause the shell to exit
5155 (@pxref{The Set Builtin}).
5158 The shell will not exit on expansion errors caused by @var{var} being unset
5159 or null in @code{$@{@var{var}:?@var{word}@}} expansions
5160 (@pxref{Shell Parameter Expansion}).
5163 Redirection errors encountered by shell builtins will not cause the
5167 When running in @sc{posix} mode, a special builtin returning an error
5168 status will not cause the shell to exit (@pxref{Bash POSIX Mode}).
5170 A failed @code{exec} will not cause the shell to exit
5171 (@pxref{Bourne Shell Builtins}).
5174 Parser syntax errors will not cause the shell to exit.
5177 Simple spelling correction for directory arguments to the @code{cd}
5178 builtin is enabled by default (see the description of the @code{cdspell}
5179 option to the @code{shopt} builtin in @ref{Bash Builtins}).
5182 The shell will check the value of the @env{TMOUT} variable and exit
5183 if a command is not read within the specified number of seconds after
5184 printing @env{$PS1} (@pxref{Bash Variables}).
5188 @node Bash Conditional Expressions
5189 @section Bash Conditional Expressions
5190 @cindex expressions, conditional
5192 Conditional expressions are used by the @code{[[} compound command
5193 and the @code{test} and @code{[} builtin commands.
5195 Expressions may be unary or binary.
5196 Unary expressions are often used to examine the status of a file.
5197 There are string operators and numeric comparison operators as well.
5198 If the @var{file} argument to one of the primaries is of the form
5199 @file{/dev/fd/@var{N}}, then file descriptor @var{N} is checked.
5200 If the @var{file} argument to one of the primaries is one of
5201 @file{/dev/stdin}, @file{/dev/stdout}, or @file{/dev/stderr}, file
5202 descriptor 0, 1, or 2, respectively, is checked.
5206 True if @var{file} exists.
5209 True if @var{file} exists and is a block special file.
5212 True if @var{file} exists and is a character special file.
5215 True if @var{file} exists and is a directory.
5218 True if @var{file} exists.
5221 True if @var{file} exists and is a regular file.
5224 True if @var{file} exists and its set-group-id bit is set.
5227 True if @var{file} exists and is a symbolic link.
5230 True if @var{file} exists and its "sticky" bit is set.
5233 True if @var{file} exists and is a named pipe (FIFO).
5236 True if @var{file} exists and is readable.
5239 True if @var{file} exists and has a size greater than zero.
5242 True if file descriptor @var{fd} is open and refers to a terminal.
5245 True if @var{file} exists and its set-user-id bit is set.
5248 True if @var{file} exists and is writable.
5251 True if @var{file} exists and is executable.
5254 True if @var{file} exists and is owned by the effective user id.
5257 True if @var{file} exists and is owned by the effective group id.
5260 True if @var{file} exists and is a symbolic link.
5263 True if @var{file} exists and is a socket.
5266 True if @var{file} exists and has been modified since it was last read.
5268 @item @var{file1} -nt @var{file2}
5269 True if @var{file1} is newer (according to modification date)
5270 than @var{file2}, or if @var{file1} exists and @var{file2} does not.
5272 @item @var{file1} -ot @var{file2}
5273 True if @var{file1} is older than @var{file2},
5274 or if @var{file2} exists and @var{file1} does not.
5276 @item @var{file1} -ef @var{file2}
5277 True if @var{file1} and @var{file2} refer to the same device and
5280 @item -o @var{optname}
5281 True if shell option @var{optname} is enabled.
5282 The list of options appears in the description of the @option{-o}
5283 option to the @code{set} builtin (@pxref{The Set Builtin}).
5285 @item -z @var{string}
5286 True if the length of @var{string} is zero.
5288 @item -n @var{string}
5290 True if the length of @var{string} is non-zero.
5292 @item @var{string1} == @var{string2}
5293 True if the strings are equal.
5294 @samp{=} may be used in place of @samp{==} for strict @sc{posix} compliance.
5296 @item @var{string1} != @var{string2}
5297 True if the strings are not equal.
5299 @item @var{string1} < @var{string2}
5300 True if @var{string1} sorts before @var{string2} lexicographically
5301 in the current locale.
5303 @item @var{string1} > @var{string2}
5304 True if @var{string1} sorts after @var{string2} lexicographically
5305 in the current locale.
5307 @item @var{arg1} OP @var{arg2}
5309 @samp{-eq}, @samp{-ne}, @samp{-lt}, @samp{-le}, @samp{-gt}, or @samp{-ge}.
5310 These arithmetic binary operators return true if @var{arg1}
5311 is equal to, not equal to, less than, less than or equal to,
5312 greater than, or greater than or equal to @var{arg2},
5313 respectively. @var{Arg1} and @var{arg2}
5314 may be positive or negative integers.
5318 @node Shell Arithmetic
5319 @section Shell Arithmetic
5320 @cindex arithmetic, shell
5321 @cindex shell arithmetic
5322 @cindex expressions, arithmetic
5323 @cindex evaluation, arithmetic
5324 @cindex arithmetic evaluation
5326 The shell allows arithmetic expressions to be evaluated, as one of
5327 the shell expansions or by the @code{let} and the @option{-i} option
5328 to the @code{declare} builtins.
5330 Evaluation is done in fixed-width integers with no check for overflow,
5331 though division by 0 is trapped and flagged as an error.
5332 The operators and their precedence, associativity, and values
5333 are the same as in the C language.
5334 The following list of operators is grouped into levels of
5335 equal-precedence operators.
5336 The levels are listed in order of decreasing precedence.
5340 @item @var{id}++ @var{id}--
5341 variable post-increment and post-decrement
5343 @item ++@var{id} --@var{id}
5344 variable pre-increment and pre-decrement
5347 unary minus and plus
5350 logical and bitwise negation
5356 multiplication, division, remainder
5359 addition, subtraction
5362 left and right bitwise shifts
5368 equality and inequality
5374 bitwise exclusive OR
5385 @item expr ? expr : expr
5386 conditional operator
5388 @item = *= /= %= += -= <<= >>= &= ^= |=
5395 Shell variables are allowed as operands; parameter expansion is
5396 performed before the expression is evaluated.
5397 Within an expression, shell variables may also be referenced by name
5398 without using the parameter expansion syntax.
5399 A shell variable that is null or unset evaluates to 0 when referenced
5400 by name without using the parameter expansion syntax.
5401 The value of a variable is evaluated as an arithmetic expression
5402 when it is referenced, or when a variable which has been given the
5403 @var{integer} attribute using @samp{declare -i} is assigned a value.
5404 A null value evaluates to 0.
5405 A shell variable need not have its integer attribute turned on
5406 to be used in an expression.
5408 Constants with a leading 0 are interpreted as octal numbers.
5409 A leading @samp{0x} or @samp{0X} denotes hexadecimal. Otherwise,
5410 numbers take the form [@var{base}@code{#}]@var{n}, where @var{base}
5411 is a decimal number between 2 and 64 representing the arithmetic
5412 base, and @var{n} is a number in that base. If @var{base}@code{#} is
5413 omitted, then base 10 is used.
5414 The digits greater than 9 are represented by the lowercase letters,
5415 the uppercase letters, @samp{@@}, and @samp{_}, in that order.
5416 If @var{base} is less than or equal to 36, lowercase and uppercase
5417 letters may be used interchangably to represent numbers between 10
5420 Operators are evaluated in order of precedence. Sub-expressions in
5421 parentheses are evaluated first and may override the precedence
5426 @cindex alias expansion
5428 @var{Aliases} allow a string to be substituted for a word when it is used
5429 as the first word of a simple command.
5430 The shell maintains a list of aliases that may be set and unset with
5431 the @code{alias} and @code{unalias} builtin commands.
5433 The first word of each simple command, if unquoted, is checked to see
5435 If so, that word is replaced by the text of the alias.
5436 The characters @samp{/}, @samp{$}, @samp{`}, @samp{=} and any of the
5437 shell metacharacters or quoting characters listed above may not appear
5439 The replacement text may contain any valid
5440 shell input, including shell metacharacters.
5441 The first word of the replacement text is tested for
5442 aliases, but a word that is identical to an alias being expanded
5443 is not expanded a second time.
5444 This means that one may alias @code{ls} to @code{"ls -F"},
5445 for instance, and Bash does not try to recursively expand the
5446 replacement text. If the last character of the alias value is a
5447 space or tab character, then the next command word following the
5448 alias is also checked for alias expansion.
5450 Aliases are created and listed with the @code{alias}
5451 command, and removed with the @code{unalias} command.
5453 There is no mechanism for using arguments in the replacement text,
5455 If arguments are needed, a shell function should be used
5456 (@pxref{Shell Functions}).
5458 Aliases are not expanded when the shell is not interactive,
5459 unless the @code{expand_aliases} shell option is set using
5460 @code{shopt} (@pxref{Bash Builtins}).
5462 The rules concerning the definition and use of aliases are
5463 somewhat confusing. Bash
5464 always reads at least one complete line
5465 of input before executing any
5466 of the commands on that line. Aliases are expanded when a
5467 command is read, not when it is executed. Therefore, an
5468 alias definition appearing on the same line as another
5469 command does not take effect until the next line of input is read.
5470 The commands following the alias definition
5471 on that line are not affected by the new alias.
5472 This behavior is also an issue when functions are executed.
5473 Aliases are expanded when a function definition is read,
5474 not when the function is executed, because a function definition
5475 is itself a compound command. As a consequence, aliases
5476 defined in a function are not available until after that
5477 function is executed. To be safe, always put
5478 alias definitions on a separate line, and do not use @code{alias}
5479 in compound commands.
5481 For almost every purpose, shell functions are preferred over aliases.
5487 Bash provides one-dimensional array variables. Any variable may be used as
5488 an array; the @code{declare} builtin will explicitly declare an array.
5490 limit on the size of an array, nor any requirement that members
5491 be indexed or assigned contiguously. Arrays are zero-based.
5493 An array is created automatically if any variable is assigned to using
5496 name[@var{subscript}]=@var{value}
5501 is treated as an arithmetic expression that must evaluate to a number
5502 greater than or equal to zero. To explicitly declare an array, use
5504 declare -a @var{name}
5509 declare -a @var{name}[@var{subscript}]
5512 is also accepted; the @var{subscript} is ignored. Attributes may be
5513 specified for an array variable using the @code{declare} and
5514 @code{readonly} builtins. Each attribute applies to all members of
5517 Arrays are assigned to using compound assignments of the form
5519 name=(value@var{1} @dots{} value@var{n})
5523 @var{value} is of the form @code{[[@var{subscript}]=]}@var{string}. If
5524 the optional subscript is supplied, that index is assigned to;
5525 otherwise the index of the element assigned is the last index assigned
5526 to by the statement plus one. Indexing starts at zero.
5527 This syntax is also accepted by the @code{declare}
5528 builtin. Individual array elements may be assigned to using the
5529 @code{name[}@var{subscript}@code{]=}@var{value} syntax introduced above.
5531 Any element of an array may be referenced using
5532 @code{$@{name[}@var{subscript}@code{]@}}.
5533 The braces are required to avoid
5534 conflicts with the shell's filename expansion operators. If the
5535 @var{subscript} is @samp{@@} or @samp{*}, the word expands to all members
5536 of the array @var{name}. These subscripts differ only when the word
5537 appears within double quotes. If the word is double-quoted,
5538 @code{$@{name[*]@}} expands to a single word with
5539 the value of each array member separated by the first character of the
5540 @env{IFS} variable, and @code{$@{name[@@]@}} expands each element of
5541 @var{name} to a separate word. When there are no array members,
5542 @code{$@{name[@@]@}} expands to nothing. This is analogous to the
5543 expansion of the special parameters @samp{@@} and @samp{*}.
5544 @code{$@{#name[}@var{subscript}@code{]@}} expands to the length of
5545 @code{$@{name[}@var{subscript}@code{]@}}.
5546 If @var{subscript} is @samp{@@} or
5547 @samp{*}, the expansion is the number of elements in the array.
5548 Referencing an array variable without a subscript is equivalent to
5549 referencing element zero.
5551 The @code{unset} builtin is used to destroy arrays.
5552 @code{unset} @var{name}[@var{subscript}]
5553 destroys the array element at index @var{subscript}.
5554 @code{unset} @var{name}, where @var{name} is an array, removes the
5555 entire array. A subscript of @samp{*} or @samp{@@} also removes the
5558 The @code{declare}, @code{local}, and @code{readonly}
5559 builtins each accept a @option{-a}
5560 option to specify an array. The @code{read}
5561 builtin accepts a @option{-a}
5562 option to assign a list of words read from the standard input
5563 to an array, and can read values from the standard input into
5564 individual array elements. The @code{set} and @code{declare}
5565 builtins display array values in a way that allows them to be
5568 @node The Directory Stack
5569 @section The Directory Stack
5570 @cindex directory stack
5573 * Directory Stack Builtins:: Bash builtin commands to manipulate
5574 the directory stack.
5577 The directory stack is a list of recently-visited directories. The
5578 @code{pushd} builtin adds directories to the stack as it changes
5579 the current directory, and the @code{popd} builtin removes specified
5580 directories from the stack and changes the current directory to
5581 the directory removed. The @code{dirs} builtin displays the contents
5582 of the directory stack.
5584 The contents of the directory stack are also visible
5585 as the value of the @env{DIRSTACK} shell variable.
5587 @node Directory Stack Builtins
5588 @subsection Directory Stack Builtins
5595 dirs [+@var{N} | -@var{N}] [-clpv]
5597 Display the list of currently remembered directories. Directories
5598 are added to the list with the @code{pushd} command; the
5599 @code{popd} command removes directories from the list.
5602 Displays the @var{N}th directory (counting from the left of the
5603 list printed by @code{dirs} when invoked without options), starting
5606 Displays the @var{N}th directory (counting from the right of the
5607 list printed by @code{dirs} when invoked without options), starting
5610 Clears the directory stack by deleting all of the elements.
5612 Produces a longer listing; the default listing format uses a
5613 tilde to denote the home directory.
5615 Causes @code{dirs} to print the directory stack with one entry per
5618 Causes @code{dirs} to print the directory stack with one entry per
5619 line, prefixing each entry with its index in the stack.
5625 popd [+@var{N} | -@var{N}] [-n]
5628 Remove the top entry from the directory stack, and @code{cd}
5629 to the new top directory.
5630 When no arguments are given, @code{popd}
5631 removes the top directory from the stack and
5632 performs a @code{cd} to the new top directory. The
5633 elements are numbered from 0 starting at the first directory listed with
5634 @code{dirs}; i.e., @code{popd} is equivalent to @code{popd +0}.
5637 Removes the @var{N}th directory (counting from the left of the
5638 list printed by @code{dirs}), starting with zero.
5640 Removes the @var{N}th directory (counting from the right of the
5641 list printed by @code{dirs}), starting with zero.
5643 Suppresses the normal change of directory when removing directories
5644 from the stack, so that only the stack is manipulated.
5650 pushd [@var{dir} | @var{+N} | @var{-N}] [-n]
5653 Save the current directory on the top of the directory stack
5654 and then @code{cd} to @var{dir}.
5655 With no arguments, @code{pushd} exchanges the top two directories.
5659 Brings the @var{N}th directory (counting from the left of the
5660 list printed by @code{dirs}, starting with zero) to the top of
5661 the list by rotating the stack.
5663 Brings the @var{N}th directory (counting from the right of the
5664 list printed by @code{dirs}, starting with zero) to the top of
5665 the list by rotating the stack.
5667 Suppresses the normal change of directory when adding directories
5668 to the stack, so that only the stack is manipulated.
5670 Makes the current working directory be the top of the stack, and then
5671 executes the equivalent of `@code{cd} @var{dir}'.
5672 @code{cd}s to @var{dir}.
5677 @node Printing a Prompt
5678 @section Controlling the Prompt
5681 The value of the variable @env{PROMPT_COMMAND} is examined just before
5682 Bash prints each primary prompt. If @env{PROMPT_COMMAND} is set and
5683 has a non-null value, then the
5684 value is executed just as if it had been typed on the command line.
5686 In addition, the following table describes the special characters which
5687 can appear in the prompt variables:
5693 The date, in "Weekday Month Date" format (e.g., "Tue May 26").
5694 @item \D@{@var{format}@}
5695 The @var{format} is passed to @code{strftime}(3) and the result is inserted
5696 into the prompt string; an empty @var{format} results in a locale-specific
5697 time representation. The braces are required.
5699 An escape character.
5701 The hostname, up to the first `.'.
5705 The number of jobs currently managed by the shell.
5707 The basename of the shell's terminal device name.
5713 The name of the shell, the basename of @code{$0} (the portion
5714 following the final slash).
5716 The time, in 24-hour HH:MM:SS format.
5718 The time, in 12-hour HH:MM:SS format.
5720 The time, in 12-hour am/pm format.
5722 The time, in 24-hour HH:MM format.
5724 The username of the current user.
5726 The version of Bash (e.g., 2.00)
5728 The release of Bash, version + patchlevel (e.g., 2.00.0)
5730 The current working directory, with @env{$HOME} abbreviated with a tilde.
5732 The basename of @env{$PWD}, with @env{$HOME} abbreviated with a tilde.
5734 The history number of this command.
5736 The command number of this command.
5738 If the effective uid is 0, @code{#}, otherwise @code{$}.
5740 The character whose ASCII code is the octal value @var{nnn}.
5744 Begin a sequence of non-printing characters. This could be used to
5745 embed a terminal control sequence into the prompt.
5747 End a sequence of non-printing characters.
5750 The command number and the history number are usually different:
5751 the history number of a command is its position in the history
5752 list, which may include commands restored from the history file
5753 (@pxref{Bash History Facilities}), while the command number is
5754 the position in the sequence of commands executed during the current
5757 After the string is decoded, it is expanded via
5758 parameter expansion, command substitution, arithmetic
5759 expansion, and quote removal, subject to the value of the
5760 @code{promptvars} shell option (@pxref{Bash Builtins}).
5762 @node The Restricted Shell
5763 @section The Restricted Shell
5764 @cindex restricted shell
5766 If Bash is started with the name @code{rbash}, or the
5767 @option{--restricted}
5770 option is supplied at invocation, the shell becomes restricted.
5771 A restricted shell is used to
5772 set up an environment more controlled than the standard shell.
5773 A restricted shell behaves identically to @code{bash}
5774 with the exception that the following are disallowed or not performed:
5778 Changing directories with the @code{cd} builtin.
5780 Setting or unsetting the values of the @env{SHELL}, @env{PATH},
5781 @env{ENV}, or @env{BASH_ENV} variables.
5783 Specifying command names containing slashes.
5785 Specifying a filename containing a slash as an argument to the @code{.}
5788 Specifying a filename containing a slash as an argument to the @option{-p}
5789 option to the @code{hash} builtin command.
5791 Importing function definitions from the shell environment at startup.
5793 Parsing the value of @env{SHELLOPTS} from the shell environment at startup.
5795 Redirecting output using the @samp{>}, @samp{>|}, @samp{<>}, @samp{>&},
5796 @samp{&>}, and @samp{>>} redirection operators.
5798 Using the @code{exec} builtin to replace the shell with another command.
5800 Adding or deleting builtin commands with the
5801 @option{-f} and @option{-d} options to the @code{enable} builtin.
5803 Using the @code{enable} builtin command to enable disabled shell builtins.
5805 Specifying the @option{-p} option to the @code{command} builtin.
5807 Turning off restricted mode with @samp{set +r} or @samp{set +o restricted}.
5810 These restrictions are enforced after any startup files are read.
5812 When a command that is found to be a shell script is executed
5813 (@pxref{Shell Scripts}), @code{rbash} turns off any restrictions in
5814 the shell spawned to execute the script.
5816 @node Bash POSIX Mode
5817 @section Bash POSIX Mode
5820 Starting Bash with the @option{--posix} command-line option or executing
5821 @samp{set -o posix} while Bash is running will cause Bash to conform more
5822 closely to the @sc{posix} 1003.2 standard by changing the behavior to
5823 match that specified by @sc{posix} in areas where the Bash default differs.
5825 When invoked as @code{sh}, Bash enters @sc{posix} mode after reading the
5828 The following list is what's changed when `@sc{posix} mode' is in effect:
5832 When a command in the hash table no longer exists, Bash will re-search
5833 @env{$PATH} to find the new location. This is also available with
5834 @samp{shopt -s checkhash}.
5837 The message printed by the job control code and builtins when a job
5838 exits with a non-zero status is `Done(status)'.
5841 The message printed by the job control code and builtins when a job
5842 is stopped is `Stopped(@var{signame})', where @var{signame} is, for
5843 example, @code{SIGTSTP}.
5846 Reserved words may not be aliased.
5849 The @sc{posix} 1003.2 @env{PS1} and @env{PS2} expansions of @samp{!} to
5850 the history number and @samp{!!} to @samp{!} are enabled,
5851 and parameter expansion is performed on the values of @env{PS1} and
5852 @env{PS2} regardless of the setting of the @code{promptvars} option.
5855 The @sc{posix} 1003.2 startup files are executed (@env{$ENV}) rather than
5856 the normal Bash files.
5859 Tilde expansion is only performed on assignments preceding a command
5860 name, rather than on all assignment statements on the line.
5863 The default history file is @file{~/.sh_history} (this is the
5864 default value of @env{$HISTFILE}).
5867 The output of @samp{kill -l} prints all the signal names on a single line,
5868 separated by spaces, without the @samp{SIG} prefix.
5871 The @code{kill} builtin does not accept signal names with a @samp{SIG}
5875 Non-interactive shells exit if @var{filename} in @code{.} @var{filename}
5879 Non-interactive shells exit if a syntax error in an arithmetic expansion
5880 results in an invalid expression.
5883 Redirection operators do not perform filename expansion on the word
5884 in the redirection unless the shell is interactive.
5887 Redirection operators do not perform word splitting on the word in the
5891 Function names must be valid shell @code{name}s. That is, they may not
5892 contain characters other than letters, digits, and underscores, and
5893 may not start with a digit. Declaring a function with an invalid name
5894 causes a fatal syntax error in non-interactive shells.
5897 @sc{posix} 1003.2 `special' builtins are found before shell functions
5898 during command lookup.
5901 If a @sc{posix} 1003.2 special builtin returns an error status, a
5902 non-interactive shell exits. The fatal errors are those listed in
5903 the POSIX.2 standard, and include things like passing incorrect options,
5904 redirection errors, variable assignment errors for assignments preceding
5905 the command name, and so on.
5908 If the @code{cd} builtin finds a directory to change to
5909 using @env{$CDPATH}, the
5910 value it assigns to the @env{PWD} variable does not contain any
5911 symbolic links, as if @samp{cd -P} had been executed.
5914 If @env{CDPATH} is set, the @code{cd} builtin will not implicitly
5915 append the current directory to it. This means that @code{cd} will
5916 fail if no valid directory name can be constructed from
5917 any of the entries in @env{$CDPATH}, even if the a directory with
5918 the same name as the name given as an argument to @code{cd} exists
5919 in the current directory.
5922 A non-interactive shell exits with an error status if a variable
5923 assignment error occurs when no command name follows the assignment
5925 A variable assignment error occurs, for example, when trying to assign
5926 a value to a readonly variable.
5929 A non-interactive shell exits with an error status if the iteration
5930 variable in a @code{for} statement or the selection variable in a
5931 @code{select} statement is a readonly variable.
5934 Process substitution is not available.
5937 Assignment statements preceding @sc{posix} 1003.2 special builtins
5938 persist in the shell environment after the builtin completes.
5941 Assignment statements preceding shell function calls persist in the
5942 shell environment after the function returns, as if a @sc{posix}
5943 special builtin command had been executed.
5946 The @code{export} and @code{readonly} builtin commands display their
5947 output in the format required by @sc{posix} 1003.2.
5950 The @code{trap} builtin displays signal names without the leading
5954 The @code{trap} builtin doesn't check the first argument for a possible
5955 signal specification and revert the signal handling to the original
5956 disposition if it is. If users want to reset the handler for a given
5957 signal to the original disposition, they should use @samp{-} as the
5961 The @code{.} and @code{source} builtins do not search the current directory
5962 for the filename argument if it is not found by searching @env{PATH}.
5965 Subshells spawned to execute command substitutions inherit the value of
5966 the @option{-e} option from the parent shell. When not in @sc{posix} mode,
5967 Bash clears the @option{-e} option in such subshells.
5970 Alias expansion is always enabled, even in non-interactive shells.
5973 When the @code{alias} builtin displays alias definitions, it does not
5974 display them with a leading @samp{alias } unless the @option{-p} option
5978 When the @code{set} builtin is invoked without options, it does not display
5979 shell function names and definitions.
5982 When the @code{set} builtin is invoked without options, it displays
5983 variable values without quotes, unless they contain shell metacharacters,
5984 even if the result contains nonprinting characters.
5987 When the @code{cd} builtin is invoked in @var{logical} mode, and the pathname
5988 constructed from @code{$PWD} and the directory name supplied as an argument
5989 does not refer to an existing directory, @code{cd} will fail instead of
5990 falling back to @var{physical} mode.
5993 There is other @sc{posix} 1003.2 behavior that Bash does not implement.
5998 Assignment statements affect the execution environment of all
5999 builtins, not just special ones.
6002 When a subshell is created to execute a shell script with execute permission,
6003 but without a leading @samp{#!}, Bash sets @code{$0} to the full pathname of
6004 the script as found by searching @code{$PATH}, rather than the command as
6008 When using @samp{.} to source a shell script found in @code{$PATH}, bash
6009 checks execute permission bits rather than read permission bits, just as
6010 if it were searching for a command.
6015 @chapter Job Control
6017 This chapter discusses what job control is, how it works, and how
6018 Bash allows you to access its facilities.
6021 * Job Control Basics:: How job control works.
6022 * Job Control Builtins:: Bash builtin commands used to interact
6024 * Job Control Variables:: Variables Bash uses to customize job
6028 @node Job Control Basics
6029 @section Job Control Basics
6033 @cindex suspending jobs
6036 refers to the ability to selectively stop (suspend)
6037 the execution of processes and continue (resume)
6038 their execution at a later point. A user typically employs
6039 this facility via an interactive interface supplied jointly
6040 by the system's terminal driver and Bash.
6042 The shell associates a @var{job} with each pipeline. It keeps a
6043 table of currently executing jobs, which may be listed with the
6044 @code{jobs} command. When Bash starts a job
6045 asynchronously, it prints a line that looks
6051 indicating that this job is job number 1 and that the process @sc{id}
6052 of the last process in the pipeline associated with this job is
6053 25647. All of the processes in a single pipeline are members of
6054 the same job. Bash uses the @var{job} abstraction as the
6055 basis for job control.
6057 To facilitate the implementation of the user interface to job
6058 control, the operating system maintains the notion of a current terminal
6059 process group @sc{id}. Members of this process group (processes whose
6060 process group @sc{id} is equal to the current terminal process group
6061 @sc{id}) receive keyboard-generated signals such as @code{SIGINT}.
6062 These processes are said to be in the foreground. Background
6063 processes are those whose process group @sc{id} differs from the
6064 terminal's; such processes are immune to keyboard-generated
6065 signals. Only foreground processes are allowed to read from or
6066 write to the terminal. Background processes which attempt to
6067 read from (write to) the terminal are sent a @code{SIGTTIN}
6068 (@code{SIGTTOU}) signal by the terminal driver, which, unless
6069 caught, suspends the process.
6071 If the operating system on which Bash is running supports
6072 job control, Bash contains facilities to use it. Typing the
6073 @var{suspend} character (typically @samp{^Z}, Control-Z) while a
6074 process is running causes that process to be stopped and returns
6075 control to Bash. Typing the @var{delayed suspend} character
6076 (typically @samp{^Y}, Control-Y) causes the process to be stopped
6077 when it attempts to read input from the terminal, and control to
6078 be returned to Bash. The user then manipulates the state of
6079 this job, using the @code{bg} command to continue it in the
6080 background, the @code{fg} command to continue it in the
6081 foreground, or the @code{kill} command to kill it. A @samp{^Z}
6082 takes effect immediately, and has the additional side effect of
6083 causing pending output and typeahead to be discarded.
6085 There are a number of ways to refer to a job in the shell. The
6086 character @samp{%} introduces a job name.
6088 Job number @code{n} may be referred to as @samp{%n}.
6089 The symbols @samp{%%} and
6090 @samp{%+} refer to the shell's notion of the current job, which
6091 is the last job stopped while it was in the foreground or started
6092 in the background. The
6093 previous job may be referenced using @samp{%-}. In output
6094 pertaining to jobs (e.g., the output of the @code{jobs} command),
6095 the current job is always flagged with a @samp{+}, and the
6096 previous job with a @samp{-}.
6098 A job may also be referred to
6099 using a prefix of the name used to start it, or using a substring
6100 that appears in its command line. For example, @samp{%ce} refers
6101 to a stopped @code{ce} job. Using @samp{%?ce}, on the
6102 other hand, refers to any job containing the string @samp{ce} in
6103 its command line. If the prefix or substring matches more than one job,
6104 Bash reports an error.
6106 Simply naming a job can be used to bring it into the foreground:
6107 @samp{%1} is a synonym for @samp{fg %1}, bringing job 1 from the
6108 background into the foreground. Similarly, @samp{%1 &} resumes
6109 job 1 in the background, equivalent to @samp{bg %1}
6111 The shell learns immediately whenever a job changes state.
6112 Normally, Bash waits until it is about to print a prompt
6113 before reporting changes in a job's status so as to not interrupt
6115 If the @option{-b} option to the @code{set} builtin is enabled,
6116 Bash reports such changes immediately (@pxref{The Set Builtin}).
6117 Any trap on @code{SIGCHLD} is executed for each child process
6120 If an attempt to exit Bash is made while jobs are stopped, the
6121 shell prints a message warning that there are stopped jobs.
6122 The @code{jobs} command may then be used to inspect their status.
6123 If a second attempt to exit is made without an intervening command,
6124 Bash does not print another warning, and the stopped jobs are terminated.
6126 @node Job Control Builtins
6127 @section Job Control Builtins
6136 Resume the suspended job @var{jobspec} in the background, as if it
6137 had been started with @samp{&}.
6138 If @var{jobspec} is not supplied, the current job is used.
6139 The return status is zero unless it is run when job control is not
6140 enabled, or, when run with job control enabled, if @var{jobspec} was
6141 not found or @var{jobspec} specifies a job that was started without
6149 Resume the job @var{jobspec} in the foreground and make it the current job.
6150 If @var{jobspec} is not supplied, the current job is used.
6151 The return status is that of the command placed into the foreground,
6152 or non-zero if run when job control is disabled or, when run with
6153 job control enabled, @var{jobspec} does not specify a valid job or
6154 @var{jobspec} specifies a job that was started without job control.
6159 jobs [-lnprs] [@var{jobspec}]
6160 jobs -x @var{command} [@var{arguments}]
6163 The first form lists the active jobs. The options have the
6168 List process @sc{id}s in addition to the normal information.
6171 Display information only about jobs that have changed status since
6172 the user was last notified of their status.
6175 List only the process @sc{id} of the job's process group leader.
6178 Restrict output to running jobs.
6181 Restrict output to stopped jobs.
6184 If @var{jobspec} is given,
6185 output is restricted to information about that job.
6186 If @var{jobspec} is not supplied, the status of all jobs is
6189 If the @option{-x} option is supplied, @code{jobs} replaces any
6190 @var{jobspec} found in @var{command} or @var{arguments} with the
6191 corresponding process group @sc{id}, and executes @var{command},
6192 passing it @var{argument}s, returning its exit status.
6197 kill [-s @var{sigspec}] [-n @var{signum}] [-@var{sigspec}] @var{jobspec} or @var{pid}
6198 kill -l [@var{exit_status}]
6200 Send a signal specified by @var{sigspec} or @var{signum} to the process
6201 named by job specification @var{jobspec} or process @sc{id} @var{pid}.
6202 @var{sigspec} is either a case-insensitive signal name such as
6203 @code{SIGINT} (with or without the @code{SIG} prefix)
6204 or a signal number; @var{signum} is a signal number.
6205 If @var{sigspec} and @var{signum} are not present, @code{SIGTERM} is used.
6206 The @option{-l} option lists the signal names.
6207 If any arguments are supplied when @option{-l} is given, the names of the
6208 signals corresponding to the arguments are listed, and the return status
6210 @var{exit_status} is a number specifying a signal number or the exit
6211 status of a process terminated by a signal.
6212 The return status is zero if at least one signal was successfully sent,
6213 or non-zero if an error occurs or an invalid option is encountered.
6218 wait [@var{jobspec} or @var{pid}]
6220 Wait until the child process specified by process @sc{id} @var{pid} or job
6221 specification @var{jobspec} exits and return the exit status of the last
6223 If a job spec is given, all processes in the job are waited for.
6224 If no arguments are given, all currently active child processes are
6225 waited for, and the return status is zero.
6226 If neither @var{jobspec} nor @var{pid} specifies an active child process
6227 of the shell, the return status is 127.
6232 disown [-ar] [-h] [@var{jobspec} @dots{}]
6234 Without options, each @var{jobspec} is removed from the table of
6236 If the @option{-h} option is given, the job is not removed from the table,
6237 but is marked so that @code{SIGHUP} is not sent to the job if the shell
6238 receives a @code{SIGHUP}.
6239 If @var{jobspec} is not present, and neither the @option{-a} nor @option{-r}
6240 option is supplied, the current job is used.
6241 If no @var{jobspec} is supplied, the @option{-a} option means to remove or
6242 mark all jobs; the @option{-r} option without a @var{jobspec}
6243 argument restricts operation to running jobs.
6250 Suspend the execution of this shell until it receives a
6251 @code{SIGCONT} signal. The @option{-f} option means to suspend
6252 even if the shell is a login shell.
6256 When job control is not active, the @code{kill} and @code{wait}
6257 builtins do not accept @var{jobspec} arguments. They must be
6258 supplied process @sc{id}s.
6260 @node Job Control Variables
6261 @section Job Control Variables
6266 This variable controls how the shell interacts with the user and
6267 job control. If this variable exists then single word simple
6268 commands without redirections are treated as candidates for resumption
6269 of an existing job. There is no ambiguity allowed; if there is
6270 more than one job beginning with the string typed, then
6271 the most recently accessed job will be selected.
6272 The name of a stopped job, in this context, is the command line
6273 used to start it. If this variable is set to the value @samp{exact},
6274 the string supplied must match the name of a stopped job exactly;
6275 if set to @samp{substring},
6276 the string supplied needs to match a substring of the name of a
6277 stopped job. The @samp{substring} value provides functionality
6278 analogous to the @samp{%?} job @sc{id} (@pxref{Job Control Basics}).
6279 If set to any other value, the supplied string must
6280 be a prefix of a stopped job's name; this provides functionality
6281 analogous to the @samp{%} job @sc{id}.
6285 @set readline-appendix
6286 @set history-appendix
6287 @cindex Readline, how to use
6288 @include rluser.texi
6289 @cindex History, how to use
6290 @include hsuser.texi
6291 @clear readline-appendix
6292 @clear history-appendix
6294 @node Installing Bash
6295 @chapter Installing Bash
6297 This chapter provides basic instructions for installing Bash on
6298 the various supported platforms. The distribution supports the
6299 @sc{gnu} operating systems, nearly every version of Unix, and several
6300 non-Unix systems such as BeOS and Interix.
6301 Other independent ports exist for
6302 @sc{ms-dos}, @sc{os/2}, and Windows platforms.
6305 * Basic Installation:: Installation instructions.
6307 * Compilers and Options:: How to set special options for various
6310 * Compiling For Multiple Architectures:: How to compile Bash for more
6311 than one kind of system from
6312 the same source tree.
6314 * Installation Names:: How to set the various paths used by the installation.
6316 * Specifying the System Type:: How to configure Bash for a particular system.
6318 * Sharing Defaults:: How to share default configuration values among GNU
6321 * Operation Controls:: Options recognized by the configuration program.
6323 * Optional Features:: How to enable and disable optional features when
6327 @node Basic Installation
6328 @section Basic Installation
6329 @cindex installation
6330 @cindex configuration
6331 @cindex Bash installation
6332 @cindex Bash configuration
6334 These are installation instructions for Bash.
6336 The simplest way to compile Bash is:
6340 @code{cd} to the directory containing the source code and type
6341 @samp{./configure} to configure Bash for your system. If you're
6342 using @code{csh} on an old version of System V, you might need to
6343 type @samp{sh ./configure} instead to prevent @code{csh} from trying
6344 to execute @code{configure} itself.
6346 Running @code{configure} takes some time.
6347 While running, it prints messages telling which features it is
6351 Type @samp{make} to compile Bash and build the @code{bashbug} bug
6355 Optionally, type @samp{make tests} to run the Bash test suite.
6358 Type @samp{make install} to install @code{bash} and @code{bashbug}.
6359 This will also install the manual pages and Info file.
6363 The @code{configure} shell script attempts to guess correct
6364 values for various system-dependent variables used during
6365 compilation. It uses those values to create a @file{Makefile} in
6366 each directory of the package (the top directory, the
6367 @file{builtins}, @file{doc}, and @file{support} directories,
6368 each directory under @file{lib}, and several others). It also creates a
6369 @file{config.h} file containing system-dependent definitions.
6370 Finally, it creates a shell script named @code{config.status} that you
6371 can run in the future to recreate the current configuration, a
6372 file @file{config.cache} that saves the results of its tests to
6373 speed up reconfiguring, and a file @file{config.log} containing
6374 compiler output (useful mainly for debugging @code{configure}).
6376 @file{config.cache} contains results you don't want to keep, you
6377 may remove or edit it.
6379 To find out more about the options and arguments that the
6380 @code{configure} script understands, type
6383 bash-2.04$ ./configure --help
6387 at the Bash prompt in your Bash source directory.
6389 If you need to do unusual things to compile Bash, please
6390 try to figure out how @code{configure} could check whether or not
6391 to do them, and mail diffs or instructions to
6392 @email{bash-maintainers@@gnu.org} so they can be
6393 considered for the next release.
6395 The file @file{configure.in} is used to create @code{configure}
6396 by a program called Autoconf. You only need
6397 @file{configure.in} if you want to change it or regenerate
6398 @code{configure} using a newer version of Autoconf. If
6399 you do this, make sure you are using Autoconf version 2.50 or
6402 You can remove the program binaries and object files from the
6403 source code directory by typing @samp{make clean}. To also remove the
6404 files that @code{configure} created (so you can compile Bash for
6405 a different kind of computer), type @samp{make distclean}.
6407 @node Compilers and Options
6408 @section Compilers and Options
6410 Some systems require unusual options for compilation or linking
6411 that the @code{configure} script does not know about. You can
6412 give @code{configure} initial values for variables by setting
6413 them in the environment. Using a Bourne-compatible shell, you
6414 can do that on the command line like this:
6417 CC=c89 CFLAGS=-O2 LIBS=-lposix ./configure
6420 On systems that have the @code{env} program, you can do it like this:
6423 env CPPFLAGS=-I/usr/local/include LDFLAGS=-s ./configure
6426 The configuration process uses GCC to build Bash if it
6429 @node Compiling For Multiple Architectures
6430 @section Compiling For Multiple Architectures
6432 You can compile Bash for more than one kind of computer at the
6433 same time, by placing the object files for each architecture in their
6434 own directory. To do this, you must use a version of @code{make} that
6435 supports the @code{VPATH} variable, such as GNU @code{make}.
6437 directory where you want the object files and executables to go and run
6438 the @code{configure} script from the source directory. You may need to
6439 supply the @option{--srcdir=PATH} argument to tell @code{configure} where the
6440 source files are. @code{configure} automatically checks for the
6441 source code in the directory that @code{configure} is in and in `..'.
6443 If you have to use a @code{make} that does not supports the @code{VPATH}
6444 variable, you can compile Bash for one architecture at a
6445 time in the source code directory. After you have installed
6446 Bash for one architecture, use @samp{make distclean} before
6447 reconfiguring for another architecture.
6449 Alternatively, if your system supports symbolic links, you can use the
6450 @file{support/mkclone} script to create a build tree which has
6451 symbolic links back to each file in the source directory. Here's an
6452 example that creates a build directory in the current directory from a
6453 source directory @file{/usr/gnu/src/bash-2.0}:
6456 bash /usr/gnu/src/bash-2.0/support/mkclone -s /usr/gnu/src/bash-2.0 .
6460 The @code{mkclone} script requires Bash, so you must have already built
6461 Bash for at least one architecture before you can create build
6462 directories for other architectures.
6464 @node Installation Names
6465 @section Installation Names
6467 By default, @samp{make install} will install into
6468 @file{/usr/local/bin}, @file{/usr/local/man}, etc. You can
6469 specify an installation prefix other than @file{/usr/local} by
6470 giving @code{configure} the option @option{--prefix=@var{PATH}},
6471 or by specifying a value for the @code{DESTDIR} @samp{make}
6472 variable when running @samp{make install}.
6474 You can specify separate installation prefixes for
6475 architecture-specific files and architecture-independent files.
6476 If you give @code{configure} the option
6477 @option{--exec-prefix=@var{PATH}}, @samp{make install} will use
6478 @var{PATH} as the prefix for installing programs and libraries.
6479 Documentation and other data files will still use the regular prefix.
6481 @node Specifying the System Type
6482 @section Specifying the System Type
6484 There may be some features @code{configure} can not figure out
6485 automatically, but need to determine by the type of host Bash
6486 will run on. Usually @code{configure} can figure that
6487 out, but if it prints a message saying it can not guess the host
6488 type, give it the @option{--host=TYPE} option. @samp{TYPE} can
6489 either be a short name for the system type, such as @samp{sun4},
6490 or a canonical name with three fields: @samp{CPU-COMPANY-SYSTEM}
6491 (e.g., @samp{i386-unknown-freebsd4.2}).
6493 See the file @file{support/config.sub} for the possible
6494 values of each field.
6496 @node Sharing Defaults
6497 @section Sharing Defaults
6499 If you want to set default values for @code{configure} scripts to
6500 share, you can create a site shell script called
6501 @code{config.site} that gives default values for variables like
6502 @code{CC}, @code{cache_file}, and @code{prefix}. @code{configure}
6503 looks for @file{PREFIX/share/config.site} if it exists, then
6504 @file{PREFIX/etc/config.site} if it exists. Or, you can set the
6505 @code{CONFIG_SITE} environment variable to the location of the site
6506 script. A warning: the Bash @code{configure} looks for a site script,
6507 but not all @code{configure} scripts do.
6509 @node Operation Controls
6510 @section Operation Controls
6512 @code{configure} recognizes the following options to control how it
6517 @item --cache-file=@var{file}
6518 Use and save the results of the tests in
6519 @var{file} instead of @file{./config.cache}. Set @var{file} to
6520 @file{/dev/null} to disable caching, for debugging
6524 Print a summary of the options to @code{configure}, and exit.
6529 Do not print messages saying which checks are being made.
6531 @item --srcdir=@var{dir}
6532 Look for the Bash source code in directory @var{dir}. Usually
6533 @code{configure} can determine that directory automatically.
6536 Print the version of Autoconf used to generate the @code{configure}
6540 @code{configure} also accepts some other, not widely used, boilerplate
6541 options. @samp{configure --help} prints the complete list.
6543 @node Optional Features
6544 @section Optional Features
6546 The Bash @code{configure} has a number of @option{--enable-@var{feature}}
6547 options, where @var{feature} indicates an optional part of Bash.
6548 There are also several @option{--with-@var{package}} options,
6549 where @var{package} is something like @samp{bash-malloc} or @samp{purify}.
6550 To turn off the default use of a package, use
6551 @option{--without-@var{package}}. To configure Bash without a feature
6552 that is enabled by default, use @option{--disable-@var{feature}}.
6554 Here is a complete list of the @option{--enable-} and
6555 @option{--with-} options that the Bash @code{configure} recognizes.
6559 Define if you are using the Andrew File System from Transarc.
6561 @item --with-bash-malloc
6562 Use the Bash version of
6563 @code{malloc} in @file{lib/malloc/malloc.c}. This is not the same
6564 @code{malloc} that appears in @sc{gnu} libc, but an older version
6565 derived from the 4.2 @sc{bsd} @code{malloc}. This @code{malloc} is
6566 very fast, but wastes some space on each allocation.
6567 This option is enabled by default.
6568 The @file{NOTES} file contains a list of systems for
6569 which this should be turned off, and @code{configure} disables this
6570 option automatically for a number of systems.
6573 Use the curses library instead of the termcap library. This should
6574 be supplied if your system has an inadequate or incomplete termcap
6577 @item --with-gnu-malloc
6578 A synonym for @code{--with-bash-malloc}.
6580 @item --with-installed-readline[=@var{PREFIX}]
6581 Define this to make Bash link with a locally-installed version of Readline
6582 rather than the version in @file{lib/readline}. This works only with
6583 Readline 4.3 and later versions. If @var{PREFIX} is @code{yes} or not
6584 supplied, @code{configure} uses the values of the make variables
6585 @code{includedir} and @code{libdir}, which are subdirectories of @code{prefix}
6586 by default, to find the installed version of Readline if it is not in
6587 the standard system include and library directories.
6588 If @var{PREFIX} is @code{no}, Bash links with the version in
6589 @file{lib/readline}.
6590 If @var{PREFIX} is set to any other value, @code{configure} treats it as
6591 a directory pathname and looks for
6592 the installed version of Readline in subdirectories of that directory
6593 (include files in @var{PREFIX}/@code{include} and the library in
6594 @var{PREFIX}/@code{lib}).
6597 Define this to use the Purify memory allocation checker from Rational
6600 @item --enable-minimal-config
6601 This produces a shell with minimal features, close to the historical
6605 There are several @option{--enable-} options that alter how Bash is
6606 compiled and linked, rather than changing run-time features.
6609 @item --enable-largefile
6610 Enable support for @uref{http://www.sas.com/standards/large_file/x_open.20Mar96.html,
6611 large files} if the operating system requires special compiler options
6612 to build programs which can access large files. This is enabled by
6613 default, if the operating system provides large file support.
6615 @item --enable-profiling
6616 This builds a Bash binary that produces profiling information to be
6617 processed by @code{gprof} each time it is executed.
6619 @item --enable-static-link
6620 This causes Bash to be linked statically, if @code{gcc} is being used.
6621 This could be used to build a version to use as root's shell.
6624 The @samp{minimal-config} option can be used to disable all of
6625 the following options, but it is processed first, so individual
6626 options may be enabled using @samp{enable-@var{feature}}.
6628 All of the following options except for @samp{disabled-builtins} and
6629 @samp{xpg-echo-default} are
6630 enabled by default, unless the operating system does not provide the
6634 @item --enable-alias
6635 Allow alias expansion and include the @code{alias} and @code{unalias}
6636 builtins (@pxref{Aliases}).
6638 @item --enable-arith-for-command
6639 Include support for the alternate form of the @code{for} command
6640 that behaves like the C language @code{for} statement
6641 (@pxref{Looping Constructs}).
6643 @item --enable-array-variables
6644 Include support for one-dimensional array shell variables
6647 @item --enable-bang-history
6648 Include support for @code{csh}-like history substitution
6649 (@pxref{History Interaction}).
6651 @item --enable-brace-expansion
6652 Include @code{csh}-like brace expansion
6653 ( @code{b@{a,b@}c} @expansion{} @code{bac bbc} ).
6654 See @ref{Brace Expansion}, for a complete description.
6656 @item --enable-command-timing
6657 Include support for recognizing @code{time} as a reserved word and for
6658 displaying timing statistics for the pipeline following @code{time}
6659 (@pxref{Pipelines}).
6660 This allows pipelines as well as shell builtins and functions to be timed.
6662 @item --enable-cond-command
6663 Include support for the @code{[[} conditional command.
6664 (@pxref{Conditional Constructs}).
6666 @item --enable-cond-regexp
6667 Include support for matching POSIX regular expressions using the
6668 @samp{=~} binary operator in the @code{[[} conditional command.
6669 (@pxref{Conditional Constructs}).
6671 @item --enable-directory-stack
6672 Include support for a @code{csh}-like directory stack and the
6673 @code{pushd}, @code{popd}, and @code{dirs} builtins
6674 (@pxref{The Directory Stack}).
6676 @item --enable-disabled-builtins
6677 Allow builtin commands to be invoked via @samp{builtin xxx}
6678 even after @code{xxx} has been disabled using @samp{enable -n xxx}.
6679 See @ref{Bash Builtins}, for details of the @code{builtin} and
6680 @code{enable} builtin commands.
6682 @item --enable-dparen-arithmetic
6683 Include support for the @code{((@dots{}))} command
6684 (@pxref{Conditional Constructs}).
6686 @item --enable-extended-glob
6687 Include support for the extended pattern matching features described
6688 above under @ref{Pattern Matching}.
6690 @item --enable-help-builtin
6691 Include the @code{help} builtin, which displays help on shell builtins and
6692 variables (@pxref{Bash Builtins}).
6694 @item --enable-history
6695 Include command history and the @code{fc} and @code{history}
6696 builtin commands (@pxref{Bash History Facilities}).
6698 @item --enable-job-control
6699 This enables the job control features (@pxref{Job Control}),
6700 if the operating system supports them.
6702 @item --enable-multibyte
6703 This enables support for multibyte characters if the operating
6704 system provides the necessary support.
6706 @item --enable-net-redirections
6707 This enables the special handling of filenames of the form
6708 @code{/dev/tcp/@var{host}/@var{port}} and
6709 @code{/dev/udp/@var{host}/@var{port}}
6710 when used in redirections (@pxref{Redirections}).
6712 @item --enable-process-substitution
6713 This enables process substitution (@pxref{Process Substitution}) if
6714 the operating system provides the necessary support.
6716 @item --enable-prompt-string-decoding
6717 Turn on the interpretation of a number of backslash-escaped characters
6718 in the @env{$PS1}, @env{$PS2}, @env{$PS3}, and @env{$PS4} prompt
6719 strings. See @ref{Printing a Prompt}, for a complete list of prompt
6720 string escape sequences.
6722 @item --enable-progcomp
6723 Enable the programmable completion facilities
6724 (@pxref{Programmable Completion}).
6725 If Readline is not enabled, this option has no effect.
6727 @item --enable-readline
6728 Include support for command-line editing and history with the Bash
6729 version of the Readline library (@pxref{Command Line Editing}).
6731 @item --enable-restricted
6732 Include support for a @dfn{restricted shell}. If this is enabled, Bash,
6733 when called as @code{rbash}, enters a restricted mode. See
6734 @ref{The Restricted Shell}, for a description of restricted mode.
6736 @item --enable-select
6737 Include the @code{select} builtin, which allows the generation of simple
6738 menus (@pxref{Conditional Constructs}).
6740 @item --enable-usg-echo-default
6741 A synonym for @code{--enable-xpg-echo-default}.
6743 @item --enable-xpg-echo-default
6744 Make the @code{echo} builtin expand backslash-escaped characters by default,
6745 without requiring the @option{-e} option.
6746 This sets the default value of the @code{xpg_echo} shell option to @code{on},
6747 which makes the Bash @code{echo} behave more like the version specified in
6748 the Single Unix Specification, version 2.
6749 @xref{Bash Builtins}, for a description of the escape sequences that
6750 @code{echo} recognizes.
6754 The file @file{config-top.h} contains C Preprocessor
6755 @samp{#define} statements for options which are not settable from
6757 Some of these are not meant to be changed; beware of the consequences if
6759 Read the comments associated with each definition for more
6760 information about its effect.
6762 @node Reporting Bugs
6763 @appendix Reporting Bugs
6765 Please report all bugs you find in Bash.
6766 But first, you should
6767 make sure that it really is a bug, and that it appears in the latest
6769 The latest version of Bash is always available for FTP from
6770 @uref{ftp://ftp.gnu.org/pub/bash/}.
6772 Once you have determined that a bug actually exists, use the
6773 @code{bashbug} command to submit a bug report.
6774 If you have a fix, you are encouraged to mail that as well!
6775 Suggestions and `philosophical' bug reports may be mailed
6776 to @email{bug-bash@@gnu.org} or posted to the Usenet
6777 newsgroup @code{gnu.bash.bug}.
6779 All bug reports should include:
6782 The version number of Bash.
6784 The hardware and operating system.
6786 The compiler used to compile Bash.
6788 A description of the bug behaviour.
6790 A short script or `recipe' which exercises the bug and may be used
6795 @code{bashbug} inserts the first three items automatically into
6796 the template it provides for filing a bug report.
6798 Please send all reports concerning this manual to
6799 @email{chet@@po.CWRU.Edu}.
6801 @node Major Differences From The Bourne Shell
6802 @appendix Major Differences From The Bourne Shell
6804 Bash implements essentially the same grammar, parameter and
6805 variable expansion, redirection, and quoting as the Bourne Shell.
6806 Bash uses the @sc{posix} 1003.2 standard as the specification of
6807 how these features are to be implemented. There are some
6808 differences between the traditional Bourne shell and Bash; this
6809 section quickly details the differences of significance. A
6810 number of these differences are explained in greater depth in
6812 This section uses the version of @code{sh} included in SVR4.2 as
6813 the baseline reference.
6818 Bash is @sc{posix}-conformant, even where the @sc{posix} specification
6819 differs from traditional @code{sh} behavior (@pxref{Bash POSIX Mode}).
6822 Bash has multi-character invocation options (@pxref{Invoking Bash}).
6825 Bash has command-line editing (@pxref{Command Line Editing}) and
6826 the @code{bind} builtin.
6829 Bash provides a programmable word completion mechanism
6830 (@pxref{Programmable Completion}), and two builtin commands,
6831 @code{complete} and @code{compgen}, to manipulate it.
6834 Bash has command history (@pxref{Bash History Facilities}) and the
6835 @code{history} and @code{fc} builtins to manipulate it.
6836 The Bash history list maintains timestamp information and uses the
6837 value of the @code{HISTTIMEFORMAT} variable to display it.
6840 Bash implements @code{csh}-like history expansion
6841 (@pxref{History Interaction}).
6844 Bash has one-dimensional array variables (@pxref{Arrays}), and the
6845 appropriate variable expansions and assignment syntax to use them.
6846 Several of the Bash builtins take options to act on arrays.
6847 Bash provides a number of built-in array variables.
6850 The @code{$'@dots{}'} quoting syntax, which expands ANSI-C
6851 backslash-escaped characters in the text between the single quotes,
6852 is supported (@pxref{ANSI-C Quoting}).
6855 Bash supports the @code{$"@dots{}"} quoting syntax to do
6856 locale-specific translation of the characters between the double
6857 quotes. The @option{-D}, @option{--dump-strings}, and @option{--dump-po-strings}
6858 invocation options list the translatable strings found in a script
6859 (@pxref{Locale Translation}).
6862 Bash implements the @code{!} keyword to negate the return value of
6863 a pipeline (@pxref{Pipelines}).
6864 Very useful when an @code{if} statement needs to act only if a test fails.
6867 Bash has the @code{time} reserved word and command timing (@pxref{Pipelines}).
6868 The display of the timing statistics may be controlled with the
6869 @env{TIMEFORMAT} variable.
6872 Bash implements the @code{for (( @var{expr1} ; @var{expr2} ; @var{expr3} ))}
6873 arithmetic for command, similar to the C language (@pxref{Looping Constructs}).
6876 Bash includes the @code{select} compound command, which allows the
6877 generation of simple menus (@pxref{Conditional Constructs}).
6880 Bash includes the @code{[[} compound command, which makes conditional
6881 testing part of the shell grammar (@pxref{Conditional Constructs}).
6884 Bash includes brace expansion (@pxref{Brace Expansion}) and tilde
6885 expansion (@pxref{Tilde Expansion}).
6888 Bash implements command aliases and the @code{alias} and @code{unalias}
6889 builtins (@pxref{Aliases}).
6892 Bash provides shell arithmetic, the @code{((} compound command
6893 (@pxref{Conditional Constructs}),
6894 and arithmetic expansion (@pxref{Shell Arithmetic}).
6897 Variables present in the shell's initial environment are automatically
6898 exported to child processes. The Bourne shell does not normally do
6899 this unless the variables are explicitly marked using the @code{export}
6903 Bash includes the @sc{posix} pattern removal @samp{%}, @samp{#}, @samp{%%}
6904 and @samp{##} expansions to remove leading or trailing substrings from
6905 variable values (@pxref{Shell Parameter Expansion}).
6908 The expansion @code{$@{#xx@}}, which returns the length of @code{$@{xx@}},
6909 is supported (@pxref{Shell Parameter Expansion}).
6912 The expansion @code{$@{var:}@var{offset}@code{[:}@var{length}@code{]@}},
6913 which expands to the substring of @code{var}'s value of length
6914 @var{length}, beginning at @var{offset}, is present
6915 (@pxref{Shell Parameter Expansion}).
6919 @code{$@{var/[/]}@var{pattern}@code{[/}@var{replacement}@code{]@}},
6920 which matches @var{pattern} and replaces it with @var{replacement} in
6921 the value of @code{var}, is available (@pxref{Shell Parameter Expansion}).
6924 The expansion @code{$@{!@var{prefix@}*}} expansion, which expands to
6925 the names of all shell variables whose names begin with @var{prefix},
6926 is available (@pxref{Shell Parameter Expansion}).
6929 Bash has @var{indirect} variable expansion using @code{$@{!word@}}
6930 (@pxref{Shell Parameter Expansion}).
6933 Bash can expand positional parameters beyond @code{$9} using
6934 @code{$@{@var{num}@}}.
6937 The @sc{posix} @code{$()} form of command substitution
6938 is implemented (@pxref{Command Substitution}),
6939 and preferred to the Bourne shell's @code{``} (which
6940 is also implemented for backwards compatibility).
6943 Bash has process substitution (@pxref{Process Substitution}).
6946 Bash automatically assigns variables that provide information about the
6947 current user (@env{UID}, @env{EUID}, and @env{GROUPS}), the current host
6948 (@env{HOSTTYPE}, @env{OSTYPE}, @env{MACHTYPE}, and @env{HOSTNAME}),
6949 and the instance of Bash that is running (@env{BASH},
6950 @env{BASH_VERSION}, and @env{BASH_VERSINFO}). @xref{Bash Variables},
6954 The @env{IFS} variable is used to split only the results of expansion,
6955 not all words (@pxref{Word Splitting}).
6956 This closes a longstanding shell security hole.
6959 Bash implements the full set of @sc{posix} 1003.2 filename expansion operators,
6960 including @var{character classes}, @var{equivalence classes}, and
6961 @var{collating symbols} (@pxref{Filename Expansion}).
6964 Bash implements extended pattern matching features when the @code{extglob}
6965 shell option is enabled (@pxref{Pattern Matching}).
6968 It is possible to have a variable and a function with the same name;
6969 @code{sh} does not separate the two name spaces.
6972 Bash functions are permitted to have local variables using the
6973 @code{local} builtin, and thus useful recursive functions may be written
6974 (@pxref{Bash Builtins}).
6977 Variable assignments preceding commands affect only that command, even
6978 builtins and functions (@pxref{Environment}).
6979 In @code{sh}, all variable assignments
6980 preceding commands are global unless the command is executed from the
6984 Bash performs filename expansion on filenames specified as operands
6985 to input and output redirection operators (@pxref{Redirections}).
6988 Bash contains the @samp{<>} redirection operator, allowing a file to be
6989 opened for both reading and writing, and the @samp{&>} redirection
6990 operator, for directing standard output and standard error to the same
6991 file (@pxref{Redirections}).
6994 Bash treats a number of filenames specially when they are
6995 used in redirection operators (@pxref{Redirections}).
6998 Bash can open network connections to arbitrary machines and services
6999 with the redirection operators (@pxref{Redirections}).
7002 The @code{noclobber} option is available to avoid overwriting existing
7003 files with output redirection (@pxref{The Set Builtin}).
7004 The @samp{>|} redirection operator may be used to override @code{noclobber}.
7007 The Bash @code{cd} and @code{pwd} builtins (@pxref{Bourne Shell Builtins})
7008 each take @option{-L} and @option{-P} options to switch between logical and
7012 Bash allows a function to override a builtin with the same name, and provides
7013 access to that builtin's functionality within the function via the
7014 @code{builtin} and @code{command} builtins (@pxref{Bash Builtins}).
7017 The @code{command} builtin allows selective disabling of functions
7018 when command lookup is performed (@pxref{Bash Builtins}).
7021 Individual builtins may be enabled or disabled using the @code{enable}
7022 builtin (@pxref{Bash Builtins}).
7025 The Bash @code{exec} builtin takes additional options that allow users
7026 to control the contents of the environment passed to the executed
7027 command, and what the zeroth argument to the command is to be
7028 (@pxref{Bourne Shell Builtins}).
7031 Shell functions may be exported to children via the environment
7032 using @code{export -f} (@pxref{Shell Functions}).
7035 The Bash @code{export}, @code{readonly}, and @code{declare} builtins can
7036 take a @option{-f} option to act on shell functions, a @option{-p} option to
7037 display variables with various attributes set in a format that can be
7038 used as shell input, a @option{-n} option to remove various variable
7039 attributes, and @samp{name=value} arguments to set variable attributes
7040 and values simultaneously.
7043 The Bash @code{hash} builtin allows a name to be associated with
7044 an arbitrary filename, even when that filename cannot be found by
7045 searching the @env{$PATH}, using @samp{hash -p}
7046 (@pxref{Bourne Shell Builtins}).
7049 Bash includes a @code{help} builtin for quick reference to shell
7050 facilities (@pxref{Bash Builtins}).
7053 The @code{printf} builtin is available to display formatted output
7054 (@pxref{Bash Builtins}).
7057 The Bash @code{read} builtin (@pxref{Bash Builtins})
7058 will read a line ending in @samp{\} with
7059 the @option{-r} option, and will use the @env{REPLY} variable as a
7060 default if no non-option arguments are supplied.
7061 The Bash @code{read} builtin
7062 also accepts a prompt string with the @option{-p} option and will use
7063 Readline to obtain the line when given the @option{-e} option.
7064 The @code{read} builtin also has additional options to control input:
7065 the @option{-s} option will turn off echoing of input characters as
7066 they are read, the @option{-t} option will allow @code{read} to time out
7067 if input does not arrive within a specified number of seconds, the
7068 @option{-n} option will allow reading only a specified number of
7069 characters rather than a full line, and the @option{-d} option will read
7070 until a particular character rather than newline.
7073 The @code{return} builtin may be used to abort execution of scripts
7074 executed with the @code{.} or @code{source} builtins
7075 (@pxref{Bourne Shell Builtins}).
7078 Bash includes the @code{shopt} builtin, for finer control of shell
7079 optional capabilities (@pxref{Bash Builtins}), and allows these options
7080 to be set and unset at shell invocation (@pxref{Invoking Bash}).
7083 Bash has much more optional behavior controllable with the @code{set}
7084 builtin (@pxref{The Set Builtin}).
7087 The @samp{-x} (@code{xtrace}) option displays commands other than
7088 simple commands when performing an execution trace
7089 (@pxref{The Set Builtin}).
7092 The @code{test} builtin (@pxref{Bourne Shell Builtins})
7093 is slightly different, as it implements the @sc{posix} algorithm,
7094 which specifies the behavior based on the number of arguments.
7097 Bash includes the @code{caller} builtin, which displays the context of
7098 any active subroutine call (a shell function or a script executed with
7099 the @code{.} or @code{source} builtins). This supports the bash
7103 The @code{trap} builtin (@pxref{Bourne Shell Builtins}) allows a
7104 @code{DEBUG} pseudo-signal specification, similar to @code{EXIT}.
7105 Commands specified with a @code{DEBUG} trap are executed before every
7106 simple command, @code{for} command, @code{case} command,
7107 @code{select} command, every arithmetic @code{for} command, and before
7108 the first command executes in a shell function.
7109 The @code{DEBUG} trap is not inherited by shell functions unless the
7110 function has been given the @code{trace} attribute or the
7111 @code{functrace} option has been enabled using the @code{shopt} builtin.
7112 The @code{extdebug} shell option has additional effects on the
7115 The @code{trap} builtin (@pxref{Bourne Shell Builtins}) allows an
7116 @code{ERR} pseudo-signal specification, similar to @code{EXIT} and @code{DEBUG}.
7117 Commands specified with an @code{ERR} trap are executed after a simple
7118 command fails, with a few exceptions.
7119 The @code{ERR} trap is not inherited by shell functions unless the
7120 @code{-o errtrace} option to the @code{set} builtin is enabled.
7122 The @code{trap} builtin (@pxref{Bourne Shell Builtins}) allows a
7123 @code{RETURN} pseudo-signal specification, similar to
7124 @code{EXIT} and @code{DEBUG}.
7125 Commands specified with an @code{RETURN} trap are executed before
7126 execution resumes after a shell function or a shell script executed with
7127 @code{.} or @code{source} returns.
7128 The @code{RETURN} trap is not inherited by shell functions.
7131 The Bash @code{type} builtin is more extensive and gives more information
7132 about the names it finds (@pxref{Bash Builtins}).
7135 The Bash @code{umask} builtin permits a @option{-p} option to cause
7136 the output to be displayed in the form of a @code{umask} command
7137 that may be reused as input (@pxref{Bourne Shell Builtins}).
7140 Bash implements a @code{csh}-like directory stack, and provides the
7141 @code{pushd}, @code{popd}, and @code{dirs} builtins to manipulate it
7142 (@pxref{The Directory Stack}).
7143 Bash also makes the directory stack visible as the value of the
7144 @env{DIRSTACK} shell variable.
7147 Bash interprets special backslash-escaped characters in the prompt
7148 strings when interactive (@pxref{Printing a Prompt}).
7151 The Bash restricted mode is more useful (@pxref{The Restricted Shell});
7152 the SVR4.2 shell restricted mode is too limited.
7155 The @code{disown} builtin can remove a job from the internal shell
7156 job table (@pxref{Job Control Builtins}) or suppress the sending
7157 of @code{SIGHUP} to a job when the shell exits as the result of a
7161 The SVR4.2 shell has two privilege-related builtins
7162 (@code{mldmode} and @code{priv}) not present in Bash.
7165 Bash does not have the @code{stop} or @code{newgrp} builtins.
7168 Bash does not use the @env{SHACCT} variable or perform shell accounting.
7171 The SVR4.2 @code{sh} uses a @env{TIMEOUT} variable like Bash uses
7177 More features unique to Bash may be found in @ref{Bash Features}.
7180 @appendixsec Implementation Differences From The SVR4.2 Shell
7182 Since Bash is a completely new implementation, it does not suffer from
7183 many of the limitations of the SVR4.2 shell. For instance:
7188 Bash does not fork a subshell when redirecting into or out of
7189 a shell control structure such as an @code{if} or @code{while}
7193 Bash does not allow unbalanced quotes. The SVR4.2 shell will silently
7194 insert a needed closing quote at @code{EOF} under certain circumstances.
7195 This can be the cause of some hard-to-find errors.
7198 The SVR4.2 shell uses a baroque memory management scheme based on
7199 trapping @code{SIGSEGV}. If the shell is started from a process with
7200 @code{SIGSEGV} blocked (e.g., by using the @code{system()} C library
7201 function call), it misbehaves badly.
7204 In a questionable attempt at security, the SVR4.2 shell,
7205 when invoked without the @option{-p} option, will alter its real
7206 and effective @sc{uid} and @sc{gid} if they are less than some
7207 magic threshold value, commonly 100.
7208 This can lead to unexpected results.
7211 The SVR4.2 shell does not allow users to trap @code{SIGSEGV},
7212 @code{SIGALRM}, or @code{SIGCHLD}.
7215 The SVR4.2 shell does not allow the @env{IFS}, @env{MAILCHECK},
7216 @env{PATH}, @env{PS1}, or @env{PS2} variables to be unset.
7219 The SVR4.2 shell treats @samp{^} as the undocumented equivalent of
7223 Bash allows multiple option arguments when it is invoked (@code{-x -v});
7224 the SVR4.2 shell allows only one option argument (@code{-xv}). In
7225 fact, some versions of the shell dump core if the second argument begins
7229 The SVR4.2 shell exits a script if any builtin fails; Bash exits
7230 a script only if one of the @sc{posix} 1003.2 special builtins fails, and
7231 only for certain failures, as enumerated in the @sc{posix} 1003.2 standard.
7234 The SVR4.2 shell behaves differently when invoked as @code{jsh}
7235 (it turns on job control).
7238 @node Copying This Manual
7239 @appendix Copying This Manual
7242 * GNU Free Documentation License:: License for copying this manual.
7248 @unnumbered Index of Shell Builtin Commands
7251 @node Reserved Word Index
7252 @unnumbered Index of Shell Reserved Words
7255 @node Variable Index
7256 @unnumbered Parameter and Variable Index
7259 @node Function Index
7260 @unnumbered Function Index
7264 @unnumbered Concept Index