1 \input texinfo.tex @c -*- texinfo -*-
3 @setfilename bashref.info
4 @settitle Bash Reference Manual
8 Last Change: Mon Jul 15 15:21:16 EDT 2002
13 @set UPDATED 15 July 2002
14 @set UPDATE-MONTH July 2002
20 @setchapternewpage odd
26 @dircategory Utilities
28 * Bash: (bash). The GNU Bourne-Again SHell.
32 This text is a brief description of the features that are present in
35 This is Edition @value{EDITION}, last updated @value{UPDATED},
36 of @cite{The GNU Bash Reference Manual},
37 for @code{Bash}, Version @value{VERSION}.
39 Copyright (C) 1991-2002 Free Software Foundation, Inc.
41 Permission is granted to make and distribute verbatim copies of
42 this manual provided the copyright notice and this permission notice
43 are preserved on all copies.
46 Permission is granted to process this file through TeX and print the
47 results, provided the printed document carries copying permission
48 notice identical to this one except for the removal of this paragraph
49 (this paragraph not being relevant to the printed manual).
52 Permission is granted to copy and distribute modified versions of this
53 manual under the conditions for verbatim copying, provided that the entire
54 resulting derived work is distributed under the terms of a permission
55 notice identical to this one.
57 Permission is granted to copy and distribute translations of this manual
58 into another language, under the above conditions for modified versions,
59 except that this permission notice may be stated in a translation approved
60 by the Free Software Foundation.
65 @title Bash Reference Manual
66 @subtitle Reference Documentation for Bash
67 @subtitle Edition @value{EDITION}, for @code{Bash} Version @value{VERSION}.
68 @subtitle @value{UPDATE-MONTH}
69 @author Chet Ramey, Case Western Reserve University
70 @author Brian Fox, Free Software Foundation
72 @vskip 0pt plus 1filll
73 Copyright @copyright{} 1991-2002 Free Software Foundation, Inc.
75 Permission is granted to make and distribute verbatim copies of
76 this manual provided the copyright notice and this permission notice
77 are preserved on all copies.
79 Permission is granted to copy and distribute modified versions of this
80 manual under the conditions for verbatim copying, provided that the entire
81 resulting derived work is distributed under the terms of a permission
82 notice identical to this one.
84 Permission is granted to copy and distribute translations of this manual
85 into another language, under the above conditions for modified versions,
86 except that this permission notice may be stated in a translation approved
87 by the Free Software Foundation.
91 @node Top, Introduction, (dir), (dir)
96 This text is a brief description of the features that are present in
99 This is Edition @value{EDITION}, last updated @value{UPDATED},
100 of @cite{The GNU Bash Reference Manual},
101 for @code{Bash}, Version @value{VERSION}.
103 Copyright (C) 1991-2002 Free Software Foundation, Inc.
105 Bash contains features that appear in other popular shells, and some
106 features that only appear in Bash. Some of the shells that Bash has
107 borrowed concepts from are the Bourne Shell (@file{sh}), the Korn Shell
108 (@file{ksh}), and the C-shell (@file{csh} and its successor,
109 @file{tcsh}). The following menu breaks the features up into
110 categories based upon which one of these other shells inspired the
113 This manual is meant as a brief introduction to features found in
114 Bash. The Bash manual page should be used as the definitive
115 reference on shell behavior.
118 * Introduction:: An introduction to the shell.
120 * Definitions:: Some definitions used in the rest of this
123 * Basic Shell Features:: The shell "building blocks".
125 * Shell Builtin Commands:: Commands that are a part of the shell.
127 * Shell Variables:: Variables used or set by Bash.
129 * Bash Features:: Features found only in Bash.
131 * Job Control:: A chapter describing what job control is
132 and how Bash allows you to use it.
134 * Using History Interactively:: Chapter dealing with history expansion
137 * Command Line Editing:: Chapter describing the command line
140 * Installing Bash:: How to build and install Bash on your system.
142 * Reporting Bugs:: How to report bugs in Bash.
144 * Major Differences From The Bourne Shell:: A terse list of the differences
145 between Bash and historical
148 * Builtin Index:: Index of Bash builtin commands.
150 * Reserved Word Index:: Index of Bash reserved words.
152 * Variable Index:: Quick reference helps you find the
155 * Function Index:: Index of bindable Readline functions.
157 * Concept Index:: General index for concepts described in
163 @chapter Introduction
165 * What is Bash?:: A short description of Bash.
167 * What is a shell?:: A brief introduction to shells.
171 @section What is Bash?
173 Bash is the shell, or command language interpreter,
174 for the @sc{gnu} operating system.
175 The name is an acronym for the @samp{Bourne-Again SHell},
176 a pun on Stephen Bourne, the author of the direct ancestor of
177 the current Unix shell @code{/bin/sh},
178 which appeared in the Seventh Edition Bell Labs Research version
181 Bash is largely compatible with @code{sh} and incorporates useful
182 features from the Korn shell @code{ksh} and the C shell @code{csh}.
183 It is intended to be a conformant implementation of the @sc{ieee}
184 @sc{posix} Shell and Tools specification (@sc{ieee} Working Group 1003.2).
185 It offers functional improvements over @code{sh} for both interactive and
188 While the @sc{gnu} operating system provides other shells, including
189 a version of @code{csh}, Bash is the default shell.
190 Like other @sc{gnu} software, Bash is quite portable. It currently runs
191 on nearly every version of Unix and a few other operating systems @minus{}
192 independently-supported ports exist for @sc{ms-dos}, @sc{os/2},
193 Windows @sc{95/98}, and Windows @sc{nt}.
195 @node What is a shell?
196 @section What is a shell?
198 At its base, a shell is simply a macro processor that executes
199 commands. A Unix shell is both a command interpreter, which
200 provides the user interface to the rich set of @sc{gnu} utilities,
201 and a programming language, allowing these utilitites to be
202 combined. Files containing commands can be created, and become
203 commands themselves. These new commands have the same status as
204 system commands in directories such as @file{/bin}, allowing users
205 or groups to establish custom environments.
207 A shell allows execution of @sc{gnu} commands, both synchronously and
209 The shell waits for synchronous commands to complete before accepting
210 more input; asynchronous commands continue to execute in parallel
211 with the shell while it reads and executes additional commands.
212 The @dfn{redirection} constructs permit
213 fine-grained control of the input and output of those commands.
214 Moreover, the shell allows control over the contents of commands'
216 Shells may be used interactively or non-interactively: they accept
217 input typed from the keyboard or from a file.
219 Shells also provide a small set of built-in
220 commands (@dfn{builtins}) implementing functionality impossible
221 or inconvenient to obtain via separate utilities.
222 For example, @code{cd}, @code{break}, @code{continue}, and
223 @code{exec}) cannot be implemented outside of the shell because
224 they directly manipulate the shell itself.
225 The @code{history}, @code{getopts}, @code{kill}, or @code{pwd}
226 builtins, among others, could be implemented in separate utilities,
227 but they are more convenient to use as builtin commands.
228 All of the shell builtins are described in
231 While executing commands is essential, most of the power (and
232 complexity) of shells is due to their embedded programming
233 languages. Like any high-level language, the shell provides
234 variables, flow control constructs, quoting, and functions.
236 Shells offer features geared specifically for
237 interactive use rather than to augment the programming language.
238 These interactive features include job control, command line
239 editing, history and aliases. Each of these features is
240 described in this manual.
244 These definitions are used throughout the remainder of this manual.
250 A family of open system standards based on Unix. Bash
251 is concerned with @sc{posix} 1003.2, the Shell and Tools Standard.
254 A space or tab character.
258 A command that is implemented internally by the shell itself, rather
259 than by an executable program somewhere in the file system.
261 @item control operator
262 @cindex control operator
263 A @code{word} that performs a control function. It is a @code{newline}
264 or one of the following:
265 @samp{||}, @samp{&&}, @samp{&}, @samp{;}, @samp{;;},
266 @samp{|}, @samp{(}, or @samp{)}.
270 The value returned by a command to its caller. The value is restricted
271 to eight bits, so the maximum value is 255.
275 A unit of text that is the result of one of the shell expansions. After
276 expansion, when executing a command, the resulting fields are used as
277 the command name and arguments.
281 A string of characters used to identify a file.
285 A set of processes comprising a pipeline, and any processes descended
286 from it, that are all in the same process group.
290 A mechanism by which users can selectively stop (suspend) and restart
291 (resume) execution of processes.
294 @cindex metacharacter
295 A character that, when unquoted, separates words. A metacharacter is
296 a @code{blank} or one of the following characters:
297 @samp{|}, @samp{&}, @samp{;}, @samp{(}, @samp{)}, @samp{<}, or
303 A @code{word} consisting solely of letters, numbers, and underscores,
304 and beginning with a letter or underscore. @code{Name}s are used as
305 shell variable and function names.
306 Also referred to as an @code{identifier}.
309 @cindex operator, shell
310 A @code{control operator} or a @code{redirection operator}.
311 @xref{Redirections}, for a list of redirection operators.
314 @cindex process group
315 A collection of related processes each having the same process
318 @item process group ID
319 @cindex process group ID
320 A unique identifer that represents a @code{process group}
324 @cindex reserved word
325 A @code{word} that has a special meaning to the shell. Most reserved
326 words introduce shell flow control constructs, such as @code{for} and
330 @cindex return status
331 A synonym for @code{exit status}.
335 A mechanism by which a process may be notified by the kernel
336 of an event occurring in the system.
338 @item special builtin
339 @cindex special builtin
340 A shell builtin command that has been classified as special by the
341 @sc{posix} 1003.2 standard.
345 A sequence of characters considered a single unit by the shell. It is
346 either a @code{word} or an @code{operator}.
350 A @code{token} that is not an @code{operator}.
353 @node Basic Shell Features
354 @chapter Basic Shell Features
357 Bash is an acronym for @samp{Bourne-Again SHell}.
359 the traditional Unix shell originally written by Stephen Bourne.
360 All of the Bourne shell builtin commands are available in Bash,
361 and the rules for evaluation and quoting are taken from the @sc{posix}
362 1003.2 specification for the `standard' Unix shell.
364 This chapter briefly summarizes the shell's `building blocks':
365 commands, control structures, shell functions, shell @i{parameters},
367 @i{redirections}, which are a way to direct input and output from
368 and to named files, and how the shell executes commands.
371 * Shell Syntax:: What your input means to the shell.
372 * Shell Commands:: The types of commands you can use.
373 * Shell Functions:: Grouping commands by name.
374 * Shell Parameters:: Special shell variables.
375 * Shell Expansions:: How Bash expands variables and the various
376 expansions available.
377 * Redirections:: A way to control where input and output go.
378 * Executing Commands:: What happens when you run a command.
379 * Shell Scripts:: Executing files of shell commands.
383 @section Shell Syntax
385 * Shell Operation:: The basic operation of the shell.
387 * Quoting:: How to remove the special meaning from characters.
389 * Comments:: How to specify comments.
392 When the shell reads input, it proceeds through a
393 sequence of operations. If the input indicates the beginning of a
394 comment, the shell ignores the comment symbol (@samp{#}), and the rest
397 Otherwise, roughly speaking, the shell reads its input and
398 divides the input into words and operators, employing the quoting rules
399 to select which meanings to assign various words and characters.
401 The shell then parses these tokens into commands and other constructs,
402 removes the special meaning of certain words or characters, expands
403 others, redirects input and output as needed, executes the specified
404 command, waits for the command's exit status, and makes that exit status
405 available for further inspection or processing.
407 @node Shell Operation
408 @subsection Shell Operation
410 The following is a brief description of the shell's operation when it
411 reads and executes a command. Basically, the shell does the
416 Reads its input from a file (@pxref{Shell Scripts}), from a string
417 supplied as an argument to the @option{-c} invocation option
418 (@pxref{Invoking Bash}), or from the user's terminal.
421 Breaks the input into words and operators, obeying the quoting rules
422 described in @ref{Quoting}. These tokens are separated by
423 @code{metacharacters}. Alias expansion is performed by this step
427 Parses the tokens into simple and compound commands
428 (@pxref{Shell Commands}).
431 Performs the various shell expansions (@pxref{Shell Expansions}), breaking
432 the expanded tokens into lists of filenames (@pxref{Filename Expansion})
433 and commands and arguments.
436 Performs any necessary redirections (@pxref{Redirections}) and removes
437 the redirection operators and their operands from the argument list.
440 Executes the command (@pxref{Executing Commands}).
443 Optionally waits for the command to complete and collects its exit
444 status (@pxref{Exit Status}).
452 * Escape Character:: How to remove the special meaning from a single
454 * Single Quotes:: How to inhibit all interpretation of a sequence
456 * Double Quotes:: How to suppress most of the interpretation of a
457 sequence of characters.
458 * ANSI-C Quoting:: How to expand ANSI-C sequences in quoted strings.
460 * Locale Translation:: How to translate strings into different languages.
463 Quoting is used to remove the special meaning of certain
464 characters or words to the shell. Quoting can be used to
465 disable special treatment for special characters, to prevent
466 reserved words from being recognized as such, and to prevent
469 Each of the shell metacharacters (@pxref{Definitions})
470 has special meaning to the shell and must be quoted if it is to
472 When the command history expansion facilities are being used, the
473 @var{history expansion} character, usually @samp{!}, must be quoted
474 to prevent history expansion. @xref{Bash History Facilities}, for
475 more details concerning history expansion.
476 There are three quoting mechanisms: the
477 @var{escape character}, single quotes, and double quotes.
479 @node Escape Character
480 @subsubsection Escape Character
481 A non-quoted backslash @samp{\} is the Bash escape character.
482 It preserves the literal value of the next character that follows,
483 with the exception of @code{newline}. If a @code{\newline} pair
484 appears, and the backslash itself is not quoted, the @code{\newline}
485 is treated as a line continuation (that is, it is removed from
486 the input stream and effectively ignored).
489 @subsubsection Single Quotes
491 Enclosing characters in single quotes (@samp{'}) preserves the literal value
492 of each character within the quotes. A single quote may not occur
493 between single quotes, even when preceded by a backslash.
496 @subsubsection Double Quotes
498 Enclosing characters in double quotes (@samp{"}) preserves the literal value
499 of all characters within the quotes, with the exception of
500 @samp{$}, @samp{`}, and @samp{\}.
501 The characters @samp{$} and @samp{`}
502 retain their special meaning within double quotes (@pxref{Shell Expansions}).
503 The backslash retains its special meaning only when followed by one of
504 the following characters:
505 @samp{$}, @samp{`}, @samp{"}, @samp{\}, or @code{newline}.
506 Within double quotes, backslashes that are followed by one of these
507 characters are removed. Backslashes preceding characters without a
508 special meaning are left unmodified.
509 A double quote may be quoted within double quotes by preceding it with
512 The special parameters @samp{*} and @samp{@@} have special meaning
513 when in double quotes (@pxref{Shell Parameter Expansion}).
516 @subsubsection ANSI-C Quoting
517 @cindex quoting, ANSI
519 Words of the form @code{$'@var{string}'} are treated specially. The
520 word expands to @var{string}, with backslash-escaped characters replaced
521 as specified by the ANSI C standard. Backslash escape sequences, if
522 present, are decoded as follows:
530 an escape character (not ANSI C)
546 the eight-bit character whose value is the octal value @var{nnn}
547 (one to three digits)
549 the eight-bit character whose value is the hexadecimal value @var{HH}
550 (one or two hex digits)
552 a control-@var{x} character
556 The expanded result is single-quoted, as if the dollar sign had not
559 @node Locale Translation
560 @subsubsection Locale-Specific Translation
562 @cindex internationalization
563 @cindex native languages
564 @cindex translation, native languages
566 A double-quoted string preceded by a dollar sign (@samp{$}) will cause
567 the string to be translated according to the current locale.
568 If the current locale is @code{C} or @code{POSIX}, the dollar sign
570 If the string is translated and replaced, the replacement is
575 @vindex TEXTDOMAINDIR
576 Some systems use the message catalog selected by the @env{LC_MESSAGES}
577 shell variable. Others create the name of the message catalog from the
578 value of the @env{TEXTDOMAIN} shell variable, possibly adding a
579 suffix of @samp{.mo}. If you use the @env{TEXTDOMAIN} variable, you
580 may need to set the @env{TEXTDOMAINDIR} variable to the location of
581 the message catalog files. Still others use both variables in this
583 @env{TEXTDOMAINDIR}/@env{LC_MESSAGES}/LC_MESSAGES/@env{TEXTDOMAIN}.mo.
587 @cindex comments, shell
589 In a non-interactive shell, or an interactive shell in which the
590 @code{interactive_comments} option to the @code{shopt}
591 builtin is enabled (@pxref{Bash Builtins}),
592 a word beginning with @samp{#}
593 causes that word and all remaining characters on that line to
594 be ignored. An interactive shell without the @code{interactive_comments}
595 option enabled does not allow comments. The @code{interactive_comments}
596 option is on by default in interactive shells.
597 @xref{Interactive Shells}, for a description of what makes
601 @section Shell Commands
602 @cindex commands, shell
604 A simple shell command such as @code{echo a b c} consists of the command
605 itself followed by arguments, separated by spaces.
607 More complex shell commands are composed of simple commands arranged together
608 in a variety of ways: in a pipeline in which the output of one command
609 becomes the input of a second, in a loop or conditional construct, or in
613 * Simple Commands:: The most common type of command.
614 * Pipelines:: Connecting the input and output of several
616 * Lists:: How to execute commands sequentially.
617 * Looping Constructs:: Shell commands for iterative action.
618 * Conditional Constructs:: Shell commands for conditional execution.
619 * Command Grouping:: Ways to group commands.
622 @node Simple Commands
623 @subsection Simple Commands
624 @cindex commands, simple
626 A simple command is the kind of command encountered most often.
627 It's just a sequence of words separated by @code{blank}s, terminated
628 by one of the shell's control operators (@pxref{Definitions}). The
629 first word generally specifies a command to be executed, with the
630 rest of the words being that command's arguments.
632 The return status (@pxref{Exit Status}) of a simple command is
633 its exit status as provided
634 by the @sc{posix} 1003.1 @code{waitpid} function, or 128+@var{n} if
635 the command was terminated by signal @var{n}.
638 @subsection Pipelines
640 @cindex commands, pipelines
642 A @code{pipeline} is a sequence of simple commands separated by
647 @cindex command timing
648 The format for a pipeline is
650 [@code{time} [@code{-p}]] [@code{!}] @var{command1} [@code{|} @var{command2} @dots{}]
654 The output of each command in the pipeline is connected via a pipe
655 to the input of the next command.
656 That is, each command reads the previous command's output.
658 The reserved word @code{time} causes timing statistics
659 to be printed for the pipeline once it finishes.
660 The statistics currently consist of elapsed (wall-clock) time and
661 user and system time consumed by the command's execution.
662 The @option{-p} option changes the output format to that specified
664 The @env{TIMEFORMAT} variable may be set to a format string that
665 specifies how the timing information should be displayed.
666 @xref{Bash Variables}, for a description of the available formats.
667 The use of @code{time} as a reserved word permits the timing of
668 shell builtins, shell functions, and pipelines. An external
669 @code{time} command cannot time these easily.
671 If the pipeline is not executed asynchronously (@pxref{Lists}), the
672 shell waits for all commands in the pipeline to complete.
674 Each command in a pipeline is executed in its own subshell
675 (@pxref{Command Execution Environment}). The exit
676 status of a pipeline is the exit status of the last command in the
677 pipeline. If the reserved word @samp{!} precedes the pipeline, the
678 exit status is the logical negation of the exit status of the last command.
681 @subsection Lists of Commands
682 @cindex commands, lists
684 A @code{list} is a sequence of one or more pipelines separated by one
685 of the operators @samp{;}, @samp{&}, @samp{&&}, or @samp{||},
686 and optionally terminated by one of @samp{;}, @samp{&}, or a
689 Of these list operators, @samp{&&} and @samp{||}
690 have equal precedence, followed by @samp{;} and @samp{&},
691 which have equal precedence.
693 A sequence of one or more newlines may appear in a @code{list}
694 to delimit commands, equivalent to a semicolon.
696 If a command is terminated by the control operator @samp{&},
697 the shell executes the command asynchronously in a subshell.
698 This is known as executing the command in the @var{background}.
699 The shell does not wait for the command to finish, and the return
701 When job control is not active (@pxref{Job Control}),
702 the standard input for asynchronous commands, in the absence of any
703 explicit redirections, is redirected from @code{/dev/null}.
705 Commands separated by a @samp{;} are executed sequentially; the shell
706 waits for each command to terminate in turn. The return status is the
707 exit status of the last command executed.
709 The control operators @samp{&&} and @samp{||}
710 denote @sc{and} lists and @sc{or} lists, respectively.
711 An @sc{and} list has the form
713 @var{command1} && @var{command2}
717 @var{command2} is executed if, and only if, @var{command1}
718 returns an exit status of zero.
720 An @sc{or} list has the form
722 @var{command1} || @var{command2}
726 @var{command2} is executed if, and only if, @var{command1}
727 returns a non-zero exit status.
730 @sc{and} and @sc{or} lists is the exit status of the last command
731 executed in the list.
733 @node Looping Constructs
734 @subsection Looping Constructs
735 @cindex commands, looping
737 Bash supports the following looping constructs.
739 Note that wherever a @samp{;} appears in the description of a
740 command's syntax, it may be replaced with one or more newlines.
747 The syntax of the @code{until} command is:
749 until @var{test-commands}; do @var{consequent-commands}; done
751 Execute @var{consequent-commands} as long as
752 @var{test-commands} has an exit status which is not zero.
753 The return status is the exit status of the last command executed
754 in @var{consequent-commands}, or zero if none was executed.
758 The syntax of the @code{while} command is:
760 while @var{test-commands}; do @var{consequent-commands}; done
763 Execute @var{consequent-commands} as long as
764 @var{test-commands} has an exit status of zero.
765 The return status is the exit status of the last command executed
766 in @var{consequent-commands}, or zero if none was executed.
770 The syntax of the @code{for} command is:
773 for @var{name} [in @var{words} @dots{}]; do @var{commands}; done
775 Expand @var{words}, and execute @var{commands} once for each member
776 in the resultant list, with @var{name} bound to the current member.
777 If @samp{in @var{words}} is not present, the @code{for} command
778 executes the @var{commands} once for each positional parameter that is
779 set, as if @samp{in "$@@"} had been specified
780 (@pxref{Special Parameters}).
781 The return status is the exit status of the last command that executes.
782 If there are no items in the expansion of @var{words}, no commands are
783 executed, and the return status is zero.
785 An alternate form of the @code{for} command is also supported:
788 for (( @var{expr1} ; @var{expr2} ; @var{expr3} )) ; do @var{commands} ; done
790 First, the arithmetic expression @var{expr1} is evaluated according
791 to the rules described below (@pxref{Shell Arithmetic}).
792 The arithmetic expression @var{expr2} is then evaluated repeatedly
793 until it evaluates to zero.
794 Each time @var{expr2} evaluates to a non-zero value, @var{commands} are
795 executed and the arithmetic expression @var{expr3} is evaluated.
796 If any expression is omitted, it behaves as if it evaluates to 1.
797 The return value is the exit status of the last command in @var{list}
798 that is executed, or false if any of the expressions is invalid.
802 The @code{break} and @code{continue} builtins (@pxref{Bourne Shell Builtins})
803 may be used to control loop execution.
805 @node Conditional Constructs
806 @subsection Conditional Constructs
807 @cindex commands, conditional
816 The syntax of the @code{if} command is:
819 if @var{test-commands}; then
820 @var{consequent-commands};
821 [elif @var{more-test-commands}; then
822 @var{more-consequents};]
823 [else @var{alternate-consequents};]
827 The @var{test-commands} list is executed, and if its return status is zero,
828 the @var{consequent-commands} list is executed.
829 If @var{test-commands} returns a non-zero status, each @code{elif} list
830 is executed in turn, and if its exit status is zero,
831 the corresponding @var{more-consequents} is executed and the
833 If @samp{else @var{alternate-consequents}} is present, and
834 the final command in the final @code{if} or @code{elif} clause
835 has a non-zero exit status, then @var{alternate-consequents} is executed.
836 The return status is the exit status of the last command executed, or
837 zero if no condition tested true.
843 The syntax of the @code{case} command is:
846 @code{case @var{word} in [ [(] @var{pattern} [| @var{pattern}]@dots{}) @var{command-list} ;;]@dots{} esac}
849 @code{case} will selectively execute the @var{command-list} corresponding to
850 the first @var{pattern} that matches @var{word}.
851 The @samp{|} is used to separate multiple patterns, and the @samp{)}
852 operator terminates a pattern list.
853 A list of patterns and an associated command-list is known
854 as a @var{clause}. Each clause must be terminated with @samp{;;}.
855 The @var{word} undergoes tilde expansion, parameter expansion, command
856 substitution, arithmetic expansion, and quote removal before matching is
857 attempted. Each @var{pattern} undergoes tilde expansion, parameter
858 expansion, command substitution, and arithmetic expansion.
860 There may be an arbitrary number of @code{case} clauses, each terminated
861 by a @samp{;;}. The first pattern that matches determines the
862 command-list that is executed.
864 Here is an example using @code{case} in a script that could be used to
865 describe one interesting feature of an animal:
868 echo -n "Enter the name of an animal: "
870 echo -n "The $ANIMAL has "
872 horse | dog | cat) echo -n "four";;
873 man | kangaroo ) echo -n "two";;
874 *) echo -n "an unknown number of";;
880 The return status is zero if no @var{pattern} is matched. Otherwise, the
881 return status is the exit status of the @var{command-list} executed.
886 The @code{select} construct allows the easy generation of menus.
887 It has almost the same syntax as the @code{for} command:
890 select @var{name} [in @var{words} @dots{}]; do @var{commands}; done
893 The list of words following @code{in} is expanded, generating a list
894 of items. The set of expanded words is printed on the standard
895 error output stream, each preceded by a number. If the
896 @samp{in @var{words}} is omitted, the positional parameters are printed,
897 as if @samp{in "$@@"} had been specifed.
898 The @env{PS3} prompt is then displayed and a line is read from the
900 If the line consists of a number corresponding to one of the displayed
901 words, then the value of @var{name} is set to that word.
902 If the line is empty, the words and prompt are displayed again.
903 If @code{EOF} is read, the @code{select} command completes.
904 Any other value read causes @var{name} to be set to null.
905 The line read is saved in the variable @env{REPLY}.
907 The @var{commands} are executed after each selection until a
908 @code{break} command is executed, at which
909 point the @code{select} command completes.
911 Here is an example that allows the user to pick a filename from the
912 current directory, and displays the name and index of the file
918 echo you picked $fname \($REPLY\)
925 (( @var{expression} ))
928 The arithmetic @var{expression} is evaluated according to the rules
929 described below (@pxref{Shell Arithmetic}).
930 If the value of the expression is non-zero, the return status is 0;
931 otherwise the return status is 1. This is exactly equivalent to
933 let "@var{expression}"
936 @xref{Bash Builtins}, for a full description of the @code{let} builtin.
942 [[ @var{expression} ]]
945 Return a status of 0 or 1 depending on the evaluation of
946 the conditional expression @var{expression}.
947 Expressions are composed of the primaries described below in
948 @ref{Bash Conditional Expressions}.
949 Word splitting and filename expansion are not performed on the words
950 between the @samp{[[} and @samp{]]}; tilde expansion, parameter and
951 variable expansion, arithmetic expansion, command substitution, process
952 substitution, and quote removal are performed.
954 When the @samp{==} and @samp{!=} operators are used, the string to the
955 right of the operator is considered a pattern and matched according
956 to the rules described below in @ref{Pattern Matching}.
957 The return value is 0 if the string matches or does not match
958 the pattern, respectively, and 1 otherwise.
959 Any part of the pattern may be quoted to force it to be matched as a
962 Expressions may be combined using the following operators, listed
963 in decreasing order of precedence:
966 @item ( @var{expression} )
967 Returns the value of @var{expression}.
968 This may be used to override the normal precedence of operators.
970 @item ! @var{expression}
971 True if @var{expression} is false.
973 @item @var{expression1} && @var{expression2}
974 True if both @var{expression1} and @var{expression2} are true.
976 @item @var{expression1} || @var{expression2}
977 True if either @var{expression1} or @var{expression2} is true.
980 The @code{&&} and @code{||} operators do not evaluate @var{expression2} if the
981 value of @var{expression1} is sufficient to determine the return
982 value of the entire conditional expression.
986 @node Command Grouping
987 @subsection Grouping Commands
988 @cindex commands, grouping
990 Bash provides two ways to group a list of commands to be executed
991 as a unit. When commands are grouped, redirections may be applied
992 to the entire command list. For example, the output of all the
993 commands in the list may be redirected to a single stream.
1001 Placing a list of commands between parentheses causes a subshell
1002 to be created, and each of the commands in @var{list} to be executed
1003 in that subshell. Since the @var{list} is executed in a subshell,
1004 variable assignments do not remain in effect after the subshell completes.
1013 Placing a list of commands between curly braces causes the list to
1014 be executed in the current shell context. No subshell is created.
1015 The semicolon (or newline) following @var{list} is required.
1018 In addition to the creation of a subshell, there is a subtle difference
1019 between these two constructs due to historical reasons. The braces
1020 are @code{reserved words}, so they must be separated from the @var{list}
1021 by @code{blank}s. The parentheses are @code{operators}, and are
1022 recognized as separate tokens by the shell even if they are not separated
1023 from the @var{list} by whitespace.
1025 The exit status of both of these constructs is the exit status of
1028 @node Shell Functions
1029 @section Shell Functions
1030 @cindex shell function
1031 @cindex functions, shell
1033 Shell functions are a way to group commands for later execution
1034 using a single name for the group. They are executed just like
1035 a "regular" command.
1036 When the name of a shell function is used as a simple command name,
1037 the list of commands associated with that function name is executed.
1038 Shell functions are executed in the current
1039 shell context; no new process is created to interpret them.
1041 Functions are declared using this syntax:
1044 [ @code{function} ] @var{name} () @{ @var{command-list}; @}
1047 This defines a shell function named @var{name}. The reserved
1048 word @code{function} is optional.
1049 If the @code{function} reserved
1050 word is supplied, the parentheses are optional.
1051 The @var{body} of the function is the @var{command-list} between @{ and @}.
1052 This list is executed whenever @var{name} is specified as the
1053 name of a command. The exit status of a function is
1054 the exit status of the last command executed in the body.
1056 Note that for historical reasons, the curly braces that surround
1057 the body of the function must be separated from the body by
1058 @code{blank}s or newlines.
1059 This is because the braces are reserved words and are only recognized
1060 as such when they are separated by whitespace.
1061 Also, the @var{command-list} must be terminated with a semicolon
1064 When a function is executed, the arguments to the
1065 function become the positional parameters
1066 during its execution (@pxref{Positional Parameters}).
1067 The special parameter @samp{#} that expands to the number of
1068 positional parameters is updated to reflect the change.
1069 Positional parameter @code{0} is unchanged.
1070 The @env{FUNCNAME} variable is set to the name of the function
1071 while the function is executing.
1073 If the builtin command @code{return}
1074 is executed in a function, the function completes and
1075 execution resumes with the next command after the function
1076 call. When a function completes, the values of the
1077 positional parameters and the special parameter @samp{#}
1078 are restored to the values they had prior to the function's
1079 execution. If a numeric argument is given to @code{return},
1080 that is the function's return status; otherwise the function's
1081 return status is the exit status of the last command executed
1082 before the @code{return}.
1084 Variables local to the function may be declared with the
1085 @code{local} builtin. These variables are visible only to
1086 the function and the commands it invokes.
1088 Functions may be recursive. No limit is placed on the number of
1091 @node Shell Parameters
1092 @section Shell Parameters
1094 @cindex variable, shell
1095 @cindex shell variable
1098 * Positional Parameters:: The shell's command-line arguments.
1099 * Special Parameters:: Parameters with special meanings.
1102 A @var{parameter} is an entity that stores values.
1103 It can be a @code{name}, a number, or one of the special characters
1105 For the shell's purposes, a @var{variable} is a parameter denoted by a
1107 A variable has a @var{value} and zero or more @var{attributes}.
1108 Attributes are assigned using the @code{declare} builtin command
1109 (see the description of the @code{declare} builtin in @ref{Bash Builtins}).
1111 A parameter is set if it has been assigned a value. The null string is
1112 a valid value. Once a variable is set, it may be unset only by using
1113 the @code{unset} builtin command.
1115 A variable may be assigned to by a statement of the form
1117 @var{name}=[@var{value}]
1121 is not given, the variable is assigned the null string. All
1122 @var{value}s undergo tilde expansion, parameter and variable expansion,
1123 command substitution, arithmetic expansion, and quote
1124 removal (detailed below). If the variable has its @code{integer}
1125 attribute set, then @var{value}
1126 is subject to arithmetic expansion even if the @code{$((@dots{}))}
1127 expansion is not used (@pxref{Arithmetic Expansion}).
1128 Word splitting is not performed, with the exception
1129 of @code{"$@@"} as explained below.
1130 Filename expansion is not performed.
1131 Assignment statements may also appear as arguments to the
1132 @code{declare}, @code{typeset}, @code{export}, @code{readonly},
1133 and @code{local} builtin commands.
1135 @node Positional Parameters
1136 @subsection Positional Parameters
1137 @cindex parameters, positional
1139 A @var{positional parameter} is a parameter denoted by one or more
1140 digits, other than the single digit @code{0}. Positional parameters are
1141 assigned from the shell's arguments when it is invoked,
1142 and may be reassigned using the @code{set} builtin command.
1143 Positional parameter @code{N} may be referenced as @code{$@{N@}}, or
1144 as @code{$N} when @code{N} consists of a single digit.
1145 Positional parameters may not be assigned to with assignment statements.
1146 The @code{set} and @code{shift} builtins are used to set and
1147 unset them (@pxref{Shell Builtin Commands}).
1148 The positional parameters are
1149 temporarily replaced when a shell function is executed
1150 (@pxref{Shell Functions}).
1152 When a positional parameter consisting of more than a single
1153 digit is expanded, it must be enclosed in braces.
1155 @node Special Parameters
1156 @subsection Special Parameters
1157 @cindex parameters, special
1159 The shell treats several parameters specially. These parameters may
1160 only be referenced; assignment to them is not allowed.
1165 Expands to the positional parameters, starting from one. When the
1166 expansion occurs within double quotes, it expands to a single word
1167 with the value of each parameter separated by the first character
1169 special variable. That is, @code{"$*"} is equivalent
1170 to @code{"$1@var{c}$2@var{c}@dots{}"}, where @var{c}
1171 is the first character of the value of the @code{IFS}
1173 If @env{IFS} is unset, the parameters are separated by spaces.
1174 If @env{IFS} is null, the parameters are joined without intervening
1179 Expands to the positional parameters, starting from one. When the
1180 expansion occurs within double quotes, each parameter expands to a
1181 separate word. That is, @code{"$@@"} is equivalent to
1182 @code{"$1" "$2" @dots{}}.
1183 When there are no positional parameters, @code{"$@@"} and
1185 expand to nothing (i.e., they are removed).
1188 Expands to the number of positional parameters in decimal.
1191 Expands to the exit status of the most recently executed foreground
1195 (A hyphen.) Expands to the current option flags as specified upon
1196 invocation, by the @code{set}
1197 builtin command, or those set by the shell itself
1198 (such as the @option{-i} option).
1201 Expands to the process @sc{id} of the shell. In a @code{()} subshell, it
1202 expands to the process @sc{id} of the invoking shell, not the subshell.
1205 Expands to the process @sc{id} of the most recently executed background
1206 (asynchronous) command.
1209 Expands to the name of the shell or shell script. This is set at
1210 shell initialization. If Bash is invoked with a file of commands
1211 (@pxref{Shell Scripts}), @code{$0} is set to the name of that file.
1212 If Bash is started with the @option{-c} option (@pxref{Invoking Bash}),
1213 then @code{$0} is set to the first argument after the string to be
1214 executed, if one is present. Otherwise, it is set
1215 to the filename used to invoke Bash, as given by argument zero.
1219 At shell startup, set to the absolute filename of the shell or shell
1220 script being executed as passed in the argument list.
1221 Subsequently, expands to the last argument to the previous command,
1223 Also set to the full pathname of each command executed and placed in
1224 the environment exported to that command.
1225 When checking mail, this parameter holds the name of the mail file.
1228 @node Shell Expansions
1229 @section Shell Expansions
1232 Expansion is performed on the command line after it has been split into
1233 @code{token}s. There are seven kinds of expansion performed:
1235 @item brace expansion
1236 @item tilde expansion
1237 @item parameter and variable expansion
1238 @item command substitution
1239 @item arithmetic expansion
1240 @item word splitting
1241 @item filename expansion
1245 * Brace Expansion:: Expansion of expressions within braces.
1246 * Tilde Expansion:: Expansion of the ~ character.
1247 * Shell Parameter Expansion:: How Bash expands variables to their values.
1248 * Command Substitution:: Using the output of a command as an argument.
1249 * Arithmetic Expansion:: How to use arithmetic in shell expansions.
1250 * Process Substitution:: A way to write and read to and from a
1252 * Word Splitting:: How the results of expansion are split into separate
1254 * Filename Expansion:: A shorthand for specifying filenames matching patterns.
1255 * Quote Removal:: How and when quote characters are removed from
1259 The order of expansions is: brace expansion, tilde expansion,
1260 parameter, variable, and arithmetic expansion and
1261 command substitution
1262 (done in a left-to-right fashion), word splitting, and filename
1265 On systems that can support it, there is an additional expansion
1266 available: @var{process substitution}. This is performed at the
1267 same time as parameter, variable, and arithmetic expansion and
1268 command substitution.
1270 Only brace expansion, word splitting, and filename expansion
1271 can change the number of words of the expansion; other expansions
1272 expand a single word to a single word.
1273 The only exceptions to this are the expansions of
1274 @code{"$@@"} (@pxref{Special Parameters}) and @code{"$@{@var{name}[@@]@}"}
1277 After all expansions, @code{quote removal} (@pxref{Quote Removal})
1280 @node Brace Expansion
1281 @subsection Brace Expansion
1282 @cindex brace expansion
1283 @cindex expansion, brace
1285 Brace expansion is a mechanism by which arbitrary strings may be generated.
1286 This mechanism is similar to
1287 @var{filename expansion} (@pxref{Filename Expansion}),
1288 but the file names generated need not exist.
1289 Patterns to be brace expanded take the form of an optional @var{preamble},
1290 followed by a series of comma-separated strings between a pair of braces,
1291 followed by an optional @var{postscript}.
1292 The preamble is prefixed to each string contained within the braces, and
1293 the postscript is then appended to each resulting string, expanding left
1296 Brace expansions may be nested.
1297 The results of each expanded string are not sorted; left to right order
1301 bash$ echo a@{d,c,b@}e
1305 Brace expansion is performed before any other expansions,
1306 and any characters special to other expansions are preserved
1307 in the result. It is strictly textual. Bash
1308 does not apply any syntactic interpretation to the context of the
1309 expansion or the text between the braces.
1310 To avoid conflicts with parameter expansion, the string @samp{$@{}
1311 is not considered eligible for brace expansion.
1313 A correctly-formed brace expansion must contain unquoted opening
1314 and closing braces, and at least one unquoted comma.
1315 Any incorrectly formed brace expansion is left unchanged.
1317 This construct is typically used as shorthand when the common
1318 prefix of the strings to be generated is longer than in the
1321 mkdir /usr/local/src/bash/@{old,new,dist,bugs@}
1325 chown root /usr/@{ucb/@{ex,edit@},lib/@{ex?.?*,how_ex@}@}
1328 @node Tilde Expansion
1329 @subsection Tilde Expansion
1330 @cindex tilde expansion
1331 @cindex expansion, tilde
1333 If a word begins with an unquoted tilde character (@samp{~}), all of the
1334 characters up to the first unquoted slash (or all characters,
1335 if there is no unquoted slash) are considered a @var{tilde-prefix}.
1336 If none of the characters in the tilde-prefix are quoted, the
1337 characters in the tilde-prefix following the tilde are treated as a
1338 possible @var{login name}.
1339 If this login name is the null string, the tilde is replaced with the
1340 value of the @env{HOME} shell variable.
1341 If @env{HOME} is unset, the home directory of the user executing the
1342 shell is substituted instead.
1343 Otherwise, the tilde-prefix is replaced with the home directory
1344 associated with the specified login name.
1346 If the tilde-prefix is @samp{~+}, the value of
1347 the shell variable @env{PWD} replaces the tilde-prefix.
1348 If the tilde-prefix is @samp{~-}, the value of the shell variable
1349 @env{OLDPWD}, if it is set, is substituted.
1351 If the characters following the tilde in the tilde-prefix consist of a
1352 number @var{N}, optionally prefixed by a @samp{+} or a @samp{-},
1353 the tilde-prefix is replaced with the
1354 corresponding element from the directory stack, as it would be displayed
1355 by the @code{dirs} builtin invoked with the characters following tilde
1356 in the tilde-prefix as an argument (@pxref{The Directory Stack}).
1357 If the tilde-prefix, sans the tilde, consists of a number without a
1358 leading @samp{+} or @samp{-}, @samp{+} is assumed.
1360 If the login name is invalid, or the tilde expansion fails, the word is
1363 Each variable assignment is checked for unquoted tilde-prefixes immediately
1364 following a @samp{:} or @samp{=}.
1365 In these cases, tilde expansion is also performed.
1366 Consequently, one may use file names with tildes in assignments to
1367 @env{PATH}, @env{MAILPATH}, and @env{CDPATH},
1368 and the shell assigns the expanded value.
1370 The following table shows how Bash treats unquoted tilde-prefixes:
1374 The value of @code{$HOME}
1379 The subdirectory @code{foo} of the home directory of the user
1386 @file{$@{OLDPWD-'~-'@}/foo}
1389 The string that would be displayed by @samp{dirs +@var{N}}
1392 The string that would be displayed by @samp{dirs +@var{N}}
1395 The string that would be displayed by @samp{dirs -@var{N}}
1399 @node Shell Parameter Expansion
1400 @subsection Shell Parameter Expansion
1401 @cindex parameter expansion
1402 @cindex expansion, parameter
1404 The @samp{$} character introduces parameter expansion,
1405 command substitution, or arithmetic expansion. The parameter name
1406 or symbol to be expanded may be enclosed in braces, which
1407 are optional but serve to protect the variable to be expanded from
1408 characters immediately following it which could be
1409 interpreted as part of the name.
1411 When braces are used, the matching ending brace is the first @samp{@}}
1412 not escaped by a backslash or within a quoted string, and not within an
1413 embedded arithmetic expansion, command substitution, or parameter
1416 The basic form of parameter expansion is $@{@var{parameter}@}.
1417 The value of @var{parameter} is substituted. The braces are required
1418 when @var{parameter}
1419 is a positional parameter with more than one digit,
1420 or when @var{parameter}
1421 is followed by a character that is not to be
1422 interpreted as part of its name.
1424 If the first character of @var{parameter} is an exclamation point,
1425 a level of variable indirection is introduced.
1426 Bash uses the value of the variable formed from the rest of
1427 @var{parameter} as the name of the variable; this variable is then
1428 expanded and that value is used in the rest of the substitution, rather
1429 than the value of @var{parameter} itself.
1430 This is known as @code{indirect expansion}.
1431 The exception to this is the expansion of $@{!@var{prefix*@}}
1434 In each of the cases below, @var{word} is subject to tilde expansion,
1435 parameter expansion, command substitution, and arithmetic expansion.
1437 When not performing substring expansion, Bash tests for a parameter
1438 that is unset or null; omitting the colon results in a test only for a
1439 parameter that is unset. Put another way, if the colon is included,
1440 the operator tests for both existence and that the value is not null;
1441 if the colon is omitted, the operator tests only for existence.
1445 @item $@{@var{parameter}:@minus{}@var{word}@}
1446 If @var{parameter} is unset or null, the expansion of
1447 @var{word} is substituted. Otherwise, the value of
1448 @var{parameter} is substituted.
1450 @item $@{@var{parameter}:=@var{word}@}
1452 is unset or null, the expansion of @var{word}
1453 is assigned to @var{parameter}.
1454 The value of @var{parameter}
1455 is then substituted. Positional parameters and special parameters may
1456 not be assigned to in this way.
1458 @item $@{@var{parameter}:?@var{word}@}
1460 is null or unset, the expansion of @var{word} (or a message
1461 to that effect if @var{word}
1462 is not present) is written to the standard error and the shell, if it
1463 is not interactive, exits. Otherwise, the value of @var{parameter} is
1466 @item $@{@var{parameter}:+@var{word}@}
1468 is null or unset, nothing is substituted, otherwise the expansion of
1469 @var{word} is substituted.
1471 @item $@{@var{parameter}:@var{offset}@}
1472 @itemx $@{@var{parameter}:@var{offset}:@var{length}@}
1473 Expands to up to @var{length} characters of @var{parameter}
1474 starting at the character specified by @var{offset}.
1475 If @var{length} is omitted, expands to the substring of
1476 @var{parameter} starting at the character specified by @var{offset}.
1477 @var{length} and @var{offset} are arithmetic expressions
1478 (@pxref{Shell Arithmetic}).
1479 This is referred to as Substring Expansion.
1481 @var{length} must evaluate to a number greater than or equal to zero.
1482 If @var{offset} evaluates to a number less than zero, the value
1483 is used as an offset from the end of the value of @var{parameter}.
1484 If @var{parameter} is @samp{@@}, the result is @var{length} positional
1485 parameters beginning at @var{offset}.
1486 If @var{parameter} is an array name indexed by @samp{@@} or @samp{*},
1487 the result is the @var{length}
1488 members of the array beginning with @code{$@{@var{parameter}[@var{offset}]@}}.
1489 Substring indexing is zero-based unless the positional parameters
1490 are used, in which case the indexing starts at 1.
1492 @item $@{!@var{prefix}*@}
1493 Expands to the names of variables whose names begin with @var{prefix},
1494 separated by the first character of the @env{IFS} special variable.
1496 @item $@{#@var{parameter}@}
1497 The length in characters of the expanded value of @var{parameter} is
1499 If @var{parameter} is @samp{*} or @samp{@@}, the value substituted
1500 is the number of positional parameters.
1501 If @var{parameter} is an array name subscripted by @samp{*} or @samp{@@},
1502 the value substituted is the number of elements in the array.
1504 @item $@{@var{parameter}#@var{word}@}
1505 @itemx $@{@var{parameter}##@var{word}@}
1507 is expanded to produce a pattern just as in filename
1508 expansion (@pxref{Filename Expansion}). If the pattern matches
1509 the beginning of the expanded value of @var{parameter},
1510 then the result of the expansion is the expanded value of @var{parameter}
1511 with the shortest matching pattern (the @samp{#} case) or the
1512 longest matching pattern (the @samp{##} case) deleted.
1513 If @var{parameter} is @samp{@@} or @samp{*},
1514 the pattern removal operation is applied to each positional
1515 parameter in turn, and the expansion is the resultant list.
1516 If @var{parameter} is an array variable subscripted with
1517 @samp{@@} or @samp{*},
1518 the pattern removal operation is applied to each member of the
1519 array in turn, and the expansion is the resultant list.
1521 @item $@{@var{parameter}%@var{word}@}
1522 @itemx $@{@var{parameter}%%@var{word}@}
1523 The @var{word} is expanded to produce a pattern just as in
1525 If the pattern matches a trailing portion of the expanded value of
1526 @var{parameter}, then the result of the expansion is the value of
1527 @var{parameter} with the shortest matching pattern (the @samp{%} case)
1528 or the longest matching pattern (the @samp{%%} case) deleted.
1529 If @var{parameter} is @samp{@@} or @samp{*},
1530 the pattern removal operation is applied to each positional
1531 parameter in turn, and the expansion is the resultant list.
1533 is an array variable subscripted with @samp{@@} or @samp{*},
1534 the pattern removal operation is applied to each member of the
1535 array in turn, and the expansion is the resultant list.
1537 @item $@{@var{parameter}/@var{pattern}/@var{string}@}
1538 @itemx $@{@var{parameter}//@var{pattern}/@var{string}@}
1540 The @var{pattern} is expanded to produce a pattern just as in
1542 @var{Parameter} is expanded and the longest match of @var{pattern}
1543 against its value is replaced with @var{string}.
1544 In the first form, only the first match is replaced.
1545 The second form causes all matches of @var{pattern} to be
1546 replaced with @var{string}.
1547 If @var{pattern} begins with @samp{#}, it must match at the beginning
1548 of the expanded value of @var{parameter}.
1549 If @var{pattern} begins with @samp{%}, it must match at the end
1550 of the expanded value of @var{parameter}.
1551 If @var{string} is null, matches of @var{pattern} are deleted
1552 and the @code{/} following @var{pattern} may be omitted.
1553 If @var{parameter} is @samp{@@} or @samp{*},
1554 the substitution operation is applied to each positional
1555 parameter in turn, and the expansion is the resultant list.
1557 is an array variable subscripted with @samp{@@} or @samp{*},
1558 the substitution operation is applied to each member of the
1559 array in turn, and the expansion is the resultant list.
1563 @node Command Substitution
1564 @subsection Command Substitution
1565 @cindex command substitution
1567 Command substitution allows the output of a command to replace
1569 Command substitution occurs when a command is enclosed as follows:
1580 Bash performs the expansion by executing @var{command} and
1581 replacing the command substitution with the standard output of the
1582 command, with any trailing newlines deleted.
1583 Embedded newlines are not deleted, but they may be removed during
1585 The command substitution @code{$(cat @var{file})} can be
1586 replaced by the equivalent but faster @code{$(< @var{file})}.
1588 When the old-style backquote form of substitution is used,
1589 backslash retains its literal meaning except when followed by
1590 @samp{$}, @samp{`}, or @samp{\}.
1591 The first backquote not preceded by a backslash terminates the
1592 command substitution.
1593 When using the @code{$(@var{command})} form, all characters between
1594 the parentheses make up the command; none are treated specially.
1596 Command substitutions may be nested. To nest when using the backquoted
1597 form, escape the inner backquotes with backslashes.
1599 If the substitution appears within double quotes, word splitting and
1600 filename expansion are not performed on the results.
1602 @node Arithmetic Expansion
1603 @subsection Arithmetic Expansion
1604 @cindex expansion, arithmetic
1605 @cindex arithmetic expansion
1607 Arithmetic expansion allows the evaluation of an arithmetic expression
1608 and the substitution of the result. The format for arithmetic expansion is:
1611 $(( @var{expression} ))
1614 The expression is treated as if it were within double quotes, but
1615 a double quote inside the parentheses is not treated specially.
1616 All tokens in the expression undergo parameter expansion, command
1617 substitution, and quote removal.
1618 Arithmetic substitutions may be nested.
1620 The evaluation is performed according to the rules listed below
1621 (@pxref{Shell Arithmetic}).
1622 If the expression is invalid, Bash prints a message indicating
1623 failure to the standard error and no substitution occurs.
1625 @node Process Substitution
1626 @subsection Process Substitution
1627 @cindex process substitution
1629 Process substitution is supported on systems that support named
1630 pipes (@sc{fifo}s) or the @file{/dev/fd} method of naming open files.
1631 It takes the form of
1641 The process @var{list} is run with its input or output connected to a
1642 @sc{fifo} or some file in @file{/dev/fd}. The name of this file is
1643 passed as an argument to the current command as the result of the
1644 expansion. If the @code{>(@var{list})} form is used, writing to
1645 the file will provide input for @var{list}. If the
1646 @code{<(@var{list})} form is used, the file passed as an
1647 argument should be read to obtain the output of @var{list}.
1648 Note that no space may appear between the @code{<} or @code{>}
1649 and the left parenthesis, otherwise the construct would be interpreted
1652 When available, process substitution is performed simultaneously with
1653 parameter and variable expansion, command substitution, and arithmetic
1656 @node Word Splitting
1657 @subsection Word Splitting
1658 @cindex word splitting
1660 The shell scans the results of parameter expansion, command substitution,
1661 and arithmetic expansion that did not occur within double quotes for
1664 The shell treats each character of @env{$IFS}
1665 as a delimiter, and splits the results of the other
1666 expansions into words on these characters. If
1667 @env{IFS} is unset, or its value is exactly @code{<space><tab><newline>},
1668 the default, then any sequence of @env{IFS}
1669 characters serves to delimit words. If @env{IFS}
1670 has a value other than the default, then sequences of
1671 the whitespace characters @code{space} and @code{tab}
1672 are ignored at the beginning and end of the
1673 word, as long as the whitespace character is in the
1674 value of @env{IFS} (an @env{IFS} whitespace character).
1675 Any character in @env{IFS} that is not @env{IFS}
1676 whitespace, along with any adjacent @env{IFS}
1677 whitespace characters, delimits a field. A sequence of @env{IFS}
1678 whitespace characters is also treated as a delimiter.
1679 If the value of @env{IFS} is null, no word splitting occurs.
1681 Explicit null arguments (@code{""} or @code{''}) are retained.
1682 Unquoted implicit null arguments, resulting from the expansion of
1683 parameters that have no values, are removed.
1684 If a parameter with no value is expanded within double quotes, a
1685 null argument results and is retained.
1687 Note that if no expansion occurs, no splitting
1690 @node Filename Expansion
1691 @subsection Filename Expansion
1693 * Pattern Matching:: How the shell matches patterns.
1695 @cindex expansion, filename
1696 @cindex expansion, pathname
1697 @cindex filename expansion
1698 @cindex pathname expansion
1700 After word splitting, unless the @option{-f} option has been set
1701 (@pxref{The Set Builtin}), Bash scans each word for the characters
1702 @samp{*}, @samp{?}, and @samp{[}.
1703 If one of these characters appears, then the word is
1704 regarded as a @var{pattern},
1705 and replaced with an alphabetically sorted list of
1706 file names matching the pattern. If no matching file names are found,
1707 and the shell option @code{nullglob} is disabled, the word is left
1709 If the @code{nullglob} option is set, and no matches are found, the word
1711 If the shell option @code{nocaseglob} is enabled, the match is performed
1712 without regard to the case of alphabetic characters.
1714 When a pattern is used for filename generation, the character @samp{.}
1715 at the start of a filename or immediately following a slash
1716 must be matched explicitly, unless the shell option @code{dotglob} is set.
1717 When matching a file name, the slash character must always be
1719 In other cases, the @samp{.} character is not treated specially.
1721 See the description of @code{shopt} in @ref{Bash Builtins},
1722 for a description of the @code{nocaseglob}, @code{nullglob},
1723 and @code{dotglob} options.
1725 The @env{GLOBIGNORE}
1726 shell variable may be used to restrict the set of filenames matching a
1727 pattern. If @env{GLOBIGNORE}
1728 is set, each matching filename that also matches one of the patterns in
1729 @env{GLOBIGNORE} is removed from the list of matches. The filenames
1730 @file{.} and @file{..}
1731 are always ignored, even when @env{GLOBIGNORE}
1732 is set. However, setting @env{GLOBIGNORE} has the effect of
1733 enabling the @code{dotglob}
1734 shell option, so all other filenames beginning with a
1735 @samp{.} will match.
1736 To get the old behavior of ignoring filenames beginning with a
1737 @samp{.}, make @samp{.*} one of the patterns in @env{GLOBIGNORE}.
1738 The @code{dotglob} option is disabled when @env{GLOBIGNORE}
1741 @node Pattern Matching
1742 @subsubsection Pattern Matching
1743 @cindex pattern matching
1744 @cindex matching, pattern
1746 Any character that appears in a pattern, other than the special pattern
1747 characters described below, matches itself. The @sc{nul} character may not
1748 occur in a pattern. The special pattern characters must be quoted if
1749 they are to be matched literally.
1751 The special pattern characters have the following meanings:
1754 Matches any string, including the null string.
1756 Matches any single character.
1758 Matches any one of the enclosed characters. A pair of characters
1759 separated by a hyphen denotes a @var{range expression};
1760 any character that sorts between those two characters, inclusive,
1761 using the current locale's collating sequence and character set,
1762 is matched. If the first character following the
1763 @samp{[} is a @samp{!} or a @samp{^}
1764 then any character not enclosed is matched. A @samp{@minus{}}
1765 may be matched by including it as the first or last character
1766 in the set. A @samp{]} may be matched by including it as the first
1767 character in the set.
1768 The sorting order of characters in range expressions is determined by
1769 the current locale and the value of the @env{LC_COLLATE} shell variable,
1772 For example, in the default C locale, @samp{[a-dx-z]} is equivalent to
1773 @samp{[abcdxyz]}. Many locales sort characters in dictionary order, and in
1774 these locales @samp{[a-dx-z]} is typically not equivalent to @samp{[abcdxyz]};
1775 it might be equivalent to @samp{[aBbCcDdxXyYz]}, for example. To obtain
1776 the traditional interpretation of ranges in bracket expressions, you can
1777 force the use of the C locale by setting the @env{LC_COLLATE} or
1778 @env{LC_ALL} environment variable to the value @samp{C}.
1780 Within @samp{[} and @samp{]}, @var{character classes} can be specified
1782 @code{[:}@var{class}@code{:]}, where @var{class} is one of the
1783 following classes defined in the @sc{posix} 1003.2 standard:
1785 alnum alpha ascii blank cntrl digit graph lower
1786 print punct space upper word xdigit
1789 A character class matches any character belonging to that class.
1790 The @code{word} character class matches letters, digits, and the character
1793 Within @samp{[} and @samp{]}, an @var{equivalence class} can be
1794 specified using the syntax @code{[=}@var{c}@code{=]}, which
1795 matches all characters with the same collation weight (as defined
1796 by the current locale) as the character @var{c}.
1798 Within @samp{[} and @samp{]}, the syntax @code{[.}@var{symbol}@code{.]}
1799 matches the collating symbol @var{symbol}.
1802 If the @code{extglob} shell option is enabled using the @code{shopt}
1803 builtin, several extended pattern matching operators are recognized.
1804 In the following description, a @var{pattern-list} is a list of one
1805 or more patterns separated by a @samp{|}.
1806 Composite patterns may be formed using one or more of the following
1810 @item ?(@var{pattern-list})
1811 Matches zero or one occurrence of the given patterns.
1813 @item *(@var{pattern-list})
1814 Matches zero or more occurrences of the given patterns.
1816 @item +(@var{pattern-list})
1817 Matches one or more occurrences of the given patterns.
1819 @item @@(@var{pattern-list})
1820 Matches exactly one of the given patterns.
1822 @item !(@var{pattern-list})
1823 Matches anything except one of the given patterns.
1827 @subsection Quote Removal
1829 After the preceding expansions, all unquoted occurrences of the
1830 characters @samp{\}, @samp{'}, and @samp{"} that did not
1831 result from one of the above expansions are removed.
1834 @section Redirections
1837 Before a command is executed, its input and output
1838 may be @var{redirected}
1839 using a special notation interpreted by the shell.
1840 Redirection may also be used to open and close files for the
1841 current shell execution environment. The following redirection
1842 operators may precede or appear anywhere within a
1843 simple command or may follow a command.
1844 Redirections are processed in the order they appear, from
1847 In the following descriptions, if the file descriptor number is
1848 omitted, and the first character of the redirection operator is
1849 @samp{<}, the redirection refers to the standard input (file
1850 descriptor 0). If the first character of the redirection operator
1851 is @samp{>}, the redirection refers to the standard output (file
1854 The word following the redirection operator in the following
1855 descriptions, unless otherwise noted, is subjected to brace expansion,
1856 tilde expansion, parameter expansion, command substitution, arithmetic
1857 expansion, quote removal, filename expansion, and word splitting.
1858 If it expands to more than one word, Bash reports an error.
1860 Note that the order of redirections is significant. For example,
1863 ls > @var{dirlist} 2>&1
1866 directs both standard output (file descriptor 1) and standard error
1867 (file descriptor 2) to the file @var{dirlist}, while the command
1869 ls 2>&1 > @var{dirlist}
1872 directs only the standard output to file @var{dirlist},
1873 because the standard error was duplicated as standard output
1874 before the standard output was redirected to @var{dirlist}.
1876 Bash handles several filenames specially when they are used in
1877 redirections, as described in the following table:
1880 @item /dev/fd/@var{fd}
1881 If @var{fd} is a valid integer, file descriptor @var{fd} is duplicated.
1884 File descriptor 0 is duplicated.
1887 File descriptor 1 is duplicated.
1890 File descriptor 2 is duplicated.
1892 @item /dev/tcp/@var{host}/@var{port}
1893 If @var{host} is a valid hostname or Internet address, and @var{port}
1894 is an integer port number or service name, Bash attempts to open a TCP
1895 connection to the corresponding socket.
1897 @item /dev/udp/@var{host}/@var{port}
1898 If @var{host} is a valid hostname or Internet address, and @var{port}
1899 is an integer port number or service name, Bash attempts to open a UDP
1900 connection to the corresponding socket.
1904 A failure to open or create a file causes the redirection to fail.
1906 @subsection Redirecting Input
1907 Redirection of input causes the file whose name results from
1908 the expansion of @var{word}
1909 to be opened for reading on file descriptor @code{n},
1910 or the standard input (file descriptor 0) if @code{n}
1913 The general format for redirecting input is:
1915 [@var{n}]<@var{word}
1918 @subsection Redirecting Output
1919 Redirection of output causes the file whose name results from
1920 the expansion of @var{word}
1921 to be opened for writing on file descriptor @var{n},
1922 or the standard output (file descriptor 1) if @var{n}
1923 is not specified. If the file does not exist it is created;
1924 if it does exist it is truncated to zero size.
1926 The general format for redirecting output is:
1928 [@var{n}]>[|]@var{word}
1931 If the redirection operator is @samp{>}, and the @code{noclobber}
1932 option to the @code{set} builtin has been enabled, the redirection
1933 will fail if the file whose name results from the expansion of
1934 @var{word} exists and is a regular file.
1935 If the redirection operator is @samp{>|}, or the redirection operator is
1936 @samp{>} and the @code{noclobber} option is not enabled, the redirection
1937 is attempted even if the file named by @var{word} exists.
1939 @subsection Appending Redirected Output
1940 Redirection of output in this fashion
1941 causes the file whose name results from
1942 the expansion of @var{word}
1943 to be opened for appending on file descriptor @var{n},
1944 or the standard output (file descriptor 1) if @var{n}
1945 is not specified. If the file does not exist it is created.
1947 The general format for appending output is:
1949 [@var{n}]>>@var{word}
1952 @subsection Redirecting Standard Output and Standard Error
1953 Bash allows both the
1954 standard output (file descriptor 1) and
1955 the standard error output (file descriptor 2)
1956 to be redirected to the file whose name is the
1957 expansion of @var{word} with this construct.
1959 There are two formats for redirecting standard output and
1970 Of the two forms, the first is preferred.
1971 This is semantically equivalent to
1976 @subsection Here Documents
1977 This type of redirection instructs the shell to read input from the
1978 current source until a line containing only @var{word}
1979 (with no trailing blanks) is seen. All of
1980 the lines read up to that point are then used as the standard
1981 input for a command.
1983 The format of here-documents is:
1985 <<[@minus{}]@var{word}
1990 No parameter expansion, command substitution, arithmetic expansion,
1991 or filename expansion is performed on
1992 @var{word}. If any characters in @var{word} are quoted, the
1993 @var{delimiter} is the result of quote removal on @var{word},
1994 and the lines in the here-document are not expanded.
1995 If @var{word} is unquoted,
1996 all lines of the here-document are subjected to parameter expansion,
1997 command substitution, and arithmetic expansion. In the latter
1998 case, the character sequence @code{\newline} is ignored, and @samp{\}
1999 must be used to quote the characters
2000 @samp{\}, @samp{$}, and @samp{`}.
2002 If the redirection operator is @samp{<<-},
2003 then all leading tab characters are stripped from input lines and the
2004 line containing @var{delimiter}.
2005 This allows here-documents within shell scripts to be indented in a
2008 @subsection Here Strings
2009 A variant of here documents, the format is:
2014 The @var{word} is expanded and supplied to the command on its standard
2017 @subsection Duplicating File Descriptors
2018 The redirection operator
2020 [@var{n}]<&@var{word}
2023 is used to duplicate input file descriptors.
2025 expands to one or more digits, the file descriptor denoted by @var{n}
2026 is made to be a copy of that file descriptor.
2027 If the digits in @var{word} do not specify a file descriptor open for
2028 input, a redirection error occurs.
2030 evaluates to @samp{-}, file descriptor @var{n} is closed. If
2031 @var{n} is not specified, the standard input (file descriptor 0) is used.
2035 [@var{n}]>&@var{word}
2038 is used similarly to duplicate output file descriptors. If
2039 @var{n} is not specified, the standard output (file descriptor 1) is used.
2040 If the digits in @var{word} do not specify a file descriptor open for
2041 output, a redirection error occurs.
2042 As a special case, if @var{n} is omitted, and @var{word} does not
2043 expand to one or more digits, the standard output and standard
2044 error are redirected as described previously.
2046 @subsection Moving File Descriptors
2047 The redirection operator
2049 [@var{n}]<&@var{digit}-
2052 moves the file descriptor @var{digit} to file descriptor @var{n},
2053 or the standard input (file descriptor 0) if @var{n} is not specified.
2054 @var{digit} is closed after being duplicated to @var{n}.
2056 Similarly, the redirection operator
2058 [@var{n}]>&@var{digit}-
2061 moves the file descriptor @var{digit} to file descriptor @var{n},
2062 or the standard output (file descriptor 1) if @var{n} is not specified.
2064 @subsection Opening File Descriptors for Reading and Writing
2065 The redirection operator
2067 [@var{n}]<>@var{word}
2070 causes the file whose name is the expansion of @var{word}
2071 to be opened for both reading and writing on file descriptor
2072 @var{n}, or on file descriptor 0 if @var{n}
2073 is not specified. If the file does not exist, it is created.
2075 @node Executing Commands
2076 @section Executing Commands
2079 * Simple Command Expansion:: How Bash expands simple commands before
2082 * Command Search and Execution:: How Bash finds commands and runs them.
2084 * Command Execution Environment:: The environment in which Bash
2085 executes commands that are not
2088 * Environment:: The environment given to a command.
2090 * Exit Status:: The status returned by commands and how Bash
2093 * Signals:: What happens when Bash or a command it runs
2098 @node Simple Command Expansion
2099 @subsection Simple Command Expansion
2100 @cindex command expansion
2102 When a simple command is executed, the shell performs the following
2103 expansions, assignments, and redirections, from left to right.
2107 The words that the parser has marked as variable assignments (those
2108 preceding the command name) and redirections are saved for later
2112 The words that are not variable assignments or redirections are
2113 expanded (@pxref{Shell Expansions}).
2114 If any words remain after expansion, the first word
2115 is taken to be the name of the command and the remaining words are
2119 Redirections are performed as described above (@pxref{Redirections}).
2122 The text after the @samp{=} in each variable assignment undergoes tilde
2123 expansion, parameter expansion, command substitution, arithmetic expansion,
2124 and quote removal before being assigned to the variable.
2127 If no command name results, the variable assignments affect the current
2128 shell environment. Otherwise, the variables are added to the environment
2129 of the executed command and do not affect the current shell environment.
2130 If any of the assignments attempts to assign a value to a readonly variable,
2131 an error occurs, and the command exits with a non-zero status.
2133 If no command name results, redirections are performed, but do not
2134 affect the current shell environment. A redirection error causes the
2135 command to exit with a non-zero status.
2137 If there is a command name left after expansion, execution proceeds as
2138 described below. Otherwise, the command exits. If one of the expansions
2139 contained a command substitution, the exit status of the command is
2140 the exit status of the last command substitution performed. If there
2141 were no command substitutions, the command exits with a status of zero.
2143 @node Command Search and Execution
2144 @subsection Command Search and Execution
2145 @cindex command execution
2146 @cindex command search
2148 After a command has been split into words, if it results in a
2149 simple command and an optional list of arguments, the following
2154 If the command name contains no slashes, the shell attempts to
2155 locate it. If there exists a shell function by that name, that
2156 function is invoked as described in @ref{Shell Functions}.
2159 If the name does not match a function, the shell searches for
2160 it in the list of shell builtins. If a match is found, that
2164 If the name is neither a shell function nor a builtin,
2165 and contains no slashes, Bash searches each element of
2166 @env{$PATH} for a directory containing an executable file
2167 by that name. Bash uses a hash table to remember the full
2168 pathnames of executable files to avoid multiple @env{PATH} searches
2169 (see the description of @code{hash} in @ref{Bourne Shell Builtins}).
2170 A full search of the directories in @env{$PATH}
2171 is performed only if the command is not found in the hash table.
2172 If the search is unsuccessful, the shell prints an error
2173 message and returns an exit status of 127.
2176 If the search is successful, or if the command name contains
2177 one or more slashes, the shell executes the named program in
2178 a separate execution environment.
2179 Argument 0 is set to the name given, and the remaining arguments
2180 to the command are set to the arguments supplied, if any.
2183 If this execution fails because the file is not in executable
2184 format, and the file is not a directory, it is assumed to be a
2185 @var{shell script} and the shell executes it as described in
2186 @ref{Shell Scripts}.
2189 If the command was not begun asynchronously, the shell waits for
2190 the command to complete and collects its exit status.
2194 @node Command Execution Environment
2195 @subsection Command Execution Environment
2196 @cindex execution environment
2198 The shell has an @var{execution environment}, which consists of the
2203 open files inherited by the shell at invocation, as modified by
2204 redirections supplied to the @code{exec} builtin
2207 the current working directory as set by @code{cd}, @code{pushd}, or
2208 @code{popd}, or inherited by the shell at invocation
2211 the file creation mode mask as set by @code{umask} or inherited from
2215 current traps set by @code{trap}
2218 shell parameters that are set by variable assignment or with @code{set}
2219 or inherited from the shell's parent in the environment
2222 shell functions defined during execution or inherited from the shell's
2223 parent in the environment
2226 options enabled at invocation (either by default or with command-line
2227 arguments) or by @code{set}
2230 options enabled by @code{shopt}
2233 shell aliases defined with @code{alias} (@pxref{Aliases})
2236 various process @sc{id}s, including those of background jobs
2237 (@pxref{Lists}), the value of @code{$$}, and the value of
2242 When a simple command other than a builtin or shell function
2243 is to be executed, it
2244 is invoked in a separate execution environment that consists of
2245 the following. Unless otherwise noted, the values are inherited
2250 the shell's open files, plus any modifications and additions specified
2251 by redirections to the command
2254 the current working directory
2257 the file creation mode mask
2260 shell variables marked for export, along with variables exported for
2261 the command, passed in the environment (@pxref{Environment})
2264 traps caught by the shell are reset to the values inherited from the
2265 shell's parent, and traps ignored by the shell are ignored
2269 A command invoked in this separate environment cannot affect the
2270 shell's execution environment.
2272 Command substitution and asynchronous commands are invoked in a
2273 subshell environment that is a duplicate of the shell environment,
2274 except that traps caught by the shell are reset to the values
2275 that the shell inherited from its parent at invocation. Builtin
2276 commands that are invoked as part of a pipeline are also executed
2277 in a subshell environment. Changes made to the subshell environment
2278 cannot affect the shell's execution environment.
2280 If a command is followed by a @samp{&} and job control is not active, the
2281 default standard input for the command is the empty file @file{/dev/null}.
2282 Otherwise, the invoked command inherits the file descriptors of the calling
2283 shell as modified by redirections.
2286 @subsection Environment
2289 When a program is invoked it is given an array of strings
2290 called the @var{environment}.
2291 This is a list of name-value pairs, of the form @code{name=value}.
2293 Bash provides several ways to manipulate the environment.
2294 On invocation, the shell scans its own environment and
2295 creates a parameter for each name found, automatically marking
2297 to child processes. Executed commands inherit the environment.
2298 The @code{export} and @samp{declare -x}
2299 commands allow parameters and functions to be added to and
2300 deleted from the environment. If the value of a parameter
2301 in the environment is modified, the new value becomes part
2302 of the environment, replacing the old. The environment
2303 inherited by any executed command consists of the shell's
2304 initial environment, whose values may be modified in the shell,
2305 less any pairs removed by the @code{unset} and @samp{export -n}
2306 commands, plus any additions via the @code{export} and
2307 @samp{declare -x} commands.
2309 The environment for any simple command
2310 or function may be augmented temporarily by prefixing it with
2311 parameter assignments, as described in @ref{Shell Parameters}.
2312 These assignment statements affect only the environment seen
2315 If the @option{-k} option is set (@pxref{The Set Builtin}), then all
2316 parameter assignments are placed in the environment for a command,
2317 not just those that precede the command name.
2319 When Bash invokes an external command, the variable @samp{$_}
2320 is set to the full path name of the command and passed to that
2321 command in its environment.
2324 @subsection Exit Status
2327 For the shell's purposes, a command which exits with a
2328 zero exit status has succeeded.
2329 A non-zero exit status indicates failure.
2330 This seemingly counter-intuitive scheme is used so there
2331 is one well-defined way to indicate success and a variety of
2332 ways to indicate various failure modes.
2333 When a command terminates on a fatal signal whose number is @var{N},
2334 Bash uses the value 128+@var{N} as the exit status.
2336 If a command is not found, the child process created to
2337 execute it returns a status of 127. If a command is found
2338 but is not executable, the return status is 126.
2340 If a command fails because of an error during expansion or redirection,
2341 the exit status is greater than zero.
2343 The exit status is used by the Bash conditional commands
2344 (@pxref{Conditional Constructs}) and some of the list
2345 constructs (@pxref{Lists}).
2347 All of the Bash builtins return an exit status of zero if they succeed
2348 and a non-zero status on failure, so they may be used by the
2349 conditional and list constructs.
2350 All builtins return an exit status of 2 to indicate incorrect usage.
2354 @cindex signal handling
2356 When Bash is interactive, in the absence of any traps, it ignores
2357 @code{SIGTERM} (so that @samp{kill 0} does not kill an interactive shell),
2359 is caught and handled (so that the @code{wait} builtin is interruptible).
2360 When Bash receives a @code{SIGINT}, it breaks out of any executing loops.
2361 In all cases, Bash ignores @code{SIGQUIT}.
2362 If job control is in effect (@pxref{Job Control}), Bash
2363 ignores @code{SIGTTIN}, @code{SIGTTOU}, and @code{SIGTSTP}.
2365 Commands started by Bash have signal handlers set to the
2366 values inherited by the shell from its parent.
2367 When job control is not in effect, asynchronous commands
2368 ignore @code{SIGINT} and @code{SIGQUIT} as well.
2369 Commands run as a result of
2370 command substitution ignore the keyboard-generated job control signals
2371 @code{SIGTTIN}, @code{SIGTTOU}, and @code{SIGTSTP}.
2373 The shell exits by default upon receipt of a @code{SIGHUP}.
2374 Before exiting, an interactive shell resends the @code{SIGHUP} to
2375 all jobs, running or stopped.
2376 Stopped jobs are sent @code{SIGCONT} to ensure that they receive
2378 To prevent the shell from sending the @code{SIGHUP} signal to a
2379 particular job, it should be removed
2380 from the jobs table with the @code{disown}
2381 builtin (@pxref{Job Control Builtins}) or marked
2382 to not receive @code{SIGHUP} using @code{disown -h}.
2384 If the @code{huponexit} shell option has been set with @code{shopt}
2385 (@pxref{Bash Builtins}), Bash sends a @code{SIGHUP} to all jobs when
2386 an interactive login shell exits.
2388 When Bash receives a signal for which a trap has been set while waiting
2389 for a command to complete, the trap will not be executed until the
2391 When Bash is waiting for an asynchronous
2392 command via the @code{wait} builtin, the reception of a signal for
2393 which a trap has been set will cause the @code{wait} builtin to return
2394 immediately with an exit status greater than 128, immediately after
2395 which the trap is executed.
2398 @section Shell Scripts
2399 @cindex shell script
2401 A shell script is a text file containing shell commands. When such
2402 a file is used as the first non-option argument when invoking Bash,
2403 and neither the @option{-c} nor @option{-s} option is supplied
2404 (@pxref{Invoking Bash}),
2405 Bash reads and executes commands from the file, then exits. This
2406 mode of operation creates a non-interactive shell. The shell first
2407 searches for the file in the current directory, and looks in the
2408 directories in @env{$PATH} if not found there.
2411 a shell script, it sets the special parameter @code{0} to the name
2412 of the file, rather than the name of the shell, and the positional
2413 parameters are set to the remaining arguments, if any are given.
2414 If no additional arguments are supplied, the positional parameters
2417 A shell script may be made executable by using the @code{chmod} command
2418 to turn on the execute bit. When Bash finds such a file while
2419 searching the @env{$PATH} for a command, it spawns a subshell to
2420 execute it. In other words, executing
2422 filename @var{arguments}
2425 is equivalent to executing
2427 bash filename @var{arguments}
2431 if @code{filename} is an executable shell script.
2432 This subshell reinitializes itself, so that the effect is as if a
2433 new shell had been invoked to interpret the script, with the
2434 exception that the locations of commands remembered by the parent
2435 (see the description of @code{hash} in @ref{Bourne Shell Builtins})
2436 are retained by the child.
2438 Most versions of Unix make this a part of the operating system's command
2439 execution mechanism. If the first line of a script begins with
2440 the two characters @samp{#!}, the remainder of the line specifies
2441 an interpreter for the program.
2442 Thus, you can specify Bash, @code{awk}, Perl, or some other
2443 interpreter and write the rest of the script file in that language.
2445 The arguments to the interpreter
2446 consist of a single optional argument following the interpreter
2447 name on the first line of the script file, followed by the name of
2448 the script file, followed by the rest of the arguments. Bash
2449 will perform this action on operating systems that do not handle it
2450 themselves. Note that some older versions of Unix limit the interpreter
2451 name and argument to a maximum of 32 characters.
2453 Bash scripts often begin with @code{#! /bin/bash} (assuming that
2454 Bash has been installed in @file{/bin}), since this ensures that
2455 Bash will be used to interpret the script, even if it is executed
2456 under another shell.
2458 @node Shell Builtin Commands
2459 @chapter Shell Builtin Commands
2462 * Bourne Shell Builtins:: Builtin commands inherited from the Bourne
2464 * Bash Builtins:: Table of builtins specific to Bash.
2465 * The Set Builtin:: This builtin is so overloaded it
2466 deserves its own section.
2467 * Special Builtins:: Builtin commands classified specially by
2471 Builtin commands are contained within the shell itself.
2472 When the name of a builtin command is used as the first word of
2473 a simple command (@pxref{Simple Commands}), the shell executes
2474 the command directly, without invoking another program.
2475 Builtin commands are necessary to implement functionality impossible
2476 or inconvenient to obtain with separate utilities.
2478 This section briefly the builtins which Bash inherits from
2479 the Bourne Shell, as well as the builtin commands which are unique
2480 to or have been extended in Bash.
2482 Several builtin commands are described in other chapters: builtin
2483 commands which provide the Bash interface to the job control
2484 facilities (@pxref{Job Control Builtins}), the directory stack
2485 (@pxref{Directory Stack Builtins}), the command history
2486 (@pxref{Bash History Builtins}), and the programmable completion
2487 facilities (@pxref{Programmable Completion Builtins}).
2489 Many of the builtins have been extended by @sc{posix} or Bash.
2491 @node Bourne Shell Builtins
2492 @section Bourne Shell Builtins
2494 The following shell builtin commands are inherited from the Bourne Shell.
2495 These commands are implemented as specified by the @sc{posix} 1003.2 standard.
2498 @item : @r{(a colon)}
2503 Do nothing beyond expanding @var{arguments} and performing redirections.
2504 The return status is zero.
2506 @item . @r{(a period)}
2509 . @var{filename} [@var{arguments}]
2511 Read and execute commands from the @var{filename} argument in the
2512 current shell context. If @var{filename} does not contain a slash,
2513 the @env{PATH} variable is used to find @var{filename}.
2514 When Bash is not in @sc{posix} mode, the current directory is searched
2515 if @var{filename} is not found in @env{$PATH}.
2516 If any @var{arguments} are supplied, they become the positional
2517 parameters when @var{filename} is executed. Otherwise the positional
2518 parameters are unchanged.
2519 The return status is the exit status of the last command executed, or
2520 zero if no commands are executed. If @var{filename} is not found, or
2521 cannot be read, the return status is non-zero.
2522 This builtin is equivalent to @code{source}.
2529 Exit from a @code{for}, @code{while}, @code{until}, or @code{select} loop.
2530 If @var{n} is supplied, the @var{n}th enclosing loop is exited.
2531 @var{n} must be greater than or equal to 1.
2532 The return status is zero unless @var{n} is not greater than or equal to 1.
2537 cd [-L|-P] [@var{directory}]
2539 Change the current working directory to @var{directory}. If @var{directory}
2540 is not given, the value of the @env{HOME} shell variable is used. If the
2541 shell variable @env{CDPATH} exists, it is used as a search path. If
2542 @var{directory} begins with a slash, @env{CDPATH} is not used.
2543 The @option{-P} option means
2544 to not follow symbolic links; symbolic links are followed by default
2545 or with the @option{-L} option.
2546 If @var{directory} is @samp{-}, it is equivalent to @env{$OLDPWD}.
2547 The return status is zero if the directory is successfully changed,
2555 Resume the next iteration of an enclosing @code{for}, @code{while},
2556 @code{until}, or @code{select} loop.
2557 If @var{n} is supplied, the execution of the @var{n}th enclosing loop
2559 @var{n} must be greater than or equal to 1.
2560 The return status is zero unless @var{n} is not greater than or equal to 1.
2565 eval [@var{arguments}]
2567 The arguments are concatenated together into a single command, which is
2568 then read and executed, and its exit status returned as the exit status
2570 If there are no arguments or only empty arguments, the return status is
2576 exec [-cl] [-a @var{name}] [@var{command} [@var{arguments}]]
2579 is supplied, it replaces the shell without creating a new process.
2580 If the @option{-l} option is supplied, the shell places a dash at the
2581 beginning of the zeroth arg passed to @var{command}.
2582 This is what the @code{login} program does.
2583 The @option{-c} option causes @var{command} to be executed with an empty
2585 If @option{-a} is supplied, the shell passes @var{name} as the zeroth
2586 argument to @var{command}.
2587 If no @var{command} is specified, redirections may be used to affect
2588 the current shell environment. If there are no redirection errors, the
2589 return status is zero; otherwise the return status is non-zero.
2596 Exit the shell, returning a status of @var{n} to the shell's parent.
2597 If @var{n} is omitted, the exit status is that of the last command executed.
2598 Any trap on @code{EXIT} is executed before the shell terminates.
2603 export [-fn] [-p] [@var{name}[=@var{value}]]
2605 Mark each @var{name} to be passed to child processes
2606 in the environment. If the @option{-f} option is supplied, the @var{name}s
2607 refer to shell functions; otherwise the names refer to shell variables.
2608 The @option{-n} option means to no longer mark each @var{name} for export.
2609 If no @var{names} are supplied, or if the @option{-p} option is given, a
2610 list of exported names is displayed.
2611 The @option{-p} option displays output in a form that may be reused as input.
2612 The return status is zero unless an invalid option is supplied, one of
2613 the names is not a valid shell variable name, or @option{-f} is supplied
2614 with a name that is not a shell function.
2619 getopts @var{optstring} @var{name} [@var{args}]
2621 @code{getopts} is used by shell scripts to parse positional parameters.
2622 @var{optstring} contains the option characters to be recognized; if a
2623 character is followed by a colon, the option is expected to have an
2624 argument, which should be separated from it by white space.
2625 The colon (@samp{:}) and question mark (@samp{?}) may not be
2626 used as option characters.
2627 Each time it is invoked, @code{getopts}
2628 places the next option in the shell variable @var{name}, initializing
2629 @var{name} if it does not exist,
2630 and the index of the next argument to be processed into the
2631 variable @env{OPTIND}.
2632 @env{OPTIND} is initialized to 1 each time the shell or a shell script
2634 When an option requires an argument,
2635 @code{getopts} places that argument into the variable @env{OPTARG}.
2636 The shell does not reset @env{OPTIND} automatically; it must be manually
2637 reset between multiple calls to @code{getopts} within the same shell
2638 invocation if a new set of parameters is to be used.
2640 When the end of options is encountered, @code{getopts} exits with a
2641 return value greater than zero.
2642 @env{OPTIND} is set to the index of the first non-option argument,
2643 and @code{name} is set to @samp{?}.
2646 normally parses the positional parameters, but if more arguments are
2647 given in @var{args}, @code{getopts} parses those instead.
2649 @code{getopts} can report errors in two ways. If the first character of
2650 @var{optstring} is a colon, @var{silent}
2651 error reporting is used. In normal operation diagnostic messages
2652 are printed when invalid options or missing option arguments are
2654 If the variable @env{OPTERR}
2655 is set to 0, no error messages will be displayed, even if the first
2656 character of @code{optstring} is not a colon.
2658 If an invalid option is seen,
2659 @code{getopts} places @samp{?} into @var{name} and, if not silent,
2660 prints an error message and unsets @env{OPTARG}.
2661 If @code{getopts} is silent, the option character found is placed in
2662 @env{OPTARG} and no diagnostic message is printed.
2664 If a required argument is not found, and @code{getopts}
2665 is not silent, a question mark (@samp{?}) is placed in @var{name},
2666 @code{OPTARG} is unset, and a diagnostic message is printed.
2667 If @code{getopts} is silent, then a colon (@samp{:}) is placed in
2668 @var{name} and @env{OPTARG} is set to the option character found.
2673 hash [-'r] [-p @var{filename}] [-dt] [@var{name}]
2675 Remember the full pathnames of commands specified as @var{name} arguments,
2676 so they need not be searched for on subsequent invocations.
2677 The commands are found by searching through the directories listed in
2679 The @option{-p} option inhibits the path search, and @var{filename} is
2680 used as the location of @var{name}.
2681 The @option{-r} option causes the shell to forget all remembered locations.
2682 The @option{-d} option causes the shell to forget the remembered location
2684 If the @option{-t} option is supplied, the full pathname to which each
2685 @var{name} corresponds is printed. If multiple @var{name} arguments are
2686 supplied with @option{-t} the @var{name} is printed before the hashed
2688 The @option{-l} option causes output to be displayed in a format
2689 that may be reused as input.
2690 If no arguments are given, or if only @option{-l} is supplied,
2691 information about remembered commands is printed.
2692 The return status is zero unless a @var{name} is not found or an invalid
2700 Print the absolute pathname of the current working directory.
2701 If the @option{-P} option is supplied, the pathname printed will not
2702 contain symbolic links.
2703 If the @option{-L} option is supplied, the pathname printed may contain
2705 The return status is zero unless an error is encountered while
2706 determining the name of the current directory or an invalid option
2712 readonly [-apf] [@var{name}] @dots{}
2714 Mark each @var{name} as readonly.
2715 The values of these names may not be changed by subsequent assignment.
2716 If the @option{-f} option is supplied, each @var{name} refers to a shell
2718 The @option{-a} option means each @var{name} refers to an array variable.
2719 If no @var{name} arguments are given, or if the @option{-p}
2720 option is supplied, a list of all readonly names is printed.
2721 The @option{-p} option causes output to be displayed in a format that
2722 may be reused as input.
2723 The return status is zero unless an invalid option is supplied, one of
2724 the @var{name} arguments is not a valid shell variable or function name,
2725 or the @option{-f} option is supplied with a name that is not a shell function.
2732 Cause a shell function to exit with the return value @var{n}.
2733 If @var{n} is not supplied, the return value is the exit status of the
2734 last command executed in the function.
2735 This may also be used to terminate execution of a script being executed
2736 with the @code{.} (or @code{source}) builtin, returning either @var{n} or
2737 the exit status of the last command executed within the script as the exit
2738 status of the script.
2739 The return status is non-zero if @code{return} is used outside a function
2740 and not during the execution of a script by @code{.} or @code{source}.
2747 Shift the positional parameters to the left by @var{n}.
2748 The positional parameters from @var{n}+1 @dots{} @code{$#} are
2749 renamed to @code{$1} @dots{} @code{$#}-@var{n}+1.
2750 Parameters represented by the numbers @code{$#} to @var{n}+1 are unset.
2751 @var{n} must be a non-negative number less than or equal to @code{$#}.
2752 If @var{n} is zero or greater than @code{$#}, the positional parameters
2754 If @var{n} is not supplied, it is assumed to be 1.
2755 The return status is zero unless @var{n} is greater than @code{$#} or
2756 less than zero, non-zero otherwise.
2762 Evaluate a conditional expression @var{expr}.
2763 Each operator and operand must be a separate argument.
2764 Expressions are composed of the primaries described below in
2765 @ref{Bash Conditional Expressions}.
2767 When the @code{[} form is used, the last argument to the command must
2770 Expressions may be combined using the following operators, listed in
2771 decreasing order of precedence.
2775 True if @var{expr} is false.
2777 @item ( @var{expr} )
2778 Returns the value of @var{expr}.
2779 This may be used to override the normal precedence of operators.
2781 @item @var{expr1} -a @var{expr2}
2782 True if both @var{expr1} and @var{expr2} are true.
2784 @item @var{expr1} -o @var{expr2}
2785 True if either @var{expr1} or @var{expr2} is true.
2788 The @code{test} and @code{[} builtins evaluate conditional
2789 expressions using a set of rules based on the number of arguments.
2793 The expression is false.
2796 The expression is true if and only if the argument is not null.
2799 If the first argument is @samp{!}, the expression is true if and
2800 only if the second argument is null.
2801 If the first argument is one of the unary conditional operators
2802 (@pxref{Bash Conditional Expressions}), the expression
2803 is true if the unary test is true.
2804 If the first argument is not a valid unary operator, the expression is
2808 If the second argument is one of the binary conditional
2809 operators (@pxref{Bash Conditional Expressions}), the
2810 result of the expression is the result of the binary test using the
2811 first and third arguments as operands.
2812 If the first argument is @samp{!}, the value is the negation of
2813 the two-argument test using the second and third arguments.
2814 If the first argument is exactly @samp{(} and the third argument is
2815 exactly @samp{)}, the result is the one-argument test of the second
2817 Otherwise, the expression is false.
2818 The @samp{-a} and @samp{-o} operators are considered binary operators
2822 If the first argument is @samp{!}, the result is the negation of
2823 the three-argument expression composed of the remaining arguments.
2824 Otherwise, the expression is parsed and evaluated according to
2825 precedence using the rules listed above.
2827 @item 5 or more arguments
2828 The expression is parsed and evaluated according to precedence
2829 using the rules listed above.
2837 Print out the user and system times used by the shell and its children.
2838 The return status is zero.
2843 trap [-lp] [@var{arg}] [@var{sigspec} @dots{}]
2845 The commands in @var{arg} are to be read and executed when the
2846 shell receives signal @var{sigspec}. If @var{arg} is absent or
2847 equal to @samp{-}, all specified signals are reset to the values
2848 they had when the shell was started.
2849 If @var{arg} is the null string, then the signal specified by
2850 each @var{sigspec} is ignored by the shell and commands it invokes.
2851 If @var{arg} is not present and @option{-p} has been supplied,
2852 the shell displays the trap commands associated with each @var{sigspec}.
2853 If no arguments are supplied, or
2854 only @option{-p} is given, @code{trap} prints the list of commands
2855 associated with each signal number in a form that may be reused as
2857 Each @var{sigspec} is either a signal name such as @code{SIGINT} (with
2858 or without the @code{SIG} prefix) or a signal number.
2860 is @code{0} or @code{EXIT}, @var{arg} is executed when the shell exits.
2861 If a @var{sigspec} is @code{DEBUG}, the command @var{arg} is executed
2862 after every simple command.
2863 If a @var{sigspec} is @code{ERR}, the command @var{arg}
2864 is executed whenever a simple command has a non-zero exit status.
2865 The @code{ERR} trap is not executed if the failed command is part of an
2866 @code{until} or @code{while} loop, part of an @code{if} statement,
2867 part of a @code{&&} or @code{||} list, or if the command's return
2868 status is being inverted using @code{!}.
2869 The @option{-l} option causes the shell to print a list of signal names
2870 and their corresponding numbers.
2872 Signals ignored upon entry to the shell cannot be trapped or reset.
2873 Trapped signals are reset to their original values in a child
2874 process when it is created.
2876 The return status is zero unless a @var{sigspec} does not specify a
2882 umask [-p] [-S] [@var{mode}]
2884 Set the shell process's file creation mask to @var{mode}. If
2885 @var{mode} begins with a digit, it is interpreted as an octal number;
2886 if not, it is interpreted as a symbolic mode mask similar
2887 to that accepted by the @code{chmod} command. If @var{mode} is
2888 omitted, the current value of the mask is printed. If the @option{-S}
2889 option is supplied without a @var{mode} argument, the mask is printed
2890 in a symbolic format.
2891 If the @option{-p} option is supplied, and @var{mode}
2892 is omitted, the output is in a form that may be reused as input.
2893 The return status is zero if the mode is successfully changed or if
2894 no @var{mode} argument is supplied, and non-zero otherwise.
2896 Note that when the mode is interpreted as an octal number, each number
2897 of the umask is subtracted from @code{7}. Thus, a umask of @code{022}
2898 results in permissions of @code{755}.
2903 unset [-fv] [@var{name}]
2905 Each variable or function @var{name} is removed.
2906 If no options are supplied, or the @option{-v} option is given, each
2907 @var{name} refers to a shell variable.
2908 If the @option{-f} option is given, the @var{name}s refer to shell
2909 functions, and the function definition is removed.
2910 Readonly variables and functions may not be unset.
2911 The return status is zero unless a @var{name} does not exist or is
2916 @section Bash Builtin Commands
2918 This section describes builtin commands which are unique to
2919 or have been extended in Bash.
2920 Some of these commands are specified in the @sc{posix} 1003.2 standard.
2927 alias [@code{-p}] [@var{name}[=@var{value}] @dots{}]
2930 Without arguments or with the @option{-p} option, @code{alias} prints
2931 the list of aliases on the standard output in a form that allows
2932 them to be reused as input.
2933 If arguments are supplied, an alias is defined for each @var{name}
2934 whose @var{value} is given. If no @var{value} is given, the name
2935 and value of the alias is printed.
2936 Aliases are described in @ref{Aliases}.
2941 bind [-m @var{keymap}] [-lpsvPSV]
2942 bind [-m @var{keymap}] [-q @var{function}] [-u @var{function}] [-r @var{keyseq}]
2943 bind [-m @var{keymap}] -f @var{filename}
2944 bind [-m @var{keymap}] -x @var{keyseq:shell-command}
2945 bind [-m @var{keymap}] @var{keyseq:function-name}
2946 bind @var{readline-command}
2949 Display current Readline (@pxref{Command Line Editing})
2950 key and function bindings,
2951 bind a key sequence to a Readline function or macro,
2952 or set a Readline variable.
2953 Each non-option argument is a command as it would appear in a
2954 a Readline initialization file (@pxref{Readline Init File}),
2955 but each binding or command must be passed as a separate argument; e.g.,
2956 @samp{"\C-x\C-r":re-read-init-file}.
2957 Options, if supplied, have the following meanings:
2960 @item -m @var{keymap}
2961 Use @var{keymap} as the keymap to be affected by
2962 the subsequent bindings. Acceptable @var{keymap}
2965 @code{emacs-standard},
2970 @code{vi-command}, and
2972 @code{vi} is equivalent to @code{vi-command};
2973 @code{emacs} is equivalent to @code{emacs-standard}.
2976 List the names of all Readline functions.
2979 Display Readline function names and bindings in such a way that they
2980 can be used as input or in a Readline initialization file.
2983 List current Readline function names and bindings.
2986 Display Readline variable names and values in such a way that they
2987 can be used as input or in a Readline initialization file.
2990 List current Readline variable names and values.
2993 Display Readline key sequences bound to macros and the strings they output
2994 in such a way that they can be used as input or in a Readline
2995 initialization file.
2998 Display Readline key sequences bound to macros and the strings they output.
3000 @item -f @var{filename}
3001 Read key bindings from @var{filename}.
3003 @item -q @var{function}
3004 Query about which keys invoke the named @var{function}.
3006 @item -u @var{function}
3007 Unbind all keys bound to the named @var{function}.
3009 @item -r @var{keyseq}
3010 Remove any current binding for @var{keyseq}.
3012 @item -x @var{keyseq:shell-command}
3013 Cause @var{shell-command} to be executed whenever @var{keyseq} is
3019 The return status is zero unless an invalid option is supplied or an
3025 builtin [@var{shell-builtin} [@var{args}]]
3027 Run a shell builtin, passing it @var{args}, and return its exit status.
3028 This is useful when defining a shell function with the same
3029 name as a shell builtin, retaining the functionality of the builtin within
3031 The return status is non-zero if @var{shell-builtin} is not a shell
3037 command [-pVv] @var{command} [@var{arguments} @dots{}]
3039 Runs @var{command} with @var{arguments} ignoring any shell function
3040 named @var{command}.
3041 Only shell builtin commands or commands found by searching the
3042 @env{PATH} are executed.
3043 If there is a shell function named @code{ls}, running @samp{command ls}
3044 within the function will execute the external command @code{ls}
3045 instead of calling the function recursively.
3046 The @option{-p} option means to use a default value for @env{PATH}
3047 that is guaranteed to find all of the standard utilities.
3048 The return status in this case is 127 if @var{command} cannot be
3049 found or an error occurred, and the exit status of @var{command}
3052 If either the @option{-V} or @option{-v} option is supplied, a
3053 description of @var{command} is printed. The @option{-v} option
3054 causes a single word indicating the command or file name used to
3055 invoke @var{command} to be displayed; the @option{-V} option produces
3056 a more verbose description. In this case, the return status is
3057 zero if @var{command} is found, and non-zero if not.
3062 declare [-afFirtx] [-p] [@var{name}[=@var{value}]]
3065 Declare variables and give them attributes. If no @var{name}s
3066 are given, then display the values of variables instead.
3068 The @option{-p} option will display the attributes and values of each
3069 @var{name}. When @option{-p} is used, additional options are ignored.
3070 The @option{-F} option inhibits the display of function definitions;
3071 only the function name and attributes are printed. @option{-F} implies
3072 @option{-f}. The following options can be used to restrict output
3073 to variables with the specified attributes or to give variables
3078 Each @var{name} is an array variable (@pxref{Arrays}).
3081 Use function names only.
3084 The variable is to be treated as
3085 an integer; arithmetic evaluation (@pxref{Shell Arithmetic}) is
3086 performed when the variable is assigned a value.
3089 Make @var{name}s readonly. These names cannot then be assigned values
3090 by subsequent assignment statements or unset.
3093 Give each @var{name} the @code{trace} attribute.
3094 Traced functions inherit the @code{DEBUG} trap from the calling shell.
3095 The trace attribute has no special meaning for variables.
3098 Mark each @var{name} for export to subsequent commands via
3102 Using @samp{+} instead of @samp{-} turns off the attribute instead.
3103 When used in a function, @code{declare} makes each @var{name} local,
3104 as with the @code{local} command.
3106 The return status is zero unless an invalid option is encountered,
3107 an attempt is made to define a function using @samp{-f foo=bar},
3108 an attempt is made to assign a value to a readonly variable,
3109 an attempt is made to assign a value to an array variable without
3110 using the compound assignment syntax (@pxref{Arrays}),
3111 one of the @var{names} is not a valid shell variable name,
3112 an attempt is made to turn off readonly status for a readonly variable,
3113 an attempt is made to turn off array status for an array variable,
3114 or an attempt is made to display a non-existent function with @option{-f}.
3119 echo [-neE] [@var{arg} @dots{}]
3121 Output the @var{arg}s, separated by spaces, terminated with a
3123 The return status is always 0.
3124 If @option{-n} is specified, the trailing newline is suppressed.
3125 If the @option{-e} option is given, interpretation of the following
3126 backslash-escaped characters is enabled.
3127 The @option{-E} option disables the interpretation of these escape characters,
3128 even on systems where they are interpreted by default.
3129 The @code{xpg_echo} shell option may be used to
3130 dynamically determine whether or not @code{echo} expands these
3131 escape characters by default.
3132 @code{echo} interprets the following escape sequences:
3139 suppress trailing newline
3155 the eight-bit character whose value is the octal value @var{nnn}
3156 (zero to three octal digits)
3158 the eight-bit character whose value is the octal value @var{nnn}
3159 (one to three octal digits)
3161 the eight-bit character whose value is the hexadecimal value @var{HH}
3162 (one or two hex digits)
3168 enable [-n] [-p] [-f @var{filename}] [-ads] [@var{name} @dots{}]
3170 Enable and disable builtin shell commands.
3171 Disabling a builtin allows a disk command which has the same name
3172 as a shell builtin to be executed without specifying a full pathname,
3173 even though the shell normally searches for builtins before disk commands.
3174 If @option{-n} is used, the @var{name}s become disabled. Otherwise
3175 @var{name}s are enabled. For example, to use the @code{test} binary
3176 found via @env{$PATH} instead of the shell builtin version, type
3177 @samp{enable -n test}.
3179 If the @option{-p} option is supplied, or no @var{name} arguments appear,
3180 a list of shell builtins is printed. With no other arguments, the list
3181 consists of all enabled shell builtins.
3182 The @option{-a} option means to list
3183 each builtin with an indication of whether or not it is enabled.
3185 The @option{-f} option means to load the new builtin command @var{name}
3186 from shared object @var{filename}, on systems that support dynamic loading.
3187 The @option{-d} option will delete a builtin loaded with @option{-f}.
3189 If there are no options, a list of the shell builtins is displayed.
3190 The @option{-s} option restricts @code{enable} to the @sc{posix} special
3191 builtins. If @option{-s} is used with @option{-f}, the new builtin becomes
3192 a special builtin (@pxref{Special Builtins}).
3194 The return status is zero unless a @var{name} is not a shell builtin
3195 or there is an error loading a new builtin from a shared object.
3200 help [-s] [@var{pattern}]
3202 Display helpful information about builtin commands.
3203 If @var{pattern} is specified, @code{help} gives detailed help
3204 on all commands matching @var{pattern}, otherwise a list of
3205 the builtins is printed.
3206 The @option{-s} option restricts the information displayed to a short
3208 The return status is zero unless no command matches @var{pattern}.
3213 let @var{expression} [@var{expression}]
3215 The @code{let} builtin allows arithmetic to be performed on shell
3216 variables. Each @var{expression} is evaluated according to the
3217 rules given below in @ref{Shell Arithmetic}. If the
3218 last @var{expression} evaluates to 0, @code{let} returns 1;
3219 otherwise 0 is returned.
3224 local [@var{option}] @var{name}[=@var{value}]
3226 For each argument, a local variable named @var{name} is created,
3227 and assigned @var{value}.
3228 The @var{option} can be any of the options accepted by @code{declare}.
3229 @code{local} can only be used within a function; it makes the variable
3230 @var{name} have a visible scope restricted to that function and its
3231 children. The return status is zero unless @code{local} is used outside
3232 a function, an invalid @var{name} is supplied, or @var{name} is a
3240 Exit a login shell, returning a status of @var{n} to the shell's
3246 @code{printf} @var{format} [@var{arguments}]
3248 Write the formatted @var{arguments} to the standard output under the
3249 control of the @var{format}.
3250 The @var{format} is a character string which contains three types of objects:
3251 plain characters, which are simply copied to standard output, character
3252 escape sequences, which are converted and copied to the standard output, and
3253 format specifications, each of which causes printing of the next successive
3255 In addition to the standard @code{printf(1)} formats, @samp{%b} causes
3256 @code{printf} to expand backslash escape sequences in the corresponding
3257 @var{argument}, and @samp{%q} causes @code{printf} to output the
3258 corresponding @var{argument} in a format that can be reused as shell input.
3260 The @var{format} is reused as necessary to consume all of the @var{arguments}.
3261 If the @var{format} requires more @var{arguments} than are supplied, the
3262 extra format specifications behave as if a zero value or null string, as
3263 appropriate, had been supplied. The return value is zero on success,
3264 non-zero on failure.
3269 read [-ers] [-a @var{aname}] [-d @var{delim}] [-n @var{nchars}] [-p @var{prompt}] [-t @var{timeout}] [-u @var{fd}] [@var{name} @dots{}]
3271 One line is read from the standard input, or from the file descriptor
3272 @var{fd} supplied as an argument to the @option{-u} option, and the first word
3273 is assigned to the first @var{name}, the second word to the second @var{name},
3274 and so on, with leftover words and their intervening separators assigned
3275 to the last @var{name}.
3276 If there are fewer words read from the input stream than names,
3277 the remaining names are assigned empty values.
3278 The characters in the value of the @env{IFS} variable
3279 are used to split the line into words.
3280 The backslash character @samp{\} may be used to remove any special
3281 meaning for the next character read and for line continuation.
3282 If no names are supplied, the line read is assigned to the
3283 variable @env{REPLY}.
3284 The return code is zero, unless end-of-file is encountered, @code{read}
3285 times out, or an invalid file descriptor is supplied as the argument to
3287 Options, if supplied, have the following meanings:
3290 @item -a @var{aname}
3291 The words are assigned to sequential indices of the array variable
3292 @var{aname}, starting at 0.
3293 All elements are removed from @var{aname} before the assignment.
3294 Other @var{name} arguments are ignored.
3296 @item -d @var{delim}
3297 The first character of @var{delim} is used to terminate the input line,
3298 rather than newline.
3301 Readline (@pxref{Command Line Editing}) is used to obtain the line.
3303 @item -n @var{nchars}
3304 @code{read} returns after reading @var{nchars} characters rather than
3305 waiting for a complete line of input.
3307 @item -p @var{prompt}
3308 Display @var{prompt}, without a trailing newline, before attempting
3310 The prompt is displayed only if input is coming from a terminal.
3313 If this option is given, backslash does not act as an escape character.
3314 The backslash is considered to be part of the line.
3315 In particular, a backslash-newline pair may not be used as a line
3319 Silent mode. If input is coming from a terminal, characters are
3322 @item -t @var{timeout}
3323 Cause @code{read} to time out and return failure if a complete line of
3324 input is not read within @var{timeout} seconds.
3325 This option has no effect if @code{read} is not reading input from the
3329 Read input from file descriptor @var{fd}.
3336 shopt [-pqsu] [-o] [@var{optname} @dots{}]
3338 Toggle the values of variables controlling optional shell behavior.
3339 With no options, or with the @option{-p} option, a list of all settable
3340 options is displayed, with an indication of whether or not each is set.
3341 The @option{-p} option causes output to be displayed in a form that
3342 may be reused as input.
3343 Other options have the following meanings:
3347 Enable (set) each @var{optname}.
3350 Disable (unset) each @var{optname}.
3353 Suppresses normal output; the return status
3354 indicates whether the @var{optname} is set or unset.
3355 If multiple @var{optname} arguments are given with @option{-q},
3356 the return status is zero if all @var{optnames} are enabled;
3360 Restricts the values of
3361 @var{optname} to be those defined for the @option{-o} option to the
3362 @code{set} builtin (@pxref{The Set Builtin}).
3365 If either @option{-s} or @option{-u}
3366 is used with no @var{optname} arguments, the display is limited to
3367 those options which are set or unset, respectively.
3369 Unless otherwise noted, the @code{shopt} options are disabled (off)
3372 The return status when listing options is zero if all @var{optnames}
3373 are enabled, non-zero otherwise. When setting or unsetting options,
3374 the return status is zero unless an @var{optname} is not a valid shell
3377 The list of @code{shopt} options is:
3380 If this is set, an argument to the @code{cd}
3381 builtin command that
3382 is not a directory is assumed to be the name of a variable whose
3383 value is the directory to change to.
3386 If set, minor errors in the spelling of a directory component in a
3387 @code{cd} command will be corrected.
3388 The errors checked for are transposed characters,
3389 a missing character, and a character too many.
3390 If a correction is found, the corrected path is printed,
3391 and the command proceeds.
3392 This option is only used by interactive shells.
3395 If this is set, Bash checks that a command found in the hash
3396 table exists before trying to execute it. If a hashed command no
3397 longer exists, a normal path search is performed.
3400 If set, Bash checks the window size after each command
3401 and, if necessary, updates the values of
3402 @env{LINES} and @env{COLUMNS}.
3406 attempts to save all lines of a multiple-line
3407 command in the same history entry. This allows
3408 easy re-editing of multi-line commands.
3411 If set, Bash includes filenames beginning with a `.' in
3412 the results of filename expansion.
3415 If this is set, a non-interactive shell will not exit if
3416 it cannot execute the file specified as an argument to the @code{exec}
3417 builtin command. An interactive shell does not exit if @code{exec}
3420 @item expand_aliases
3421 If set, aliases are expanded as described below under Aliases,
3423 This option is enabled by default for interactive shells.
3426 If set, the extended pattern matching features described above
3427 (@pxref{Pattern Matching}) are enabled.
3430 If set, the history list is appended to the file named by the value
3431 of the @env{HISTFILE}
3432 variable when the shell exits, rather than overwriting the file.
3435 If set, and Readline
3436 is being used, a user is given the opportunity to re-edit a
3437 failed history substitution.
3440 If set, and Readline
3441 is being used, the results of history substitution are not immediately
3442 passed to the shell parser. Instead, the resulting line is loaded into
3443 the Readline editing buffer, allowing further modification.
3446 If set, and Readline is being used, Bash will attempt to perform
3447 hostname completion when a word containing a @samp{@@} is being
3448 completed (@pxref{Commands For Completion}). This option is enabled
3452 If set, Bash will send @code{SIGHUP} to all jobs when an interactive
3453 login shell exits (@pxref{Signals}).
3455 @item interactive_comments
3456 Allow a word beginning with @samp{#}
3457 to cause that word and all remaining characters on that
3458 line to be ignored in an interactive shell.
3459 This option is enabled by default.
3462 If enabled, and the @code{cmdhist}
3463 option is enabled, multi-line commands are saved to the history with
3464 embedded newlines rather than using semicolon separators where possible.
3467 The shell sets this option if it is started as a login shell
3468 (@pxref{Invoking Bash}).
3469 The value may not be changed.
3472 If set, and a file that Bash is checking for mail has been
3473 accessed since the last time it was checked, the message
3474 @code{"The mail in @var{mailfile} has been read"} is displayed.
3476 @item no_empty_cmd_completion
3477 If set, and Readline is being used, Bash will not attempt to search
3478 the @env{PATH} for possible completions when completion is attempted
3482 If set, Bash matches filenames in a case-insensitive fashion when
3483 performing filename expansion.
3486 If set, Bash allows filename patterns which match no
3487 files to expand to a null string, rather than themselves.
3490 If set, the programmable completion facilities
3491 (@pxref{Programmable Completion}) are enabled.
3492 This option is enabled by default.
3495 If set, prompt strings undergo variable and parameter expansion after
3496 being expanded (@pxref{Printing a Prompt}).
3497 This option is enabled by default.
3499 @item restricted_shell
3500 The shell sets this option if it is started in restricted mode
3501 (@pxref{The Restricted Shell}).
3502 The value may not be changed.
3503 This is not reset when the startup files are executed, allowing
3504 the startup files to discover whether or not a shell is restricted.
3507 If this is set, the @code{shift}
3508 builtin prints an error message when the shift count exceeds the
3509 number of positional parameters.
3512 If set, the @code{source} builtin uses the value of @env{PATH}
3513 to find the directory containing the file supplied as an argument.
3514 This option is enabled by default.
3517 If set, the @code{echo} builtin expands backslash-escape sequences
3523 The return status when listing options is zero if all @var{optnames}
3524 are enabled, non-zero otherwise.
3525 When setting or unsetting options, the return status is zero unless an
3526 @var{optname} is not a valid shell option.
3531 source @var{filename}
3533 A synonym for @code{.} (@pxref{Bourne Shell Builtins}).
3538 type [-afptP] [@var{name} @dots{}]
3540 For each @var{name}, indicate how it would be interpreted if used as a
3543 If the @option{-t} option is used, @code{type} prints a single word
3544 which is one of @samp{alias}, @samp{function}, @samp{builtin},
3545 @samp{file} or @samp{keyword},
3546 if @var{name} is an alias, shell function, shell builtin,
3547 disk file, or shell reserved word, respectively.
3548 If the @var{name} is not found, then nothing is printed, and
3549 @code{type} returns a failure status.
3551 If the @option{-p} option is used, @code{type} either returns the name
3552 of the disk file that would be executed, or nothing if @option{-t}
3553 would not return @samp{file}.
3555 The @option{-P} option forces a path search for each @var{name}, even if
3556 @option{-t} would not return @samp{file}.
3558 If a command is hashed, @option{-p} and @option{-P} print the hashed value,
3559 not necessarily the file that appears first in @code{$PATH}.
3561 If the @option{-a} option is used, @code{type} returns all of the places
3562 that contain an executable named @var{file}.
3563 This includes aliases and functions, if and only if the @option{-p} option
3566 If the @option{-f} option is used, @code{type} does not attempt to find
3567 shell functions, as with the @code{command} builtin.
3569 The return status is zero if any of the @var{names} are found, non-zero
3575 typeset [-afFrxi] [-p] [@var{name}[=@var{value}]]
3577 The @code{typeset} command is supplied for compatibility with the Korn
3578 shell; however, it has been deprecated in favor of the @code{declare}
3584 ulimit [-acdflmnpstuvSH] [@var{limit}]
3586 @code{ulimit} provides control over the resources available to processes
3587 started by the shell, on systems that allow such control. If an
3588 option is given, it is interpreted as follows:
3591 Change and report the soft limit associated with a resource.
3594 Change and report the hard limit associated with a resource.
3597 All current limits are reported.
3600 The maximum size of core files created.
3603 The maximum size of a process's data segment.
3606 The maximum size of files created by the shell.
3609 The maximum size that may be locked into memory.
3612 The maximum resident set size.
3615 The maximum number of open file descriptors.
3618 The pipe buffer size.
3621 The maximum stack size.
3624 The maximum amount of cpu time in seconds.
3627 The maximum number of processes available to a single user.
3630 The maximum amount of virtual memory available to the process.
3634 If @var{limit} is given, it is the new value of the specified resource;
3635 the special @var{limit} values @code{hard}, @code{soft}, and
3636 @code{unlimited} stand for the current hard limit, the current soft limit,
3637 and no limit, respectively.
3638 Otherwise, the current value of the soft limit for the specified resource
3639 is printed, unless the @option{-H} option is supplied.
3640 When setting new limits, if neither @option{-H} nor @option{-S} is supplied,
3641 both the hard and soft limits are set.
3642 If no option is given, then @option{-f} is assumed. Values are in 1024-byte
3643 increments, except for @option{-t}, which is in seconds, @option{-p},
3644 which is in units of 512-byte blocks, and @option{-n} and @option{-u}, which
3645 are unscaled values.
3647 The return status is zero unless an invalid option or argument is supplied,
3648 or an error occurs while setting a new limit.
3653 unalias [-a] [@var{name} @dots{} ]
3656 Remove each @var{name} from the list of aliases. If @option{-a} is
3657 supplied, all aliases are removed.
3658 Aliases are described in @ref{Aliases}.
3662 @node The Set Builtin
3663 @section The Set Builtin
3665 This builtin is so complicated that it deserves its own section.
3671 set [--abefhkmnptuvxBCHP] [-o @var{option}] [@var{argument} @dots{}]
3674 If no options or arguments are supplied, @code{set} displays the names
3675 and values of all shell variables and functions, sorted according to the
3676 current locale, in a format that may be reused as input.
3678 When options are supplied, they set or unset shell attributes.
3679 Options, if specified, have the following meanings:
3683 Mark variables and function which are modified or created for export
3684 to the environment of subsequent commands.
3687 Cause the status of terminated background jobs to be reported
3688 immediately, rather than before printing the next primary prompt.
3691 Exit immediately if a simple command (@pxref{Simple Commands}) exits
3692 with a non-zero status, unless the command that fails is part of an
3693 @code{until} or @code{while} loop, part of an @code{if} statement,
3694 part of a @code{&&} or @code{||} list, or if the command's return
3695 status is being inverted using @code{!}.
3696 A trap on @code{ERR}, if set, is executed before the shell exits.
3699 Disable file name generation (globbing).
3702 Locate and remember (hash) commands as they are looked up for execution.
3703 This option is enabled by default.
3706 All arguments in the form of assignment statements are placed
3707 in the environment for a command, not just those that precede
3711 Job control is enabled (@pxref{Job Control}).
3714 Read commands but do not execute them; this may be used to check a
3715 script for syntax errors.
3716 This option is ignored by interactive shells.
3718 @item -o @var{option-name}
3720 Set the option corresponding to @var{option-name}:
3730 Use an @code{emacs}-style line editing interface (@pxref{Command Line Editing}).
3742 Enable command history, as described in @ref{Bash History Facilities}.
3743 This option is on by default in interactive shells.
3746 An interactive shell will not exit upon reading EOF.
3779 Change the behavior of Bash where the default operation differs
3780 from the @sc{posix} 1003.2 standard to match the standard
3781 (@pxref{Bash POSIX Mode}).
3782 This is intended to make Bash behave as a strict superset of that
3792 Use a @code{vi}-style line editing interface.
3799 Turn on privileged mode.
3800 In this mode, the @env{$BASH_ENV} and @env{$ENV} files are not
3801 processed, shell functions are not inherited from the environment,
3802 and the @env{SHELLOPTS} variable, if it appears in the environment,
3804 If the shell is started with the effective user (group) id not equal to the
3805 real user (group) id, and the @code{-p} option is not supplied, these actions
3806 are taken and the effective user id is set to the real user id.
3807 If the @code{-p} option is supplied at startup, the effective user id is
3809 Turning this option off causes the effective user
3810 and group ids to be set to the real user and group ids.
3813 Exit after reading and executing one command.
3816 Treat unset variables as an error when performing parameter expansion.
3817 An error message will be written to the standard error, and a non-interactive
3821 Print shell input lines as they are read.
3824 Print a trace of simple commands and their arguments after they are
3825 expanded and before they are executed.
3828 The shell will perform brace expansion (@pxref{Brace Expansion}).
3829 This option is on by default.
3832 Prevent output redirection using @samp{>}, @samp{>&}, and @samp{<>}
3833 from overwriting existing files.
3836 Enable @samp{!} style history substitution (@pxref{History Interaction}).
3837 This option is on by default for interactive shells.
3840 If set, do not follow symbolic links when performing commands such as
3841 @code{cd} which change the current directory. The physical directory
3842 is used instead. By default, Bash follows
3843 the logical chain of directories when performing commands
3844 which change the current directory.
3846 For example, if @file{/usr/sys} is a symbolic link to @file{/usr/local/sys}
3849 $ cd /usr/sys; echo $PWD
3856 If @code{set -P} is on, then:
3858 $ cd /usr/sys; echo $PWD
3865 If no arguments follow this option, then the positional parameters are
3866 unset. Otherwise, the positional parameters are set to the
3867 @var{arguments}, even if some of them begin with a @samp{-}.
3870 Signal the end of options, cause all remaining @var{arguments}
3871 to be assigned to the positional parameters. The @option{-x}
3872 and @option{-v} options are turned off.
3873 If there are no arguments, the positional parameters remain unchanged.
3876 Using @samp{+} rather than @samp{-} causes these options to be
3877 turned off. The options can also be used upon invocation of the
3878 shell. The current set of options may be found in @code{$-}.
3880 The remaining N @var{arguments} are positional parameters and are
3881 assigned, in order, to @code{$1}, @code{$2}, @dots{} @code{$N}.
3882 The special parameter @code{#} is set to N.
3884 The return status is always zero unless an invalid option is supplied.
3887 @node Special Builtins
3888 @section Special Builtins
3889 @cindex special builtin
3891 For historical reasons, the @sc{posix} 1003.2 standard has classified
3892 several builtin commands as @emph{special}.
3893 When Bash is executing in @sc{posix} mode, the special builtins
3894 differ from other builtin commands in three respects:
3898 Special builtins are found before shell functions during command lookup.
3901 If a special builtin returns an error status, a non-interactive shell exits.
3904 Assignment statements preceding the command stay in effect in the shell
3905 environment after the command completes.
3908 When Bash is not executing in @sc{posix} mode, these builtins behave no
3909 differently than the rest of the Bash builtin commands.
3910 The Bash @sc{posix} mode is described in @ref{Bash POSIX Mode}.
3912 These are the @sc{posix} special builtins:
3914 @w{break : . continue eval exec exit export readonly return set}
3915 @w{shift trap unset}
3918 @node Shell Variables
3919 @chapter Shell Variables
3922 * Bourne Shell Variables:: Variables which Bash uses in the same way
3923 as the Bourne Shell.
3924 * Bash Variables:: List of variables that exist in Bash.
3927 This chapter describes the shell variables that Bash uses.
3928 Bash automatically assigns default values to a number of variables.
3930 @node Bourne Shell Variables
3931 @section Bourne Shell Variables
3933 Bash uses certain shell variables in the same way as the Bourne shell.
3934 In some cases, Bash assigns a default value to the variable.
3939 A colon-separated list of directories used as a search path for
3940 the @code{cd} builtin command.
3943 The current user's home directory; the default for the @code{cd} builtin
3945 The value of this variable is also used by tilde expansion
3946 (@pxref{Tilde Expansion}).
3949 A list of characters that separate fields; used when the shell splits
3950 words as part of expansion.
3953 If this parameter is set to a filename and the @env{MAILPATH} variable
3954 is not set, Bash informs the user of the arrival of mail in
3958 A colon-separated list of filenames which the shell periodically checks
3960 Each list entry can specify the message that is printed when new mail
3961 arrives in the mail file by separating the file name from the message with
3963 When used in the text of the message, @code{$_} expands to the name of
3964 the current mail file.
3967 The value of the last option argument processed by the @code{getopts} builtin.
3970 The index of the last option argument processed by the @code{getopts} builtin.
3973 A colon-separated list of directories in which the shell looks for
3977 The primary prompt string. The default value is @samp{\s-\v\$ }.
3978 @xref{Printing a Prompt}, for the complete list of escape
3979 sequences that are expanded before @env{PS1} is displayed.
3982 The secondary prompt string. The default value is @samp{> }.
3986 @node Bash Variables
3987 @section Bash Variables
3989 These variables are set or used by Bash, but other shells
3990 do not normally treat them specially.
3992 A few variables used by Bash are described in different chapters:
3993 variables for controlling the job control facilities
3994 (@pxref{Job Control Variables}).
3999 The full pathname used to execute the current instance of Bash.
4002 If this variable is set when Bash is invoked to execute a shell
4003 script, its value is expanded and used as the name of a startup file
4004 to read before executing the script. @xref{Bash Startup Files}.
4007 The version number of the current instance of Bash.
4010 A readonly array variable (@pxref{Arrays})
4011 whose members hold version information for this instance of Bash.
4012 The values assigned to the array members are as follows:
4016 @item BASH_VERSINFO[0]
4017 The major version number (the @var{release}).
4019 @item BASH_VERSINFO[1]
4020 The minor version number (the @var{version}).
4022 @item BASH_VERSINFO[2]
4025 @item BASH_VERSINFO[3]
4028 @item BASH_VERSINFO[4]
4029 The release status (e.g., @var{beta1}).
4031 @item BASH_VERSINFO[5]
4032 The value of @env{MACHTYPE}.
4037 Used by the @code{select} builtin command to determine the terminal width
4038 when printing selection lists. Automatically set upon receipt of a
4042 An index into @env{$@{COMP_WORDS@}} of the word containing the current
4044 This variable is available only in shell functions invoked by the
4045 programmable completion facilities (@pxref{Programmable Completion}).
4048 The current command line.
4049 This variable is available only in shell functions and external
4050 commands invoked by the
4051 programmable completion facilities (@pxref{Programmable Completion}).
4054 The index of the current cursor position relative to the beginning of
4055 the current command.
4056 If the current cursor position is at the end of the current command,
4057 the value of this variable is equal to @code{$@{#COMP_LINE@}}.
4058 This variable is available only in shell functions and external
4059 commands invoked by the
4060 programmable completion facilities (@pxref{Programmable Completion}).
4063 An array variable consisting of the individual
4064 words in the current command line.
4065 This variable is available only in shell functions invoked by the
4066 programmable completion facilities (@pxref{Programmable Completion}).
4069 An array variable from which Bash reads the possible completions
4070 generated by a shell function invoked by the programmable completion
4071 facility (@pxref{Programmable Completion}).
4074 An array variable containing the current contents of the directory stack.
4075 Directories appear in the stack in the order they are displayed by the
4076 @code{dirs} builtin.
4077 Assigning to members of this array variable may be used to modify
4078 directories already in the stack, but the @code{pushd} and @code{popd}
4079 builtins must be used to add and remove directories.
4080 Assignment to this variable will not change the current directory.
4081 If @env{DIRSTACK} is unset, it loses its special properties, even if
4082 it is subsequently reset.
4085 The numeric effective user id of the current user. This variable
4089 The editor used as a default by the @option{-e} option to the @code{fc}
4093 A colon-separated list of suffixes to ignore when performing
4094 filename completion.
4095 A file name whose suffix matches one of the entries in
4097 is excluded from the list of matched file names. A sample
4098 value is @samp{.o:~}
4101 The name of any currently-executing shell function.
4102 This variable exists only when a shell function is executing.
4103 Assignments to @env{FUNCNAME} have no effect and return an error status.
4104 If @env{FUNCNAME} is unset, it loses its special properties, even if
4105 it is subsequently reset.
4108 A colon-separated list of patterns defining the set of filenames to
4109 be ignored by filename expansion.
4110 If a filename matched by a filename expansion pattern also matches one
4111 of the patterns in @env{GLOBIGNORE}, it is removed from the list
4115 An array variable containing the list of groups of which the current
4117 Assignments to @env{GROUPS} have no effect and return an error status.
4118 If @env{GROUPS} is unset, it loses its special properties, even if it is
4122 Up to three characters which control history expansion, quick
4123 substitution, and tokenization (@pxref{History Interaction}).
4124 The first character is the
4125 @var{history expansion} character, that is, the character which signifies the
4126 start of a history expansion, normally @samp{!}. The second character is the
4127 character which signifies `quick substitution' when seen as the first
4128 character on a line, normally @samp{^}. The optional third character is the
4129 character which indicates that the remainder of the line is a comment when
4130 found as the first character of a word, usually @samp{#}. The history
4131 comment character causes history substitution to be skipped for the
4132 remaining words on the line. It does not necessarily cause the shell
4133 parser to treat the rest of the line as a comment.
4136 The history number, or index in the history list, of the current
4137 command. If @env{HISTCMD} is unset, it loses its special properties,
4138 even if it is subsequently reset.
4141 A value of @samp{ignorespace} means to not enter lines which
4142 begin with a space or tab into the history list.
4143 A value of @samp{ignoredups} means to not enter lines which match the last
4145 A value of @samp{ignoreboth} combines the two options.
4146 Unset, or set to any other value than those above, means to save
4147 all lines on the history list.
4148 The second and subsequent lines of a multi-line compound command are
4149 not tested, and are added to the history regardless of the value of
4153 The name of the file to which the command history is saved. The
4154 default value is @file{~/.bash_history}.
4157 The maximum number of lines contained in the history file. When this
4158 variable is assigned a value, the history file is truncated, if
4159 necessary, to contain no more than that number of lines.
4160 The history file is also truncated to this size after
4161 writing it when an interactive shell exits.
4162 The default value is 500.
4165 A colon-separated list of patterns used to decide which command
4166 lines should be saved on the history list. Each pattern is
4167 anchored at the beginning of the line and must match the complete
4168 line (no implicit @samp{*} is appended). Each pattern is tested
4169 against the line after the checks specified by @env{HISTCONTROL}
4170 are applied. In addition to the normal shell pattern matching
4171 characters, @samp{&} matches the previous history line. @samp{&}
4172 may be escaped using a backslash; the backslash is removed
4173 before attempting a match.
4174 The second and subsequent lines of a multi-line compound command are
4175 not tested, and are added to the history regardless of the value of
4178 @env{HISTIGNORE} subsumes the function of @env{HISTCONTROL}. A
4179 pattern of @samp{&} is identical to @code{ignoredups}, and a
4180 pattern of @samp{[ ]*} is identical to @code{ignorespace}.
4181 Combining these two patterns, separating them with a colon,
4182 provides the functionality of @code{ignoreboth}.
4185 The maximum number of commands to remember on the history list.
4186 The default value is 500.
4189 Contains the name of a file in the same format as @file{/etc/hosts} that
4190 should be read when the shell needs to complete a hostname.
4191 The list of possible hostname completions may be changed while the shell
4193 the next time hostname completion is attempted after the
4194 value is changed, Bash adds the contents of the new file to the
4196 If @env{HOSTFILE} is set, but has no value, Bash attempts to read
4197 @file{/etc/hosts} to obtain the list of possible hostname completions.
4198 When @env{HOSTFILE} is unset, the hostname list is cleared.
4201 The name of the current host.
4204 A string describing the machine Bash is running on.
4207 Controls the action of the shell on receipt of an @code{EOF} character
4208 as the sole input. If set, the value denotes the number
4209 of consecutive @code{EOF} characters that can be read as the
4210 first character on an input line
4211 before the shell will exit. If the variable exists but does not
4212 have a numeric value (or has no value) then the default is 10.
4213 If the variable does not exist, then @code{EOF} signifies the end of
4214 input to the shell. This is only in effect for interactive shells.
4217 The name of the Readline initialization file, overriding the default
4218 of @file{~/.inputrc}.
4221 Used to determine the locale category for any category not specifically
4222 selected with a variable starting with @code{LC_}.
4225 This variable overrides the value of @env{LANG} and any other
4226 @code{LC_} variable specifying a locale category.
4229 This variable determines the collation order used when sorting the
4230 results of filename expansion, and
4231 determines the behavior of range expressions, equivalence classes,
4232 and collating sequences within filename expansion and pattern matching
4233 (@pxref{Filename Expansion}).
4236 This variable determines the interpretation of characters and the
4237 behavior of character classes within filename expansion and pattern
4238 matching (@pxref{Filename Expansion}).
4241 This variable determines the locale used to translate double-quoted
4242 strings preceded by a @samp{$} (@pxref{Locale Translation}).
4245 This variable determines the locale category used for number formatting.
4248 The line number in the script or shell function currently executing.
4251 Used by the @code{select} builtin command to determine the column length
4252 for printing selection lists. Automatically set upon receipt of a
4256 A string that fully describes the system type on which Bash
4257 is executing, in the standard @sc{gnu} @var{cpu-company-system} format.
4260 How often (in seconds) that the shell should check for mail in the
4261 files specified in the @env{MAILPATH} or @env{MAIL} variables.
4262 The default is 60 seconds. When it is time to check
4263 for mail, the shell does so before displaying the primary prompt.
4264 If this variable is unset, or set to a value that is not a number
4265 greater than or equal to zero, the shell disables mail checking.
4268 The previous working directory as set by the @code{cd} builtin.
4271 If set to the value 1, Bash displays error messages
4272 generated by the @code{getopts} builtin command.
4275 A string describing the operating system Bash is running on.
4278 An array variable (@pxref{Arrays})
4279 containing a list of exit status values from the processes
4280 in the most-recently-executed foreground pipeline (which may
4281 contain only a single command).
4283 @item POSIXLY_CORRECT
4284 If this variable is in the environment when @code{bash} starts, the shell
4285 enters @sc{posix} mode (@pxref{Bash POSIX Mode}) before reading the
4286 startup files, as if the @option{--posix} invocation option had been supplied.
4287 If it is set while the shell is running, @code{bash} enables @sc{posix} mode,
4296 The process @sc{id} of the shell's parent process. This variable
4299 @item PROMPT_COMMAND
4300 If set, the value is interpreted as a command to execute
4301 before the printing of each primary prompt (@env{$PS1}).
4304 The value of this variable is used as the prompt for the
4305 @code{select} command. If this variable is not set, the
4306 @code{select} command prompts with @samp{#? }
4309 The value is the prompt printed before the command line is echoed
4310 when the @option{-x} option is set (@pxref{The Set Builtin}).
4311 The first character of @env{PS4} is replicated multiple times, as
4312 necessary, to indicate multiple levels of indirection.
4313 The default is @samp{+ }.
4316 The current working directory as set by the @code{cd} builtin.
4319 Each time this parameter is referenced, a random integer
4320 between 0 and 32767 is generated. Assigning a value to this
4321 variable seeds the random number generator.
4324 The default variable for the @code{read} builtin.
4327 This variable expands to the number of seconds since the
4328 shell was started. Assignment to this variable resets
4329 the count to the value assigned, and the expanded value
4330 becomes the value assigned plus the number of seconds
4331 since the assignment.
4334 A colon-separated list of enabled shell options. Each word in
4335 the list is a valid argument for the @option{-o} option to the
4336 @code{set} builtin command (@pxref{The Set Builtin}).
4337 The options appearing in @env{SHELLOPTS} are those reported
4338 as @samp{on} by @samp{set -o}.
4339 If this variable is in the environment when Bash
4340 starts up, each shell option in the list will be enabled before
4341 reading any startup files. This variable is readonly.
4344 Incremented by one each time a new instance of Bash is started. This is
4345 intended to be a count of how deeply your Bash shells are nested.
4348 The value of this parameter is used as a format string specifying
4349 how the timing information for pipelines prefixed with the @code{time}
4350 reserved word should be displayed.
4351 The @samp{%} character introduces an
4352 escape sequence that is expanded to a time value or other
4354 The escape sequences and their meanings are as
4355 follows; the braces denote optional portions.
4362 @item %[@var{p}][l]R
4363 The elapsed time in seconds.
4365 @item %[@var{p}][l]U
4366 The number of CPU seconds spent in user mode.
4368 @item %[@var{p}][l]S
4369 The number of CPU seconds spent in system mode.
4372 The CPU percentage, computed as (%U + %S) / %R.
4375 The optional @var{p} is a digit specifying the precision, the number of
4376 fractional digits after a decimal point.
4377 A value of 0 causes no decimal point or fraction to be output.
4378 At most three places after the decimal point may be specified; values
4379 of @var{p} greater than 3 are changed to 3.
4380 If @var{p} is not specified, the value 3 is used.
4382 The optional @code{l} specifies a longer format, including minutes, of
4383 the form @var{MM}m@var{SS}.@var{FF}s.
4384 The value of @var{p} determines whether or not the fraction is included.
4386 If this variable is not set, Bash acts as if it had the value
4388 @code{$'\nreal\t%3lR\nuser\t%3lU\nsys\t%3lS'}
4390 If the value is null, no timing information is displayed.
4391 A trailing newline is added when the format string is displayed.
4394 If set to a value greater than zero, @code{TMOUT} is treated as the
4395 default timeout for the @code{read} builtin (@pxref{Bash Builtins}).
4396 The @code{select} command (@pxref{Conditional Constructs}) terminates
4397 if input does not arrive after @code{TMOUT} seconds when input is coming
4400 In an interative shell, the value is interpreted as
4401 the number of seconds to wait for input after issuing the primary
4402 prompt when the shell is interactive.
4403 Bash terminates after that number of seconds if input does
4407 The numeric real user id of the current user. This variable is readonly.
4412 @chapter Bash Features
4414 This section describes features unique to Bash.
4417 * Invoking Bash:: Command line options that you can give
4419 * Bash Startup Files:: When and how Bash executes scripts.
4420 * Interactive Shells:: What an interactive shell is.
4421 * Bash Conditional Expressions:: Primitives used in composing expressions for
4422 the @code{test} builtin.
4423 * Shell Arithmetic:: Arithmetic on shell variables.
4424 * Aliases:: Substituting one command for another.
4425 * Arrays:: Array Variables.
4426 * The Directory Stack:: History of visited directories.
4427 * Printing a Prompt:: Controlling the PS1 string.
4428 * The Restricted Shell:: A more controlled mode of shell execution.
4429 * Bash POSIX Mode:: Making Bash behave more closely to what
4430 the POSIX standard specifies.
4434 @section Invoking Bash
4437 bash [long-opt] [-ir] [-abefhkmnptuvxdBCDHP] [-o @var{option}] [-O @var{shopt_option}] [@var{argument} @dots{}]
4438 bash [long-opt] [-abefhkmnptuvxdBCDHP] [-o @var{option}] [-O @var{shopt_option}] -c @var{string} [@var{argument} @dots{}]
4439 bash [long-opt] -s [-abefhkmnptuvxdBCDHP] [-o @var{option}] [-O @var{shopt_option}] [@var{argument} @dots{}]
4442 In addition to the single-character shell command-line options
4443 (@pxref{The Set Builtin}), there are several multi-character
4444 options that you can use. These options must appear on the command
4445 line before the single-character options to be recognized.
4448 @item --dump-po-strings
4449 A list of all double-quoted strings preceded by @samp{$}
4450 is printed on the standard ouput
4451 in the @sc{gnu} @code{gettext} PO (portable object) file format.
4452 Equivalent to @option{-D} except for the output format.
4454 @item --dump-strings
4455 Equivalent to @option{-D}.
4458 Display a usage message on standard output and exit sucessfully.
4460 @item --init-file @var{filename}
4461 @itemx --rcfile @var{filename}
4462 Execute commands from @var{filename} (instead of @file{~/.bashrc})
4463 in an interactive shell.
4466 Equivalent to @option{-l}.
4469 Do not use the @sc{gnu} Readline library (@pxref{Command Line Editing})
4470 to read command lines when the shell is interactive.
4473 Don't load the system-wide startup file @file{/etc/profile}
4474 or any of the personal initialization files
4475 @file{~/.bash_profile}, @file{~/.bash_login}, or @file{~/.profile}
4476 when Bash is invoked as a login shell.
4479 Don't read the @file{~/.bashrc} initialization file in an
4480 interactive shell. This is on by default if the shell is
4481 invoked as @code{sh}.
4484 Change the behavior of Bash where the default operation differs
4485 from the @sc{posix} 1003.2 standard to match the standard. This
4486 is intended to make Bash behave as a strict superset of that
4487 standard. @xref{Bash POSIX Mode}, for a description of the Bash
4491 Make the shell a restricted shell (@pxref{The Restricted Shell}).
4494 Equivalent to @option{-v}. Print shell input lines as they're read.
4497 Show version information for this instance of
4498 Bash on the standard output and exit successfully.
4502 There are several single-character options that may be supplied at
4503 invocation which are not available with the @code{set} builtin.
4506 @item -c @var{string}
4507 Read and execute commands from @var{string} after processing the
4508 options, then exit. Any remaining arguments are assigned to the
4509 positional parameters, starting with @code{$0}.
4512 Force the shell to run interactively. Interactive shells are
4513 described in @ref{Interactive Shells}.
4516 Make this shell act as if it had been directly invoked by login.
4517 When the shell is interactive, this is equivalent to starting a
4518 login shell with @samp{exec -l bash}.
4519 When the shell is not interactive, the login shell startup files will
4521 @samp{exec bash -l} or @samp{exec bash --login}
4522 will replace the current shell with a Bash login shell.
4523 @xref{Bash Startup Files}, for a description of the special behavior
4527 Make the shell a restricted shell (@pxref{The Restricted Shell}).
4530 If this option is present, or if no arguments remain after option
4531 processing, then commands are read from the standard input.
4532 This option allows the positional parameters to be set
4533 when invoking an interactive shell.
4536 A list of all double-quoted strings preceded by @samp{$}
4537 is printed on the standard ouput.
4538 These are the strings that
4539 are subject to language translation when the current locale
4540 is not @code{C} or @code{POSIX} (@pxref{Locale Translation}).
4541 This implies the @option{-n} option; no commands will be executed.
4543 @item [-+]O [@var{shopt_option}]
4544 @var{shopt_option} is one of the shell options accepted by the
4545 @code{shopt} builtin (@pxref{Shell Builtin Commands}).
4546 If @var{shopt_option} is present, @option{-O} sets the value of that option;
4547 @option{+O} unsets it.
4548 If @var{shopt_option} is not supplied, the names and values of the shell
4549 options accepted by @code{shopt} are printed on the standard output.
4550 If the invocation option is @option{+O}, the output is displayed in a format
4551 that may be reused as input.
4554 A @code{--} signals the end of options and disables further option
4556 Any arguments after the @code{--} are treated as filenames and arguments.
4561 A @emph{login} shell is one whose first character of argument zero is
4562 @samp{-}, or one invoked with the @option{--login} option.
4564 @cindex interactive shell
4565 An @emph{interactive} shell is one started without non-option arguments,
4566 unless @option{-s} is specified,
4567 without specifying the @option{-c} option, and whose input and output are both
4568 connected to terminals (as determined by @code{isatty(3)}), or one
4569 started with the @option{-i} option. @xref{Interactive Shells}, for more
4572 If arguments remain after option processing, and neither the
4573 @option{-c} nor the @option{-s}
4574 option has been supplied, the first argument is assumed to
4575 be the name of a file containing shell commands (@pxref{Shell Scripts}).
4576 When Bash is invoked in this fashion, @code{$0}
4577 is set to the name of the file, and the positional parameters
4578 are set to the remaining arguments.
4579 Bash reads and executes commands from this file, then exits.
4580 Bash's exit status is the exit status of the last command executed
4581 in the script. If no commands are executed, the exit status is 0.
4583 @node Bash Startup Files
4584 @section Bash Startup Files
4585 @cindex startup files
4587 This section describs how Bash executes its startup files.
4588 If any of the files exist but cannot be read, Bash reports an error.
4589 Tildes are expanded in file names as described above under
4590 Tilde Expansion (@pxref{Tilde Expansion}).
4592 Interactive shells are described in @ref{Interactive Shells}.
4594 @subsubheading Invoked as an interactive login shell, or with @option{--login}
4596 When Bash is invoked as an interactive login shell, or as a
4597 non-interactive shell with the @option{--login} option, it first reads and
4598 executes commands from the file @file{/etc/profile}, if that file exists.
4599 After reading that file, it looks for @file{~/.bash_profile},
4600 @file{~/.bash_login}, and @file{~/.profile}, in that order, and reads
4601 and executes commands from the first one that exists and is readable.
4602 The @option{--noprofile} option may be used when the shell is started to
4603 inhibit this behavior.
4605 When a login shell exits, Bash reads and executes commands from
4606 the file @file{~/.bash_logout}, if it exists.
4608 @subsubheading Invoked as an interactive non-login shell
4610 When an interactive shell that is not a login shell is started, Bash
4611 reads and executes commands from @file{~/.bashrc}, if that file exists.
4612 This may be inhibited by using the @option{--norc} option.
4613 The @option{--rcfile @var{file}} option will force Bash to read and
4614 execute commands from @var{file} instead of @file{~/.bashrc}.
4616 So, typically, your @file{~/.bash_profile} contains the line
4618 @code{if [ -f ~/.bashrc ]; then . ~/.bashrc; fi}
4621 after (or before) any login-specific initializations.
4623 @subsubheading Invoked non-interactively
4625 When Bash is started non-interactively, to run a shell script,
4626 for example, it looks for the variable @env{BASH_ENV} in the environment,
4627 expands its value if it appears there, and uses the expanded value as
4628 the name of a file to read and execute. Bash behaves as if the
4629 following command were executed:
4631 @code{if [ -n "$BASH_ENV" ]; then . "$BASH_ENV"; fi}
4634 but the value of the @env{PATH} variable is not used to search for the
4637 As noted above, if a non-interactive shell is invoked with the
4638 @option{--login} option, Bash attempts to read and execute commands from the
4639 login shell startup files.
4641 @subsubheading Invoked with name @code{sh}
4643 If Bash is invoked with the name @code{sh}, it tries to mimic the
4644 startup behavior of historical versions of @code{sh} as closely as
4645 possible, while conforming to the @sc{posix} standard as well.
4647 When invoked as an interactive login shell, or as a non-interactive
4648 shell with the @option{--login} option, it first attempts to read
4649 and execute commands from @file{/etc/profile} and @file{~/.profile}, in
4651 The @option{--noprofile} option may be used to inhibit this behavior.
4652 When invoked as an interactive shell with the name @code{sh}, Bash
4653 looks for the variable @env{ENV}, expands its value if it is defined,
4654 and uses the expanded value as the name of a file to read and execute.
4655 Since a shell invoked as @code{sh} does not attempt to read and execute
4656 commands from any other startup files, the @option{--rcfile} option has
4658 A non-interactive shell invoked with the name @code{sh} does not attempt
4659 to read any other startup files.
4661 When invoked as @code{sh}, Bash enters @sc{posix} mode after
4662 the startup files are read.
4664 @subsubheading Invoked in @sc{posix} mode
4666 When Bash is started in @sc{posix} mode, as with the
4667 @option{--posix} command line option, it follows the @sc{posix} standard
4669 In this mode, interactive shells expand the @env{ENV} variable
4670 and commands are read and executed from the file whose name is the
4672 No other startup files are read.
4674 @subsubheading Invoked by remote shell daemon
4676 Bash attempts to determine when it is being run by the remote shell
4677 daemon, usually @code{rshd}. If Bash determines it is being run by
4678 rshd, it reads and executes commands from @file{~/.bashrc}, if that
4679 file exists and is readable.
4680 It will not do this if invoked as @code{sh}.
4681 The @option{--norc} option may be used to inhibit this behavior, and the
4682 @option{--rcfile} option may be used to force another file to be read, but
4683 @code{rshd} does not generally invoke the shell with those options or
4684 allow them to be specified.
4686 @subsubheading Invoked with unequal effective and real @sc{uid/gid}s
4688 If Bash is started with the effective user (group) id not equal to the
4689 real user (group) id, and the @code{-p} option is not supplied, no startup
4690 files are read, shell functions are not inherited from the environment,
4691 the @env{SHELLOPTS} variable, if it appears in the environment, is ignored,
4692 and the effective user id is set to the real user id.
4693 If the @code{-p} option is supplied at invocation, the startup behavior is
4694 the same, but the effective user id is not reset.
4696 @node Interactive Shells
4697 @section Interactive Shells
4698 @cindex interactive shell
4699 @cindex shell, interactive
4702 * What is an Interactive Shell?:: What determines whether a shell is Interactive.
4703 * Is this Shell Interactive?:: How to tell if a shell is interactive.
4704 * Interactive Shell Behavior:: What changes in a interactive shell?
4707 @node What is an Interactive Shell?
4708 @subsection What is an Interactive Shell?
4710 An interactive shell
4711 is one started without non-option arguments, unless @option{-s} is
4712 specified, without specifiying the @option{-c} option, and
4713 whose input and output are both
4714 connected to terminals (as determined by @code{isatty(3)}),
4715 or one started with the @option{-i} option.
4717 An interactive shell generally reads from and writes to a user's
4720 The @option{-s} invocation option may be used to set the positional parameters
4721 when an interactive shell is started.
4723 @node Is this Shell Interactive?
4724 @subsection Is this Shell Interactive?
4726 To determine within a startup script whether or not Bash is
4727 running interactively,
4728 test the value of the @samp{-} special parameter.
4729 It contains @code{i} when the shell is interactive. For example:
4733 *i*) echo This shell is interactive ;;
4734 *) echo This shell is not interactive ;;
4738 Alternatively, startup scripts may examine the variable
4739 @env{PS1}; it is unset in non-interactive shells, and set in
4740 interactive shells. Thus:
4743 if [ -z "$PS1" ]; then
4744 echo This shell is not interactive
4746 echo This shell is interactive
4750 @node Interactive Shell Behavior
4751 @subsection Interactive Shell Behavior
4753 When the shell is running interactively, it changes its behavior in
4758 Startup files are read and executed as described in @ref{Bash Startup Files}.
4761 Job Control (@pxref{Job Control}) is enabled by default. When job
4762 control is in effect, Bash ignores the keyboard-generated job control
4763 signals @code{SIGTTIN}, @code{SIGTTOU}, and @code{SIGTSTP}.
4766 Bash expands and displays @env{PS1} before reading the first line
4767 of a command, and expands and displays @env{PS2} before reading the
4768 second and subsequent lines of a multi-line command.
4771 Bash executes the value of the @env{PROMPT_COMMAND} variable as a command
4772 before printing the primary prompt, @env{$PS1}
4773 (@pxref{Bash Variables}).
4776 Readline (@pxref{Command Line Editing}) is used to read commands from
4777 the user's terminal.
4780 Bash inspects the value of the @code{ignoreeof} option to @code{set -o}
4781 instead of exiting immediately when it receives an @code{EOF} on its
4782 standard input when reading a command (@pxref{The Set Builtin}).
4785 Command history (@pxref{Bash History Facilities})
4786 and history expansion (@pxref{History Interaction})
4787 are enabled by default.
4788 Bash will save the command history to the file named by @env{$HISTFILE}
4789 when an interactive shell exits.
4792 Alias expansion (@pxref{Aliases}) is performed by default.
4795 In the absence of any traps, Bash ignores @code{SIGTERM}
4799 In the absence of any traps, @code{SIGINT} is caught and handled
4801 @code{SIGINT} will interrupt some shell builtins.
4804 An interactive login shell sends a @code{SIGHUP} to all jobs on exit
4805 if the @code{hupoxexit} shell option has been enabled (@pxref{Signals}).
4808 The @option{-n} invocation option is ignored, and @samp{set -n} has
4809 no effect (@pxref{The Set Builtin}).
4812 Bash will check for mail periodically, depending on the values of the
4813 @env{MAIL}, @env{MAILPATH}, and @env{MAILCHECK} shell variables
4814 (@pxref{Bash Variables}).
4817 Expansion errors due to references to unbound shell variables after
4818 @samp{set -u} has been enabled will not cause the shell to exit
4819 (@pxref{The Set Builtin}).
4822 The shell will not exit on expansion errors caused by @var{var} being unset
4823 or null in @code{$@{@var{var}:?@var{word}@}} expansions
4824 (@pxref{Shell Parameter Expansion}).
4827 Redirection errors encountered by shell builtins will not cause the
4831 When running in @sc{posix} mode, a special builtin returning an error
4832 status will not cause the shell to exit (@pxref{Bash POSIX Mode}).
4834 A failed @code{exec} will not cause the shell to exit
4835 (@pxref{Bourne Shell Builtins}).
4838 Parser syntax errors will not cause the shell to exit.
4841 Simple spelling correction for directory arguments to the @code{cd}
4842 builtin is enabled by default (see the description of the @code{cdspell}
4843 option to the @code{shopt} builtin in @ref{Bash Builtins}).
4846 The shell will check the value of the @env{TMOUT} variable and exit
4847 if a command is not read within the specified number of seconds after
4848 printing @env{$PS1} (@pxref{Bash Variables}).
4852 @node Bash Conditional Expressions
4853 @section Bash Conditional Expressions
4854 @cindex expressions, conditional
4856 Conditional expressions are used by the @code{[[} compound command
4857 and the @code{test} and @code{[} builtin commands.
4859 Expressions may be unary or binary.
4860 Unary expressions are often used to examine the status of a file.
4861 There are string operators and numeric comparison operators as well.
4862 If the @var{file} argument to one of the primaries is of the form
4863 @file{/dev/fd/@var{N}}, then file descriptor @var{N} is checked.
4864 If the @var{file} argument to one of the primaries is one of
4865 @file{/dev/stdin}, @file{/dev/stdout}, or @file{/dev/stderr}, file
4866 descriptor 0, 1, or 2, respectively, is checked.
4870 True if @var{file} exists.
4873 True if @var{file} exists and is a block special file.
4876 True if @var{file} exists and is a character special file.
4879 True if @var{file} exists and is a directory.
4882 True if @var{file} exists.
4885 True if @var{file} exists and is a regular file.
4888 True if @var{file} exists and its set-group-id bit is set.
4891 True if @var{file} exists and is a symbolic link.
4894 True if @var{file} exists and its "sticky" bit is set.
4897 True if @var{file} exists and is a named pipe (FIFO).
4900 True if @var{file} exists and is readable.
4903 True if @var{file} exists and has a size greater than zero.
4906 True if file descriptor @var{fd} is open and refers to a terminal.
4909 True if @var{file} exists and its set-user-id bit is set.
4912 True if @var{file} exists and is writable.
4915 True if @var{file} exists and is executable.
4918 True if @var{file} exists and is owned by the effective user id.
4921 True if @var{file} exists and is owned by the effective group id.
4924 True if @var{file} exists and is a symbolic link.
4927 True if @var{file} exists and is a socket.
4930 True if @var{file} exists and has been modified since it was last read.
4932 @item @var{file1} -nt @var{file2}
4933 True if @var{file1} is newer (according to modification date)
4934 than @var{file2}, or if @var{file1} exists and @var{file2} does not.
4936 @item @var{file1} -ot @var{file2}
4937 True if @var{file1} is older than @var{file2},
4938 or if @var{file2} exists and @var{file1} does not.
4940 @item @var{file1} -ef @var{file2}
4941 True if @var{file1} and @var{file2} refer to the same device and
4944 @item -o @var{optname}
4945 True if shell option @var{optname} is enabled.
4946 The list of options appears in the description of the @option{-o}
4947 option to the @code{set} builtin (@pxref{The Set Builtin}).
4949 @item -z @var{string}
4950 True if the length of @var{string} is zero.
4952 @item -n @var{string}
4954 True if the length of @var{string} is non-zero.
4956 @item @var{string1} == @var{string2}
4957 True if the strings are equal.
4958 @samp{=} may be used in place of @samp{==} for strict @sc{posix} compliance.
4960 @item @var{string1} != @var{string2}
4961 True if the strings are not equal.
4963 @item @var{string1} < @var{string2}
4964 True if @var{string1} sorts before @var{string2} lexicographically
4965 in the current locale.
4967 @item @var{string1} > @var{string2}
4968 True if @var{string1} sorts after @var{string2} lexicographically
4969 in the current locale.
4971 @item @var{arg1} OP @var{arg2}
4973 @samp{-eq}, @samp{-ne}, @samp{-lt}, @samp{-le}, @samp{-gt}, or @samp{-ge}.
4974 These arithmetic binary operators return true if @var{arg1}
4975 is equal to, not equal to, less than, less than or equal to,
4976 greater than, or greater than or equal to @var{arg2},
4977 respectively. @var{Arg1} and @var{arg2}
4978 may be positive or negative integers.
4982 @node Shell Arithmetic
4983 @section Shell Arithmetic
4984 @cindex arithmetic, shell
4985 @cindex shell arithmetic
4986 @cindex expressions, arithmetic
4987 @cindex evaluation, arithmetic
4988 @cindex arithmetic evaluation
4990 The shell allows arithmetic expressions to be evaluated, as one of
4991 the shell expansions or by the @code{let} builtin.
4993 Evaluation is done in fixed-width integers with no check for overflow,
4994 though division by 0 is trapped and flagged as an error.
4995 The operators and their precedence and associativity are the same
4996 as in the C language.
4997 The following list of operators is grouped into levels of
4998 equal-precedence operators.
4999 The levels are listed in order of decreasing precedence.
5003 @item @var{id}++ @var{id}--
5004 variable post-increment and post-decrement
5006 @item ++@var{id} --@var{id}
5007 variable pre-increment and pre-decrement
5010 unary minus and plus
5013 logical and bitwise negation
5019 multiplication, division, remainder
5022 addition, subtraction
5025 left and right bitwise shifts
5031 equality and inequality
5037 bitwise exclusive OR
5048 @item expr ? expr : expr
5049 conditional evaluation
5051 @item = *= /= %= += -= <<= >>= &= ^= |=
5058 Shell variables are allowed as operands; parameter expansion is
5059 performed before the expression is evaluated.
5060 Within an expression, shell variables may also be referenced by name
5061 without using the parameter expansion syntax.
5062 The value of a variable is evaluated as an arithmetic expression
5063 when it is referenced.
5064 A shell variable need not have its integer attribute turned on
5065 to be used in an expression.
5067 Constants with a leading 0 are interpreted as octal numbers.
5068 A leading @samp{0x} or @samp{0X} denotes hexadecimal. Otherwise,
5069 numbers take the form [@var{base}@code{#}]@var{n}, where @var{base}
5070 is a decimal number between 2 and 64 representing the arithmetic
5071 base, and @var{n} is a number in that base. If @var{base}@code{#} is
5072 omitted, then base 10 is used.
5073 The digits greater than 9 are represented by the lowercase letters,
5074 the uppercase letters, @samp{@@}, and @samp{_}, in that order.
5075 If @var{base} is less than or equal to 36, lowercase and uppercase
5076 letters may be used interchangably to represent numbers between 10
5079 Operators are evaluated in order of precedence. Sub-expressions in
5080 parentheses are evaluated first and may override the precedence
5085 @cindex alias expansion
5087 @var{Aliases} allow a string to be substituted for a word when it is used
5088 as the first word of a simple command.
5089 The shell maintains a list of aliases that may be set and unset with
5090 the @code{alias} and @code{unalias} builtin commands.
5092 The first word of each simple command, if unquoted, is checked to see
5094 If so, that word is replaced by the text of the alias.
5095 The alias name and the replacement text may contain any valid
5096 shell input, including shell metacharacters, with the exception
5097 that the alias name may not contain @samp{=}.
5098 The first word of the replacement text is tested for
5099 aliases, but a word that is identical to an alias being expanded
5100 is not expanded a second time. This means that one may alias
5101 @code{ls} to @code{"ls -F"},
5102 for instance, and Bash does not try to recursively expand the
5103 replacement text. If the last character of the alias value is a
5104 space or tab character, then the next command word following the
5105 alias is also checked for alias expansion.
5107 Aliases are created and listed with the @code{alias}
5108 command, and removed with the @code{unalias} command.
5110 There is no mechanism for using arguments in the replacement text,
5112 If arguments are needed, a shell function should be used
5113 (@pxref{Shell Functions}).
5115 Aliases are not expanded when the shell is not interactive,
5116 unless the @code{expand_aliases} shell option is set using
5117 @code{shopt} (@pxref{Bash Builtins}).
5119 The rules concerning the definition and use of aliases are
5120 somewhat confusing. Bash
5121 always reads at least one complete line
5122 of input before executing any
5123 of the commands on that line. Aliases are expanded when a
5124 command is read, not when it is executed. Therefore, an
5125 alias definition appearing on the same line as another
5126 command does not take effect until the next line of input is read.
5127 The commands following the alias definition
5128 on that line are not affected by the new alias.
5129 This behavior is also an issue when functions are executed.
5130 Aliases are expanded when a function definition is read,
5131 not when the function is executed, because a function definition
5132 is itself a compound command. As a consequence, aliases
5133 defined in a function are not available until after that
5134 function is executed. To be safe, always put
5135 alias definitions on a separate line, and do not use @code{alias}
5136 in compound commands.
5138 For almost every purpose, shell functions are preferred over aliases.
5144 Bash provides one-dimensional array variables. Any variable may be used as
5145 an array; the @code{declare} builtin will explicitly declare an array.
5147 limit on the size of an array, nor any requirement that members
5148 be indexed or assigned contiguously. Arrays are zero-based.
5150 An array is created automatically if any variable is assigned to using
5153 name[@var{subscript}]=@var{value}
5158 is treated as an arithmetic expression that must evaluate to a number
5159 greater than or equal to zero. To explicitly declare an array, use
5161 declare -a @var{name}
5166 declare -a @var{name}[@var{subscript}]
5169 is also accepted; the @var{subscript} is ignored. Attributes may be
5170 specified for an array variable using the @code{declare} and
5171 @code{readonly} builtins. Each attribute applies to all members of
5174 Arrays are assigned to using compound assignments of the form
5176 name=(value@var{1} @dots{} value@var{n})
5180 @var{value} is of the form @code{[[@var{subscript}]=]}@var{string}. If
5181 the optional subscript is supplied, that index is assigned to;
5182 otherwise the index of the element assigned is the last index assigned
5183 to by the statement plus one. Indexing starts at zero.
5184 This syntax is also accepted by the @code{declare}
5185 builtin. Individual array elements may be assigned to using the
5186 @code{name[}@var{subscript}@code{]=}@var{value} syntax introduced above.
5188 Any element of an array may be referenced using
5189 @code{$@{name[}@var{subscript}@code{]@}}.
5190 The braces are required to avoid
5191 conflicts with the shell's filename expansion operators. If the
5192 @var{subscript} is @samp{@@} or @samp{*}, the word expands to all members
5193 of the array @var{name}. These subscripts differ only when the word
5194 appears within double quotes. If the word is double-quoted,
5195 @code{$@{name[*]@}} expands to a single word with
5196 the value of each array member separated by the first character of the
5197 @env{IFS} variable, and @code{$@{name[@@]@}} expands each element of
5198 @var{name} to a separate word. When there are no array members,
5199 @code{$@{name[@@]@}} expands to nothing. This is analogous to the
5200 expansion of the special parameters @samp{@@} and @samp{*}.
5201 @code{$@{#name[}@var{subscript}@code{]@}} expands to the length of
5202 @code{$@{name[}@var{subscript}@code{]@}}.
5203 If @var{subscript} is @samp{@@} or
5204 @samp{*}, the expansion is the number of elements in the array.
5205 Referencing an array variable without a subscript is equivalent to
5206 referencing element zero.
5208 The @code{unset} builtin is used to destroy arrays.
5209 @code{unset} @var{name}[@var{subscript}]
5210 destroys the array element at index @var{subscript}.
5211 @code{unset} @var{name}, where @var{name} is an array, removes the
5212 entire array. A subscript of @samp{*} or @samp{@@} also removes the
5215 The @code{declare}, @code{local}, and @code{readonly}
5216 builtins each accept a @option{-a}
5217 option to specify an array. The @code{read}
5218 builtin accepts a @option{-a}
5219 option to assign a list of words read from the standard input
5220 to an array, and can read values from the standard input into
5221 individual array elements. The @code{set} and @code{declare}
5222 builtins display array values in a way that allows them to be
5225 @node The Directory Stack
5226 @section The Directory Stack
5227 @cindex directory stack
5230 * Directory Stack Builtins:: Bash builtin commands to manipulate
5231 the directory stack.
5234 The directory stack is a list of recently-visited directories. The
5235 @code{pushd} builtin adds directories to the stack as it changes
5236 the current directory, and the @code{popd} builtin removes specified
5237 directories from the stack and changes the current directory to
5238 the directory removed. The @code{dirs} builtin displays the contents
5239 of the directory stack.
5241 The contents of the directory stack are also visible
5242 as the value of the @env{DIRSTACK} shell variable.
5244 @node Directory Stack Builtins
5245 @subsection Directory Stack Builtins
5252 dirs [+@var{N} | -@var{N}] [-clpv]
5254 Display the list of currently remembered directories. Directories
5255 are added to the list with the @code{pushd} command; the
5256 @code{popd} command removes directories from the list.
5259 Displays the @var{N}th directory (counting from the left of the
5260 list printed by @code{dirs} when invoked without options), starting
5263 Displays the @var{N}th directory (counting from the right of the
5264 list printed by @code{dirs} when invoked without options), starting
5267 Clears the directory stack by deleting all of the elements.
5269 Produces a longer listing; the default listing format uses a
5270 tilde to denote the home directory.
5272 Causes @code{dirs} to print the directory stack with one entry per
5275 Causes @code{dirs} to print the directory stack with one entry per
5276 line, prefixing each entry with its index in the stack.
5282 popd [+@var{N} | -@var{N}] [-n]
5285 Remove the top entry from the directory stack, and @code{cd}
5286 to the new top directory.
5287 When no arguments are given, @code{popd}
5288 removes the top directory from the stack and
5289 performs a @code{cd} to the new top directory. The
5290 elements are numbered from 0 starting at the first directory listed with
5291 @code{dirs}; i.e., @code{popd} is equivalent to @code{popd +0}.
5294 Removes the @var{N}th directory (counting from the left of the
5295 list printed by @code{dirs}), starting with zero.
5297 Removes the @var{N}th directory (counting from the right of the
5298 list printed by @code{dirs}), starting with zero.
5300 Suppresses the normal change of directory when removing directories
5301 from the stack, so that only the stack is manipulated.
5307 pushd [@var{dir} | @var{+N} | @var{-N}] [-n]
5310 Save the current directory on the top of the directory stack
5311 and then @code{cd} to @var{dir}.
5312 With no arguments, @code{pushd} exchanges the top two directories.
5316 Brings the @var{N}th directory (counting from the left of the
5317 list printed by @code{dirs}, starting with zero) to the top of
5318 the list by rotating the stack.
5320 Brings the @var{N}th directory (counting from the right of the
5321 list printed by @code{dirs}, starting with zero) to the top of
5322 the list by rotating the stack.
5324 Suppresses the normal change of directory when adding directories
5325 to the stack, so that only the stack is manipulated.
5327 Makes the current working directory be the top of the stack, and then
5328 executes the equivalent of `@code{cd} @var{dir}'.
5329 @code{cd}s to @var{dir}.
5334 @node Printing a Prompt
5335 @section Controlling the Prompt
5338 The value of the variable @env{PROMPT_COMMAND} is examined just before
5339 Bash prints each primary prompt. If @env{PROMPT_COMMAND} is set and
5340 has a non-null value, then the
5341 value is executed just as if it had been typed on the command line.
5343 In addition, the following table describes the special characters which
5344 can appear in the prompt variables:
5350 The date, in "Weekday Month Date" format (e.g., "Tue May 26").
5351 @item \D@{@var{format}@}
5352 The @var{format} is passed to @code{strftime}(3) and the result is inserted
5353 into the prompt string; an empty @var{format} results in a locale-specific
5354 time representation. The braces are required.
5356 An escape character.
5358 The hostname, up to the first `.'.
5362 The number of jobs currently managed by the shell.
5364 The basename of the shell's terminal device name.
5370 The name of the shell, the basename of @code{$0} (the portion
5371 following the final slash).
5373 The time, in 24-hour HH:MM:SS format.
5375 The time, in 12-hour HH:MM:SS format.
5377 The time, in 12-hour am/pm format.
5379 The time, in 24-hour HH:MM format.
5381 The username of the current user.
5383 The version of Bash (e.g., 2.00)
5385 The release of Bash, version + patchlevel (e.g., 2.00.0)
5387 The current working directory.
5389 The basename of @env{$PWD}.
5391 The history number of this command.
5393 The command number of this command.
5395 If the effective uid is 0, @code{#}, otherwise @code{$}.
5397 The character whose ASCII code is the octal value @var{nnn}.
5401 Begin a sequence of non-printing characters. This could be used to
5402 embed a terminal control sequence into the prompt.
5404 End a sequence of non-printing characters.
5407 The command number and the history number are usually different:
5408 the history number of a command is its position in the history
5409 list, which may include commands restored from the history file
5410 (@pxref{Bash History Facilities}), while the command number is
5411 the position in the sequence of commands executed during the current
5414 After the string is decoded, it is expanded via
5415 parameter expansion, command substitution, arithmetic
5416 expansion, and quote removal, subject to the value of the
5417 @code{promptvars} shell option (@pxref{Bash Builtins}).
5419 @node The Restricted Shell
5420 @section The Restricted Shell
5421 @cindex restricted shell
5423 If Bash is started with the name @code{rbash}, or the
5424 @option{--restricted}
5427 option is supplied at invocation, the shell becomes restricted.
5428 A restricted shell is used to
5429 set up an environment more controlled than the standard shell.
5430 A restricted shell behaves identically to @code{bash}
5431 with the exception that the following are disallowed or not performed:
5435 Changing directories with the @code{cd} builtin.
5437 Setting or unsetting the values of the @env{SHELL}, @env{PATH},
5438 @env{ENV}, or @env{BASH_ENV} variables.
5440 Specifying command names containing slashes.
5442 Specifying a filename containing a slash as an argument to the @code{.}
5445 Specifying a filename containing a slash as an argument to the @option{-p}
5446 option to the @code{hash} builtin command.
5448 Importing function definitions from the shell environment at startup.
5450 Parsing the value of @env{SHELLOPTS} from the shell environment at startup.
5452 Redirecting output using the @samp{>}, @samp{>|}, @samp{<>}, @samp{>&},
5453 @samp{&>}, and @samp{>>} redirection operators.
5455 Using the @code{exec} builtin to replace the shell with another command.
5457 Adding or deleting builtin commands with the
5458 @option{-f} and @option{-d} options to the @code{enable} builtin.
5460 Using the @code{enable} builtin command to enable disabled shell builtins.
5462 Specifying the @option{-p} option to the @code{command} builtin.
5464 Turning off restricted mode with @samp{set +r} or @samp{set +o restricted}.
5467 These restrictions are enforced after any startup files are read.
5469 When a command that is found to be a shell script is executed
5470 (@pxref{Shell Scripts}), @code{rbash} turns off any restrictions in
5471 the shell spawned to execute the script.
5473 @node Bash POSIX Mode
5474 @section Bash POSIX Mode
5477 Starting Bash with the @option{--posix} command-line option or executing
5478 @samp{set -o posix} while Bash is running will cause Bash to conform more
5479 closely to the @sc{posix} 1003.2 standard by changing the behavior to
5480 match that specified by @sc{posix} in areas where the Bash default differs.
5482 When invoked as @code{sh}, Bash enters @sc{posix} mode after reading the
5485 The following list is what's changed when `@sc{posix} mode' is in effect:
5489 When a command in the hash table no longer exists, Bash will re-search
5490 @env{$PATH} to find the new location. This is also available with
5491 @samp{shopt -s checkhash}.
5494 The message printed by the job control code and builtins when a job
5495 exits with a non-zero status is `Done(status)'.
5498 The message printed by the job control code and builtins when a job
5499 is stopped is `Stopped(@var{signame})', where @var{signame} is, for
5500 example, @code{SIGTSTP}.
5503 Reserved words may not be aliased.
5506 The @sc{posix} 1003.2 @env{PS1} and @env{PS2} expansions of @samp{!} to
5507 the history number and @samp{!!} to @samp{!} are enabled,
5508 and parameter expansion is performed on the values of @env{PS1} and
5509 @env{PS2} regardless of the setting of the @code{promptvars} option.
5512 Interactive comments are enabled by default. (Bash has them on by
5516 The @sc{posix} 1003.2 startup files are executed (@env{$ENV}) rather than
5517 the normal Bash files.
5520 Tilde expansion is only performed on assignments preceding a command
5521 name, rather than on all assignment statements on the line.
5524 The default history file is @file{~/.sh_history} (this is the
5525 default value of @env{$HISTFILE}).
5528 The output of @samp{kill -l} prints all the signal names on a single line,
5529 separated by spaces.
5532 Non-interactive shells exit if @var{filename} in @code{.} @var{filename}
5536 Non-interactive shells exit if a syntax error in an arithmetic expansion
5537 results in an invalid expression.
5540 Redirection operators do not perform filename expansion on the word
5541 in the redirection unless the shell is interactive.
5544 Redirection operators do not perform word splitting on the word in the
5548 Function names must be valid shell @code{name}s. That is, they may not
5549 contain characters other than letters, digits, and underscores, and
5550 may not start with a digit. Declaring a function with an invalid name
5551 causes a fatal syntax error in non-interactive shells.
5554 @sc{posix} 1003.2 `special' builtins are found before shell functions
5555 during command lookup.
5558 If a @sc{posix} 1003.2 special builtin returns an error status, a
5559 non-interactive shell exits. The fatal errors are those listed in
5560 the POSIX.2 standard, and include things like passing incorrect options,
5561 redirection errors, variable assignment errors for assignments preceding
5562 the command name, and so on.
5565 If the @code{cd} builtin finds a directory to change to
5566 using @env{$CDPATH}, the
5567 value it assigns to the @env{PWD} variable does not contain any
5568 symbolic links, as if @samp{cd -P} had been executed.
5571 If @env{CDPATH} is set, the @code{cd} builtin will not implicitly
5572 append the current directory to it. This means that @code{cd} will
5573 fail if no valid directory name can be constructed from
5574 any of the entries in @env{$CDPATH}, even if the a directory with
5575 the same name as the name given as an argument to @code{cd} exists
5576 in the current directory.
5579 A non-interactive shell exits with an error status if a variable
5580 assignment error occurs when no command name follows the assignment
5582 A variable assignment error occurs, for example, when trying to assign
5583 a value to a readonly variable.
5586 A non-interactive shell exits with an error status if the iteration
5587 variable in a @code{for} statement or the selection variable in a
5588 @code{select} statement is a readonly variable.
5591 Process substitution is not available.
5594 Assignment statements preceding @sc{posix} 1003.2 special builtins
5595 persist in the shell environment after the builtin completes.
5598 Assignment statements preceding shell function calls persist in the
5599 shell environment after the function returns, as if a @sc{posix}
5600 special builtin command had been executed.
5603 The @code{export} and @code{readonly} builtin commands display their
5604 output in the format required by @sc{posix} 1003.2.
5607 The @code{trap} builtin displays signal names without the leading
5611 The @code{.} and @code{source} builtins do not search the current directory
5612 for the filename argument if it is not found by searching @env{PATH}.
5615 Subshells spawned to execute command substitutions inherit the value of
5616 the @option{-e} option from the parent shell. When not in @sc{posix} mode,
5617 Bash clears the @option{-e} option in such subshells.
5620 Alias expansion is always enabled, even in non-interactive shells.
5623 When the @code{set} builtin is invoked without options, it does not display
5624 shell function names and definitions.
5627 When the @code{set} builtin is invoked without options, it displays
5628 variable values without quotes, unless they contain shell metacharacters,
5629 even if the result contains nonprinting characters.
5632 When the @code{cd} builtin is invoked in @var{logical} mode, and the pathname
5633 constructed from @code{$PWD} and the directory name supplied as an argument
5634 does not refer to an existing directory, @code{cd} will fail instead of
5635 falling back to @var{physical} mode.
5638 There is other @sc{posix} 1003.2 behavior that Bash does not implement.
5643 Assignment statements affect the execution environment of all
5644 builtins, not just special ones.
5647 When a subshell is created to execute a shell script with execute permission,
5648 but without a leading @samp{#!}, Bash sets @code{$0} to the full pathname of
5649 the script as found by searching @code{$PATH}, rather than the command as
5653 When using @samp{.} to source a shell script found in @code{$PATH}, bash
5654 checks execute permission bits rather than read permission bits, just as
5655 if it were searching for a command.
5660 @chapter Job Control
5662 This chapter discusses what job control is, how it works, and how
5663 Bash allows you to access its facilities.
5666 * Job Control Basics:: How job control works.
5667 * Job Control Builtins:: Bash builtin commands used to interact
5669 * Job Control Variables:: Variables Bash uses to customize job
5673 @node Job Control Basics
5674 @section Job Control Basics
5678 @cindex suspending jobs
5681 refers to the ability to selectively stop (suspend)
5682 the execution of processes and continue (resume)
5683 their execution at a later point. A user typically employs
5684 this facility via an interactive interface supplied jointly
5685 by the system's terminal driver and Bash.
5687 The shell associates a @var{job} with each pipeline. It keeps a
5688 table of currently executing jobs, which may be listed with the
5689 @code{jobs} command. When Bash starts a job
5690 asynchronously, it prints a line that looks
5696 indicating that this job is job number 1 and that the process @sc{id}
5697 of the last process in the pipeline associated with this job is
5698 25647. All of the processes in a single pipeline are members of
5699 the same job. Bash uses the @var{job} abstraction as the
5700 basis for job control.
5702 To facilitate the implementation of the user interface to job
5703 control, the operating system maintains the notion of a current terminal
5704 process group @sc{id}. Members of this process group (processes whose
5705 process group @sc{id} is equal to the current terminal process group
5706 @sc{id}) receive keyboard-generated signals such as @code{SIGINT}.
5707 These processes are said to be in the foreground. Background
5708 processes are those whose process group @sc{id} differs from the
5709 terminal's; such processes are immune to keyboard-generated
5710 signals. Only foreground processes are allowed to read from or
5711 write to the terminal. Background processes which attempt to
5712 read from (write to) the terminal are sent a @code{SIGTTIN}
5713 (@code{SIGTTOU}) signal by the terminal driver, which, unless
5714 caught, suspends the process.
5716 If the operating system on which Bash is running supports
5717 job control, Bash contains facilities to use it. Typing the
5718 @var{suspend} character (typically @samp{^Z}, Control-Z) while a
5719 process is running causes that process to be stopped and returns
5720 control to Bash. Typing the @var{delayed suspend} character
5721 (typically @samp{^Y}, Control-Y) causes the process to be stopped
5722 when it attempts to read input from the terminal, and control to
5723 be returned to Bash. The user then manipulates the state of
5724 this job, using the @code{bg} command to continue it in the
5725 background, the @code{fg} command to continue it in the
5726 foreground, or the @code{kill} command to kill it. A @samp{^Z}
5727 takes effect immediately, and has the additional side effect of
5728 causing pending output and typeahead to be discarded.
5730 There are a number of ways to refer to a job in the shell. The
5731 character @samp{%} introduces a job name.
5733 Job number @code{n} may be referred to as @samp{%n}.
5734 The symbols @samp{%%} and
5735 @samp{%+} refer to the shell's notion of the current job, which
5736 is the last job stopped while it was in the foreground or started
5737 in the background. The
5738 previous job may be referenced using @samp{%-}. In output
5739 pertaining to jobs (e.g., the output of the @code{jobs} command),
5740 the current job is always flagged with a @samp{+}, and the
5741 previous job with a @samp{-}.
5743 A job may also be referred to
5744 using a prefix of the name used to start it, or using a substring
5745 that appears in its command line. For example, @samp{%ce} refers
5746 to a stopped @code{ce} job. Using @samp{%?ce}, on the
5747 other hand, refers to any job containing the string @samp{ce} in
5748 its command line. If the prefix or substring matches more than one job,
5749 Bash reports an error.
5751 Simply naming a job can be used to bring it into the foreground:
5752 @samp{%1} is a synonym for @samp{fg %1}, bringing job 1 from the
5753 background into the foreground. Similarly, @samp{%1 &} resumes
5754 job 1 in the background, equivalent to @samp{bg %1}
5756 The shell learns immediately whenever a job changes state.
5757 Normally, Bash waits until it is about to print a prompt
5758 before reporting changes in a job's status so as to not interrupt
5760 If the @option{-b} option to the @code{set} builtin is enabled,
5761 Bash reports such changes immediately (@pxref{The Set Builtin}).
5762 Any trap on @code{SIGCHLD} is executed for each child process
5765 If an attempt to exit Bash is while jobs are stopped, the
5766 shell prints a message warning that there are stopped jobs.
5767 The @code{jobs} command may then be used to inspect their status.
5768 If a second attempt to exit is made without an intervening command,
5769 Bash does not print another warning, and the stopped jobs are terminated.
5771 @node Job Control Builtins
5772 @section Job Control Builtins
5781 Resume the suspended job @var{jobspec} in the background, as if it
5782 had been started with @samp{&}.
5783 If @var{jobspec} is not supplied, the current job is used.
5784 The return status is zero unless it is run when job control is not
5785 enabled, or, when run with job control enabled, if @var{jobspec} was
5786 not found or @var{jobspec} specifies a job that was started without
5794 Resume the job @var{jobspec} in the foreground and make it the current job.
5795 If @var{jobspec} is not supplied, the current job is used.
5796 The return status is that of the command placed into the foreground,
5797 or non-zero if run when job control is disabled or, when run with
5798 job control enabled, @var{jobspec} does not specify a valid job or
5799 @var{jobspec} specifies a job that was started without job control.
5804 jobs [-lnprs] [@var{jobspec}]
5805 jobs -x @var{command} [@var{arguments}]
5808 The first form lists the active jobs. The options have the
5813 List process @sc{id}s in addition to the normal information.
5816 Display information only about jobs that have changed status since
5817 the user was last notified of their status.
5820 List only the process @sc{id} of the job's process group leader.
5823 Restrict output to running jobs.
5826 Restrict output to stopped jobs.
5829 If @var{jobspec} is given,
5830 output is restricted to information about that job.
5831 If @var{jobspec} is not supplied, the status of all jobs is
5834 If the @option{-x} option is supplied, @code{jobs} replaces any
5835 @var{jobspec} found in @var{command} or @var{arguments} with the
5836 corresponding process group @sc{id}, and executes @var{command},
5837 passing it @var{argument}s, returning its exit status.
5842 kill [-s @var{sigspec}] [-n @var{signum}] [-@var{sigspec}] @var{jobspec} or @var{pid}
5843 kill -l [@var{exit_status}]
5845 Send a signal specified by @var{sigspec} or @var{signum} to the process
5846 named by job specification @var{jobspec} or process @sc{id} @var{pid}.
5847 @var{sigspec} is either a signal name such as @code{SIGINT} (with or without
5848 the @code{SIG} prefix) or a signal number; @var{signum} is a signal number.
5849 If @var{sigspec} and @var{signum} are not present, @code{SIGTERM} is used.
5850 The @option{-l} option lists the signal names.
5851 If any arguments are supplied when @option{-l} is given, the names of the
5852 signals corresponding to the arguments are listed, and the return status
5854 @var{exit_status} is a number specifying a signal number or the exit
5855 status of a process terminated by a signal.
5856 The return status is zero if at least one signal was successfully sent,
5857 or non-zero if an error occurs or an invalid option is encountered.
5862 wait [@var{jobspec} or @var{pid}]
5864 Wait until the child process specified by process @sc{id} @var{pid} or job
5865 specification @var{jobspec} exits and return the exit status of the last
5867 If a job spec is given, all processes in the job are waited for.
5868 If no arguments are given, all currently active child processes are
5869 waited for, and the return status is zero.
5870 If neither @var{jobspec} nor @var{pid} specifies an active child process
5871 of the shell, the return status is 127.
5876 disown [-ar] [-h] [@var{jobspec} @dots{}]
5878 Without options, each @var{jobspec} is removed from the table of
5880 If the @option{-h} option is given, the job is not removed from the table,
5881 but is marked so that @code{SIGHUP} is not sent to the job if the shell
5882 receives a @code{SIGHUP}.
5883 If @var{jobspec} is not present, and neither the @option{-a} nor @option{-r}
5884 option is supplied, the current job is used.
5885 If no @var{jobspec} is supplied, the @option{-a} option means to remove or
5886 mark all jobs; the @option{-r} option without a @var{jobspec}
5887 argument restricts operation to running jobs.
5894 Suspend the execution of this shell until it receives a
5895 @code{SIGCONT} signal. The @option{-f} option means to suspend
5896 even if the shell is a login shell.
5900 When job control is not active, the @code{kill} and @code{wait}
5901 builtins do not accept @var{jobspec} arguments. They must be
5902 supplied process @sc{id}s.
5904 @node Job Control Variables
5905 @section Job Control Variables
5910 This variable controls how the shell interacts with the user and
5911 job control. If this variable exists then single word simple
5912 commands without redirections are treated as candidates for resumption
5913 of an existing job. There is no ambiguity allowed; if there is
5914 more than one job beginning with the string typed, then
5915 the most recently accessed job will be selected.
5916 The name of a stopped job, in this context, is the command line
5917 used to start it. If this variable is set to the value @samp{exact},
5918 the string supplied must match the name of a stopped job exactly;
5919 if set to @samp{substring},
5920 the string supplied needs to match a substring of the name of a
5921 stopped job. The @samp{substring} value provides functionality
5922 analogous to the @samp{%?} job @sc{id} (@pxref{Job Control Basics}).
5923 If set to any other value, the supplied string must
5924 be a prefix of a stopped job's name; this provides functionality
5925 analogous to the @samp{%} job @sc{id}.
5929 @set readline-appendix
5930 @set history-appendix
5931 @cindex Readline, how to use
5932 @include rluser.texinfo
5933 @cindex History, how to use
5934 @include hsuser.texinfo
5935 @clear readline-appendix
5936 @clear history-appendix
5938 @node Installing Bash
5939 @chapter Installing Bash
5941 This chapter provides basic instructions for installing Bash on
5942 the various supported platforms. The distribution supports the
5943 @sc{gnu} operating systems, nearly every version of Unix, and several
5944 non-Unix systems such as BeOS and Interix.
5945 Other independent ports exist for
5946 @sc{ms-dos}, @sc{os/2}, Windows @sc{95/98}, and Windows @sc{nt}.
5949 * Basic Installation:: Installation instructions.
5951 * Compilers and Options:: How to set special options for various
5954 * Compiling For Multiple Architectures:: How to compile Bash for more
5955 than one kind of system from
5956 the same source tree.
5958 * Installation Names:: How to set the various paths used by the installation.
5960 * Specifying the System Type:: How to configure Bash for a particular system.
5962 * Sharing Defaults:: How to share default configuration values among GNU
5965 * Operation Controls:: Options recognized by the configuration program.
5967 * Optional Features:: How to enable and disable optional features when
5971 @node Basic Installation
5972 @section Basic Installation
5973 @cindex installation
5974 @cindex configuration
5975 @cindex Bash installation
5976 @cindex Bash configuration
5978 These are installation instructions for Bash.
5980 The simplest way to compile Bash is:
5984 @code{cd} to the directory containing the source code and type
5985 @samp{./configure} to configure Bash for your system. If you're
5986 using @code{csh} on an old version of System V, you might need to
5987 type @samp{sh ./configure} instead to prevent @code{csh} from trying
5988 to execute @code{configure} itself.
5990 Running @code{configure} takes some time.
5991 While running, it prints messages telling which features it is
5995 Type @samp{make} to compile Bash and build the @code{bashbug} bug
5999 Optionally, type @samp{make tests} to run the Bash test suite.
6002 Type @samp{make install} to install @code{bash} and @code{bashbug}.
6003 This will also install the manual pages and Info file.
6007 The @code{configure} shell script attempts to guess correct
6008 values for various system-dependent variables used during
6009 compilation. It uses those values to create a @file{Makefile} in
6010 each directory of the package (the top directory, the
6011 @file{builtins}, @file{doc}, and @file{support} directories,
6012 each directory under @file{lib}, and several others). It also creates a
6013 @file{config.h} file containing system-dependent definitions.
6014 Finally, it creates a shell script named @code{config.status} that you
6015 can run in the future to recreate the current configuration, a
6016 file @file{config.cache} that saves the results of its tests to
6017 speed up reconfiguring, and a file @file{config.log} containing
6018 compiler output (useful mainly for debugging @code{configure}).
6020 @file{config.cache} contains results you don't want to keep, you
6021 may remove or edit it.
6023 To find out more about the options and arguments that the
6024 @code{configure} script understands, type
6027 bash-2.04$ ./configure --help
6031 at the Bash prompt in your Bash source directory.
6033 If you need to do unusual things to compile Bash, please
6034 try to figure out how @code{configure} could check whether or not
6035 to do them, and mail diffs or instructions to
6036 @email{bash-maintainers@@gnu.org} so they can be
6037 considered for the next release.
6039 The file @file{configure.in} is used to create @code{configure}
6040 by a program called Autoconf. You only need
6041 @file{configure.in} if you want to change it or regenerate
6042 @code{configure} using a newer version of Autoconf. If
6043 you do this, make sure you are using Autoconf version 2.50 or
6046 You can remove the program binaries and object files from the
6047 source code directory by typing @samp{make clean}. To also remove the
6048 files that @code{configure} created (so you can compile Bash for
6049 a different kind of computer), type @samp{make distclean}.
6051 @node Compilers and Options
6052 @section Compilers and Options
6054 Some systems require unusual options for compilation or linking
6055 that the @code{configure} script does not know about. You can
6056 give @code{configure} initial values for variables by setting
6057 them in the environment. Using a Bourne-compatible shell, you
6058 can do that on the command line like this:
6061 CC=c89 CFLAGS=-O2 LIBS=-lposix ./configure
6064 On systems that have the @code{env} program, you can do it like this:
6067 env CPPFLAGS=-I/usr/local/include LDFLAGS=-s ./configure
6070 The configuration process uses GCC to build Bash if it
6073 @node Compiling For Multiple Architectures
6074 @section Compiling For Multiple Architectures
6076 You can compile Bash for more than one kind of computer at the
6077 same time, by placing the object files for each architecture in their
6078 own directory. To do this, you must use a version of @code{make} that
6079 supports the @code{VPATH} variable, such as GNU @code{make}.
6081 directory where you want the object files and executables to go and run
6082 the @code{configure} script from the source directory. You may need to
6083 supply the @option{--srcdir=PATH} argument to tell @code{configure} where the
6084 source files are. @code{configure} automatically checks for the
6085 source code in the directory that @code{configure} is in and in `..'.
6087 If you have to use a @code{make} that does not supports the @code{VPATH}
6088 variable, you can compile Bash for one architecture at a
6089 time in the source code directory. After you have installed
6090 Bash for one architecture, use @samp{make distclean} before
6091 reconfiguring for another architecture.
6093 Alternatively, if your system supports symbolic links, you can use the
6094 @file{support/mkclone} script to create a build tree which has
6095 symbolic links back to each file in the source directory. Here's an
6096 example that creates a build directory in the current directory from a
6097 source directory @file{/usr/gnu/src/bash-2.0}:
6100 bash /usr/gnu/src/bash-2.0/support/mkclone -s /usr/gnu/src/bash-2.0 .
6104 The @code{mkclone} script requires Bash, so you must have already built
6105 Bash for at least one architecture before you can create build
6106 directories for other architectures.
6108 @node Installation Names
6109 @section Installation Names
6111 By default, @samp{make install} will install into
6112 @file{/usr/local/bin}, @file{/usr/local/man}, etc. You can
6113 specify an installation prefix other than @file{/usr/local} by
6114 giving @code{configure} the option @option{--prefix=@var{PATH}},
6115 or by specifying a value for the @code{DESTDIR} @samp{make}
6116 variable when running @samp{make install}.
6118 You can specify separate installation prefixes for
6119 architecture-specific files and architecture-independent files.
6120 If you give @code{configure} the option
6121 @option{--exec-prefix=@var{PATH}}, @samp{make install} will use
6122 @var{PATH} as the prefix for installing programs and libraries.
6123 Documentation and other data files will still use the regular prefix.
6125 @node Specifying the System Type
6126 @section Specifying the System Type
6128 There may be some features @code{configure} can not figure out
6129 automatically, but need to determine by the type of host Bash
6130 will run on. Usually @code{configure} can figure that
6131 out, but if it prints a message saying it can not guess the host
6132 type, give it the @option{--host=TYPE} option. @samp{TYPE} can
6133 either be a short name for the system type, such as @samp{sun4},
6134 or a canonical name with three fields: @samp{CPU-COMPANY-SYSTEM}
6135 (e.g., @samp{i386-unknown-freebsd4.2}).
6137 See the file @file{support/config.sub} for the possible
6138 values of each field.
6140 @node Sharing Defaults
6141 @section Sharing Defaults
6143 If you want to set default values for @code{configure} scripts to
6144 share, you can create a site shell script called
6145 @code{config.site} that gives default values for variables like
6146 @code{CC}, @code{cache_file}, and @code{prefix}. @code{configure}
6147 looks for @file{PREFIX/share/config.site} if it exists, then
6148 @file{PREFIX/etc/config.site} if it exists. Or, you can set the
6149 @code{CONFIG_SITE} environment variable to the location of the site
6150 script. A warning: the Bash @code{configure} looks for a site script,
6151 but not all @code{configure} scripts do.
6153 @node Operation Controls
6154 @section Operation Controls
6156 @code{configure} recognizes the following options to control how it
6161 @item --cache-file=@var{file}
6162 Use and save the results of the tests in
6163 @var{file} instead of @file{./config.cache}. Set @var{file} to
6164 @file{/dev/null} to disable caching, for debugging
6168 Print a summary of the options to @code{configure}, and exit.
6173 Do not print messages saying which checks are being made.
6175 @item --srcdir=@var{dir}
6176 Look for the Bash source code in directory @var{dir}. Usually
6177 @code{configure} can determine that directory automatically.
6180 Print the version of Autoconf used to generate the @code{configure}
6184 @code{configure} also accepts some other, not widely used, boilerplate
6185 options. @samp{configure --help} prints the complete list.
6187 @node Optional Features
6188 @section Optional Features
6190 The Bash @code{configure} has a number of @option{--enable-@var{feature}}
6191 options, where @var{feature} indicates an optional part of Bash.
6192 There are also several @option{--with-@var{package}} options,
6193 where @var{package} is something like @samp{bash-malloc} or @samp{purify}.
6194 To turn off the default use of a package, use
6195 @option{--without-@var{package}}. To configure Bash without a feature
6196 that is enabled by default, use @option{--disable-@var{feature}}.
6198 Here is a complete list of the @option{--enable-} and
6199 @option{--with-} options that the Bash @code{configure} recognizes.
6203 Define if you are using the Andrew File System from Transarc.
6205 @item --with-bash-malloc
6206 Use the Bash version of
6207 @code{malloc} in @file{lib/malloc/malloc.c}. This is not the same
6208 @code{malloc} that appears in @sc{gnu} libc, but an older version
6209 derived from the 4.2 @sc{bsd} @code{malloc}. This @code{malloc} is
6210 very fast, but wastes some space on each allocation.
6211 This option is enabled by default.
6212 The @file{NOTES} file contains a list of systems for
6213 which this should be turned off, and @code{configure} disables this
6214 option automatically for a number of systems.
6217 Use the curses library instead of the termcap library. This should
6218 be supplied if your system has an inadequate or incomplete termcap
6221 @item --with-gnu-malloc
6222 A synonym for @code{--with-bash-malloc}.
6224 @item --with-installed-readline[=@var{PREFIX}]
6225 Define this to make Bash link with a locally-installed version of Readline
6226 rather than the version in @file{lib/readline}. This works only with
6227 Readline 4.3 and later versions. If @var{PREFIX} is @code{yes} or not
6228 supplied, @code{configure} uses the values of the make variables
6229 @code{includedir} and @code{libdir}, which are subdirectories of @code{prefix}
6230 by default, to find the installed version of Readline if it is not in
6231 the standard system include and library directories.
6232 If @var{PREFIX} is @code{no}, Bash links with the version in
6233 @file{lib/readline}.
6234 If @var{PREFIX} is set to any other value, @code{configure} treats it as
6235 a directory pathname and looks for
6236 the installed version of Readline in subdirectories of that directory
6237 (include files in @var{PREFIX}/@code{include} and the library in
6238 @var{PREFIX}/@code{lib}).
6241 Define this to use the Purify memory allocation checker from Rational
6244 @item --enable-minimal-config
6245 This produces a shell with minimal features, close to the historical
6249 There are several @option{--enable-} options that alter how Bash is
6250 compiled and linked, rather than changing run-time features.
6253 @item --enable-largefile
6254 Enable support for @uref{http://www.sas.com/standards/large_file/x_open.20Mar96.html,
6255 large files} if the operating system requires special compiler options
6256 to build programs which can access large files. This is enabled by
6257 default, if the operating system provides large file support.
6259 @item --enable-profiling
6260 This builds a Bash binary that produces profiling information to be
6261 processed by @code{gprof} each time it is executed.
6263 @item --enable-static-link
6264 This causes Bash to be linked statically, if @code{gcc} is being used.
6265 This could be used to build a version to use as root's shell.
6268 The @samp{minimal-config} option can be used to disable all of
6269 the following options, but it is processed first, so individual
6270 options may be enabled using @samp{enable-@var{feature}}.
6272 All of the following options except for @samp{disabled-builtins} and
6273 @samp{xpg-echo-default} are
6274 enabled by default, unless the operating system does not provide the
6278 @item --enable-alias
6279 Allow alias expansion and include the @code{alias} and @code{unalias}
6280 builtins (@pxref{Aliases}).
6282 @item --enable-arith-for-command
6283 Include support for the alternate form of the @code{for} command
6284 that behaves like the C language @code{for} statement
6285 (@pxref{Looping Constructs}).
6287 @item --enable-array-variables
6288 Include support for one-dimensional array shell variables
6291 @item --enable-bang-history
6292 Include support for @code{csh}-like history substitution
6293 (@pxref{History Interaction}).
6295 @item --enable-brace-expansion
6296 Include @code{csh}-like brace expansion
6297 ( @code{b@{a,b@}c} @expansion{} @code{bac bbc} ).
6298 See @ref{Brace Expansion}, for a complete description.
6300 @item --enable-command-timing
6301 Include support for recognizing @code{time} as a reserved word and for
6302 displaying timing statistics for the pipeline following @code{time}
6303 (@pxref{Pipelines}).
6304 This allows pipelines as well as shell builtins and functions to be timed.
6306 @item --enable-cond-command
6307 Include support for the @code{[[} conditional command
6308 (@pxref{Conditional Constructs}).
6310 @item --enable-directory-stack
6311 Include support for a @code{csh}-like directory stack and the
6312 @code{pushd}, @code{popd}, and @code{dirs} builtins
6313 (@pxref{The Directory Stack}).
6315 @item --enable-disabled-builtins
6316 Allow builtin commands to be invoked via @samp{builtin xxx}
6317 even after @code{xxx} has been disabled using @samp{enable -n xxx}.
6318 See @ref{Bash Builtins}, for details of the @code{builtin} and
6319 @code{enable} builtin commands.
6321 @item --enable-dparen-arithmetic
6322 Include support for the @code{((@dots{}))} command
6323 (@pxref{Conditional Constructs}).
6325 @item --enable-extended-glob
6326 Include support for the extended pattern matching features described
6327 above under @ref{Pattern Matching}.
6329 @item --enable-help-builtin
6330 Include the @code{help} builtin, which displays help on shell builtins and
6331 variables (@pxref{Bash Builtins}).
6333 @item --enable-history
6334 Include command history and the @code{fc} and @code{history}
6335 builtin commands (@pxref{Bash History Facilities}).
6337 @item --enable-job-control
6338 This enables the job control features (@pxref{Job Control}),
6339 if the operating system supports them.
6341 @item --enable-net-redirections
6342 This enables the special handling of filenames of the form
6343 @code{/dev/tcp/@var{host}/@var{port}} and
6344 @code{/dev/udp/@var{host}/@var{port}}
6345 when used in redirections (@pxref{Redirections}).
6347 @item --enable-process-substitution
6348 This enables process substitution (@pxref{Process Substitution}) if
6349 the operating system provides the necessary support.
6351 @item --enable-prompt-string-decoding
6352 Turn on the interpretation of a number of backslash-escaped characters
6353 in the @env{$PS1}, @env{$PS2}, @env{$PS3}, and @env{$PS4} prompt
6354 strings. See @ref{Printing a Prompt}, for a complete list of prompt
6355 string escape sequences.
6357 @item --enable-progcomp
6358 Enable the programmable completion facilities
6359 (@pxref{Programmable Completion}).
6360 If Readline is not enabled, this option has no effect.
6362 @item --enable-readline
6363 Include support for command-line editing and history with the Bash
6364 version of the Readline library (@pxref{Command Line Editing}).
6366 @item --enable-restricted
6367 Include support for a @dfn{restricted shell}. If this is enabled, Bash,
6368 when called as @code{rbash}, enters a restricted mode. See
6369 @ref{The Restricted Shell}, for a description of restricted mode.
6371 @item --enable-select
6372 Include the @code{select} builtin, which allows the generation of simple
6373 menus (@pxref{Conditional Constructs}).
6375 @item --enable-usg-echo-default
6376 A synonym for @code{--enable-xpg-echo-default}.
6378 @item --enable-xpg-echo-default
6379 Make the @code{echo} builtin expand backslash-escaped characters by default,
6380 without requiring the @option{-e} option.
6381 This sets the default value of the @code{xpg_echo} shell option to @code{on},
6382 which makes the Bash @code{echo} behave more like the version specified in
6383 the Single Unix Specification, version 2.
6384 @xref{Bash Builtins}, for a description of the escape sequences that
6385 @code{echo} recognizes.
6389 The file @file{config-top.h} contains C Preprocessor
6390 @samp{#define} statements for options which are not settable from
6392 Some of these are not meant to be changed; beware of the consequences if
6394 Read the comments associated with each definition for more
6395 information about its effect.
6397 @node Reporting Bugs
6398 @appendix Reporting Bugs
6400 Please report all bugs you find in Bash.
6401 But first, you should
6402 make sure that it really is a bug, and that it appears in the latest
6403 version of Bash that you have.
6405 Once you have determined that a bug actually exists, use the
6406 @code{bashbug} command to submit a bug report.
6407 If you have a fix, you are encouraged to mail that as well!
6408 Suggestions and `philosophical' bug reports may be mailed
6409 to @email{bug-bash@@gnu.org} or posted to the Usenet
6410 newsgroup @code{gnu.bash.bug}.
6412 All bug reports should include:
6415 The version number of Bash.
6417 The hardware and operating system.
6419 The compiler used to compile Bash.
6421 A description of the bug behaviour.
6423 A short script or `recipe' which exercises the bug and may be used
6428 @code{bashbug} inserts the first three items automatically into
6429 the template it provides for filing a bug report.
6431 Please send all reports concerning this manual to
6432 @email{chet@@po.CWRU.Edu}.
6434 @node Major Differences From The Bourne Shell
6435 @appendix Major Differences From The Bourne Shell
6437 Bash implements essentially the same grammar, parameter and
6438 variable expansion, redirection, and quoting as the Bourne Shell.
6439 Bash uses the @sc{posix} 1003.2 standard as the specification of
6440 how these features are to be implemented. There are some
6441 differences between the traditional Bourne shell and Bash; this
6442 section quickly details the differences of significance. A
6443 number of these differences are explained in greater depth in
6445 This section uses the version of @code{sh} included in SVR4.2 as
6446 the baseline reference.
6451 Bash is @sc{posix}-conformant, even where the @sc{posix} specification
6452 differs from traditional @code{sh} behavior (@pxref{Bash POSIX Mode}).
6455 Bash has multi-character invocation options (@pxref{Invoking Bash}).
6458 Bash has command-line editing (@pxref{Command Line Editing}) and
6459 the @code{bind} builtin.
6462 Bash provides a programmable word completion mechanism
6463 (@pxref{Programmable Completion}), and two builtin commands,
6464 @code{complete} and @code{compgen}, to manipulate it.
6467 Bash has command history (@pxref{Bash History Facilities}) and the
6468 @code{history} and @code{fc} builtins to manipulate it.
6471 Bash implements @code{csh}-like history expansion
6472 (@pxref{History Interaction}).
6475 Bash has one-dimensional array variables (@pxref{Arrays}), and the
6476 appropriate variable expansions and assignment syntax to use them.
6477 Several of the Bash builtins take options to act on arrays.
6478 Bash provides a number of built-in array variables.
6481 The @code{$'@dots{}'} quoting syntax, which expands ANSI-C
6482 backslash-escaped characters in the text between the single quotes,
6483 is supported (@pxref{ANSI-C Quoting}).
6486 Bash supports the @code{$"@dots{}"} quoting syntax to do
6487 locale-specific translation of the characters between the double
6488 quotes. The @option{-D}, @option{--dump-strings}, and @option{--dump-po-strings}
6489 invocation options list the translatable strings found in a script
6490 (@pxref{Locale Translation}).
6493 Bash implements the @code{!} keyword to negate the return value of
6494 a pipeline (@pxref{Pipelines}).
6495 Very useful when an @code{if} statement needs to act only if a test fails.
6498 Bash has the @code{time} reserved word and command timing (@pxref{Pipelines}).
6499 The display of the timing statistics may be controlled with the
6500 @env{TIMEFORMAT} variable.
6503 Bash implements the @code{for (( @var{expr1} ; @var{expr2} ; @var{expr3} ))}
6504 arithmetic for command, similar to the C language (@pxref{Looping Constructs}).
6507 Bash includes the @code{select} compound command, which allows the
6508 generation of simple menus (@pxref{Conditional Constructs}).
6511 Bash includes the @code{[[} compound command, which makes conditional
6512 testing part of the shell grammar (@pxref{Conditional Constructs}).
6515 Bash includes brace expansion (@pxref{Brace Expansion}) and tilde
6516 expansion (@pxref{Tilde Expansion}).
6519 Bash implements command aliases and the @code{alias} and @code{unalias}
6520 builtins (@pxref{Aliases}).
6523 Bash provides shell arithmetic, the @code{((} compound command
6524 (@pxref{Conditional Constructs}),
6525 and arithmetic expansion (@pxref{Shell Arithmetic}).
6528 Variables present in the shell's initial environment are automatically
6529 exported to child processes. The Bourne shell does not normally do
6530 this unless the variables are explicitly marked using the @code{export}
6534 Bash includes the @sc{posix} pattern removal @samp{%}, @samp{#}, @samp{%%}
6535 and @samp{##} expansions to remove leading or trailing substrings from
6536 variable values (@pxref{Shell Parameter Expansion}).
6539 The expansion @code{$@{#xx@}}, which returns the length of @code{$@{xx@}},
6540 is supported (@pxref{Shell Parameter Expansion}).
6543 The expansion @code{$@{var:}@var{offset}@code{[:}@var{length}@code{]@}},
6544 which expands to the substring of @code{var}'s value of length
6545 @var{length}, beginning at @var{offset}, is present
6546 (@pxref{Shell Parameter Expansion}).
6550 @code{$@{var/[/]}@var{pattern}@code{[/}@var{replacement}@code{]@}},
6551 which matches @var{pattern} and replaces it with @var{replacement} in
6552 the value of @code{var}, is available (@pxref{Shell Parameter Expansion}).
6555 The expansion @code{$@{!@var{prefix@}*}} expansion, which expands to
6556 the names of all shell variables whose names begin with @var{prefix},
6557 is available (@pxref{Shell Parameter Expansion}).
6560 Bash has @var{indirect} variable expansion using @code{$@{!word@}}
6561 (@pxref{Shell Parameter Expansion}).
6564 Bash can expand positional parameters beyond @code{$9} using
6565 @code{$@{@var{num}@}}.
6568 The @sc{posix} @code{$()} form of command substitution
6569 is implemented (@pxref{Command Substitution}),
6570 and preferred to the Bourne shell's @code{``} (which
6571 is also implemented for backwards compatibility).
6574 Bash has process substitution (@pxref{Process Substitution}).
6577 Bash automatically assigns variables that provide information about the
6578 current user (@env{UID}, @env{EUID}, and @env{GROUPS}), the current host
6579 (@env{HOSTTYPE}, @env{OSTYPE}, @env{MACHTYPE}, and @env{HOSTNAME}),
6580 and the instance of Bash that is running (@env{BASH},
6581 @env{BASH_VERSION}, and @env{BASH_VERSINFO}). @xref{Bash Variables},
6585 The @env{IFS} variable is used to split only the results of expansion,
6586 not all words (@pxref{Word Splitting}).
6587 This closes a longstanding shell security hole.
6590 Bash implements the full set of @sc{posix} 1003.2 filename expansion operators,
6591 including @var{character classes}, @var{equivalence classes}, and
6592 @var{collating symbols} (@pxref{Filename Expansion}).
6595 Bash implements extended pattern matching features when the @code{extglob}
6596 shell option is enabled (@pxref{Pattern Matching}).
6599 It is possible to have a variable and a function with the same name;
6600 @code{sh} does not separate the two name spaces.
6603 Bash functions are permitted to have local variables using the
6604 @code{local} builtin, and thus useful recursive functions may be written
6605 (@pxref{Bash Builtins}).
6608 Variable assignments preceding commands affect only that command, even
6609 builtins and functions (@pxref{Environment}).
6610 In @code{sh}, all variable assignments
6611 preceding commands are global unless the command is executed from the
6615 Bash performs filename expansion on filenames specified as operands
6616 to input and output redirection operators (@pxref{Redirections}).
6619 Bash contains the @samp{<>} redirection operator, allowing a file to be
6620 opened for both reading and writing, and the @samp{&>} redirection
6621 operator, for directing standard output and standard error to the same
6622 file (@pxref{Redirections}).
6625 Bash treats a number of filenames specially when they are
6626 used in redirection operators (@pxref{Redirections}).
6629 Bash can open network connections to arbitrary machines and services
6630 with the redirection operators (@pxref{Redirections}).
6633 The @code{noclobber} option is available to avoid overwriting existing
6634 files with output redirection (@pxref{The Set Builtin}).
6635 The @samp{>|} redirection operator may be used to override @code{noclobber}.
6638 The Bash @code{cd} and @code{pwd} builtins (@pxref{Bourne Shell Builtins})
6639 each take @option{-L} and @option{-P} options to switch between logical and
6643 Bash allows a function to override a builtin with the same name, and provides
6644 access to that builtin's functionality within the function via the
6645 @code{builtin} and @code{command} builtins (@pxref{Bash Builtins}).
6648 The @code{command} builtin allows selective disabling of functions
6649 when command lookup is performed (@pxref{Bash Builtins}).
6652 Individual builtins may be enabled or disabled using the @code{enable}
6653 builtin (@pxref{Bash Builtins}).
6656 The Bash @code{exec} builtin takes additional options that allow users
6657 to control the contents of the environment passed to the executed
6658 command, and what the zeroth argument to the command is to be
6659 (@pxref{Bourne Shell Builtins}).
6662 Shell functions may be exported to children via the environment
6663 using @code{export -f} (@pxref{Shell Functions}).
6666 The Bash @code{export}, @code{readonly}, and @code{declare} builtins can
6667 take a @option{-f} option to act on shell functions, a @option{-p} option to
6668 display variables with various attributes set in a format that can be
6669 used as shell input, a @option{-n} option to remove various variable
6670 attributes, and @samp{name=value} arguments to set variable attributes
6671 and values simultaneously.
6674 The Bash @code{hash} builtin allows a name to be associated with
6675 an arbitrary filename, even when that filename cannot be found by
6676 searching the @env{$PATH}, using @samp{hash -p}
6677 (@pxref{Bourne Shell Builtins}).
6680 Bash includes a @code{help} builtin for quick reference to shell
6681 facilities (@pxref{Bash Builtins}).
6684 The @code{printf} builtin is available to display formatted output
6685 (@pxref{Bash Builtins}).
6688 The Bash @code{read} builtin (@pxref{Bash Builtins})
6689 will read a line ending in @samp{\} with
6690 the @option{-r} option, and will use the @env{REPLY} variable as a
6691 default if no non-option arguments are supplied.
6692 The Bash @code{read} builtin
6693 also accepts a prompt string with the @option{-p} option and will use
6694 Readline to obtain the line when given the @option{-e} option.
6695 The @code{read} builtin also has additional options to control input:
6696 the @option{-s} option will turn off echoing of input characters as
6697 they are read, the @option{-t} option will allow @code{read} to time out
6698 if input does not arrive within a specified number of seconds, the
6699 @option{-n} option will allow reading only a specified number of
6700 characters rather than a full line, and the @option{-d} option will read
6701 until a particular character rather than newline.
6704 The @code{return} builtin may be used to abort execution of scripts
6705 executed with the @code{.} or @code{source} builtins
6706 (@pxref{Bourne Shell Builtins}).
6709 Bash includes the @code{shopt} builtin, for finer control of shell
6710 optional capabilities (@pxref{Bash Builtins}), and allows these options
6711 to be set and unset at shell invocation (@pxref{Invoking Bash}).
6714 Bash has much more optional behavior controllable with the @code{set}
6715 builtin (@pxref{The Set Builtin}).
6718 The @code{test} builtin (@pxref{Bourne Shell Builtins})
6719 is slightly different, as it implements the @sc{posix} algorithm,
6720 which specifies the behavior based on the number of arguments.
6723 The @code{trap} builtin (@pxref{Bourne Shell Builtins}) allows a
6724 @code{DEBUG} pseudo-signal specification, similar to @code{EXIT}.
6725 Commands specified with a @code{DEBUG} trap are executed after every
6727 The @code{DEBUG} trap is not inherited by shell functions unless the
6728 function has been given the @code{trace} attribute.
6730 The @code{trap} builtin (@pxref{Bourne Shell Builtins}) allows an
6731 @code{ERR} pseudo-signal specification, similar to @code{EXIT} and @code{DEBUG}.
6732 Commands specified with an @code{ERR} trap are executed after a simple
6733 command fails, with a few exceptions.
6734 The @code{ERR} trap is not inherited by shell functions.
6737 The Bash @code{type} builtin is more extensive and gives more information
6738 about the names it finds (@pxref{Bash Builtins}).
6741 The Bash @code{umask} builtin permits a @option{-p} option to cause
6742 the output to be displayed in the form of a @code{umask} command
6743 that may be reused as input (@pxref{Bourne Shell Builtins}).
6746 Bash implements a @code{csh}-like directory stack, and provides the
6747 @code{pushd}, @code{popd}, and @code{dirs} builtins to manipulate it
6748 (@pxref{The Directory Stack}).
6749 Bash also makes the directory stack visible as the value of the
6750 @env{DIRSTACK} shell variable.
6753 Bash interprets special backslash-escaped characters in the prompt
6754 strings when interactive (@pxref{Printing a Prompt}).
6757 The Bash restricted mode is more useful (@pxref{The Restricted Shell});
6758 the SVR4.2 shell restricted mode is too limited.
6761 The @code{disown} builtin can remove a job from the internal shell
6762 job table (@pxref{Job Control Builtins}) or suppress the sending
6763 of @code{SIGHUP} to a job when the shell exits as the result of a
6767 The SVR4.2 shell has two privilege-related builtins
6768 (@code{mldmode} and @code{priv}) not present in Bash.
6771 Bash does not have the @code{stop} or @code{newgrp} builtins.
6774 Bash does not use the @env{SHACCT} variable or perform shell accounting.
6777 The SVR4.2 @code{sh} uses a @env{TIMEOUT} variable like Bash uses
6783 More features unique to Bash may be found in @ref{Bash Features}.
6786 @appendixsec Implementation Differences From The SVR4.2 Shell
6788 Since Bash is a completely new implementation, it does not suffer from
6789 many of the limitations of the SVR4.2 shell. For instance:
6794 Bash does not fork a subshell when redirecting into or out of
6795 a shell control structure such as an @code{if} or @code{while}
6799 Bash does not allow unbalanced quotes. The SVR4.2 shell will silently
6800 insert a needed closing quote at @code{EOF} under certain circumstances.
6801 This can be the cause of some hard-to-find errors.
6804 The SVR4.2 shell uses a baroque memory management scheme based on
6805 trapping @code{SIGSEGV}. If the shell is started from a process with
6806 @code{SIGSEGV} blocked (e.g., by using the @code{system()} C library
6807 function call), it misbehaves badly.
6810 In a questionable attempt at security, the SVR4.2 shell,
6811 when invoked without the @option{-p} option, will alter its real
6812 and effective @sc{uid} and @sc{gid} if they are less than some
6813 magic threshold value, commonly 100.
6814 This can lead to unexpected results.
6817 The SVR4.2 shell does not allow users to trap @code{SIGSEGV},
6818 @code{SIGALRM}, or @code{SIGCHLD}.
6821 The SVR4.2 shell does not allow the @env{IFS}, @env{MAILCHECK},
6822 @env{PATH}, @env{PS1}, or @env{PS2} variables to be unset.
6825 The SVR4.2 shell treats @samp{^} as the undocumented equivalent of
6829 Bash allows multiple option arguments when it is invoked (@code{-x -v});
6830 the SVR4.2 shell allows only one option argument (@code{-xv}). In
6831 fact, some versions of the shell dump core if the second argument begins
6835 The SVR4.2 shell exits a script if any builtin fails; Bash exits
6836 a script only if one of the @sc{posix} 1003.2 special builtins fails, and
6837 only for certain failures, as enumerated in the @sc{posix} 1003.2 standard.
6840 The SVR4.2 shell behaves differently when invoked as @code{jsh}
6841 (it turns on job control).
6845 @unnumbered Index of Shell Builtin Commands
6848 @node Reserved Word Index
6849 @unnumbered Index of Shell Reserved Words
6852 @node Variable Index
6853 @unnumbered Parameter and Variable Index
6856 @node Function Index
6857 @unnumbered Function Index
6861 @unnumbered Concept Index