1 \input texinfo.tex @c -*- texinfo -*-
3 @setfilename bashref.info
4 @settitle Bash Reference Manual
10 This text is a brief description of the features that are present in
11 the Bash shell (version @value{VERSION}, @value{UPDATED}).
13 This is Edition @value{EDITION}, last updated @value{UPDATED},
14 of @cite{The GNU Bash Reference Manual},
15 for @code{Bash}, Version @value{VERSION}.
17 Copyright @copyright{} 1988--2016 Free Software Foundation, Inc.
20 Permission is granted to copy, distribute and/or modify this document
21 under the terms of the GNU Free Documentation License, Version 1.3 or
22 any later version published by the Free Software Foundation; with no
23 Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
24 A copy of the license is included in the section entitled
25 ``GNU Free Documentation License''.
35 * Bash: (bash). The GNU Bourne-Again SHell.
41 @title Bash Reference Manual
42 @subtitle Reference Documentation for Bash
43 @subtitle Edition @value{EDITION}, for @code{Bash} Version @value{VERSION}.
44 @subtitle @value{UPDATED-MONTH}
45 @author Chet Ramey, Case Western Reserve University
46 @author Brian Fox, Free Software Foundation
49 @vskip 0pt plus 1filll
57 @node Top, Introduction, (dir), (dir)
60 This text is a brief description of the features that are present in
61 the Bash shell (version @value{VERSION}, @value{UPDATED}).
62 The Bash home page is @url{http://www.gnu.org/software/bash/}.
64 This is Edition @value{EDITION}, last updated @value{UPDATED},
65 of @cite{The GNU Bash Reference Manual},
66 for @code{Bash}, Version @value{VERSION}.
68 Bash contains features that appear in other popular shells, and some
69 features that only appear in Bash. Some of the shells that Bash has
70 borrowed concepts from are the Bourne Shell (@file{sh}), the Korn Shell
71 (@file{ksh}), and the C-shell (@file{csh} and its successor,
72 @file{tcsh}). The following menu breaks the features up into
73 categories, noting which features were inspired by other shells and
74 which are specific to Bash.
76 This manual is meant as a brief introduction to features found in
77 Bash. The Bash manual page should be used as the definitive
78 reference on shell behavior.
81 * Introduction:: An introduction to the shell.
82 * Definitions:: Some definitions used in the rest of this
84 * Basic Shell Features:: The shell "building blocks".
85 * Shell Builtin Commands:: Commands that are a part of the shell.
86 * Shell Variables:: Variables used or set by Bash.
87 * Bash Features:: Features found only in Bash.
88 * Job Control:: What job control is and how Bash allows you
90 * Command Line Editing:: Chapter describing the command line
92 * Using History Interactively:: Command History Expansion
93 * Installing Bash:: How to build and install Bash on your system.
94 * Reporting Bugs:: How to report bugs in Bash.
95 * Major Differences From The Bourne Shell:: A terse list of the differences
96 between Bash and historical
98 * GNU Free Documentation License:: Copying and sharing this documentation.
99 * Indexes:: Various indexes for this manual.
104 @chapter Introduction
106 * What is Bash?:: A short description of Bash.
107 * What is a shell?:: A brief introduction to shells.
111 @section What is Bash?
113 Bash is the shell, or command language interpreter,
114 for the @sc{gnu} operating system.
115 The name is an acronym for the @samp{Bourne-Again SHell},
116 a pun on Stephen Bourne, the author of the direct ancestor of
117 the current Unix shell @code{sh},
118 which appeared in the Seventh Edition Bell Labs Research version
121 Bash is largely compatible with @code{sh} and incorporates useful
122 features from the Korn shell @code{ksh} and the C shell @code{csh}.
123 It is intended to be a conformant implementation of the @sc{ieee}
124 @sc{posix} Shell and Tools portion of the @sc{ieee} @sc{posix}
125 specification (@sc{ieee} Standard 1003.1).
126 It offers functional improvements over @code{sh} for both interactive and
129 While the @sc{gnu} operating system provides other shells, including
130 a version of @code{csh}, Bash is the default shell.
131 Like other @sc{gnu} software, Bash is quite portable. It currently runs
132 on nearly every version of Unix and a few other operating systems @minus{}
133 independently-supported ports exist for @sc{ms-dos}, @sc{os/2},
134 and Windows platforms.
136 @node What is a shell?
137 @section What is a shell?
139 At its base, a shell is simply a macro processor that executes
140 commands. The term macro processor means functionality where text
141 and symbols are expanded to create larger expressions.
143 A Unix shell is both a command interpreter and a programming
144 language. As a command interpreter, the shell provides the user
145 interface to the rich set of @sc{gnu} utilities. The programming
146 language features allow these utilities to be combined.
147 Files containing commands can be created, and become
148 commands themselves. These new commands have the same status as
149 system commands in directories such as @file{/bin}, allowing users
150 or groups to establish custom environments to automate their common
153 Shells may be used interactively or non-interactively. In
154 interactive mode, they accept input typed from the keyboard.
155 When executing non-interactively, shells execute commands read
158 A shell allows execution of @sc{gnu} commands, both synchronously and
160 The shell waits for synchronous commands to complete before accepting
161 more input; asynchronous commands continue to execute in parallel
162 with the shell while it reads and executes additional commands.
163 The @dfn{redirection} constructs permit
164 fine-grained control of the input and output of those commands.
165 Moreover, the shell allows control over the contents of commands'
168 Shells also provide a small set of built-in
169 commands (@dfn{builtins}) implementing functionality impossible
170 or inconvenient to obtain via separate utilities.
171 For example, @code{cd}, @code{break}, @code{continue}, and
172 @code{exec} cannot be implemented outside of the shell because
173 they directly manipulate the shell itself.
174 The @code{history}, @code{getopts}, @code{kill}, or @code{pwd}
175 builtins, among others, could be implemented in separate utilities,
176 but they are more convenient to use as builtin commands.
177 All of the shell builtins are described in
180 While executing commands is essential, most of the power (and
181 complexity) of shells is due to their embedded programming
182 languages. Like any high-level language, the shell provides
183 variables, flow control constructs, quoting, and functions.
185 Shells offer features geared specifically for
186 interactive use rather than to augment the programming language.
187 These interactive features include job control, command line
188 editing, command history and aliases. Each of these features is
189 described in this manual.
193 These definitions are used throughout the remainder of this manual.
199 A family of open system standards based on Unix. Bash
200 is primarily concerned with the Shell and Utilities portion of the
201 @sc{posix} 1003.1 standard.
204 A space or tab character.
208 A command that is implemented internally by the shell itself, rather
209 than by an executable program somewhere in the file system.
211 @item control operator
212 @cindex control operator
213 A @code{token} that performs a control function. It is a @code{newline}
214 or one of the following:
215 @samp{||}, @samp{&&}, @samp{&}, @samp{;}, @samp{;;}, @samp{;&}, @samp{;;&},
216 @samp{|}, @samp{|&}, @samp{(}, or @samp{)}.
220 The value returned by a command to its caller. The value is restricted
221 to eight bits, so the maximum value is 255.
225 A unit of text that is the result of one of the shell expansions. After
226 expansion, when executing a command, the resulting fields are used as
227 the command name and arguments.
231 A string of characters used to identify a file.
235 A set of processes comprising a pipeline, and any processes descended
236 from it, that are all in the same process group.
240 A mechanism by which users can selectively stop (suspend) and restart
241 (resume) execution of processes.
244 @cindex metacharacter
245 A character that, when unquoted, separates words. A metacharacter is
246 a @code{space}, @code{tab}, @code{newline}, or one of the following characters:
247 @samp{|}, @samp{&}, @samp{;}, @samp{(}, @samp{)}, @samp{<}, or
253 A @code{word} consisting solely of letters, numbers, and underscores,
254 and beginning with a letter or underscore. @code{Name}s are used as
255 shell variable and function names.
256 Also referred to as an @code{identifier}.
259 @cindex operator, shell
260 A @code{control operator} or a @code{redirection operator}.
261 @xref{Redirections}, for a list of redirection operators.
262 Operators contain at least one unquoted @code{metacharacter}.
265 @cindex process group
266 A collection of related processes each having the same process
269 @item process group ID
270 @cindex process group ID
271 A unique identifier that represents a @code{process group}
275 @cindex reserved word
276 A @code{word} that has a special meaning to the shell. Most reserved
277 words introduce shell flow control constructs, such as @code{for} and
281 @cindex return status
282 A synonym for @code{exit status}.
286 A mechanism by which a process may be notified by the kernel
287 of an event occurring in the system.
289 @item special builtin
290 @cindex special builtin
291 A shell builtin command that has been classified as special by the
296 A sequence of characters considered a single unit by the shell.
297 It is either a @code{word} or an @code{operator}.
301 A sequence of characters treated as a unit by the shell.
302 Words may not include unquoted @code{metacharacters}.
305 @node Basic Shell Features
306 @chapter Basic Shell Features
309 Bash is an acronym for @samp{Bourne-Again SHell}.
311 the traditional Unix shell originally written by Stephen Bourne.
312 All of the Bourne shell builtin commands are available in Bash,
313 The rules for evaluation and quoting are taken from the @sc{posix}
314 specification for the `standard' Unix shell.
316 This chapter briefly summarizes the shell's `building blocks':
317 commands, control structures, shell functions, shell @i{parameters},
319 @i{redirections}, which are a way to direct input and output from
320 and to named files, and how the shell executes commands.
323 * Shell Syntax:: What your input means to the shell.
324 * Shell Commands:: The types of commands you can use.
325 * Shell Functions:: Grouping commands by name.
326 * Shell Parameters:: How the shell stores values.
327 * Shell Expansions:: How Bash expands parameters and the various
328 expansions available.
329 * Redirections:: A way to control where input and output go.
330 * Executing Commands:: What happens when you run a command.
331 * Shell Scripts:: Executing files of shell commands.
335 @section Shell Syntax
337 * Shell Operation:: The basic operation of the shell.
338 * Quoting:: How to remove the special meaning from characters.
339 * Comments:: How to specify comments.
342 When the shell reads input, it proceeds through a
343 sequence of operations. If the input indicates the beginning of a
344 comment, the shell ignores the comment symbol (@samp{#}), and the rest
347 Otherwise, roughly speaking, the shell reads its input and
348 divides the input into words and operators, employing the quoting rules
349 to select which meanings to assign various words and characters.
351 The shell then parses these tokens into commands and other constructs,
352 removes the special meaning of certain words or characters, expands
353 others, redirects input and output as needed, executes the specified
354 command, waits for the command's exit status, and makes that exit status
355 available for further inspection or processing.
357 @node Shell Operation
358 @subsection Shell Operation
360 The following is a brief description of the shell's operation when it
361 reads and executes a command. Basically, the shell does the
366 Reads its input from a file (@pxref{Shell Scripts}), from a string
367 supplied as an argument to the @option{-c} invocation option
368 (@pxref{Invoking Bash}), or from the user's terminal.
371 Breaks the input into words and operators, obeying the quoting rules
372 described in @ref{Quoting}. These tokens are separated by
373 @code{metacharacters}. Alias expansion is performed by this step
377 Parses the tokens into simple and compound commands
378 (@pxref{Shell Commands}).
381 Performs the various shell expansions (@pxref{Shell Expansions}), breaking
382 the expanded tokens into lists of filenames (@pxref{Filename Expansion})
383 and commands and arguments.
386 Performs any necessary redirections (@pxref{Redirections}) and removes
387 the redirection operators and their operands from the argument list.
390 Executes the command (@pxref{Executing Commands}).
393 Optionally waits for the command to complete and collects its exit
394 status (@pxref{Exit Status}).
402 * Escape Character:: How to remove the special meaning from a single
404 * Single Quotes:: How to inhibit all interpretation of a sequence
406 * Double Quotes:: How to suppress most of the interpretation of a
407 sequence of characters.
408 * ANSI-C Quoting:: How to expand ANSI-C sequences in quoted strings.
409 * Locale Translation:: How to translate strings into different languages.
412 Quoting is used to remove the special meaning of certain
413 characters or words to the shell. Quoting can be used to
414 disable special treatment for special characters, to prevent
415 reserved words from being recognized as such, and to prevent
418 Each of the shell metacharacters (@pxref{Definitions})
419 has special meaning to the shell and must be quoted if it is to
421 When the command history expansion facilities are being used
422 (@pxref{History Interaction}), the
423 @var{history expansion} character, usually @samp{!}, must be quoted
424 to prevent history expansion. @xref{Bash History Facilities}, for
425 more details concerning history expansion.
427 There are three quoting mechanisms: the
428 @var{escape character}, single quotes, and double quotes.
430 @node Escape Character
431 @subsubsection Escape Character
432 A non-quoted backslash @samp{\} is the Bash escape character.
433 It preserves the literal value of the next character that follows,
434 with the exception of @code{newline}. If a @code{\newline} pair
435 appears, and the backslash itself is not quoted, the @code{\newline}
436 is treated as a line continuation (that is, it is removed from
437 the input stream and effectively ignored).
440 @subsubsection Single Quotes
442 Enclosing characters in single quotes (@samp{'}) preserves the literal value
443 of each character within the quotes. A single quote may not occur
444 between single quotes, even when preceded by a backslash.
447 @subsubsection Double Quotes
449 Enclosing characters in double quotes (@samp{"}) preserves the literal value
450 of all characters within the quotes, with the exception of
451 @samp{$}, @samp{`}, @samp{\},
452 and, when history expansion is enabled, @samp{!}.
454 @sc{posix} mode (@pxref{Bash POSIX Mode}),
455 the @samp{!} has no special meaning
456 within double quotes, even when history expansion is enabled.
457 The characters @samp{$} and @samp{`}
458 retain their special meaning within double quotes (@pxref{Shell Expansions}).
459 The backslash retains its special meaning only when followed by one of
460 the following characters:
461 @samp{$}, @samp{`}, @samp{"}, @samp{\}, or @code{newline}.
462 Within double quotes, backslashes that are followed by one of these
463 characters are removed. Backslashes preceding characters without a
464 special meaning are left unmodified.
465 A double quote may be quoted within double quotes by preceding it with
467 If enabled, history expansion will be performed unless an @samp{!}
468 appearing in double quotes is escaped using a backslash.
469 The backslash preceding the @samp{!} is not removed.
471 The special parameters @samp{*} and @samp{@@} have special meaning
472 when in double quotes (@pxref{Shell Parameter Expansion}).
475 @subsubsection ANSI-C Quoting
476 @cindex quoting, ANSI
478 Words of the form @code{$'@var{string}'} are treated specially. The
479 word expands to @var{string}, with backslash-escaped characters replaced
480 as specified by the ANSI C standard. Backslash escape sequences, if
481 present, are decoded as follows:
490 an escape character (not ANSI C)
510 the eight-bit character whose value is the octal value @var{nnn}
511 (one to three digits)
513 the eight-bit character whose value is the hexadecimal value @var{HH}
514 (one or two hex digits)
516 the Unicode (ISO/IEC 10646) character whose value is the hexadecimal value
517 @var{HHHH} (one to four hex digits)
518 @item \U@var{HHHHHHHH}
519 the Unicode (ISO/IEC 10646) character whose value is the hexadecimal value
520 @var{HHHHHHHH} (one to eight hex digits)
522 a control-@var{x} character
526 The expanded result is single-quoted, as if the dollar sign had not
529 @node Locale Translation
530 @subsubsection Locale-Specific Translation
532 @cindex internationalization
533 @cindex native languages
534 @cindex translation, native languages
536 A double-quoted string preceded by a dollar sign (@samp{$}) will cause
537 the string to be translated according to the current locale.
538 If the current locale is @code{C} or @code{POSIX}, the dollar sign
540 If the string is translated and replaced, the replacement is
545 @vindex TEXTDOMAINDIR
546 Some systems use the message catalog selected by the @env{LC_MESSAGES}
547 shell variable. Others create the name of the message catalog from the
548 value of the @env{TEXTDOMAIN} shell variable, possibly adding a
549 suffix of @samp{.mo}. If you use the @env{TEXTDOMAIN} variable, you
550 may need to set the @env{TEXTDOMAINDIR} variable to the location of
551 the message catalog files. Still others use both variables in this
553 @env{TEXTDOMAINDIR}/@env{LC_MESSAGES}/LC_MESSAGES/@env{TEXTDOMAIN}.mo.
557 @cindex comments, shell
559 In a non-interactive shell, or an interactive shell in which the
560 @code{interactive_comments} option to the @code{shopt}
561 builtin is enabled (@pxref{The Shopt Builtin}),
562 a word beginning with @samp{#}
563 causes that word and all remaining characters on that line to
564 be ignored. An interactive shell without the @code{interactive_comments}
565 option enabled does not allow comments. The @code{interactive_comments}
566 option is on by default in interactive shells.
567 @xref{Interactive Shells}, for a description of what makes
571 @section Shell Commands
572 @cindex commands, shell
574 A simple shell command such as @code{echo a b c} consists of the command
575 itself followed by arguments, separated by spaces.
577 More complex shell commands are composed of simple commands arranged together
578 in a variety of ways: in a pipeline in which the output of one command
579 becomes the input of a second, in a loop or conditional construct, or in
583 * Simple Commands:: The most common type of command.
584 * Pipelines:: Connecting the input and output of several
586 * Lists:: How to execute commands sequentially.
587 * Compound Commands:: Shell commands for control flow.
588 * Coprocesses:: Two-way communication between commands.
589 * GNU Parallel:: Running commands in parallel.
592 @node Simple Commands
593 @subsection Simple Commands
594 @cindex commands, simple
596 A simple command is the kind of command encountered most often.
597 It's just a sequence of words separated by @code{blank}s, terminated
598 by one of the shell's control operators (@pxref{Definitions}). The
599 first word generally specifies a command to be executed, with the
600 rest of the words being that command's arguments.
602 The return status (@pxref{Exit Status}) of a simple command is
603 its exit status as provided
604 by the @sc{posix} 1003.1 @code{waitpid} function, or 128+@var{n} if
605 the command was terminated by signal @var{n}.
608 @subsection Pipelines
610 @cindex commands, pipelines
612 A @code{pipeline} is a sequence of one or more commands separated by
613 one of the control operators @samp{|} or @samp{|&}.
617 @cindex command timing
618 The format for a pipeline is
620 [time [-p]] [!] @var{command1} [ | or |& @var{command2} ] @dots{}
624 The output of each command in the pipeline is connected via a pipe
625 to the input of the next command.
626 That is, each command reads the previous command's output. This
627 connection is performed before any redirections specified by the
630 If @samp{|&} is used, @var{command1}'s standard error, in addition to
631 its standard output, is connected to
632 @var{command2}'s standard input through the pipe;
633 it is shorthand for @code{2>&1 |}.
634 This implicit redirection of the standard error to the standard output is
635 performed after any redirections specified by the command.
637 The reserved word @code{time} causes timing statistics
638 to be printed for the pipeline once it finishes.
639 The statistics currently consist of elapsed (wall-clock) time and
640 user and system time consumed by the command's execution.
641 The @option{-p} option changes the output format to that specified
643 When the shell is in @sc{posix} mode (@pxref{Bash POSIX Mode}),
644 it does not recognize @code{time} as a reserved word if the next
645 token begins with a @samp{-}.
646 The @env{TIMEFORMAT} variable may be set to a format string that
647 specifies how the timing information should be displayed.
648 @xref{Bash Variables}, for a description of the available formats.
649 The use of @code{time} as a reserved word permits the timing of
650 shell builtins, shell functions, and pipelines. An external
651 @code{time} command cannot time these easily.
653 When the shell is in @sc{posix} mode (@pxref{Bash POSIX Mode}), @code{time}
654 may be followed by a newline. In this case, the shell displays the
655 total user and system time consumed by the shell and its children.
656 The @env{TIMEFORMAT} variable may be used to specify the format of
657 the time information.
659 If the pipeline is not executed asynchronously (@pxref{Lists}), the
660 shell waits for all commands in the pipeline to complete.
662 Each command in a pipeline is executed in its own subshell
663 (@pxref{Command Execution Environment}). The exit
664 status of a pipeline is the exit status of the last command in the
665 pipeline, unless the @code{pipefail} option is enabled
666 (@pxref{The Set Builtin}).
667 If @code{pipefail} is enabled, the pipeline's return status is the
668 value of the last (rightmost) command to exit with a non-zero status,
669 or zero if all commands exit successfully.
670 If the reserved word @samp{!} precedes the pipeline, the
671 exit status is the logical negation of the exit status as described
673 The shell waits for all commands in the pipeline to terminate before
677 @subsection Lists of Commands
678 @cindex commands, lists
680 A @code{list} is a sequence of one or more pipelines separated by one
681 of the operators @samp{;}, @samp{&}, @samp{&&}, or @samp{||},
682 and optionally terminated by one of @samp{;}, @samp{&}, or a
685 Of these list operators, @samp{&&} and @samp{||}
686 have equal precedence, followed by @samp{;} and @samp{&},
687 which have equal precedence.
689 A sequence of one or more newlines may appear in a @code{list}
690 to delimit commands, equivalent to a semicolon.
692 If a command is terminated by the control operator @samp{&},
693 the shell executes the command asynchronously in a subshell.
694 This is known as executing the command in the @var{background}.
695 The shell does not wait for the command to finish, and the return
697 When job control is not active (@pxref{Job Control}),
698 the standard input for asynchronous commands, in the absence of any
699 explicit redirections, is redirected from @code{/dev/null}.
701 Commands separated by a @samp{;} are executed sequentially; the shell
702 waits for each command to terminate in turn. The return status is the
703 exit status of the last command executed.
705 @sc{and} and @sc{or} lists are sequences of one or more pipelines
706 separated by the control operators @samp{&&} and @samp{||},
707 respectively. @sc{and} and @sc{or} lists are executed with left
710 An @sc{and} list has the form
712 @var{command1} && @var{command2}
716 @var{command2} is executed if, and only if, @var{command1}
717 returns an exit status of zero.
719 An @sc{or} list has the form
721 @var{command1} || @var{command2}
725 @var{command2} is executed if, and only if, @var{command1}
726 returns a non-zero exit status.
729 @sc{and} and @sc{or} lists is the exit status of the last command
730 executed in the list.
732 @node Compound Commands
733 @subsection Compound Commands
734 @cindex commands, compound
737 * Looping Constructs:: Shell commands for iterative action.
738 * Conditional Constructs:: Shell commands for conditional execution.
739 * Command Grouping:: Ways to group commands.
742 Compound commands are the shell programming constructs.
743 Each construct begins with a reserved word or control operator and is
744 terminated by a corresponding reserved word or operator.
745 Any redirections (@pxref{Redirections}) associated with a compound command
746 apply to all commands within that compound command unless explicitly overridden.
748 In most cases a list of commands in a compound command's description may be
749 separated from the rest of the command by one or more newlines, and may be
750 followed by a newline in place of a semicolon.
752 Bash provides looping constructs, conditional commands, and mechanisms
753 to group commands and execute them as a unit.
755 @node Looping Constructs
756 @subsubsection Looping Constructs
757 @cindex commands, looping
759 Bash supports the following looping constructs.
761 Note that wherever a @samp{;} appears in the description of a
762 command's syntax, it may be replaced with one or more newlines.
769 The syntax of the @code{until} command is:
772 until @var{test-commands}; do @var{consequent-commands}; done
775 Execute @var{consequent-commands} as long as
776 @var{test-commands} has an exit status which is not zero.
777 The return status is the exit status of the last command executed
778 in @var{consequent-commands}, or zero if none was executed.
782 The syntax of the @code{while} command is:
785 while @var{test-commands}; do @var{consequent-commands}; done
788 Execute @var{consequent-commands} as long as
789 @var{test-commands} has an exit status of zero.
790 The return status is the exit status of the last command executed
791 in @var{consequent-commands}, or zero if none was executed.
795 The syntax of the @code{for} command is:
798 for @var{name} [ [in [@var{words} @dots{}] ] ; ] do @var{commands}; done
801 Expand @var{words}, and execute @var{commands} once for each member
802 in the resultant list, with @var{name} bound to the current member.
803 If @samp{in @var{words}} is not present, the @code{for} command
804 executes the @var{commands} once for each positional parameter that is
805 set, as if @samp{in "$@@"} had been specified
806 (@pxref{Special Parameters}).
807 The return status is the exit status of the last command that executes.
808 If there are no items in the expansion of @var{words}, no commands are
809 executed, and the return status is zero.
811 An alternate form of the @code{for} command is also supported:
814 for (( @var{expr1} ; @var{expr2} ; @var{expr3} )) ; do @var{commands} ; done
817 First, the arithmetic expression @var{expr1} is evaluated according
818 to the rules described below (@pxref{Shell Arithmetic}).
819 The arithmetic expression @var{expr2} is then evaluated repeatedly
820 until it evaluates to zero.
821 Each time @var{expr2} evaluates to a non-zero value, @var{commands} are
822 executed and the arithmetic expression @var{expr3} is evaluated.
823 If any expression is omitted, it behaves as if it evaluates to 1.
824 The return value is the exit status of the last command in @var{commands}
825 that is executed, or false if any of the expressions is invalid.
828 The @code{break} and @code{continue} builtins (@pxref{Bourne Shell Builtins})
829 may be used to control loop execution.
831 @node Conditional Constructs
832 @subsubsection Conditional Constructs
833 @cindex commands, conditional
842 The syntax of the @code{if} command is:
845 if @var{test-commands}; then
846 @var{consequent-commands};
847 [elif @var{more-test-commands}; then
848 @var{more-consequents};]
849 [else @var{alternate-consequents};]
853 The @var{test-commands} list is executed, and if its return status is zero,
854 the @var{consequent-commands} list is executed.
855 If @var{test-commands} returns a non-zero status, each @code{elif} list
856 is executed in turn, and if its exit status is zero,
857 the corresponding @var{more-consequents} is executed and the
859 If @samp{else @var{alternate-consequents}} is present, and
860 the final command in the final @code{if} or @code{elif} clause
861 has a non-zero exit status, then @var{alternate-consequents} is executed.
862 The return status is the exit status of the last command executed, or
863 zero if no condition tested true.
869 The syntax of the @code{case} command is:
872 case @var{word} in [ [(] @var{pattern} [| @var{pattern}]@dots{}) @var{command-list} ;;]@dots{} esac
875 @code{case} will selectively execute the @var{command-list} corresponding to
876 the first @var{pattern} that matches @var{word}.
877 If the @code{nocasematch} shell option
878 (see the description of @code{shopt} in @ref{The Shopt Builtin})
879 is enabled, the match is performed without regard to the case
880 of alphabetic characters.
881 The @samp{|} is used to separate multiple patterns, and the @samp{)}
882 operator terminates a pattern list.
883 A list of patterns and an associated command-list is known
886 Each clause must be terminated with @samp{;;}, @samp{;&}, or @samp{;;&}.
887 The @var{word} undergoes tilde expansion, parameter expansion, command
888 substitution, arithmetic expansion, and quote removal before matching is
889 attempted. Each @var{pattern} undergoes tilde expansion, parameter
890 expansion, command substitution, and arithmetic expansion.
892 There may be an arbitrary number of @code{case} clauses, each terminated
893 by a @samp{;;}, @samp{;&}, or @samp{;;&}.
894 The first pattern that matches determines the
895 command-list that is executed.
896 It's a common idiom to use @samp{*} as the final pattern to define the
897 default case, since that pattern will always match.
899 Here is an example using @code{case} in a script that could be used to
900 describe one interesting feature of an animal:
903 echo -n "Enter the name of an animal: "
905 echo -n "The $ANIMAL has "
907 horse | dog | cat) echo -n "four";;
908 man | kangaroo ) echo -n "two";;
909 *) echo -n "an unknown number of";;
916 If the @samp{;;} operator is used, no subsequent matches are attempted after
917 the first pattern match.
918 Using @samp{;&} in place of @samp{;;} causes execution to continue with
919 the @var{command-list} associated with the next clause, if any.
920 Using @samp{;;&} in place of @samp{;;} causes the shell to test the patterns
921 in the next clause, if any, and execute any associated @var{command-list}
922 on a successful match.
924 The return status is zero if no @var{pattern} is matched. Otherwise, the
925 return status is the exit status of the @var{command-list} executed.
930 The @code{select} construct allows the easy generation of menus.
931 It has almost the same syntax as the @code{for} command:
934 select @var{name} [in @var{words} @dots{}]; do @var{commands}; done
937 The list of words following @code{in} is expanded, generating a list
938 of items. The set of expanded words is printed on the standard
939 error output stream, each preceded by a number. If the
940 @samp{in @var{words}} is omitted, the positional parameters are printed,
941 as if @samp{in "$@@"} had been specified.
942 The @env{PS3} prompt is then displayed and a line is read from the
944 If the line consists of a number corresponding to one of the displayed
945 words, then the value of @var{name} is set to that word.
946 If the line is empty, the words and prompt are displayed again.
947 If @code{EOF} is read, the @code{select} command completes.
948 Any other value read causes @var{name} to be set to null.
949 The line read is saved in the variable @env{REPLY}.
951 The @var{commands} are executed after each selection until a
952 @code{break} command is executed, at which
953 point the @code{select} command completes.
955 Here is an example that allows the user to pick a filename from the
956 current directory, and displays the name and index of the file
962 echo you picked $fname \($REPLY\)
969 (( @var{expression} ))
972 The arithmetic @var{expression} is evaluated according to the rules
973 described below (@pxref{Shell Arithmetic}).
974 If the value of the expression is non-zero, the return status is 0;
975 otherwise the return status is 1. This is exactly equivalent to
977 let "@var{expression}"
980 @xref{Bash Builtins}, for a full description of the @code{let} builtin.
986 [[ @var{expression} ]]
989 Return a status of 0 or 1 depending on the evaluation of
990 the conditional expression @var{expression}.
991 Expressions are composed of the primaries described below in
992 @ref{Bash Conditional Expressions}.
993 Word splitting and filename expansion are not performed on the words
994 between the @code{[[} and @code{]]}; tilde expansion, parameter and
995 variable expansion, arithmetic expansion, command substitution, process
996 substitution, and quote removal are performed.
997 Conditional operators such as @samp{-f} must be unquoted to be recognized
1000 When used with @code{[[}, the @samp{<} and @samp{>} operators sort
1001 lexicographically using the current locale.
1003 When the @samp{==} and @samp{!=} operators are used, the string to the
1004 right of the operator is considered a pattern and matched according
1005 to the rules described below in @ref{Pattern Matching},
1006 as if the @code{extglob} shell option were enabled.
1007 The @samp{=} operator is identical to @samp{==}.
1008 If the @code{nocasematch} shell option
1009 (see the description of @code{shopt} in @ref{The Shopt Builtin})
1010 is enabled, the match is performed without regard to the case
1011 of alphabetic characters.
1012 The return value is 0 if the string matches (@samp{==}) or does not
1013 match (@samp{!=})the pattern, and 1 otherwise.
1014 Any part of the pattern may be quoted to force the quoted portion
1015 to be matched as a string.
1017 An additional binary operator, @samp{=~}, is available, with the same
1018 precedence as @samp{==} and @samp{!=}.
1019 When it is used, the string to the right of the operator is considered
1020 an extended regular expression and matched accordingly (as in @i{regex}3)).
1021 The return value is 0 if the string matches
1022 the pattern, and 1 otherwise.
1023 If the regular expression is syntactically incorrect, the conditional
1024 expression's return value is 2.
1025 If the @code{nocasematch} shell option
1026 (see the description of @code{shopt} in @ref{The Shopt Builtin})
1027 is enabled, the match is performed without regard to the case
1028 of alphabetic characters.
1029 Any part of the pattern may be quoted to force the quoted portion
1030 to be matched as a string.
1031 Bracket expressions in regular expressions must be treated carefully,
1032 since normal quoting characters lose their meanings between brackets.
1033 If the pattern is stored in a shell variable, quoting the variable
1034 expansion forces the entire pattern to be matched as a string.
1035 Substrings matched by parenthesized subexpressions within the regular
1036 expression are saved in the array variable @code{BASH_REMATCH}.
1037 The element of @code{BASH_REMATCH} with index 0 is the portion of the string
1038 matching the entire regular expression.
1039 The element of @code{BASH_REMATCH} with index @var{n} is the portion of the
1040 string matching the @var{n}th parenthesized subexpression.
1042 For example, the following will match a line
1043 (stored in the shell variable @var{line})
1044 if there is a sequence of characters in the value consisting of
1045 any number, including zero, of
1046 space characters, zero or one instances of @samp{a}, then a @samp{b}:
1048 [[ $line =~ [[:space:]]*(a)?b ]]
1052 That means values like @samp{aab} and @samp{ aaaaaab} will match, as
1053 will a line containing a @samp{b} anywhere in its value.
1055 Storing the regular expression in a shell variable is often a useful
1056 way to avoid problems with quoting characters that are special to the
1058 It is sometimes difficult to specify a regular expression literally
1059 without using quotes, or to keep track of the quoting used by regular
1060 expressions while paying attention to the shell's quote removal.
1061 Using a shell variable to store the pattern decreases these problems.
1062 For example, the following is equivalent to the above:
1064 pattern='[[:space:]]*(a)?b'
1065 [[ $line =~ $pattern ]]
1069 If you want to match a character that's special to the regular expression
1070 grammar, it has to be quoted to remove its special meaning.
1071 This means that in the pattern @samp{xxx.txt}, the @samp{.} matches any
1072 character in the string (its usual regular expression meaning), but in the
1073 pattern @samp{"xxx.txt"} it can only match a literal @samp{.}.
1074 Shell programmers should take special care with backslashes, since backslashes
1075 are used both by the shell and regular expressions to remove the special
1076 meaning from the following character.
1077 The following two sets of commands are @emph{not} equivalent:
1084 [[ . =~ "$pattern" ]]
1089 The first two matches will succeed, but the second two will not, because
1090 in the second two the backslash will be part of the pattern to be matched.
1091 In the first two examples, the backslash removes the special meaning from
1092 @samp{.}, so the literal @samp{.} matches.
1093 If the string in the first examples were anything other than @samp{.}, say
1094 @samp{a}, the pattern would not match, because the quoted @samp{.} in the
1095 pattern loses its special meaning of matching any single character.
1097 Expressions may be combined using the following operators, listed
1098 in decreasing order of precedence:
1101 @item ( @var{expression} )
1102 Returns the value of @var{expression}.
1103 This may be used to override the normal precedence of operators.
1105 @item ! @var{expression}
1106 True if @var{expression} is false.
1108 @item @var{expression1} && @var{expression2}
1109 True if both @var{expression1} and @var{expression2} are true.
1111 @item @var{expression1} || @var{expression2}
1112 True if either @var{expression1} or @var{expression2} is true.
1116 The @code{&&} and @code{||} operators do not evaluate @var{expression2} if the
1117 value of @var{expression1} is sufficient to determine the return
1118 value of the entire conditional expression.
1121 @node Command Grouping
1122 @subsubsection Grouping Commands
1123 @cindex commands, grouping
1125 Bash provides two ways to group a list of commands to be executed
1126 as a unit. When commands are grouped, redirections may be applied
1127 to the entire command list. For example, the output of all the
1128 commands in the list may be redirected to a single stream.
1136 Placing a list of commands between parentheses causes a subshell
1137 environment to be created (@pxref{Command Execution Environment}), and each
1138 of the commands in @var{list} to be executed in that subshell. Since the
1139 @var{list} is executed in a subshell, variable assignments do not remain in
1140 effect after the subshell completes.
1149 Placing a list of commands between curly braces causes the list to
1150 be executed in the current shell context. No subshell is created.
1151 The semicolon (or newline) following @var{list} is required.
1154 In addition to the creation of a subshell, there is a subtle difference
1155 between these two constructs due to historical reasons. The braces
1156 are @code{reserved words}, so they must be separated from the @var{list}
1157 by @code{blank}s or other shell metacharacters.
1158 The parentheses are @code{operators}, and are
1159 recognized as separate tokens by the shell even if they are not separated
1160 from the @var{list} by whitespace.
1162 The exit status of both of these constructs is the exit status of
1166 @subsection Coprocesses
1169 A @code{coprocess} is a shell command preceded by the @code{coproc}
1171 A coprocess is executed asynchronously in a subshell, as if the command
1172 had been terminated with the @samp{&} control operator, with a two-way pipe
1173 established between the executing shell and the coprocess.
1175 The format for a coprocess is:
1177 coproc [@var{NAME}] @var{command} [@var{redirections}]
1181 This creates a coprocess named @var{NAME}.
1182 If @var{NAME} is not supplied, the default name is @var{COPROC}.
1183 @var{NAME} must not be supplied if @var{command} is a simple
1184 command (@pxref{Simple Commands}); otherwise, it is interpreted as
1185 the first word of the simple command.
1187 When the coprocess is executed, the shell creates an array variable
1189 named @env{NAME} in the context of the executing shell.
1190 The standard output of @var{command}
1191 is connected via a pipe to a file descriptor in the executing shell,
1192 and that file descriptor is assigned to @env{NAME}[0].
1193 The standard input of @var{command}
1194 is connected via a pipe to a file descriptor in the executing shell,
1195 and that file descriptor is assigned to @env{NAME}[1].
1196 This pipe is established before any redirections specified by the
1197 command (@pxref{Redirections}).
1198 The file descriptors can be utilized as arguments to shell commands
1199 and redirections using standard word expansions.
1200 The file descriptors are not available in subshells.
1202 The process ID of the shell spawned to execute the coprocess is
1203 available as the value of the variable @env{NAME}_PID.
1205 builtin command may be used to wait for the coprocess to terminate.
1207 Since the coprocess is created as an asynchronous command,
1208 the @code{coproc} command always returns success.
1209 The return status of a coprocess is the exit status of @var{command}.
1212 @subsection GNU Parallel
1214 There are ways to run commands in parallel that are not built into Bash.
1215 GNU Parallel is a tool to do just that.
1217 GNU Parallel, as its name suggests, can be used to build and run commands
1218 in parallel. You may run the same command with different arguments, whether
1219 they are filenames, usernames, hostnames, or lines read from files. GNU
1220 Parallel provides shorthand references to many of the most common operations
1221 (input lines, various portions of the input line, different ways to specify
1222 the input source, and so on). Parallel can replace @code{xargs} or feed
1223 commands from its input sources to several different instances of Bash.
1225 For a complete description, refer to the GNU Parallel documentation. A few
1226 examples should provide a brief introduction to its use.
1228 For example, it is easy to replace @code{xargs} to gzip all html files in the
1229 current directory and its subdirectories:
1231 find . -type f -name '*.html' -print | parallel gzip
1234 If you need to protect special characters such as newlines in file names,
1235 use find's @option{-print0} option and parallel's @option{-0} option.
1237 You can use Parallel to move files from the current directory when the
1238 number of files is too large to process with one @code{mv} invocation:
1240 ls | parallel mv @{@} destdir
1243 As you can see, the @{@} is replaced with each line read from standard input.
1244 While using @code{ls} will work in most instances, it is not sufficient to
1245 deal with all filenames.
1246 If you need to accommodate special characters in filenames, you can use
1249 find . -depth 1 \! -name '.*' -print0 | parallel -0 mv @{@} destdir
1253 as alluded to above.
1255 This will run as many @code{mv} commands as there are files in the current
1257 You can emulate a parallel @code{xargs} by adding the @option{-X} option:
1259 find . -depth 1 \! -name '.*' -print0 | parallel -0 -X mv @{@} destdir
1262 GNU Parallel can replace certain common idioms that operate on lines read
1263 from a file (in this case, filenames listed one per line):
1265 while IFS= read -r x; do
1266 do-something1 "$x" "config-$x"
1267 do-something2 < "$x"
1268 done < file | process-output
1272 with a more compact syntax reminiscent of lambdas:
1274 cat list | parallel "do-something1 @{@} config-@{@} ; do-something2 < @{@}" | process-output
1277 Parallel provides a built-in mechanism to remove filename extensions, which
1278 lends itself to batch file transformations or renaming:
1280 ls *.gz | parallel -j+0 "zcat @{@} | bzip2 >@{.@}.bz2 && rm @{@}"
1283 This will recompress all files in the current directory with names ending
1284 in .gz using bzip2, running one job per CPU (-j+0) in parallel.
1285 (We use @code{ls} for brevity here; using @code{find} as above is more
1286 robust in the face of filenames containing unexpected characters.)
1287 Parallel can take arguments from the command line; the above can also be
1291 parallel "zcat @{@} | bzip2 >@{.@}.bz2 && rm @{@}" ::: *.gz
1294 If a command generates output, you may want to preserve the input order in
1295 the output. For instance, the following command
1297 @{ echo foss.org.my ; echo debian.org; echo freenetproject.org; @} | parallel traceroute
1300 will display as output the traceroute invocation that finishes first.
1301 Adding the @option{-k} option
1303 @{ echo foss.org.my ; echo debian.org; echo freenetproject.org; @} | parallel -k traceroute
1306 will ensure that the output of @code{traceroute foss.org.my} is displayed first.
1308 Finally, Parallel can be used to run a sequence of shell commands in parallel,
1309 similar to @samp{cat file | bash}.
1310 It is not uncommon to take a list of filenames, create a series of shell
1311 commands to operate on them, and feed that list of commnds to a shell.
1312 Parallel can speed this up. Assuming that @file{file} contains a list of
1313 shell commands, one per line,
1316 parallel -j 10 < file
1320 will evaluate the commands using the shell (since no explicit command is
1321 supplied as an argument), in blocks of ten shell jobs at a time.
1323 @node Shell Functions
1324 @section Shell Functions
1325 @cindex shell function
1326 @cindex functions, shell
1328 Shell functions are a way to group commands for later execution
1329 using a single name for the group. They are executed just like
1330 a "regular" command.
1331 When the name of a shell function is used as a simple command name,
1332 the list of commands associated with that function name is executed.
1333 Shell functions are executed in the current
1334 shell context; no new process is created to interpret them.
1336 Functions are declared using this syntax:
1339 @var{name} () @var{compound-command} [ @var{redirections} ]
1345 function @var{name} [()] @var{compound-command} [ @var{redirections} ]
1348 This defines a shell function named @var{name}. The reserved
1349 word @code{function} is optional.
1350 If the @code{function} reserved
1351 word is supplied, the parentheses are optional.
1352 The @var{body} of the function is the compound command
1353 @var{compound-command} (@pxref{Compound Commands}).
1354 That command is usually a @var{list} enclosed between @{ and @}, but
1355 may be any compound command listed above,
1356 with one exception: If the @code{function} reserved word is used, but the
1357 parentheses are not supplied, the braces are required.
1358 @var{compound-command} is executed whenever @var{name} is specified as the
1360 When the shell is in @sc{posix} mode (@pxref{Bash POSIX Mode}),
1361 @var{name} may not be the same as one of the special builtins
1362 (@pxref{Special Builtins}).
1363 Any redirections (@pxref{Redirections}) associated with the shell function
1364 are performed when the function is executed.
1366 A function definition may be deleted using the @option{-f} option to the
1367 @code{unset} builtin (@pxref{Bourne Shell Builtins}).
1369 The exit status of a function definition is zero unless a syntax error
1370 occurs or a readonly function with the same name already exists.
1371 When executed, the exit status of a function is the exit status of the
1372 last command executed in the body.
1374 Note that for historical reasons, in the most common usage the curly braces
1375 that surround the body of the function must be separated from the body by
1376 @code{blank}s or newlines.
1377 This is because the braces are reserved words and are only recognized
1378 as such when they are separated from the command list
1379 by whitespace or another shell metacharacter.
1380 Also, when using the braces, the @var{list} must be terminated by a semicolon,
1381 a @samp{&}, or a newline.
1383 When a function is executed, the arguments to the
1384 function become the positional parameters
1385 during its execution (@pxref{Positional Parameters}).
1386 The special parameter @samp{#} that expands to the number of
1387 positional parameters is updated to reflect the change.
1388 Special parameter @code{0} is unchanged.
1389 The first element of the @env{FUNCNAME} variable is set to the
1390 name of the function while the function is executing.
1392 All other aspects of the shell execution
1393 environment are identical between a function and its caller
1394 with these exceptions:
1395 the @env{DEBUG} and @env{RETURN} traps
1396 are not inherited unless the function has been given the
1397 @code{trace} attribute using the @code{declare} builtin or
1398 the @code{-o functrace} option has been enabled with
1399 the @code{set} builtin,
1400 (in which case all functions inherit the @env{DEBUG} and @env{RETURN} traps),
1401 and the @env{ERR} trap is not inherited unless the @code{-o errtrace}
1402 shell option has been enabled.
1403 @xref{Bourne Shell Builtins}, for the description of the
1404 @code{trap} builtin.
1406 The @env{FUNCNEST} variable, if set to a numeric value greater
1407 than 0, defines a maximum function nesting level. Function
1408 invocations that exceed the limit cause the entire command to
1411 If the builtin command @code{return}
1412 is executed in a function, the function completes and
1413 execution resumes with the next command after the function
1415 Any command associated with the @code{RETURN} trap is executed
1416 before execution resumes.
1417 When a function completes, the values of the
1418 positional parameters and the special parameter @samp{#}
1419 are restored to the values they had prior to the function's
1420 execution. If a numeric argument is given to @code{return},
1421 that is the function's return status; otherwise the function's
1422 return status is the exit status of the last command executed
1423 before the @code{return}.
1425 Variables local to the function may be declared with the
1426 @code{local} builtin. These variables are visible only to
1427 the function and the commands it invokes.
1429 Function names and definitions may be listed with the
1430 @option{-f} option to the @code{declare} (@code{typeset})
1431 builtin command (@pxref{Bash Builtins}).
1432 The @option{-F} option to @code{declare} or @code{typeset}
1433 will list the function names only
1434 (and optionally the source file and line number, if the @code{extdebug}
1435 shell option is enabled).
1436 Functions may be exported so that subshells
1437 automatically have them defined with the
1438 @option{-f} option to the @code{export} builtin
1439 (@pxref{Bourne Shell Builtins}).
1440 Note that shell functions and variables with the same name may result
1441 in multiple identically-named entries in the environment passed to the
1443 Care should be taken in cases where this may cause a problem.
1445 Functions may be recursive.
1446 The @code{FUNCNEST} variable may be used to limit the depth of the
1447 function call stack and restrict the number of function invocations.
1448 By default, no limit is placed on the number of recursive calls.
1450 @node Shell Parameters
1451 @section Shell Parameters
1453 @cindex variable, shell
1454 @cindex shell variable
1457 * Positional Parameters:: The shell's command-line arguments.
1458 * Special Parameters:: Parameters denoted by special characters.
1461 A @var{parameter} is an entity that stores values.
1462 It can be a @code{name}, a number, or one of the special characters
1464 A @var{variable} is a parameter denoted by a @code{name}.
1465 A variable has a @var{value} and zero or more @var{attributes}.
1466 Attributes are assigned using the @code{declare} builtin command
1467 (see the description of the @code{declare} builtin in @ref{Bash Builtins}).
1469 A parameter is set if it has been assigned a value. The null string is
1470 a valid value. Once a variable is set, it may be unset only by using
1471 the @code{unset} builtin command.
1473 A variable may be assigned to by a statement of the form
1475 @var{name}=[@var{value}]
1479 is not given, the variable is assigned the null string. All
1480 @var{value}s undergo tilde expansion, parameter and variable expansion,
1481 command substitution, arithmetic expansion, and quote
1482 removal (detailed below). If the variable has its @code{integer}
1483 attribute set, then @var{value}
1484 is evaluated as an arithmetic expression even if the @code{$((@dots{}))}
1485 expansion is not used (@pxref{Arithmetic Expansion}).
1486 Word splitting is not performed, with the exception
1487 of @code{"$@@"} as explained below.
1488 Filename expansion is not performed.
1489 Assignment statements may also appear as arguments to the
1491 @code{declare}, @code{typeset}, @code{export}, @code{readonly},
1492 and @code{local} builtin commands (@var{declaration} commands).
1493 When in @sc{posix} mode (@pxref{Bash POSIX Mode}), these builtins may appear
1494 in a command after one or more instances of the @code{command} builtin
1495 and retain these assignment statement properties.
1497 In the context where an assignment statement is assigning a value
1498 to a shell variable or array index (@pxref{Arrays}), the @samp{+=}
1499 operator can be used to
1500 append to or add to the variable's previous value.
1501 This includes arguments to builtin commands such as @code{declare} that
1502 accept assignment statements (@var{declaration} commands).
1503 When @samp{+=} is applied to a variable for which the @var{integer} attribute
1504 has been set, @var{value} is evaluated as an arithmetic expression and
1505 added to the variable's current value, which is also evaluated.
1506 When @samp{+=} is applied to an array variable using compound assignment
1507 (@pxref{Arrays}), the
1508 variable's value is not unset (as it is when using @samp{=}), and new
1509 values are appended to the array beginning at one greater than the array's
1510 maximum index (for indexed arrays), or added as additional key-value pairs
1511 in an associative array.
1512 When applied to a string-valued variable, @var{value} is expanded and
1513 appended to the variable's value.
1515 A variable can be assigned the @var{nameref} attribute using the
1516 @option{-n} option to the @code{declare} or @code{local} builtin commands
1517 (@pxref{Bash Builtins})
1518 to create a @var{nameref}, or a reference to another variable.
1519 This allows variables to be manipulated indirectly.
1520 Whenever the nameref variable is referenced, assigned to, unset, or has
1521 its attributes modified (other than using or changing the nameref
1522 attribute itself), the
1523 operation is actually performed on the variable specified by the nameref
1525 A nameref is commonly used within shell functions to refer to a variable
1526 whose name is passed as an argument to the function.
1527 For instance, if a variable name is passed to a shell function as its first
1533 inside the function creates a nameref variable @var{ref} whose value is
1534 the variable name passed as the first argument.
1535 References and assignments to @var{ref}, and changes to its attributes,
1536 are treated as references, assignments, and attribute modifications
1537 to the variable whose name was passed as @code{$1}.
1539 If the control variable in a @code{for} loop has the nameref attribute,
1540 the list of words can be a list of shell variables, and a name reference
1541 will be established for each word in the list, in turn, when the loop is
1543 Array variables cannot be given the nameref attribute.
1544 However, nameref variables can reference array variables and subscripted
1546 Namerefs can be unset using the @option{-n} option to the @code{unset} builtin
1547 (@pxref{Bourne Shell Builtins}).
1548 Otherwise, if @code{unset} is executed with the name of a nameref variable
1549 as an argument, the variable referenced by the nameref variable will be unset.
1551 @node Positional Parameters
1552 @subsection Positional Parameters
1553 @cindex parameters, positional
1555 A @var{positional parameter} is a parameter denoted by one or more
1556 digits, other than the single digit @code{0}. Positional parameters are
1557 assigned from the shell's arguments when it is invoked,
1558 and may be reassigned using the @code{set} builtin command.
1559 Positional parameter @code{N} may be referenced as @code{$@{N@}}, or
1560 as @code{$N} when @code{N} consists of a single digit.
1561 Positional parameters may not be assigned to with assignment statements.
1562 The @code{set} and @code{shift} builtins are used to set and
1563 unset them (@pxref{Shell Builtin Commands}).
1564 The positional parameters are
1565 temporarily replaced when a shell function is executed
1566 (@pxref{Shell Functions}).
1568 When a positional parameter consisting of more than a single
1569 digit is expanded, it must be enclosed in braces.
1571 @node Special Parameters
1572 @subsection Special Parameters
1573 @cindex parameters, special
1575 The shell treats several parameters specially. These parameters may
1576 only be referenced; assignment to them is not allowed.
1582 ($*) Expands to the positional parameters, starting from one.
1583 When the expansion is not within double quotes, each positional parameter
1584 expands to a separate word.
1585 In contexts where it is performed, those words
1586 are subject to further word splitting and pathname expansion.
1587 When the expansion occurs within double quotes, it expands to a single word
1588 with the value of each parameter separated by the first character of the
1589 @env{IFS} special variable. That is, @code{"$*"} is equivalent
1590 to @code{"$1@var{c}$2@var{c}@dots{}"}, where @var{c}
1591 is the first character of the value of the @code{IFS}
1593 If @env{IFS} is unset, the parameters are separated by spaces.
1594 If @env{IFS} is null, the parameters are joined without intervening
1599 ($@@) Expands to the positional parameters, starting from one. When the
1600 expansion occurs within double quotes, each parameter expands to a
1601 separate word. That is, @code{"$@@"} is equivalent to
1602 @code{"$1" "$2" @dots{}}.
1603 If the double-quoted expansion occurs within a word, the expansion of
1604 the first parameter is joined with the beginning part of the original
1605 word, and the expansion of the last parameter is joined with the last
1606 part of the original word.
1607 When there are no positional parameters, @code{"$@@"} and
1609 expand to nothing (i.e., they are removed).
1613 ($#) Expands to the number of positional parameters in decimal.
1617 ($?) Expands to the exit status of the most recently executed foreground
1622 ($-, a hyphen.) Expands to the current option flags as specified upon
1623 invocation, by the @code{set}
1624 builtin command, or those set by the shell itself
1625 (such as the @option{-i} option).
1629 ($$) Expands to the process @sc{id} of the shell. In a @code{()} subshell, it
1630 expands to the process @sc{id} of the invoking shell, not the subshell.
1634 ($!) Expands to the process @sc{id} of the job most recently placed into the
1635 background, whether executed as an asynchronous command or using
1636 the @code{bg} builtin (@pxref{Job Control Builtins}).
1640 ($0) Expands to the name of the shell or shell script. This is set at
1641 shell initialization. If Bash is invoked with a file of commands
1642 (@pxref{Shell Scripts}), @code{$0} is set to the name of that file.
1643 If Bash is started with the @option{-c} option (@pxref{Invoking Bash}),
1644 then @code{$0} is set to the first argument after the string to be
1645 executed, if one is present. Otherwise, it is set
1646 to the filename used to invoke Bash, as given by argument zero.
1650 ($_, an underscore.)
1651 At shell startup, set to the absolute pathname used to invoke the
1652 shell or shell script being executed as passed in the environment
1654 Subsequently, expands to the last argument to the previous command,
1656 Also set to the full pathname used to invoke each command executed
1657 and placed in the environment exported to that command.
1658 When checking mail, this parameter holds the name of the mail file.
1661 @node Shell Expansions
1662 @section Shell Expansions
1665 Expansion is performed on the command line after it has been split into
1666 @code{token}s. There are seven kinds of expansion performed:
1669 @item brace expansion
1670 @item tilde expansion
1671 @item parameter and variable expansion
1672 @item command substitution
1673 @item arithmetic expansion
1674 @item word splitting
1675 @item filename expansion
1679 * Brace Expansion:: Expansion of expressions within braces.
1680 * Tilde Expansion:: Expansion of the ~ character.
1681 * Shell Parameter Expansion:: How Bash expands variables to their values.
1682 * Command Substitution:: Using the output of a command as an argument.
1683 * Arithmetic Expansion:: How to use arithmetic in shell expansions.
1684 * Process Substitution:: A way to write and read to and from a
1686 * Word Splitting:: How the results of expansion are split into separate
1688 * Filename Expansion:: A shorthand for specifying filenames matching patterns.
1689 * Quote Removal:: How and when quote characters are removed from
1693 The order of expansions is:
1695 tilde expansion, parameter and variable expansion, arithmetic expansion,
1696 and command substitution (done in a left-to-right fashion);
1698 and filename expansion.
1700 On systems that can support it, there is an additional expansion
1701 available: @var{process substitution}.
1702 This is performed at the
1703 same time as tilde, parameter, variable, and arithmetic expansion and
1704 command substitution.
1706 After these expansions are performed, quote characters present in the
1707 original word are removed unless they have been quoted themselves
1708 (@var{quote removal}).
1710 Only brace expansion, word splitting, and filename expansion
1711 can change the number of words of the expansion; other expansions
1712 expand a single word to a single word.
1713 The only exceptions to this are the expansions of
1714 @code{"$@@"} (@pxref{Special Parameters}) and @code{"$@{@var{name}[@@]@}"}
1717 After all expansions, @code{quote removal} (@pxref{Quote Removal})
1720 @node Brace Expansion
1721 @subsection Brace Expansion
1722 @cindex brace expansion
1723 @cindex expansion, brace
1725 Brace expansion is a mechanism by which arbitrary strings may be generated.
1726 This mechanism is similar to
1727 @var{filename expansion} (@pxref{Filename Expansion}),
1728 but the filenames generated need not exist.
1729 Patterns to be brace expanded take the form of an optional @var{preamble},
1730 followed by either a series of comma-separated strings or a sequence expression
1731 between a pair of braces,
1732 followed by an optional @var{postscript}.
1733 The preamble is prefixed to each string contained within the braces, and
1734 the postscript is then appended to each resulting string, expanding left
1737 Brace expansions may be nested.
1738 The results of each expanded string are not sorted; left to right order
1742 bash$ echo a@{d,c,b@}e
1746 A sequence expression takes the form @code{@{@var{x}..@var{y}[..@var{incr}]@}},
1747 where @var{x} and @var{y} are either integers or single characters,
1748 and @var{incr}, an optional increment, is an integer.
1749 When integers are supplied, the expression expands to each number between
1750 @var{x} and @var{y}, inclusive.
1751 Supplied integers may be prefixed with @samp{0} to force each term to have the
1753 When either @var{x} or @var{y} begins with a zero, the shell
1754 attempts to force all generated terms to contain the same number of digits,
1755 zero-padding where necessary.
1756 When characters are supplied, the expression expands to each character
1757 lexicographically between @var{x} and @var{y}, inclusive,
1758 using the default C locale.
1759 Note that both @var{x} and @var{y} must be of the same type.
1760 When the increment is supplied, it is used as the difference between
1761 each term. The default increment is 1 or -1 as appropriate.
1763 Brace expansion is performed before any other expansions,
1764 and any characters special to other expansions are preserved
1765 in the result. It is strictly textual. Bash
1766 does not apply any syntactic interpretation to the context of the
1767 expansion or the text between the braces.
1768 To avoid conflicts with parameter expansion, the string @samp{$@{}
1769 is not considered eligible for brace expansion.
1771 A correctly-formed brace expansion must contain unquoted opening
1772 and closing braces, and at least one unquoted comma or a valid
1773 sequence expression.
1774 Any incorrectly formed brace expansion is left unchanged.
1776 A @{ or @samp{,} may be quoted with a backslash to prevent its
1777 being considered part of a brace expression.
1778 To avoid conflicts with parameter expansion, the string @samp{$@{}
1779 is not considered eligible for brace expansion.
1781 This construct is typically used as shorthand when the common
1782 prefix of the strings to be generated is longer than in the
1785 mkdir /usr/local/src/bash/@{old,new,dist,bugs@}
1789 chown root /usr/@{ucb/@{ex,edit@},lib/@{ex?.?*,how_ex@}@}
1792 @node Tilde Expansion
1793 @subsection Tilde Expansion
1794 @cindex tilde expansion
1795 @cindex expansion, tilde
1797 If a word begins with an unquoted tilde character (@samp{~}), all of the
1798 characters up to the first unquoted slash (or all characters,
1799 if there is no unquoted slash) are considered a @var{tilde-prefix}.
1800 If none of the characters in the tilde-prefix are quoted, the
1801 characters in the tilde-prefix following the tilde are treated as a
1802 possible @var{login name}.
1803 If this login name is the null string, the tilde is replaced with the
1804 value of the @env{HOME} shell variable.
1805 If @env{HOME} is unset, the home directory of the user executing the
1806 shell is substituted instead.
1807 Otherwise, the tilde-prefix is replaced with the home directory
1808 associated with the specified login name.
1810 If the tilde-prefix is @samp{~+}, the value of
1811 the shell variable @env{PWD} replaces the tilde-prefix.
1812 If the tilde-prefix is @samp{~-}, the value of the shell variable
1813 @env{OLDPWD}, if it is set, is substituted.
1815 If the characters following the tilde in the tilde-prefix consist of a
1816 number @var{N}, optionally prefixed by a @samp{+} or a @samp{-},
1817 the tilde-prefix is replaced with the
1818 corresponding element from the directory stack, as it would be displayed
1819 by the @code{dirs} builtin invoked with the characters following tilde
1820 in the tilde-prefix as an argument (@pxref{The Directory Stack}).
1821 If the tilde-prefix, sans the tilde, consists of a number without a
1822 leading @samp{+} or @samp{-}, @samp{+} is assumed.
1824 If the login name is invalid, or the tilde expansion fails, the word is
1827 Each variable assignment is checked for unquoted tilde-prefixes immediately
1828 following a @samp{:} or the first @samp{=}.
1829 In these cases, tilde expansion is also performed.
1830 Consequently, one may use filenames with tildes in assignments to
1831 @env{PATH}, @env{MAILPATH}, and @env{CDPATH},
1832 and the shell assigns the expanded value.
1834 The following table shows how Bash treats unquoted tilde-prefixes:
1838 The value of @code{$HOME}
1843 The subdirectory @code{foo} of the home directory of the user
1850 @file{$@{OLDPWD-'~-'@}/foo}
1853 The string that would be displayed by @samp{dirs +@var{N}}
1856 The string that would be displayed by @samp{dirs +@var{N}}
1859 The string that would be displayed by @samp{dirs -@var{N}}
1862 @node Shell Parameter Expansion
1863 @subsection Shell Parameter Expansion
1864 @cindex parameter expansion
1865 @cindex expansion, parameter
1867 The @samp{$} character introduces parameter expansion,
1868 command substitution, or arithmetic expansion. The parameter name
1869 or symbol to be expanded may be enclosed in braces, which
1870 are optional but serve to protect the variable to be expanded from
1871 characters immediately following it which could be
1872 interpreted as part of the name.
1874 When braces are used, the matching ending brace is the first @samp{@}}
1875 not escaped by a backslash or within a quoted string, and not within an
1876 embedded arithmetic expansion, command substitution, or parameter
1879 The basic form of parameter expansion is $@{@var{parameter}@}.
1880 The value of @var{parameter} is substituted.
1881 The @var{parameter} is a shell parameter as described above
1882 (@pxref{Shell Parameters}) or an array reference (@pxref{Arrays}).
1883 The braces are required when @var{parameter}
1884 is a positional parameter with more than one digit,
1885 or when @var{parameter} is followed by a character that is not to be
1886 interpreted as part of its name.
1888 If the first character of @var{parameter} is an exclamation point (!),
1889 and @var{parameter} is not a @var{nameref},
1890 it introduces a level of variable indirection.
1891 Bash uses the value of the variable formed from the rest of
1892 @var{parameter} as the name of the variable; this variable is then
1893 expanded and that value is used in the rest of the substitution, rather
1894 than the value of @var{parameter} itself.
1895 This is known as @code{indirect expansion}.
1896 If @var{parameter} is a nameref, this expands to the name of the
1897 variable referenced by @var{parameter} instead of performing the
1898 complete indirect expansion.
1899 The exceptions to this are the expansions of $@{!@var{prefix}*@}
1900 and $@{!@var{name}[@@]@}
1902 The exclamation point must immediately follow the left brace in order to
1903 introduce indirection.
1905 In each of the cases below, @var{word} is subject to tilde expansion,
1906 parameter expansion, command substitution, and arithmetic expansion.
1908 When not performing substring expansion, using the form described
1909 below (e.g., @samp{:-}), Bash tests for a parameter that is unset or null.
1910 Omitting the colon results in a test only for a parameter that is unset.
1911 Put another way, if the colon is included,
1912 the operator tests for both @var{parameter}'s existence and that its value
1913 is not null; if the colon is omitted, the operator tests only for existence.
1917 @item $@{@var{parameter}:@minus{}@var{word}@}
1918 If @var{parameter} is unset or null, the expansion of
1919 @var{word} is substituted. Otherwise, the value of
1920 @var{parameter} is substituted.
1922 @item $@{@var{parameter}:=@var{word}@}
1924 is unset or null, the expansion of @var{word}
1925 is assigned to @var{parameter}.
1926 The value of @var{parameter} is then substituted.
1927 Positional parameters and special parameters may not be assigned to
1930 @item $@{@var{parameter}:?@var{word}@}
1932 is null or unset, the expansion of @var{word} (or a message
1933 to that effect if @var{word}
1934 is not present) is written to the standard error and the shell, if it
1935 is not interactive, exits. Otherwise, the value of @var{parameter} is
1938 @item $@{@var{parameter}:+@var{word}@}
1940 is null or unset, nothing is substituted, otherwise the expansion of
1941 @var{word} is substituted.
1943 @item $@{@var{parameter}:@var{offset}@}
1944 @itemx $@{@var{parameter}:@var{offset}:@var{length}@}
1945 This is referred to as Substring Expansion.
1946 It expands to up to @var{length} characters of the value of @var{parameter}
1947 starting at the character specified by @var{offset}.
1948 If @var{parameter} is @samp{@@}, an indexed array subscripted by
1949 @samp{@@} or @samp{*}, or an associative array name, the results differ as
1951 If @var{length} is omitted, it expands to the substring of the value of
1952 @var{parameter} starting at the character specified by @var{offset}
1953 and extending to the end of the value.
1954 @var{length} and @var{offset} are arithmetic expressions
1955 (@pxref{Shell Arithmetic}).
1957 If @var{offset} evaluates to a number less than zero, the value
1958 is used as an offset in characters
1959 from the end of the value of @var{parameter}.
1960 If @var{length} evaluates to a number less than zero,
1961 it is interpreted as an offset in characters
1962 from the end of the value of @var{parameter} rather than
1963 a number of characters, and the expansion is the characters between
1964 @var{offset} and that result.
1965 Note that a negative offset must be separated from the colon by at least
1966 one space to avoid being confused with the @samp{:-} expansion.
1968 Here are some examples illustrating substring expansion on parameters and
1972 $ string=01234567890abcdefgh
1975 $ echo ${string:7:0}
1977 $ echo ${string:7:2}
1979 $ echo ${string:7:-2}
1981 $ echo ${string: -7}
1983 $ echo ${string: -7:0}
1985 $ echo ${string: -7:2}
1987 $ echo ${string: -7:-2}
1989 $ set -- 01234567890abcdefgh
2006 $ array[0]=01234567890abcdefgh
2007 $ echo ${array[0]:7}
2009 $ echo ${array[0]:7:0}
2011 $ echo ${array[0]:7:2}
2013 $ echo ${array[0]:7:-2}
2015 $ echo ${array[0]: -7}
2017 $ echo ${array[0]: -7:0}
2019 $ echo ${array[0]: -7:2}
2021 $ echo ${array[0]: -7:-2}
2025 If @var{parameter} is @samp{@@}, the result is @var{length} positional
2026 parameters beginning at @var{offset}.
2027 A negative @var{offset} is taken relative to one greater than the greatest
2028 positional parameter, so an offset of -1 evaluates to the last positional
2030 It is an expansion error if @var{length} evaluates to a number less than zero.
2032 The following examples illustrate substring expansion using positional
2036 $ set -- 1 2 3 4 5 6 7 8 9 0 a b c d e f g h
2038 7 8 9 0 a b c d e f g h
2044 bash: -2: substring expression < 0
2048 ./bash 1 2 3 4 5 6 7 8 9 0 a b c d e f g h
2055 If @var{parameter} is an indexed array name subscripted
2056 by @samp{@@} or @samp{*}, the result is the @var{length}
2057 members of the array beginning with @code{$@{@var{parameter}[@var{offset}]@}}.
2058 A negative @var{offset} is taken relative to one greater than the maximum
2059 index of the specified array.
2060 It is an expansion error if @var{length} evaluates to a number less than zero.
2062 These examples show how you can use substring expansion with indexed
2066 $ array=(0 1 2 3 4 5 6 7 8 9 0 a b c d e f g h)
2067 $ echo ${array[@]:7}
2068 7 8 9 0 a b c d e f g h
2069 $ echo ${array[@]:7:2}
2071 $ echo ${array[@]: -7:2}
2073 $ echo ${array[@]: -7:-2}
2074 bash: -2: substring expression < 0
2075 $ echo ${array[@]:0}
2076 0 1 2 3 4 5 6 7 8 9 0 a b c d e f g h
2077 $ echo ${array[@]:0:2}
2079 $ echo ${array[@]: -7:0}
2083 Substring expansion applied to an associative array produces undefined
2086 Substring indexing is zero-based unless the positional parameters
2087 are used, in which case the indexing starts at 1 by default.
2088 If @var{offset} is 0, and the positional parameters are used, @code{$@@} is
2089 prefixed to the list.
2091 @item $@{!@var{prefix}*@}
2092 @itemx $@{!@var{prefix}@@@}
2093 Expands to the names of variables whose names begin with @var{prefix},
2094 separated by the first character of the @env{IFS} special variable.
2095 When @samp{@@} is used and the expansion appears within double quotes, each
2096 variable name expands to a separate word.
2098 @item $@{!@var{name}[@@]@}
2099 @itemx $@{!@var{name}[*]@}
2100 If @var{name} is an array variable, expands to the list of array indices
2101 (keys) assigned in @var{name}.
2102 If @var{name} is not an array, expands to 0 if @var{name} is set and null
2104 When @samp{@@} is used and the expansion appears within double quotes, each
2105 key expands to a separate word.
2107 @item $@{#@var{parameter}@}
2108 The length in characters of the expanded value of @var{parameter} is
2110 If @var{parameter} is @samp{*} or @samp{@@}, the value substituted
2111 is the number of positional parameters.
2112 If @var{parameter} is an array name subscripted by @samp{*} or @samp{@@},
2113 the value substituted is the number of elements in the array.
2115 is an indexed array name subscripted by a negative number, that number is
2116 interpreted as relative to one greater than the maximum index of
2117 @var{parameter}, so negative indices count back from the end of the
2118 array, and an index of -1 references the last element.
2120 @item $@{@var{parameter}#@var{word}@}
2121 @itemx $@{@var{parameter}##@var{word}@}
2123 is expanded to produce a pattern just as in filename
2124 expansion (@pxref{Filename Expansion}). If the pattern matches
2125 the beginning of the expanded value of @var{parameter},
2126 then the result of the expansion is the expanded value of @var{parameter}
2127 with the shortest matching pattern (the @samp{#} case) or the
2128 longest matching pattern (the @samp{##} case) deleted.
2129 If @var{parameter} is @samp{@@} or @samp{*},
2130 the pattern removal operation is applied to each positional
2131 parameter in turn, and the expansion is the resultant list.
2132 If @var{parameter} is an array variable subscripted with
2133 @samp{@@} or @samp{*},
2134 the pattern removal operation is applied to each member of the
2135 array in turn, and the expansion is the resultant list.
2137 @item $@{@var{parameter}%@var{word}@}
2138 @itemx $@{@var{parameter}%%@var{word}@}
2139 The @var{word} is expanded to produce a pattern just as in
2141 If the pattern matches a trailing portion of the expanded value of
2142 @var{parameter}, then the result of the expansion is the value of
2143 @var{parameter} with the shortest matching pattern (the @samp{%} case)
2144 or the longest matching pattern (the @samp{%%} case) deleted.
2145 If @var{parameter} is @samp{@@} or @samp{*},
2146 the pattern removal operation is applied to each positional
2147 parameter in turn, and the expansion is the resultant list.
2149 is an array variable subscripted with @samp{@@} or @samp{*},
2150 the pattern removal operation is applied to each member of the
2151 array in turn, and the expansion is the resultant list.
2153 @item $@{@var{parameter}/@var{pattern}/@var{string}@}
2155 The @var{pattern} is expanded to produce a pattern just as in
2157 @var{Parameter} is expanded and the longest match of @var{pattern}
2158 against its value is replaced with @var{string}.
2159 If @var{pattern} begins with @samp{/}, all matches of @var{pattern} are
2160 replaced with @var{string}. Normally only the first match is replaced.
2161 If @var{pattern} begins with @samp{#}, it must match at the beginning
2162 of the expanded value of @var{parameter}.
2163 If @var{pattern} begins with @samp{%}, it must match at the end
2164 of the expanded value of @var{parameter}.
2165 If @var{string} is null, matches of @var{pattern} are deleted
2166 and the @code{/} following @var{pattern} may be omitted.
2167 If the @code{nocasematch} shell option
2168 (see the description of @code{shopt} in @ref{The Shopt Builtin})
2169 is enabled, the match is performed without regard to the case
2170 of alphabetic characters.
2171 If @var{parameter} is @samp{@@} or @samp{*},
2172 the substitution operation is applied to each positional
2173 parameter in turn, and the expansion is the resultant list.
2175 is an array variable subscripted with @samp{@@} or @samp{*},
2176 the substitution operation is applied to each member of the
2177 array in turn, and the expansion is the resultant list.
2179 @item $@{@var{parameter}^@var{pattern}@}
2180 @itemx $@{@var{parameter}^^@var{pattern}@}
2181 @itemx $@{@var{parameter},@var{pattern}@}
2182 @itemx $@{@var{parameter},,@var{pattern}@}
2183 This expansion modifies the case of alphabetic characters in @var{parameter}.
2184 The @var{pattern} is expanded to produce a pattern just as in
2186 Each character in the expanded value of @var{parameter} is tested against
2187 @var{pattern}, and, if it matches the pattern, its case is converted.
2188 The pattern should not attempt to match more than one character.
2189 The @samp{^} operator converts lowercase letters matching @var{pattern}
2190 to uppercase; the @samp{,} operator converts matching uppercase letters
2192 The @samp{^^} and @samp{,,} expansions convert each matched character in the
2193 expanded value; the @samp{^} and @samp{,} expansions match and convert only
2194 the first character in the expanded value.
2195 If @var{pattern} is omitted, it is treated like a @samp{?}, which matches
2197 If @var{parameter} is @samp{@@} or @samp{*},
2198 the case modification operation is applied to each positional
2199 parameter in turn, and the expansion is the resultant list.
2201 is an array variable subscripted with @samp{@@} or @samp{*},
2202 the case modification operation is applied to each member of the
2203 array in turn, and the expansion is the resultant list.
2205 @item $@{@var{parameter}@@@var{operator}@}
2206 The expansion is either a transformation of the value of @var{parameter}
2207 or information about @var{parameter} itself, depending on the value of
2208 @var{operator}. Each @var{operator} is a single letter:
2212 The expansion is a string that is the value of @var{parameter} quoted in a
2213 format that can be reused as input.
2215 The expansion is a string that is the value of @var{parameter} with backslash
2216 escape sequences expanded as with the @code{$'@dots{}'} quoting mechansim.
2218 The expansion is a string that is the result of expanding the value of
2219 @var{parameter} as if it were a prompt string (@pxref{Controlling the Prompt}).
2221 The expansion is a string in the form of
2222 an assignment statement or @code{declare} command that, if
2223 evaluated, will recreate @var{parameter} with its attributes and value.
2225 The expansion is a string consisting of flag values representing
2226 @var{parameter}'s attributes.
2229 If @var{parameter} is @samp{@@} or @samp{*},
2230 the operation is applied to each positional
2231 parameter in turn, and the expansion is the resultant list.
2233 is an array variable subscripted with @samp{@@} or @samp{*},
2234 the operation is applied to each member of the
2235 array in turn, and the expansion is the resultant list.
2237 The result of the expansion is subject to word splitting and pathname
2238 expansion as described below.
2241 @node Command Substitution
2242 @subsection Command Substitution
2243 @cindex command substitution
2245 Command substitution allows the output of a command to replace
2247 Command substitution occurs when a command is enclosed as follows:
2258 Bash performs the expansion by executing @var{command} in a subshell environment
2259 and replacing the command substitution with the standard output of the
2260 command, with any trailing newlines deleted.
2261 Embedded newlines are not deleted, but they may be removed during
2263 The command substitution @code{$(cat @var{file})} can be
2264 replaced by the equivalent but faster @code{$(< @var{file})}.
2266 When the old-style backquote form of substitution is used,
2267 backslash retains its literal meaning except when followed by
2268 @samp{$}, @samp{`}, or @samp{\}.
2269 The first backquote not preceded by a backslash terminates the
2270 command substitution.
2271 When using the @code{$(@var{command})} form, all characters between
2272 the parentheses make up the command; none are treated specially.
2274 Command substitutions may be nested. To nest when using the backquoted
2275 form, escape the inner backquotes with backslashes.
2277 If the substitution appears within double quotes, word splitting and
2278 filename expansion are not performed on the results.
2280 @node Arithmetic Expansion
2281 @subsection Arithmetic Expansion
2282 @cindex expansion, arithmetic
2283 @cindex arithmetic expansion
2285 Arithmetic expansion allows the evaluation of an arithmetic expression
2286 and the substitution of the result. The format for arithmetic expansion is:
2289 $(( @var{expression} ))
2292 The expression is treated as if it were within double quotes, but
2293 a double quote inside the parentheses is not treated specially.
2294 All tokens in the expression undergo parameter and variable expansion,
2295 command substitution, and quote removal.
2296 The result is treated as the arithmetic expression to be evaluated.
2297 Arithmetic expansions may be nested.
2299 The evaluation is performed according to the rules listed below
2300 (@pxref{Shell Arithmetic}).
2301 If the expression is invalid, Bash prints a message indicating
2302 failure to the standard error and no substitution occurs.
2304 @node Process Substitution
2305 @subsection Process Substitution
2306 @cindex process substitution
2308 Process substitution allows a process's input or output to be
2309 referred to using a filename.
2310 It takes the form of
2320 The process @var{list} is run asynchronously, and its input or output
2321 appears as a filename.
2323 passed as an argument to the current command as the result of the
2325 If the @code{>(@var{list})} form is used, writing to
2326 the file will provide input for @var{list}. If the
2327 @code{<(@var{list})} form is used, the file passed as an
2328 argument should be read to obtain the output of @var{list}.
2329 Note that no space may appear between the @code{<} or @code{>}
2330 and the left parenthesis, otherwise the construct would be interpreted
2332 Process substitution is supported on systems that support named
2333 pipes (@sc{fifo}s) or the @file{/dev/fd} method of naming open files.
2335 When available, process substitution is performed simultaneously with
2336 parameter and variable expansion, command substitution, and arithmetic
2339 @node Word Splitting
2340 @subsection Word Splitting
2341 @cindex word splitting
2343 The shell scans the results of parameter expansion, command substitution,
2344 and arithmetic expansion that did not occur within double quotes for
2347 The shell treats each character of @env{$IFS} as a delimiter, and splits
2348 the results of the other expansions into words using these characters
2349 as field terminators.
2350 If @env{IFS} is unset, or its value is exactly @code{<space><tab><newline>},
2351 the default, then sequences of
2352 @code{ <space>}, @code{<tab>}, and @code{<newline>}
2353 at the beginning and end of the results of the previous
2354 expansions are ignored, and any sequence of @env{IFS}
2355 characters not at the beginning or end serves to delimit words.
2356 If @env{IFS} has a value other than the default, then sequences of
2357 the whitespace characters @code{space}, @code{tab}, and @code{newline}
2358 are ignored at the beginning and end of the
2359 word, as long as the whitespace character is in the
2360 value of @env{IFS} (an @env{IFS} whitespace character).
2361 Any character in @env{IFS} that is not @env{IFS}
2362 whitespace, along with any adjacent @env{IFS}
2363 whitespace characters, delimits a field. A sequence of @env{IFS}
2364 whitespace characters is also treated as a delimiter.
2365 If the value of @env{IFS} is null, no word splitting occurs.
2367 Explicit null arguments (@code{""} or @code{''}) are retained
2368 and passed to commands as empty strings.
2369 Unquoted implicit null arguments, resulting from the expansion of
2370 parameters that have no values, are removed.
2371 If a parameter with no value is expanded within double quotes, a
2372 null argument results and is retained
2373 and passed to a command as an empty string.
2374 When a quoted null argument appears as part of a word whose expansion is
2375 non-null, the null argument is removed.
2377 @code{-d''} becomes @code{-d} after word splitting and
2378 null argument removal.
2380 Note that if no expansion occurs, no splitting
2383 @node Filename Expansion
2384 @subsection Filename Expansion
2386 * Pattern Matching:: How the shell matches patterns.
2388 @cindex expansion, filename
2389 @cindex expansion, pathname
2390 @cindex filename expansion
2391 @cindex pathname expansion
2393 After word splitting, unless the @option{-f} option has been set
2394 (@pxref{The Set Builtin}), Bash scans each word for the characters
2395 @samp{*}, @samp{?}, and @samp{[}.
2396 If one of these characters appears, then the word is
2397 regarded as a @var{pattern},
2398 and replaced with an alphabetically sorted list of
2399 filenames matching the pattern (@pxref{Pattern Matching}).
2400 If no matching filenames are found,
2401 and the shell option @code{nullglob} is disabled, the word is left
2403 If the @code{nullglob} option is set, and no matches are found, the word
2405 If the @code{failglob} shell option is set, and no matches are found,
2406 an error message is printed and the command is not executed.
2407 If the shell option @code{nocaseglob} is enabled, the match is performed
2408 without regard to the case of alphabetic characters.
2410 When a pattern is used for filename expansion, the character @samp{.}
2411 at the start of a filename or immediately following a slash
2412 must be matched explicitly, unless the shell option @code{dotglob} is set.
2413 When matching a filename, the slash character must always be
2415 In other cases, the @samp{.} character is not treated specially.
2417 See the description of @code{shopt} in @ref{The Shopt Builtin},
2418 for a description of the @code{nocaseglob}, @code{nullglob},
2419 @code{failglob}, and @code{dotglob} options.
2421 The @env{GLOBIGNORE}
2422 shell variable may be used to restrict the set of filenames matching a
2423 pattern. If @env{GLOBIGNORE}
2424 is set, each matching filename that also matches one of the patterns in
2425 @env{GLOBIGNORE} is removed from the list of matches.
2426 If the @code{nocaseglob} option is set, the matching against the patterns in
2427 @env{GLOBIGNORE} is performed without regard to case.
2429 @file{.} and @file{..}
2430 are always ignored when @env{GLOBIGNORE}
2431 is set and not null.
2432 However, setting @env{GLOBIGNORE} to a non-null value has the effect of
2433 enabling the @code{dotglob}
2434 shell option, so all other filenames beginning with a
2435 @samp{.} will match.
2436 To get the old behavior of ignoring filenames beginning with a
2437 @samp{.}, make @samp{.*} one of the patterns in @env{GLOBIGNORE}.
2438 The @code{dotglob} option is disabled when @env{GLOBIGNORE}
2441 @node Pattern Matching
2442 @subsubsection Pattern Matching
2443 @cindex pattern matching
2444 @cindex matching, pattern
2446 Any character that appears in a pattern, other than the special pattern
2447 characters described below, matches itself.
2448 The @sc{nul} character may not occur in a pattern.
2449 A backslash escapes the following character; the
2450 escaping backslash is discarded when matching.
2451 The special pattern characters must be quoted if they are to be matched
2454 The special pattern characters have the following meanings:
2457 Matches any string, including the null string.
2458 When the @code{globstar} shell option is enabled, and @samp{*} is used in
2459 a filename expansion context, two adjacent @samp{*}s used as a single
2460 pattern will match all files and zero or more directories and
2462 If followed by a @samp{/}, two adjacent @samp{*}s will match only
2463 directories and subdirectories.
2465 Matches any single character.
2467 Matches any one of the enclosed characters. A pair of characters
2468 separated by a hyphen denotes a @var{range expression};
2469 any character that falls between those two characters, inclusive,
2470 using the current locale's collating sequence and character set,
2471 is matched. If the first character following the
2472 @samp{[} is a @samp{!} or a @samp{^}
2473 then any character not enclosed is matched. A @samp{@minus{}}
2474 may be matched by including it as the first or last character
2475 in the set. A @samp{]} may be matched by including it as the first
2476 character in the set.
2477 The sorting order of characters in range expressions is determined by
2478 the current locale and the values of the
2479 @env{LC_COLLATE} and @env{LC_ALL} shell variables, if set.
2481 For example, in the default C locale, @samp{[a-dx-z]} is equivalent to
2482 @samp{[abcdxyz]}. Many locales sort characters in dictionary order, and in
2483 these locales @samp{[a-dx-z]} is typically not equivalent to @samp{[abcdxyz]};
2484 it might be equivalent to @samp{[aBbCcDdxXyYz]}, for example. To obtain
2485 the traditional interpretation of ranges in bracket expressions, you can
2486 force the use of the C locale by setting the @env{LC_COLLATE} or
2487 @env{LC_ALL} environment variable to the value @samp{C}, or enable the
2488 @code{globasciiranges} shell option.
2490 Within @samp{[} and @samp{]}, @var{character classes} can be specified
2492 @code{[:}@var{class}@code{:]}, where @var{class} is one of the
2493 following classes defined in the @sc{posix} standard:
2495 alnum alpha ascii blank cntrl digit graph lower
2496 print punct space upper word xdigit
2499 A character class matches any character belonging to that class.
2500 The @code{word} character class matches letters, digits, and the character
2503 Within @samp{[} and @samp{]}, an @var{equivalence class} can be
2504 specified using the syntax @code{[=}@var{c}@code{=]}, which
2505 matches all characters with the same collation weight (as defined
2506 by the current locale) as the character @var{c}.
2508 Within @samp{[} and @samp{]}, the syntax @code{[.}@var{symbol}@code{.]}
2509 matches the collating symbol @var{symbol}.
2512 If the @code{extglob} shell option is enabled using the @code{shopt}
2513 builtin, several extended pattern matching operators are recognized.
2514 In the following description, a @var{pattern-list} is a list of one
2515 or more patterns separated by a @samp{|}.
2516 Composite patterns may be formed using one or more of the following
2520 @item ?(@var{pattern-list})
2521 Matches zero or one occurrence of the given patterns.
2523 @item *(@var{pattern-list})
2524 Matches zero or more occurrences of the given patterns.
2526 @item +(@var{pattern-list})
2527 Matches one or more occurrences of the given patterns.
2529 @item @@(@var{pattern-list})
2530 Matches one of the given patterns.
2532 @item !(@var{pattern-list})
2533 Matches anything except one of the given patterns.
2537 @subsection Quote Removal
2539 After the preceding expansions, all unquoted occurrences of the
2540 characters @samp{\}, @samp{'}, and @samp{"} that did not
2541 result from one of the above expansions are removed.
2544 @section Redirections
2547 Before a command is executed, its input and output
2548 may be @var{redirected}
2549 using a special notation interpreted by the shell.
2550 Redirection allows commands' file handles to be
2551 duplicated, opened, closed,
2552 made to refer to different files,
2553 and can change the files the command reads from and writes to.
2554 Redirection may also be used to modify file handles in the
2555 current shell execution environment. The following redirection
2556 operators may precede or appear anywhere within a
2557 simple command or may follow a command.
2558 Redirections are processed in the order they appear, from
2561 Each redirection that may be preceded by a file descriptor number
2562 may instead be preceded by a word of the form @{@var{varname}@}.
2563 In this case, for each redirection operator except
2564 >&- and <&-, the shell will allocate a file descriptor greater
2565 than 10 and assign it to @{@var{varname}@}. If >&- or <&- is preceded
2566 by @{@var{varname}@}, the value of @var{varname} defines the file
2567 descriptor to close.
2569 In the following descriptions, if the file descriptor number is
2570 omitted, and the first character of the redirection operator is
2571 @samp{<}, the redirection refers to the standard input (file
2572 descriptor 0). If the first character of the redirection operator
2573 is @samp{>}, the redirection refers to the standard output (file
2576 The word following the redirection operator in the following
2577 descriptions, unless otherwise noted, is subjected to brace expansion,
2578 tilde expansion, parameter expansion, command substitution, arithmetic
2579 expansion, quote removal, filename expansion, and word splitting.
2580 If it expands to more than one word, Bash reports an error.
2582 Note that the order of redirections is significant. For example,
2585 ls > @var{dirlist} 2>&1
2588 directs both standard output (file descriptor 1) and standard error
2589 (file descriptor 2) to the file @var{dirlist}, while the command
2591 ls 2>&1 > @var{dirlist}
2594 directs only the standard output to file @var{dirlist},
2595 because the standard error was made a copy of the standard output
2596 before the standard output was redirected to @var{dirlist}.
2598 Bash handles several filenames specially when they are used in
2599 redirections, as described in the following table.
2600 If the operating system on which Bash is running provides these
2601 special files, bash will use them; otherwise it will emulate them
2602 internally with the behavior described below.
2605 @item /dev/fd/@var{fd}
2606 If @var{fd} is a valid integer, file descriptor @var{fd} is duplicated.
2609 File descriptor 0 is duplicated.
2612 File descriptor 1 is duplicated.
2615 File descriptor 2 is duplicated.
2617 @item /dev/tcp/@var{host}/@var{port}
2618 If @var{host} is a valid hostname or Internet address, and @var{port}
2619 is an integer port number or service name, Bash attempts to open
2620 the corresponding TCP socket.
2622 @item /dev/udp/@var{host}/@var{port}
2623 If @var{host} is a valid hostname or Internet address, and @var{port}
2624 is an integer port number or service name, Bash attempts to open
2625 the corresponding UDP socket.
2628 A failure to open or create a file causes the redirection to fail.
2630 Redirections using file descriptors greater than 9 should be used with
2631 care, as they may conflict with file descriptors the shell uses
2634 @subsection Redirecting Input
2635 Redirection of input causes the file whose name results from
2636 the expansion of @var{word}
2637 to be opened for reading on file descriptor @code{n},
2638 or the standard input (file descriptor 0) if @code{n}
2641 The general format for redirecting input is:
2643 [@var{n}]<@var{word}
2646 @subsection Redirecting Output
2647 Redirection of output causes the file whose name results from
2648 the expansion of @var{word}
2649 to be opened for writing on file descriptor @var{n},
2650 or the standard output (file descriptor 1) if @var{n}
2651 is not specified. If the file does not exist it is created;
2652 if it does exist it is truncated to zero size.
2654 The general format for redirecting output is:
2656 [@var{n}]>[|]@var{word}
2659 If the redirection operator is @samp{>}, and the @code{noclobber}
2660 option to the @code{set} builtin has been enabled, the redirection
2661 will fail if the file whose name results from the expansion of
2662 @var{word} exists and is a regular file.
2663 If the redirection operator is @samp{>|}, or the redirection operator is
2664 @samp{>} and the @code{noclobber} option is not enabled, the redirection
2665 is attempted even if the file named by @var{word} exists.
2667 @subsection Appending Redirected Output
2668 Redirection of output in this fashion
2669 causes the file whose name results from
2670 the expansion of @var{word}
2671 to be opened for appending on file descriptor @var{n},
2672 or the standard output (file descriptor 1) if @var{n}
2673 is not specified. If the file does not exist it is created.
2675 The general format for appending output is:
2677 [@var{n}]>>@var{word}
2680 @subsection Redirecting Standard Output and Standard Error
2681 This construct allows both the
2682 standard output (file descriptor 1) and
2683 the standard error output (file descriptor 2)
2684 to be redirected to the file whose name is the
2685 expansion of @var{word}.
2687 There are two formats for redirecting standard output and
2698 Of the two forms, the first is preferred.
2699 This is semantically equivalent to
2703 When using the second form, @var{word} may not expand to a number or
2704 @samp{-}. If it does, other redirection operators apply
2705 (see Duplicating File Descriptors below) for compatibility reasons.
2707 @subsection Appending Standard Output and Standard Error
2708 This construct allows both the
2709 standard output (file descriptor 1) and
2710 the standard error output (file descriptor 2)
2711 to be appended to the file whose name is the
2712 expansion of @var{word}.
2714 The format for appending standard output and standard error is:
2719 This is semantically equivalent to
2723 (see Duplicating File Descriptors below).
2725 @subsection Here Documents
2726 This type of redirection instructs the shell to read input from the
2727 current source until a line containing only @var{word}
2728 (with no trailing blanks) is seen. All of
2729 the lines read up to that point are then used as the standard
2730 input (or file descriptor @var{n} if @var{n} is specified) for a command.
2732 The format of here-documents is:
2734 [@var{n}]<<[@minus{}]@var{word}
2739 No parameter and variable expansion, command substitution,
2740 arithmetic expansion, or filename expansion is performed on
2741 @var{word}. If any part of @var{word} is quoted, the
2742 @var{delimiter} is the result of quote removal on @var{word},
2743 and the lines in the here-document are not expanded.
2744 If @var{word} is unquoted,
2745 all lines of the here-document are subjected to
2746 parameter expansion, command substitution, and arithmetic expansion,
2747 the character sequence @code{\newline} is ignored, and @samp{\}
2748 must be used to quote the characters
2749 @samp{\}, @samp{$}, and @samp{`}.
2751 If the redirection operator is @samp{<<-},
2752 then all leading tab characters are stripped from input lines and the
2753 line containing @var{delimiter}.
2754 This allows here-documents within shell scripts to be indented in a
2757 @subsection Here Strings
2758 A variant of here documents, the format is:
2760 [@var{n}]<<< @var{word}
2763 The @var{word} undergoes
2764 brace expansion, tilde expansion, parameter and variable expansion,
2765 command substitution, arithmetic expansion, and quote removal.
2766 Pathname expansion and word splitting are not performed.
2767 The result is supplied as a single string,
2768 with a newline appended,
2769 to the command on its
2770 standard input (or file descriptor @var{n} if @var{n} is specified).
2772 @subsection Duplicating File Descriptors
2773 The redirection operator
2775 [@var{n}]<&@var{word}
2778 is used to duplicate input file descriptors.
2780 expands to one or more digits, the file descriptor denoted by @var{n}
2781 is made to be a copy of that file descriptor.
2782 If the digits in @var{word} do not specify a file descriptor open for
2783 input, a redirection error occurs.
2785 evaluates to @samp{-}, file descriptor @var{n} is closed.
2786 If @var{n} is not specified, the standard input (file descriptor 0) is used.
2790 [@var{n}]>&@var{word}
2793 is used similarly to duplicate output file descriptors. If
2794 @var{n} is not specified, the standard output (file descriptor 1) is used.
2795 If the digits in @var{word} do not specify a file descriptor open for
2796 output, a redirection error occurs.
2798 evaluates to @samp{-}, file descriptor @var{n} is closed.
2799 As a special case, if @var{n} is omitted, and @var{word} does not
2800 expand to one or more digits or @samp{-}, the standard output and standard
2801 error are redirected as described previously.
2803 @subsection Moving File Descriptors
2804 The redirection operator
2806 [@var{n}]<&@var{digit}-
2809 moves the file descriptor @var{digit} to file descriptor @var{n},
2810 or the standard input (file descriptor 0) if @var{n} is not specified.
2811 @var{digit} is closed after being duplicated to @var{n}.
2813 Similarly, the redirection operator
2815 [@var{n}]>&@var{digit}-
2818 moves the file descriptor @var{digit} to file descriptor @var{n},
2819 or the standard output (file descriptor 1) if @var{n} is not specified.
2821 @subsection Opening File Descriptors for Reading and Writing
2822 The redirection operator
2824 [@var{n}]<>@var{word}
2827 causes the file whose name is the expansion of @var{word}
2828 to be opened for both reading and writing on file descriptor
2829 @var{n}, or on file descriptor 0 if @var{n}
2830 is not specified. If the file does not exist, it is created.
2832 @node Executing Commands
2833 @section Executing Commands
2836 * Simple Command Expansion:: How Bash expands simple commands before
2838 * Command Search and Execution:: How Bash finds commands and runs them.
2839 * Command Execution Environment:: The environment in which Bash
2840 executes commands that are not
2842 * Environment:: The environment given to a command.
2843 * Exit Status:: The status returned by commands and how Bash
2845 * Signals:: What happens when Bash or a command it runs
2849 @node Simple Command Expansion
2850 @subsection Simple Command Expansion
2851 @cindex command expansion
2853 When a simple command is executed, the shell performs the following
2854 expansions, assignments, and redirections, from left to right.
2858 The words that the parser has marked as variable assignments (those
2859 preceding the command name) and redirections are saved for later
2863 The words that are not variable assignments or redirections are
2864 expanded (@pxref{Shell Expansions}).
2865 If any words remain after expansion, the first word
2866 is taken to be the name of the command and the remaining words are
2870 Redirections are performed as described above (@pxref{Redirections}).
2873 The text after the @samp{=} in each variable assignment undergoes tilde
2874 expansion, parameter expansion, command substitution, arithmetic expansion,
2875 and quote removal before being assigned to the variable.
2878 If no command name results, the variable assignments affect the current
2879 shell environment. Otherwise, the variables are added to the environment
2880 of the executed command and do not affect the current shell environment.
2881 If any of the assignments attempts to assign a value to a readonly variable,
2882 an error occurs, and the command exits with a non-zero status.
2884 If no command name results, redirections are performed, but do not
2885 affect the current shell environment. A redirection error causes the
2886 command to exit with a non-zero status.
2888 If there is a command name left after expansion, execution proceeds as
2889 described below. Otherwise, the command exits. If one of the expansions
2890 contained a command substitution, the exit status of the command is
2891 the exit status of the last command substitution performed. If there
2892 were no command substitutions, the command exits with a status of zero.
2894 @node Command Search and Execution
2895 @subsection Command Search and Execution
2896 @cindex command execution
2897 @cindex command search
2899 After a command has been split into words, if it results in a
2900 simple command and an optional list of arguments, the following
2905 If the command name contains no slashes, the shell attempts to
2906 locate it. If there exists a shell function by that name, that
2907 function is invoked as described in @ref{Shell Functions}.
2910 If the name does not match a function, the shell searches for
2911 it in the list of shell builtins. If a match is found, that
2915 If the name is neither a shell function nor a builtin,
2916 and contains no slashes, Bash searches each element of
2917 @env{$PATH} for a directory containing an executable file
2918 by that name. Bash uses a hash table to remember the full
2919 pathnames of executable files to avoid multiple @env{PATH} searches
2920 (see the description of @code{hash} in @ref{Bourne Shell Builtins}).
2921 A full search of the directories in @env{$PATH}
2922 is performed only if the command is not found in the hash table.
2923 If the search is unsuccessful, the shell searches for a defined shell
2924 function named @code{command_not_found_handle}.
2925 If that function exists, it is invoked with the original command and
2926 the original command's arguments as its arguments, and the function's
2927 exit status becomes the exit status of the shell.
2928 If that function is not defined, the shell prints an error
2929 message and returns an exit status of 127.
2932 If the search is successful, or if the command name contains
2933 one or more slashes, the shell executes the named program in
2934 a separate execution environment.
2935 Argument 0 is set to the name given, and the remaining arguments
2936 to the command are set to the arguments supplied, if any.
2939 If this execution fails because the file is not in executable
2940 format, and the file is not a directory, it is assumed to be a
2941 @var{shell script} and the shell executes it as described in
2942 @ref{Shell Scripts}.
2945 If the command was not begun asynchronously, the shell waits for
2946 the command to complete and collects its exit status.
2950 @node Command Execution Environment
2951 @subsection Command Execution Environment
2952 @cindex execution environment
2954 The shell has an @var{execution environment}, which consists of the
2959 open files inherited by the shell at invocation, as modified by
2960 redirections supplied to the @code{exec} builtin
2963 the current working directory as set by @code{cd}, @code{pushd}, or
2964 @code{popd}, or inherited by the shell at invocation
2967 the file creation mode mask as set by @code{umask} or inherited from
2971 current traps set by @code{trap}
2974 shell parameters that are set by variable assignment or with @code{set}
2975 or inherited from the shell's parent in the environment
2978 shell functions defined during execution or inherited from the shell's
2979 parent in the environment
2982 options enabled at invocation (either by default or with command-line
2983 arguments) or by @code{set}
2986 options enabled by @code{shopt} (@pxref{The Shopt Builtin})
2989 shell aliases defined with @code{alias} (@pxref{Aliases})
2992 various process @sc{id}s, including those of background jobs
2993 (@pxref{Lists}), the value of @code{$$}, and the value of
2998 When a simple command other than a builtin or shell function
2999 is to be executed, it
3000 is invoked in a separate execution environment that consists of
3001 the following. Unless otherwise noted, the values are inherited
3006 the shell's open files, plus any modifications and additions specified
3007 by redirections to the command
3010 the current working directory
3013 the file creation mode mask
3016 shell variables and functions marked for export, along with variables
3017 exported for the command, passed in the environment (@pxref{Environment})
3020 traps caught by the shell are reset to the values inherited from the
3021 shell's parent, and traps ignored by the shell are ignored
3025 A command invoked in this separate environment cannot affect the
3026 shell's execution environment.
3028 Command substitution, commands grouped with parentheses,
3029 and asynchronous commands are invoked in a
3030 subshell environment that is a duplicate of the shell environment,
3031 except that traps caught by the shell are reset to the values
3032 that the shell inherited from its parent at invocation. Builtin
3033 commands that are invoked as part of a pipeline are also executed
3034 in a subshell environment. Changes made to the subshell environment
3035 cannot affect the shell's execution environment.
3037 Subshells spawned to execute command substitutions inherit the value of
3038 the @option{-e} option from the parent shell. When not in @sc{posix} mode,
3039 Bash clears the @option{-e} option in such subshells.
3041 If a command is followed by a @samp{&} and job control is not active, the
3042 default standard input for the command is the empty file @file{/dev/null}.
3043 Otherwise, the invoked command inherits the file descriptors of the calling
3044 shell as modified by redirections.
3047 @subsection Environment
3050 When a program is invoked it is given an array of strings
3051 called the @var{environment}.
3052 This is a list of name-value pairs, of the form @code{name=value}.
3054 Bash provides several ways to manipulate the environment.
3055 On invocation, the shell scans its own environment and
3056 creates a parameter for each name found, automatically marking
3058 to child processes. Executed commands inherit the environment.
3059 The @code{export} and @samp{declare -x}
3060 commands allow parameters and functions to be added to and
3061 deleted from the environment. If the value of a parameter
3062 in the environment is modified, the new value becomes part
3063 of the environment, replacing the old. The environment
3064 inherited by any executed command consists of the shell's
3065 initial environment, whose values may be modified in the shell,
3066 less any pairs removed by the @code{unset} and @samp{export -n}
3067 commands, plus any additions via the @code{export} and
3068 @samp{declare -x} commands.
3070 The environment for any simple command
3071 or function may be augmented temporarily by prefixing it with
3072 parameter assignments, as described in @ref{Shell Parameters}.
3073 These assignment statements affect only the environment seen
3076 If the @option{-k} option is set (@pxref{The Set Builtin}), then all
3077 parameter assignments are placed in the environment for a command,
3078 not just those that precede the command name.
3080 When Bash invokes an external command, the variable @samp{$_}
3081 is set to the full pathname of the command and passed to that
3082 command in its environment.
3085 @subsection Exit Status
3088 The exit status of an executed command is the value returned by the
3089 @var{waitpid} system call or equivalent function. Exit statuses
3090 fall between 0 and 255, though, as explained below, the shell may
3091 use values above 125 specially. Exit statuses from shell builtins and
3092 compound commands are also limited to this range. Under certain
3093 circumstances, the shell will use special values to indicate specific
3096 For the shell's purposes, a command which exits with a
3097 zero exit status has succeeded.
3098 A non-zero exit status indicates failure.
3099 This seemingly counter-intuitive scheme is used so there
3100 is one well-defined way to indicate success and a variety of
3101 ways to indicate various failure modes.
3102 When a command terminates on a fatal signal whose number is @var{N},
3103 Bash uses the value 128+@var{N} as the exit status.
3105 If a command is not found, the child process created to
3106 execute it returns a status of 127. If a command is found
3107 but is not executable, the return status is 126.
3109 If a command fails because of an error during expansion or redirection,
3110 the exit status is greater than zero.
3112 The exit status is used by the Bash conditional commands
3113 (@pxref{Conditional Constructs}) and some of the list
3114 constructs (@pxref{Lists}).
3116 All of the Bash builtins return an exit status of zero if they succeed
3117 and a non-zero status on failure, so they may be used by the
3118 conditional and list constructs.
3119 All builtins return an exit status of 2 to indicate incorrect usage,
3120 generally invalid options or missing arguments.
3124 @cindex signal handling
3126 When Bash is interactive, in the absence of any traps, it ignores
3127 @code{SIGTERM} (so that @samp{kill 0} does not kill an interactive shell),
3129 is caught and handled (so that the @code{wait} builtin is interruptible).
3130 When Bash receives a @code{SIGINT}, it breaks out of any executing loops.
3131 In all cases, Bash ignores @code{SIGQUIT}.
3132 If job control is in effect (@pxref{Job Control}), Bash
3133 ignores @code{SIGTTIN}, @code{SIGTTOU}, and @code{SIGTSTP}.
3135 Non-builtin commands started by Bash have signal handlers set to the
3136 values inherited by the shell from its parent.
3137 When job control is not in effect, asynchronous commands
3138 ignore @code{SIGINT} and @code{SIGQUIT} in addition to these inherited
3140 Commands run as a result of
3141 command substitution ignore the keyboard-generated job control signals
3142 @code{SIGTTIN}, @code{SIGTTOU}, and @code{SIGTSTP}.
3144 The shell exits by default upon receipt of a @code{SIGHUP}.
3145 Before exiting, an interactive shell resends the @code{SIGHUP} to
3146 all jobs, running or stopped.
3147 Stopped jobs are sent @code{SIGCONT} to ensure that they receive
3149 To prevent the shell from sending the @code{SIGHUP} signal to a
3150 particular job, it should be removed
3151 from the jobs table with the @code{disown}
3152 builtin (@pxref{Job Control Builtins}) or marked
3153 to not receive @code{SIGHUP} using @code{disown -h}.
3155 If the @code{huponexit} shell option has been set with @code{shopt}
3156 (@pxref{The Shopt Builtin}), Bash sends a @code{SIGHUP} to all jobs when
3157 an interactive login shell exits.
3159 If Bash is waiting for a command to complete and receives a signal
3160 for which a trap has been set, the trap will not be executed until
3161 the command completes.
3162 When Bash is waiting for an asynchronous
3163 command via the @code{wait} builtin, the reception of a signal for
3164 which a trap has been set will cause the @code{wait} builtin to return
3165 immediately with an exit status greater than 128, immediately after
3166 which the trap is executed.
3169 @section Shell Scripts
3170 @cindex shell script
3172 A shell script is a text file containing shell commands. When such
3173 a file is used as the first non-option argument when invoking Bash,
3174 and neither the @option{-c} nor @option{-s} option is supplied
3175 (@pxref{Invoking Bash}),
3176 Bash reads and executes commands from the file, then exits. This
3177 mode of operation creates a non-interactive shell. The shell first
3178 searches for the file in the current directory, and looks in the
3179 directories in @env{$PATH} if not found there.
3182 a shell script, it sets the special parameter @code{0} to the name
3183 of the file, rather than the name of the shell, and the positional
3184 parameters are set to the remaining arguments, if any are given.
3185 If no additional arguments are supplied, the positional parameters
3188 A shell script may be made executable by using the @code{chmod} command
3189 to turn on the execute bit. When Bash finds such a file while
3190 searching the @env{$PATH} for a command, it spawns a subshell to
3191 execute it. In other words, executing
3193 filename @var{arguments}
3196 is equivalent to executing
3198 bash filename @var{arguments}
3202 if @code{filename} is an executable shell script.
3203 This subshell reinitializes itself, so that the effect is as if a
3204 new shell had been invoked to interpret the script, with the
3205 exception that the locations of commands remembered by the parent
3206 (see the description of @code{hash} in @ref{Bourne Shell Builtins})
3207 are retained by the child.
3209 Most versions of Unix make this a part of the operating system's command
3210 execution mechanism. If the first line of a script begins with
3211 the two characters @samp{#!}, the remainder of the line specifies
3212 an interpreter for the program.
3213 Thus, you can specify Bash, @code{awk}, Perl, or some other
3214 interpreter and write the rest of the script file in that language.
3216 The arguments to the interpreter
3217 consist of a single optional argument following the interpreter
3218 name on the first line of the script file, followed by the name of
3219 the script file, followed by the rest of the arguments. Bash
3220 will perform this action on operating systems that do not handle it
3221 themselves. Note that some older versions of Unix limit the interpreter
3222 name and argument to a maximum of 32 characters.
3224 Bash scripts often begin with @code{#! /bin/bash} (assuming that
3225 Bash has been installed in @file{/bin}), since this ensures that
3226 Bash will be used to interpret the script, even if it is executed
3227 under another shell.
3229 @node Shell Builtin Commands
3230 @chapter Shell Builtin Commands
3233 * Bourne Shell Builtins:: Builtin commands inherited from the Bourne
3235 * Bash Builtins:: Table of builtins specific to Bash.
3236 * Modifying Shell Behavior:: Builtins to modify shell attributes and
3238 * Special Builtins:: Builtin commands classified specially by
3242 Builtin commands are contained within the shell itself.
3243 When the name of a builtin command is used as the first word of
3244 a simple command (@pxref{Simple Commands}), the shell executes
3245 the command directly, without invoking another program.
3246 Builtin commands are necessary to implement functionality impossible
3247 or inconvenient to obtain with separate utilities.
3249 This section briefly describes the builtins which Bash inherits from
3250 the Bourne Shell, as well as the builtin commands which are unique
3251 to or have been extended in Bash.
3253 Several builtin commands are described in other chapters: builtin
3254 commands which provide the Bash interface to the job control
3255 facilities (@pxref{Job Control Builtins}), the directory stack
3256 (@pxref{Directory Stack Builtins}), the command history
3257 (@pxref{Bash History Builtins}), and the programmable completion
3258 facilities (@pxref{Programmable Completion Builtins}).
3260 Many of the builtins have been extended by @sc{posix} or Bash.
3262 Unless otherwise noted, each builtin command documented as accepting
3263 options preceded by @samp{-} accepts @samp{--}
3264 to signify the end of the options.
3265 The @code{:}, @code{true}, @code{false}, and @code{test}
3266 builtins do not accept options and do not treat @samp{--} specially.
3267 The @code{exit}, @code{logout}, @code{return},
3268 @code{break}, @code{continue}, @code{let},
3269 and @code{shift} builtins accept and process arguments beginning
3270 with @samp{-} without requiring @samp{--}.
3271 Other builtins that accept arguments but are not specified as accepting
3272 options interpret arguments beginning with @samp{-} as invalid options and
3273 require @samp{--} to prevent this interpretation.
3275 @node Bourne Shell Builtins
3276 @section Bourne Shell Builtins
3278 The following shell builtin commands are inherited from the Bourne Shell.
3279 These commands are implemented as specified by the @sc{posix} standard.
3282 @item : @r{(a colon)}
3288 Do nothing beyond expanding @var{arguments} and performing redirections.
3289 The return status is zero.
3291 @item . @r{(a period)}
3294 . @var{filename} [@var{arguments}]
3297 Read and execute commands from the @var{filename} argument in the
3298 current shell context. If @var{filename} does not contain a slash,
3299 the @env{PATH} variable is used to find @var{filename}.
3300 When Bash is not in @sc{posix} mode, the current directory is searched
3301 if @var{filename} is not found in @env{$PATH}.
3302 If any @var{arguments} are supplied, they become the positional
3303 parameters when @var{filename} is executed. Otherwise the positional
3304 parameters are unchanged.
3305 If the @option{-T} option is enabled, @code{source} inherits any trap on
3306 @code{DEBUG}; if it is not, any @code{DEBUG} trap string is saved and
3307 restored around the call to @code{source}, and @code{source} unsets the
3308 @code{DEBUG} trap while it executes.
3309 If @option{-T} is not set, and the sourced file changes
3310 the @code{DEBUG} trap, the new value is retained when @code{source} completes.
3311 The return status is the exit status of the last command executed, or
3312 zero if no commands are executed. If @var{filename} is not found, or
3313 cannot be read, the return status is non-zero.
3314 This builtin is equivalent to @code{source}.
3322 Exit from a @code{for}, @code{while}, @code{until}, or @code{select} loop.
3323 If @var{n} is supplied, the @var{n}th enclosing loop is exited.
3324 @var{n} must be greater than or equal to 1.
3325 The return status is zero unless @var{n} is not greater than or equal to 1.
3330 cd [-L|[-P [-e]] [-@@] [@var{directory}]
3333 Change the current working directory to @var{directory}.
3334 If @var{directory} is not supplied, the value of the @env{HOME}
3335 shell variable is used.
3336 Any additional arguments following @var{directory} are ignored.
3337 If the shell variable
3338 @env{CDPATH} exists, it is used as a search path:
3339 each directory name in @env{CDPATH} is searched for
3340 @var{directory}, with alternative directory names in @env{CDPATH}
3341 separated by a colon (@samp{:}).
3342 If @var{directory} begins with a slash, @env{CDPATH} is not used.
3344 The @option{-P} option means to not follow symbolic links: symbolic links
3345 are resolved while @code{cd} is traversing @var{directory} and before
3346 processing an instance of @samp{..} in @var{directory}.
3348 By default, or when the @option{-L} option is supplied, symbolic links
3349 in @var{directory} are resolved after @code{cd} processes an instance
3350 of @samp{..} in @var{directory}.
3352 If @samp{..} appears in @var{directory}, it is processed by removing the
3353 immediately preceding pathname component, back to a slash or the beginning
3356 If the @option{-e} option is supplied with @option{-P}
3357 and the current working directory cannot be successfully determined
3358 after a successful directory change, @code{cd} will return an unsuccessful
3361 On systems that support it, the @option{-@@} option presents the extended
3362 attributes associated with a file as a directory.
3364 If @var{directory} is @samp{-}, it is converted to @env{$OLDPWD}
3365 before the directory change is attempted.
3367 If a non-empty directory name from @env{CDPATH} is used, or if
3368 @samp{-} is the first argument, and the directory change is
3369 successful, the absolute pathname of the new working directory is
3370 written to the standard output.
3372 The return status is zero if the directory is successfully changed,
3381 Resume the next iteration of an enclosing @code{for}, @code{while},
3382 @code{until}, or @code{select} loop.
3383 If @var{n} is supplied, the execution of the @var{n}th enclosing loop
3385 @var{n} must be greater than or equal to 1.
3386 The return status is zero unless @var{n} is not greater than or equal to 1.
3391 eval [@var{arguments}]
3394 The arguments are concatenated together into a single command, which is
3395 then read and executed, and its exit status returned as the exit status
3397 If there are no arguments or only empty arguments, the return status is
3403 exec [-cl] [-a @var{name}] [@var{command} [@var{arguments}]]
3407 is supplied, it replaces the shell without creating a new process.
3408 If the @option{-l} option is supplied, the shell places a dash at the
3409 beginning of the zeroth argument passed to @var{command}.
3410 This is what the @code{login} program does.
3411 The @option{-c} option causes @var{command} to be executed with an empty
3413 If @option{-a} is supplied, the shell passes @var{name} as the zeroth
3414 argument to @var{command}.
3416 cannot be executed for some reason, a non-interactive shell exits,
3417 unless the @code{execfail} shell option
3418 is enabled. In that case, it returns failure.
3419 An interactive shell returns failure if the file cannot be executed.
3420 If no @var{command} is specified, redirections may be used to affect
3421 the current shell environment. If there are no redirection errors, the
3422 return status is zero; otherwise the return status is non-zero.
3430 Exit the shell, returning a status of @var{n} to the shell's parent.
3431 If @var{n} is omitted, the exit status is that of the last command executed.
3432 Any trap on @code{EXIT} is executed before the shell terminates.
3437 export [-fn] [-p] [@var{name}[=@var{value}]]
3440 Mark each @var{name} to be passed to child processes
3441 in the environment. If the @option{-f} option is supplied, the @var{name}s
3442 refer to shell functions; otherwise the names refer to shell variables.
3443 The @option{-n} option means to no longer mark each @var{name} for export.
3444 If no @var{names} are supplied, or if the @option{-p} option is given, a
3445 list of names of all exported variables is displayed.
3446 The @option{-p} option displays output in a form that may be reused as input.
3447 If a variable name is followed by =@var{value}, the value of
3448 the variable is set to @var{value}.
3450 The return status is zero unless an invalid option is supplied, one of
3451 the names is not a valid shell variable name, or @option{-f} is supplied
3452 with a name that is not a shell function.
3457 getopts @var{optstring} @var{name} [@var{args}]
3460 @code{getopts} is used by shell scripts to parse positional parameters.
3461 @var{optstring} contains the option characters to be recognized; if a
3462 character is followed by a colon, the option is expected to have an
3463 argument, which should be separated from it by whitespace.
3464 The colon (@samp{:}) and question mark (@samp{?}) may not be
3465 used as option characters.
3466 Each time it is invoked, @code{getopts}
3467 places the next option in the shell variable @var{name}, initializing
3468 @var{name} if it does not exist,
3469 and the index of the next argument to be processed into the
3470 variable @env{OPTIND}.
3471 @env{OPTIND} is initialized to 1 each time the shell or a shell script
3473 When an option requires an argument,
3474 @code{getopts} places that argument into the variable @env{OPTARG}.
3475 The shell does not reset @env{OPTIND} automatically; it must be manually
3476 reset between multiple calls to @code{getopts} within the same shell
3477 invocation if a new set of parameters is to be used.
3479 When the end of options is encountered, @code{getopts} exits with a
3480 return value greater than zero.
3481 @env{OPTIND} is set to the index of the first non-option argument,
3482 and @var{name} is set to @samp{?}.
3485 normally parses the positional parameters, but if more arguments are
3486 given in @var{args}, @code{getopts} parses those instead.
3488 @code{getopts} can report errors in two ways. If the first character of
3489 @var{optstring} is a colon, @var{silent}
3490 error reporting is used. In normal operation, diagnostic messages
3491 are printed when invalid options or missing option arguments are
3493 If the variable @env{OPTERR}
3494 is set to 0, no error messages will be displayed, even if the first
3495 character of @code{optstring} is not a colon.
3497 If an invalid option is seen,
3498 @code{getopts} places @samp{?} into @var{name} and, if not silent,
3499 prints an error message and unsets @env{OPTARG}.
3500 If @code{getopts} is silent, the option character found is placed in
3501 @env{OPTARG} and no diagnostic message is printed.
3503 If a required argument is not found, and @code{getopts}
3504 is not silent, a question mark (@samp{?}) is placed in @var{name},
3505 @code{OPTARG} is unset, and a diagnostic message is printed.
3506 If @code{getopts} is silent, then a colon (@samp{:}) is placed in
3507 @var{name} and @env{OPTARG} is set to the option character found.
3512 hash [-r] [-p @var{filename}] [-dt] [@var{name}]
3515 Each time @code{hash} is invoked, it remembers the full pathnames of the
3516 commands specified as @var{name} arguments,
3517 so they need not be searched for on subsequent invocations.
3518 The commands are found by searching through the directories listed in
3520 Any previously-remembered pathname is discarded.
3521 The @option{-p} option inhibits the path search, and @var{filename} is
3522 used as the location of @var{name}.
3523 The @option{-r} option causes the shell to forget all remembered locations.
3524 The @option{-d} option causes the shell to forget the remembered location
3526 If the @option{-t} option is supplied, the full pathname to which each
3527 @var{name} corresponds is printed. If multiple @var{name} arguments are
3528 supplied with @option{-t} the @var{name} is printed before the hashed
3530 The @option{-l} option causes output to be displayed in a format
3531 that may be reused as input.
3532 If no arguments are given, or if only @option{-l} is supplied,
3533 information about remembered commands is printed.
3534 The return status is zero unless a @var{name} is not found or an invalid
3543 Print the absolute pathname of the current working directory.
3544 If the @option{-P} option is supplied, the pathname printed will not
3545 contain symbolic links.
3546 If the @option{-L} option is supplied, the pathname printed may contain
3548 The return status is zero unless an error is encountered while
3549 determining the name of the current directory or an invalid option
3555 readonly [-aAf] [-p] [@var{name}[=@var{value}]] @dots{}
3558 Mark each @var{name} as readonly.
3559 The values of these names may not be changed by subsequent assignment.
3560 If the @option{-f} option is supplied, each @var{name} refers to a shell
3562 The @option{-a} option means each @var{name} refers to an indexed
3563 array variable; the @option{-A} option means each @var{name} refers
3564 to an associative array variable.
3565 If both options are supplied, @option{-A} takes precedence.
3566 If no @var{name} arguments are given, or if the @option{-p}
3567 option is supplied, a list of all readonly names is printed.
3568 The other options may be used to restrict the output to a subset of
3569 the set of readonly names.
3570 The @option{-p} option causes output to be displayed in a format that
3571 may be reused as input.
3572 If a variable name is followed by =@var{value}, the value of
3573 the variable is set to @var{value}.
3574 The return status is zero unless an invalid option is supplied, one of
3575 the @var{name} arguments is not a valid shell variable or function name,
3576 or the @option{-f} option is supplied with a name that is not a shell function.
3584 Cause a shell function to stop executing and return the value @var{n}
3586 If @var{n} is not supplied, the return value is the exit status of the
3587 last command executed in the function.
3588 If @code{return} is executed by a trap handler, the last command used to
3589 determine the status is the last command executed before the trap handler.
3590 if @code{return} is executed during a @code{DEBUG} trap, the last command
3591 used to determine the status is the last command executed by the trap
3592 handler before @code{return} was invoked.
3593 @code{return} may also be used to terminate execution of a script
3594 being executed with the @code{.} (@code{source}) builtin,
3595 returning either @var{n} or
3596 the exit status of the last command executed within the script as the exit
3597 status of the script.
3598 If @var{n} is supplied, the return value is its least significant
3600 Any command associated with the @code{RETURN} trap is executed
3601 before execution resumes after the function or script.
3602 The return status is non-zero if @code{return} is supplied a non-numeric
3603 argument or is used outside a function
3604 and not during the execution of a script by @code{.} or @code{source}.
3612 Shift the positional parameters to the left by @var{n}.
3613 The positional parameters from @var{n}+1 @dots{} @code{$#} are
3614 renamed to @code{$1} @dots{} @code{$#}-@var{n}.
3615 Parameters represented by the numbers @code{$#} to @code{$#}-@var{n}+1
3617 @var{n} must be a non-negative number less than or equal to @code{$#}.
3618 If @var{n} is zero or greater than @code{$#}, the positional parameters
3620 If @var{n} is not supplied, it is assumed to be 1.
3621 The return status is zero unless @var{n} is greater than @code{$#} or
3622 less than zero, non-zero otherwise.
3632 Evaluate a conditional expression @var{expr} and return a status of 0
3633 (true) or 1 (false).
3634 Each operator and operand must be a separate argument.
3635 Expressions are composed of the primaries described below in
3636 @ref{Bash Conditional Expressions}.
3637 @code{test} does not accept any options, nor does it accept and ignore
3638 an argument of @option{--} as signifying the end of options.
3640 When the @code{[} form is used, the last argument to the command must
3643 Expressions may be combined using the following operators, listed in
3644 decreasing order of precedence.
3645 The evaluation depends on the number of arguments; see below.
3646 Operator precedence is used when there are five or more arguments.
3650 True if @var{expr} is false.
3652 @item ( @var{expr} )
3653 Returns the value of @var{expr}.
3654 This may be used to override the normal precedence of operators.
3656 @item @var{expr1} -a @var{expr2}
3657 True if both @var{expr1} and @var{expr2} are true.
3659 @item @var{expr1} -o @var{expr2}
3660 True if either @var{expr1} or @var{expr2} is true.
3663 The @code{test} and @code{[} builtins evaluate conditional
3664 expressions using a set of rules based on the number of arguments.
3668 The expression is false.
3671 The expression is true if and only if the argument is not null.
3674 If the first argument is @samp{!}, the expression is true if and
3675 only if the second argument is null.
3676 If the first argument is one of the unary conditional operators
3677 (@pxref{Bash Conditional Expressions}), the expression
3678 is true if the unary test is true.
3679 If the first argument is not a valid unary operator, the expression is
3683 The following conditions are applied in the order listed.
3684 If the second argument is one of the binary conditional
3685 operators (@pxref{Bash Conditional Expressions}), the
3686 result of the expression is the result of the binary test using the
3687 first and third arguments as operands.
3688 The @samp{-a} and @samp{-o} operators are considered binary operators
3689 when there are three arguments.
3690 If the first argument is @samp{!}, the value is the negation of
3691 the two-argument test using the second and third arguments.
3692 If the first argument is exactly @samp{(} and the third argument is
3693 exactly @samp{)}, the result is the one-argument test of the second
3695 Otherwise, the expression is false.
3698 If the first argument is @samp{!}, the result is the negation of
3699 the three-argument expression composed of the remaining arguments.
3700 Otherwise, the expression is parsed and evaluated according to
3701 precedence using the rules listed above.
3703 @item 5 or more arguments
3704 The expression is parsed and evaluated according to precedence
3705 using the rules listed above.
3708 When used with @code{test} or @samp{[}, the @samp{<} and @samp{>}
3709 operators sort lexicographically using ASCII ordering.
3717 Print out the user and system times used by the shell and its children.
3718 The return status is zero.
3723 trap [-lp] [@var{arg}] [@var{sigspec} @dots{}]
3726 The commands in @var{arg} are to be read and executed when the
3727 shell receives signal @var{sigspec}. If @var{arg} is absent (and
3728 there is a single @var{sigspec}) or
3729 equal to @samp{-}, each specified signal's disposition is reset
3730 to the value it had when the shell was started.
3731 If @var{arg} is the null string, then the signal specified by
3732 each @var{sigspec} is ignored by the shell and commands it invokes.
3733 If @var{arg} is not present and @option{-p} has been supplied,
3734 the shell displays the trap commands associated with each @var{sigspec}.
3735 If no arguments are supplied, or
3736 only @option{-p} is given, @code{trap} prints the list of commands
3737 associated with each signal number in a form that may be reused as
3739 The @option{-l} option causes the shell to print a list of signal names
3740 and their corresponding numbers.
3741 Each @var{sigspec} is either a signal name or a signal number.
3742 Signal names are case insensitive and the @code{SIG} prefix is optional.
3745 is @code{0} or @code{EXIT}, @var{arg} is executed when the shell exits.
3746 If a @var{sigspec} is @code{DEBUG}, the command @var{arg} is executed
3747 before every simple command, @code{for} command, @code{case} command,
3748 @code{select} command, every arithmetic @code{for} command, and before
3749 the first command executes in a shell function.
3750 Refer to the description of the @code{extdebug} option to the
3751 @code{shopt} builtin (@pxref{The Shopt Builtin}) for details of its
3752 effect on the @code{DEBUG} trap.
3753 If a @var{sigspec} is @code{RETURN}, the command @var{arg} is executed
3754 each time a shell function or a script executed with the @code{.} or
3755 @code{source} builtins finishes executing.
3757 If a @var{sigspec} is @code{ERR}, the command @var{arg}
3758 is executed whenever
3759 a pipeline (which may consist of a single simple
3760 command), a list, or a compound command returns a
3761 non-zero exit status,
3762 subject to the following conditions.
3763 The @code{ERR} trap is not executed if the failed command is part of the
3764 command list immediately following an @code{until} or @code{while} keyword,
3765 part of the test following the @code{if} or @code{elif} reserved words,
3766 part of a command executed in a @code{&&} or @code{||} list
3767 except the command following the final @code{&&} or @code{||},
3768 any command in a pipeline but the last,
3769 or if the command's return
3770 status is being inverted using @code{!}.
3771 These are the same conditions obeyed by the @code{errexit} (@option{-e})
3774 Signals ignored upon entry to the shell cannot be trapped or reset.
3775 Trapped signals that are not being ignored are reset to their original
3776 values in a subshell or subshell environment when one is created.
3778 The return status is zero unless a @var{sigspec} does not specify a
3784 umask [-p] [-S] [@var{mode}]
3787 Set the shell process's file creation mask to @var{mode}. If
3788 @var{mode} begins with a digit, it is interpreted as an octal number;
3789 if not, it is interpreted as a symbolic mode mask similar
3790 to that accepted by the @code{chmod} command. If @var{mode} is
3791 omitted, the current value of the mask is printed. If the @option{-S}
3792 option is supplied without a @var{mode} argument, the mask is printed
3793 in a symbolic format.
3794 If the @option{-p} option is supplied, and @var{mode}
3795 is omitted, the output is in a form that may be reused as input.
3796 The return status is zero if the mode is successfully changed or if
3797 no @var{mode} argument is supplied, and non-zero otherwise.
3799 Note that when the mode is interpreted as an octal number, each number
3800 of the umask is subtracted from @code{7}. Thus, a umask of @code{022}
3801 results in permissions of @code{755}.
3806 unset [-fnv] [@var{name}]
3809 Remove each variable or function @var{name}.
3810 If the @option{-v} option is given, each
3811 @var{name} refers to a shell variable and that variable is removed.
3812 If the @option{-f} option is given, the @var{name}s refer to shell
3813 functions, and the function definition is removed.
3814 If the @option{-n} option is supplied, and @var{name} is a variable with
3815 the @var{nameref} attribute, @var{name} will be unset rather than the
3816 variable it references.
3817 @option{-n} has no effect if the @option{-f} option is supplied.
3818 If no options are supplied, each @var{name} refers to a variable; if
3819 there is no variable by that name, any function with that name is
3821 Readonly variables and functions may not be unset.
3822 The return status is zero unless a @var{name} is readonly.
3826 @section Bash Builtin Commands
3828 This section describes builtin commands which are unique to
3829 or have been extended in Bash.
3830 Some of these commands are specified in the @sc{posix} standard.
3837 alias [-p] [@var{name}[=@var{value}] @dots{}]
3840 Without arguments or with the @option{-p} option, @code{alias} prints
3841 the list of aliases on the standard output in a form that allows
3842 them to be reused as input.
3843 If arguments are supplied, an alias is defined for each @var{name}
3844 whose @var{value} is given. If no @var{value} is given, the name
3845 and value of the alias is printed.
3846 Aliases are described in @ref{Aliases}.
3851 bind [-m @var{keymap}] [-lpsvPSVX]
3852 bind [-m @var{keymap}] [-q @var{function}] [-u @var{function}] [-r @var{keyseq}]
3853 bind [-m @var{keymap}] -f @var{filename}
3854 bind [-m @var{keymap}] -x @var{keyseq:shell-command}
3855 bind [-m @var{keymap}] @var{keyseq:function-name}
3856 bind [-m @var{keymap}] @var{keyseq:readline-command}
3859 Display current Readline (@pxref{Command Line Editing})
3860 key and function bindings,
3861 bind a key sequence to a Readline function or macro,
3862 or set a Readline variable.
3863 Each non-option argument is a command as it would appear in a
3864 Readline initialization file (@pxref{Readline Init File}),
3865 but each binding or command must be passed as a separate argument; e.g.,
3866 @samp{"\C-x\C-r":re-read-init-file}.
3868 Options, if supplied, have the following meanings:
3871 @item -m @var{keymap}
3872 Use @var{keymap} as the keymap to be affected by
3873 the subsequent bindings. Acceptable @var{keymap}
3876 @code{emacs-standard},
3881 @code{vi-command}, and
3883 @code{vi} is equivalent to @code{vi-command} (@code{vi-move} is also a
3884 synonym); @code{emacs} is equivalent to @code{emacs-standard}.
3887 List the names of all Readline functions.
3890 Display Readline function names and bindings in such a way that they
3891 can be used as input or in a Readline initialization file.
3894 List current Readline function names and bindings.
3897 Display Readline variable names and values in such a way that they
3898 can be used as input or in a Readline initialization file.
3901 List current Readline variable names and values.
3904 Display Readline key sequences bound to macros and the strings they output
3905 in such a way that they can be used as input or in a Readline
3906 initialization file.
3909 Display Readline key sequences bound to macros and the strings they output.
3911 @item -f @var{filename}
3912 Read key bindings from @var{filename}.
3914 @item -q @var{function}
3915 Query about which keys invoke the named @var{function}.
3917 @item -u @var{function}
3918 Unbind all keys bound to the named @var{function}.
3920 @item -r @var{keyseq}
3921 Remove any current binding for @var{keyseq}.
3923 @item -x @var{keyseq:shell-command}
3924 Cause @var{shell-command} to be executed whenever @var{keyseq} is
3926 When @var{shell-command} is executed, the shell sets the
3927 @code{READLINE_LINE} variable to the contents of the Readline line
3928 buffer and the @code{READLINE_POINT} variable to the current location
3929 of the insertion point.
3930 If the executed command changes the value of @code{READLINE_LINE} or
3931 @code{READLINE_POINT}, those new values will be reflected in the
3935 List all key sequences bound to shell commands and the associated commands
3936 in a format that can be reused as input.
3940 The return status is zero unless an invalid option is supplied or an
3946 builtin [@var{shell-builtin} [@var{args}]]
3949 Run a shell builtin, passing it @var{args}, and return its exit status.
3950 This is useful when defining a shell function with the same
3951 name as a shell builtin, retaining the functionality of the builtin within
3953 The return status is non-zero if @var{shell-builtin} is not a shell
3962 Returns the context of any active subroutine call (a shell function or
3963 a script executed with the @code{.} or @code{source} builtins).
3965 Without @var{expr}, @code{caller} displays the line number and source
3966 filename of the current subroutine call.
3967 If a non-negative integer is supplied as @var{expr}, @code{caller}
3968 displays the line number, subroutine name, and source file corresponding
3969 to that position in the current execution call stack. This extra
3970 information may be used, for example, to print a stack trace. The
3971 current frame is frame 0.
3973 The return value is 0 unless the shell is not executing a subroutine
3974 call or @var{expr} does not correspond to a valid position in the
3980 command [-pVv] @var{command} [@var{arguments} @dots{}]
3983 Runs @var{command} with @var{arguments} ignoring any shell function
3984 named @var{command}.
3985 Only shell builtin commands or commands found by searching the
3986 @env{PATH} are executed.
3987 If there is a shell function named @code{ls}, running @samp{command ls}
3988 within the function will execute the external command @code{ls}
3989 instead of calling the function recursively.
3990 The @option{-p} option means to use a default value for @env{PATH}
3991 that is guaranteed to find all of the standard utilities.
3992 The return status in this case is 127 if @var{command} cannot be
3993 found or an error occurred, and the exit status of @var{command}
3996 If either the @option{-V} or @option{-v} option is supplied, a
3997 description of @var{command} is printed. The @option{-v} option
3998 causes a single word indicating the command or file name used to
3999 invoke @var{command} to be displayed; the @option{-V} option produces
4000 a more verbose description. In this case, the return status is
4001 zero if @var{command} is found, and non-zero if not.
4006 declare [-aAfFgilnrtux] [-p] [@var{name}[=@var{value}] @dots{}]
4009 Declare variables and give them attributes. If no @var{name}s
4010 are given, then display the values of variables instead.
4012 The @option{-p} option will display the attributes and values of each
4014 When @option{-p} is used with @var{name} arguments, additional options,
4015 other than @option{-f} and @option{-F}, are ignored.
4017 When @option{-p} is supplied without @var{name} arguments, @code{declare}
4018 will display the attributes and values of all variables having the
4019 attributes specified by the additional options.
4020 If no other options are supplied with @option{-p}, @code{declare} will
4021 display the attributes and values of all shell variables. The @option{-f}
4022 option will restrict the display to shell functions.
4024 The @option{-F} option inhibits the display of function definitions;
4025 only the function name and attributes are printed.
4026 If the @code{extdebug} shell option is enabled using @code{shopt}
4027 (@pxref{The Shopt Builtin}), the source file name and line number where
4028 each @var{name} is defined are displayed as well.
4029 @option{-F} implies @option{-f}.
4031 The @option{-g} option forces variables to be created or modified at
4032 the global scope, even when @code{declare} is executed in a shell function.
4033 It is ignored in all other cases.
4035 The following options can be used to restrict output to variables with
4036 the specified attributes or to give variables attributes:
4040 Each @var{name} is an indexed array variable (@pxref{Arrays}).
4043 Each @var{name} is an associative array variable (@pxref{Arrays}).
4046 Use function names only.
4049 The variable is to be treated as
4050 an integer; arithmetic evaluation (@pxref{Shell Arithmetic}) is
4051 performed when the variable is assigned a value.
4054 When the variable is assigned a value, all upper-case characters are
4055 converted to lower-case.
4056 The upper-case attribute is disabled.
4059 Give each @var{name} the @var{nameref} attribute, making
4060 it a name reference to another variable.
4061 That other variable is defined by the value of @var{name}.
4062 All references, assignments, and attribute modifications
4063 to @var{name}, except for those using or changing the
4064 @option{-n} attribute itself, are performed on the variable referenced by
4066 The nameref attribute cannot be applied to array variables.
4069 Make @var{name}s readonly. These names cannot then be assigned values
4070 by subsequent assignment statements or unset.
4073 Give each @var{name} the @code{trace} attribute.
4074 Traced functions inherit the @code{DEBUG} and @code{RETURN} traps from
4076 The trace attribute has no special meaning for variables.
4079 When the variable is assigned a value, all lower-case characters are
4080 converted to upper-case.
4081 The lower-case attribute is disabled.
4084 Mark each @var{name} for export to subsequent commands via
4088 Using @samp{+} instead of @samp{-} turns off the attribute instead,
4089 with the exceptions that @samp{+a}
4090 may not be used to destroy an array variable and @samp{+r} will not
4091 remove the readonly attribute.
4092 When used in a function, @code{declare} makes each @var{name} local,
4093 as with the @code{local} command, unless the @option{-g} option is used.
4094 If a variable name is followed by =@var{value}, the value of the variable
4095 is set to @var{value}.
4097 When using @option{-a} or @option{-A} and the compound assignment syntax to
4098 create array variables, additional attributes do not take effect until
4099 subsequent assignments.
4101 The return status is zero unless an invalid option is encountered,
4102 an attempt is made to define a function using @samp{-f foo=bar},
4103 an attempt is made to assign a value to a readonly variable,
4104 an attempt is made to assign a value to an array variable without
4105 using the compound assignment syntax (@pxref{Arrays}),
4106 one of the @var{names} is not a valid shell variable name,
4107 an attempt is made to turn off readonly status for a readonly variable,
4108 an attempt is made to turn off array status for an array variable,
4109 or an attempt is made to display a non-existent function with @option{-f}.
4114 echo [-neE] [@var{arg} @dots{}]
4117 Output the @var{arg}s, separated by spaces, terminated with a
4119 The return status is 0 unless a write error occurs.
4120 If @option{-n} is specified, the trailing newline is suppressed.
4121 If the @option{-e} option is given, interpretation of the following
4122 backslash-escaped characters is enabled.
4123 The @option{-E} option disables the interpretation of these escape characters,
4124 even on systems where they are interpreted by default.
4125 The @code{xpg_echo} shell option may be used to
4126 dynamically determine whether or not @code{echo} expands these
4127 escape characters by default.
4128 @code{echo} does not interpret @option{--} to mean the end of options.
4130 @code{echo} interprets the following escape sequences:
4137 suppress further output
4154 the eight-bit character whose value is the octal value @var{nnn}
4155 (zero to three octal digits)
4157 the eight-bit character whose value is the hexadecimal value @var{HH}
4158 (one or two hex digits)
4160 the Unicode (ISO/IEC 10646) character whose value is the hexadecimal value
4161 @var{HHHH} (one to four hex digits)
4162 @item \U@var{HHHHHHHH}
4163 the Unicode (ISO/IEC 10646) character whose value is the hexadecimal value
4164 @var{HHHHHHHH} (one to eight hex digits)
4170 enable [-a] [-dnps] [-f @var{filename}] [@var{name} @dots{}]
4173 Enable and disable builtin shell commands.
4174 Disabling a builtin allows a disk command which has the same name
4175 as a shell builtin to be executed without specifying a full pathname,
4176 even though the shell normally searches for builtins before disk commands.
4177 If @option{-n} is used, the @var{name}s become disabled. Otherwise
4178 @var{name}s are enabled. For example, to use the @code{test} binary
4179 found via @env{$PATH} instead of the shell builtin version, type
4180 @samp{enable -n test}.
4182 If the @option{-p} option is supplied, or no @var{name} arguments appear,
4183 a list of shell builtins is printed. With no other arguments, the list
4184 consists of all enabled shell builtins.
4185 The @option{-a} option means to list
4186 each builtin with an indication of whether or not it is enabled.
4188 The @option{-f} option means to load the new builtin command @var{name}
4189 from shared object @var{filename}, on systems that support dynamic loading.
4190 The @option{-d} option will delete a builtin loaded with @option{-f}.
4192 If there are no options, a list of the shell builtins is displayed.
4193 The @option{-s} option restricts @code{enable} to the @sc{posix} special
4194 builtins. If @option{-s} is used with @option{-f}, the new builtin becomes
4195 a special builtin (@pxref{Special Builtins}).
4197 The return status is zero unless a @var{name} is not a shell builtin
4198 or there is an error loading a new builtin from a shared object.
4203 help [-dms] [@var{pattern}]
4206 Display helpful information about builtin commands.
4207 If @var{pattern} is specified, @code{help} gives detailed help
4208 on all commands matching @var{pattern}, otherwise a list of
4209 the builtins is printed.
4211 Options, if supplied, have the following meanings:
4215 Display a short description of each @var{pattern}
4217 Display the description of each @var{pattern} in a manpage-like format
4219 Display only a short usage synopsis for each @var{pattern}
4222 The return status is zero unless no command matches @var{pattern}.
4227 let @var{expression} [@var{expression} @dots{}]
4230 The @code{let} builtin allows arithmetic to be performed on shell
4231 variables. Each @var{expression} is evaluated according to the
4232 rules given below in @ref{Shell Arithmetic}. If the
4233 last @var{expression} evaluates to 0, @code{let} returns 1;
4234 otherwise 0 is returned.
4239 local [@var{option}] @var{name}[=@var{value}] @dots{}
4242 For each argument, a local variable named @var{name} is created,
4243 and assigned @var{value}.
4244 The @var{option} can be any of the options accepted by @code{declare}.
4245 @code{local} can only be used within a function; it makes the variable
4246 @var{name} have a visible scope restricted to that function and its
4248 If @var{name} is @samp{-}, the set of shell options is made local to the
4249 function in which @code{local} is invoked: shell options changed using
4250 the @code{set} builtin inside the function are restored to their original
4251 values when the function returns.
4252 The return status is zero unless @code{local} is used outside
4253 a function, an invalid @var{name} is supplied, or @var{name} is a
4262 Exit a login shell, returning a status of @var{n} to the shell's
4268 mapfile [-d @var{delim}] [-n @var{count}] [-O @var{origin}] [-s @var{count}] [-t] [-u @var{fd}]
4269 [-C @var{callback}] [-c @var{quantum}] [@var{array}]
4272 Read lines from the standard input into the indexed array variable @var{array},
4273 or from file descriptor @var{fd}
4274 if the @option{-u} option is supplied.
4275 The variable @code{MAPFILE} is the default @var{array}.
4276 Options, if supplied, have the following meanings:
4281 The first character of @var{delim} is used to terminate each input line,
4282 rather than newline.
4284 Copy at most @var{count} lines. If @var{count} is 0, all lines are copied.
4286 Begin assigning to @var{array} at index @var{origin}.
4287 The default index is 0.
4289 Discard the first @var{count} lines read.
4291 Remove a trailing @var{delim} (default newline) from each line read.
4293 Read lines from file descriptor @var{fd} instead of the standard input.
4295 Evaluate @var{callback} each time @var{quantum}P lines are read.
4296 The @option{-c} option specifies @var{quantum}.
4298 Specify the number of lines read between each call to @var{callback}.
4301 If @option{-C} is specified without @option{-c},
4302 the default quantum is 5000.
4303 When @var{callback} is evaluated, it is supplied the index of the next
4304 array element to be assigned and the line to be assigned to that element
4305 as additional arguments.
4306 @var{callback} is evaluated after the line is read but before the
4307 array element is assigned.
4309 If not supplied with an explicit origin, @code{mapfile} will clear @var{array}
4310 before assigning to it.
4312 @code{mapfile} returns successfully unless an invalid option or option
4313 argument is supplied, @var{array} is invalid or unassignable, or @var{array}
4314 is not an indexed array.
4319 printf [-v @var{var}] @var{format} [@var{arguments}]
4322 Write the formatted @var{arguments} to the standard output under the
4323 control of the @var{format}.
4324 The @option{-v} option causes the output to be assigned to the variable
4325 @var{var} rather than being printed to the standard output.
4327 The @var{format} is a character string which contains three types of objects:
4328 plain characters, which are simply copied to standard output, character
4329 escape sequences, which are converted and copied to the standard output, and
4330 format specifications, each of which causes printing of the next successive
4332 In addition to the standard @code{printf(1)} formats, @code{printf}
4333 interprets the following extensions:
4337 Causes @code{printf} to expand backslash escape sequences in the
4338 corresponding @var{argument} in the same way as @code{echo -e}
4339 (@pxref{Bash Builtins}).
4341 Causes @code{printf} to output the
4342 corresponding @var{argument} in a format that can be reused as shell input.
4343 @item %(@var{datefmt})T
4344 Causes @code{printf} to output the date-time string resulting from using
4345 @var{datefmt} as a format string for @code{strftime}(3).
4346 The corresponding @var{argument} is an integer representing the number of
4347 seconds since the epoch.
4348 Two special argument values may be used: -1 represents the current
4349 time, and -2 represents the time the shell was invoked.
4350 If no argument is specified, conversion behaves as if -1 had been given.
4351 This is an exception to the usual @code{printf} behavior.
4355 Arguments to non-string format specifiers are treated as C language constants,
4356 except that a leading plus or minus sign is allowed, and if the leading
4357 character is a single or double quote, the value is the ASCII value of
4358 the following character.
4360 The @var{format} is reused as necessary to consume all of the @var{arguments}.
4361 If the @var{format} requires more @var{arguments} than are supplied, the
4362 extra format specifications behave as if a zero value or null string, as
4363 appropriate, had been supplied. The return value is zero on success,
4364 non-zero on failure.
4369 read [-ers] [-a @var{aname}] [-d @var{delim}] [-i @var{text}] [-n @var{nchars}]
4370 [-N @var{nchars}] [-p @var{prompt}] [-t @var{timeout}] [-u @var{fd}] [@var{name} @dots{}]
4373 One line is read from the standard input, or from the file descriptor
4374 @var{fd} supplied as an argument to the @option{-u} option,
4375 split into words as described above in @ref{Word Splitting},
4377 is assigned to the first @var{name}, the second word to the second @var{name},
4379 If there are more words than names,
4380 the remaining words and their intervening delimiters are assigned
4381 to the last @var{name}.
4382 If there are fewer words read from the input stream than names,
4383 the remaining names are assigned empty values.
4384 The characters in the value of the @env{IFS} variable
4385 are used to split the line into words using the same rules the shell
4386 uses for expansion (described above in @ref{Word Splitting}).
4387 The backslash character @samp{\} may be used to remove any special
4388 meaning for the next character read and for line continuation.
4389 If no names are supplied, the line read is assigned to the
4390 variable @env{REPLY}.
4391 The exit status is zero, unless end-of-file is encountered, @code{read}
4392 times out (in which case the status is greater than 128),
4393 a variable assignment error (such as assigning to a readonly variable) occurs,
4394 or an invalid file descriptor is supplied as the argument to @option{-u}.
4396 Options, if supplied, have the following meanings:
4399 @item -a @var{aname}
4400 The words are assigned to sequential indices of the array variable
4401 @var{aname}, starting at 0.
4402 All elements are removed from @var{aname} before the assignment.
4403 Other @var{name} arguments are ignored.
4405 @item -d @var{delim}
4406 The first character of @var{delim} is used to terminate the input line,
4407 rather than newline.
4410 Readline (@pxref{Command Line Editing}) is used to obtain the line.
4411 Readline uses the current (or default, if line editing was not previously
4412 active) editing settings.
4415 If Readline is being used to read the line, @var{text} is placed into
4416 the editing buffer before editing begins.
4418 @item -n @var{nchars}
4419 @code{read} returns after reading @var{nchars} characters rather than
4420 waiting for a complete line of input, but honors a delimiter if fewer
4421 than @var{nchars} characters are read before the delimiter.
4423 @item -N @var{nchars}
4424 @code{read} returns after reading exactly @var{nchars} characters rather
4425 than waiting for a complete line of input, unless EOF is encountered or
4426 @code{read} times out.
4427 Delimiter characters encountered in the input are
4428 not treated specially and do not cause @code{read} to return until
4429 @var{nchars} characters are read.
4430 The result is not split on the characters in @code{IFS}; the intent is
4431 that the variable is assigned exactly the characters read
4432 (with the exception of backslash; see the @option{-r} option below).
4434 @item -p @var{prompt}
4435 Display @var{prompt}, without a trailing newline, before attempting
4437 The prompt is displayed only if input is coming from a terminal.
4440 If this option is given, backslash does not act as an escape character.
4441 The backslash is considered to be part of the line.
4442 In particular, a backslash-newline pair may not be used as a line
4446 Silent mode. If input is coming from a terminal, characters are
4449 @item -t @var{timeout}
4450 Cause @code{read} to time out and return failure if a complete line of
4451 input (or a specified number of characters)
4452 is not read within @var{timeout} seconds.
4453 @var{timeout} may be a decimal number with a fractional portion following
4455 This option is only effective if @code{read} is reading input from a
4456 terminal, pipe, or other special file; it has no effect when reading
4458 If @code{read} times out, @code{read} saves any partial input read into
4459 the specified variable @var{name}.
4460 If @var{timeout} is 0, @code{read} returns immediately, without trying to
4461 read and data. The exit status is 0 if input is available on
4462 the specified file descriptor, non-zero otherwise.
4463 The exit status is greater than 128 if the timeout is exceeded.
4466 Read input from file descriptor @var{fd}.
4472 readarray [-d @var{delim}] [-n @var{count}] [-O @var{origin}] [-s @var{count}] [-t] [-u @var{fd}]
4473 [-C @var{callback}] [-c @var{quantum}] [@var{array}]
4476 Read lines from the standard input into the indexed array variable @var{array},
4477 or from file descriptor @var{fd}
4478 if the @option{-u} option is supplied.
4480 A synonym for @code{mapfile}.
4485 source @var{filename}
4488 A synonym for @code{.} (@pxref{Bourne Shell Builtins}).
4493 type [-afptP] [@var{name} @dots{}]
4496 For each @var{name}, indicate how it would be interpreted if used as a
4499 If the @option{-t} option is used, @code{type} prints a single word
4500 which is one of @samp{alias}, @samp{function}, @samp{builtin},
4501 @samp{file} or @samp{keyword},
4502 if @var{name} is an alias, shell function, shell builtin,
4503 disk file, or shell reserved word, respectively.
4504 If the @var{name} is not found, then nothing is printed, and
4505 @code{type} returns a failure status.
4507 If the @option{-p} option is used, @code{type} either returns the name
4508 of the disk file that would be executed, or nothing if @option{-t}
4509 would not return @samp{file}.
4511 The @option{-P} option forces a path search for each @var{name}, even if
4512 @option{-t} would not return @samp{file}.
4514 If a command is hashed, @option{-p} and @option{-P} print the hashed value,
4515 which is not necessarily the file that appears first in @code{$PATH}.
4517 If the @option{-a} option is used, @code{type} returns all of the places
4518 that contain an executable named @var{file}.
4519 This includes aliases and functions, if and only if the @option{-p} option
4522 If the @option{-f} option is used, @code{type} does not attempt to find
4523 shell functions, as with the @code{command} builtin.
4525 The return status is zero if all of the @var{names} are found, non-zero
4526 if any are not found.
4531 typeset [-afFgrxilnrtux] [-p] [@var{name}[=@var{value}] @dots{}]
4534 The @code{typeset} command is supplied for compatibility with the Korn
4536 It is a synonym for the @code{declare} builtin command.
4541 ulimit [-HSabcdefiklmnpqrstuvxPT] [@var{limit}]
4544 @code{ulimit} provides control over the resources available to processes
4545 started by the shell, on systems that allow such control. If an
4546 option is given, it is interpreted as follows:
4550 Change and report the soft limit associated with a resource.
4553 Change and report the hard limit associated with a resource.
4556 All current limits are reported.
4559 The maximum socket buffer size.
4562 The maximum size of core files created.
4565 The maximum size of a process's data segment.
4568 The maximum scheduling priority ("nice").
4571 The maximum size of files written by the shell and its children.
4574 The maximum number of pending signals.
4577 The maximum number of kqueues that may be allocated.
4580 The maximum size that may be locked into memory.
4583 The maximum resident set size (many systems do not honor this limit).
4586 The maximum number of open file descriptors (most systems do not
4587 allow this value to be set).
4590 The pipe buffer size.
4593 The maximum number of bytes in POSIX message queues.
4596 The maximum real-time scheduling priority.
4599 The maximum stack size.
4602 The maximum amount of cpu time in seconds.
4605 The maximum number of processes available to a single user.
4608 The maximum amount of virtual memory available to the shell, and, on
4609 some systems, to its children.
4612 The maximum number of file locks.
4615 The maximum number of pseudoterminals.
4618 The maximum number of threads.
4621 If @var{limit} is given, and the @option{-a} option is not used,
4622 @var{limit} is the new value of the specified resource.
4623 The special @var{limit} values @code{hard}, @code{soft}, and
4624 @code{unlimited} stand for the current hard limit, the current soft limit,
4625 and no limit, respectively.
4626 A hard limit cannot be increased by a non-root user once it is set;
4627 a soft limit may be increased up to the value of the hard limit.
4628 Otherwise, the current value of the soft limit for the specified resource
4629 is printed, unless the @option{-H} option is supplied.
4630 When setting new limits, if neither @option{-H} nor @option{-S} is supplied,
4631 both the hard and soft limits are set.
4632 If no option is given, then @option{-f} is assumed. Values are in 1024-byte
4633 increments, except for @option{-t}, which is in seconds; @option{-p},
4634 which is in units of 512-byte blocks;
4639 @option{-n} and @option{-u}, which are unscaled values;
4640 and, when in @sc{posix} Mode (@pxref{Bash POSIX Mode}),
4641 @option{-c} and @option{-f}, which are in 512-byte increments.
4643 The return status is zero unless an invalid option or argument is supplied,
4644 or an error occurs while setting a new limit.
4649 unalias [-a] [@var{name} @dots{} ]
4652 Remove each @var{name} from the list of aliases. If @option{-a} is
4653 supplied, all aliases are removed.
4654 Aliases are described in @ref{Aliases}.
4657 @node Modifying Shell Behavior
4658 @section Modifying Shell Behavior
4661 * The Set Builtin:: Change the values of shell attributes and
4662 positional parameters.
4663 * The Shopt Builtin:: Modify shell optional behavior.
4666 @node The Set Builtin
4667 @subsection The Set Builtin
4669 This builtin is so complicated that it deserves its own section. @code{set}
4670 allows you to change the values of shell options and set the positional
4671 parameters, or to display the names and values of shell variables.
4677 set [--abefhkmnptuvxBCEHPT] [-o @var{option-name}] [@var{argument} @dots{}]
4678 set [+abefhkmnptuvxBCEHPT] [+o @var{option-name}] [@var{argument} @dots{}]
4681 If no options or arguments are supplied, @code{set} displays the names
4682 and values of all shell variables and functions, sorted according to the
4683 current locale, in a format that may be reused as input
4684 for setting or resetting the currently-set variables.
4685 Read-only variables cannot be reset.
4686 In @sc{posix} mode, only shell variables are listed.
4688 When options are supplied, they set or unset shell attributes.
4689 Options, if specified, have the following meanings:
4693 Each variable or function that is created or modified is given the
4694 export attribute and marked for export to the environment of
4695 subsequent commands.
4698 Cause the status of terminated background jobs to be reported
4699 immediately, rather than before printing the next primary prompt.
4703 a pipeline (@pxref{Pipelines}), which may consist of a single simple command
4704 (@pxref{Simple Commands}),
4705 a list (@pxref{Lists}),
4706 or a compound command (@pxref{Compound Commands})
4707 returns a non-zero status.
4708 The shell does not exit if the command that fails is part of the
4709 command list immediately following a @code{while} or @code{until} keyword,
4710 part of the test in an @code{if} statement,
4711 part of any command executed in a @code{&&} or @code{||} list except
4712 the command following the final @code{&&} or @code{||},
4713 any command in a pipeline but the last,
4714 or if the command's return status is being inverted with @code{!}.
4715 If a compound command other than a subshell
4716 returns a non-zero status because a command failed
4717 while @option{-e} was being ignored, the shell does not exit.
4718 A trap on @code{ERR}, if set, is executed before the shell exits.
4720 This option applies to the shell environment and each subshell environment
4721 separately (@pxref{Command Execution Environment}), and may cause
4722 subshells to exit before executing all the commands in the subshell.
4724 If a compound command or shell function executes in a context where
4725 @option{-e} is being ignored,
4726 none of the commands executed within the compound command or function body
4727 will be affected by the @option{-e} setting, even if @option{-e} is set
4728 and a command returns a failure status.
4729 If a compound command or shell function sets @option{-e} while executing in
4730 a context where @option{-e} is ignored, that setting will not have any
4731 effect until the compound command or the command containing the function
4735 Disable filename expansion (globbing).
4738 Locate and remember (hash) commands as they are looked up for execution.
4739 This option is enabled by default.
4742 All arguments in the form of assignment statements are placed
4743 in the environment for a command, not just those that precede
4747 Job control is enabled (@pxref{Job Control}).
4748 All processes run in a separate process group.
4749 When a background job completes, the shell prints a line
4750 containing its exit status.
4753 Read commands but do not execute them.
4754 This may be used to check a script for syntax errors.
4755 This option is ignored by interactive shells.
4757 @item -o @var{option-name}
4759 Set the option corresponding to @var{option-name}:
4769 Use an @code{emacs}-style line editing interface (@pxref{Command Line Editing}).
4770 This also affects the editing interface used for @code{read -e}.
4788 Enable command history, as described in @ref{Bash History Facilities}.
4789 This option is on by default in interactive shells.
4792 An interactive shell will not exit upon reading EOF.
4825 If set, the return value of a pipeline is the value of the last
4826 (rightmost) command to exit with a non-zero status, or zero if all
4827 commands in the pipeline exit successfully.
4828 This option is disabled by default.
4831 Change the behavior of Bash where the default operation differs
4832 from the @sc{posix} standard to match the standard
4833 (@pxref{Bash POSIX Mode}).
4834 This is intended to make Bash behave as a strict superset of that
4844 Use a @code{vi}-style line editing interface.
4845 This also affects the editing interface used for @code{read -e}.
4852 Turn on privileged mode.
4853 In this mode, the @env{$BASH_ENV} and @env{$ENV} files are not
4854 processed, shell functions are not inherited from the environment,
4855 and the @env{SHELLOPTS}, @env{BASHOPTS}, @env{CDPATH} and @env{GLOBIGNORE}
4856 variables, if they appear in the environment, are ignored.
4857 If the shell is started with the effective user (group) id not equal to the
4858 real user (group) id, and the @option{-p} option is not supplied, these actions
4859 are taken and the effective user id is set to the real user id.
4860 If the @option{-p} option is supplied at startup, the effective user id is
4862 Turning this option off causes the effective user
4863 and group ids to be set to the real user and group ids.
4866 Exit after reading and executing one command.
4869 Treat unset variables and parameters other than the special parameters
4870 @samp{@@} or @samp{*} as an error when performing parameter expansion.
4871 An error message will be written to the standard error, and a non-interactive
4875 Print shell input lines as they are read.
4878 Print a trace of simple commands, @code{for} commands, @code{case}
4879 commands, @code{select} commands, and arithmetic @code{for} commands
4880 and their arguments or associated word lists after they are
4881 expanded and before they are executed. The value of the @env{PS4}
4882 variable is expanded and the resultant value is printed before
4883 the command and its expanded arguments.
4886 The shell will perform brace expansion (@pxref{Brace Expansion}).
4887 This option is on by default.
4890 Prevent output redirection using @samp{>}, @samp{>&}, and @samp{<>}
4891 from overwriting existing files.
4894 If set, any trap on @code{ERR} is inherited by shell functions, command
4895 substitutions, and commands executed in a subshell environment.
4896 The @code{ERR} trap is normally not inherited in such cases.
4899 Enable @samp{!} style history substitution (@pxref{History Interaction}).
4900 This option is on by default for interactive shells.
4903 If set, do not resolve symbolic links when performing commands such as
4904 @code{cd} which change the current directory. The physical directory
4905 is used instead. By default, Bash follows
4906 the logical chain of directories when performing commands
4907 which change the current directory.
4909 For example, if @file{/usr/sys} is a symbolic link to @file{/usr/local/sys}
4912 $ cd /usr/sys; echo $PWD
4919 If @code{set -P} is on, then:
4921 $ cd /usr/sys; echo $PWD
4928 If set, any trap on @code{DEBUG} and @code{RETURN} are inherited by
4929 shell functions, command substitutions, and commands executed
4930 in a subshell environment.
4931 The @code{DEBUG} and @code{RETURN} traps are normally not inherited
4935 If no arguments follow this option, then the positional parameters are
4936 unset. Otherwise, the positional parameters are set to the
4937 @var{arguments}, even if some of them begin with a @samp{-}.
4940 Signal the end of options, cause all remaining @var{arguments}
4941 to be assigned to the positional parameters. The @option{-x}
4942 and @option{-v} options are turned off.
4943 If there are no arguments, the positional parameters remain unchanged.
4946 Using @samp{+} rather than @samp{-} causes these options to be
4947 turned off. The options can also be used upon invocation of the
4948 shell. The current set of options may be found in @code{$-}.
4950 The remaining N @var{arguments} are positional parameters and are
4951 assigned, in order, to @code{$1}, @code{$2}, @dots{} @code{$N}.
4952 The special parameter @code{#} is set to N.
4954 The return status is always zero unless an invalid option is supplied.
4957 @node The Shopt Builtin
4958 @subsection The Shopt Builtin
4960 This builtin allows you to change additional shell optional behavior.
4967 shopt [-pqsu] [-o] [@var{optname} @dots{}]
4970 Toggle the values of settings controlling optional shell behavior.
4971 The settings can be either those listed below, or, if the
4972 @option{-o} option is used, those available with the @option{-o}
4973 option to the @code{set} builtin command (@pxref{The Set Builtin}).
4974 With no options, or with the @option{-p} option, a list of all settable
4975 options is displayed, with an indication of whether or not each is set.
4976 The @option{-p} option causes output to be displayed in a form that
4977 may be reused as input.
4978 Other options have the following meanings:
4982 Enable (set) each @var{optname}.
4985 Disable (unset) each @var{optname}.
4988 Suppresses normal output; the return status
4989 indicates whether the @var{optname} is set or unset.
4990 If multiple @var{optname} arguments are given with @option{-q},
4991 the return status is zero if all @var{optnames} are enabled;
4995 Restricts the values of
4996 @var{optname} to be those defined for the @option{-o} option to the
4997 @code{set} builtin (@pxref{The Set Builtin}).
5000 If either @option{-s} or @option{-u}
5001 is used with no @var{optname} arguments, @code{shopt} shows only
5002 those options which are set or unset, respectively.
5004 Unless otherwise noted, the @code{shopt} options are disabled (off)
5007 The return status when listing options is zero if all @var{optnames}
5008 are enabled, non-zero otherwise. When setting or unsetting options,
5009 the return status is zero unless an @var{optname} is not a valid shell
5012 The list of @code{shopt} options is:
5016 If set, a command name that is the name of a directory is executed as if
5017 it were the argument to the @code{cd} command.
5018 This option is only used by interactive shells.
5021 If this is set, an argument to the @code{cd} builtin command that
5022 is not a directory is assumed to be the name of a variable whose
5023 value is the directory to change to.
5026 If set, minor errors in the spelling of a directory component in a
5027 @code{cd} command will be corrected.
5028 The errors checked for are transposed characters,
5029 a missing character, and a character too many.
5030 If a correction is found, the corrected path is printed,
5031 and the command proceeds.
5032 This option is only used by interactive shells.
5035 If this is set, Bash checks that a command found in the hash
5036 table exists before trying to execute it. If a hashed command no
5037 longer exists, a normal path search is performed.
5040 If set, Bash lists the status of any stopped and running jobs before
5041 exiting an interactive shell. If any jobs are running, this causes
5042 the exit to be deferred until a second exit is attempted without an
5043 intervening command (@pxref{Job Control}).
5044 The shell always postpones exiting if any jobs are stopped.
5047 If set, Bash checks the window size after each command
5048 and, if necessary, updates the values of
5049 @env{LINES} and @env{COLUMNS}.
5053 attempts to save all lines of a multiple-line
5054 command in the same history entry. This allows
5055 easy re-editing of multi-line commands.
5059 changes its behavior to that of version 3.1 with respect to quoted
5060 arguments to the conditional command's @samp{=~} operator
5061 and with respect to locale-specific
5062 string comparison when using the @code{[[}
5063 conditional command's @samp{<} and @samp{>} operators.
5064 Bash versions prior to bash-4.1 use ASCII collation and strcmp(3);
5065 bash-4.1 and later use the current locale's collation sequence and strcoll(3).
5069 changes its behavior to that of version 3.2 with respect to locale-specific
5070 string comparison when using the @code{[[}
5071 conditional command's @samp{<} and @samp{>} operators (see previous item)
5072 and the effect of interrupting a command list.
5073 Bash versions 3.2 and earlier continue with the next command in the list
5074 after one terminates due to an interrupt.
5078 changes its behavior to that of version 4.0 with respect to locale-specific
5079 string comparison when using the @code{[[}
5080 conditional command's @samp{<} and @samp{>} operators (see description
5082 and the effect of interrupting a command list.
5083 Bash versions 4.0 and later interrupt the list as if the shell received the
5084 interrupt; previous versions continue with the next command in the list.
5087 If set, Bash, when in @sc{posix} mode, treats a single quote in a double-quoted
5088 parameter expansion as a special character. The single quotes must match
5089 (an even number) and the characters between the single quotes are considered
5090 quoted. This is the behavior of @sc{posix} mode through version 4.1.
5091 The default Bash behavior remains as in previous versions.
5095 does not process the replacement string in the pattern substitution word
5096 expansion using quote removal.
5100 does not print a warning message if an attempt is made to use a quoted compound
5101 array assignment as an argument to @code{declare},
5102 makes word expansion errors
5103 non-fatal errors that cause the current command to fail (the default behavior is
5104 to make them fatal errors that cause the shell to exit),
5105 and does not reset the
5106 loop state when a shell function is executed (this allows @code{break} or
5107 @code{continue} in a shell function to affect loops in the caller's context).
5109 @item complete_fullquote
5111 quotes all shell metacharacters in filenames and directory names when
5112 performing completion.
5114 removes metacharacters such as the dollar sign from the set of
5115 characters that will be quoted in completed filenames
5116 when these metacharacters appear in shell variable references in words to be
5118 This means that dollar signs in variable names that expand to directories
5120 however, any dollar signs appearing in filenames will not be quoted, either.
5121 This is active only when bash is using backslashes to quote completed
5123 This variable is set by default, which is the default Bash behavior in
5124 versions through 4.2.
5128 replaces directory names with the results of word expansion when performing
5129 filename completion. This changes the contents of the readline editing
5131 If not set, Bash attempts to preserve what the user typed.
5135 attempts spelling correction on directory names during word completion
5136 if the directory name initially supplied does not exist.
5139 If set, Bash includes filenames beginning with a `.' in
5140 the results of filename expansion.
5143 If this is set, a non-interactive shell will not exit if
5144 it cannot execute the file specified as an argument to the @code{exec}
5145 builtin command. An interactive shell does not exit if @code{exec}
5148 @item expand_aliases
5149 If set, aliases are expanded as described below under Aliases,
5151 This option is enabled by default for interactive shells.
5154 If set at shell invocation, arrange to execute the debugger profile
5155 before the shell starts, identical to the @option{--debugger} option.
5156 If set after invocation, behavior intended for use by debuggers is enabled:
5160 The @option{-F} option to the @code{declare} builtin (@pxref{Bash Builtins})
5161 displays the source file name and line number corresponding to each function
5162 name supplied as an argument.
5165 If the command run by the @code{DEBUG} trap returns a non-zero value, the
5166 next command is skipped and not executed.
5169 If the command run by the @code{DEBUG} trap returns a value of 2, and the
5170 shell is executing in a subroutine (a shell function or a shell script
5171 executed by the @code{.} or @code{source} builtins), the shell simulates
5172 a call to @code{return}.
5175 @code{BASH_ARGC} and @code{BASH_ARGV} are updated as described in their
5176 descriptions (@pxref{Bash Variables}).
5179 Function tracing is enabled: command substitution, shell functions, and
5180 subshells invoked with @code{( @var{command} )} inherit the
5181 @code{DEBUG} and @code{RETURN} traps.
5184 Error tracing is enabled: command substitution, shell functions, and
5185 subshells invoked with @code{( @var{command} )} inherit the
5190 If set, the extended pattern matching features described above
5191 (@pxref{Pattern Matching}) are enabled.
5194 If set, @code{$'@var{string}'} and @code{$"@var{string}"} quoting is
5195 performed within @code{$@{@var{parameter}@}} expansions
5196 enclosed in double quotes. This option is enabled by default.
5199 If set, patterns which fail to match filenames during filename expansion
5200 result in an expansion error.
5203 If set, the suffixes specified by the @env{FIGNORE} shell variable
5204 cause words to be ignored when performing word completion even if
5205 the ignored words are the only possible completions.
5206 @xref{Bash Variables}, for a description of @env{FIGNORE}.
5207 This option is enabled by default.
5209 @item globasciiranges
5210 If set, range expressions used in pattern matching bracket expressions
5211 (@pxref{Pattern Matching})
5212 behave as if in the traditional C locale when performing
5213 comparisons. That is, the current locale's collating sequence
5214 is not taken into account, so
5215 @samp{b} will not collate between @samp{A} and @samp{B},
5216 and upper-case and lower-case ASCII characters will collate together.
5219 If set, the pattern @samp{**} used in a filename expansion context will
5220 match all files and zero or more directories and subdirectories.
5221 If the pattern is followed by a @samp{/}, only directories and
5222 subdirectories match.
5225 If set, shell error messages are written in the standard @sc{gnu} error
5229 If set, the history list is appended to the file named by the value
5230 of the @env{HISTFILE}
5231 variable when the shell exits, rather than overwriting the file.
5234 If set, and Readline
5235 is being used, a user is given the opportunity to re-edit a
5236 failed history substitution.
5239 If set, and Readline
5240 is being used, the results of history substitution are not immediately
5241 passed to the shell parser. Instead, the resulting line is loaded into
5242 the Readline editing buffer, allowing further modification.
5245 If set, and Readline is being used, Bash will attempt to perform
5246 hostname completion when a word containing a @samp{@@} is being
5247 completed (@pxref{Commands For Completion}). This option is enabled
5251 If set, Bash will send @code{SIGHUP} to all jobs when an interactive
5252 login shell exits (@pxref{Signals}).
5254 @item inherit_errexit
5255 If set, command substitution inherits the value of the @code{errexit} option,
5256 instead of unsetting it in the subshell environment.
5257 This option is enabled when @sc{posix} mode is enabled.
5259 @item interactive_comments
5260 Allow a word beginning with @samp{#}
5261 to cause that word and all remaining characters on that
5262 line to be ignored in an interactive shell.
5263 This option is enabled by default.
5266 If set, and job control is not active, the shell runs the last command of
5267 a pipeline not executed in the background in the current shell environment.
5270 If enabled, and the @code{cmdhist}
5271 option is enabled, multi-line commands are saved to the history with
5272 embedded newlines rather than using semicolon separators where possible.
5275 The shell sets this option if it is started as a login shell
5276 (@pxref{Invoking Bash}).
5277 The value may not be changed.
5280 If set, and a file that Bash is checking for mail has been
5281 accessed since the last time it was checked, the message
5282 @code{"The mail in @var{mailfile} has been read"} is displayed.
5284 @item no_empty_cmd_completion
5285 If set, and Readline is being used, Bash will not attempt to search
5286 the @env{PATH} for possible completions when completion is attempted
5290 If set, Bash matches filenames in a case-insensitive fashion when
5291 performing filename expansion.
5294 If set, Bash matches patterns in a case-insensitive fashion when
5295 performing matching while executing @code{case} or @code{[[}
5296 conditional commands,
5297 when performing pattern substitution word expansions,
5298 or when filtering possible completions as part of programmable completion.
5301 If set, Bash allows filename patterns which match no
5302 files to expand to a null string, rather than themselves.
5305 If set, the programmable completion facilities
5306 (@pxref{Programmable Completion}) are enabled.
5307 This option is enabled by default.
5310 If set, prompt strings undergo
5311 parameter expansion, command substitution, arithmetic
5312 expansion, and quote removal after being expanded
5313 as described below (@pxref{Controlling the Prompt}).
5314 This option is enabled by default.
5316 @item restricted_shell
5317 The shell sets this option if it is started in restricted mode
5318 (@pxref{The Restricted Shell}).
5319 The value may not be changed.
5320 This is not reset when the startup files are executed, allowing
5321 the startup files to discover whether or not a shell is restricted.
5324 If this is set, the @code{shift}
5325 builtin prints an error message when the shift count exceeds the
5326 number of positional parameters.
5329 If set, the @code{source} builtin uses the value of @env{PATH}
5330 to find the directory containing the file supplied as an argument.
5331 This option is enabled by default.
5334 If set, the @code{echo} builtin expands backslash-escape sequences
5340 The return status when listing options is zero if all @var{optnames}
5341 are enabled, non-zero otherwise.
5342 When setting or unsetting options, the return status is zero unless an
5343 @var{optname} is not a valid shell option.
5346 @node Special Builtins
5347 @section Special Builtins
5348 @cindex special builtin
5350 For historical reasons, the @sc{posix} standard has classified
5351 several builtin commands as @emph{special}.
5352 When Bash is executing in @sc{posix} mode, the special builtins
5353 differ from other builtin commands in three respects:
5357 Special builtins are found before shell functions during command lookup.
5360 If a special builtin returns an error status, a non-interactive shell exits.
5363 Assignment statements preceding the command stay in effect in the shell
5364 environment after the command completes.
5367 When Bash is not executing in @sc{posix} mode, these builtins behave no
5368 differently than the rest of the Bash builtin commands.
5369 The Bash @sc{posix} mode is described in @ref{Bash POSIX Mode}.
5371 These are the @sc{posix} special builtins:
5373 @w{break : . continue eval exec exit export readonly return set}
5374 @w{shift trap unset}
5377 @node Shell Variables
5378 @chapter Shell Variables
5381 * Bourne Shell Variables:: Variables which Bash uses in the same way
5382 as the Bourne Shell.
5383 * Bash Variables:: List of variables that exist in Bash.
5386 This chapter describes the shell variables that Bash uses.
5387 Bash automatically assigns default values to a number of variables.
5389 @node Bourne Shell Variables
5390 @section Bourne Shell Variables
5392 Bash uses certain shell variables in the same way as the Bourne shell.
5393 In some cases, Bash assigns a default value to the variable.
5398 A colon-separated list of directories used as a search path for
5399 the @code{cd} builtin command.
5402 The current user's home directory; the default for the @code{cd} builtin
5404 The value of this variable is also used by tilde expansion
5405 (@pxref{Tilde Expansion}).
5408 A list of characters that separate fields; used when the shell splits
5409 words as part of expansion.
5412 If this parameter is set to a filename or directory name
5413 and the @env{MAILPATH} variable
5414 is not set, Bash informs the user of the arrival of mail in
5415 the specified file or Maildir-format directory.
5418 A colon-separated list of filenames which the shell periodically checks
5420 Each list entry can specify the message that is printed when new mail
5421 arrives in the mail file by separating the filename from the message with
5423 When used in the text of the message, @code{$_} expands to the name of
5424 the current mail file.
5427 The value of the last option argument processed by the @code{getopts} builtin.
5430 The index of the last option argument processed by the @code{getopts} builtin.
5433 A colon-separated list of directories in which the shell looks for
5435 A zero-length (null) directory name in the value of @code{PATH} indicates the
5437 A null directory name may appear as two adjacent colons, or as an initial
5441 The primary prompt string. The default value is @samp{\s-\v\$ }.
5442 @xref{Controlling the Prompt}, for the complete list of escape
5443 sequences that are expanded before @env{PS1} is displayed.
5446 The secondary prompt string. The default value is @samp{> }.
5450 @node Bash Variables
5451 @section Bash Variables
5453 These variables are set or used by Bash, but other shells
5454 do not normally treat them specially.
5456 A few variables used by Bash are described in different chapters:
5457 variables for controlling the job control facilities
5458 (@pxref{Job Control Variables}).
5463 The full pathname used to execute the current instance of Bash.
5466 A colon-separated list of enabled shell options. Each word in
5467 the list is a valid argument for the @option{-s} option to the
5468 @code{shopt} builtin command (@pxref{The Shopt Builtin}).
5469 The options appearing in @env{BASHOPTS} are those reported
5470 as @samp{on} by @samp{shopt}.
5471 If this variable is in the environment when Bash
5472 starts up, each shell option in the list will be enabled before
5473 reading any startup files. This variable is readonly.
5476 Expands to the process ID of the current Bash process.
5477 This differs from @code{$$} under certain circumstances, such as subshells
5478 that do not require Bash to be re-initialized.
5481 An associative array variable whose members correspond to the internal
5482 list of aliases as maintained by the @code{alias} builtin.
5483 (@pxref{Bourne Shell Builtins}).
5484 Elements added to this array appear in the alias list; however,
5485 unsetting array elements currently does not cause aliases to be removed
5486 from the alias list.
5487 If @code{BASH_ALIASES}
5488 is unset, it loses its special properties, even if it is
5492 An array variable whose values are the number of parameters in each
5493 frame of the current bash execution call stack. The number of
5494 parameters to the current subroutine (shell function or script executed
5495 with @code{.} or @code{source}) is at the top of the stack. When a
5496 subroutine is executed, the number of parameters passed is pushed onto
5498 The shell sets @code{BASH_ARGC} only when in extended debugging mode
5499 (see @ref{The Shopt Builtin}
5500 for a description of the @code{extdebug} option to the @code{shopt}
5504 An array variable containing all of the parameters in the current bash
5505 execution call stack. The final parameter of the last subroutine call
5506 is at the top of the stack; the first parameter of the initial call is
5507 at the bottom. When a subroutine is executed, the parameters supplied
5508 are pushed onto @code{BASH_ARGV}.
5509 The shell sets @code{BASH_ARGV} only when in extended debugging mode
5510 (see @ref{The Shopt Builtin}
5511 for a description of the @code{extdebug} option to the @code{shopt}
5515 An associative array variable whose members correspond to the internal
5516 hash table of commands as maintained by the @code{hash} builtin
5517 (@pxref{Bourne Shell Builtins}).
5518 Elements added to this array appear in the hash table; however,
5519 unsetting array elements currently does not cause command names to be removed
5520 from the hash table.
5522 is unset, it loses its special properties, even if it is
5526 The command currently being executed or about to be executed, unless the
5527 shell is executing a command as the result of a trap,
5528 in which case it is the command executing at the time of the trap.
5531 The value is used to set the shell's compatibility level.
5532 @xref{The Shopt Builtin}, for a description of the various compatibility
5533 levels and their effects.
5534 The value may be a decimal number (e.g., 4.2) or an integer (e.g., 42)
5535 corresponding to the desired compatibility level.
5536 If @code{BASH_COMPAT} is unset or set to the empty string, the compatibility
5537 level is set to the default for the current version.
5538 If @code{BASH_COMPAT} is set to a value that is not one of the valid
5539 compatibility levels, the shell prints an error message and sets the
5540 compatibility level to the default for the current version.
5541 The valid compatibility levels correspond to the compatibility options
5542 accepted by the @code{shopt} builtin described above (for example,
5543 @var{compat42} means that 4.2 and 42 are valid values).
5544 The current version is also a valid value.
5547 If this variable is set when Bash is invoked to execute a shell
5548 script, its value is expanded and used as the name of a startup file
5549 to read before executing the script. @xref{Bash Startup Files}.
5551 @item BASH_EXECUTION_STRING
5552 The command argument to the @option{-c} invocation option.
5555 An array variable whose members are the line numbers in source files
5556 where each corresponding member of @var{FUNCNAME} was invoked.
5557 @code{$@{BASH_LINENO[$i]@}} is the line number in the source file
5558 (@code{$@{BASH_SOURCE[$i+1]@}}) where
5559 @code{$@{FUNCNAME[$i]@}} was called (or @code{$@{BASH_LINENO[$i-1]@}} if
5560 referenced within another shell function).
5561 Use @code{LINENO} to obtain the current line number.
5563 @item BASH_LOADABLES_PATH
5564 A colon-separated list of directories in which the shell looks for
5565 dynamically loadable builtins specified by the
5566 @code{enable} command.
5569 An array variable whose members are assigned by the @samp{=~} binary
5570 operator to the @code{[[} conditional command
5571 (@pxref{Conditional Constructs}).
5572 The element with index 0 is the portion of the string
5573 matching the entire regular expression.
5574 The element with index @var{n} is the portion of the
5575 string matching the @var{n}th parenthesized subexpression.
5576 This variable is read-only.
5579 An array variable whose members are the source filenames where the
5580 corresponding shell function names in the @code{FUNCNAME} array
5581 variable are defined.
5582 The shell function @code{$@{FUNCNAME[$i]@}} is defined in the file
5583 @code{$@{BASH_SOURCE[$i]@}} and called from @code{$@{BASH_SOURCE[$i+1]@}}
5586 Incremented by one within each subshell or subshell environment when
5587 the shell begins executing in that environment.
5588 The initial value is 0.
5591 A readonly array variable (@pxref{Arrays})
5592 whose members hold version information for this instance of Bash.
5593 The values assigned to the array members are as follows:
5597 @item BASH_VERSINFO[0]
5598 The major version number (the @var{release}).
5600 @item BASH_VERSINFO[1]
5601 The minor version number (the @var{version}).
5603 @item BASH_VERSINFO[2]
5606 @item BASH_VERSINFO[3]
5609 @item BASH_VERSINFO[4]
5610 The release status (e.g., @var{beta1}).
5612 @item BASH_VERSINFO[5]
5613 The value of @env{MACHTYPE}.
5617 The version number of the current instance of Bash.
5620 If set to an integer corresponding to a valid file descriptor, Bash
5621 will write the trace output generated when @samp{set -x}
5622 is enabled to that file descriptor.
5623 This allows tracing output to be separated from diagnostic and error
5625 The file descriptor is closed when @code{BASH_XTRACEFD} is unset or assigned
5627 Unsetting @code{BASH_XTRACEFD} or assigning it the empty string causes the
5628 trace output to be sent to the standard error.
5629 Note that setting @code{BASH_XTRACEFD} to 2 (the standard error file
5630 descriptor) and then unsetting it will result in the standard error
5634 Set the number of exited child status values for the shell to remember.
5635 Bash will not allow this value to be decreased below a @sc{posix}-mandated
5636 minimum, and there is a maximum value (currently 8192) that this may
5638 The minimum value is system-dependent.
5641 Used by the @code{select} command to determine the terminal width
5642 when printing selection lists.
5643 Automatically set if the @code{checkwinsize} option is enabled
5644 (@pxref{The Shopt Builtin}), or in an interactive shell upon receipt of a
5648 An index into @env{$@{COMP_WORDS@}} of the word containing the current
5650 This variable is available only in shell functions invoked by the
5651 programmable completion facilities (@pxref{Programmable Completion}).
5654 The current command line.
5655 This variable is available only in shell functions and external
5656 commands invoked by the
5657 programmable completion facilities (@pxref{Programmable Completion}).
5660 The index of the current cursor position relative to the beginning of
5661 the current command.
5662 If the current cursor position is at the end of the current command,
5663 the value of this variable is equal to @code{$@{#COMP_LINE@}}.
5664 This variable is available only in shell functions and external
5665 commands invoked by the
5666 programmable completion facilities (@pxref{Programmable Completion}).
5669 Set to an integer value corresponding to the type of completion attempted
5670 that caused a completion function to be called:
5671 @var{TAB}, for normal completion,
5672 @samp{?}, for listing completions after successive tabs,
5673 @samp{!}, for listing alternatives on partial word completion,
5674 @samp{@@}, to list completions if the word is not unmodified,
5676 @samp{%}, for menu completion.
5677 This variable is available only in shell functions and external
5678 commands invoked by the
5679 programmable completion facilities (@pxref{Programmable Completion}).
5682 The key (or final key of a key sequence) used to invoke the current
5683 completion function.
5685 @item COMP_WORDBREAKS
5686 The set of characters that the Readline library treats as word
5687 separators when performing word completion.
5688 If @code{COMP_WORDBREAKS} is unset, it loses its special properties,
5689 even if it is subsequently reset.
5692 An array variable consisting of the individual
5693 words in the current command line.
5694 The line is split into words as Readline would split it, using
5695 @code{COMP_WORDBREAKS} as described above.
5696 This variable is available only in shell functions invoked by the
5697 programmable completion facilities (@pxref{Programmable Completion}).
5700 An array variable from which Bash reads the possible completions
5701 generated by a shell function invoked by the programmable completion
5702 facility (@pxref{Programmable Completion}).
5703 Each array element contains one possible completion.
5706 An array variable created to hold the file descriptors
5707 for output from and input to an unnamed coprocess (@pxref{Coprocesses}).
5710 An array variable containing the current contents of the directory stack.
5711 Directories appear in the stack in the order they are displayed by the
5712 @code{dirs} builtin.
5713 Assigning to members of this array variable may be used to modify
5714 directories already in the stack, but the @code{pushd} and @code{popd}
5715 builtins must be used to add and remove directories.
5716 Assignment to this variable will not change the current directory.
5717 If @env{DIRSTACK} is unset, it loses its special properties, even if
5718 it is subsequently reset.
5721 If Bash finds this variable in the environment when the shell
5722 starts with value @samp{t}, it assumes that the shell is running in an
5723 Emacs shell buffer and disables line editing.
5726 Similar to @code{BASH_ENV}; used when the shell is invoked in
5727 @sc{posix} Mode (@pxref{Bash POSIX Mode}).
5730 The numeric effective user id of the current user. This variable
5734 A colon-separated list of shell patterns (@pxref{Pattern Matching})
5735 defining the list of filenames to be ignored by command search using
5737 Files whose full pathnames match one of these patterns are not considered
5738 executable files for the purposes of completion and command execution
5739 via @code{PATH} lookup.
5740 This does not affect the behavior of the @code{[}, @code{test}, and @code{[[}
5742 Full pathnames in the command hash table are not subject to @code{EXECIGNORE}.
5743 Use this variable to ignore shared library files that have the executable
5744 bit set, but are not executable files.
5745 The pattern matching honors the setting of the @code{extglob} shell
5749 The editor used as a default by the @option{-e} option to the @code{fc}
5753 A colon-separated list of suffixes to ignore when performing
5754 filename completion.
5755 A filename whose suffix matches one of the entries in
5757 is excluded from the list of matched filenames. A sample
5758 value is @samp{.o:~}
5761 An array variable containing the names of all shell functions
5762 currently in the execution call stack.
5763 The element with index 0 is the name of any currently-executing
5765 The bottom-most element (the one with the highest index)
5767 This variable exists only when a shell function is executing.
5768 Assignments to @env{FUNCNAME} have no effect.
5769 If @env{FUNCNAME} is unset, it loses its special properties, even if
5770 it is subsequently reset.
5772 This variable can be used with @code{BASH_LINENO} and @code{BASH_SOURCE}.
5773 Each element of @code{FUNCNAME} has corresponding elements in
5774 @code{BASH_LINENO} and @code{BASH_SOURCE} to describe the call stack.
5775 For instance, @code{$@{FUNCNAME[$i]@}} was called from the file
5776 @code{$@{BASH_SOURCE[$i+1]@}} at line number @code{$@{BASH_LINENO[$i]@}}.
5777 The @code{caller} builtin displays the current call stack using this
5781 If set to a numeric value greater than 0, defines a maximum function
5782 nesting level. Function invocations that exceed this nesting level
5783 will cause the current command to abort.
5786 A colon-separated list of patterns defining the set of filenames to
5787 be ignored by filename expansion.
5788 If a filename matched by a filename expansion pattern also matches one
5789 of the patterns in @env{GLOBIGNORE}, it is removed from the list
5791 The pattern matching honors the setting of the @code{extglob} shell
5795 An array variable containing the list of groups of which the current
5797 Assignments to @env{GROUPS} have no effect.
5798 If @env{GROUPS} is unset, it loses its special properties, even if it is
5802 Up to three characters which control history expansion, quick
5803 substitution, and tokenization (@pxref{History Interaction}).
5804 The first character is the
5805 @var{history expansion} character, that is, the character which signifies the
5806 start of a history expansion, normally @samp{!}. The second character is the
5807 character which signifies `quick substitution' when seen as the first
5808 character on a line, normally @samp{^}. The optional third character is the
5809 character which indicates that the remainder of the line is a comment when
5810 found as the first character of a word, usually @samp{#}. The history
5811 comment character causes history substitution to be skipped for the
5812 remaining words on the line. It does not necessarily cause the shell
5813 parser to treat the rest of the line as a comment.
5816 The history number, or index in the history list, of the current
5817 command. If @env{HISTCMD} is unset, it loses its special properties,
5818 even if it is subsequently reset.
5821 A colon-separated list of values controlling how commands are saved on
5823 If the list of values includes @samp{ignorespace}, lines which begin
5824 with a space character are not saved in the history list.
5825 A value of @samp{ignoredups} causes lines which match the previous
5826 history entry to not be saved.
5827 A value of @samp{ignoreboth} is shorthand for
5828 @samp{ignorespace} and @samp{ignoredups}.
5829 A value of @samp{erasedups} causes all previous lines matching the
5830 current line to be removed from the history list before that line
5832 Any value not in the above list is ignored.
5833 If @env{HISTCONTROL} is unset, or does not include a valid value,
5834 all lines read by the shell parser are saved on the history list,
5835 subject to the value of @env{HISTIGNORE}.
5836 The second and subsequent lines of a multi-line compound command are
5837 not tested, and are added to the history regardless of the value of
5841 The name of the file to which the command history is saved. The
5842 default value is @file{~/.bash_history}.
5845 The maximum number of lines contained in the history file.
5846 When this variable is assigned a value, the history file is truncated,
5847 if necessary, to contain no more than that number of lines
5848 by removing the oldest entries.
5849 The history file is also truncated to this size after
5850 writing it when a shell exits.
5851 If the value is 0, the history file is truncated to zero size.
5852 Non-numeric values and numeric values less than zero inhibit truncation.
5853 The shell sets the default value to the value of @env{HISTSIZE}
5854 after reading any startup files.
5857 A colon-separated list of patterns used to decide which command
5858 lines should be saved on the history list. Each pattern is
5859 anchored at the beginning of the line and must match the complete
5860 line (no implicit @samp{*} is appended). Each pattern is tested
5861 against the line after the checks specified by @env{HISTCONTROL}
5862 are applied. In addition to the normal shell pattern matching
5863 characters, @samp{&} matches the previous history line. @samp{&}
5864 may be escaped using a backslash; the backslash is removed
5865 before attempting a match.
5866 The second and subsequent lines of a multi-line compound command are
5867 not tested, and are added to the history regardless of the value of
5869 The pattern matching honors the setting of the @code{extglob} shell
5872 @env{HISTIGNORE} subsumes the function of @env{HISTCONTROL}. A
5873 pattern of @samp{&} is identical to @code{ignoredups}, and a
5874 pattern of @samp{[ ]*} is identical to @code{ignorespace}.
5875 Combining these two patterns, separating them with a colon,
5876 provides the functionality of @code{ignoreboth}.
5879 The maximum number of commands to remember on the history list.
5880 If the value is 0, commands are not saved in the history list.
5881 Numeric values less than zero result in every command being saved
5882 on the history list (there is no limit).
5883 The shell sets the default value to 500 after reading any startup files.
5885 @item HISTTIMEFORMAT
5886 If this variable is set and not null, its value is used as a format string
5887 for @var{strftime} to print the time stamp associated with each history
5888 entry displayed by the @code{history} builtin.
5889 If this variable is set, time stamps are written to the history file so
5890 they may be preserved across shell sessions.
5891 This uses the history comment character to distinguish timestamps from
5892 other history lines.
5895 Contains the name of a file in the same format as @file{/etc/hosts} that
5896 should be read when the shell needs to complete a hostname.
5897 The list of possible hostname completions may be changed while the shell
5899 the next time hostname completion is attempted after the
5900 value is changed, Bash adds the contents of the new file to the
5902 If @env{HOSTFILE} is set, but has no value, or does not name a readable file,
5903 Bash attempts to read
5904 @file{/etc/hosts} to obtain the list of possible hostname completions.
5905 When @env{HOSTFILE} is unset, the hostname list is cleared.
5908 The name of the current host.
5911 A string describing the machine Bash is running on.
5914 Controls the action of the shell on receipt of an @code{EOF} character
5915 as the sole input. If set, the value denotes the number
5916 of consecutive @code{EOF} characters that can be read as the
5917 first character on an input line
5918 before the shell will exit. If the variable exists but does not
5919 have a numeric value (or has no value) then the default is 10.
5920 If the variable does not exist, then @code{EOF} signifies the end of
5921 input to the shell. This is only in effect for interactive shells.
5924 The name of the Readline initialization file, overriding the default
5925 of @file{~/.inputrc}.
5928 Used to determine the locale category for any category not specifically
5929 selected with a variable starting with @code{LC_}.
5932 This variable overrides the value of @env{LANG} and any other
5933 @code{LC_} variable specifying a locale category.
5936 This variable determines the collation order used when sorting the
5937 results of filename expansion, and
5938 determines the behavior of range expressions, equivalence classes,
5939 and collating sequences within filename expansion and pattern matching
5940 (@pxref{Filename Expansion}).
5943 This variable determines the interpretation of characters and the
5944 behavior of character classes within filename expansion and pattern
5945 matching (@pxref{Filename Expansion}).
5948 This variable determines the locale used to translate double-quoted
5949 strings preceded by a @samp{$} (@pxref{Locale Translation}).
5952 This variable determines the locale category used for number formatting.
5955 This variable determines the locale category used for data and time
5959 The line number in the script or shell function currently executing.
5962 Used by the @code{select} command to determine the column length
5963 for printing selection lists.
5964 Automatically set if the @code{checkwinsize} option is enabled
5965 (@pxref{The Shopt Builtin}), or in an interactive shell upon receipt of a
5969 A string that fully describes the system type on which Bash
5970 is executing, in the standard @sc{gnu} @var{cpu-company-system} format.
5973 How often (in seconds) that the shell should check for mail in the
5974 files specified in the @env{MAILPATH} or @env{MAIL} variables.
5975 The default is 60 seconds. When it is time to check
5976 for mail, the shell does so before displaying the primary prompt.
5977 If this variable is unset, or set to a value that is not a number
5978 greater than or equal to zero, the shell disables mail checking.
5981 An array variable created to hold the text read by the
5982 @code{mapfile} builtin when no variable name is supplied.
5985 The previous working directory as set by the @code{cd} builtin.
5988 If set to the value 1, Bash displays error messages
5989 generated by the @code{getopts} builtin command.
5992 A string describing the operating system Bash is running on.
5995 An array variable (@pxref{Arrays})
5996 containing a list of exit status values from the processes
5997 in the most-recently-executed foreground pipeline (which may
5998 contain only a single command).
6000 @item POSIXLY_CORRECT
6001 If this variable is in the environment when Bash starts, the shell
6002 enters @sc{posix} mode (@pxref{Bash POSIX Mode}) before reading the
6003 startup files, as if the @option{--posix} invocation option had been supplied.
6004 If it is set while the shell is running, Bash enables @sc{posix} mode,
6013 The process @sc{id} of the shell's parent process. This variable
6016 @item PROMPT_COMMAND
6017 If set, the value is interpreted as a command to execute
6018 before the printing of each primary prompt (@env{$PS1}).
6020 @item PROMPT_DIRTRIM
6021 If set to a number greater than zero, the value is used as the number of
6022 trailing directory components to retain when expanding the @code{\w} and
6023 @code{\W} prompt string escapes (@pxref{Controlling the Prompt}).
6024 Characters removed are replaced with an ellipsis.
6027 The value of this parameter is expanded like @var{PS1}
6028 and displayed by interactive shells after reading a command
6029 and before the command is executed.
6032 The value of this variable is used as the prompt for the
6033 @code{select} command. If this variable is not set, the
6034 @code{select} command prompts with @samp{#? }
6037 The value is the prompt printed before the command line is echoed
6038 when the @option{-x} option is set (@pxref{The Set Builtin}).
6039 The first character of @env{PS4} is replicated multiple times, as
6040 necessary, to indicate multiple levels of indirection.
6041 The default is @samp{+ }.
6044 The current working directory as set by the @code{cd} builtin.
6047 Each time this parameter is referenced, a random integer
6048 between 0 and 32767 is generated. Assigning a value to this
6049 variable seeds the random number generator.
6052 The contents of the Readline line buffer, for use
6053 with @samp{bind -x} (@pxref{Bash Builtins}).
6055 @item READLINE_POINT
6056 The position of the insertion point in the Readline line buffer, for use
6057 with @samp{bind -x} (@pxref{Bash Builtins}).
6060 The default variable for the @code{read} builtin.
6063 This variable expands to the number of seconds since the
6064 shell was started. Assignment to this variable resets
6065 the count to the value assigned, and the expanded value
6066 becomes the value assigned plus the number of seconds
6067 since the assignment.
6070 The full pathname to the shell is kept in this environment variable.
6071 If it is not set when the shell starts,
6072 Bash assigns to it the full pathname of the current user's login shell.
6075 A colon-separated list of enabled shell options. Each word in
6076 the list is a valid argument for the @option{-o} option to the
6077 @code{set} builtin command (@pxref{The Set Builtin}).
6078 The options appearing in @env{SHELLOPTS} are those reported
6079 as @samp{on} by @samp{set -o}.
6080 If this variable is in the environment when Bash
6081 starts up, each shell option in the list will be enabled before
6082 reading any startup files. This variable is readonly.
6085 Incremented by one each time a new instance of Bash is started. This is
6086 intended to be a count of how deeply your Bash shells are nested.
6089 The value of this parameter is used as a format string specifying
6090 how the timing information for pipelines prefixed with the @code{time}
6091 reserved word should be displayed.
6092 The @samp{%} character introduces an
6093 escape sequence that is expanded to a time value or other
6095 The escape sequences and their meanings are as
6096 follows; the braces denote optional portions.
6103 @item %[@var{p}][l]R
6104 The elapsed time in seconds.
6106 @item %[@var{p}][l]U
6107 The number of CPU seconds spent in user mode.
6109 @item %[@var{p}][l]S
6110 The number of CPU seconds spent in system mode.
6113 The CPU percentage, computed as (%U + %S) / %R.
6116 The optional @var{p} is a digit specifying the precision, the number of
6117 fractional digits after a decimal point.
6118 A value of 0 causes no decimal point or fraction to be output.
6119 At most three places after the decimal point may be specified; values
6120 of @var{p} greater than 3 are changed to 3.
6121 If @var{p} is not specified, the value 3 is used.
6123 The optional @code{l} specifies a longer format, including minutes, of
6124 the form @var{MM}m@var{SS}.@var{FF}s.
6125 The value of @var{p} determines whether or not the fraction is included.
6127 If this variable is not set, Bash acts as if it had the value
6129 @code{$'\nreal\t%3lR\nuser\t%3lU\nsys\t%3lS'}
6131 If the value is null, no timing information is displayed.
6132 A trailing newline is added when the format string is displayed.
6135 If set to a value greater than zero, @code{TMOUT} is treated as the
6136 default timeout for the @code{read} builtin (@pxref{Bash Builtins}).
6137 The @code{select} command (@pxref{Conditional Constructs}) terminates
6138 if input does not arrive after @code{TMOUT} seconds when input is coming
6141 In an interactive shell, the value is interpreted as
6142 the number of seconds to wait for a line of input after issuing
6145 terminates after waiting for that number of seconds if a complete
6146 line of input does not arrive.
6149 If set, Bash uses its value as the name of a directory in which
6150 Bash creates temporary files for the shell's use.
6153 The numeric real user id of the current user. This variable is readonly.
6158 @chapter Bash Features
6160 This chapter describes features unique to Bash.
6163 * Invoking Bash:: Command line options that you can give
6165 * Bash Startup Files:: When and how Bash executes scripts.
6166 * Interactive Shells:: What an interactive shell is.
6167 * Bash Conditional Expressions:: Primitives used in composing expressions for
6168 the @code{test} builtin.
6169 * Shell Arithmetic:: Arithmetic on shell variables.
6170 * Aliases:: Substituting one command for another.
6171 * Arrays:: Array Variables.
6172 * The Directory Stack:: History of visited directories.
6173 * Controlling the Prompt:: Customizing the various prompt strings.
6174 * The Restricted Shell:: A more controlled mode of shell execution.
6175 * Bash POSIX Mode:: Making Bash behave more closely to what
6176 the POSIX standard specifies.
6180 @section Invoking Bash
6183 bash [long-opt] [-ir] [-abefhkmnptuvxdBCDHP] [-o @var{option}] [-O @var{shopt_option}] [@var{argument} @dots{}]
6184 bash [long-opt] [-abefhkmnptuvxdBCDHP] [-o @var{option}] [-O @var{shopt_option}] -c @var{string} [@var{argument} @dots{}]
6185 bash [long-opt] -s [-abefhkmnptuvxdBCDHP] [-o @var{option}] [-O @var{shopt_option}] [@var{argument} @dots{}]
6188 All of the single-character options used with the @code{set} builtin
6189 (@pxref{The Set Builtin}) can be used as options when the shell is invoked.
6190 In addition, there are several multi-character
6191 options that you can use. These options must appear on the command
6192 line before the single-character options to be recognized.
6196 Arrange for the debugger profile to be executed before the shell
6197 starts. Turns on extended debugging mode (see @ref{The Shopt Builtin}
6198 for a description of the @code{extdebug} option to the @code{shopt}
6201 @item --dump-po-strings
6202 A list of all double-quoted strings preceded by @samp{$}
6203 is printed on the standard output
6204 in the @sc{gnu} @code{gettext} PO (portable object) file format.
6205 Equivalent to @option{-D} except for the output format.
6207 @item --dump-strings
6208 Equivalent to @option{-D}.
6211 Display a usage message on standard output and exit successfully.
6213 @item --init-file @var{filename}
6214 @itemx --rcfile @var{filename}
6215 Execute commands from @var{filename} (instead of @file{~/.bashrc})
6216 in an interactive shell.
6219 Equivalent to @option{-l}.
6222 Do not use the @sc{gnu} Readline library (@pxref{Command Line Editing})
6223 to read command lines when the shell is interactive.
6226 Don't load the system-wide startup file @file{/etc/profile}
6227 or any of the personal initialization files
6228 @file{~/.bash_profile}, @file{~/.bash_login}, or @file{~/.profile}
6229 when Bash is invoked as a login shell.
6232 Don't read the @file{~/.bashrc} initialization file in an
6233 interactive shell. This is on by default if the shell is
6234 invoked as @code{sh}.
6237 Change the behavior of Bash where the default operation differs
6238 from the @sc{posix} standard to match the standard. This
6239 is intended to make Bash behave as a strict superset of that
6240 standard. @xref{Bash POSIX Mode}, for a description of the Bash
6244 Make the shell a restricted shell (@pxref{The Restricted Shell}).
6247 Equivalent to @option{-v}. Print shell input lines as they're read.
6250 Show version information for this instance of
6251 Bash on the standard output and exit successfully.
6254 There are several single-character options that may be supplied at
6255 invocation which are not available with the @code{set} builtin.
6259 Read and execute commands from the first non-option argument
6260 @var{command_string}, then exit.
6261 If there are arguments after the @var{command_string},
6262 the first argument is assigned to @code{$0}
6263 and any remaining arguments are assigned to the positional parameters.
6264 The assignment to @code{$0} sets the name of the shell, which is used
6265 in warning and error messages.
6268 Force the shell to run interactively. Interactive shells are
6269 described in @ref{Interactive Shells}.
6272 Make this shell act as if it had been directly invoked by login.
6273 When the shell is interactive, this is equivalent to starting a
6274 login shell with @samp{exec -l bash}.
6275 When the shell is not interactive, the login shell startup files will
6277 @samp{exec bash -l} or @samp{exec bash --login}
6278 will replace the current shell with a Bash login shell.
6279 @xref{Bash Startup Files}, for a description of the special behavior
6283 Make the shell a restricted shell (@pxref{The Restricted Shell}).
6286 If this option is present, or if no arguments remain after option
6287 processing, then commands are read from the standard input.
6288 This option allows the positional parameters to be set
6289 when invoking an interactive shell.
6292 A list of all double-quoted strings preceded by @samp{$}
6293 is printed on the standard output.
6294 These are the strings that
6295 are subject to language translation when the current locale
6296 is not @code{C} or @code{POSIX} (@pxref{Locale Translation}).
6297 This implies the @option{-n} option; no commands will be executed.
6299 @item [-+]O [@var{shopt_option}]
6300 @var{shopt_option} is one of the shell options accepted by the
6301 @code{shopt} builtin (@pxref{The Shopt Builtin}).
6302 If @var{shopt_option} is present, @option{-O} sets the value of that option;
6303 @option{+O} unsets it.
6304 If @var{shopt_option} is not supplied, the names and values of the shell
6305 options accepted by @code{shopt} are printed on the standard output.
6306 If the invocation option is @option{+O}, the output is displayed in a format
6307 that may be reused as input.
6310 A @code{--} signals the end of options and disables further option
6312 Any arguments after the @code{--} are treated as filenames and arguments.
6316 A @emph{login} shell is one whose first character of argument zero is
6317 @samp{-}, or one invoked with the @option{--login} option.
6319 @cindex interactive shell
6320 An @emph{interactive} shell is one started without non-option arguments,
6321 unless @option{-s} is specified,
6322 without specifying the @option{-c} option, and whose input and output are both
6323 connected to terminals (as determined by @code{isatty(3)}), or one
6324 started with the @option{-i} option. @xref{Interactive Shells}, for more
6327 If arguments remain after option processing, and neither the
6328 @option{-c} nor the @option{-s}
6329 option has been supplied, the first argument is assumed to
6330 be the name of a file containing shell commands (@pxref{Shell Scripts}).
6331 When Bash is invoked in this fashion, @code{$0}
6332 is set to the name of the file, and the positional parameters
6333 are set to the remaining arguments.
6334 Bash reads and executes commands from this file, then exits.
6335 Bash's exit status is the exit status of the last command executed
6336 in the script. If no commands are executed, the exit status is 0.
6338 @node Bash Startup Files
6339 @section Bash Startup Files
6340 @cindex startup files
6342 This section describes how Bash executes its startup files.
6343 If any of the files exist but cannot be read, Bash reports an error.
6344 Tildes are expanded in filenames as described above under
6345 Tilde Expansion (@pxref{Tilde Expansion}).
6347 Interactive shells are described in @ref{Interactive Shells}.
6349 @subsubheading Invoked as an interactive login shell, or with @option{--login}
6351 When Bash is invoked as an interactive login shell, or as a
6352 non-interactive shell with the @option{--login} option, it first reads and
6353 executes commands from the file @file{/etc/profile}, if that file exists.
6354 After reading that file, it looks for @file{~/.bash_profile},
6355 @file{~/.bash_login}, and @file{~/.profile}, in that order, and reads
6356 and executes commands from the first one that exists and is readable.
6357 The @option{--noprofile} option may be used when the shell is started to
6358 inhibit this behavior.
6360 When an interactive login shell exits,
6361 or a non-interactive login shell executes the @code{exit} builtin command,
6362 Bash reads and executes commands from
6363 the file @file{~/.bash_logout}, if it exists.
6365 @subsubheading Invoked as an interactive non-login shell
6367 When an interactive shell that is not a login shell is started, Bash
6368 reads and executes commands from @file{~/.bashrc}, if that file exists.
6369 This may be inhibited by using the @option{--norc} option.
6370 The @option{--rcfile @var{file}} option will force Bash to read and
6371 execute commands from @var{file} instead of @file{~/.bashrc}.
6373 So, typically, your @file{~/.bash_profile} contains the line
6375 @code{if [ -f ~/.bashrc ]; then . ~/.bashrc; fi}
6378 after (or before) any login-specific initializations.
6380 @subsubheading Invoked non-interactively
6382 When Bash is started non-interactively, to run a shell script,
6383 for example, it looks for the variable @env{BASH_ENV} in the environment,
6384 expands its value if it appears there, and uses the expanded value as
6385 the name of a file to read and execute. Bash behaves as if the
6386 following command were executed:
6388 @code{if [ -n "$BASH_ENV" ]; then . "$BASH_ENV"; fi}
6391 but the value of the @env{PATH} variable is not used to search for the
6394 As noted above, if a non-interactive shell is invoked with the
6395 @option{--login} option, Bash attempts to read and execute commands from the
6396 login shell startup files.
6398 @subsubheading Invoked with name @code{sh}
6400 If Bash is invoked with the name @code{sh}, it tries to mimic the
6401 startup behavior of historical versions of @code{sh} as closely as
6402 possible, while conforming to the @sc{posix} standard as well.
6404 When invoked as an interactive login shell, or as a non-interactive
6405 shell with the @option{--login} option, it first attempts to read
6406 and execute commands from @file{/etc/profile} and @file{~/.profile}, in
6408 The @option{--noprofile} option may be used to inhibit this behavior.
6409 When invoked as an interactive shell with the name @code{sh}, Bash
6410 looks for the variable @env{ENV}, expands its value if it is defined,
6411 and uses the expanded value as the name of a file to read and execute.
6412 Since a shell invoked as @code{sh} does not attempt to read and execute
6413 commands from any other startup files, the @option{--rcfile} option has
6415 A non-interactive shell invoked with the name @code{sh} does not attempt
6416 to read any other startup files.
6418 When invoked as @code{sh}, Bash enters @sc{posix} mode after
6419 the startup files are read.
6421 @subsubheading Invoked in @sc{posix} mode
6423 When Bash is started in @sc{posix} mode, as with the
6424 @option{--posix} command line option, it follows the @sc{posix} standard
6426 In this mode, interactive shells expand the @env{ENV} variable
6427 and commands are read and executed from the file whose name is the
6429 No other startup files are read.
6431 @subsubheading Invoked by remote shell daemon
6433 Bash attempts to determine when it is being run with its standard input
6434 connected to a network connection, as when executed by the remote shell
6435 daemon, usually @code{rshd}, or the secure shell daemon @code{sshd}.
6436 If Bash determines it is being run in
6437 this fashion, it reads and executes commands from @file{~/.bashrc}, if that
6438 file exists and is readable.
6439 It will not do this if invoked as @code{sh}.
6440 The @option{--norc} option may be used to inhibit this behavior, and the
6441 @option{--rcfile} option may be used to force another file to be read, but
6442 neither @code{rshd} nor @code{sshd} generally invoke the shell with those
6443 options or allow them to be specified.
6445 @subsubheading Invoked with unequal effective and real @sc{uid/gid}s
6447 If Bash is started with the effective user (group) id not equal to the
6448 real user (group) id, and the @option{-p} option is not supplied, no startup
6449 files are read, shell functions are not inherited from the environment,
6450 the @env{SHELLOPTS}, @env{BASHOPTS}, @env{CDPATH}, and @env{GLOBIGNORE}
6451 variables, if they appear in the environment, are ignored, and the effective
6452 user id is set to the real user id.
6453 If the @option{-p} option is supplied at invocation, the startup behavior is
6454 the same, but the effective user id is not reset.
6456 @node Interactive Shells
6457 @section Interactive Shells
6458 @cindex interactive shell
6459 @cindex shell, interactive
6462 * What is an Interactive Shell?:: What determines whether a shell is Interactive.
6463 * Is this Shell Interactive?:: How to tell if a shell is interactive.
6464 * Interactive Shell Behavior:: What changes in a interactive shell?
6467 @node What is an Interactive Shell?
6468 @subsection What is an Interactive Shell?
6470 An interactive shell
6471 is one started without non-option arguments, unless @option{-s} is
6472 specified, without specifying the @option{-c} option, and
6473 whose input and error output are both
6474 connected to terminals (as determined by @code{isatty(3)}),
6475 or one started with the @option{-i} option.
6477 An interactive shell generally reads from and writes to a user's
6480 The @option{-s} invocation option may be used to set the positional parameters
6481 when an interactive shell is started.
6483 @node Is this Shell Interactive?
6484 @subsection Is this Shell Interactive?
6486 To determine within a startup script whether or not Bash is
6487 running interactively,
6488 test the value of the @samp{-} special parameter.
6489 It contains @code{i} when the shell is interactive. For example:
6493 *i*) echo This shell is interactive ;;
6494 *) echo This shell is not interactive ;;
6498 Alternatively, startup scripts may examine the variable
6499 @env{PS1}; it is unset in non-interactive shells, and set in
6500 interactive shells. Thus:
6503 if [ -z "$PS1" ]; then
6504 echo This shell is not interactive
6506 echo This shell is interactive
6510 @node Interactive Shell Behavior
6511 @subsection Interactive Shell Behavior
6513 When the shell is running interactively, it changes its behavior in
6518 Startup files are read and executed as described in @ref{Bash Startup Files}.
6521 Job Control (@pxref{Job Control}) is enabled by default. When job
6522 control is in effect, Bash ignores the keyboard-generated job control
6523 signals @code{SIGTTIN}, @code{SIGTTOU}, and @code{SIGTSTP}.
6526 Bash expands and displays @env{PS1} before reading the first line
6527 of a command, and expands and displays @env{PS2} before reading the
6528 second and subsequent lines of a multi-line command.
6529 Bash displays @env{PS0} after it reads a command but before executing it.
6532 Bash executes the value of the @env{PROMPT_COMMAND} variable as a command
6533 before printing the primary prompt, @env{$PS1}
6534 (@pxref{Bash Variables}).
6537 Readline (@pxref{Command Line Editing}) is used to read commands from
6538 the user's terminal.
6541 Bash inspects the value of the @code{ignoreeof} option to @code{set -o}
6542 instead of exiting immediately when it receives an @code{EOF} on its
6543 standard input when reading a command (@pxref{The Set Builtin}).
6546 Command history (@pxref{Bash History Facilities})
6547 and history expansion (@pxref{History Interaction})
6548 are enabled by default.
6549 Bash will save the command history to the file named by @env{$HISTFILE}
6550 when a shell with history enabled exits.
6553 Alias expansion (@pxref{Aliases}) is performed by default.
6556 In the absence of any traps, Bash ignores @code{SIGTERM}
6560 In the absence of any traps, @code{SIGINT} is caught and handled
6562 @code{SIGINT} will interrupt some shell builtins.
6565 An interactive login shell sends a @code{SIGHUP} to all jobs on exit
6566 if the @code{huponexit} shell option has been enabled (@pxref{Signals}).
6569 The @option{-n} invocation option is ignored, and @samp{set -n} has
6570 no effect (@pxref{The Set Builtin}).
6573 Bash will check for mail periodically, depending on the values of the
6574 @env{MAIL}, @env{MAILPATH}, and @env{MAILCHECK} shell variables
6575 (@pxref{Bash Variables}).
6578 Expansion errors due to references to unbound shell variables after
6579 @samp{set -u} has been enabled will not cause the shell to exit
6580 (@pxref{The Set Builtin}).
6583 The shell will not exit on expansion errors caused by @var{var} being unset
6584 or null in @code{$@{@var{var}:?@var{word}@}} expansions
6585 (@pxref{Shell Parameter Expansion}).
6588 Redirection errors encountered by shell builtins will not cause the
6592 When running in @sc{posix} mode, a special builtin returning an error
6593 status will not cause the shell to exit (@pxref{Bash POSIX Mode}).
6596 A failed @code{exec} will not cause the shell to exit
6597 (@pxref{Bourne Shell Builtins}).
6600 Parser syntax errors will not cause the shell to exit.
6603 Simple spelling correction for directory arguments to the @code{cd}
6604 builtin is enabled by default (see the description of the @code{cdspell}
6605 option to the @code{shopt} builtin in @ref{The Shopt Builtin}).
6608 The shell will check the value of the @env{TMOUT} variable and exit
6609 if a command is not read within the specified number of seconds after
6610 printing @env{$PS1} (@pxref{Bash Variables}).
6614 @node Bash Conditional Expressions
6615 @section Bash Conditional Expressions
6616 @cindex expressions, conditional
6618 Conditional expressions are used by the @code{[[} compound command
6619 and the @code{test} and @code{[} builtin commands.
6621 Expressions may be unary or binary.
6622 Unary expressions are often used to examine the status of a file.
6623 There are string operators and numeric comparison operators as well.
6624 Bash handles several filenames specially when they are used in
6626 If the operating system on which Bash is running provides these
6627 special files, Bash will use them; otherwise it will emulate them
6628 internally with this behavior:
6629 If the @var{file} argument to one of the primaries is of the form
6630 @file{/dev/fd/@var{N}}, then file descriptor @var{N} is checked.
6631 If the @var{file} argument to one of the primaries is one of
6632 @file{/dev/stdin}, @file{/dev/stdout}, or @file{/dev/stderr}, file
6633 descriptor 0, 1, or 2, respectively, is checked.
6635 When used with @code{[[}, the @samp{<} and @samp{>} operators sort
6636 lexicographically using the current locale.
6637 The @code{test} command uses ASCII ordering.
6639 Unless otherwise specified, primaries that operate on files follow symbolic
6640 links and operate on the target of the link, rather than the link itself.
6644 True if @var{file} exists.
6647 True if @var{file} exists and is a block special file.
6650 True if @var{file} exists and is a character special file.
6653 True if @var{file} exists and is a directory.
6656 True if @var{file} exists.
6659 True if @var{file} exists and is a regular file.
6662 True if @var{file} exists and its set-group-id bit is set.
6665 True if @var{file} exists and is a symbolic link.
6668 True if @var{file} exists and its "sticky" bit is set.
6671 True if @var{file} exists and is a named pipe (FIFO).
6674 True if @var{file} exists and is readable.
6677 True if @var{file} exists and has a size greater than zero.
6680 True if file descriptor @var{fd} is open and refers to a terminal.
6683 True if @var{file} exists and its set-user-id bit is set.
6686 True if @var{file} exists and is writable.
6689 True if @var{file} exists and is executable.
6692 True if @var{file} exists and is owned by the effective group id.
6695 True if @var{file} exists and is a symbolic link.
6698 True if @var{file} exists and has been modified since it was last read.
6701 True if @var{file} exists and is owned by the effective user id.
6704 True if @var{file} exists and is a socket.
6706 @item @var{file1} -ef @var{file2}
6707 True if @var{file1} and @var{file2} refer to the same device and
6710 @item @var{file1} -nt @var{file2}
6711 True if @var{file1} is newer (according to modification date)
6712 than @var{file2}, or if @var{file1} exists and @var{file2} does not.
6714 @item @var{file1} -ot @var{file2}
6715 True if @var{file1} is older than @var{file2},
6716 or if @var{file2} exists and @var{file1} does not.
6718 @item -o @var{optname}
6719 True if the shell option @var{optname} is enabled.
6720 The list of options appears in the description of the @option{-o}
6721 option to the @code{set} builtin (@pxref{The Set Builtin}).
6723 @item -v @var{varname}
6724 True if the shell variable @var{varname} is set (has been assigned a value).
6726 @item -R @var{varname}
6727 True if the shell variable @var{varname} is set and is a name reference.
6729 @item -z @var{string}
6730 True if the length of @var{string} is zero.
6732 @item -n @var{string}
6734 True if the length of @var{string} is non-zero.
6736 @item @var{string1} == @var{string2}
6737 @itemx @var{string1} = @var{string2}
6738 True if the strings are equal.
6739 When used with the @code{[[} command, this performs pattern matching as
6740 described above (@pxref{Conditional Constructs}).
6742 @samp{=} should be used with the @code{test} command for @sc{posix} conformance.
6744 @item @var{string1} != @var{string2}
6745 True if the strings are not equal.
6747 @item @var{string1} < @var{string2}
6748 True if @var{string1} sorts before @var{string2} lexicographically.
6750 @item @var{string1} > @var{string2}
6751 True if @var{string1} sorts after @var{string2} lexicographically.
6753 @item @var{arg1} OP @var{arg2}
6755 @samp{-eq}, @samp{-ne}, @samp{-lt}, @samp{-le}, @samp{-gt}, or @samp{-ge}.
6756 These arithmetic binary operators return true if @var{arg1}
6757 is equal to, not equal to, less than, less than or equal to,
6758 greater than, or greater than or equal to @var{arg2},
6759 respectively. @var{Arg1} and @var{arg2}
6760 may be positive or negative integers.
6763 @node Shell Arithmetic
6764 @section Shell Arithmetic
6765 @cindex arithmetic, shell
6766 @cindex shell arithmetic
6767 @cindex expressions, arithmetic
6768 @cindex evaluation, arithmetic
6769 @cindex arithmetic evaluation
6771 The shell allows arithmetic expressions to be evaluated, as one of
6772 the shell expansions or by using the @code{((} compound command, the
6773 @code{let} builtin, or the @option{-i} option to the @code{declare} builtin.
6775 Evaluation is done in fixed-width integers with no check for overflow,
6776 though division by 0 is trapped and flagged as an error.
6777 The operators and their precedence, associativity, and values
6778 are the same as in the C language.
6779 The following list of operators is grouped into levels of
6780 equal-precedence operators.
6781 The levels are listed in order of decreasing precedence.
6785 @item @var{id}++ @var{id}--
6786 variable post-increment and post-decrement
6788 @item ++@var{id} --@var{id}
6789 variable pre-increment and pre-decrement
6792 unary minus and plus
6795 logical and bitwise negation
6801 multiplication, division, remainder
6804 addition, subtraction
6807 left and right bitwise shifts
6813 equality and inequality
6819 bitwise exclusive OR
6830 @item expr ? expr : expr
6831 conditional operator
6833 @item = *= /= %= += -= <<= >>= &= ^= |=
6840 Shell variables are allowed as operands; parameter expansion is
6841 performed before the expression is evaluated.
6842 Within an expression, shell variables may also be referenced by name
6843 without using the parameter expansion syntax.
6844 A shell variable that is null or unset evaluates to 0 when referenced
6845 by name without using the parameter expansion syntax.
6846 The value of a variable is evaluated as an arithmetic expression
6847 when it is referenced, or when a variable which has been given the
6848 @var{integer} attribute using @samp{declare -i} is assigned a value.
6849 A null value evaluates to 0.
6850 A shell variable need not have its @var{integer} attribute turned on
6851 to be used in an expression.
6853 Constants with a leading 0 are interpreted as octal numbers.
6854 A leading @samp{0x} or @samp{0X} denotes hexadecimal. Otherwise,
6855 numbers take the form [@var{base}@code{#}]@var{n}, where the optional @var{base}
6856 is a decimal number between 2 and 64 representing the arithmetic
6857 base, and @var{n} is a number in that base.
6858 If @var{base}@code{#} is omitted, then base 10 is used.
6859 When specifying @var{n},
6860 the digits greater than 9 are represented by the lowercase letters,
6861 the uppercase letters, @samp{@@}, and @samp{_}, in that order.
6862 If @var{base} is less than or equal to 36, lowercase and uppercase
6863 letters may be used interchangeably to represent numbers between 10
6866 Operators are evaluated in order of precedence. Sub-expressions in
6867 parentheses are evaluated first and may override the precedence
6872 @cindex alias expansion
6874 @var{Aliases} allow a string to be substituted for a word when it is used
6875 as the first word of a simple command.
6876 The shell maintains a list of aliases that may be set and unset with
6877 the @code{alias} and @code{unalias} builtin commands.
6879 The first word of each simple command, if unquoted, is checked to see
6881 If so, that word is replaced by the text of the alias.
6882 The characters @samp{/}, @samp{$}, @samp{`}, @samp{=} and any of the
6883 shell metacharacters or quoting characters listed above may not appear
6885 The replacement text may contain any valid
6886 shell input, including shell metacharacters.
6887 The first word of the replacement text is tested for
6888 aliases, but a word that is identical to an alias being expanded
6889 is not expanded a second time.
6890 This means that one may alias @code{ls} to @code{"ls -F"},
6891 for instance, and Bash does not try to recursively expand the
6893 If the last character of the alias value is a
6894 @var{blank}, then the next command word following the
6895 alias is also checked for alias expansion.
6897 Aliases are created and listed with the @code{alias}
6898 command, and removed with the @code{unalias} command.
6900 There is no mechanism for using arguments in the replacement text,
6902 If arguments are needed, a shell function should be used
6903 (@pxref{Shell Functions}).
6905 Aliases are not expanded when the shell is not interactive,
6906 unless the @code{expand_aliases} shell option is set using
6907 @code{shopt} (@pxref{The Shopt Builtin}).
6909 The rules concerning the definition and use of aliases are
6910 somewhat confusing. Bash
6911 always reads at least one complete line
6912 of input before executing any
6913 of the commands on that line. Aliases are expanded when a
6914 command is read, not when it is executed. Therefore, an
6915 alias definition appearing on the same line as another
6916 command does not take effect until the next line of input is read.
6917 The commands following the alias definition
6918 on that line are not affected by the new alias.
6919 This behavior is also an issue when functions are executed.
6920 Aliases are expanded when a function definition is read,
6921 not when the function is executed, because a function definition
6922 is itself a command. As a consequence, aliases
6923 defined in a function are not available until after that
6924 function is executed. To be safe, always put
6925 alias definitions on a separate line, and do not use @code{alias}
6926 in compound commands.
6928 For almost every purpose, shell functions are preferred over aliases.
6934 Bash provides one-dimensional indexed and associative array variables.
6935 Any variable may be used as an indexed array;
6936 the @code{declare} builtin will explicitly declare an array.
6938 limit on the size of an array, nor any requirement that members
6939 be indexed or assigned contiguously.
6940 Indexed arrays are referenced using integers (including arithmetic
6941 expressions (@pxref{Shell Arithmetic})) and are zero-based;
6942 associative arrays use arbitrary strings.
6943 Unless otherwise noted, indexed array indices must be non-negative integers.
6945 An indexed array is created automatically if any variable is assigned to
6948 @var{name}[@var{subscript}]=@var{value}
6953 is treated as an arithmetic expression that must evaluate to a number.
6954 To explicitly declare an array, use
6956 declare -a @var{name}
6961 declare -a @var{name}[@var{subscript}]
6964 is also accepted; the @var{subscript} is ignored.
6967 Associative arrays are created using
6969 declare -A @var{name}.
6973 specified for an array variable using the @code{declare} and
6974 @code{readonly} builtins. Each attribute applies to all members of
6977 Arrays are assigned to using compound assignments of the form
6979 @var{name}=(@var{value1} @var{value2} @dots{} )
6983 @var{value} is of the form @code{[@var{subscript}]=}@var{string}.
6984 Indexed array assignments do not require anything but @var{string}.
6985 When assigning to indexed arrays, if
6986 the optional subscript is supplied, that index is assigned to;
6987 otherwise the index of the element assigned is the last index assigned
6988 to by the statement plus one. Indexing starts at zero.
6990 When assigning to an associative array, the subscript is required.
6992 This syntax is also accepted by the @code{declare}
6993 builtin. Individual array elements may be assigned to using the
6994 @code{@var{name}[@var{subscript}]=@var{value}} syntax introduced above.
6996 When assigning to an indexed array, if @var{name}
6997 is subscripted by a negative number, that number is
6998 interpreted as relative to one greater than the maximum index of
6999 @var{name}, so negative indices count back from the end of the
7000 array, and an index of -1 references the last element.
7002 Any element of an array may be referenced using
7003 @code{$@{@var{name}[@var{subscript}]@}}.
7004 The braces are required to avoid
7005 conflicts with the shell's filename expansion operators. If the
7006 @var{subscript} is @samp{@@} or @samp{*}, the word expands to all members
7007 of the array @var{name}. These subscripts differ only when the word
7008 appears within double quotes.
7009 If the word is double-quoted,
7010 @code{$@{@var{name}[*]@}} expands to a single word with
7011 the value of each array member separated by the first character of the
7012 @env{IFS} variable, and @code{$@{@var{name}[@@]@}} expands each element of
7013 @var{name} to a separate word. When there are no array members,
7014 @code{$@{@var{name}[@@]@}} expands to nothing.
7015 If the double-quoted expansion occurs within a word, the expansion of
7016 the first parameter is joined with the beginning part of the original
7017 word, and the expansion of the last parameter is joined with the last
7018 part of the original word.
7019 This is analogous to the
7020 expansion of the special parameters @samp{@@} and @samp{*}.
7021 @code{$@{#@var{name}[@var{subscript}]@}} expands to the length of
7022 @code{$@{@var{name}[@var{subscript}]@}}.
7023 If @var{subscript} is @samp{@@} or
7024 @samp{*}, the expansion is the number of elements in the array.
7025 If the @var{subscript}
7026 used to reference an element of an indexed array
7027 evaluates to a number less than zero, it is
7028 interpreted as relative to one greater than the maximum index of the array,
7029 so negative indices count back from the end of the array,
7030 and an index of -1 refers to the last element.
7032 Referencing an array variable without a subscript is equivalent to
7033 referencing with a subscript of 0.
7034 Any reference to a variable using a valid subscript is legal, and
7035 @code{bash} will create an array if necessary.
7037 An array variable is considered set if a subscript has been assigned a
7038 value. The null string is a valid value.
7040 It is possible to obtain the keys (indices) of an array as well as the values.
7041 $@{!@var{name}[@@]@} and $@{!@var{name}[*]@} expand to the indices
7042 assigned in array variable @var{name}.
7043 The treatment when in double quotes is similar to the expansion of the
7044 special parameters @samp{@@} and @samp{*} within double quotes.
7046 The @code{unset} builtin is used to destroy arrays.
7047 @code{unset @var{name}[@var{subscript}]}
7048 destroys the array element at index @var{subscript}.
7049 Negative subscripts to indexed arrays are interpreted as described above.
7050 Care must be taken to avoid unwanted side effects caused by filename
7052 @code{unset @var{name}}, where @var{name} is an array, removes the
7053 entire array. A subscript of @samp{*} or @samp{@@} also removes the
7056 The @code{declare}, @code{local}, and @code{readonly}
7057 builtins each accept a @option{-a} option to specify an indexed
7058 array and a @option{-A} option to specify an associative array.
7059 If both options are supplied, @option{-A} takes precedence.
7060 The @code{read} builtin accepts a @option{-a}
7061 option to assign a list of words read from the standard input
7062 to an array, and can read values from the standard input into
7063 individual array elements. The @code{set} and @code{declare}
7064 builtins display array values in a way that allows them to be
7067 @node The Directory Stack
7068 @section The Directory Stack
7069 @cindex directory stack
7072 * Directory Stack Builtins:: Bash builtin commands to manipulate
7073 the directory stack.
7076 The directory stack is a list of recently-visited directories. The
7077 @code{pushd} builtin adds directories to the stack as it changes
7078 the current directory, and the @code{popd} builtin removes specified
7079 directories from the stack and changes the current directory to
7080 the directory removed. The @code{dirs} builtin displays the contents
7081 of the directory stack. The current directory is always the "top"
7082 of the directory stack.
7084 The contents of the directory stack are also visible
7085 as the value of the @env{DIRSTACK} shell variable.
7087 @node Directory Stack Builtins
7088 @subsection Directory Stack Builtins
7095 dirs [-clpv] [+@var{N} | -@var{N}]
7098 Display the list of currently remembered directories. Directories
7099 are added to the list with the @code{pushd} command; the
7100 @code{popd} command removes directories from the list.
7101 The current directory is always the first directory in the stack.
7105 Clears the directory stack by deleting all of the elements.
7107 Produces a listing using full pathnames;
7108 the default listing format uses a tilde to denote the home directory.
7110 Causes @code{dirs} to print the directory stack with one entry per
7113 Causes @code{dirs} to print the directory stack with one entry per
7114 line, prefixing each entry with its index in the stack.
7116 Displays the @var{N}th directory (counting from the left of the
7117 list printed by @code{dirs} when invoked without options), starting
7120 Displays the @var{N}th directory (counting from the right of the
7121 list printed by @code{dirs} when invoked without options), starting
7128 popd [-n] [+@var{N} | -@var{N}]
7131 When no arguments are given, @code{popd}
7132 removes the top directory from the stack and
7133 performs a @code{cd} to the new top directory.
7134 The elements are numbered from 0 starting at the first directory
7135 listed with @code{dirs}; that is, @code{popd} is equivalent to @code{popd +0}.
7139 Suppresses the normal change of directory when removing directories
7140 from the stack, so that only the stack is manipulated.
7142 Removes the @var{N}th directory (counting from the left of the
7143 list printed by @code{dirs}), starting with zero.
7145 Removes the @var{N}th directory (counting from the right of the
7146 list printed by @code{dirs}), starting with zero.
7152 pushd [-n] [@var{+N} | @var{-N} | @var{dir}]
7155 Save the current directory on the top of the directory stack
7156 and then @code{cd} to @var{dir}.
7157 With no arguments, @code{pushd} exchanges the top two directories
7158 and makes the new top the current directory.
7162 Suppresses the normal change of directory when rotating or
7163 adding directories to the stack, so that only the stack is manipulated.
7165 Brings the @var{N}th directory (counting from the left of the
7166 list printed by @code{dirs}, starting with zero) to the top of
7167 the list by rotating the stack.
7169 Brings the @var{N}th directory (counting from the right of the
7170 list printed by @code{dirs}, starting with zero) to the top of
7171 the list by rotating the stack.
7173 Makes @var{dir} be the top of the stack, making
7174 it the new current directory as if it had been supplied as an argument
7175 to the @code{cd} builtin.
7179 @node Controlling the Prompt
7180 @section Controlling the Prompt
7183 The value of the variable @env{PROMPT_COMMAND} is examined just before
7184 Bash prints each primary prompt. If @env{PROMPT_COMMAND} is set and
7185 has a non-null value, then the
7186 value is executed just as if it had been typed on the command line.
7188 In addition, the following table describes the special characters which
7189 can appear in the prompt variables @env{PS1} to @env{PS4}:
7195 The date, in "Weekday Month Date" format (e.g., "Tue May 26").
7196 @item \D@{@var{format}@}
7197 The @var{format} is passed to @code{strftime}(3) and the result is inserted
7198 into the prompt string; an empty @var{format} results in a locale-specific
7199 time representation. The braces are required.
7201 An escape character.
7203 The hostname, up to the first `.'.
7207 The number of jobs currently managed by the shell.
7209 The basename of the shell's terminal device name.
7215 The name of the shell, the basename of @code{$0} (the portion
7216 following the final slash).
7218 The time, in 24-hour HH:MM:SS format.
7220 The time, in 12-hour HH:MM:SS format.
7222 The time, in 12-hour am/pm format.
7224 The time, in 24-hour HH:MM format.
7226 The username of the current user.
7228 The version of Bash (e.g., 2.00)
7230 The release of Bash, version + patchlevel (e.g., 2.00.0)
7232 The current working directory, with @env{$HOME} abbreviated with a tilde
7233 (uses the @env{$PROMPT_DIRTRIM} variable).
7235 The basename of @env{$PWD}, with @env{$HOME} abbreviated with a tilde.
7237 The history number of this command.
7239 The command number of this command.
7241 If the effective uid is 0, @code{#}, otherwise @code{$}.
7243 The character whose ASCII code is the octal value @var{nnn}.
7247 Begin a sequence of non-printing characters. This could be used to
7248 embed a terminal control sequence into the prompt.
7250 End a sequence of non-printing characters.
7253 The command number and the history number are usually different:
7254 the history number of a command is its position in the history
7255 list, which may include commands restored from the history file
7256 (@pxref{Bash History Facilities}), while the command number is
7257 the position in the sequence of commands executed during the current
7260 After the string is decoded, it is expanded via
7261 parameter expansion, command substitution, arithmetic
7262 expansion, and quote removal, subject to the value of the
7263 @code{promptvars} shell option (@pxref{Bash Builtins}).
7265 @node The Restricted Shell
7266 @section The Restricted Shell
7267 @cindex restricted shell
7269 If Bash is started with the name @code{rbash}, or the
7270 @option{--restricted}
7273 option is supplied at invocation, the shell becomes restricted.
7274 A restricted shell is used to
7275 set up an environment more controlled than the standard shell.
7276 A restricted shell behaves identically to @code{bash}
7277 with the exception that the following are disallowed or not performed:
7281 Changing directories with the @code{cd} builtin.
7283 Setting or unsetting the values of the @env{SHELL}, @env{PATH},
7284 @env{ENV}, or @env{BASH_ENV} variables.
7286 Specifying command names containing slashes.
7288 Specifying a filename containing a slash as an argument to the @code{.}
7291 Specifying a filename containing a slash as an argument to the @option{-p}
7292 option to the @code{hash} builtin command.
7294 Importing function definitions from the shell environment at startup.
7296 Parsing the value of @env{SHELLOPTS} from the shell environment at startup.
7298 Redirecting output using the @samp{>}, @samp{>|}, @samp{<>}, @samp{>&},
7299 @samp{&>}, and @samp{>>} redirection operators.
7301 Using the @code{exec} builtin to replace the shell with another command.
7303 Adding or deleting builtin commands with the
7304 @option{-f} and @option{-d} options to the @code{enable} builtin.
7306 Using the @code{enable} builtin command to enable disabled shell builtins.
7308 Specifying the @option{-p} option to the @code{command} builtin.
7310 Turning off restricted mode with @samp{set +r} or @samp{set +o restricted}.
7313 These restrictions are enforced after any startup files are read.
7315 When a command that is found to be a shell script is executed
7316 (@pxref{Shell Scripts}), @code{rbash} turns off any restrictions in
7317 the shell spawned to execute the script.
7319 @node Bash POSIX Mode
7320 @section Bash POSIX Mode
7323 Starting Bash with the @option{--posix} command-line option or executing
7324 @samp{set -o posix} while Bash is running will cause Bash to conform more
7325 closely to the @sc{posix} standard by changing the behavior to
7326 match that specified by @sc{posix} in areas where the Bash default differs.
7328 When invoked as @code{sh}, Bash enters @sc{posix} mode after reading the
7331 The following list is what's changed when `@sc{posix} mode' is in effect:
7335 When a command in the hash table no longer exists, Bash will re-search
7336 @env{$PATH} to find the new location. This is also available with
7337 @samp{shopt -s checkhash}.
7340 The message printed by the job control code and builtins when a job
7341 exits with a non-zero status is `Done(status)'.
7344 The message printed by the job control code and builtins when a job
7345 is stopped is `Stopped(@var{signame})', where @var{signame} is, for
7346 example, @code{SIGTSTP}.
7349 Alias expansion is always enabled, even in non-interactive shells.
7352 Reserved words appearing in a context where reserved words are recognized
7353 do not undergo alias expansion.
7356 The @sc{posix} @env{PS1} and @env{PS2} expansions of @samp{!} to
7357 the history number and @samp{!!} to @samp{!} are enabled,
7358 and parameter expansion is performed on the values of @env{PS1} and
7359 @env{PS2} regardless of the setting of the @code{promptvars} option.
7362 The @sc{posix} startup files are executed (@env{$ENV}) rather than
7363 the normal Bash files.
7366 Tilde expansion is only performed on assignments preceding a command
7367 name, rather than on all assignment statements on the line.
7370 The default history file is @file{~/.sh_history} (this is the
7371 default value of @env{$HISTFILE}).
7374 Redirection operators do not perform filename expansion on the word
7375 in the redirection unless the shell is interactive.
7378 Redirection operators do not perform word splitting on the word in the
7382 Function names must be valid shell @code{name}s. That is, they may not
7383 contain characters other than letters, digits, and underscores, and
7384 may not start with a digit. Declaring a function with an invalid name
7385 causes a fatal syntax error in non-interactive shells.
7388 Function names may not be the same as one of the @sc{posix} special
7392 @sc{posix} special builtins are found before shell functions
7393 during command lookup.
7396 When printing shell function definitions (e.g., by @code{type}), Bash does
7397 not print the @code{function} keyword.
7400 Literal tildes that appear as the first character in elements of
7401 the @env{PATH} variable are not expanded as described above
7402 under @ref{Tilde Expansion}.
7405 The @code{time} reserved word may be used by itself as a command. When
7406 used in this way, it displays timing statistics for the shell and its
7407 completed children. The @env{TIMEFORMAT} variable controls the format
7408 of the timing information.
7411 When parsing and expanding a $@{@dots{}@} expansion that appears within
7412 double quotes, single quotes are no longer special and cannot be used to
7413 quote a closing brace or other special character, unless the operator is
7414 one of those defined to perform pattern removal. In this case, they do
7415 not have to appear as matched pairs.
7418 The parser does not recognize @code{time} as a reserved word if the next
7419 token begins with a @samp{-}.
7422 The @samp{!} character does not introduce history expansion within a
7423 double-quoted string, even if the @code{histexpand} option is enabled.
7426 If a @sc{posix} special builtin returns an error status, a
7427 non-interactive shell exits. The fatal errors are those listed in
7428 the @sc{posix} standard, and include things like passing incorrect options,
7429 redirection errors, variable assignment errors for assignments preceding
7430 the command name, and so on.
7433 A non-interactive shell exits with an error status if a variable
7434 assignment error occurs when no command name follows the assignment
7436 A variable assignment error occurs, for example, when trying to assign
7437 a value to a readonly variable.
7440 A non-interactive shell exits with an error status if a variable
7441 assignment error occurs in an assignment statement preceding a special
7442 builtin, but not with any other simple command.
7445 A non-interactive shell exits with an error status if the iteration
7446 variable in a @code{for} statement or the selection variable in a
7447 @code{select} statement is a readonly variable.
7450 Non-interactive shells exit if @var{filename} in @code{.} @var{filename}
7454 Non-interactive shells exit if a syntax error in an arithmetic expansion
7455 results in an invalid expression.
7458 Non-interactive shells exit if a parameter expansion error occurs.
7461 Non-interactive shells exit if there is a syntax error in a script read
7462 with the @code{.} or @code{source} builtins, or in a string processed by
7463 the @code{eval} builtin.
7466 Process substitution is not available.
7469 While variable indirection is available, it may not be applied to the
7470 @samp{#} and @samp{?} special parameters.
7473 When expanding the @samp{*} special parameter in a pattern context where the
7474 expansion is double-quoted does not treat the @code{$*} as if it were
7478 Assignment statements preceding @sc{posix} special builtins
7479 persist in the shell environment after the builtin completes.
7482 Assignment statements preceding shell function calls persist in the
7483 shell environment after the function returns, as if a @sc{posix}
7484 special builtin command had been executed.
7487 The @code{command} builtin does not prevent builtins that take assignment
7488 statements as arguments from expanding them as assignment statements;
7489 when not in @sc{posix} mode, assignment builtins lose their assignment
7490 statement expansion properties when preceded by @code{command}.
7493 The @code{bg} builtin uses the required format to describe each job placed
7494 in the background, which does not include an indication of whether the job
7495 is the current or previous job.
7498 The output of @samp{kill -l} prints all the signal names on a single line,
7499 separated by spaces, without the @samp{SIG} prefix.
7502 The @code{kill} builtin does not accept signal names with a @samp{SIG}
7506 The @code{export} and @code{readonly} builtin commands display their
7507 output in the format required by @sc{posix}.
7510 The @code{trap} builtin displays signal names without the leading
7514 The @code{trap} builtin doesn't check the first argument for a possible
7515 signal specification and revert the signal handling to the original
7516 disposition if it is, unless that argument consists solely of digits and
7517 is a valid signal number. If users want to reset the handler for a given
7518 signal to the original disposition, they should use @samp{-} as the
7522 The @code{.} and @code{source} builtins do not search the current directory
7523 for the filename argument if it is not found by searching @env{PATH}.
7526 Enabling @sc{posix} mode has the effect of setting the
7527 @code{inherit_errexit} option, so
7528 subshells spawned to execute command substitutions inherit the value of
7529 the @option{-e} option from the parent shell.
7530 When the @code{inherit_errexit} option is not enabled,
7531 Bash clears the @option{-e} option in such subshells.
7534 When the @code{alias} builtin displays alias definitions, it does not
7535 display them with a leading @samp{alias } unless the @option{-p} option
7539 When the @code{set} builtin is invoked without options, it does not display
7540 shell function names and definitions.
7543 When the @code{set} builtin is invoked without options, it displays
7544 variable values without quotes, unless they contain shell metacharacters,
7545 even if the result contains nonprinting characters.
7548 When the @code{cd} builtin is invoked in @var{logical} mode, and the pathname
7549 constructed from @code{$PWD} and the directory name supplied as an argument
7550 does not refer to an existing directory, @code{cd} will fail instead of
7551 falling back to @var{physical} mode.
7554 The @code{pwd} builtin verifies that the value it prints is the same as the
7555 current directory, even if it is not asked to check the file system with the
7559 When listing the history, the @code{fc} builtin does not include an
7560 indication of whether or not a history entry has been modified.
7563 The default editor used by @code{fc} is @code{ed}.
7566 The @code{type} and @code{command} builtins will not report a non-executable
7567 file as having been found, though the shell will attempt to execute such a
7568 file if it is the only so-named file found in @code{$PATH}.
7571 The @code{vi} editing mode will invoke the @code{vi} editor directly when
7572 the @samp{v} command is run, instead of checking @code{$VISUAL} and
7576 When the @code{xpg_echo} option is enabled, Bash does not attempt to interpret
7577 any arguments to @code{echo} as options. Each argument is displayed, after
7578 escape characters are converted.
7581 The @code{ulimit} builtin uses a block size of 512 bytes for the @option{-c}
7582 and @option{-f} options.
7585 The arrival of @code{SIGCHLD} when a trap is set on @code{SIGCHLD} does
7586 not interrupt the @code{wait} builtin and cause it to return immediately.
7587 The trap command is run once for each child that exits.
7590 The @code{read} builtin may be interrupted by a signal for which a trap
7592 If Bash receives a trapped signal while executing @code{read}, the trap
7593 handler executes and @code{read} returns an exit status greater than 128.
7596 Bash removes an exited background process's status from the list of such
7597 statuses after the @code{wait} builtin is used to obtain it.
7601 There is other @sc{posix} behavior that Bash does not implement by
7602 default even when in @sc{posix} mode.
7608 The @code{fc} builtin checks @code{$EDITOR} as a program to edit history
7609 entries if @code{FCEDIT} is unset, rather than defaulting directly to
7610 @code{ed}. @code{fc} uses @code{ed} if @code{EDITOR} is unset.
7613 As noted above, Bash requires the @code{xpg_echo} option to be enabled for
7614 the @code{echo} builtin to be fully conformant.
7618 Bash can be configured to be @sc{posix}-conformant by default, by specifying
7619 the @option{--enable-strict-posix-default} to @code{configure} when building
7620 (@pxref{Optional Features}).
7623 @chapter Job Control
7625 This chapter discusses what job control is, how it works, and how
7626 Bash allows you to access its facilities.
7629 * Job Control Basics:: How job control works.
7630 * Job Control Builtins:: Bash builtin commands used to interact
7632 * Job Control Variables:: Variables Bash uses to customize job
7636 @node Job Control Basics
7637 @section Job Control Basics
7641 @cindex suspending jobs
7644 refers to the ability to selectively stop (suspend)
7645 the execution of processes and continue (resume)
7646 their execution at a later point. A user typically employs
7647 this facility via an interactive interface supplied jointly
7648 by the operating system kernel's terminal driver and Bash.
7650 The shell associates a @var{job} with each pipeline. It keeps a
7651 table of currently executing jobs, which may be listed with the
7652 @code{jobs} command. When Bash starts a job
7653 asynchronously, it prints a line that looks
7659 indicating that this job is job number 1 and that the process @sc{id}
7660 of the last process in the pipeline associated with this job is
7661 25647. All of the processes in a single pipeline are members of
7662 the same job. Bash uses the @var{job} abstraction as the
7663 basis for job control.
7665 To facilitate the implementation of the user interface to job
7666 control, the operating system maintains the notion of a current terminal
7667 process group @sc{id}. Members of this process group (processes whose
7668 process group @sc{id} is equal to the current terminal process group
7669 @sc{id}) receive keyboard-generated signals such as @code{SIGINT}.
7670 These processes are said to be in the foreground. Background
7671 processes are those whose process group @sc{id} differs from the
7672 terminal's; such processes are immune to keyboard-generated
7673 signals. Only foreground processes are allowed to read from or, if
7674 the user so specifies with @code{stty tostop}, write to the terminal.
7675 Background processes which attempt to
7676 read from (write to when @code{stty tostop} is in effect) the
7677 terminal are sent a @code{SIGTTIN} (@code{SIGTTOU})
7678 signal by the kernel's terminal driver,
7679 which, unless caught, suspends the process.
7681 If the operating system on which Bash is running supports
7682 job control, Bash contains facilities to use it. Typing the
7683 @var{suspend} character (typically @samp{^Z}, Control-Z) while a
7684 process is running causes that process to be stopped and returns
7685 control to Bash. Typing the @var{delayed suspend} character
7686 (typically @samp{^Y}, Control-Y) causes the process to be stopped
7687 when it attempts to read input from the terminal, and control to
7688 be returned to Bash. The user then manipulates the state of
7689 this job, using the @code{bg} command to continue it in the
7690 background, the @code{fg} command to continue it in the
7691 foreground, or the @code{kill} command to kill it. A @samp{^Z}
7692 takes effect immediately, and has the additional side effect of
7693 causing pending output and typeahead to be discarded.
7695 There are a number of ways to refer to a job in the shell. The
7696 character @samp{%} introduces a job specification (@var{jobspec}).
7698 Job number @code{n} may be referred to as @samp{%n}.
7699 The symbols @samp{%%} and @samp{%+} refer to the shell's notion of the
7700 current job, which is the last job stopped while it was in the foreground
7701 or started in the background.
7702 A single @samp{%} (with no accompanying job specification) also refers
7704 The previous job may be referenced using @samp{%-}.
7705 If there is only a single job, @samp{%+} and @samp{%-} can both be used
7706 to refer to that job.
7707 In output pertaining to jobs (e.g., the output of the @code{jobs}
7708 command), the current job is always flagged with a @samp{+}, and the
7709 previous job with a @samp{-}.
7711 A job may also be referred to
7712 using a prefix of the name used to start it, or using a substring
7713 that appears in its command line. For example, @samp{%ce} refers
7714 to a stopped @code{ce} job. Using @samp{%?ce}, on the
7715 other hand, refers to any job containing the string @samp{ce} in
7716 its command line. If the prefix or substring matches more than one job,
7717 Bash reports an error.
7719 Simply naming a job can be used to bring it into the foreground:
7720 @samp{%1} is a synonym for @samp{fg %1}, bringing job 1 from the
7721 background into the foreground. Similarly, @samp{%1 &} resumes
7722 job 1 in the background, equivalent to @samp{bg %1}
7724 The shell learns immediately whenever a job changes state.
7725 Normally, Bash waits until it is about to print a prompt
7726 before reporting changes in a job's status so as to not interrupt
7728 If the @option{-b} option to the @code{set} builtin is enabled,
7729 Bash reports such changes immediately (@pxref{The Set Builtin}).
7730 Any trap on @code{SIGCHLD} is executed for each child process
7733 If an attempt to exit Bash is made while jobs are stopped, (or running, if
7734 the @code{checkjobs} option is enabled -- see @ref{The Shopt Builtin}), the
7735 shell prints a warning message, and if the @code{checkjobs} option is
7736 enabled, lists the jobs and their statuses.
7737 The @code{jobs} command may then be used to inspect their status.
7738 If a second attempt to exit is made without an intervening command,
7739 Bash does not print another warning, and any stopped jobs are terminated.
7741 @node Job Control Builtins
7742 @section Job Control Builtins
7749 bg [@var{jobspec} @dots{}]
7752 Resume each suspended job @var{jobspec} in the background, as if it
7753 had been started with @samp{&}.
7754 If @var{jobspec} is not supplied, the current job is used.
7755 The return status is zero unless it is run when job control is not
7756 enabled, or, when run with job control enabled, any
7757 @var{jobspec} was not found or specifies a job
7758 that was started without job control.
7766 Resume the job @var{jobspec} in the foreground and make it the current job.
7767 If @var{jobspec} is not supplied, the current job is used.
7768 The return status is that of the command placed into the foreground,
7769 or non-zero if run when job control is disabled or, when run with
7770 job control enabled, @var{jobspec} does not specify a valid job or
7771 @var{jobspec} specifies a job that was started without job control.
7776 jobs [-lnprs] [@var{jobspec}]
7777 jobs -x @var{command} [@var{arguments}]
7780 The first form lists the active jobs. The options have the
7785 List process @sc{id}s in addition to the normal information.
7788 Display information only about jobs that have changed status since
7789 the user was last notified of their status.
7792 List only the process @sc{id} of the job's process group leader.
7795 Display only running jobs.
7798 Display only stopped jobs.
7801 If @var{jobspec} is given,
7802 output is restricted to information about that job.
7803 If @var{jobspec} is not supplied, the status of all jobs is
7806 If the @option{-x} option is supplied, @code{jobs} replaces any
7807 @var{jobspec} found in @var{command} or @var{arguments} with the
7808 corresponding process group @sc{id}, and executes @var{command},
7809 passing it @var{argument}s, returning its exit status.
7814 kill [-s @var{sigspec}] [-n @var{signum}] [-@var{sigspec}] @var{jobspec} or @var{pid}
7815 kill -l|-L [@var{exit_status}]
7818 Send a signal specified by @var{sigspec} or @var{signum} to the process
7819 named by job specification @var{jobspec} or process @sc{id} @var{pid}.
7820 @var{sigspec} is either a case-insensitive signal name such as
7821 @code{SIGINT} (with or without the @code{SIG} prefix)
7822 or a signal number; @var{signum} is a signal number.
7823 If @var{sigspec} and @var{signum} are not present, @code{SIGTERM} is used.
7824 The @option{-l} option lists the signal names.
7825 If any arguments are supplied when @option{-l} is given, the names of the
7826 signals corresponding to the arguments are listed, and the return status
7828 @var{exit_status} is a number specifying a signal number or the exit
7829 status of a process terminated by a signal.
7830 The @option{-L} option is equivalent to @option{-l}.
7831 The return status is zero if at least one signal was successfully sent,
7832 or non-zero if an error occurs or an invalid option is encountered.
7837 wait [-n] [@var{jobspec} or @var{pid} @dots{}]
7840 Wait until the child process specified by each process @sc{id} @var{pid}
7841 or job specification @var{jobspec} exits and return the exit status of the
7842 last command waited for.
7843 If a job spec is given, all processes in the job are waited for.
7844 If no arguments are given, all currently active child processes are
7845 waited for, and the return status is zero.
7846 If the @option{-n} option is supplied, @code{wait} waits for any job to
7847 terminate and returns its exit status.
7848 If neither @var{jobspec} nor @var{pid} specifies an active child process
7849 of the shell, the return status is 127.
7854 disown [-ar] [-h] [@var{jobspec} @dots{} | @var{pid} @dots{} ]
7857 Without options, remove each @var{jobspec} from the table of
7859 If the @option{-h} option is given, the job is not removed from the table,
7860 but is marked so that @code{SIGHUP} is not sent to the job if the shell
7861 receives a @code{SIGHUP}.
7862 If @var{jobspec} is not present, and neither the @option{-a} nor the
7863 @option{-r} option is supplied, the current job is used.
7864 If no @var{jobspec} is supplied, the @option{-a} option means to remove or
7865 mark all jobs; the @option{-r} option without a @var{jobspec}
7866 argument restricts operation to running jobs.
7874 Suspend the execution of this shell until it receives a
7875 @code{SIGCONT} signal.
7876 A login shell cannot be suspended; the @option{-f}
7877 option can be used to override this and force the suspension.
7880 When job control is not active, the @code{kill} and @code{wait}
7881 builtins do not accept @var{jobspec} arguments. They must be
7882 supplied process @sc{id}s.
7884 @node Job Control Variables
7885 @section Job Control Variables
7890 This variable controls how the shell interacts with the user and
7891 job control. If this variable exists then single word simple
7892 commands without redirections are treated as candidates for resumption
7893 of an existing job. There is no ambiguity allowed; if there is
7894 more than one job beginning with the string typed, then
7895 the most recently accessed job will be selected.
7896 The name of a stopped job, in this context, is the command line
7897 used to start it. If this variable is set to the value @samp{exact},
7898 the string supplied must match the name of a stopped job exactly;
7899 if set to @samp{substring},
7900 the string supplied needs to match a substring of the name of a
7901 stopped job. The @samp{substring} value provides functionality
7902 analogous to the @samp{%?} job @sc{id} (@pxref{Job Control Basics}).
7903 If set to any other value, the supplied string must
7904 be a prefix of a stopped job's name; this provides functionality
7905 analogous to the @samp{%} job @sc{id}.
7909 @set readline-appendix
7910 @set history-appendix
7911 @cindex Readline, how to use
7912 @include rluser.texi
7913 @cindex History, how to use
7914 @include hsuser.texi
7915 @clear readline-appendix
7916 @clear history-appendix
7918 @node Installing Bash
7919 @chapter Installing Bash
7921 This chapter provides basic instructions for installing Bash on
7922 the various supported platforms. The distribution supports the
7923 @sc{gnu} operating systems, nearly every version of Unix, and several
7924 non-Unix systems such as BeOS and Interix.
7925 Other independent ports exist for
7926 @sc{ms-dos}, @sc{os/2}, and Windows platforms.
7929 * Basic Installation:: Installation instructions.
7930 * Compilers and Options:: How to set special options for various
7932 * Compiling For Multiple Architectures:: How to compile Bash for more
7933 than one kind of system from
7934 the same source tree.
7935 * Installation Names:: How to set the various paths used by the installation.
7936 * Specifying the System Type:: How to configure Bash for a particular system.
7937 * Sharing Defaults:: How to share default configuration values among GNU
7939 * Operation Controls:: Options recognized by the configuration program.
7940 * Optional Features:: How to enable and disable optional features when
7944 @node Basic Installation
7945 @section Basic Installation
7946 @cindex installation
7947 @cindex configuration
7948 @cindex Bash installation
7949 @cindex Bash configuration
7951 These are installation instructions for Bash.
7953 The simplest way to compile Bash is:
7957 @code{cd} to the directory containing the source code and type
7958 @samp{./configure} to configure Bash for your system. If you're
7959 using @code{csh} on an old version of System V, you might need to
7960 type @samp{sh ./configure} instead to prevent @code{csh} from trying
7961 to execute @code{configure} itself.
7963 Running @code{configure} takes some time.
7964 While running, it prints messages telling which features it is
7968 Type @samp{make} to compile Bash and build the @code{bashbug} bug
7972 Optionally, type @samp{make tests} to run the Bash test suite.
7975 Type @samp{make install} to install @code{bash} and @code{bashbug}.
7976 This will also install the manual pages and Info file.
7980 The @code{configure} shell script attempts to guess correct
7981 values for various system-dependent variables used during
7982 compilation. It uses those values to create a @file{Makefile} in
7983 each directory of the package (the top directory, the
7984 @file{builtins}, @file{doc}, and @file{support} directories,
7985 each directory under @file{lib}, and several others). It also creates a
7986 @file{config.h} file containing system-dependent definitions.
7987 Finally, it creates a shell script named @code{config.status} that you
7988 can run in the future to recreate the current configuration, a
7989 file @file{config.cache} that saves the results of its tests to
7990 speed up reconfiguring, and a file @file{config.log} containing
7991 compiler output (useful mainly for debugging @code{configure}).
7993 @file{config.cache} contains results you don't want to keep, you
7994 may remove or edit it.
7996 To find out more about the options and arguments that the
7997 @code{configure} script understands, type
8000 bash-2.04$ ./configure --help
8004 at the Bash prompt in your Bash source directory.
8006 If you need to do unusual things to compile Bash, please
8007 try to figure out how @code{configure} could check whether or not
8008 to do them, and mail diffs or instructions to
8009 @email{bash-maintainers@@gnu.org} so they can be
8010 considered for the next release.
8012 The file @file{configure.ac} is used to create @code{configure}
8013 by a program called Autoconf. You only need
8014 @file{configure.ac} if you want to change it or regenerate
8015 @code{configure} using a newer version of Autoconf. If
8016 you do this, make sure you are using Autoconf version 2.50 or
8019 You can remove the program binaries and object files from the
8020 source code directory by typing @samp{make clean}. To also remove the
8021 files that @code{configure} created (so you can compile Bash for
8022 a different kind of computer), type @samp{make distclean}.
8024 @node Compilers and Options
8025 @section Compilers and Options
8027 Some systems require unusual options for compilation or linking
8028 that the @code{configure} script does not know about. You can
8029 give @code{configure} initial values for variables by setting
8030 them in the environment. Using a Bourne-compatible shell, you
8031 can do that on the command line like this:
8034 CC=c89 CFLAGS=-O2 LIBS=-lposix ./configure
8037 On systems that have the @code{env} program, you can do it like this:
8040 env CPPFLAGS=-I/usr/local/include LDFLAGS=-s ./configure
8043 The configuration process uses GCC to build Bash if it
8046 @node Compiling For Multiple Architectures
8047 @section Compiling For Multiple Architectures
8049 You can compile Bash for more than one kind of computer at the
8050 same time, by placing the object files for each architecture in their
8051 own directory. To do this, you must use a version of @code{make} that
8052 supports the @code{VPATH} variable, such as GNU @code{make}.
8054 directory where you want the object files and executables to go and run
8055 the @code{configure} script from the source directory. You may need to
8056 supply the @option{--srcdir=PATH} argument to tell @code{configure} where the
8057 source files are. @code{configure} automatically checks for the
8058 source code in the directory that @code{configure} is in and in `..'.
8060 If you have to use a @code{make} that does not supports the @code{VPATH}
8061 variable, you can compile Bash for one architecture at a
8062 time in the source code directory. After you have installed
8063 Bash for one architecture, use @samp{make distclean} before
8064 reconfiguring for another architecture.
8066 Alternatively, if your system supports symbolic links, you can use the
8067 @file{support/mkclone} script to create a build tree which has
8068 symbolic links back to each file in the source directory. Here's an
8069 example that creates a build directory in the current directory from a
8070 source directory @file{/usr/gnu/src/bash-2.0}:
8073 bash /usr/gnu/src/bash-2.0/support/mkclone -s /usr/gnu/src/bash-2.0 .
8077 The @code{mkclone} script requires Bash, so you must have already built
8078 Bash for at least one architecture before you can create build
8079 directories for other architectures.
8081 @node Installation Names
8082 @section Installation Names
8084 By default, @samp{make install} will install into
8085 @file{/usr/local/bin}, @file{/usr/local/man}, etc. You can
8086 specify an installation prefix other than @file{/usr/local} by
8087 giving @code{configure} the option @option{--prefix=@var{PATH}},
8088 or by specifying a value for the @code{DESTDIR} @samp{make}
8089 variable when running @samp{make install}.
8091 You can specify separate installation prefixes for
8092 architecture-specific files and architecture-independent files.
8093 If you give @code{configure} the option
8094 @option{--exec-prefix=@var{PATH}}, @samp{make install} will use
8095 @var{PATH} as the prefix for installing programs and libraries.
8096 Documentation and other data files will still use the regular prefix.
8098 @node Specifying the System Type
8099 @section Specifying the System Type
8101 There may be some features @code{configure} can not figure out
8102 automatically, but need to determine by the type of host Bash
8103 will run on. Usually @code{configure} can figure that
8104 out, but if it prints a message saying it can not guess the host
8105 type, give it the @option{--host=TYPE} option. @samp{TYPE} can
8106 either be a short name for the system type, such as @samp{sun4},
8107 or a canonical name with three fields: @samp{CPU-COMPANY-SYSTEM}
8108 (e.g., @samp{i386-unknown-freebsd4.2}).
8110 See the file @file{support/config.sub} for the possible
8111 values of each field.
8113 @node Sharing Defaults
8114 @section Sharing Defaults
8116 If you want to set default values for @code{configure} scripts to
8117 share, you can create a site shell script called
8118 @code{config.site} that gives default values for variables like
8119 @code{CC}, @code{cache_file}, and @code{prefix}. @code{configure}
8120 looks for @file{PREFIX/share/config.site} if it exists, then
8121 @file{PREFIX/etc/config.site} if it exists. Or, you can set the
8122 @code{CONFIG_SITE} environment variable to the location of the site
8123 script. A warning: the Bash @code{configure} looks for a site script,
8124 but not all @code{configure} scripts do.
8126 @node Operation Controls
8127 @section Operation Controls
8129 @code{configure} recognizes the following options to control how it
8134 @item --cache-file=@var{file}
8135 Use and save the results of the tests in
8136 @var{file} instead of @file{./config.cache}. Set @var{file} to
8137 @file{/dev/null} to disable caching, for debugging
8141 Print a summary of the options to @code{configure}, and exit.
8146 Do not print messages saying which checks are being made.
8148 @item --srcdir=@var{dir}
8149 Look for the Bash source code in directory @var{dir}. Usually
8150 @code{configure} can determine that directory automatically.
8153 Print the version of Autoconf used to generate the @code{configure}
8157 @code{configure} also accepts some other, not widely used, boilerplate
8158 options. @samp{configure --help} prints the complete list.
8160 @node Optional Features
8161 @section Optional Features
8163 The Bash @code{configure} has a number of @option{--enable-@var{feature}}
8164 options, where @var{feature} indicates an optional part of Bash.
8165 There are also several @option{--with-@var{package}} options,
8166 where @var{package} is something like @samp{bash-malloc} or @samp{purify}.
8167 To turn off the default use of a package, use
8168 @option{--without-@var{package}}. To configure Bash without a feature
8169 that is enabled by default, use @option{--disable-@var{feature}}.
8171 Here is a complete list of the @option{--enable-} and
8172 @option{--with-} options that the Bash @code{configure} recognizes.
8176 Define if you are using the Andrew File System from Transarc.
8178 @item --with-bash-malloc
8179 Use the Bash version of
8180 @code{malloc} in the directory @file{lib/malloc}. This is not the same
8181 @code{malloc} that appears in @sc{gnu} libc, but an older version
8182 originally derived from the 4.2 @sc{bsd} @code{malloc}. This @code{malloc}
8183 is very fast, but wastes some space on each allocation.
8184 This option is enabled by default.
8185 The @file{NOTES} file contains a list of systems for
8186 which this should be turned off, and @code{configure} disables this
8187 option automatically for a number of systems.
8190 Use the curses library instead of the termcap library. This should
8191 be supplied if your system has an inadequate or incomplete termcap
8194 @item --with-gnu-malloc
8195 A synonym for @code{--with-bash-malloc}.
8197 @item --with-installed-readline[=@var{PREFIX}]
8198 Define this to make Bash link with a locally-installed version of Readline
8199 rather than the version in @file{lib/readline}. This works only with
8200 Readline 5.0 and later versions. If @var{PREFIX} is @code{yes} or not
8201 supplied, @code{configure} uses the values of the make variables
8202 @code{includedir} and @code{libdir}, which are subdirectories of @code{prefix}
8203 by default, to find the installed version of Readline if it is not in
8204 the standard system include and library directories.
8205 If @var{PREFIX} is @code{no}, Bash links with the version in
8206 @file{lib/readline}.
8207 If @var{PREFIX} is set to any other value, @code{configure} treats it as
8208 a directory pathname and looks for
8209 the installed version of Readline in subdirectories of that directory
8210 (include files in @var{PREFIX}/@code{include} and the library in
8211 @var{PREFIX}/@code{lib}).
8214 Define this to use the Purify memory allocation checker from Rational
8217 @item --enable-minimal-config
8218 This produces a shell with minimal features, close to the historical
8222 There are several @option{--enable-} options that alter how Bash is
8223 compiled and linked, rather than changing run-time features.
8226 @item --enable-largefile
8227 Enable support for @uref{http://www.sas.com/standards/large_file/x_open.20Mar96.html,
8228 large files} if the operating system requires special compiler options
8229 to build programs which can access large files. This is enabled by
8230 default, if the operating system provides large file support.
8232 @item --enable-profiling
8233 This builds a Bash binary that produces profiling information to be
8234 processed by @code{gprof} each time it is executed.
8236 @item --enable-static-link
8237 This causes Bash to be linked statically, if @code{gcc} is being used.
8238 This could be used to build a version to use as root's shell.
8241 The @samp{minimal-config} option can be used to disable all of
8242 the following options, but it is processed first, so individual
8243 options may be enabled using @samp{enable-@var{feature}}.
8245 All of the following options except for @samp{disabled-builtins},
8246 @samp{direxpand-default}, and
8247 @samp{xpg-echo-default} are
8248 enabled by default, unless the operating system does not provide the
8252 @item --enable-alias
8253 Allow alias expansion and include the @code{alias} and @code{unalias}
8254 builtins (@pxref{Aliases}).
8256 @item --enable-arith-for-command
8257 Include support for the alternate form of the @code{for} command
8258 that behaves like the C language @code{for} statement
8259 (@pxref{Looping Constructs}).
8261 @item --enable-array-variables
8262 Include support for one-dimensional array shell variables
8265 @item --enable-bang-history
8266 Include support for @code{csh}-like history substitution
8267 (@pxref{History Interaction}).
8269 @item --enable-brace-expansion
8270 Include @code{csh}-like brace expansion
8271 ( @code{b@{a,b@}c} @expansion{} @code{bac bbc} ).
8272 See @ref{Brace Expansion}, for a complete description.
8274 @item --enable-casemod-attributes
8275 Include support for case-modifying attributes in the @code{declare} builtin
8276 and assignment statements. Variables with the @var{uppercase} attribute,
8277 for example, will have their values converted to uppercase upon assignment.
8279 @item --enable-casemod-expansion
8280 Include support for case-modifying word expansions.
8282 @item --enable-command-timing
8283 Include support for recognizing @code{time} as a reserved word and for
8284 displaying timing statistics for the pipeline following @code{time}
8285 (@pxref{Pipelines}).
8286 This allows pipelines as well as shell builtins and functions to be timed.
8288 @item --enable-cond-command
8289 Include support for the @code{[[} conditional command.
8290 (@pxref{Conditional Constructs}).
8292 @item --enable-cond-regexp
8293 Include support for matching @sc{posix} regular expressions using the
8294 @samp{=~} binary operator in the @code{[[} conditional command.
8295 (@pxref{Conditional Constructs}).
8297 @item --enable-coprocesses
8298 Include support for coprocesses and the @code{coproc} reserved word
8299 (@pxref{Pipelines}).
8301 @item --enable-debugger
8302 Include support for the bash debugger (distributed separately).
8304 @item --enable-direxpand-default
8305 Cause the @code{direxpand} shell option (@pxref{The Shopt Builtin})
8306 to be enabled by default when the shell starts.
8307 It is normally disabled by default.
8309 @item --enable-directory-stack
8310 Include support for a @code{csh}-like directory stack and the
8311 @code{pushd}, @code{popd}, and @code{dirs} builtins
8312 (@pxref{The Directory Stack}).
8314 @item --enable-disabled-builtins
8315 Allow builtin commands to be invoked via @samp{builtin xxx}
8316 even after @code{xxx} has been disabled using @samp{enable -n xxx}.
8317 See @ref{Bash Builtins}, for details of the @code{builtin} and
8318 @code{enable} builtin commands.
8320 @item --enable-dparen-arithmetic
8321 Include support for the @code{((@dots{}))} command
8322 (@pxref{Conditional Constructs}).
8324 @item --enable-extended-glob
8325 Include support for the extended pattern matching features described
8326 above under @ref{Pattern Matching}.
8328 @item --enable-extended-glob-default
8329 Set the default value of the @var{extglob} shell option described
8330 above under @ref{The Shopt Builtin} to be enabled.
8332 @item --enable-function-import
8333 Include support for importing function definitions exported by another
8334 instance of the shell from the environment. This option is enabled by
8337 @item --enable-glob-asciirange-default
8338 Set the default value of the @var{globasciiranges} shell option described
8339 above under @ref{The Shopt Builtin} to be enabled.
8340 This controls the behavior of character ranges when used in pattern matching
8341 bracket expressions.
8343 @item --enable-help-builtin
8344 Include the @code{help} builtin, which displays help on shell builtins and
8345 variables (@pxref{Bash Builtins}).
8347 @item --enable-history
8348 Include command history and the @code{fc} and @code{history}
8349 builtin commands (@pxref{Bash History Facilities}).
8351 @item --enable-job-control
8352 This enables the job control features (@pxref{Job Control}),
8353 if the operating system supports them.
8355 @item --enable-multibyte
8356 This enables support for multibyte characters if the operating
8357 system provides the necessary support.
8359 @item --enable-net-redirections
8360 This enables the special handling of filenames of the form
8361 @code{/dev/tcp/@var{host}/@var{port}} and
8362 @code{/dev/udp/@var{host}/@var{port}}
8363 when used in redirections (@pxref{Redirections}).
8365 @item --enable-process-substitution
8366 This enables process substitution (@pxref{Process Substitution}) if
8367 the operating system provides the necessary support.
8369 @item --enable-progcomp
8370 Enable the programmable completion facilities
8371 (@pxref{Programmable Completion}).
8372 If Readline is not enabled, this option has no effect.
8374 @item --enable-prompt-string-decoding
8375 Turn on the interpretation of a number of backslash-escaped characters
8376 in the @env{$PS1}, @env{$PS2}, @env{$PS3}, and @env{$PS4} prompt
8377 strings. See @ref{Controlling the Prompt}, for a complete list of prompt
8378 string escape sequences.
8380 @item --enable-readline
8381 Include support for command-line editing and history with the Bash
8382 version of the Readline library (@pxref{Command Line Editing}).
8384 @item --enable-restricted
8385 Include support for a @dfn{restricted shell}. If this is enabled, Bash,
8386 when called as @code{rbash}, enters a restricted mode. See
8387 @ref{The Restricted Shell}, for a description of restricted mode.
8389 @item --enable-select
8390 Include the @code{select} compound command, which allows the generation of
8391 simple menus (@pxref{Conditional Constructs}).
8393 @item --enable-separate-helpfiles
8394 Use external files for the documentation displayed by the @code{help} builtin
8395 instead of storing the text internally.
8397 @item --enable-single-help-strings
8398 Store the text displayed by the @code{help} builtin as a single string for
8399 each help topic. This aids in translating the text to different languages.
8400 You may need to disable this if your compiler cannot handle very long string
8403 @item --enable-strict-posix-default
8404 Make Bash @sc{posix}-conformant by default (@pxref{Bash POSIX Mode}).
8406 @item --enable-usg-echo-default
8407 A synonym for @code{--enable-xpg-echo-default}.
8409 @item --enable-xpg-echo-default
8410 Make the @code{echo} builtin expand backslash-escaped characters by default,
8411 without requiring the @option{-e} option.
8412 This sets the default value of the @code{xpg_echo} shell option to @code{on},
8413 which makes the Bash @code{echo} behave more like the version specified in
8414 the Single Unix Specification, version 3.
8415 @xref{Bash Builtins}, for a description of the escape sequences that
8416 @code{echo} recognizes.
8419 The file @file{config-top.h} contains C Preprocessor
8420 @samp{#define} statements for options which are not settable from
8422 Some of these are not meant to be changed; beware of the consequences if
8424 Read the comments associated with each definition for more
8425 information about its effect.
8427 @node Reporting Bugs
8428 @appendix Reporting Bugs
8430 Please report all bugs you find in Bash.
8431 But first, you should
8432 make sure that it really is a bug, and that it appears in the latest
8434 The latest version of Bash is always available for FTP from
8435 @uref{ftp://ftp.gnu.org/pub/gnu/bash/}.
8437 Once you have determined that a bug actually exists, use the
8438 @code{bashbug} command to submit a bug report.
8439 If you have a fix, you are encouraged to mail that as well!
8440 Suggestions and `philosophical' bug reports may be mailed
8441 to @email{bug-bash@@gnu.org} or posted to the Usenet
8442 newsgroup @code{gnu.bash.bug}.
8444 All bug reports should include:
8447 The version number of Bash.
8449 The hardware and operating system.
8451 The compiler used to compile Bash.
8453 A description of the bug behaviour.
8455 A short script or `recipe' which exercises the bug and may be used
8460 @code{bashbug} inserts the first three items automatically into
8461 the template it provides for filing a bug report.
8463 Please send all reports concerning this manual to
8464 @email{bug-bash@@gnu.org}.
8466 @node Major Differences From The Bourne Shell
8467 @appendix Major Differences From The Bourne Shell
8469 Bash implements essentially the same grammar, parameter and
8470 variable expansion, redirection, and quoting as the Bourne Shell.
8471 Bash uses the @sc{posix} standard as the specification of
8472 how these features are to be implemented. There are some
8473 differences between the traditional Bourne shell and Bash; this
8474 section quickly details the differences of significance. A
8475 number of these differences are explained in greater depth in
8477 This section uses the version of @code{sh} included in SVR4.2 (the
8478 last version of the historical Bourne shell) as the baseline reference.
8483 Bash is @sc{posix}-conformant, even where the @sc{posix} specification
8484 differs from traditional @code{sh} behavior (@pxref{Bash POSIX Mode}).
8487 Bash has multi-character invocation options (@pxref{Invoking Bash}).
8490 Bash has command-line editing (@pxref{Command Line Editing}) and
8491 the @code{bind} builtin.
8494 Bash provides a programmable word completion mechanism
8495 (@pxref{Programmable Completion}), and builtin commands
8496 @code{complete}, @code{compgen}, and @code{compopt}, to
8500 Bash has command history (@pxref{Bash History Facilities}) and the
8501 @code{history} and @code{fc} builtins to manipulate it.
8502 The Bash history list maintains timestamp information and uses the
8503 value of the @code{HISTTIMEFORMAT} variable to display it.
8506 Bash implements @code{csh}-like history expansion
8507 (@pxref{History Interaction}).
8510 Bash has one-dimensional array variables (@pxref{Arrays}), and the
8511 appropriate variable expansions and assignment syntax to use them.
8512 Several of the Bash builtins take options to act on arrays.
8513 Bash provides a number of built-in array variables.
8516 The @code{$'@dots{}'} quoting syntax, which expands ANSI-C
8517 backslash-escaped characters in the text between the single quotes,
8518 is supported (@pxref{ANSI-C Quoting}).
8521 Bash supports the @code{$"@dots{}"} quoting syntax to do
8522 locale-specific translation of the characters between the double
8523 quotes. The @option{-D}, @option{--dump-strings}, and @option{--dump-po-strings}
8524 invocation options list the translatable strings found in a script
8525 (@pxref{Locale Translation}).
8528 Bash implements the @code{!} keyword to negate the return value of
8529 a pipeline (@pxref{Pipelines}).
8530 Very useful when an @code{if} statement needs to act only if a test fails.
8531 The Bash @samp{-o pipefail} option to @code{set} will cause a pipeline to
8532 return a failure status if any command fails.
8535 Bash has the @code{time} reserved word and command timing (@pxref{Pipelines}).
8536 The display of the timing statistics may be controlled with the
8537 @env{TIMEFORMAT} variable.
8540 Bash implements the @code{for (( @var{expr1} ; @var{expr2} ; @var{expr3} ))}
8541 arithmetic for command, similar to the C language (@pxref{Looping Constructs}).
8544 Bash includes the @code{select} compound command, which allows the
8545 generation of simple menus (@pxref{Conditional Constructs}).
8548 Bash includes the @code{[[} compound command, which makes conditional
8549 testing part of the shell grammar (@pxref{Conditional Constructs}), including
8550 optional regular expression matching.
8553 Bash provides optional case-insensitive matching for the @code{case} and
8554 @code{[[} constructs.
8557 Bash includes brace expansion (@pxref{Brace Expansion}) and tilde
8558 expansion (@pxref{Tilde Expansion}).
8561 Bash implements command aliases and the @code{alias} and @code{unalias}
8562 builtins (@pxref{Aliases}).
8565 Bash provides shell arithmetic, the @code{((} compound command
8566 (@pxref{Conditional Constructs}),
8567 and arithmetic expansion (@pxref{Shell Arithmetic}).
8570 Variables present in the shell's initial environment are automatically
8571 exported to child processes. The Bourne shell does not normally do
8572 this unless the variables are explicitly marked using the @code{export}
8576 Bash supports the @samp{+=} assignment operator, which appends to the value
8577 of the variable named on the left hand side.
8580 Bash includes the @sc{posix} pattern removal @samp{%}, @samp{#}, @samp{%%}
8581 and @samp{##} expansions to remove leading or trailing substrings from
8582 variable values (@pxref{Shell Parameter Expansion}).
8585 The expansion @code{$@{#xx@}}, which returns the length of @code{$@{xx@}},
8586 is supported (@pxref{Shell Parameter Expansion}).
8589 The expansion @code{$@{var:}@var{offset}@code{[:}@var{length}@code{]@}},
8590 which expands to the substring of @code{var}'s value of length
8591 @var{length}, beginning at @var{offset}, is present
8592 (@pxref{Shell Parameter Expansion}).
8596 @code{$@{var/[/]}@var{pattern}@code{[/}@var{replacement}@code{]@}},
8597 which matches @var{pattern} and replaces it with @var{replacement} in
8598 the value of @code{var}, is available (@pxref{Shell Parameter Expansion}).
8601 The expansion @code{$@{!@var{prefix}*@}} expansion, which expands to
8602 the names of all shell variables whose names begin with @var{prefix},
8603 is available (@pxref{Shell Parameter Expansion}).
8606 Bash has @var{indirect} variable expansion using @code{$@{!word@}}
8607 (@pxref{Shell Parameter Expansion}).
8610 Bash can expand positional parameters beyond @code{$9} using
8611 @code{$@{@var{num}@}}.
8614 The @sc{posix} @code{$()} form of command substitution
8615 is implemented (@pxref{Command Substitution}),
8616 and preferred to the Bourne shell's @code{``} (which
8617 is also implemented for backwards compatibility).
8620 Bash has process substitution (@pxref{Process Substitution}).
8623 Bash automatically assigns variables that provide information about the
8624 current user (@env{UID}, @env{EUID}, and @env{GROUPS}), the current host
8625 (@env{HOSTTYPE}, @env{OSTYPE}, @env{MACHTYPE}, and @env{HOSTNAME}),
8626 and the instance of Bash that is running (@env{BASH},
8627 @env{BASH_VERSION}, and @env{BASH_VERSINFO}). @xref{Bash Variables},
8631 The @env{IFS} variable is used to split only the results of expansion,
8632 not all words (@pxref{Word Splitting}).
8633 This closes a longstanding shell security hole.
8636 The filename expansion bracket expression code uses @samp{!} and @samp{^}
8637 to negate the set of characters between the brackets.
8638 The Bourne shell uses only @samp{!}.
8641 Bash implements the full set of @sc{posix} filename expansion operators,
8642 including @var{character classes}, @var{equivalence classes}, and
8643 @var{collating symbols} (@pxref{Filename Expansion}).
8646 Bash implements extended pattern matching features when the @code{extglob}
8647 shell option is enabled (@pxref{Pattern Matching}).
8650 It is possible to have a variable and a function with the same name;
8651 @code{sh} does not separate the two name spaces.
8654 Bash functions are permitted to have local variables using the
8655 @code{local} builtin, and thus useful recursive functions may be written
8656 (@pxref{Bash Builtins}).
8659 Variable assignments preceding commands affect only that command, even
8660 builtins and functions (@pxref{Environment}).
8661 In @code{sh}, all variable assignments
8662 preceding commands are global unless the command is executed from the
8666 Bash performs filename expansion on filenames specified as operands
8667 to input and output redirection operators (@pxref{Redirections}).
8670 Bash contains the @samp{<>} redirection operator, allowing a file to be
8671 opened for both reading and writing, and the @samp{&>} redirection
8672 operator, for directing standard output and standard error to the same
8673 file (@pxref{Redirections}).
8676 Bash includes the @samp{<<<} redirection operator, allowing a string to
8677 be used as the standard input to a command.
8680 Bash implements the @samp{[n]<&@var{word}} and @samp{[n]>&@var{word}}
8681 redirection operators, which move one file descriptor to another.
8684 Bash treats a number of filenames specially when they are
8685 used in redirection operators (@pxref{Redirections}).
8688 Bash can open network connections to arbitrary machines and services
8689 with the redirection operators (@pxref{Redirections}).
8692 The @code{noclobber} option is available to avoid overwriting existing
8693 files with output redirection (@pxref{The Set Builtin}).
8694 The @samp{>|} redirection operator may be used to override @code{noclobber}.
8697 The Bash @code{cd} and @code{pwd} builtins (@pxref{Bourne Shell Builtins})
8698 each take @option{-L} and @option{-P} options to switch between logical and
8702 Bash allows a function to override a builtin with the same name, and provides
8703 access to that builtin's functionality within the function via the
8704 @code{builtin} and @code{command} builtins (@pxref{Bash Builtins}).
8707 The @code{command} builtin allows selective disabling of functions
8708 when command lookup is performed (@pxref{Bash Builtins}).
8711 Individual builtins may be enabled or disabled using the @code{enable}
8712 builtin (@pxref{Bash Builtins}).
8715 The Bash @code{exec} builtin takes additional options that allow users
8716 to control the contents of the environment passed to the executed
8717 command, and what the zeroth argument to the command is to be
8718 (@pxref{Bourne Shell Builtins}).
8721 Shell functions may be exported to children via the environment
8722 using @code{export -f} (@pxref{Shell Functions}).
8725 The Bash @code{export}, @code{readonly}, and @code{declare} builtins can
8726 take a @option{-f} option to act on shell functions, a @option{-p} option to
8727 display variables with various attributes set in a format that can be
8728 used as shell input, a @option{-n} option to remove various variable
8729 attributes, and @samp{name=value} arguments to set variable attributes
8730 and values simultaneously.
8733 The Bash @code{hash} builtin allows a name to be associated with
8734 an arbitrary filename, even when that filename cannot be found by
8735 searching the @env{$PATH}, using @samp{hash -p}
8736 (@pxref{Bourne Shell Builtins}).
8739 Bash includes a @code{help} builtin for quick reference to shell
8740 facilities (@pxref{Bash Builtins}).
8743 The @code{printf} builtin is available to display formatted output
8744 (@pxref{Bash Builtins}).
8747 The Bash @code{read} builtin (@pxref{Bash Builtins})
8748 will read a line ending in @samp{\} with
8749 the @option{-r} option, and will use the @env{REPLY} variable as a
8750 default if no non-option arguments are supplied.
8751 The Bash @code{read} builtin
8752 also accepts a prompt string with the @option{-p} option and will use
8753 Readline to obtain the line when given the @option{-e} option.
8754 The @code{read} builtin also has additional options to control input:
8755 the @option{-s} option will turn off echoing of input characters as
8756 they are read, the @option{-t} option will allow @code{read} to time out
8757 if input does not arrive within a specified number of seconds, the
8758 @option{-n} option will allow reading only a specified number of
8759 characters rather than a full line, and the @option{-d} option will read
8760 until a particular character rather than newline.
8763 The @code{return} builtin may be used to abort execution of scripts
8764 executed with the @code{.} or @code{source} builtins
8765 (@pxref{Bourne Shell Builtins}).
8768 Bash includes the @code{shopt} builtin, for finer control of shell
8769 optional capabilities (@pxref{The Shopt Builtin}), and allows these options
8770 to be set and unset at shell invocation (@pxref{Invoking Bash}).
8773 Bash has much more optional behavior controllable with the @code{set}
8774 builtin (@pxref{The Set Builtin}).
8777 The @samp{-x} (@option{xtrace}) option displays commands other than
8778 simple commands when performing an execution trace
8779 (@pxref{The Set Builtin}).
8782 The @code{test} builtin (@pxref{Bourne Shell Builtins})
8783 is slightly different, as it implements the @sc{posix} algorithm,
8784 which specifies the behavior based on the number of arguments.
8787 Bash includes the @code{caller} builtin, which displays the context of
8788 any active subroutine call (a shell function or a script executed with
8789 the @code{.} or @code{source} builtins). This supports the bash
8793 The @code{trap} builtin (@pxref{Bourne Shell Builtins}) allows a
8794 @code{DEBUG} pseudo-signal specification, similar to @code{EXIT}.
8795 Commands specified with a @code{DEBUG} trap are executed before every
8796 simple command, @code{for} command, @code{case} command,
8797 @code{select} command, every arithmetic @code{for} command, and before
8798 the first command executes in a shell function.
8799 The @code{DEBUG} trap is not inherited by shell functions unless the
8800 function has been given the @code{trace} attribute or the
8801 @code{functrace} option has been enabled using the @code{shopt} builtin.
8802 The @code{extdebug} shell option has additional effects on the
8805 The @code{trap} builtin (@pxref{Bourne Shell Builtins}) allows an
8806 @code{ERR} pseudo-signal specification, similar to @code{EXIT} and @code{DEBUG}.
8807 Commands specified with an @code{ERR} trap are executed after a simple
8808 command fails, with a few exceptions.
8809 The @code{ERR} trap is not inherited by shell functions unless the
8810 @code{-o errtrace} option to the @code{set} builtin is enabled.
8812 The @code{trap} builtin (@pxref{Bourne Shell Builtins}) allows a
8813 @code{RETURN} pseudo-signal specification, similar to
8814 @code{EXIT} and @code{DEBUG}.
8815 Commands specified with an @code{RETURN} trap are executed before
8816 execution resumes after a shell function or a shell script executed with
8817 @code{.} or @code{source} returns.
8818 The @code{RETURN} trap is not inherited by shell functions unless the
8819 function has been given the @code{trace} attribute or the
8820 @code{functrace} option has been enabled using the @code{shopt} builtin.
8823 The Bash @code{type} builtin is more extensive and gives more information
8824 about the names it finds (@pxref{Bash Builtins}).
8827 The Bash @code{umask} builtin permits a @option{-p} option to cause
8828 the output to be displayed in the form of a @code{umask} command
8829 that may be reused as input (@pxref{Bourne Shell Builtins}).
8832 Bash implements a @code{csh}-like directory stack, and provides the
8833 @code{pushd}, @code{popd}, and @code{dirs} builtins to manipulate it
8834 (@pxref{The Directory Stack}).
8835 Bash also makes the directory stack visible as the value of the
8836 @env{DIRSTACK} shell variable.
8839 Bash interprets special backslash-escaped characters in the prompt
8840 strings when interactive (@pxref{Controlling the Prompt}).
8843 The Bash restricted mode is more useful (@pxref{The Restricted Shell});
8844 the SVR4.2 shell restricted mode is too limited.
8847 The @code{disown} builtin can remove a job from the internal shell
8848 job table (@pxref{Job Control Builtins}) or suppress the sending
8849 of @code{SIGHUP} to a job when the shell exits as the result of a
8853 Bash includes a number of features to support a separate debugger for
8857 The SVR4.2 shell has two privilege-related builtins
8858 (@code{mldmode} and @code{priv}) not present in Bash.
8861 Bash does not have the @code{stop} or @code{newgrp} builtins.
8864 Bash does not use the @env{SHACCT} variable or perform shell accounting.
8867 The SVR4.2 @code{sh} uses a @env{TIMEOUT} variable like Bash uses
8873 More features unique to Bash may be found in @ref{Bash Features}.
8876 @appendixsec Implementation Differences From The SVR4.2 Shell
8878 Since Bash is a completely new implementation, it does not suffer from
8879 many of the limitations of the SVR4.2 shell. For instance:
8884 Bash does not fork a subshell when redirecting into or out of
8885 a shell control structure such as an @code{if} or @code{while}
8889 Bash does not allow unbalanced quotes. The SVR4.2 shell will silently
8890 insert a needed closing quote at @code{EOF} under certain circumstances.
8891 This can be the cause of some hard-to-find errors.
8894 The SVR4.2 shell uses a baroque memory management scheme based on
8895 trapping @code{SIGSEGV}. If the shell is started from a process with
8896 @code{SIGSEGV} blocked (e.g., by using the @code{system()} C library
8897 function call), it misbehaves badly.
8900 In a questionable attempt at security, the SVR4.2 shell,
8901 when invoked without the @option{-p} option, will alter its real
8902 and effective @sc{uid} and @sc{gid} if they are less than some
8903 magic threshold value, commonly 100.
8904 This can lead to unexpected results.
8907 The SVR4.2 shell does not allow users to trap @code{SIGSEGV},
8908 @code{SIGALRM}, or @code{SIGCHLD}.
8911 The SVR4.2 shell does not allow the @env{IFS}, @env{MAILCHECK},
8912 @env{PATH}, @env{PS1}, or @env{PS2} variables to be unset.
8915 The SVR4.2 shell treats @samp{^} as the undocumented equivalent of
8919 Bash allows multiple option arguments when it is invoked (@code{-x -v});
8920 the SVR4.2 shell allows only one option argument (@code{-xv}). In
8921 fact, some versions of the shell dump core if the second argument begins
8925 The SVR4.2 shell exits a script if any builtin fails; Bash exits
8926 a script only if one of the @sc{posix} special builtins fails, and
8927 only for certain failures, as enumerated in the @sc{posix} standard.
8930 The SVR4.2 shell behaves differently when invoked as @code{jsh}
8931 (it turns on job control).
8934 @node GNU Free Documentation License
8935 @appendix GNU Free Documentation License
8943 * Builtin Index:: Index of Bash builtin commands.
8944 * Reserved Word Index:: Index of Bash reserved words.
8945 * Variable Index:: Quick reference helps you find the
8947 * Function Index:: Index of bindable Readline functions.
8948 * Concept Index:: General index for concepts described in
8953 @appendixsec Index of Shell Builtin Commands
8956 @node Reserved Word Index
8957 @appendixsec Index of Shell Reserved Words
8960 @node Variable Index
8961 @appendixsec Parameter and Variable Index
8964 @node Function Index
8965 @appendixsec Function Index
8969 @appendixsec Concept Index