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 \fBdeclare\fP or \fBlocal\fP 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 the nameref attribute itself), the
1522 operation is actually performed on the variable specified by the nameref
1524 A nameref is commonly used within shell functions to refer to a variable
1525 whose name is passed as an argument to the function.
1526 For instance, if a variable name is passed to a shell function as its first
1532 inside the function creates a nameref variable @var{ref} whose value is
1533 the variable name passed as the first argument.
1534 References and assignments to @var{ref}, and changes to its attributes,
1535 are treated as references, assignments, and attribute modifications
1536 to the variable whose name was passed as @code{$1}.
1538 If the control variable in a @code{for} loop has the nameref attribute,
1539 the list of words can be a list of shell variables, and a name reference
1540 will be established for each word in the list, in turn, when the loop is
1542 Array variables cannot be given the nameref attribute.
1543 However, nameref variables can reference array variables and subscripted
1545 Namerefs can be unset using the @option{-n} option to the @code{unset} builtin
1546 (@pxref{Bourne Shell Builtins}).
1547 Otherwise, if @code{unset} is executed with the name of a nameref variable
1548 as an argument, the variable referenced by the nameref variable will be unset.
1550 @node Positional Parameters
1551 @subsection Positional Parameters
1552 @cindex parameters, positional
1554 A @var{positional parameter} is a parameter denoted by one or more
1555 digits, other than the single digit @code{0}. Positional parameters are
1556 assigned from the shell's arguments when it is invoked,
1557 and may be reassigned using the @code{set} builtin command.
1558 Positional parameter @code{N} may be referenced as @code{$@{N@}}, or
1559 as @code{$N} when @code{N} consists of a single digit.
1560 Positional parameters may not be assigned to with assignment statements.
1561 The @code{set} and @code{shift} builtins are used to set and
1562 unset them (@pxref{Shell Builtin Commands}).
1563 The positional parameters are
1564 temporarily replaced when a shell function is executed
1565 (@pxref{Shell Functions}).
1567 When a positional parameter consisting of more than a single
1568 digit is expanded, it must be enclosed in braces.
1570 @node Special Parameters
1571 @subsection Special Parameters
1572 @cindex parameters, special
1574 The shell treats several parameters specially. These parameters may
1575 only be referenced; assignment to them is not allowed.
1581 ($*) Expands to the positional parameters, starting from one.
1582 When the expansion is not within double quotes, each positional parameter
1583 expands to a separate word.
1584 In contexts where it is performed, those words
1585 are subject to further word splitting and pathname expansion.
1586 When the expansion occurs within double quotes, it expands to a single word
1587 with the value of each parameter separated by the first character of the
1588 @env{IFS} special variable. That is, @code{"$*"} is equivalent
1589 to @code{"$1@var{c}$2@var{c}@dots{}"}, where @var{c}
1590 is the first character of the value of the @code{IFS}
1592 If @env{IFS} is unset, the parameters are separated by spaces.
1593 If @env{IFS} is null, the parameters are joined without intervening
1598 ($@@) Expands to the positional parameters, starting from one. When the
1599 expansion occurs within double quotes, each parameter expands to a
1600 separate word. That is, @code{"$@@"} is equivalent to
1601 @code{"$1" "$2" @dots{}}.
1602 If the double-quoted expansion occurs within a word, the expansion of
1603 the first parameter is joined with the beginning part of the original
1604 word, and the expansion of the last parameter is joined with the last
1605 part of the original word.
1606 When there are no positional parameters, @code{"$@@"} and
1608 expand to nothing (i.e., they are removed).
1612 ($#) Expands to the number of positional parameters in decimal.
1616 ($?) Expands to the exit status of the most recently executed foreground
1621 ($-, a hyphen.) Expands to the current option flags as specified upon
1622 invocation, by the @code{set}
1623 builtin command, or those set by the shell itself
1624 (such as the @option{-i} option).
1628 ($$) Expands to the process @sc{id} of the shell. In a @code{()} subshell, it
1629 expands to the process @sc{id} of the invoking shell, not the subshell.
1633 ($!) Expands to the process @sc{id} of the job most recently placed into the
1634 background, whether executed as an asynchronous command or using
1635 the @code{bg} builtin (@pxref{Job Control Builtins}).
1639 ($0) Expands to the name of the shell or shell script. This is set at
1640 shell initialization. If Bash is invoked with a file of commands
1641 (@pxref{Shell Scripts}), @code{$0} is set to the name of that file.
1642 If Bash is started with the @option{-c} option (@pxref{Invoking Bash}),
1643 then @code{$0} is set to the first argument after the string to be
1644 executed, if one is present. Otherwise, it is set
1645 to the filename used to invoke Bash, as given by argument zero.
1649 ($_, an underscore.)
1650 At shell startup, set to the absolute pathname used to invoke the
1651 shell or shell script being executed as passed in the environment
1653 Subsequently, expands to the last argument to the previous command,
1655 Also set to the full pathname used to invoke each command executed
1656 and placed in the environment exported to that command.
1657 When checking mail, this parameter holds the name of the mail file.
1660 @node Shell Expansions
1661 @section Shell Expansions
1664 Expansion is performed on the command line after it has been split into
1665 @code{token}s. There are seven kinds of expansion performed:
1668 @item brace expansion
1669 @item tilde expansion
1670 @item parameter and variable expansion
1671 @item command substitution
1672 @item arithmetic expansion
1673 @item word splitting
1674 @item filename expansion
1678 * Brace Expansion:: Expansion of expressions within braces.
1679 * Tilde Expansion:: Expansion of the ~ character.
1680 * Shell Parameter Expansion:: How Bash expands variables to their values.
1681 * Command Substitution:: Using the output of a command as an argument.
1682 * Arithmetic Expansion:: How to use arithmetic in shell expansions.
1683 * Process Substitution:: A way to write and read to and from a
1685 * Word Splitting:: How the results of expansion are split into separate
1687 * Filename Expansion:: A shorthand for specifying filenames matching patterns.
1688 * Quote Removal:: How and when quote characters are removed from
1692 The order of expansions is:
1694 tilde expansion, parameter and variable expansion, arithmetic expansion,
1695 and command substitution (done in a left-to-right fashion);
1697 and filename expansion.
1699 On systems that can support it, there is an additional expansion
1700 available: @var{process substitution}.
1701 This is performed at the
1702 same time as tilde, parameter, variable, and arithmetic expansion and
1703 command substitution.
1705 Only brace expansion, word splitting, and filename expansion
1706 can change the number of words of the expansion; other expansions
1707 expand a single word to a single word.
1708 The only exceptions to this are the expansions of
1709 @code{"$@@"} (@pxref{Special Parameters}) and @code{"$@{@var{name}[@@]@}"}
1712 After all expansions, @code{quote removal} (@pxref{Quote Removal})
1715 @node Brace Expansion
1716 @subsection Brace Expansion
1717 @cindex brace expansion
1718 @cindex expansion, brace
1720 Brace expansion is a mechanism by which arbitrary strings may be generated.
1721 This mechanism is similar to
1722 @var{filename expansion} (@pxref{Filename Expansion}),
1723 but the filenames generated need not exist.
1724 Patterns to be brace expanded take the form of an optional @var{preamble},
1725 followed by either a series of comma-separated strings or a sequence expression
1726 between a pair of braces,
1727 followed by an optional @var{postscript}.
1728 The preamble is prefixed to each string contained within the braces, and
1729 the postscript is then appended to each resulting string, expanding left
1732 Brace expansions may be nested.
1733 The results of each expanded string are not sorted; left to right order
1737 bash$ echo a@{d,c,b@}e
1741 A sequence expression takes the form @code{@{@var{x}..@var{y}[..@var{incr}]@}},
1742 where @var{x} and @var{y} are either integers or single characters,
1743 and @var{incr}, an optional increment, is an integer.
1744 When integers are supplied, the expression expands to each number between
1745 @var{x} and @var{y}, inclusive.
1746 Supplied integers may be prefixed with @samp{0} to force each term to have the
1748 When either @var{x} or @var{y} begins with a zero, the shell
1749 attempts to force all generated terms to contain the same number of digits,
1750 zero-padding where necessary.
1751 When characters are supplied, the expression expands to each character
1752 lexicographically between @var{x} and @var{y}, inclusive,
1753 using the default C locale.
1754 Note that both @var{x} and @var{y} must be of the same type.
1755 When the increment is supplied, it is used as the difference between
1756 each term. The default increment is 1 or -1 as appropriate.
1758 Brace expansion is performed before any other expansions,
1759 and any characters special to other expansions are preserved
1760 in the result. It is strictly textual. Bash
1761 does not apply any syntactic interpretation to the context of the
1762 expansion or the text between the braces.
1763 To avoid conflicts with parameter expansion, the string @samp{$@{}
1764 is not considered eligible for brace expansion.
1766 A correctly-formed brace expansion must contain unquoted opening
1767 and closing braces, and at least one unquoted comma or a valid
1768 sequence expression.
1769 Any incorrectly formed brace expansion is left unchanged.
1771 A @{ or @samp{,} may be quoted with a backslash to prevent its
1772 being considered part of a brace expression.
1773 To avoid conflicts with parameter expansion, the string @samp{$@{}
1774 is not considered eligible for brace expansion.
1776 This construct is typically used as shorthand when the common
1777 prefix of the strings to be generated is longer than in the
1780 mkdir /usr/local/src/bash/@{old,new,dist,bugs@}
1784 chown root /usr/@{ucb/@{ex,edit@},lib/@{ex?.?*,how_ex@}@}
1787 @node Tilde Expansion
1788 @subsection Tilde Expansion
1789 @cindex tilde expansion
1790 @cindex expansion, tilde
1792 If a word begins with an unquoted tilde character (@samp{~}), all of the
1793 characters up to the first unquoted slash (or all characters,
1794 if there is no unquoted slash) are considered a @var{tilde-prefix}.
1795 If none of the characters in the tilde-prefix are quoted, the
1796 characters in the tilde-prefix following the tilde are treated as a
1797 possible @var{login name}.
1798 If this login name is the null string, the tilde is replaced with the
1799 value of the @env{HOME} shell variable.
1800 If @env{HOME} is unset, the home directory of the user executing the
1801 shell is substituted instead.
1802 Otherwise, the tilde-prefix is replaced with the home directory
1803 associated with the specified login name.
1805 If the tilde-prefix is @samp{~+}, the value of
1806 the shell variable @env{PWD} replaces the tilde-prefix.
1807 If the tilde-prefix is @samp{~-}, the value of the shell variable
1808 @env{OLDPWD}, if it is set, is substituted.
1810 If the characters following the tilde in the tilde-prefix consist of a
1811 number @var{N}, optionally prefixed by a @samp{+} or a @samp{-},
1812 the tilde-prefix is replaced with the
1813 corresponding element from the directory stack, as it would be displayed
1814 by the @code{dirs} builtin invoked with the characters following tilde
1815 in the tilde-prefix as an argument (@pxref{The Directory Stack}).
1816 If the tilde-prefix, sans the tilde, consists of a number without a
1817 leading @samp{+} or @samp{-}, @samp{+} is assumed.
1819 If the login name is invalid, or the tilde expansion fails, the word is
1822 Each variable assignment is checked for unquoted tilde-prefixes immediately
1823 following a @samp{:} or the first @samp{=}.
1824 In these cases, tilde expansion is also performed.
1825 Consequently, one may use filenames with tildes in assignments to
1826 @env{PATH}, @env{MAILPATH}, and @env{CDPATH},
1827 and the shell assigns the expanded value.
1829 The following table shows how Bash treats unquoted tilde-prefixes:
1833 The value of @code{$HOME}
1838 The subdirectory @code{foo} of the home directory of the user
1845 @file{$@{OLDPWD-'~-'@}/foo}
1848 The string that would be displayed by @samp{dirs +@var{N}}
1851 The string that would be displayed by @samp{dirs +@var{N}}
1854 The string that would be displayed by @samp{dirs -@var{N}}
1857 @node Shell Parameter Expansion
1858 @subsection Shell Parameter Expansion
1859 @cindex parameter expansion
1860 @cindex expansion, parameter
1862 The @samp{$} character introduces parameter expansion,
1863 command substitution, or arithmetic expansion. The parameter name
1864 or symbol to be expanded may be enclosed in braces, which
1865 are optional but serve to protect the variable to be expanded from
1866 characters immediately following it which could be
1867 interpreted as part of the name.
1869 When braces are used, the matching ending brace is the first @samp{@}}
1870 not escaped by a backslash or within a quoted string, and not within an
1871 embedded arithmetic expansion, command substitution, or parameter
1874 The basic form of parameter expansion is $@{@var{parameter}@}.
1875 The value of @var{parameter} is substituted.
1876 The @var{parameter} is a shell parameter as described above
1877 (@pxref{Shell Parameters}) or an array reference (@pxref{Arrays}).
1878 The braces are required when @var{parameter}
1879 is a positional parameter with more than one digit,
1880 or when @var{parameter} is followed by a character that is not to be
1881 interpreted as part of its name.
1883 If the first character of @var{parameter} is an exclamation point (!),
1884 and @var{parameter} is not a @var{nameref},
1885 it introduces a level of variable indirection.
1886 Bash uses the value of the variable formed from the rest of
1887 @var{parameter} as the name of the variable; this variable is then
1888 expanded and that value is used in the rest of the substitution, rather
1889 than the value of @var{parameter} itself.
1890 This is known as @code{indirect expansion}.
1891 If @var{parameter} is a nameref, this expands to the name of the
1892 variable referenced by @var{parameter} instead of performing the
1893 complete indirect expansion.
1894 The exceptions to this are the expansions of $@{!@var{prefix}*@}
1895 and $@{!@var{name}[@@]@}
1897 The exclamation point must immediately follow the left brace in order to
1898 introduce indirection.
1900 In each of the cases below, @var{word} is subject to tilde expansion,
1901 parameter expansion, command substitution, and arithmetic expansion.
1903 When not performing substring expansion, using the form described
1904 below (e.g., @samp{:-}), Bash tests for a parameter that is unset or null.
1905 Omitting the colon results in a test only for a parameter that is unset.
1906 Put another way, if the colon is included,
1907 the operator tests for both @var{parameter}'s existence and that its value
1908 is not null; if the colon is omitted, the operator tests only for existence.
1912 @item $@{@var{parameter}:@minus{}@var{word}@}
1913 If @var{parameter} is unset or null, the expansion of
1914 @var{word} is substituted. Otherwise, the value of
1915 @var{parameter} is substituted.
1917 @item $@{@var{parameter}:=@var{word}@}
1919 is unset or null, the expansion of @var{word}
1920 is assigned to @var{parameter}.
1921 The value of @var{parameter} is then substituted.
1922 Positional parameters and special parameters may not be assigned to
1925 @item $@{@var{parameter}:?@var{word}@}
1927 is null or unset, the expansion of @var{word} (or a message
1928 to that effect if @var{word}
1929 is not present) is written to the standard error and the shell, if it
1930 is not interactive, exits. Otherwise, the value of @var{parameter} is
1933 @item $@{@var{parameter}:+@var{word}@}
1935 is null or unset, nothing is substituted, otherwise the expansion of
1936 @var{word} is substituted.
1938 @item $@{@var{parameter}:@var{offset}@}
1939 @itemx $@{@var{parameter}:@var{offset}:@var{length}@}
1940 This is referred to as Substring Expansion.
1941 It expands to up to @var{length} characters of the value of @var{parameter}
1942 starting at the character specified by @var{offset}.
1943 If @var{parameter} is @samp{@@}, an indexed array subscripted by
1944 @samp{@@} or @samp{*}, or an associative array name, the results differ as
1946 If @var{length} is omitted, it expands to the substring of the value of
1947 @var{parameter} starting at the character specified by @var{offset}
1948 and extending to the end of the value.
1949 @var{length} and @var{offset} are arithmetic expressions
1950 (@pxref{Shell Arithmetic}).
1952 If @var{offset} evaluates to a number less than zero, the value
1953 is used as an offset in characters
1954 from the end of the value of @var{parameter}.
1955 If @var{length} evaluates to a number less than zero,
1956 it is interpreted as an offset in characters
1957 from the end of the value of @var{parameter} rather than
1958 a number of characters, and the expansion is the characters between
1959 @var{offset} and that result.
1960 Note that a negative offset must be separated from the colon by at least
1961 one space to avoid being confused with the @samp{:-} expansion.
1963 Here are some examples illustrating substring expansion on parameters and
1967 $ string=01234567890abcdefgh
1970 $ echo ${string:7:0}
1972 $ echo ${string:7:2}
1974 $ echo ${string:7:-2}
1976 $ echo ${string: -7}
1978 $ echo ${string: -7:0}
1980 $ echo ${string: -7:2}
1982 $ echo ${string: -7:-2}
1984 $ set -- 01234567890abcdefgh
2001 $ array[0]=01234567890abcdefgh
2002 $ echo ${array[0]:7}
2004 $ echo ${array[0]:7:0}
2006 $ echo ${array[0]:7:2}
2008 $ echo ${array[0]:7:-2}
2010 $ echo ${array[0]: -7}
2012 $ echo ${array[0]: -7:0}
2014 $ echo ${array[0]: -7:2}
2016 $ echo ${array[0]: -7:-2}
2020 If @var{parameter} is @samp{@@}, the result is @var{length} positional
2021 parameters beginning at @var{offset}.
2022 A negative @var{offset} is taken relative to one greater than the greatest
2023 positional parameter, so an offset of -1 evaluates to the last positional
2025 It is an expansion error if @var{length} evaluates to a number less than zero.
2027 The following examples illustrate substring expansion using positional
2031 $ set -- 1 2 3 4 5 6 7 8 9 0 a b c d e f g h
2033 7 8 9 0 a b c d e f g h
2039 bash: -2: substring expression < 0
2043 ./bash 1 2 3 4 5 6 7 8 9 0 a b c d e f g h
2050 If @var{parameter} is an indexed array name subscripted
2051 by @samp{@@} or @samp{*}, the result is the @var{length}
2052 members of the array beginning with @code{$@{@var{parameter}[@var{offset}]@}}.
2053 A negative @var{offset} is taken relative to one greater than the maximum
2054 index of the specified array.
2055 It is an expansion error if @var{length} evaluates to a number less than zero.
2057 These examples show how you can use substring expansion with indexed
2061 $ array=(0 1 2 3 4 5 6 7 8 9 0 a b c d e f g h)
2062 $ echo ${array[@]:7}
2063 7 8 9 0 a b c d e f g h
2064 $ echo ${array[@]:7:2}
2066 $ echo ${array[@]: -7:2}
2068 $ echo ${array[@]: -7:-2}
2069 bash: -2: substring expression < 0
2070 $ echo ${array[@]:0}
2071 0 1 2 3 4 5 6 7 8 9 0 a b c d e f g h
2072 $ echo ${array[@]:0:2}
2074 $ echo ${array[@]: -7:0}
2078 Substring expansion applied to an associative array produces undefined
2081 Substring indexing is zero-based unless the positional parameters
2082 are used, in which case the indexing starts at 1 by default.
2083 If @var{offset} is 0, and the positional parameters are used, @code{$@@} is
2084 prefixed to the list.
2086 @item $@{!@var{prefix}*@}
2087 @itemx $@{!@var{prefix}@@@}
2088 Expands to the names of variables whose names begin with @var{prefix},
2089 separated by the first character of the @env{IFS} special variable.
2090 When @samp{@@} is used and the expansion appears within double quotes, each
2091 variable name expands to a separate word.
2093 @item $@{!@var{name}[@@]@}
2094 @itemx $@{!@var{name}[*]@}
2095 If @var{name} is an array variable, expands to the list of array indices
2096 (keys) assigned in @var{name}.
2097 If @var{name} is not an array, expands to 0 if @var{name} is set and null
2099 When @samp{@@} is used and the expansion appears within double quotes, each
2100 key expands to a separate word.
2102 @item $@{#@var{parameter}@}
2103 The length in characters of the expanded value of @var{parameter} is
2105 If @var{parameter} is @samp{*} or @samp{@@}, the value substituted
2106 is the number of positional parameters.
2107 If @var{parameter} is an array name subscripted by @samp{*} or @samp{@@},
2108 the value substituted is the number of elements in the array.
2110 is an indexed array name subscripted by a negative number, that number is
2111 interpreted as relative to one greater than the maximum index of
2112 @var{parameter}, so negative indices count back from the end of the
2113 array, and an index of -1 references the last element.
2115 @item $@{@var{parameter}#@var{word}@}
2116 @itemx $@{@var{parameter}##@var{word}@}
2118 is expanded to produce a pattern just as in filename
2119 expansion (@pxref{Filename Expansion}). If the pattern matches
2120 the beginning of the expanded value of @var{parameter},
2121 then the result of the expansion is the expanded value of @var{parameter}
2122 with the shortest matching pattern (the @samp{#} case) or the
2123 longest matching pattern (the @samp{##} case) deleted.
2124 If @var{parameter} is @samp{@@} or @samp{*},
2125 the pattern removal operation is applied to each positional
2126 parameter in turn, and the expansion is the resultant list.
2127 If @var{parameter} is an array variable subscripted with
2128 @samp{@@} or @samp{*},
2129 the pattern removal operation is applied to each member of the
2130 array in turn, and the expansion is the resultant list.
2132 @item $@{@var{parameter}%@var{word}@}
2133 @itemx $@{@var{parameter}%%@var{word}@}
2134 The @var{word} is expanded to produce a pattern just as in
2136 If the pattern matches a trailing portion of the expanded value of
2137 @var{parameter}, then the result of the expansion is the value of
2138 @var{parameter} with the shortest matching pattern (the @samp{%} case)
2139 or the longest matching pattern (the @samp{%%} case) deleted.
2140 If @var{parameter} is @samp{@@} or @samp{*},
2141 the pattern removal operation is applied to each positional
2142 parameter in turn, and the expansion is the resultant list.
2144 is an array variable subscripted with @samp{@@} or @samp{*},
2145 the pattern removal operation is applied to each member of the
2146 array in turn, and the expansion is the resultant list.
2148 @item $@{@var{parameter}/@var{pattern}/@var{string}@}
2150 The @var{pattern} is expanded to produce a pattern just as in
2152 @var{Parameter} is expanded and the longest match of @var{pattern}
2153 against its value is replaced with @var{string}.
2154 If @var{pattern} begins with @samp{/}, all matches of @var{pattern} are
2155 replaced with @var{string}. Normally only the first match is replaced.
2156 If @var{pattern} begins with @samp{#}, it must match at the beginning
2157 of the expanded value of @var{parameter}.
2158 If @var{pattern} begins with @samp{%}, it must match at the end
2159 of the expanded value of @var{parameter}.
2160 If @var{string} is null, matches of @var{pattern} are deleted
2161 and the @code{/} following @var{pattern} may be omitted.
2162 If the @code{nocasematch} shell option
2163 (see the description of @code{shopt} in @ref{The Shopt Builtin})
2164 is enabled, the match is performed without regard to the case
2165 of alphabetic characters.
2166 If @var{parameter} is @samp{@@} or @samp{*},
2167 the substitution operation is applied to each positional
2168 parameter in turn, and the expansion is the resultant list.
2170 is an array variable subscripted with @samp{@@} or @samp{*},
2171 the substitution operation is applied to each member of the
2172 array in turn, and the expansion is the resultant list.
2174 @item $@{@var{parameter}^@var{pattern}@}
2175 @itemx $@{@var{parameter}^^@var{pattern}@}
2176 @itemx $@{@var{parameter},@var{pattern}@}
2177 @itemx $@{@var{parameter},,@var{pattern}@}
2178 This expansion modifies the case of alphabetic characters in @var{parameter}.
2179 The @var{pattern} is expanded to produce a pattern just as in
2181 Each character in the expanded value of @var{parameter} is tested against
2182 @var{pattern}, and, if it matches the pattern, its case is converted.
2183 The pattern should not attempt to match more than one character.
2184 The @samp{^} operator converts lowercase letters matching @var{pattern}
2185 to uppercase; the @samp{,} operator converts matching uppercase letters
2187 The @samp{^^} and @samp{,,} expansions convert each matched character in the
2188 expanded value; the @samp{^} and @samp{,} expansions match and convert only
2189 the first character in the expanded value.
2190 If @var{pattern} is omitted, it is treated like a @samp{?}, which matches
2192 If @var{parameter} is @samp{@@} or @samp{*},
2193 the case modification operation is applied to each positional
2194 parameter in turn, and the expansion is the resultant list.
2196 is an array variable subscripted with @samp{@@} or @samp{*},
2197 the case modification operation is applied to each member of the
2198 array in turn, and the expansion is the resultant list.
2200 @item $@{@var{parameter}@@@var{operator}@}
2201 The expansion is either a transformation of the value of @var{parameter}
2202 or information about @var{parameter} itself, depending on the value of
2203 @var{operator}. Each @var{operator} is a single letter:
2207 The expansion is a string that is the value of @var{parameter} quoted in a
2208 format that can be reused as input.
2210 The expansion is a string that is the value of @var{parameter} with backslash
2211 escape sequences expanded as with the @code{$'@dots{}'} quoting mechansim.
2213 The expansion is a string that is the result of expanding the value of
2214 @var{parameter} as if it were a prompt string (@pxref{Controlling the Prompt}).
2216 The expansion is a string in the form of
2217 an assignment statement or @code{declare} command that, if
2218 evaluated, will recreate @var{parameter} with its attributes and value.
2220 The expansion is a string consisting of flag values representing
2221 @var{parameter}'s attributes.
2224 If @var{parameter} is @samp{@@} or @samp{*},
2225 the operation is applied to each positional
2226 parameter in turn, and the expansion is the resultant list.
2228 is an array variable subscripted with @samp{@@} or @samp{*},
2229 the operation is applied to each member of the
2230 array in turn, and the expansion is the resultant list.
2232 The result of the expansion is subject to word splitting and pathname
2233 expansion as described below.
2236 @node Command Substitution
2237 @subsection Command Substitution
2238 @cindex command substitution
2240 Command substitution allows the output of a command to replace
2242 Command substitution occurs when a command is enclosed as follows:
2253 Bash performs the expansion by executing @var{command} in a subshell environment
2254 and replacing the command substitution with the standard output of the
2255 command, with any trailing newlines deleted.
2256 Embedded newlines are not deleted, but they may be removed during
2258 The command substitution @code{$(cat @var{file})} can be
2259 replaced by the equivalent but faster @code{$(< @var{file})}.
2261 When the old-style backquote form of substitution is used,
2262 backslash retains its literal meaning except when followed by
2263 @samp{$}, @samp{`}, or @samp{\}.
2264 The first backquote not preceded by a backslash terminates the
2265 command substitution.
2266 When using the @code{$(@var{command})} form, all characters between
2267 the parentheses make up the command; none are treated specially.
2269 Command substitutions may be nested. To nest when using the backquoted
2270 form, escape the inner backquotes with backslashes.
2272 If the substitution appears within double quotes, word splitting and
2273 filename expansion are not performed on the results.
2275 @node Arithmetic Expansion
2276 @subsection Arithmetic Expansion
2277 @cindex expansion, arithmetic
2278 @cindex arithmetic expansion
2280 Arithmetic expansion allows the evaluation of an arithmetic expression
2281 and the substitution of the result. The format for arithmetic expansion is:
2284 $(( @var{expression} ))
2287 The expression is treated as if it were within double quotes, but
2288 a double quote inside the parentheses is not treated specially.
2289 All tokens in the expression undergo parameter and variable expansion,
2290 command substitution, and quote removal.
2291 The result is treated as the arithmetic expression to be evaluated.
2292 Arithmetic expansions may be nested.
2294 The evaluation is performed according to the rules listed below
2295 (@pxref{Shell Arithmetic}).
2296 If the expression is invalid, Bash prints a message indicating
2297 failure to the standard error and no substitution occurs.
2299 @node Process Substitution
2300 @subsection Process Substitution
2301 @cindex process substitution
2303 Process substitution allows a process's input or output to be
2304 referred to using a filename.
2305 It takes the form of
2315 The process @var{list} is run asynchronously, and its input or output
2316 appears as a filename.
2318 passed as an argument to the current command as the result of the
2320 If the @code{>(@var{list})} form is used, writing to
2321 the file will provide input for @var{list}. If the
2322 @code{<(@var{list})} form is used, the file passed as an
2323 argument should be read to obtain the output of @var{list}.
2324 Note that no space may appear between the @code{<} or @code{>}
2325 and the left parenthesis, otherwise the construct would be interpreted
2327 Process substitution is supported on systems that support named
2328 pipes (@sc{fifo}s) or the @file{/dev/fd} method of naming open files.
2330 When available, process substitution is performed simultaneously with
2331 parameter and variable expansion, command substitution, and arithmetic
2334 @node Word Splitting
2335 @subsection Word Splitting
2336 @cindex word splitting
2338 The shell scans the results of parameter expansion, command substitution,
2339 and arithmetic expansion that did not occur within double quotes for
2342 The shell treats each character of @env{$IFS} as a delimiter, and splits
2343 the results of the other expansions into words using these characters
2344 as field terminators.
2345 If @env{IFS} is unset, or its value is exactly @code{<space><tab><newline>},
2346 the default, then sequences of
2347 @code{ <space>}, @code{<tab>}, and @code{<newline>}
2348 at the beginning and end of the results of the previous
2349 expansions are ignored, and any sequence of @env{IFS}
2350 characters not at the beginning or end serves to delimit words.
2351 If @env{IFS} has a value other than the default, then sequences of
2352 the whitespace characters @code{space}, @code{tab}, and @code{newline}
2353 are ignored at the beginning and end of the
2354 word, as long as the whitespace character is in the
2355 value of @env{IFS} (an @env{IFS} whitespace character).
2356 Any character in @env{IFS} that is not @env{IFS}
2357 whitespace, along with any adjacent @env{IFS}
2358 whitespace characters, delimits a field. A sequence of @env{IFS}
2359 whitespace characters is also treated as a delimiter.
2360 If the value of @env{IFS} is null, no word splitting occurs.
2362 Explicit null arguments (@code{""} or @code{''}) are retained
2363 and passed to commands as empty strings.
2364 Unquoted implicit null arguments, resulting from the expansion of
2365 parameters that have no values, are removed.
2366 If a parameter with no value is expanded within double quotes, a
2367 null argument results and is retained
2368 and passed to a command as an empty string.
2369 When a quoted null argument appears as part of a word whose expansion is
2370 non-null, the null argument is removed.
2372 @code{-d''} becomes @code{-d} after word splitting and
2373 null argument removal.
2375 Note that if no expansion occurs, no splitting
2378 @node Filename Expansion
2379 @subsection Filename Expansion
2381 * Pattern Matching:: How the shell matches patterns.
2383 @cindex expansion, filename
2384 @cindex expansion, pathname
2385 @cindex filename expansion
2386 @cindex pathname expansion
2388 After word splitting, unless the @option{-f} option has been set
2389 (@pxref{The Set Builtin}), Bash scans each word for the characters
2390 @samp{*}, @samp{?}, and @samp{[}.
2391 If one of these characters appears, then the word is
2392 regarded as a @var{pattern},
2393 and replaced with an alphabetically sorted list of
2394 filenames matching the pattern (@pxref{Pattern Matching}).
2395 If no matching filenames are found,
2396 and the shell option @code{nullglob} is disabled, the word is left
2398 If the @code{nullglob} option is set, and no matches are found, the word
2400 If the @code{failglob} shell option is set, and no matches are found,
2401 an error message is printed and the command is not executed.
2402 If the shell option @code{nocaseglob} is enabled, the match is performed
2403 without regard to the case of alphabetic characters.
2405 When a pattern is used for filename expansion, the character @samp{.}
2406 at the start of a filename or immediately following a slash
2407 must be matched explicitly, unless the shell option @code{dotglob} is set.
2408 When matching a filename, the slash character must always be
2410 In other cases, the @samp{.} character is not treated specially.
2412 See the description of @code{shopt} in @ref{The Shopt Builtin},
2413 for a description of the @code{nocaseglob}, @code{nullglob},
2414 @code{failglob}, and @code{dotglob} options.
2416 The @env{GLOBIGNORE}
2417 shell variable may be used to restrict the set of filenames matching a
2418 pattern. If @env{GLOBIGNORE}
2419 is set, each matching filename that also matches one of the patterns in
2420 @env{GLOBIGNORE} is removed from the list of matches.
2421 If the @code{nocaseglob} option is set, the matching against the patterns in
2422 @env{GLOBIGNORE} is performed without regard to case.
2424 @file{.} and @file{..}
2425 are always ignored when @env{GLOBIGNORE}
2426 is set and not null.
2427 However, setting @env{GLOBIGNORE} to a non-null value has the effect of
2428 enabling the @code{dotglob}
2429 shell option, so all other filenames beginning with a
2430 @samp{.} will match.
2431 To get the old behavior of ignoring filenames beginning with a
2432 @samp{.}, make @samp{.*} one of the patterns in @env{GLOBIGNORE}.
2433 The @code{dotglob} option is disabled when @env{GLOBIGNORE}
2436 @node Pattern Matching
2437 @subsubsection Pattern Matching
2438 @cindex pattern matching
2439 @cindex matching, pattern
2441 Any character that appears in a pattern, other than the special pattern
2442 characters described below, matches itself.
2443 The @sc{nul} character may not occur in a pattern.
2444 A backslash escapes the following character; the
2445 escaping backslash is discarded when matching.
2446 The special pattern characters must be quoted if they are to be matched
2449 The special pattern characters have the following meanings:
2452 Matches any string, including the null string.
2453 When the @code{globstar} shell option is enabled, and @samp{*} is used in
2454 a filename expansion context, two adjacent @samp{*}s used as a single
2455 pattern will match all files and zero or more directories and
2457 If followed by a @samp{/}, two adjacent @samp{*}s will match only
2458 directories and subdirectories.
2460 Matches any single character.
2462 Matches any one of the enclosed characters. A pair of characters
2463 separated by a hyphen denotes a @var{range expression};
2464 any character that falls between those two characters, inclusive,
2465 using the current locale's collating sequence and character set,
2466 is matched. If the first character following the
2467 @samp{[} is a @samp{!} or a @samp{^}
2468 then any character not enclosed is matched. A @samp{@minus{}}
2469 may be matched by including it as the first or last character
2470 in the set. A @samp{]} may be matched by including it as the first
2471 character in the set.
2472 The sorting order of characters in range expressions is determined by
2473 the current locale and the values of the
2474 @env{LC_COLLATE} and @env{LC_ALL} shell variables, if set.
2476 For example, in the default C locale, @samp{[a-dx-z]} is equivalent to
2477 @samp{[abcdxyz]}. Many locales sort characters in dictionary order, and in
2478 these locales @samp{[a-dx-z]} is typically not equivalent to @samp{[abcdxyz]};
2479 it might be equivalent to @samp{[aBbCcDdxXyYz]}, for example. To obtain
2480 the traditional interpretation of ranges in bracket expressions, you can
2481 force the use of the C locale by setting the @env{LC_COLLATE} or
2482 @env{LC_ALL} environment variable to the value @samp{C}, or enable the
2483 @code{globasciiranges} shell option.
2485 Within @samp{[} and @samp{]}, @var{character classes} can be specified
2487 @code{[:}@var{class}@code{:]}, where @var{class} is one of the
2488 following classes defined in the @sc{posix} standard:
2490 alnum alpha ascii blank cntrl digit graph lower
2491 print punct space upper word xdigit
2494 A character class matches any character belonging to that class.
2495 The @code{word} character class matches letters, digits, and the character
2498 Within @samp{[} and @samp{]}, an @var{equivalence class} can be
2499 specified using the syntax @code{[=}@var{c}@code{=]}, which
2500 matches all characters with the same collation weight (as defined
2501 by the current locale) as the character @var{c}.
2503 Within @samp{[} and @samp{]}, the syntax @code{[.}@var{symbol}@code{.]}
2504 matches the collating symbol @var{symbol}.
2507 If the @code{extglob} shell option is enabled using the @code{shopt}
2508 builtin, several extended pattern matching operators are recognized.
2509 In the following description, a @var{pattern-list} is a list of one
2510 or more patterns separated by a @samp{|}.
2511 Composite patterns may be formed using one or more of the following
2515 @item ?(@var{pattern-list})
2516 Matches zero or one occurrence of the given patterns.
2518 @item *(@var{pattern-list})
2519 Matches zero or more occurrences of the given patterns.
2521 @item +(@var{pattern-list})
2522 Matches one or more occurrences of the given patterns.
2524 @item @@(@var{pattern-list})
2525 Matches one of the given patterns.
2527 @item !(@var{pattern-list})
2528 Matches anything except one of the given patterns.
2532 @subsection Quote Removal
2534 After the preceding expansions, all unquoted occurrences of the
2535 characters @samp{\}, @samp{'}, and @samp{"} that did not
2536 result from one of the above expansions are removed.
2539 @section Redirections
2542 Before a command is executed, its input and output
2543 may be @var{redirected}
2544 using a special notation interpreted by the shell.
2545 Redirection allows commands' file handles to be
2546 duplicated, opened, closed,
2547 made to refer to different files,
2548 and can change the files the command reads from and writes to.
2549 Redirection may also be used to modify file handles in the
2550 current shell execution environment. The following redirection
2551 operators may precede or appear anywhere within a
2552 simple command or may follow a command.
2553 Redirections are processed in the order they appear, from
2556 Each redirection that may be preceded by a file descriptor number
2557 may instead be preceded by a word of the form @{@var{varname}@}.
2558 In this case, for each redirection operator except
2559 >&- and <&-, the shell will allocate a file descriptor greater
2560 than 10 and assign it to @{@var{varname}@}. If >&- or <&- is preceded
2561 by @{@var{varname}@}, the value of @var{varname} defines the file
2562 descriptor to close.
2564 In the following descriptions, if the file descriptor number is
2565 omitted, and the first character of the redirection operator is
2566 @samp{<}, the redirection refers to the standard input (file
2567 descriptor 0). If the first character of the redirection operator
2568 is @samp{>}, the redirection refers to the standard output (file
2571 The word following the redirection operator in the following
2572 descriptions, unless otherwise noted, is subjected to brace expansion,
2573 tilde expansion, parameter expansion, command substitution, arithmetic
2574 expansion, quote removal, filename expansion, and word splitting.
2575 If it expands to more than one word, Bash reports an error.
2577 Note that the order of redirections is significant. For example,
2580 ls > @var{dirlist} 2>&1
2583 directs both standard output (file descriptor 1) and standard error
2584 (file descriptor 2) to the file @var{dirlist}, while the command
2586 ls 2>&1 > @var{dirlist}
2589 directs only the standard output to file @var{dirlist},
2590 because the standard error was made a copy of the standard output
2591 before the standard output was redirected to @var{dirlist}.
2593 Bash handles several filenames specially when they are used in
2594 redirections, as described in the following table:
2597 @item /dev/fd/@var{fd}
2598 If @var{fd} is a valid integer, file descriptor @var{fd} is duplicated.
2601 File descriptor 0 is duplicated.
2604 File descriptor 1 is duplicated.
2607 File descriptor 2 is duplicated.
2609 @item /dev/tcp/@var{host}/@var{port}
2610 If @var{host} is a valid hostname or Internet address, and @var{port}
2611 is an integer port number or service name, Bash attempts to open
2612 the corresponding TCP socket.
2614 @item /dev/udp/@var{host}/@var{port}
2615 If @var{host} is a valid hostname or Internet address, and @var{port}
2616 is an integer port number or service name, Bash attempts to open
2617 the corresponding UDP socket.
2620 A failure to open or create a file causes the redirection to fail.
2622 Redirections using file descriptors greater than 9 should be used with
2623 care, as they may conflict with file descriptors the shell uses
2626 @subsection Redirecting Input
2627 Redirection of input causes the file whose name results from
2628 the expansion of @var{word}
2629 to be opened for reading on file descriptor @code{n},
2630 or the standard input (file descriptor 0) if @code{n}
2633 The general format for redirecting input is:
2635 [@var{n}]<@var{word}
2638 @subsection Redirecting Output
2639 Redirection of output causes the file whose name results from
2640 the expansion of @var{word}
2641 to be opened for writing on file descriptor @var{n},
2642 or the standard output (file descriptor 1) if @var{n}
2643 is not specified. If the file does not exist it is created;
2644 if it does exist it is truncated to zero size.
2646 The general format for redirecting output is:
2648 [@var{n}]>[|]@var{word}
2651 If the redirection operator is @samp{>}, and the @code{noclobber}
2652 option to the @code{set} builtin has been enabled, the redirection
2653 will fail if the file whose name results from the expansion of
2654 @var{word} exists and is a regular file.
2655 If the redirection operator is @samp{>|}, or the redirection operator is
2656 @samp{>} and the @code{noclobber} option is not enabled, the redirection
2657 is attempted even if the file named by @var{word} exists.
2659 @subsection Appending Redirected Output
2660 Redirection of output in this fashion
2661 causes the file whose name results from
2662 the expansion of @var{word}
2663 to be opened for appending on file descriptor @var{n},
2664 or the standard output (file descriptor 1) if @var{n}
2665 is not specified. If the file does not exist it is created.
2667 The general format for appending output is:
2669 [@var{n}]>>@var{word}
2672 @subsection Redirecting Standard Output and Standard Error
2673 This construct allows both the
2674 standard output (file descriptor 1) and
2675 the standard error output (file descriptor 2)
2676 to be redirected to the file whose name is the
2677 expansion of @var{word}.
2679 There are two formats for redirecting standard output and
2690 Of the two forms, the first is preferred.
2691 This is semantically equivalent to
2695 When using the second form, @var{word} may not expand to a number or
2696 @samp{-}. If it does, other redirection operators apply
2697 (see Duplicating File Descriptors below) for compatibility reasons.
2699 @subsection Appending Standard Output and Standard Error
2700 This construct allows both the
2701 standard output (file descriptor 1) and
2702 the standard error output (file descriptor 2)
2703 to be appended to the file whose name is the
2704 expansion of @var{word}.
2706 The format for appending standard output and standard error is:
2711 This is semantically equivalent to
2715 (see Duplicating File Descriptors below).
2717 @subsection Here Documents
2718 This type of redirection instructs the shell to read input from the
2719 current source until a line containing only @var{word}
2720 (with no trailing blanks) is seen. All of
2721 the lines read up to that point are then used as the standard
2722 input (or file descriptor @var{n} if @var{n} is specified) for a command.
2724 The format of here-documents is:
2726 [@var{n}]<<[@minus{}]@var{word}
2731 No parameter and variable expansion, command substitution,
2732 arithmetic expansion, or filename expansion is performed on
2733 @var{word}. If any characters in @var{word} are quoted, the
2734 @var{delimiter} is the result of quote removal on @var{word},
2735 and the lines in the here-document are not expanded.
2736 If @var{word} is unquoted,
2737 all lines of the here-document are subjected to
2738 parameter expansion, command substitution, and arithmetic expansion,
2739 the character sequence @code{\newline} is ignored, and @samp{\}
2740 must be used to quote the characters
2741 @samp{\}, @samp{$}, and @samp{`}.
2743 If the redirection operator is @samp{<<-},
2744 then all leading tab characters are stripped from input lines and the
2745 line containing @var{delimiter}.
2746 This allows here-documents within shell scripts to be indented in a
2749 @subsection Here Strings
2750 A variant of here documents, the format is:
2752 [@var{n}]<<< @var{word}
2755 The @var{word} undergoes
2756 brace expansion, tilde expansion, parameter and variable expansion,
2757 command substitution, arithmetic expansion, and quote removal.
2758 Pathname expansion and word splitting are not performed.
2759 The result is supplied as a single string,
2760 with a newline appended,
2761 to the command on its
2762 standard input (or file descriptor @var{n} if @var{n} is specified).
2764 @subsection Duplicating File Descriptors
2765 The redirection operator
2767 [@var{n}]<&@var{word}
2770 is used to duplicate input file descriptors.
2772 expands to one or more digits, the file descriptor denoted by @var{n}
2773 is made to be a copy of that file descriptor.
2774 If the digits in @var{word} do not specify a file descriptor open for
2775 input, a redirection error occurs.
2777 evaluates to @samp{-}, file descriptor @var{n} is closed.
2778 If @var{n} is not specified, the standard input (file descriptor 0) is used.
2782 [@var{n}]>&@var{word}
2785 is used similarly to duplicate output file descriptors. If
2786 @var{n} is not specified, the standard output (file descriptor 1) is used.
2787 If the digits in @var{word} do not specify a file descriptor open for
2788 output, a redirection error occurs.
2790 evaluates to @samp{-}, file descriptor @var{n} is closed.
2791 As a special case, if @var{n} is omitted, and @var{word} does not
2792 expand to one or more digits or @samp{-}, the standard output and standard
2793 error are redirected as described previously.
2795 @subsection Moving File Descriptors
2796 The redirection operator
2798 [@var{n}]<&@var{digit}-
2801 moves the file descriptor @var{digit} to file descriptor @var{n},
2802 or the standard input (file descriptor 0) if @var{n} is not specified.
2803 @var{digit} is closed after being duplicated to @var{n}.
2805 Similarly, the redirection operator
2807 [@var{n}]>&@var{digit}-
2810 moves the file descriptor @var{digit} to file descriptor @var{n},
2811 or the standard output (file descriptor 1) if @var{n} is not specified.
2813 @subsection Opening File Descriptors for Reading and Writing
2814 The redirection operator
2816 [@var{n}]<>@var{word}
2819 causes the file whose name is the expansion of @var{word}
2820 to be opened for both reading and writing on file descriptor
2821 @var{n}, or on file descriptor 0 if @var{n}
2822 is not specified. If the file does not exist, it is created.
2824 @node Executing Commands
2825 @section Executing Commands
2828 * Simple Command Expansion:: How Bash expands simple commands before
2830 * Command Search and Execution:: How Bash finds commands and runs them.
2831 * Command Execution Environment:: The environment in which Bash
2832 executes commands that are not
2834 * Environment:: The environment given to a command.
2835 * Exit Status:: The status returned by commands and how Bash
2837 * Signals:: What happens when Bash or a command it runs
2841 @node Simple Command Expansion
2842 @subsection Simple Command Expansion
2843 @cindex command expansion
2845 When a simple command is executed, the shell performs the following
2846 expansions, assignments, and redirections, from left to right.
2850 The words that the parser has marked as variable assignments (those
2851 preceding the command name) and redirections are saved for later
2855 The words that are not variable assignments or redirections are
2856 expanded (@pxref{Shell Expansions}).
2857 If any words remain after expansion, the first word
2858 is taken to be the name of the command and the remaining words are
2862 Redirections are performed as described above (@pxref{Redirections}).
2865 The text after the @samp{=} in each variable assignment undergoes tilde
2866 expansion, parameter expansion, command substitution, arithmetic expansion,
2867 and quote removal before being assigned to the variable.
2870 If no command name results, the variable assignments affect the current
2871 shell environment. Otherwise, the variables are added to the environment
2872 of the executed command and do not affect the current shell environment.
2873 If any of the assignments attempts to assign a value to a readonly variable,
2874 an error occurs, and the command exits with a non-zero status.
2876 If no command name results, redirections are performed, but do not
2877 affect the current shell environment. A redirection error causes the
2878 command to exit with a non-zero status.
2880 If there is a command name left after expansion, execution proceeds as
2881 described below. Otherwise, the command exits. If one of the expansions
2882 contained a command substitution, the exit status of the command is
2883 the exit status of the last command substitution performed. If there
2884 were no command substitutions, the command exits with a status of zero.
2886 @node Command Search and Execution
2887 @subsection Command Search and Execution
2888 @cindex command execution
2889 @cindex command search
2891 After a command has been split into words, if it results in a
2892 simple command and an optional list of arguments, the following
2897 If the command name contains no slashes, the shell attempts to
2898 locate it. If there exists a shell function by that name, that
2899 function is invoked as described in @ref{Shell Functions}.
2902 If the name does not match a function, the shell searches for
2903 it in the list of shell builtins. If a match is found, that
2907 If the name is neither a shell function nor a builtin,
2908 and contains no slashes, Bash searches each element of
2909 @env{$PATH} for a directory containing an executable file
2910 by that name. Bash uses a hash table to remember the full
2911 pathnames of executable files to avoid multiple @env{PATH} searches
2912 (see the description of @code{hash} in @ref{Bourne Shell Builtins}).
2913 A full search of the directories in @env{$PATH}
2914 is performed only if the command is not found in the hash table.
2915 If the search is unsuccessful, the shell searches for a defined shell
2916 function named @code{command_not_found_handle}.
2917 If that function exists, it is invoked with the original command and
2918 the original command's arguments as its arguments, and the function's
2919 exit status becomes the exit status of the shell.
2920 If that function is not defined, the shell prints an error
2921 message and returns an exit status of 127.
2924 If the search is successful, or if the command name contains
2925 one or more slashes, the shell executes the named program in
2926 a separate execution environment.
2927 Argument 0 is set to the name given, and the remaining arguments
2928 to the command are set to the arguments supplied, if any.
2931 If this execution fails because the file is not in executable
2932 format, and the file is not a directory, it is assumed to be a
2933 @var{shell script} and the shell executes it as described in
2934 @ref{Shell Scripts}.
2937 If the command was not begun asynchronously, the shell waits for
2938 the command to complete and collects its exit status.
2942 @node Command Execution Environment
2943 @subsection Command Execution Environment
2944 @cindex execution environment
2946 The shell has an @var{execution environment}, which consists of the
2951 open files inherited by the shell at invocation, as modified by
2952 redirections supplied to the @code{exec} builtin
2955 the current working directory as set by @code{cd}, @code{pushd}, or
2956 @code{popd}, or inherited by the shell at invocation
2959 the file creation mode mask as set by @code{umask} or inherited from
2963 current traps set by @code{trap}
2966 shell parameters that are set by variable assignment or with @code{set}
2967 or inherited from the shell's parent in the environment
2970 shell functions defined during execution or inherited from the shell's
2971 parent in the environment
2974 options enabled at invocation (either by default or with command-line
2975 arguments) or by @code{set}
2978 options enabled by @code{shopt} (@pxref{The Shopt Builtin})
2981 shell aliases defined with @code{alias} (@pxref{Aliases})
2984 various process @sc{id}s, including those of background jobs
2985 (@pxref{Lists}), the value of @code{$$}, and the value of
2990 When a simple command other than a builtin or shell function
2991 is to be executed, it
2992 is invoked in a separate execution environment that consists of
2993 the following. Unless otherwise noted, the values are inherited
2998 the shell's open files, plus any modifications and additions specified
2999 by redirections to the command
3002 the current working directory
3005 the file creation mode mask
3008 shell variables and functions marked for export, along with variables
3009 exported for the command, passed in the environment (@pxref{Environment})
3012 traps caught by the shell are reset to the values inherited from the
3013 shell's parent, and traps ignored by the shell are ignored
3017 A command invoked in this separate environment cannot affect the
3018 shell's execution environment.
3020 Command substitution, commands grouped with parentheses,
3021 and asynchronous commands are invoked in a
3022 subshell environment that is a duplicate of the shell environment,
3023 except that traps caught by the shell are reset to the values
3024 that the shell inherited from its parent at invocation. Builtin
3025 commands that are invoked as part of a pipeline are also executed
3026 in a subshell environment. Changes made to the subshell environment
3027 cannot affect the shell's execution environment.
3029 Subshells spawned to execute command substitutions inherit the value of
3030 the @option{-e} option from the parent shell. When not in @sc{posix} mode,
3031 Bash clears the @option{-e} option in such subshells.
3033 If a command is followed by a @samp{&} and job control is not active, the
3034 default standard input for the command is the empty file @file{/dev/null}.
3035 Otherwise, the invoked command inherits the file descriptors of the calling
3036 shell as modified by redirections.
3039 @subsection Environment
3042 When a program is invoked it is given an array of strings
3043 called the @var{environment}.
3044 This is a list of name-value pairs, of the form @code{name=value}.
3046 Bash provides several ways to manipulate the environment.
3047 On invocation, the shell scans its own environment and
3048 creates a parameter for each name found, automatically marking
3050 to child processes. Executed commands inherit the environment.
3051 The @code{export} and @samp{declare -x}
3052 commands allow parameters and functions to be added to and
3053 deleted from the environment. If the value of a parameter
3054 in the environment is modified, the new value becomes part
3055 of the environment, replacing the old. The environment
3056 inherited by any executed command consists of the shell's
3057 initial environment, whose values may be modified in the shell,
3058 less any pairs removed by the @code{unset} and @samp{export -n}
3059 commands, plus any additions via the @code{export} and
3060 @samp{declare -x} commands.
3062 The environment for any simple command
3063 or function may be augmented temporarily by prefixing it with
3064 parameter assignments, as described in @ref{Shell Parameters}.
3065 These assignment statements affect only the environment seen
3068 If the @option{-k} option is set (@pxref{The Set Builtin}), then all
3069 parameter assignments are placed in the environment for a command,
3070 not just those that precede the command name.
3072 When Bash invokes an external command, the variable @samp{$_}
3073 is set to the full pathname of the command and passed to that
3074 command in its environment.
3077 @subsection Exit Status
3080 The exit status of an executed command is the value returned by the
3081 @var{waitpid} system call or equivalent function. Exit statuses
3082 fall between 0 and 255, though, as explained below, the shell may
3083 use values above 125 specially. Exit statuses from shell builtins and
3084 compound commands are also limited to this range. Under certain
3085 circumstances, the shell will use special values to indicate specific
3088 For the shell's purposes, a command which exits with a
3089 zero exit status has succeeded.
3090 A non-zero exit status indicates failure.
3091 This seemingly counter-intuitive scheme is used so there
3092 is one well-defined way to indicate success and a variety of
3093 ways to indicate various failure modes.
3094 When a command terminates on a fatal signal whose number is @var{N},
3095 Bash uses the value 128+@var{N} as the exit status.
3097 If a command is not found, the child process created to
3098 execute it returns a status of 127. If a command is found
3099 but is not executable, the return status is 126.
3101 If a command fails because of an error during expansion or redirection,
3102 the exit status is greater than zero.
3104 The exit status is used by the Bash conditional commands
3105 (@pxref{Conditional Constructs}) and some of the list
3106 constructs (@pxref{Lists}).
3108 All of the Bash builtins return an exit status of zero if they succeed
3109 and a non-zero status on failure, so they may be used by the
3110 conditional and list constructs.
3111 All builtins return an exit status of 2 to indicate incorrect usage,
3112 generally invalid options or missing arguments.
3116 @cindex signal handling
3118 When Bash is interactive, in the absence of any traps, it ignores
3119 @code{SIGTERM} (so that @samp{kill 0} does not kill an interactive shell),
3121 is caught and handled (so that the @code{wait} builtin is interruptible).
3122 When Bash receives a @code{SIGINT}, it breaks out of any executing loops.
3123 In all cases, Bash ignores @code{SIGQUIT}.
3124 If job control is in effect (@pxref{Job Control}), Bash
3125 ignores @code{SIGTTIN}, @code{SIGTTOU}, and @code{SIGTSTP}.
3127 Non-builtin commands started by Bash have signal handlers set to the
3128 values inherited by the shell from its parent.
3129 When job control is not in effect, asynchronous commands
3130 ignore @code{SIGINT} and @code{SIGQUIT} in addition to these inherited
3132 Commands run as a result of
3133 command substitution ignore the keyboard-generated job control signals
3134 @code{SIGTTIN}, @code{SIGTTOU}, and @code{SIGTSTP}.
3136 The shell exits by default upon receipt of a @code{SIGHUP}.
3137 Before exiting, an interactive shell resends the @code{SIGHUP} to
3138 all jobs, running or stopped.
3139 Stopped jobs are sent @code{SIGCONT} to ensure that they receive
3141 To prevent the shell from sending the @code{SIGHUP} signal to a
3142 particular job, it should be removed
3143 from the jobs table with the @code{disown}
3144 builtin (@pxref{Job Control Builtins}) or marked
3145 to not receive @code{SIGHUP} using @code{disown -h}.
3147 If the @code{huponexit} shell option has been set with @code{shopt}
3148 (@pxref{The Shopt Builtin}), Bash sends a @code{SIGHUP} to all jobs when
3149 an interactive login shell exits.
3151 If Bash is waiting for a command to complete and receives a signal
3152 for which a trap has been set, the trap will not be executed until
3153 the command completes.
3154 When Bash is waiting for an asynchronous
3155 command via the @code{wait} builtin, the reception of a signal for
3156 which a trap has been set will cause the @code{wait} builtin to return
3157 immediately with an exit status greater than 128, immediately after
3158 which the trap is executed.
3161 @section Shell Scripts
3162 @cindex shell script
3164 A shell script is a text file containing shell commands. When such
3165 a file is used as the first non-option argument when invoking Bash,
3166 and neither the @option{-c} nor @option{-s} option is supplied
3167 (@pxref{Invoking Bash}),
3168 Bash reads and executes commands from the file, then exits. This
3169 mode of operation creates a non-interactive shell. The shell first
3170 searches for the file in the current directory, and looks in the
3171 directories in @env{$PATH} if not found there.
3174 a shell script, it sets the special parameter @code{0} to the name
3175 of the file, rather than the name of the shell, and the positional
3176 parameters are set to the remaining arguments, if any are given.
3177 If no additional arguments are supplied, the positional parameters
3180 A shell script may be made executable by using the @code{chmod} command
3181 to turn on the execute bit. When Bash finds such a file while
3182 searching the @env{$PATH} for a command, it spawns a subshell to
3183 execute it. In other words, executing
3185 filename @var{arguments}
3188 is equivalent to executing
3190 bash filename @var{arguments}
3194 if @code{filename} is an executable shell script.
3195 This subshell reinitializes itself, so that the effect is as if a
3196 new shell had been invoked to interpret the script, with the
3197 exception that the locations of commands remembered by the parent
3198 (see the description of @code{hash} in @ref{Bourne Shell Builtins})
3199 are retained by the child.
3201 Most versions of Unix make this a part of the operating system's command
3202 execution mechanism. If the first line of a script begins with
3203 the two characters @samp{#!}, the remainder of the line specifies
3204 an interpreter for the program.
3205 Thus, you can specify Bash, @code{awk}, Perl, or some other
3206 interpreter and write the rest of the script file in that language.
3208 The arguments to the interpreter
3209 consist of a single optional argument following the interpreter
3210 name on the first line of the script file, followed by the name of
3211 the script file, followed by the rest of the arguments. Bash
3212 will perform this action on operating systems that do not handle it
3213 themselves. Note that some older versions of Unix limit the interpreter
3214 name and argument to a maximum of 32 characters.
3216 Bash scripts often begin with @code{#! /bin/bash} (assuming that
3217 Bash has been installed in @file{/bin}), since this ensures that
3218 Bash will be used to interpret the script, even if it is executed
3219 under another shell.
3221 @node Shell Builtin Commands
3222 @chapter Shell Builtin Commands
3225 * Bourne Shell Builtins:: Builtin commands inherited from the Bourne
3227 * Bash Builtins:: Table of builtins specific to Bash.
3228 * Modifying Shell Behavior:: Builtins to modify shell attributes and
3230 * Special Builtins:: Builtin commands classified specially by
3234 Builtin commands are contained within the shell itself.
3235 When the name of a builtin command is used as the first word of
3236 a simple command (@pxref{Simple Commands}), the shell executes
3237 the command directly, without invoking another program.
3238 Builtin commands are necessary to implement functionality impossible
3239 or inconvenient to obtain with separate utilities.
3241 This section briefly describes the builtins which Bash inherits from
3242 the Bourne Shell, as well as the builtin commands which are unique
3243 to or have been extended in Bash.
3245 Several builtin commands are described in other chapters: builtin
3246 commands which provide the Bash interface to the job control
3247 facilities (@pxref{Job Control Builtins}), the directory stack
3248 (@pxref{Directory Stack Builtins}), the command history
3249 (@pxref{Bash History Builtins}), and the programmable completion
3250 facilities (@pxref{Programmable Completion Builtins}).
3252 Many of the builtins have been extended by @sc{posix} or Bash.
3254 Unless otherwise noted, each builtin command documented as accepting
3255 options preceded by @samp{-} accepts @samp{--}
3256 to signify the end of the options.
3257 The @code{:}, @code{true}, @code{false}, and @code{test}
3258 builtins do not accept options and do not treat @samp{--} specially.
3259 The @code{exit}, @code{logout}, @code{return},
3260 @code{break}, @code{continue}, @code{let},
3261 and @code{shift} builtins accept and process arguments beginning
3262 with @samp{-} without requiring @samp{--}.
3263 Other builtins that accept arguments but are not specified as accepting
3264 options interpret arguments beginning with @samp{-} as invalid options and
3265 require @samp{--} to prevent this interpretation.
3267 @node Bourne Shell Builtins
3268 @section Bourne Shell Builtins
3270 The following shell builtin commands are inherited from the Bourne Shell.
3271 These commands are implemented as specified by the @sc{posix} standard.
3274 @item : @r{(a colon)}
3280 Do nothing beyond expanding @var{arguments} and performing redirections.
3281 The return status is zero.
3283 @item . @r{(a period)}
3286 . @var{filename} [@var{arguments}]
3289 Read and execute commands from the @var{filename} argument in the
3290 current shell context. If @var{filename} does not contain a slash,
3291 the @env{PATH} variable is used to find @var{filename}.
3292 When Bash is not in @sc{posix} mode, the current directory is searched
3293 if @var{filename} is not found in @env{$PATH}.
3294 If any @var{arguments} are supplied, they become the positional
3295 parameters when @var{filename} is executed. Otherwise the positional
3296 parameters are unchanged.
3297 If the @option{-T} option is enabled, @code{source} inherits any trap on
3298 @code{DEBUG}; if it is not, any @code{DEBUG} trap string is saved and
3299 restored around the call to @code{source}, and @code{source} unsets the
3300 @code{DEBUG} trap while it executes.
3301 If @option{-T} is not set, and the sourced file changes
3302 the @code{DEBUG} trap, the new value is retained when @code{source} completes.
3303 The return status is the exit status of the last command executed, or
3304 zero if no commands are executed. If @var{filename} is not found, or
3305 cannot be read, the return status is non-zero.
3306 This builtin is equivalent to @code{source}.
3314 Exit from a @code{for}, @code{while}, @code{until}, or @code{select} loop.
3315 If @var{n} is supplied, the @var{n}th enclosing loop is exited.
3316 @var{n} must be greater than or equal to 1.
3317 The return status is zero unless @var{n} is not greater than or equal to 1.
3322 cd [-L|[-P [-e]] [-@@] [@var{directory}]
3325 Change the current working directory to @var{directory}.
3326 If @var{directory} is not supplied, the value of the @env{HOME}
3327 shell variable is used.
3328 Any additional arguments following @var{directory} are ignored.
3329 If the shell variable
3330 @env{CDPATH} exists, it is used as a search path:
3331 each directory name in @env{CDPATH} is searched for
3332 @var{directory}, with alternative directory names in @env{CDPATH}
3333 separated by a colon (@samp{:}).
3334 If @var{directory} begins with a slash, @env{CDPATH} is not used.
3336 The @option{-P} option means to not follow symbolic links: symbolic links
3337 are resolved while @code{cd} is traversing @var{directory} and before
3338 processing an instance of @samp{..} in @var{directory}.
3340 By default, or when the @option{-L} option is supplied, symbolic links
3341 in @var{directory} are resolved after @code{cd} processes an instance
3342 of @samp{..} in @var{directory}.
3344 If @samp{..} appears in @var{directory}, it is processed by removing the
3345 immediately preceding pathname component, back to a slash or the beginning
3348 If the @option{-e} option is supplied with @option{-P}
3349 and the current working directory cannot be successfully determined
3350 after a successful directory change, @code{cd} will return an unsuccessful
3353 On systems that support it, the @option{-@@} option presents the extended
3354 attributes associated with a file as a directory.
3356 If @var{directory} is @samp{-}, it is converted to @env{$OLDPWD}
3357 before the directory change is attempted.
3359 If a non-empty directory name from @env{CDPATH} is used, or if
3360 @samp{-} is the first argument, and the directory change is
3361 successful, the absolute pathname of the new working directory is
3362 written to the standard output.
3364 The return status is zero if the directory is successfully changed,
3373 Resume the next iteration of an enclosing @code{for}, @code{while},
3374 @code{until}, or @code{select} loop.
3375 If @var{n} is supplied, the execution of the @var{n}th enclosing loop
3377 @var{n} must be greater than or equal to 1.
3378 The return status is zero unless @var{n} is not greater than or equal to 1.
3383 eval [@var{arguments}]
3386 The arguments are concatenated together into a single command, which is
3387 then read and executed, and its exit status returned as the exit status
3389 If there are no arguments or only empty arguments, the return status is
3395 exec [-cl] [-a @var{name}] [@var{command} [@var{arguments}]]
3399 is supplied, it replaces the shell without creating a new process.
3400 If the @option{-l} option is supplied, the shell places a dash at the
3401 beginning of the zeroth argument passed to @var{command}.
3402 This is what the @code{login} program does.
3403 The @option{-c} option causes @var{command} to be executed with an empty
3405 If @option{-a} is supplied, the shell passes @var{name} as the zeroth
3406 argument to @var{command}.
3408 cannot be executed for some reason, a non-interactive shell exits,
3409 unless the @code{execfail} shell option
3410 is enabled. In that case, it returns failure.
3411 An interactive shell returns failure if the file cannot be executed.
3412 If no @var{command} is specified, redirections may be used to affect
3413 the current shell environment. If there are no redirection errors, the
3414 return status is zero; otherwise the return status is non-zero.
3422 Exit the shell, returning a status of @var{n} to the shell's parent.
3423 If @var{n} is omitted, the exit status is that of the last command executed.
3424 Any trap on @code{EXIT} is executed before the shell terminates.
3429 export [-fn] [-p] [@var{name}[=@var{value}]]
3432 Mark each @var{name} to be passed to child processes
3433 in the environment. If the @option{-f} option is supplied, the @var{name}s
3434 refer to shell functions; otherwise the names refer to shell variables.
3435 The @option{-n} option means to no longer mark each @var{name} for export.
3436 If no @var{names} are supplied, or if the @option{-p} option is given, a
3437 list of names of all exported variables is displayed.
3438 The @option{-p} option displays output in a form that may be reused as input.
3439 If a variable name is followed by =@var{value}, the value of
3440 the variable is set to @var{value}.
3442 The return status is zero unless an invalid option is supplied, one of
3443 the names is not a valid shell variable name, or @option{-f} is supplied
3444 with a name that is not a shell function.
3449 getopts @var{optstring} @var{name} [@var{args}]
3452 @code{getopts} is used by shell scripts to parse positional parameters.
3453 @var{optstring} contains the option characters to be recognized; if a
3454 character is followed by a colon, the option is expected to have an
3455 argument, which should be separated from it by whitespace.
3456 The colon (@samp{:}) and question mark (@samp{?}) may not be
3457 used as option characters.
3458 Each time it is invoked, @code{getopts}
3459 places the next option in the shell variable @var{name}, initializing
3460 @var{name} if it does not exist,
3461 and the index of the next argument to be processed into the
3462 variable @env{OPTIND}.
3463 @env{OPTIND} is initialized to 1 each time the shell or a shell script
3465 When an option requires an argument,
3466 @code{getopts} places that argument into the variable @env{OPTARG}.
3467 The shell does not reset @env{OPTIND} automatically; it must be manually
3468 reset between multiple calls to @code{getopts} within the same shell
3469 invocation if a new set of parameters is to be used.
3471 When the end of options is encountered, @code{getopts} exits with a
3472 return value greater than zero.
3473 @env{OPTIND} is set to the index of the first non-option argument,
3474 and @var{name} is set to @samp{?}.
3477 normally parses the positional parameters, but if more arguments are
3478 given in @var{args}, @code{getopts} parses those instead.
3480 @code{getopts} can report errors in two ways. If the first character of
3481 @var{optstring} is a colon, @var{silent}
3482 error reporting is used. In normal operation, diagnostic messages
3483 are printed when invalid options or missing option arguments are
3485 If the variable @env{OPTERR}
3486 is set to 0, no error messages will be displayed, even if the first
3487 character of @code{optstring} is not a colon.
3489 If an invalid option is seen,
3490 @code{getopts} places @samp{?} into @var{name} and, if not silent,
3491 prints an error message and unsets @env{OPTARG}.
3492 If @code{getopts} is silent, the option character found is placed in
3493 @env{OPTARG} and no diagnostic message is printed.
3495 If a required argument is not found, and @code{getopts}
3496 is not silent, a question mark (@samp{?}) is placed in @var{name},
3497 @code{OPTARG} is unset, and a diagnostic message is printed.
3498 If @code{getopts} is silent, then a colon (@samp{:}) is placed in
3499 @var{name} and @env{OPTARG} is set to the option character found.
3504 hash [-r] [-p @var{filename}] [-dt] [@var{name}]
3507 Each time @code{hash} is invoked, it remembers the full pathnames of the
3508 commands specified as @var{name} arguments,
3509 so they need not be searched for on subsequent invocations.
3510 The commands are found by searching through the directories listed in
3512 Any previously-remembered pathname is discarded.
3513 The @option{-p} option inhibits the path search, and @var{filename} is
3514 used as the location of @var{name}.
3515 The @option{-r} option causes the shell to forget all remembered locations.
3516 The @option{-d} option causes the shell to forget the remembered location
3518 If the @option{-t} option is supplied, the full pathname to which each
3519 @var{name} corresponds is printed. If multiple @var{name} arguments are
3520 supplied with @option{-t} the @var{name} is printed before the hashed
3522 The @option{-l} option causes output to be displayed in a format
3523 that may be reused as input.
3524 If no arguments are given, or if only @option{-l} is supplied,
3525 information about remembered commands is printed.
3526 The return status is zero unless a @var{name} is not found or an invalid
3535 Print the absolute pathname of the current working directory.
3536 If the @option{-P} option is supplied, the pathname printed will not
3537 contain symbolic links.
3538 If the @option{-L} option is supplied, the pathname printed may contain
3540 The return status is zero unless an error is encountered while
3541 determining the name of the current directory or an invalid option
3547 readonly [-aAf] [-p] [@var{name}[=@var{value}]] @dots{}
3550 Mark each @var{name} as readonly.
3551 The values of these names may not be changed by subsequent assignment.
3552 If the @option{-f} option is supplied, each @var{name} refers to a shell
3554 The @option{-a} option means each @var{name} refers to an indexed
3555 array variable; the @option{-A} option means each @var{name} refers
3556 to an associative array variable.
3557 If both options are supplied, @option{-A} takes precedence.
3558 If no @var{name} arguments are given, or if the @option{-p}
3559 option is supplied, a list of all readonly names is printed.
3560 The other options may be used to restrict the output to a subset of
3561 the set of readonly names.
3562 The @option{-p} option causes output to be displayed in a format that
3563 may be reused as input.
3564 If a variable name is followed by =@var{value}, the value of
3565 the variable is set to @var{value}.
3566 The return status is zero unless an invalid option is supplied, one of
3567 the @var{name} arguments is not a valid shell variable or function name,
3568 or the @option{-f} option is supplied with a name that is not a shell function.
3576 Cause a shell function to stop executing and return the value @var{n}
3578 If @var{n} is not supplied, the return value is the exit status of the
3579 last command executed in the function.
3580 If @code{return} is executed by a trap handler, the last command used to
3581 determine the status is the last command executed before the trap handler.
3582 if @code{return} is executed during a @code{DEBUG} trap, the last command
3583 used to determine the status is the last command executed by the trap
3584 handler before @code{return} was invoked.
3585 @code{return} may also be used to terminate execution of a script
3586 being executed with the @code{.} (@code{source}) builtin,
3587 returning either @var{n} or
3588 the exit status of the last command executed within the script as the exit
3589 status of the script.
3590 If @var{n} is supplied, the return value is its least significant
3592 Any command associated with the @code{RETURN} trap is executed
3593 before execution resumes after the function or script.
3594 The return status is non-zero if @code{return} is supplied a non-numeric
3595 argument or is used outside a function
3596 and not during the execution of a script by @code{.} or @code{source}.
3604 Shift the positional parameters to the left by @var{n}.
3605 The positional parameters from @var{n}+1 @dots{} @code{$#} are
3606 renamed to @code{$1} @dots{} @code{$#}-@var{n}.
3607 Parameters represented by the numbers @code{$#} to @code{$#}-@var{n}+1
3609 @var{n} must be a non-negative number less than or equal to @code{$#}.
3610 If @var{n} is zero or greater than @code{$#}, the positional parameters
3612 If @var{n} is not supplied, it is assumed to be 1.
3613 The return status is zero unless @var{n} is greater than @code{$#} or
3614 less than zero, non-zero otherwise.
3624 Evaluate a conditional express
3625 ion @var{expr} and return a status of 0
3626 (true) or 1 (false).
3627 Each operator and operand must be a separate argument.
3628 Expressions are composed of the primaries described below in
3629 @ref{Bash Conditional Expressions}.
3630 @code{test} does not accept any options, nor does it accept and ignore
3631 an argument of @option{--} as signifying the end of options.
3633 When the @code{[} form is used, the last argument to the command must
3636 Expressions may be combined using the following operators, listed in
3637 decreasing order of precedence.
3638 The evaluation depends on the number of arguments; see below.
3639 Operator precedence is used when there are five or more arguments.
3643 True if @var{expr} is false.
3645 @item ( @var{expr} )
3646 Returns the value of @var{expr}.
3647 This may be used to override the normal precedence of operators.
3649 @item @var{expr1} -a @var{expr2}
3650 True if both @var{expr1} and @var{expr2} are true.
3652 @item @var{expr1} -o @var{expr2}
3653 True if either @var{expr1} or @var{expr2} is true.
3656 The @code{test} and @code{[} builtins evaluate conditional
3657 expressions using a set of rules based on the number of arguments.
3661 The expression is false.
3664 The expression is true if and only if the argument is not null.
3667 If the first argument is @samp{!}, the expression is true if and
3668 only if the second argument is null.
3669 If the first argument is one of the unary conditional operators
3670 (@pxref{Bash Conditional Expressions}), the expression
3671 is true if the unary test is true.
3672 If the first argument is not a valid unary operator, the expression is
3676 The following conditions are applied in the order listed.
3677 If the second argument is one of the binary conditional
3678 operators (@pxref{Bash Conditional Expressions}), the
3679 result of the expression is the result of the binary test using the
3680 first and third arguments as operands.
3681 The @samp{-a} and @samp{-o} operators are considered binary operators
3682 when there are three arguments.
3683 If the first argument is @samp{!}, the value is the negation of
3684 the two-argument test using the second and third arguments.
3685 If the first argument is exactly @samp{(} and the third argument is
3686 exactly @samp{)}, the result is the one-argument test of the second
3688 Otherwise, the expression is false.
3691 If the first argument is @samp{!}, the result is the negation of
3692 the three-argument expression composed of the remaining arguments.
3693 Otherwise, the expression is parsed and evaluated according to
3694 precedence using the rules listed above.
3696 @item 5 or more arguments
3697 The expression is parsed and evaluated according to precedence
3698 using the rules listed above.
3701 When used with @code{test} or @samp{[}, the @samp{<} and @samp{>}
3702 operators sort lexicographically using ASCII ordering.
3710 Print out the user and system times used by the shell and its children.
3711 The return status is zero.
3716 trap [-lp] [@var{arg}] [@var{sigspec} @dots{}]
3719 The commands in @var{arg} are to be read and executed when the
3720 shell receives signal @var{sigspec}. If @var{arg} is absent (and
3721 there is a single @var{sigspec}) or
3722 equal to @samp{-}, each specified signal's disposition is reset
3723 to the value it had when the shell was started.
3724 If @var{arg} is the null string, then the signal specified by
3725 each @var{sigspec} is ignored by the shell and commands it invokes.
3726 If @var{arg} is not present and @option{-p} has been supplied,
3727 the shell displays the trap commands associated with each @var{sigspec}.
3728 If no arguments are supplied, or
3729 only @option{-p} is given, @code{trap} prints the list of commands
3730 associated with each signal number in a form that may be reused as
3732 The @option{-l} option causes the shell to print a list of signal names
3733 and their corresponding numbers.
3734 Each @var{sigspec} is either a signal name or a signal number.
3735 Signal names are case insensitive and the @code{SIG} prefix is optional.
3738 is @code{0} or @code{EXIT}, @var{arg} is executed when the shell exits.
3739 If a @var{sigspec} is @code{DEBUG}, the command @var{arg} is executed
3740 before every simple command, @code{for} command, @code{case} command,
3741 @code{select} command, every arithmetic @code{for} command, and before
3742 the first command executes in a shell function.
3743 Refer to the description of the @code{extdebug} option to the
3744 @code{shopt} builtin (@pxref{The Shopt Builtin}) for details of its
3745 effect on the @code{DEBUG} trap.
3746 If a @var{sigspec} is @code{RETURN}, the command @var{arg} is executed
3747 each time a shell function or a script executed with the @code{.} or
3748 @code{source} builtins finishes executing.
3750 If a @var{sigspec} is @code{ERR}, the command @var{arg}
3751 is executed whenever
3752 a pipeline (which may consist of a single simple
3753 command), a list, or a compound command returns a
3754 non-zero exit status,
3755 subject to the following conditions.
3756 The @code{ERR} trap is not executed if the failed command is part of the
3757 command list immediately following an @code{until} or @code{while} keyword,
3758 part of the test following the @code{if} or @code{elif} reserved words,
3759 part of a command executed in a @code{&&} or @code{||} list
3760 except the command following the final @code{&&} or @code{||},
3761 any command in a pipeline but the last,
3762 or if the command's return
3763 status is being inverted using @code{!}.
3764 These are the same conditions obeyed by the @code{errexit} (@option{-e})
3767 Signals ignored upon entry to the shell cannot be trapped or reset.
3768 Trapped signals that are not being ignored are reset to their original
3769 values in a subshell or subshell environment when one is created.
3771 The return status is zero unless a @var{sigspec} does not specify a
3777 umask [-p] [-S] [@var{mode}]
3780 Set the shell process's file creation mask to @var{mode}. If
3781 @var{mode} begins with a digit, it is interpreted as an octal number;
3782 if not, it is interpreted as a symbolic mode mask similar
3783 to that accepted by the @code{chmod} command. If @var{mode} is
3784 omitted, the current value of the mask is printed. If the @option{-S}
3785 option is supplied without a @var{mode} argument, the mask is printed
3786 in a symbolic format.
3787 If the @option{-p} option is supplied, and @var{mode}
3788 is omitted, the output is in a form that may be reused as input.
3789 The return status is zero if the mode is successfully changed or if
3790 no @var{mode} argument is supplied, and non-zero otherwise.
3792 Note that when the mode is interpreted as an octal number, each number
3793 of the umask is subtracted from @code{7}. Thus, a umask of @code{022}
3794 results in permissions of @code{755}.
3799 unset [-fnv] [@var{name}]
3802 Remove each variable or function @var{name}.
3803 If the @option{-v} option is given, each
3804 @var{name} refers to a shell variable and that variable is remvoved.
3805 If the @option{-f} option is given, the @var{name}s refer to shell
3806 functions, and the function definition is removed.
3807 If the @option{-n} option is supplied, and @var{name} is a variable with
3808 the @var{nameref} attribute, @var{name} will be unset rather than the
3809 variable it references.
3810 @option{-n} has no effect if the @option{-f} option is supplied.
3811 If no options are supplied, each @var{name} refers to a variable; if
3812 there is no variable by that name, any function with that name is
3814 Readonly variables and functions may not be unset.
3815 The return status is zero unless a @var{name} is readonly.
3819 @section Bash Builtin Commands
3821 This section describes builtin commands which are unique to
3822 or have been extended in Bash.
3823 Some of these commands are specified in the @sc{posix} standard.
3830 alias [-p] [@var{name}[=@var{value}] @dots{}]
3833 Without arguments or with the @option{-p} option, @code{alias} prints
3834 the list of aliases on the standard output in a form that allows
3835 them to be reused as input.
3836 If arguments are supplied, an alias is defined for each @var{name}
3837 whose @var{value} is given. If no @var{value} is given, the name
3838 and value of the alias is printed.
3839 Aliases are described in @ref{Aliases}.
3844 bind [-m @var{keymap}] [-lpsvPSVX]
3845 bind [-m @var{keymap}] [-q @var{function}] [-u @var{function}] [-r @var{keyseq}]
3846 bind [-m @var{keymap}] -f @var{filename}
3847 bind [-m @var{keymap}] -x @var{keyseq:shell-command}
3848 bind [-m @var{keymap}] @var{keyseq:function-name}
3849 bind [-m @var{keymap}] @var{keyseq:readline-command}
3852 Display current Readline (@pxref{Command Line Editing})
3853 key and function bindings,
3854 bind a key sequence to a Readline function or macro,
3855 or set a Readline variable.
3856 Each non-option argument is a command as it would appear in a
3857 Readline initialization file (@pxref{Readline Init File}),
3858 but each binding or command must be passed as a separate argument; e.g.,
3859 @samp{"\C-x\C-r":re-read-init-file}.
3861 Options, if supplied, have the following meanings:
3864 @item -m @var{keymap}
3865 Use @var{keymap} as the keymap to be affected by
3866 the subsequent bindings. Acceptable @var{keymap}
3869 @code{emacs-standard},
3874 @code{vi-command}, and
3876 @code{vi} is equivalent to @code{vi-command} (@code{vi-move} is also a
3877 synonym); @code{emacs} is equivalent to @code{emacs-standard}.
3880 List the names of all Readline functions.
3883 Display Readline function names and bindings in such a way that they
3884 can be used as input or in a Readline initialization file.
3887 List current Readline function names and bindings.
3890 Display Readline variable names and values in such a way that they
3891 can be used as input or in a Readline initialization file.
3894 List current Readline variable names and values.
3897 Display Readline key sequences bound to macros and the strings they output
3898 in such a way that they can be used as input or in a Readline
3899 initialization file.
3902 Display Readline key sequences bound to macros and the strings they output.
3904 @item -f @var{filename}
3905 Read key bindings from @var{filename}.
3907 @item -q @var{function}
3908 Query about which keys invoke the named @var{function}.
3910 @item -u @var{function}
3911 Unbind all keys bound to the named @var{function}.
3913 @item -r @var{keyseq}
3914 Remove any current binding for @var{keyseq}.
3916 @item -x @var{keyseq:shell-command}
3917 Cause @var{shell-command} to be executed whenever @var{keyseq} is
3919 When @var{shell-command} is executed, the shell sets the
3920 @code{READLINE_LINE} variable to the contents of the Readline line
3921 buffer and the @code{READLINE_POINT} variable to the current location
3922 of the insertion point.
3923 If the executed command changes the value of @code{READLINE_LINE} or
3924 @code{READLINE_POINT}, those new values will be reflected in the
3928 List all key sequences bound to shell commands and the associated commands
3929 in a format that can be reused as input.
3933 The return status is zero unless an invalid option is supplied or an
3939 builtin [@var{shell-builtin} [@var{args}]]
3942 Run a shell builtin, passing it @var{args}, and return its exit status.
3943 This is useful when defining a shell function with the same
3944 name as a shell builtin, retaining the functionality of the builtin within
3946 The return status is non-zero if @var{shell-builtin} is not a shell
3955 Returns the context of any active subroutine call (a shell function or
3956 a script executed with the @code{.} or @code{source} builtins).
3958 Without @var{expr}, @code{caller} displays the line number and source
3959 filename of the current subroutine call.
3960 If a non-negative integer is supplied as @var{expr}, @code{caller}
3961 displays the line number, subroutine name, and source file corresponding
3962 to that position in the current execution call stack. This extra
3963 information may be used, for example, to print a stack trace. The
3964 current frame is frame 0.
3966 The return value is 0 unless the shell is not executing a subroutine
3967 call or @var{expr} does not correspond to a valid position in the
3973 command [-pVv] @var{command} [@var{arguments} @dots{}]
3976 Runs @var{command} with @var{arguments} ignoring any shell function
3977 named @var{command}.
3978 Only shell builtin commands or commands found by searching the
3979 @env{PATH} are executed.
3980 If there is a shell function named @code{ls}, running @samp{command ls}
3981 within the function will execute the external command @code{ls}
3982 instead of calling the function recursively.
3983 The @option{-p} option means to use a default value for @env{PATH}
3984 that is guaranteed to find all of the standard utilities.
3985 The return status in this case is 127 if @var{command} cannot be
3986 found or an error occurred, and the exit status of @var{command}
3989 If either the @option{-V} or @option{-v} option is supplied, a
3990 description of @var{command} is printed. The @option{-v} option
3991 causes a single word indicating the command or file name used to
3992 invoke @var{command} to be displayed; the @option{-V} option produces
3993 a more verbose description. In this case, the return status is
3994 zero if @var{command} is found, and non-zero if not.
3999 declare [-aAfFgilnrtux] [-p] [@var{name}[=@var{value}] @dots{}]
4002 Declare variables and give them attributes. If no @var{name}s
4003 are given, then display the values of variables instead.
4005 The @option{-p} option will display the attributes and values of each
4007 When @option{-p} is used with @var{name} arguments, additional options,
4008 other than @option{-f} and @option{-F}, are ignored.
4010 When @option{-p} is supplied without @var{name} arguments, @code{declare}
4011 will display the attributes and values of all variables having the
4012 attributes specified by the additional options.
4013 If no other options are supplied with @option{-p}, @code{declare} will
4014 display the attributes and values of all shell variables. The @option{-f}
4015 option will restrict the display to shell functions.
4017 The @option{-F} option inhibits the display of function definitions;
4018 only the function name and attributes are printed.
4019 If the @code{extdebug} shell option is enabled using @code{shopt}
4020 (@pxref{The Shopt Builtin}), the source file name and line number where
4021 each @var{name} is defined are displayed as well.
4022 @option{-F} implies @option{-f}.
4024 The @option{-g} option forces variables to be created or modified at
4025 the global scope, even when @code{declare} is executed in a shell function.
4026 It is ignored in all other cases.
4028 The following options can be used to restrict output to variables with
4029 the specified attributes or to give variables attributes:
4033 Each @var{name} is an indexed array variable (@pxref{Arrays}).
4036 Each @var{name} is an associative array variable (@pxref{Arrays}).
4039 Use function names only.
4042 The variable is to be treated as
4043 an integer; arithmetic evaluation (@pxref{Shell Arithmetic}) is
4044 performed when the variable is assigned a value.
4047 When the variable is assigned a value, all upper-case characters are
4048 converted to lower-case.
4049 The upper-case attribute is disabled.
4052 Give each @var{name} the @var{nameref} attribute, making
4053 it a name reference to another variable.
4054 That other variable is defined by the value of @var{name}.
4055 All references, assignments, and attribute modifications
4056 to @var{name}, except for changing the
4057 @option{-n} attribute itself, are performed on the variable referenced by
4059 The nameref attribute cannot be applied to array variables.
4062 Make @var{name}s readonly. These names cannot then be assigned values
4063 by subsequent assignment statements or unset.
4066 Give each @var{name} the @code{trace} attribute.
4067 Traced functions inherit the @code{DEBUG} and @code{RETURN} traps from
4069 The trace attribute has no special meaning for variables.
4072 When the variable is assigned a value, all lower-case characters are
4073 converted to upper-case.
4074 The lower-case attribute is disabled.
4077 Mark each @var{name} for export to subsequent commands via
4081 Using @samp{+} instead of @samp{-} turns off the attribute instead,
4082 with the exceptions that @samp{+a}
4083 may not be used to destroy an array variable and @samp{+r} will not
4084 remove the readonly attribute.
4085 When used in a function, @code{declare} makes each @var{name} local,
4086 as with the @code{local} command, unless the @option{-g} option is used.
4087 If a variable name is followed by =@var{value}, the value of the variable
4088 is set to @var{value}.
4090 When using @option{-a} or @option{-A} and the compound assignment syntax to
4091 create array variables, additional attributes do not take effect until
4092 subsequent assignments.
4094 The return status is zero unless an invalid option is encountered,
4095 an attempt is made to define a function using @samp{-f foo=bar},
4096 an attempt is made to assign a value to a readonly variable,
4097 an attempt is made to assign a value to an array variable without
4098 using the compound assignment syntax (@pxref{Arrays}),
4099 one of the @var{names} is not a valid shell variable name,
4100 an attempt is made to turn off readonly status for a readonly variable,
4101 an attempt is made to turn off array status for an array variable,
4102 or an attempt is made to display a non-existent function with @option{-f}.
4107 echo [-neE] [@var{arg} @dots{}]
4110 Output the @var{arg}s, separated by spaces, terminated with a
4112 The return status is 0 unless a write error occurs.
4113 If @option{-n} is specified, the trailing newline is suppressed.
4114 If the @option{-e} option is given, interpretation of the following
4115 backslash-escaped characters is enabled.
4116 The @option{-E} option disables the interpretation of these escape characters,
4117 even on systems where they are interpreted by default.
4118 The @code{xpg_echo} shell option may be used to
4119 dynamically determine whether or not @code{echo} expands these
4120 escape characters by default.
4121 @code{echo} does not interpret @option{--} to mean the end of options.
4123 @code{echo} interprets the following escape sequences:
4130 suppress further output
4147 the eight-bit character whose value is the octal value @var{nnn}
4148 (zero to three octal digits)
4150 the eight-bit character whose value is the hexadecimal value @var{HH}
4151 (one or two hex digits)
4153 the Unicode (ISO/IEC 10646) character whose value is the hexadecimal value
4154 @var{HHHH} (one to four hex digits)
4155 @item \U@var{HHHHHHHH}
4156 the Unicode (ISO/IEC 10646) character whose value is the hexadecimal value
4157 @var{HHHHHHHH} (one to eight hex digits)
4163 enable [-a] [-dnps] [-f @var{filename}] [@var{name} @dots{}]
4166 Enable and disable builtin shell commands.
4167 Disabling a builtin allows a disk command which has the same name
4168 as a shell builtin to be executed without specifying a full pathname,
4169 even though the shell normally searches for builtins before disk commands.
4170 If @option{-n} is used, the @var{name}s become disabled. Otherwise
4171 @var{name}s are enabled. For example, to use the @code{test} binary
4172 found via @env{$PATH} instead of the shell builtin version, type
4173 @samp{enable -n test}.
4175 If the @option{-p} option is supplied, or no @var{name} arguments appear,
4176 a list of shell builtins is printed. With no other arguments, the list
4177 consists of all enabled shell builtins.
4178 The @option{-a} option means to list
4179 each builtin with an indication of whether or not it is enabled.
4181 The @option{-f} option means to load the new builtin command @var{name}
4182 from shared object @var{filename}, on systems that support dynamic loading.
4183 The @option{-d} option will delete a builtin loaded with @option{-f}.
4185 If there are no options, a list of the shell builtins is displayed.
4186 The @option{-s} option restricts @code{enable} to the @sc{posix} special
4187 builtins. If @option{-s} is used with @option{-f}, the new builtin becomes
4188 a special builtin (@pxref{Special Builtins}).
4190 The return status is zero unless a @var{name} is not a shell builtin
4191 or there is an error loading a new builtin from a shared object.
4196 help [-dms] [@var{pattern}]
4199 Display helpful information about builtin commands.
4200 If @var{pattern} is specified, @code{help} gives detailed help
4201 on all commands matching @var{pattern}, otherwise a list of
4202 the builtins is printed.
4204 Options, if supplied, have the following meanings:
4208 Display a short description of each @var{pattern}
4210 Display the description of each @var{pattern} in a manpage-like format
4212 Display only a short usage synopsis for each @var{pattern}
4215 The return status is zero unless no command matches @var{pattern}.
4220 let @var{expression} [@var{expression} @dots{}]
4223 The @code{let} builtin allows arithmetic to be performed on shell
4224 variables. Each @var{expression} is evaluated according to the
4225 rules given below in @ref{Shell Arithmetic}. If the
4226 last @var{expression} evaluates to 0, @code{let} returns 1;
4227 otherwise 0 is returned.
4232 local [@var{option}] @var{name}[=@var{value}] @dots{}
4235 For each argument, a local variable named @var{name} is created,
4236 and assigned @var{value}.
4237 The @var{option} can be any of the options accepted by @code{declare}.
4238 @code{local} can only be used within a function; it makes the variable
4239 @var{name} have a visible scope restricted to that function and its
4241 If @var{name} is @samp{-}, the set of shell options is made local to the
4242 function in which @code{local} is invoked: shell options changed using
4243 the @code{set} builtin inside the function are restored to their original
4244 values when the function returns.
4245 The return status is zero unless @code{local} is used outside
4246 a function, an invalid @var{name} is supplied, or @var{name} is a
4255 Exit a login shell, returning a status of @var{n} to the shell's
4261 mapfile [-d @var{delim}] [-n @var{count}] [-O @var{origin}] [-s @var{count}] [-t] [-u @var{fd}]
4262 [-C @var{callback}] [-c @var{quantum}] [@var{array}]
4265 Read lines from the standard input into the indexed array variable @var{array},
4266 or from file descriptor @var{fd}
4267 if the @option{-u} option is supplied.
4268 The variable @code{MAPFILE} is the default @var{array}.
4269 Options, if supplied, have the following meanings:
4274 The first character of @var{delim} is used to terminate each input line,
4275 rather than newline.
4277 Copy at most @var{count} lines. If @var{count} is 0, all lines are copied.
4279 Begin assigning to @var{array} at index @var{origin}.
4280 The default index is 0.
4282 Discard the first @var{count} lines read.
4284 Remove a trailing @var{delim} (default newline) from each line read.
4286 Read lines from file descriptor @var{fd} instead of the standard input.
4288 Evaluate @var{callback} each time @var{quantum}P lines are read.
4289 The @option{-c} option specifies @var{quantum}.
4291 Specify the number of lines read between each call to @var{callback}.
4294 If @option{-C} is specified without @option{-c},
4295 the default quantum is 5000.
4296 When @var{callback} is evaluated, it is supplied the index of the next
4297 array element to be assigned and the line to be assigned to that element
4298 as additional arguments.
4299 @var{callback} is evaluated after the line is read but before the
4300 array element is assigned.
4302 If not supplied with an explicit origin, @code{mapfile} will clear @var{array}
4303 before assigning to it.
4305 @code{mapfile} returns successfully unless an invalid option or option
4306 argument is supplied, @var{array} is invalid or unassignable, or @var{array}
4307 is not an indexed array.
4312 printf [-v @var{var}] @var{format} [@var{arguments}]
4315 Write the formatted @var{arguments} to the standard output under the
4316 control of the @var{format}.
4317 The @option{-v} option causes the output to be assigned to the variable
4318 @var{var} rather than being printed to the standard output.
4320 The @var{format} is a character string which contains three types of objects:
4321 plain characters, which are simply copied to standard output, character
4322 escape sequences, which are converted and copied to the standard output, and
4323 format specifications, each of which causes printing of the next successive
4325 In addition to the standard @code{printf(1)} formats, @code{printf}
4326 interprets the following extensions:
4330 Causes @code{printf} to expand backslash escape sequences in the
4331 corresponding @var{argument} in the same way as @code{echo -e}
4332 (@pxref{Bash Builtins}).
4334 Causes @code{printf} to output the
4335 corresponding @var{argument} in a format that can be reused as shell input.
4336 @item %(@var{datefmt})T
4337 Causes @code{printf} to output the date-time string resulting from using
4338 @var{datefmt} as a format string for @code{strftime}(3).
4339 The corresponding @var{argument} is an integer representing the number of
4340 seconds since the epoch.
4341 Two special argument values may be used: -1 represents the current
4342 time, and -2 represents the time the shell was invoked.
4343 If no argument is specified, conversion behaves as if -1 had been given.
4344 This is an exception to the usual @code{printf} behavior.
4348 Arguments to non-string format specifiers are treated as C language constants,
4349 except that a leading plus or minus sign is allowed, and if the leading
4350 character is a single or double quote, the value is the ASCII value of
4351 the following character.
4353 The @var{format} is reused as necessary to consume all of the @var{arguments}.
4354 If the @var{format} requires more @var{arguments} than are supplied, the
4355 extra format specifications behave as if a zero value or null string, as
4356 appropriate, had been supplied. The return value is zero on success,
4357 non-zero on failure.
4362 read [-ers] [-a @var{aname}] [-d @var{delim}] [-i @var{text}] [-n @var{nchars}]
4363 [-N @var{nchars}] [-p @var{prompt}] [-t @var{timeout}] [-u @var{fd}] [@var{name} @dots{}]
4366 One line is read from the standard input, or from the file descriptor
4367 @var{fd} supplied as an argument to the @option{-u} option,
4368 split into words as described above in @ref{Word Splitting},
4370 is assigned to the first @var{name}, the second word to the second @var{name},
4372 If there are more words than names,
4373 the remaining words and their intervening delimiters are assigned
4374 to the last @var{name}.
4375 If there are fewer words read from the input stream than names,
4376 the remaining names are assigned empty values.
4377 The characters in the value of the @env{IFS} variable
4378 are used to split the line into words using the same rules the shell
4379 uses for expansion (described above in @ref{Word Splitting}).
4380 The backslash character @samp{\} may be used to remove any special
4381 meaning for the next character read and for line continuation.
4382 If no names are supplied, the line read is assigned to the
4383 variable @env{REPLY}.
4384 The exit status is zero, unless end-of-file is encountered, @code{read}
4385 times out (in which case the status is greater than 128),
4386 a variable assignment error (such as assigning to a readonly variable) occurs,
4387 or an invalid file descriptor is supplied as the argument to @option{-u}.
4389 Options, if supplied, have the following meanings:
4392 @item -a @var{aname}
4393 The words are assigned to sequential indices of the array variable
4394 @var{aname}, starting at 0.
4395 All elements are removed from @var{aname} before the assignment.
4396 Other @var{name} arguments are ignored.
4398 @item -d @var{delim}
4399 The first character of @var{delim} is used to terminate the input line,
4400 rather than newline.
4403 Readline (@pxref{Command Line Editing}) is used to obtain the line.
4404 Readline uses the current (or default, if line editing was not previously
4405 active) editing settings.
4408 If Readline is being used to read the line, @var{text} is placed into
4409 the editing buffer before editing begins.
4411 @item -n @var{nchars}
4412 @code{read} returns after reading @var{nchars} characters rather than
4413 waiting for a complete line of input, but honors a delimiter if fewer
4414 than @var{nchars} characters are read before the delimiter.
4416 @item -N @var{nchars}
4417 @code{read} returns after reading exactly @var{nchars} characters rather
4418 than waiting for a complete line of input, unless EOF is encountered or
4419 @code{read} times out.
4420 Delimiter characters encountered in the input are
4421 not treated specially and do not cause @code{read} to return until
4422 @var{nchars} characters are read.
4423 The result is not split on the characters in @code{IFS}; the intent is
4424 that the variable is assigned exactly the characters read
4425 (with the exception of backslash; see the @option{-r} option below).
4427 @item -p @var{prompt}
4428 Display @var{prompt}, without a trailing newline, before attempting
4430 The prompt is displayed only if input is coming from a terminal.
4433 If this option is given, backslash does not act as an escape character.
4434 The backslash is considered to be part of the line.
4435 In particular, a backslash-newline pair may not be used as a line
4439 Silent mode. If input is coming from a terminal, characters are
4442 @item -t @var{timeout}
4443 Cause @code{read} to time out and return failure if a complete line of
4444 input (or a specified number of characters)
4445 is not read within @var{timeout} seconds.
4446 @var{timeout} may be a decimal number with a fractional portion following
4448 This option is only effective if @code{read} is reading input from a
4449 terminal, pipe, or other special file; it has no effect when reading
4451 If @code{read} times out, @code{read} saves any partial input read into
4452 the specified variable @var{name}.
4453 If @var{timeout} is 0, @code{read} returns immediately, without trying to
4454 read and data. The exit status is 0 if input is available on
4455 the specified file descriptor, non-zero otherwise.
4456 The exit status is greater than 128 if the timeout is exceeded.
4459 Read input from file descriptor @var{fd}.
4465 readarray [-d @var{delim}] [-n @var{count}] [-O @var{origin}] [-s @var{count}] [-t] [-u @var{fd}]
4466 [-C @var{callback}] [-c @var{quantum}] [@var{array}]
4469 Read lines from the standard input into the indexed array variable @var{array},
4470 or from file descriptor @var{fd}
4471 if the @option{-u} option is supplied.
4473 A synonym for @code{mapfile}.
4478 source @var{filename}
4481 A synonym for @code{.} (@pxref{Bourne Shell Builtins}).
4486 type [-afptP] [@var{name} @dots{}]
4489 For each @var{name}, indicate how it would be interpreted if used as a
4492 If the @option{-t} option is used, @code{type} prints a single word
4493 which is one of @samp{alias}, @samp{function}, @samp{builtin},
4494 @samp{file} or @samp{keyword},
4495 if @var{name} is an alias, shell function, shell builtin,
4496 disk file, or shell reserved word, respectively.
4497 If the @var{name} is not found, then nothing is printed, and
4498 @code{type} returns a failure status.
4500 If the @option{-p} option is used, @code{type} either returns the name
4501 of the disk file that would be executed, or nothing if @option{-t}
4502 would not return @samp{file}.
4504 The @option{-P} option forces a path search for each @var{name}, even if
4505 @option{-t} would not return @samp{file}.
4507 If a command is hashed, @option{-p} and @option{-P} print the hashed value,
4508 which is not necessarily the file that appears first in @code{$PATH}.
4510 If the @option{-a} option is used, @code{type} returns all of the places
4511 that contain an executable named @var{file}.
4512 This includes aliases and functions, if and only if the @option{-p} option
4515 If the @option{-f} option is used, @code{type} does not attempt to find
4516 shell functions, as with the @code{command} builtin.
4518 The return status is zero if all of the @var{names} are found, non-zero
4519 if any are not found.
4524 typeset [-afFgrxilnrtux] [-p] [@var{name}[=@var{value}] @dots{}]
4527 The @code{typeset} command is supplied for compatibility with the Korn
4529 It is a synonym for the @code{declare} builtin command.
4534 ulimit [-HSabcdefiklmnpqrstuvxPT] [@var{limit}]
4537 @code{ulimit} provides control over the resources available to processes
4538 started by the shell, on systems that allow such control. If an
4539 option is given, it is interpreted as follows:
4543 Change and report the soft limit associated with a resource.
4546 Change and report the hard limit associated with a resource.
4549 All current limits are reported.
4552 The maximum socket buffer size.
4555 The maximum size of core files created.
4558 The maximum size of a process's data segment.
4561 The maximum scheduling priority ("nice").
4564 The maximum size of files written by the shell and its children.
4567 The maximum number of pending signals.
4570 The maximum number of kqueues that may be allocated.
4573 The maximum size that may be locked into memory.
4576 The maximum resident set size (many systems do not honor this limit).
4579 The maximum number of open file descriptors (most systems do not
4580 allow this value to be set).
4583 The pipe buffer size.
4586 The maximum number of bytes in POSIX message queues.
4589 The maximum real-time scheduling priority.
4592 The maximum stack size.
4595 The maximum amount of cpu time in seconds.
4598 The maximum number of processes available to a single user.
4601 The maximum amount of virtual memory available to the shell, and, on
4602 some systems, to its children.
4605 The maximum number of file locks.
4608 The maximum number of pseudoterminals.
4611 The maximum number of threads.
4614 If @var{limit} is given, and the @option{-a} option is not used,
4615 @var{limit} is the new value of the specified resource.
4616 The special @var{limit} values @code{hard}, @code{soft}, and
4617 @code{unlimited} stand for the current hard limit, the current soft limit,
4618 and no limit, respectively.
4619 A hard limit cannot be increased by a non-root user once it is set;
4620 a soft limit may be increased up to the value of the hard limit.
4621 Otherwise, the current value of the soft limit for the specified resource
4622 is printed, unless the @option{-H} option is supplied.
4623 When setting new limits, if neither @option{-H} nor @option{-S} is supplied,
4624 both the hard and soft limits are set.
4625 If no option is given, then @option{-f} is assumed. Values are in 1024-byte
4626 increments, except for @option{-t}, which is in seconds; @option{-p},
4627 which is in units of 512-byte blocks;
4632 @option{-n} and @option{-u}, which are unscaled values;
4633 and, when in @sc{posix} Mode (@pxref{Bash POSIX Mode}),
4634 @option{-c} and @option{-f}, which are in 512-byte increments.
4636 The return status is zero unless an invalid option or argument is supplied,
4637 or an error occurs while setting a new limit.
4642 unalias [-a] [@var{name} @dots{} ]
4645 Remove each @var{name} from the list of aliases. If @option{-a} is
4646 supplied, all aliases are removed.
4647 Aliases are described in @ref{Aliases}.
4650 @node Modifying Shell Behavior
4651 @section Modifying Shell Behavior
4654 * The Set Builtin:: Change the values of shell attributes and
4655 positional parameters.
4656 * The Shopt Builtin:: Modify shell optional behavior.
4659 @node The Set Builtin
4660 @subsection The Set Builtin
4662 This builtin is so complicated that it deserves its own section. @code{set}
4663 allows you to change the values of shell options and set the positional
4664 parameters, or to display the names and values of shell variables.
4670 set [--abefhkmnptuvxBCEHPT] [-o @var{option-name}] [@var{argument} @dots{}]
4671 set [+abefhkmnptuvxBCEHPT] [+o @var{option-name}] [@var{argument} @dots{}]
4674 If no options or arguments are supplied, @code{set} displays the names
4675 and values of all shell variables and functions, sorted according to the
4676 current locale, in a format that may be reused as input
4677 for setting or resetting the currently-set variables.
4678 Read-only variables cannot be reset.
4679 In @sc{posix} mode, only shell variables are listed.
4681 When options are supplied, they set or unset shell attributes.
4682 Options, if specified, have the following meanings:
4686 Each variable or function that is created or modified is given the
4687 export attribute and marked for export to the environment of
4688 subsequent commands.
4691 Cause the status of terminated background jobs to be reported
4692 immediately, rather than before printing the next primary prompt.
4696 a pipeline (@pxref{Pipelines}), which may consist of a single simple command
4697 (@pxref{Simple Commands}),
4698 a list (@pxref{Lists}),
4699 or a compound command (@pxref{Compound Commands})
4700 returns a non-zero status.
4701 The shell does not exit if the command that fails is part of the
4702 command list immediately following a @code{while} or @code{until} keyword,
4703 part of the test in an @code{if} statement,
4704 part of any command executed in a @code{&&} or @code{||} list except
4705 the command following the final @code{&&} or @code{||},
4706 any command in a pipeline but the last,
4707 or if the command's return status is being inverted with @code{!}.
4708 If a compound command other than a subshell
4709 returns a non-zero status because a command failed
4710 while @option{-e} was being ignored, the shell does not exit.
4711 A trap on @code{ERR}, if set, is executed before the shell exits.
4713 This option applies to the shell environment and each subshell environment
4714 separately (@pxref{Command Execution Environment}), and may cause
4715 subshells to exit before executing all the commands in the subshell.
4717 If a compound command or shell function executes in a context where
4718 @option{-e} is being ignored,
4719 none of the commands executed within the compound command or function body
4720 will be affected by the @option{-e} setting, even if @option{-e} is set
4721 and a command returns a failure status.
4722 If a compound command or shell function sets @option{-e} while executing in
4723 a context where @option{-e} is ignored, that setting will not have any
4724 effect until the compound command or the command containing the function
4728 Disable filename expansion (globbing).
4731 Locate and remember (hash) commands as they are looked up for execution.
4732 This option is enabled by default.
4735 All arguments in the form of assignment statements are placed
4736 in the environment for a command, not just those that precede
4740 Job control is enabled (@pxref{Job Control}).
4741 All processes run in a separate process group.
4742 When a background job completes, the shell prints a line
4743 containing its exit status.
4746 Read commands but do not execute them.
4747 This may be used to check a script for syntax errors.
4748 This option is ignored by interactive shells.
4750 @item -o @var{option-name}
4752 Set the option corresponding to @var{option-name}:
4762 Use an @code{emacs}-style line editing interface (@pxref{Command Line Editing}).
4763 This also affects the editing interface used for @code{read -e}.
4781 Enable command history, as described in @ref{Bash History Facilities}.
4782 This option is on by default in interactive shells.
4785 An interactive shell will not exit upon reading EOF.
4818 If set, the return value of a pipeline is the value of the last
4819 (rightmost) command to exit with a non-zero status, or zero if all
4820 commands in the pipeline exit successfully.
4821 This option is disabled by default.
4824 Change the behavior of Bash where the default operation differs
4825 from the @sc{posix} standard to match the standard
4826 (@pxref{Bash POSIX Mode}).
4827 This is intended to make Bash behave as a strict superset of that
4837 Use a @code{vi}-style line editing interface.
4838 This also affects the editing interface used for @code{read -e}.
4845 Turn on privileged mode.
4846 In this mode, the @env{$BASH_ENV} and @env{$ENV} files are not
4847 processed, shell functions are not inherited from the environment,
4848 and the @env{SHELLOPTS}, @env{BASHOPTS}, @env{CDPATH} and @env{GLOBIGNORE}
4849 variables, if they appear in the environment, are ignored.
4850 If the shell is started with the effective user (group) id not equal to the
4851 real user (group) id, and the @option{-p} option is not supplied, these actions
4852 are taken and the effective user id is set to the real user id.
4853 If the @option{-p} option is supplied at startup, the effective user id is
4855 Turning this option off causes the effective user
4856 and group ids to be set to the real user and group ids.
4859 Exit after reading and executing one command.
4862 Treat unset variables and parameters other than the special parameters
4863 @samp{@@} or @samp{*} as an error when performing parameter expansion.
4864 An error message will be written to the standard error, and a non-interactive
4868 Print shell input lines as they are read.
4871 Print a trace of simple commands, @code{for} commands, @code{case}
4872 commands, @code{select} commands, and arithmetic @code{for} commands
4873 and their arguments or associated word lists after they are
4874 expanded and before they are executed. The value of the @env{PS4}
4875 variable is expanded and the resultant value is printed before
4876 the command and its expanded arguments.
4879 The shell will perform brace expansion (@pxref{Brace Expansion}).
4880 This option is on by default.
4883 Prevent output redirection using @samp{>}, @samp{>&}, and @samp{<>}
4884 from overwriting existing files.
4887 If set, any trap on @code{ERR} is inherited by shell functions, command
4888 substitutions, and commands executed in a subshell environment.
4889 The @code{ERR} trap is normally not inherited in such cases.
4892 Enable @samp{!} style history substitution (@pxref{History Interaction}).
4893 This option is on by default for interactive shells.
4896 If set, do not resolve symbolic links when performing commands such as
4897 @code{cd} which change the current directory. The physical directory
4898 is used instead. By default, Bash follows
4899 the logical chain of directories when performing commands
4900 which change the current directory.
4902 For example, if @file{/usr/sys} is a symbolic link to @file{/usr/local/sys}
4905 $ cd /usr/sys; echo $PWD
4912 If @code{set -P} is on, then:
4914 $ cd /usr/sys; echo $PWD
4921 If set, any trap on @code{DEBUG} and @code{RETURN} are inherited by
4922 shell functions, command substitutions, and commands executed
4923 in a subshell environment.
4924 The @code{DEBUG} and @code{RETURN} traps are normally not inherited
4928 If no arguments follow this option, then the positional parameters are
4929 unset. Otherwise, the positional parameters are set to the
4930 @var{arguments}, even if some of them begin with a @samp{-}.
4933 Signal the end of options, cause all remaining @var{arguments}
4934 to be assigned to the positional parameters. The @option{-x}
4935 and @option{-v} options are turned off.
4936 If there are no arguments, the positional parameters remain unchanged.
4939 Using @samp{+} rather than @samp{-} causes these options to be
4940 turned off. The options can also be used upon invocation of the
4941 shell. The current set of options may be found in @code{$-}.
4943 The remaining N @var{arguments} are positional parameters and are
4944 assigned, in order, to @code{$1}, @code{$2}, @dots{} @code{$N}.
4945 The special parameter @code{#} is set to N.
4947 The return status is always zero unless an invalid option is supplied.
4950 @node The Shopt Builtin
4951 @subsection The Shopt Builtin
4953 This builtin allows you to change additional shell optional behavior.
4960 shopt [-pqsu] [-o] [@var{optname} @dots{}]
4963 Toggle the values of settings controlling optional shell behavior.
4964 The settings can be either those listed below, or, if the
4965 @option{-o} option is used, those available with the @option{-o}
4966 option to the @code{set} builtin command (@pxref{The Set Builtin}).
4967 With no options, or with the @option{-p} option, a list of all settable
4968 options is displayed, with an indication of whether or not each is set.
4969 The @option{-p} option causes output to be displayed in a form that
4970 may be reused as input.
4971 Other options have the following meanings:
4975 Enable (set) each @var{optname}.
4978 Disable (unset) each @var{optname}.
4981 Suppresses normal output; the return status
4982 indicates whether the @var{optname} is set or unset.
4983 If multiple @var{optname} arguments are given with @option{-q},
4984 the return status is zero if all @var{optnames} are enabled;
4988 Restricts the values of
4989 @var{optname} to be those defined for the @option{-o} option to the
4990 @code{set} builtin (@pxref{The Set Builtin}).
4993 If either @option{-s} or @option{-u}
4994 is used with no @var{optname} arguments, @code{shopt} shows only
4995 those options which are set or unset, respectively.
4997 Unless otherwise noted, the @code{shopt} options are disabled (off)
5000 The return status when listing options is zero if all @var{optnames}
5001 are enabled, non-zero otherwise. When setting or unsetting options,
5002 the return status is zero unless an @var{optname} is not a valid shell
5005 The list of @code{shopt} options is:
5009 If set, a command name that is the name of a directory is executed as if
5010 it were the argument to the @code{cd} command.
5011 This option is only used by interactive shells.
5014 If this is set, an argument to the @code{cd} builtin command that
5015 is not a directory is assumed to be the name of a variable whose
5016 value is the directory to change to.
5019 If set, minor errors in the spelling of a directory component in a
5020 @code{cd} command will be corrected.
5021 The errors checked for are transposed characters,
5022 a missing character, and a character too many.
5023 If a correction is found, the corrected path is printed,
5024 and the command proceeds.
5025 This option is only used by interactive shells.
5028 If this is set, Bash checks that a command found in the hash
5029 table exists before trying to execute it. If a hashed command no
5030 longer exists, a normal path search is performed.
5033 If set, Bash lists the status of any stopped and running jobs before
5034 exiting an interactive shell. If any jobs are running, this causes
5035 the exit to be deferred until a second exit is attempted without an
5036 intervening command (@pxref{Job Control}).
5037 The shell always postpones exiting if any jobs are stopped.
5040 If set, Bash checks the window size after each command
5041 and, if necessary, updates the values of
5042 @env{LINES} and @env{COLUMNS}.
5046 attempts to save all lines of a multiple-line
5047 command in the same history entry. This allows
5048 easy re-editing of multi-line commands.
5052 changes its behavior to that of version 3.1 with respect to quoted
5053 arguments to the conditional command's @samp{=~} operator
5054 and with respect to locale-specific
5055 string comparison when using the @code{[[}
5056 conditional command's @samp{<} and @samp{>} operators.
5057 Bash versions prior to bash-4.1 use ASCII collation and strcmp(3);
5058 bash-4.1 and later use the current locale's collation sequence and strcoll(3).
5062 changes its behavior to that of version 3.2 with respect to locale-specific
5063 string comparison when using the @code{[[}
5064 conditional command's @samp{<} and @samp{>} operators (see previous item)
5065 and the effect of interrupting a command list.
5066 Bash versions 3.2 and earlier continue with the next command in the list
5067 after one terminates due to an interrupt.
5071 changes its behavior to that of version 4.0 with respect to locale-specific
5072 string comparison when using the @code{[[}
5073 conditional command's @samp{<} and @samp{>} operators (see description
5075 and the effect of interrupting a command list.
5076 Bash versions 4.0 and later interrupt the list as if the shell received the
5077 interrupt; previous versions continue with the next command in the list.
5080 If set, Bash, when in @sc{posix} mode, treats a single quote in a double-quoted
5081 parameter expansion as a special character. The single quotes must match
5082 (an even number) and the characters between the single quotes are considered
5083 quoted. This is the behavior of @sc{posix} mode through version 4.1.
5084 The default Bash behavior remains as in previous versions.
5088 does not process the replacement string in the pattern substitution word
5089 expansion using quote removal.
5093 does not print a warning message if an attempt is made to use a quoted compound
5094 array assignment as an argument to @code{declare},
5095 makes word expansion errors
5096 non-fatal errors that cause the current command to fail (the default behavior is
5097 to make them fatal errors that cause the shell to exit),
5098 and does not reset the
5099 loop state when a shell function is executed (this allows @code{break} or
5100 @code{continue} in a shell function to affect loops in the caller's context).
5102 @item complete_fullquote
5104 quotes all shell metacharacters in filenames and directory names when
5105 performing completion.
5107 removes metacharacters such as the dollar sign from the set of
5108 characters that will be quoted in completed filenames
5109 when these metacharacters appear in shell variable references in words to be
5111 This means that dollar signs in variable names that expand to directories
5113 however, any dollar signs appearing in filenames will not be quoted, either.
5114 This is active only when bash is using backslashes to quote completed
5116 This variable is set by default, which is the default Bash behavior in
5117 versions through 4.2.
5121 replaces directory names with the results of word expansion when performing
5122 filename completion. This changes the contents of the readline editing
5124 If not set, Bash attempts to preserve what the user typed.
5128 attempts spelling correction on directory names during word completion
5129 if the directory name initially supplied does not exist.
5132 If set, Bash includes filenames beginning with a `.' in
5133 the results of filename expansion.
5136 If this is set, a non-interactive shell will not exit if
5137 it cannot execute the file specified as an argument to the @code{exec}
5138 builtin command. An interactive shell does not exit if @code{exec}
5141 @item expand_aliases
5142 If set, aliases are expanded as described below under Aliases,
5144 This option is enabled by default for interactive shells.
5147 If set, behavior intended for use by debuggers is enabled:
5151 The @option{-F} option to the @code{declare} builtin (@pxref{Bash Builtins})
5152 displays the source file name and line number corresponding to each function
5153 name supplied as an argument.
5156 If the command run by the @code{DEBUG} trap returns a non-zero value, the
5157 next command is skipped and not executed.
5160 If the command run by the @code{DEBUG} trap returns a value of 2, and the
5161 shell is executing in a subroutine (a shell function or a shell script
5162 executed by the @code{.} or @code{source} builtins), the shell simulates
5163 a call to @code{return}.
5166 @code{BASH_ARGC} and @code{BASH_ARGV} are updated as described in their
5167 descriptions (@pxref{Bash Variables}).
5170 Function tracing is enabled: command substitution, shell functions, and
5171 subshells invoked with @code{( @var{command} )} inherit the
5172 @code{DEBUG} and @code{RETURN} traps.
5175 Error tracing is enabled: command substitution, shell functions, and
5176 subshells invoked with @code{( @var{command} )} inherit the
5181 If set, the extended pattern matching features described above
5182 (@pxref{Pattern Matching}) are enabled.
5185 If set, @code{$'@var{string}'} and @code{$"@var{string}"} quoting is
5186 performed within @code{$@{@var{parameter}@}} expansions
5187 enclosed in double quotes. This option is enabled by default.
5190 If set, patterns which fail to match filenames during filename expansion
5191 result in an expansion error.
5194 If set, the suffixes specified by the @env{FIGNORE} shell variable
5195 cause words to be ignored when performing word completion even if
5196 the ignored words are the only possible completions.
5197 @xref{Bash Variables}, for a description of @env{FIGNORE}.
5198 This option is enabled by default.
5200 @item globasciiranges
5201 If set, range expressions used in pattern matching bracket expressions
5202 (@pxref{Pattern Matching})
5203 behave as if in the traditional C locale when performing
5204 comparisons. That is, the current locale's collating sequence
5205 is not taken into account, so
5206 @samp{b} will not collate between @samp{A} and @samp{B},
5207 and upper-case and lower-case ASCII characters will collate together.
5210 If set, the pattern @samp{**} used in a filename expansion context will
5211 match all files and zero or more directories and subdirectories.
5212 If the pattern is followed by a @samp{/}, only directories and
5213 subdirectories match.
5216 If set, shell error messages are written in the standard @sc{gnu} error
5220 If set, the history list is appended to the file named by the value
5221 of the @env{HISTFILE}
5222 variable when the shell exits, rather than overwriting the file.
5225 If set, and Readline
5226 is being used, a user is given the opportunity to re-edit a
5227 failed history substitution.
5230 If set, and Readline
5231 is being used, the results of history substitution are not immediately
5232 passed to the shell parser. Instead, the resulting line is loaded into
5233 the Readline editing buffer, allowing further modification.
5236 If set, and Readline is being used, Bash will attempt to perform
5237 hostname completion when a word containing a @samp{@@} is being
5238 completed (@pxref{Commands For Completion}). This option is enabled
5242 If set, Bash will send @code{SIGHUP} to all jobs when an interactive
5243 login shell exits (@pxref{Signals}).
5245 @item inherit_errexit
5246 If set, command substitution inherits the value of the @code{errexit} option,
5247 instead of unsetting it in the subshell environment.
5248 This option is enabled when @sc{posix} mode is enabled.
5250 @item interactive_comments
5251 Allow a word beginning with @samp{#}
5252 to cause that word and all remaining characters on that
5253 line to be ignored in an interactive shell.
5254 This option is enabled by default.
5257 If set, and job control is not active, the shell runs the last command of
5258 a pipeline not executed in the background in the current shell environment.
5261 If enabled, and the @code{cmdhist}
5262 option is enabled, multi-line commands are saved to the history with
5263 embedded newlines rather than using semicolon separators where possible.
5266 The shell sets this option if it is started as a login shell
5267 (@pxref{Invoking Bash}).
5268 The value may not be changed.
5271 If set, and a file that Bash is checking for mail has been
5272 accessed since the last time it was checked, the message
5273 @code{"The mail in @var{mailfile} has been read"} is displayed.
5275 @item no_empty_cmd_completion
5276 If set, and Readline is being used, Bash will not attempt to search
5277 the @env{PATH} for possible completions when completion is attempted
5281 If set, Bash matches filenames in a case-insensitive fashion when
5282 performing filename expansion.
5285 If set, Bash matches patterns in a case-insensitive fashion when
5286 performing matching while executing @code{case} or @code{[[}
5287 conditional commands,
5288 when performing pattern substitution word expansions,
5289 or when filtering possible completions as part of programmable completion.
5292 If set, Bash allows filename patterns which match no
5293 files to expand to a null string, rather than themselves.
5296 If set, the programmable completion facilities
5297 (@pxref{Programmable Completion}) are enabled.
5298 This option is enabled by default.
5301 If set, prompt strings undergo
5302 parameter expansion, command substitution, arithmetic
5303 expansion, and quote removal after being expanded
5304 as described below (@pxref{Controlling the Prompt}).
5305 This option is enabled by default.
5307 @item restricted_shell
5308 The shell sets this option if it is started in restricted mode
5309 (@pxref{The Restricted Shell}).
5310 The value may not be changed.
5311 This is not reset when the startup files are executed, allowing
5312 the startup files to discover whether or not a shell is restricted.
5315 If this is set, the @code{shift}
5316 builtin prints an error message when the shift count exceeds the
5317 number of positional parameters.
5320 If set, the @code{source} builtin uses the value of @env{PATH}
5321 to find the directory containing the file supplied as an argument.
5322 This option is enabled by default.
5325 If set, the @code{echo} builtin expands backslash-escape sequences
5331 The return status when listing options is zero if all @var{optnames}
5332 are enabled, non-zero otherwise.
5333 When setting or unsetting options, the return status is zero unless an
5334 @var{optname} is not a valid shell option.
5337 @node Special Builtins
5338 @section Special Builtins
5339 @cindex special builtin
5341 For historical reasons, the @sc{posix} standard has classified
5342 several builtin commands as @emph{special}.
5343 When Bash is executing in @sc{posix} mode, the special builtins
5344 differ from other builtin commands in three respects:
5348 Special builtins are found before shell functions during command lookup.
5351 If a special builtin returns an error status, a non-interactive shell exits.
5354 Assignment statements preceding the command stay in effect in the shell
5355 environment after the command completes.
5358 When Bash is not executing in @sc{posix} mode, these builtins behave no
5359 differently than the rest of the Bash builtin commands.
5360 The Bash @sc{posix} mode is described in @ref{Bash POSIX Mode}.
5362 These are the @sc{posix} special builtins:
5364 @w{break : . continue eval exec exit export readonly return set}
5365 @w{shift trap unset}
5368 @node Shell Variables
5369 @chapter Shell Variables
5372 * Bourne Shell Variables:: Variables which Bash uses in the same way
5373 as the Bourne Shell.
5374 * Bash Variables:: List of variables that exist in Bash.
5377 This chapter describes the shell variables that Bash uses.
5378 Bash automatically assigns default values to a number of variables.
5380 @node Bourne Shell Variables
5381 @section Bourne Shell Variables
5383 Bash uses certain shell variables in the same way as the Bourne shell.
5384 In some cases, Bash assigns a default value to the variable.
5389 A colon-separated list of directories used as a search path for
5390 the @code{cd} builtin command.
5393 The current user's home directory; the default for the @code{cd} builtin
5395 The value of this variable is also used by tilde expansion
5396 (@pxref{Tilde Expansion}).
5399 A list of characters that separate fields; used when the shell splits
5400 words as part of expansion.
5403 If this parameter is set to a filename or directory name
5404 and the @env{MAILPATH} variable
5405 is not set, Bash informs the user of the arrival of mail in
5406 the specified file or Maildir-format directory.
5409 A colon-separated list of filenames which the shell periodically checks
5411 Each list entry can specify the message that is printed when new mail
5412 arrives in the mail file by separating the filename from the message with
5414 When used in the text of the message, @code{$_} expands to the name of
5415 the current mail file.
5418 The value of the last option argument processed by the @code{getopts} builtin.
5421 The index of the last option argument processed by the @code{getopts} builtin.
5424 A colon-separated list of directories in which the shell looks for
5426 A zero-length (null) directory name in the value of @code{PATH} indicates the
5428 A null directory name may appear as two adjacent colons, or as an initial
5432 The primary prompt string. The default value is @samp{\s-\v\$ }.
5433 @xref{Controlling the Prompt}, for the complete list of escape
5434 sequences that are expanded before @env{PS1} is displayed.
5437 The secondary prompt string. The default value is @samp{> }.
5441 @node Bash Variables
5442 @section Bash Variables
5444 These variables are set or used by Bash, but other shells
5445 do not normally treat them specially.
5447 A few variables used by Bash are described in different chapters:
5448 variables for controlling the job control facilities
5449 (@pxref{Job Control Variables}).
5454 The full pathname used to execute the current instance of Bash.
5457 A colon-separated list of enabled shell options. Each word in
5458 the list is a valid argument for the @option{-s} option to the
5459 @code{shopt} builtin command (@pxref{The Shopt Builtin}).
5460 The options appearing in @env{BASHOPTS} are those reported
5461 as @samp{on} by @samp{shopt}.
5462 If this variable is in the environment when Bash
5463 starts up, each shell option in the list will be enabled before
5464 reading any startup files. This variable is readonly.
5467 Expands to the process ID of the current Bash process.
5468 This differs from @code{$$} under certain circumstances, such as subshells
5469 that do not require Bash to be re-initialized.
5472 An associative array variable whose members correspond to the internal
5473 list of aliases as maintained by the @code{alias} builtin.
5474 (@pxref{Bourne Shell Builtins}).
5475 Elements added to this array appear in the alias list; however,
5476 unsetting array elements currently does not cause aliases to be removed
5477 from the alias list.
5478 If @code{BASH_ALIASES}
5479 is unset, it loses its special properties, even if it is
5483 An array variable whose values are the number of parameters in each
5484 frame of the current bash execution call stack. The number of
5485 parameters to the current subroutine (shell function or script executed
5486 with @code{.} or @code{source}) is at the top of the stack. When a
5487 subroutine is executed, the number of parameters passed is pushed onto
5489 The shell sets @code{BASH_ARGC} only when in extended debugging mode
5490 (see @ref{The Shopt Builtin}
5491 for a description of the @code{extdebug} option to the @code{shopt}
5495 An array variable containing all of the parameters in the current bash
5496 execution call stack. The final parameter of the last subroutine call
5497 is at the top of the stack; the first parameter of the initial call is
5498 at the bottom. When a subroutine is executed, the parameters supplied
5499 are pushed onto @code{BASH_ARGV}.
5500 The shell sets @code{BASH_ARGV} only when in extended debugging mode
5501 (see @ref{The Shopt Builtin}
5502 for a description of the @code{extdebug} option to the @code{shopt}
5506 An associative array variable whose members correspond to the internal
5507 hash table of commands as maintained by the @code{hash} builtin
5508 (@pxref{Bourne Shell Builtins}).
5509 Elements added to this array appear in the hash table; however,
5510 unsetting array elements currently does not cause command names to be removed
5511 from the hash table.
5513 is unset, it loses its special properties, even if it is
5517 The command currently being executed or about to be executed, unless the
5518 shell is executing a command as the result of a trap,
5519 in which case it is the command executing at the time of the trap.
5522 The value is used to set the shell's compatibility level.
5523 @xref{The Shopt Builtin}, for a description of the various compatibility
5524 levels and their effects.
5525 The value may be a decimal number (e.g., 4.2) or an integer (e.g., 42)
5526 corresponding to the desired compatibility level.
5527 If @code{BASH_COMPAT} is unset or set to the empty string, the compatibility
5528 level is set to the default for the current version.
5529 If @code{BASH_COMPAT} is set to a value that is not one of the valid
5530 compatibility levels, the shell prints an error message and sets the
5531 compatibility level to the default for the current version.
5532 The valid compatibility levels correspond to the compatibility options
5533 accepted by the @code{shopt} builtin described above (for example,
5534 @var{compat42} means that 4.2 and 42 are valid values).
5535 The current version is also a valid value.
5538 If this variable is set when Bash is invoked to execute a shell
5539 script, its value is expanded and used as the name of a startup file
5540 to read before executing the script. @xref{Bash Startup Files}.
5542 @item BASH_EXECUTION_STRING
5543 The command argument to the @option{-c} invocation option.
5546 An array variable whose members are the line numbers in source files
5547 where each corresponding member of @var{FUNCNAME} was invoked.
5548 @code{$@{BASH_LINENO[$i]@}} is the line number in the source file
5549 (@code{$@{BASH_SOURCE[$i+1]@}}) where
5550 @code{$@{FUNCNAME[$i]@}} was called (or @code{$@{BASH_LINENO[$i-1]@}} if
5551 referenced within another shell function).
5552 Use @code{LINENO} to obtain the current line number.
5554 @item BASH_LOADABLES_PATH
5555 A colon-separated list of directories in which the shell looks for
5556 dynamically loadable builtins specified by the
5557 @code{enable} command.
5560 An array variable whose members are assigned by the @samp{=~} binary
5561 operator to the @code{[[} conditional command
5562 (@pxref{Conditional Constructs}).
5563 The element with index 0 is the portion of the string
5564 matching the entire regular expression.
5565 The element with index @var{n} is the portion of the
5566 string matching the @var{n}th parenthesized subexpression.
5567 This variable is read-only.
5570 An array variable whose members are the source filenames where the
5571 corresponding shell function names in the @code{FUNCNAME} array
5572 variable are defined.
5573 The shell function @code{$@{FUNCNAME[$i]@}} is defined in the file
5574 @code{$@{BASH_SOURCE[$i]@}} and called from @code{$@{BASH_SOURCE[$i+1]@}}
5577 Incremented by one within each subshell or subshell environment when
5578 the shell begins executing in that environment.
5579 The initial value is 0.
5582 A readonly array variable (@pxref{Arrays})
5583 whose members hold version information for this instance of Bash.
5584 The values assigned to the array members are as follows:
5588 @item BASH_VERSINFO[0]
5589 The major version number (the @var{release}).
5591 @item BASH_VERSINFO[1]
5592 The minor version number (the @var{version}).
5594 @item BASH_VERSINFO[2]
5597 @item BASH_VERSINFO[3]
5600 @item BASH_VERSINFO[4]
5601 The release status (e.g., @var{beta1}).
5603 @item BASH_VERSINFO[5]
5604 The value of @env{MACHTYPE}.
5608 The version number of the current instance of Bash.
5611 If set to an integer corresponding to a valid file descriptor, Bash
5612 will write the trace output generated when @samp{set -x}
5613 is enabled to that file descriptor.
5614 This allows tracing output to be separated from diagnostic and error
5616 The file descriptor is closed when @code{BASH_XTRACEFD} is unset or assigned
5618 Unsetting @code{BASH_XTRACEFD} or assigning it the empty string causes the
5619 trace output to be sent to the standard error.
5620 Note that setting @code{BASH_XTRACEFD} to 2 (the standard error file
5621 descriptor) and then unsetting it will result in the standard error
5625 Set the number of exited child status values for the shell to remember.
5626 Bash will not allow this value to be decreased below a @sc{posix}-mandated
5627 minimum, and there is a maximum value (currently 8192) that this may
5629 The minimum value is system-dependent.
5632 Used by the @code{select} command to determine the terminal width
5633 when printing selection lists.
5634 Automatically set if the @code{checkwinsize} option is enabled
5635 (@pxref{The Shopt Builtin}), or in an interactive shell upon receipt of a
5639 An index into @env{$@{COMP_WORDS@}} of the word containing the current
5641 This variable is available only in shell functions invoked by the
5642 programmable completion facilities (@pxref{Programmable Completion}).
5645 The current command line.
5646 This variable is available only in shell functions and external
5647 commands invoked by the
5648 programmable completion facilities (@pxref{Programmable Completion}).
5651 The index of the current cursor position relative to the beginning of
5652 the current command.
5653 If the current cursor position is at the end of the current command,
5654 the value of this variable is equal to @code{$@{#COMP_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 Set to an integer value corresponding to the type of completion attempted
5661 that caused a completion function to be called:
5662 @var{TAB}, for normal completion,
5663 @samp{?}, for listing completions after successive tabs,
5664 @samp{!}, for listing alternatives on partial word completion,
5665 @samp{@@}, to list completions if the word is not unmodified,
5667 @samp{%}, for menu completion.
5668 This variable is available only in shell functions and external
5669 commands invoked by the
5670 programmable completion facilities (@pxref{Programmable Completion}).
5673 The key (or final key of a key sequence) used to invoke the current
5674 completion function.
5676 @item COMP_WORDBREAKS
5677 The set of characters that the Readline library treats as word
5678 separators when performing word completion.
5679 If @code{COMP_WORDBREAKS} is unset, it loses its special properties,
5680 even if it is subsequently reset.
5683 An array variable consisting of the individual
5684 words in the current command line.
5685 The line is split into words as Readline would split it, using
5686 @code{COMP_WORDBREAKS} as described above.
5687 This variable is available only in shell functions invoked by the
5688 programmable completion facilities (@pxref{Programmable Completion}).
5691 An array variable from which Bash reads the possible completions
5692 generated by a shell function invoked by the programmable completion
5693 facility (@pxref{Programmable Completion}).
5694 Each array element contains one possible completion.
5697 An array variable created to hold the file descriptors
5698 for output from and input to an unnamed coprocess (@pxref{Coprocesses}).
5701 An array variable containing the current contents of the directory stack.
5702 Directories appear in the stack in the order they are displayed by the
5703 @code{dirs} builtin.
5704 Assigning to members of this array variable may be used to modify
5705 directories already in the stack, but the @code{pushd} and @code{popd}
5706 builtins must be used to add and remove directories.
5707 Assignment to this variable will not change the current directory.
5708 If @env{DIRSTACK} is unset, it loses its special properties, even if
5709 it is subsequently reset.
5712 If Bash finds this variable in the environment when the shell
5713 starts with value @samp{t}, it assumes that the shell is running in an
5714 Emacs shell buffer and disables line editing.
5717 Similar to @code{BASH_ENV}; used when the shell is invoked in
5718 @sc{posix} Mode (@pxref{Bash POSIX Mode}).
5721 The numeric effective user id of the current user. This variable
5725 A colon-separated list of shell patterns (@pxref{Pattern Matching})
5726 defining the list of filenames to be ignored by command search.
5727 Files whose full pathnames match one of these patterns are not considered
5728 executable files for the purposes of completion and command execution.
5729 This does not affect the behavior of the @code{[}, @code{test}, and @code{[[}
5731 Use this variable to ignore shared library files that have the executable
5732 bit set, but are not executable files.
5733 The pattern matching honors the setting of the @code{extglob} shell
5737 The editor used as a default by the @option{-e} option to the @code{fc}
5741 A colon-separated list of suffixes to ignore when performing
5742 filename completion.
5743 A filename whose suffix matches one of the entries in
5745 is excluded from the list of matched filenames. A sample
5746 value is @samp{.o:~}
5749 An array variable containing the names of all shell functions
5750 currently in the execution call stack.
5751 The element with index 0 is the name of any currently-executing
5753 The bottom-most element (the one with the highest index)
5755 This variable exists only when a shell function is executing.
5756 Assignments to @env{FUNCNAME} have no effect.
5757 If @env{FUNCNAME} is unset, it loses its special properties, even if
5758 it is subsequently reset.
5760 This variable can be used with @code{BASH_LINENO} and @code{BASH_SOURCE}.
5761 Each element of @code{FUNCNAME} has corresponding elements in
5762 @code{BASH_LINENO} and @code{BASH_SOURCE} to describe the call stack.
5763 For instance, @code{$@{FUNCNAME[$i]@}} was called from the file
5764 @code{$@{BASH_SOURCE[$i+1]@}} at line number @code{$@{BASH_LINENO[$i]@}}.
5765 The @code{caller} builtin displays the current call stack using this
5769 If set to a numeric value greater than 0, defines a maximum function
5770 nesting level. Function invocations that exceed this nesting level
5771 will cause the current command to abort.
5774 A colon-separated list of patterns defining the set of filenames to
5775 be ignored by filename expansion.
5776 If a filename matched by a filename expansion pattern also matches one
5777 of the patterns in @env{GLOBIGNORE}, it is removed from the list
5779 The pattern matching honors the setting of the @code{extglob} shell
5783 An array variable containing the list of groups of which the current
5785 Assignments to @env{GROUPS} have no effect.
5786 If @env{GROUPS} is unset, it loses its special properties, even if it is
5790 Up to three characters which control history expansion, quick
5791 substitution, and tokenization (@pxref{History Interaction}).
5792 The first character is the
5793 @var{history expansion} character, that is, the character which signifies the
5794 start of a history expansion, normally @samp{!}. The second character is the
5795 character which signifies `quick substitution' when seen as the first
5796 character on a line, normally @samp{^}. The optional third character is the
5797 character which indicates that the remainder of the line is a comment when
5798 found as the first character of a word, usually @samp{#}. The history
5799 comment character causes history substitution to be skipped for the
5800 remaining words on the line. It does not necessarily cause the shell
5801 parser to treat the rest of the line as a comment.
5804 The history number, or index in the history list, of the current
5805 command. If @env{HISTCMD} is unset, it loses its special properties,
5806 even if it is subsequently reset.
5809 A colon-separated list of values controlling how commands are saved on
5811 If the list of values includes @samp{ignorespace}, lines which begin
5812 with a space character are not saved in the history list.
5813 A value of @samp{ignoredups} causes lines which match the previous
5814 history entry to not be saved.
5815 A value of @samp{ignoreboth} is shorthand for
5816 @samp{ignorespace} and @samp{ignoredups}.
5817 A value of @samp{erasedups} causes all previous lines matching the
5818 current line to be removed from the history list before that line
5820 Any value not in the above list is ignored.
5821 If @env{HISTCONTROL} is unset, or does not include a valid value,
5822 all lines read by the shell parser are saved on the history list,
5823 subject to the value of @env{HISTIGNORE}.
5824 The second and subsequent lines of a multi-line compound command are
5825 not tested, and are added to the history regardless of the value of
5829 The name of the file to which the command history is saved. The
5830 default value is @file{~/.bash_history}.
5833 The maximum number of lines contained in the history file.
5834 When this variable is assigned a value, the history file is truncated,
5835 if necessary, to contain no more than that number of lines
5836 by removing the oldest entries.
5837 The history file is also truncated to this size after
5838 writing it when a shell exits.
5839 If the value is 0, the history file is truncated to zero size.
5840 Non-numeric values and numeric values less than zero inhibit truncation.
5841 The shell sets the default value to the value of @env{HISTSIZE}
5842 after reading any startup files.
5845 A colon-separated list of patterns used to decide which command
5846 lines should be saved on the history list. Each pattern is
5847 anchored at the beginning of the line and must match the complete
5848 line (no implicit @samp{*} is appended). Each pattern is tested
5849 against the line after the checks specified by @env{HISTCONTROL}
5850 are applied. In addition to the normal shell pattern matching
5851 characters, @samp{&} matches the previous history line. @samp{&}
5852 may be escaped using a backslash; the backslash is removed
5853 before attempting a match.
5854 The second and subsequent lines of a multi-line compound command are
5855 not tested, and are added to the history regardless of the value of
5857 The pattern matching honors the setting of the @code{extglob} shell
5860 @env{HISTIGNORE} subsumes the function of @env{HISTCONTROL}. A
5861 pattern of @samp{&} is identical to @code{ignoredups}, and a
5862 pattern of @samp{[ ]*} is identical to @code{ignorespace}.
5863 Combining these two patterns, separating them with a colon,
5864 provides the functionality of @code{ignoreboth}.
5867 The maximum number of commands to remember on the history list.
5868 If the value is 0, commands are not saved in the history list.
5869 Numeric values less than zero result in every command being saved
5870 on the history list (there is no limit).
5871 The shell sets the default value to 500 after reading any startup files.
5873 @item HISTTIMEFORMAT
5874 If this variable is set and not null, its value is used as a format string
5875 for @var{strftime} to print the time stamp associated with each history
5876 entry displayed by the @code{history} builtin.
5877 If this variable is set, time stamps are written to the history file so
5878 they may be preserved across shell sessions.
5879 This uses the history comment character to distinguish timestamps from
5880 other history lines.
5883 Contains the name of a file in the same format as @file{/etc/hosts} that
5884 should be read when the shell needs to complete a hostname.
5885 The list of possible hostname completions may be changed while the shell
5887 the next time hostname completion is attempted after the
5888 value is changed, Bash adds the contents of the new file to the
5890 If @env{HOSTFILE} is set, but has no value, or does not name a readable file,
5891 Bash attempts to read
5892 @file{/etc/hosts} to obtain the list of possible hostname completions.
5893 When @env{HOSTFILE} is unset, the hostname list is cleared.
5896 The name of the current host.
5899 A string describing the machine Bash is running on.
5902 Controls the action of the shell on receipt of an @code{EOF} character
5903 as the sole input. If set, the value denotes the number
5904 of consecutive @code{EOF} characters that can be read as the
5905 first character on an input line
5906 before the shell will exit. If the variable exists but does not
5907 have a numeric value (or has no value) then the default is 10.
5908 If the variable does not exist, then @code{EOF} signifies the end of
5909 input to the shell. This is only in effect for interactive shells.
5912 The name of the Readline initialization file, overriding the default
5913 of @file{~/.inputrc}.
5916 Used to determine the locale category for any category not specifically
5917 selected with a variable starting with @code{LC_}.
5920 This variable overrides the value of @env{LANG} and any other
5921 @code{LC_} variable specifying a locale category.
5924 This variable determines the collation order used when sorting the
5925 results of filename expansion, and
5926 determines the behavior of range expressions, equivalence classes,
5927 and collating sequences within filename expansion and pattern matching
5928 (@pxref{Filename Expansion}).
5931 This variable determines the interpretation of characters and the
5932 behavior of character classes within filename expansion and pattern
5933 matching (@pxref{Filename Expansion}).
5936 This variable determines the locale used to translate double-quoted
5937 strings preceded by a @samp{$} (@pxref{Locale Translation}).
5940 This variable determines the locale category used for number formatting.
5943 This variable determines the locale category used for data and time
5947 The line number in the script or shell function currently executing.
5950 Used by the @code{select} command to determine the column length
5951 for printing selection lists.
5952 Automatically set if the @code{checkwinsize} option is enabled
5953 (@pxref{The Shopt Builtin}), or in an interactive shell upon receipt of a
5957 A string that fully describes the system type on which Bash
5958 is executing, in the standard @sc{gnu} @var{cpu-company-system} format.
5961 How often (in seconds) that the shell should check for mail in the
5962 files specified in the @env{MAILPATH} or @env{MAIL} variables.
5963 The default is 60 seconds. When it is time to check
5964 for mail, the shell does so before displaying the primary prompt.
5965 If this variable is unset, or set to a value that is not a number
5966 greater than or equal to zero, the shell disables mail checking.
5969 An array variable created to hold the text read by the
5970 @code{mapfile} builtin when no variable name is supplied.
5973 The previous working directory as set by the @code{cd} builtin.
5976 If set to the value 1, Bash displays error messages
5977 generated by the @code{getopts} builtin command.
5980 A string describing the operating system Bash is running on.
5983 An array variable (@pxref{Arrays})
5984 containing a list of exit status values from the processes
5985 in the most-recently-executed foreground pipeline (which may
5986 contain only a single command).
5988 @item POSIXLY_CORRECT
5989 If this variable is in the environment when Bash starts, the shell
5990 enters @sc{posix} mode (@pxref{Bash POSIX Mode}) before reading the
5991 startup files, as if the @option{--posix} invocation option had been supplied.
5992 If it is set while the shell is running, Bash enables @sc{posix} mode,
6001 The process @sc{id} of the shell's parent process. This variable
6004 @item PROMPT_COMMAND
6005 If set, the value is interpreted as a command to execute
6006 before the printing of each primary prompt (@env{$PS1}).
6008 @item PROMPT_DIRTRIM
6009 If set to a number greater than zero, the value is used as the number of
6010 trailing directory components to retain when expanding the @code{\w} and
6011 @code{\W} prompt string escapes (@pxref{Controlling the Prompt}).
6012 Characters removed are replaced with an ellipsis.
6015 The value of this parameter is expanded like @var{PS1}
6016 and displayed by interactive shells after reading a command
6017 and before the command is executed.
6020 The value of this variable is used as the prompt for the
6021 @code{select} command. If this variable is not set, the
6022 @code{select} command prompts with @samp{#? }
6025 The value is the prompt printed before the command line is echoed
6026 when the @option{-x} option is set (@pxref{The Set Builtin}).
6027 The first character of @env{PS4} is replicated multiple times, as
6028 necessary, to indicate multiple levels of indirection.
6029 The default is @samp{+ }.
6032 The current working directory as set by the @code{cd} builtin.
6035 Each time this parameter is referenced, a random integer
6036 between 0 and 32767 is generated. Assigning a value to this
6037 variable seeds the random number generator.
6040 The contents of the Readline line buffer, for use
6041 with @samp{bind -x} (@pxref{Bash Builtins}).
6043 @item READLINE_POINT
6044 The position of the insertion point in the Readline line buffer, for use
6045 with @samp{bind -x} (@pxref{Bash Builtins}).
6048 The default variable for the @code{read} builtin.
6051 This variable expands to the number of seconds since the
6052 shell was started. Assignment to this variable resets
6053 the count to the value assigned, and the expanded value
6054 becomes the value assigned plus the number of seconds
6055 since the assignment.
6058 The full pathname to the shell is kept in this environment variable.
6059 If it is not set when the shell starts,
6060 Bash assigns to it the full pathname of the current user's login shell.
6063 A colon-separated list of enabled shell options. Each word in
6064 the list is a valid argument for the @option{-o} option to the
6065 @code{set} builtin command (@pxref{The Set Builtin}).
6066 The options appearing in @env{SHELLOPTS} are those reported
6067 as @samp{on} by @samp{set -o}.
6068 If this variable is in the environment when Bash
6069 starts up, each shell option in the list will be enabled before
6070 reading any startup files. This variable is readonly.
6073 Incremented by one each time a new instance of Bash is started. This is
6074 intended to be a count of how deeply your Bash shells are nested.
6077 The value of this parameter is used as a format string specifying
6078 how the timing information for pipelines prefixed with the @code{time}
6079 reserved word should be displayed.
6080 The @samp{%} character introduces an
6081 escape sequence that is expanded to a time value or other
6083 The escape sequences and their meanings are as
6084 follows; the braces denote optional portions.
6091 @item %[@var{p}][l]R
6092 The elapsed time in seconds.
6094 @item %[@var{p}][l]U
6095 The number of CPU seconds spent in user mode.
6097 @item %[@var{p}][l]S
6098 The number of CPU seconds spent in system mode.
6101 The CPU percentage, computed as (%U + %S) / %R.
6104 The optional @var{p} is a digit specifying the precision, the number of
6105 fractional digits after a decimal point.
6106 A value of 0 causes no decimal point or fraction to be output.
6107 At most three places after the decimal point may be specified; values
6108 of @var{p} greater than 3 are changed to 3.
6109 If @var{p} is not specified, the value 3 is used.
6111 The optional @code{l} specifies a longer format, including minutes, of
6112 the form @var{MM}m@var{SS}.@var{FF}s.
6113 The value of @var{p} determines whether or not the fraction is included.
6115 If this variable is not set, Bash acts as if it had the value
6117 @code{$'\nreal\t%3lR\nuser\t%3lU\nsys\t%3lS'}
6119 If the value is null, no timing information is displayed.
6120 A trailing newline is added when the format string is displayed.
6123 If set to a value greater than zero, @code{TMOUT} is treated as the
6124 default timeout for the @code{read} builtin (@pxref{Bash Builtins}).
6125 The @code{select} command (@pxref{Conditional Constructs}) terminates
6126 if input does not arrive after @code{TMOUT} seconds when input is coming
6129 In an interactive shell, the value is interpreted as
6130 the number of seconds to wait for a line of input after issuing
6133 terminates after waiting for that number of seconds if a complete
6134 line of input does not arrive.
6137 If set, Bash uses its value as the name of a directory in which
6138 Bash creates temporary files for the shell's use.
6141 The numeric real user id of the current user. This variable is readonly.
6146 @chapter Bash Features
6148 This chapter describes features unique to Bash.
6151 * Invoking Bash:: Command line options that you can give
6153 * Bash Startup Files:: When and how Bash executes scripts.
6154 * Interactive Shells:: What an interactive shell is.
6155 * Bash Conditional Expressions:: Primitives used in composing expressions for
6156 the @code{test} builtin.
6157 * Shell Arithmetic:: Arithmetic on shell variables.
6158 * Aliases:: Substituting one command for another.
6159 * Arrays:: Array Variables.
6160 * The Directory Stack:: History of visited directories.
6161 * Controlling the Prompt:: Customizing the various prompt strings.
6162 * The Restricted Shell:: A more controlled mode of shell execution.
6163 * Bash POSIX Mode:: Making Bash behave more closely to what
6164 the POSIX standard specifies.
6168 @section Invoking Bash
6171 bash [long-opt] [-ir] [-abefhkmnptuvxdBCDHP] [-o @var{option}] [-O @var{shopt_option}] [@var{argument} @dots{}]
6172 bash [long-opt] [-abefhkmnptuvxdBCDHP] [-o @var{option}] [-O @var{shopt_option}] -c @var{string} [@var{argument} @dots{}]
6173 bash [long-opt] -s [-abefhkmnptuvxdBCDHP] [-o @var{option}] [-O @var{shopt_option}] [@var{argument} @dots{}]
6176 All of the single-character options used with the @code{set} builtin
6177 (@pxref{The Set Builtin}) can be used as options when the shell is invoked.
6178 In addition, there are several multi-character
6179 options that you can use. These options must appear on the command
6180 line before the single-character options to be recognized.
6184 Arrange for the debugger profile to be executed before the shell
6185 starts. Turns on extended debugging mode (see @ref{The Shopt Builtin}
6186 for a description of the @code{extdebug} option to the @code{shopt}
6189 @item --dump-po-strings
6190 A list of all double-quoted strings preceded by @samp{$}
6191 is printed on the standard output
6192 in the @sc{gnu} @code{gettext} PO (portable object) file format.
6193 Equivalent to @option{-D} except for the output format.
6195 @item --dump-strings
6196 Equivalent to @option{-D}.
6199 Display a usage message on standard output and exit successfully.
6201 @item --init-file @var{filename}
6202 @itemx --rcfile @var{filename}
6203 Execute commands from @var{filename} (instead of @file{~/.bashrc})
6204 in an interactive shell.
6207 Equivalent to @option{-l}.
6210 Do not use the @sc{gnu} Readline library (@pxref{Command Line Editing})
6211 to read command lines when the shell is interactive.
6214 Don't load the system-wide startup file @file{/etc/profile}
6215 or any of the personal initialization files
6216 @file{~/.bash_profile}, @file{~/.bash_login}, or @file{~/.profile}
6217 when Bash is invoked as a login shell.
6220 Don't read the @file{~/.bashrc} initialization file in an
6221 interactive shell. This is on by default if the shell is
6222 invoked as @code{sh}.
6225 Change the behavior of Bash where the default operation differs
6226 from the @sc{posix} standard to match the standard. This
6227 is intended to make Bash behave as a strict superset of that
6228 standard. @xref{Bash POSIX Mode}, for a description of the Bash
6232 Make the shell a restricted shell (@pxref{The Restricted Shell}).
6235 Equivalent to @option{-v}. Print shell input lines as they're read.
6238 Show version information for this instance of
6239 Bash on the standard output and exit successfully.
6242 There are several single-character options that may be supplied at
6243 invocation which are not available with the @code{set} builtin.
6247 Read and execute commands from the first non-option argument
6248 @var{command_string}, then exit.
6249 If there are arguments after the @var{command_string},
6250 the first argument is assigned to @code{$0}
6251 and any remaining arguments are assigned to the positional parameters.
6252 The assignment to @code{$0} sets the name of the shell, which is used
6253 in warning and error messages.
6256 Force the shell to run interactively. Interactive shells are
6257 described in @ref{Interactive Shells}.
6260 Make this shell act as if it had been directly invoked by login.
6261 When the shell is interactive, this is equivalent to starting a
6262 login shell with @samp{exec -l bash}.
6263 When the shell is not interactive, the login shell startup files will
6265 @samp{exec bash -l} or @samp{exec bash --login}
6266 will replace the current shell with a Bash login shell.
6267 @xref{Bash Startup Files}, for a description of the special behavior
6271 Make the shell a restricted shell (@pxref{The Restricted Shell}).
6274 If this option is present, or if no arguments remain after option
6275 processing, then commands are read from the standard input.
6276 This option allows the positional parameters to be set
6277 when invoking an interactive shell.
6280 A list of all double-quoted strings preceded by @samp{$}
6281 is printed on the standard output.
6282 These are the strings that
6283 are subject to language translation when the current locale
6284 is not @code{C} or @code{POSIX} (@pxref{Locale Translation}).
6285 This implies the @option{-n} option; no commands will be executed.
6287 @item [-+]O [@var{shopt_option}]
6288 @var{shopt_option} is one of the shell options accepted by the
6289 @code{shopt} builtin (@pxref{The Shopt Builtin}).
6290 If @var{shopt_option} is present, @option{-O} sets the value of that option;
6291 @option{+O} unsets it.
6292 If @var{shopt_option} is not supplied, the names and values of the shell
6293 options accepted by @code{shopt} are printed on the standard output.
6294 If the invocation option is @option{+O}, the output is displayed in a format
6295 that may be reused as input.
6298 A @code{--} signals the end of options and disables further option
6300 Any arguments after the @code{--} are treated as filenames and arguments.
6304 A @emph{login} shell is one whose first character of argument zero is
6305 @samp{-}, or one invoked with the @option{--login} option.
6307 @cindex interactive shell
6308 An @emph{interactive} shell is one started without non-option arguments,
6309 unless @option{-s} is specified,
6310 without specifying the @option{-c} option, and whose input and output are both
6311 connected to terminals (as determined by @code{isatty(3)}), or one
6312 started with the @option{-i} option. @xref{Interactive Shells}, for more
6315 If arguments remain after option processing, and neither the
6316 @option{-c} nor the @option{-s}
6317 option has been supplied, the first argument is assumed to
6318 be the name of a file containing shell commands (@pxref{Shell Scripts}).
6319 When Bash is invoked in this fashion, @code{$0}
6320 is set to the name of the file, and the positional parameters
6321 are set to the remaining arguments.
6322 Bash reads and executes commands from this file, then exits.
6323 Bash's exit status is the exit status of the last command executed
6324 in the script. If no commands are executed, the exit status is 0.
6326 @node Bash Startup Files
6327 @section Bash Startup Files
6328 @cindex startup files
6330 This section describes how Bash executes its startup files.
6331 If any of the files exist but cannot be read, Bash reports an error.
6332 Tildes are expanded in filenames as described above under
6333 Tilde Expansion (@pxref{Tilde Expansion}).
6335 Interactive shells are described in @ref{Interactive Shells}.
6337 @subsubheading Invoked as an interactive login shell, or with @option{--login}
6339 When Bash is invoked as an interactive login shell, or as a
6340 non-interactive shell with the @option{--login} option, it first reads and
6341 executes commands from the file @file{/etc/profile}, if that file exists.
6342 After reading that file, it looks for @file{~/.bash_profile},
6343 @file{~/.bash_login}, and @file{~/.profile}, in that order, and reads
6344 and executes commands from the first one that exists and is readable.
6345 The @option{--noprofile} option may be used when the shell is started to
6346 inhibit this behavior.
6348 When an interactive login shell exits,
6349 or a non-interactive login shell executes the @code{exit} builtin command,
6350 Bash reads and executes commands from
6351 the file @file{~/.bash_logout}, if it exists.
6353 @subsubheading Invoked as an interactive non-login shell
6355 When an interactive shell that is not a login shell is started, Bash
6356 reads and executes commands from @file{~/.bashrc}, if that file exists.
6357 This may be inhibited by using the @option{--norc} option.
6358 The @option{--rcfile @var{file}} option will force Bash to read and
6359 execute commands from @var{file} instead of @file{~/.bashrc}.
6361 So, typically, your @file{~/.bash_profile} contains the line
6363 @code{if [ -f ~/.bashrc ]; then . ~/.bashrc; fi}
6366 after (or before) any login-specific initializations.
6368 @subsubheading Invoked non-interactively
6370 When Bash is started non-interactively, to run a shell script,
6371 for example, it looks for the variable @env{BASH_ENV} in the environment,
6372 expands its value if it appears there, and uses the expanded value as
6373 the name of a file to read and execute. Bash behaves as if the
6374 following command were executed:
6376 @code{if [ -n "$BASH_ENV" ]; then . "$BASH_ENV"; fi}
6379 but the value of the @env{PATH} variable is not used to search for the
6382 As noted above, if a non-interactive shell is invoked with the
6383 @option{--login} option, Bash attempts to read and execute commands from the
6384 login shell startup files.
6386 @subsubheading Invoked with name @code{sh}
6388 If Bash is invoked with the name @code{sh}, it tries to mimic the
6389 startup behavior of historical versions of @code{sh} as closely as
6390 possible, while conforming to the @sc{posix} standard as well.
6392 When invoked as an interactive login shell, or as a non-interactive
6393 shell with the @option{--login} option, it first attempts to read
6394 and execute commands from @file{/etc/profile} and @file{~/.profile}, in
6396 The @option{--noprofile} option may be used to inhibit this behavior.
6397 When invoked as an interactive shell with the name @code{sh}, Bash
6398 looks for the variable @env{ENV}, expands its value if it is defined,
6399 and uses the expanded value as the name of a file to read and execute.
6400 Since a shell invoked as @code{sh} does not attempt to read and execute
6401 commands from any other startup files, the @option{--rcfile} option has
6403 A non-interactive shell invoked with the name @code{sh} does not attempt
6404 to read any other startup files.
6406 When invoked as @code{sh}, Bash enters @sc{posix} mode after
6407 the startup files are read.
6409 @subsubheading Invoked in @sc{posix} mode
6411 When Bash is started in @sc{posix} mode, as with the
6412 @option{--posix} command line option, it follows the @sc{posix} standard
6414 In this mode, interactive shells expand the @env{ENV} variable
6415 and commands are read and executed from the file whose name is the
6417 No other startup files are read.
6419 @subsubheading Invoked by remote shell daemon
6421 Bash attempts to determine when it is being run with its standard input
6422 connected to a network connection, as when executed by the remote shell
6423 daemon, usually @code{rshd}, or the secure shell daemon @code{sshd}.
6424 If Bash determines it is being run in
6425 this fashion, it reads and executes commands from @file{~/.bashrc}, if that
6426 file exists and is readable.
6427 It will not do this if invoked as @code{sh}.
6428 The @option{--norc} option may be used to inhibit this behavior, and the
6429 @option{--rcfile} option may be used to force another file to be read, but
6430 neither @code{rshd} nor @code{sshd} generally invoke the shell with those
6431 options or allow them to be specified.
6433 @subsubheading Invoked with unequal effective and real @sc{uid/gid}s
6435 If Bash is started with the effective user (group) id not equal to the
6436 real user (group) id, and the @option{-p} option is not supplied, no startup
6437 files are read, shell functions are not inherited from the environment,
6438 the @env{SHELLOPTS}, @env{BASHOPTS}, @env{CDPATH}, and @env{GLOBIGNORE}
6439 variables, if they appear in the environment, are ignored, and the effective
6440 user id is set to the real user id.
6441 If the @option{-p} option is supplied at invocation, the startup behavior is
6442 the same, but the effective user id is not reset.
6444 @node Interactive Shells
6445 @section Interactive Shells
6446 @cindex interactive shell
6447 @cindex shell, interactive
6450 * What is an Interactive Shell?:: What determines whether a shell is Interactive.
6451 * Is this Shell Interactive?:: How to tell if a shell is interactive.
6452 * Interactive Shell Behavior:: What changes in a interactive shell?
6455 @node What is an Interactive Shell?
6456 @subsection What is an Interactive Shell?
6458 An interactive shell
6459 is one started without non-option arguments, unless @option{-s} is
6460 specified, without specifying the @option{-c} option, and
6461 whose input and error output are both
6462 connected to terminals (as determined by @code{isatty(3)}),
6463 or one started with the @option{-i} option.
6465 An interactive shell generally reads from and writes to a user's
6468 The @option{-s} invocation option may be used to set the positional parameters
6469 when an interactive shell is started.
6471 @node Is this Shell Interactive?
6472 @subsection Is this Shell Interactive?
6474 To determine within a startup script whether or not Bash is
6475 running interactively,
6476 test the value of the @samp{-} special parameter.
6477 It contains @code{i} when the shell is interactive. For example:
6481 *i*) echo This shell is interactive ;;
6482 *) echo This shell is not interactive ;;
6486 Alternatively, startup scripts may examine the variable
6487 @env{PS1}; it is unset in non-interactive shells, and set in
6488 interactive shells. Thus:
6491 if [ -z "$PS1" ]; then
6492 echo This shell is not interactive
6494 echo This shell is interactive
6498 @node Interactive Shell Behavior
6499 @subsection Interactive Shell Behavior
6501 When the shell is running interactively, it changes its behavior in
6506 Startup files are read and executed as described in @ref{Bash Startup Files}.
6509 Job Control (@pxref{Job Control}) is enabled by default. When job
6510 control is in effect, Bash ignores the keyboard-generated job control
6511 signals @code{SIGTTIN}, @code{SIGTTOU}, and @code{SIGTSTP}.
6514 Bash expands and displays @env{PS1} before reading the first line
6515 of a command, and expands and displays @env{PS2} before reading the
6516 second and subsequent lines of a multi-line command.
6517 Bash displays @env{PS0} after it reads a command but before executing it.
6520 Bash executes the value of the @env{PROMPT_COMMAND} variable as a command
6521 before printing the primary prompt, @env{$PS1}
6522 (@pxref{Bash Variables}).
6525 Readline (@pxref{Command Line Editing}) is used to read commands from
6526 the user's terminal.
6529 Bash inspects the value of the @code{ignoreeof} option to @code{set -o}
6530 instead of exiting immediately when it receives an @code{EOF} on its
6531 standard input when reading a command (@pxref{The Set Builtin}).
6534 Command history (@pxref{Bash History Facilities})
6535 and history expansion (@pxref{History Interaction})
6536 are enabled by default.
6537 Bash will save the command history to the file named by @env{$HISTFILE}
6538 when a shell with history enabled exits.
6541 Alias expansion (@pxref{Aliases}) is performed by default.
6544 In the absence of any traps, Bash ignores @code{SIGTERM}
6548 In the absence of any traps, @code{SIGINT} is caught and handled
6550 @code{SIGINT} will interrupt some shell builtins.
6553 An interactive login shell sends a @code{SIGHUP} to all jobs on exit
6554 if the @code{huponexit} shell option has been enabled (@pxref{Signals}).
6557 The @option{-n} invocation option is ignored, and @samp{set -n} has
6558 no effect (@pxref{The Set Builtin}).
6561 Bash will check for mail periodically, depending on the values of the
6562 @env{MAIL}, @env{MAILPATH}, and @env{MAILCHECK} shell variables
6563 (@pxref{Bash Variables}).
6566 Expansion errors due to references to unbound shell variables after
6567 @samp{set -u} has been enabled will not cause the shell to exit
6568 (@pxref{The Set Builtin}).
6571 The shell will not exit on expansion errors caused by @var{var} being unset
6572 or null in @code{$@{@var{var}:?@var{word}@}} expansions
6573 (@pxref{Shell Parameter Expansion}).
6576 Redirection errors encountered by shell builtins will not cause the
6580 When running in @sc{posix} mode, a special builtin returning an error
6581 status will not cause the shell to exit (@pxref{Bash POSIX Mode}).
6584 A failed @code{exec} will not cause the shell to exit
6585 (@pxref{Bourne Shell Builtins}).
6588 Parser syntax errors will not cause the shell to exit.
6591 Simple spelling correction for directory arguments to the @code{cd}
6592 builtin is enabled by default (see the description of the @code{cdspell}
6593 option to the @code{shopt} builtin in @ref{The Shopt Builtin}).
6596 The shell will check the value of the @env{TMOUT} variable and exit
6597 if a command is not read within the specified number of seconds after
6598 printing @env{$PS1} (@pxref{Bash Variables}).
6602 @node Bash Conditional Expressions
6603 @section Bash Conditional Expressions
6604 @cindex expressions, conditional
6606 Conditional expressions are used by the @code{[[} compound command
6607 and the @code{test} and @code{[} builtin commands.
6609 Expressions may be unary or binary.
6610 Unary expressions are often used to examine the status of a file.
6611 There are string operators and numeric comparison operators as well.
6612 If the @var{file} argument to one of the primaries is of the form
6613 @file{/dev/fd/@var{N}}, then file descriptor @var{N} is checked.
6614 If the @var{file} argument to one of the primaries is one of
6615 @file{/dev/stdin}, @file{/dev/stdout}, or @file{/dev/stderr}, file
6616 descriptor 0, 1, or 2, respectively, is checked.
6618 When used with @code{[[}, the @samp{<} and @samp{>} operators sort
6619 lexicographically using the current locale.
6620 The @code{test} command uses ASCII ordering.
6622 Unless otherwise specified, primaries that operate on files follow symbolic
6623 links and operate on the target of the link, rather than the link itself.
6627 True if @var{file} exists.
6630 True if @var{file} exists and is a block special file.
6633 True if @var{file} exists and is a character special file.
6636 True if @var{file} exists and is a directory.
6639 True if @var{file} exists.
6642 True if @var{file} exists and is a regular file.
6645 True if @var{file} exists and its set-group-id bit is set.
6648 True if @var{file} exists and is a symbolic link.
6651 True if @var{file} exists and its "sticky" bit is set.
6654 True if @var{file} exists and is a named pipe (FIFO).
6657 True if @var{file} exists and is readable.
6660 True if @var{file} exists and has a size greater than zero.
6663 True if file descriptor @var{fd} is open and refers to a terminal.
6666 True if @var{file} exists and its set-user-id bit is set.
6669 True if @var{file} exists and is writable.
6672 True if @var{file} exists and is executable.
6675 True if @var{file} exists and is owned by the effective group id.
6678 True if @var{file} exists and is a symbolic link.
6681 True if @var{file} exists and has been modified since it was last read.
6684 True if @var{file} exists and is owned by the effective user id.
6687 True if @var{file} exists and is a socket.
6689 @item @var{file1} -ef @var{file2}
6690 True if @var{file1} and @var{file2} refer to the same device and
6693 @item @var{file1} -nt @var{file2}
6694 True if @var{file1} is newer (according to modification date)
6695 than @var{file2}, or if @var{file1} exists and @var{file2} does not.
6697 @item @var{file1} -ot @var{file2}
6698 True if @var{file1} is older than @var{file2},
6699 or if @var{file2} exists and @var{file1} does not.
6701 @item -o @var{optname}
6702 True if the shell option @var{optname} is enabled.
6703 The list of options appears in the description of the @option{-o}
6704 option to the @code{set} builtin (@pxref{The Set Builtin}).
6706 @item -v @var{varname}
6707 True if the shell variable @var{varname} is set (has been assigned a value).
6709 @item -R @var{varname}
6710 True if the shell variable @var{varname} is set and is a name reference.
6712 @item -z @var{string}
6713 True if the length of @var{string} is zero.
6715 @item -n @var{string}
6717 True if the length of @var{string} is non-zero.
6719 @item @var{string1} == @var{string2}
6720 @itemx @var{string1} = @var{string2}
6721 True if the strings are equal.
6722 When used with the @code{[[} command, this performs pattern matching as
6723 described above (@pxref{Conditional Constructs}).
6725 @samp{=} should be used with the @code{test} command for @sc{posix} conformance.
6727 @item @var{string1} != @var{string2}
6728 True if the strings are not equal.
6730 @item @var{string1} < @var{string2}
6731 True if @var{string1} sorts before @var{string2} lexicographically.
6733 @item @var{string1} > @var{string2}
6734 True if @var{string1} sorts after @var{string2} lexicographically.
6736 @item @var{arg1} OP @var{arg2}
6738 @samp{-eq}, @samp{-ne}, @samp{-lt}, @samp{-le}, @samp{-gt}, or @samp{-ge}.
6739 These arithmetic binary operators return true if @var{arg1}
6740 is equal to, not equal to, less than, less than or equal to,
6741 greater than, or greater than or equal to @var{arg2},
6742 respectively. @var{Arg1} and @var{arg2}
6743 may be positive or negative integers.
6746 @node Shell Arithmetic
6747 @section Shell Arithmetic
6748 @cindex arithmetic, shell
6749 @cindex shell arithmetic
6750 @cindex expressions, arithmetic
6751 @cindex evaluation, arithmetic
6752 @cindex arithmetic evaluation
6754 The shell allows arithmetic expressions to be evaluated, as one of
6755 the shell expansions or by the @code{let} and the @option{-i} option
6756 to the @code{declare} builtins.
6758 Evaluation is done in fixed-width integers with no check for overflow,
6759 though division by 0 is trapped and flagged as an error.
6760 The operators and their precedence, associativity, and values
6761 are the same as in the C language.
6762 The following list of operators is grouped into levels of
6763 equal-precedence operators.
6764 The levels are listed in order of decreasing precedence.
6768 @item @var{id}++ @var{id}--
6769 variable post-increment and post-decrement
6771 @item ++@var{id} --@var{id}
6772 variable pre-increment and pre-decrement
6775 unary minus and plus
6778 logical and bitwise negation
6784 multiplication, division, remainder
6787 addition, subtraction
6790 left and right bitwise shifts
6796 equality and inequality
6802 bitwise exclusive OR
6813 @item expr ? expr : expr
6814 conditional operator
6816 @item = *= /= %= += -= <<= >>= &= ^= |=
6823 Shell variables are allowed as operands; parameter expansion is
6824 performed before the expression is evaluated.
6825 Within an expression, shell variables may also be referenced by name
6826 without using the parameter expansion syntax.
6827 A shell variable that is null or unset evaluates to 0 when referenced
6828 by name without using the parameter expansion syntax.
6829 The value of a variable is evaluated as an arithmetic expression
6830 when it is referenced, or when a variable which has been given the
6831 @var{integer} attribute using @samp{declare -i} is assigned a value.
6832 A null value evaluates to 0.
6833 A shell variable need not have its @var{integer} attribute turned on
6834 to be used in an expression.
6836 Constants with a leading 0 are interpreted as octal numbers.
6837 A leading @samp{0x} or @samp{0X} denotes hexadecimal. Otherwise,
6838 numbers take the form [@var{base}@code{#}]@var{n}, where the optional @var{base}
6839 is a decimal number between 2 and 64 representing the arithmetic
6840 base, and @var{n} is a number in that base.
6841 If @var{base}@code{#} is omitted, then base 10 is used.
6842 When specifying @var{n},
6843 the digits greater than 9 are represented by the lowercase letters,
6844 the uppercase letters, @samp{@@}, and @samp{_}, in that order.
6845 If @var{base} is less than or equal to 36, lowercase and uppercase
6846 letters may be used interchangeably to represent numbers between 10
6849 Operators are evaluated in order of precedence. Sub-expressions in
6850 parentheses are evaluated first and may override the precedence
6855 @cindex alias expansion
6857 @var{Aliases} allow a string to be substituted for a word when it is used
6858 as the first word of a simple command.
6859 The shell maintains a list of aliases that may be set and unset with
6860 the @code{alias} and @code{unalias} builtin commands.
6862 The first word of each simple command, if unquoted, is checked to see
6864 If so, that word is replaced by the text of the alias.
6865 The characters @samp{/}, @samp{$}, @samp{`}, @samp{=} and any of the
6866 shell metacharacters or quoting characters listed above may not appear
6868 The replacement text may contain any valid
6869 shell input, including shell metacharacters.
6870 The first word of the replacement text is tested for
6871 aliases, but a word that is identical to an alias being expanded
6872 is not expanded a second time.
6873 This means that one may alias @code{ls} to @code{"ls -F"},
6874 for instance, and Bash does not try to recursively expand the
6876 If the last character of the alias value is a
6877 @var{blank}, then the next command word following the
6878 alias is also checked for alias expansion.
6880 Aliases are created and listed with the @code{alias}
6881 command, and removed with the @code{unalias} command.
6883 There is no mechanism for using arguments in the replacement text,
6885 If arguments are needed, a shell function should be used
6886 (@pxref{Shell Functions}).
6888 Aliases are not expanded when the shell is not interactive,
6889 unless the @code{expand_aliases} shell option is set using
6890 @code{shopt} (@pxref{The Shopt Builtin}).
6892 The rules concerning the definition and use of aliases are
6893 somewhat confusing. Bash
6894 always reads at least one complete line
6895 of input before executing any
6896 of the commands on that line. Aliases are expanded when a
6897 command is read, not when it is executed. Therefore, an
6898 alias definition appearing on the same line as another
6899 command does not take effect until the next line of input is read.
6900 The commands following the alias definition
6901 on that line are not affected by the new alias.
6902 This behavior is also an issue when functions are executed.
6903 Aliases are expanded when a function definition is read,
6904 not when the function is executed, because a function definition
6905 is itself a command. As a consequence, aliases
6906 defined in a function are not available until after that
6907 function is executed. To be safe, always put
6908 alias definitions on a separate line, and do not use @code{alias}
6909 in compound commands.
6911 For almost every purpose, shell functions are preferred over aliases.
6917 Bash provides one-dimensional indexed and associative array variables.
6918 Any variable may be used as an indexed array;
6919 the @code{declare} builtin will explicitly declare an array.
6921 limit on the size of an array, nor any requirement that members
6922 be indexed or assigned contiguously.
6923 Indexed arrays are referenced using integers (including arithmetic
6924 expressions (@pxref{Shell Arithmetic})) and are zero-based;
6925 associative arrays use arbitrary strings.
6926 Unless otherwise noted, indexed array indices must be non-negative integers.
6928 An indexed array is created automatically if any variable is assigned to
6931 @var{name}[@var{subscript}]=@var{value}
6936 is treated as an arithmetic expression that must evaluate to a number.
6937 To explicitly declare an array, use
6939 declare -a @var{name}
6944 declare -a @var{name}[@var{subscript}]
6947 is also accepted; the @var{subscript} is ignored.
6950 Associative arrays are created using
6952 declare -A @var{name}.
6956 specified for an array variable using the @code{declare} and
6957 @code{readonly} builtins. Each attribute applies to all members of
6960 Arrays are assigned to using compound assignments of the form
6962 @var{name}=(@var{value1} @var{value2} @dots{} )
6966 @var{value} is of the form @code{[@var{subscript}]=}@var{string}.
6967 Indexed array assignments do not require anything but @var{string}.
6968 When assigning to indexed arrays, if
6969 the optional subscript is supplied, that index is assigned to;
6970 otherwise the index of the element assigned is the last index assigned
6971 to by the statement plus one. Indexing starts at zero.
6973 When assigning to an associative array, the subscript is required.
6975 This syntax is also accepted by the @code{declare}
6976 builtin. Individual array elements may be assigned to using the
6977 @code{@var{name}[@var{subscript}]=@var{value}} syntax introduced above.
6979 When assigning to an indexed array, if @var{name}
6980 is subscripted by a negative number, that number is
6981 interpreted as relative to one greater than the maximum index of
6982 @var{name}, so negative indices count back from the end of the
6983 array, and an index of -1 references the last element.
6985 Any element of an array may be referenced using
6986 @code{$@{@var{name}[@var{subscript}]@}}.
6987 The braces are required to avoid
6988 conflicts with the shell's filename expansion operators. If the
6989 @var{subscript} is @samp{@@} or @samp{*}, the word expands to all members
6990 of the array @var{name}. These subscripts differ only when the word
6991 appears within double quotes.
6992 If the word is double-quoted,
6993 @code{$@{@var{name}[*]@}} expands to a single word with
6994 the value of each array member separated by the first character of the
6995 @env{IFS} variable, and @code{$@{@var{name}[@@]@}} expands each element of
6996 @var{name} to a separate word. When there are no array members,
6997 @code{$@{@var{name}[@@]@}} expands to nothing.
6998 If the double-quoted expansion occurs within a word, the expansion of
6999 the first parameter is joined with the beginning part of the original
7000 word, and the expansion of the last parameter is joined with the last
7001 part of the original word.
7002 This is analogous to the
7003 expansion of the special parameters @samp{@@} and @samp{*}.
7004 @code{$@{#@var{name}[@var{subscript}]@}} expands to the length of
7005 @code{$@{@var{name}[@var{subscript}]@}}.
7006 If @var{subscript} is @samp{@@} or
7007 @samp{*}, the expansion is the number of elements in the array.
7008 If the @var{subscript}
7009 used to reference an element of an indexed array
7010 evaluates to a number less than zero, it is
7011 interpreted as relative to one greater than the maximum index of the array,
7012 so negative indices count back from the end of the array,
7013 and an index of -1 refers to the last element.
7015 Referencing an array variable without a subscript is equivalent to
7016 referencing with a subscript of 0.
7017 Any reference to a variable using a valid subscript is legal, and
7018 @code{bash} will create an array if necessary.
7020 An array variable is considered set if a subscript has been assigned a
7021 value. The null string is a valid value.
7023 It is possible to obtain the keys (indices) of an array as well as the values.
7024 $@{!@var{name}[@@]@} and $@{!@var{name}[*]@} expand to the indices
7025 assigned in array variable @var{name}.
7026 The treatment when in double quotes is similar to the expansion of the
7027 special parameters @samp{@@} and @samp{*} within double quotes.
7029 The @code{unset} builtin is used to destroy arrays.
7030 @code{unset @var{name}[@var{subscript}]}
7031 destroys the array element at index @var{subscript}.
7032 Negative subscripts to indexed arrays are interpreted as described above.
7033 Care must be taken to avoid unwanted side effects caused by filename
7035 @code{unset @var{name}}, where @var{name} is an array, removes the
7036 entire array. A subscript of @samp{*} or @samp{@@} also removes the
7039 The @code{declare}, @code{local}, and @code{readonly}
7040 builtins each accept a @option{-a} option to specify an indexed
7041 array and a @option{-A} option to specify an associative array.
7042 If both options are supplied, @option{-A} takes precedence.
7043 The @code{read} builtin accepts a @option{-a}
7044 option to assign a list of words read from the standard input
7045 to an array, and can read values from the standard input into
7046 individual array elements. The @code{set} and @code{declare}
7047 builtins display array values in a way that allows them to be
7050 @node The Directory Stack
7051 @section The Directory Stack
7052 @cindex directory stack
7055 * Directory Stack Builtins:: Bash builtin commands to manipulate
7056 the directory stack.
7059 The directory stack is a list of recently-visited directories. The
7060 @code{pushd} builtin adds directories to the stack as it changes
7061 the current directory, and the @code{popd} builtin removes specified
7062 directories from the stack and changes the current directory to
7063 the directory removed. The @code{dirs} builtin displays the contents
7064 of the directory stack. The current directory is always the "top"
7065 of the directory stack.
7067 The contents of the directory stack are also visible
7068 as the value of the @env{DIRSTACK} shell variable.
7070 @node Directory Stack Builtins
7071 @subsection Directory Stack Builtins
7078 dirs [-clpv] [+@var{N} | -@var{N}]
7081 Display the list of currently remembered directories. Directories
7082 are added to the list with the @code{pushd} command; the
7083 @code{popd} command removes directories from the list.
7084 The current directory is always the first directory in the stack.
7088 Clears the directory stack by deleting all of the elements.
7090 Produces a listing using full pathnames;
7091 the default listing format uses a tilde to denote the home directory.
7093 Causes @code{dirs} to print the directory stack with one entry per
7096 Causes @code{dirs} to print the directory stack with one entry per
7097 line, prefixing each entry with its index in the stack.
7099 Displays the @var{N}th directory (counting from the left of the
7100 list printed by @code{dirs} when invoked without options), starting
7103 Displays the @var{N}th directory (counting from the right of the
7104 list printed by @code{dirs} when invoked without options), starting
7111 popd [-n] [+@var{N} | -@var{N}]
7114 When no arguments are given, @code{popd}
7115 removes the top directory from the stack and
7116 performs a @code{cd} to the new top directory.
7117 The elements are numbered from 0 starting at the first directory
7118 listed with @code{dirs}; that is, @code{popd} is equivalent to @code{popd +0}.
7122 Suppresses the normal change of directory when removing directories
7123 from the stack, so that only the stack is manipulated.
7125 Removes the @var{N}th directory (counting from the left of the
7126 list printed by @code{dirs}), starting with zero.
7128 Removes the @var{N}th directory (counting from the right of the
7129 list printed by @code{dirs}), starting with zero.
7135 pushd [-n] [@var{+N} | @var{-N} | @var{dir}]
7138 Save the current directory on the top of the directory stack
7139 and then @code{cd} to @var{dir}.
7140 With no arguments, @code{pushd} exchanges the top two directories
7141 and makes the new top the current directory.
7145 Suppresses the normal change of directory when rotating or
7146 adding directories to the stack, so that only the stack is manipulated.
7148 Brings the @var{N}th directory (counting from the left of the
7149 list printed by @code{dirs}, starting with zero) to the top of
7150 the list by rotating the stack.
7152 Brings the @var{N}th directory (counting from the right of the
7153 list printed by @code{dirs}, starting with zero) to the top of
7154 the list by rotating the stack.
7156 Makes @var{dir} be the top of the stack, making
7157 it the new current directory as if it had been supplied as an argument
7158 to the @code{cd} builtin.
7162 @node Controlling the Prompt
7163 @section Controlling the Prompt
7166 The value of the variable @env{PROMPT_COMMAND} is examined just before
7167 Bash prints each primary prompt. If @env{PROMPT_COMMAND} is set and
7168 has a non-null value, then the
7169 value is executed just as if it had been typed on the command line.
7171 In addition, the following table describes the special characters which
7172 can appear in the prompt variables @env{PS1} to @env{PS4}:
7178 The date, in "Weekday Month Date" format (e.g., "Tue May 26").
7179 @item \D@{@var{format}@}
7180 The @var{format} is passed to @code{strftime}(3) and the result is inserted
7181 into the prompt string; an empty @var{format} results in a locale-specific
7182 time representation. The braces are required.
7184 An escape character.
7186 The hostname, up to the first `.'.
7190 The number of jobs currently managed by the shell.
7192 The basename of the shell's terminal device name.
7198 The name of the shell, the basename of @code{$0} (the portion
7199 following the final slash).
7201 The time, in 24-hour HH:MM:SS format.
7203 The time, in 12-hour HH:MM:SS format.
7205 The time, in 12-hour am/pm format.
7207 The time, in 24-hour HH:MM format.
7209 The username of the current user.
7211 The version of Bash (e.g., 2.00)
7213 The release of Bash, version + patchlevel (e.g., 2.00.0)
7215 The current working directory, with @env{$HOME} abbreviated with a tilde
7216 (uses the @env{$PROMPT_DIRTRIM} variable).
7218 The basename of @env{$PWD}, with @env{$HOME} abbreviated with a tilde.
7220 The history number of this command.
7222 The command number of this command.
7224 If the effective uid is 0, @code{#}, otherwise @code{$}.
7226 The character whose ASCII code is the octal value @var{nnn}.
7230 Begin a sequence of non-printing characters. This could be used to
7231 embed a terminal control sequence into the prompt.
7233 End a sequence of non-printing characters.
7236 The command number and the history number are usually different:
7237 the history number of a command is its position in the history
7238 list, which may include commands restored from the history file
7239 (@pxref{Bash History Facilities}), while the command number is
7240 the position in the sequence of commands executed during the current
7243 After the string is decoded, it is expanded via
7244 parameter expansion, command substitution, arithmetic
7245 expansion, and quote removal, subject to the value of the
7246 @code{promptvars} shell option (@pxref{Bash Builtins}).
7248 @node The Restricted Shell
7249 @section The Restricted Shell
7250 @cindex restricted shell
7252 If Bash is started with the name @code{rbash}, or the
7253 @option{--restricted}
7256 option is supplied at invocation, the shell becomes restricted.
7257 A restricted shell is used to
7258 set up an environment more controlled than the standard shell.
7259 A restricted shell behaves identically to @code{bash}
7260 with the exception that the following are disallowed or not performed:
7264 Changing directories with the @code{cd} builtin.
7266 Setting or unsetting the values of the @env{SHELL}, @env{PATH},
7267 @env{ENV}, or @env{BASH_ENV} variables.
7269 Specifying command names containing slashes.
7271 Specifying a filename containing a slash as an argument to the @code{.}
7274 Specifying a filename containing a slash as an argument to the @option{-p}
7275 option to the @code{hash} builtin command.
7277 Importing function definitions from the shell environment at startup.
7279 Parsing the value of @env{SHELLOPTS} from the shell environment at startup.
7281 Redirecting output using the @samp{>}, @samp{>|}, @samp{<>}, @samp{>&},
7282 @samp{&>}, and @samp{>>} redirection operators.
7284 Using the @code{exec} builtin to replace the shell with another command.
7286 Adding or deleting builtin commands with the
7287 @option{-f} and @option{-d} options to the @code{enable} builtin.
7289 Using the @code{enable} builtin command to enable disabled shell builtins.
7291 Specifying the @option{-p} option to the @code{command} builtin.
7293 Turning off restricted mode with @samp{set +r} or @samp{set +o restricted}.
7296 These restrictions are enforced after any startup files are read.
7298 When a command that is found to be a shell script is executed
7299 (@pxref{Shell Scripts}), @code{rbash} turns off any restrictions in
7300 the shell spawned to execute the script.
7302 @node Bash POSIX Mode
7303 @section Bash POSIX Mode
7306 Starting Bash with the @option{--posix} command-line option or executing
7307 @samp{set -o posix} while Bash is running will cause Bash to conform more
7308 closely to the @sc{posix} standard by changing the behavior to
7309 match that specified by @sc{posix} in areas where the Bash default differs.
7311 When invoked as @code{sh}, Bash enters @sc{posix} mode after reading the
7314 The following list is what's changed when `@sc{posix} mode' is in effect:
7318 When a command in the hash table no longer exists, Bash will re-search
7319 @env{$PATH} to find the new location. This is also available with
7320 @samp{shopt -s checkhash}.
7323 The message printed by the job control code and builtins when a job
7324 exits with a non-zero status is `Done(status)'.
7327 The message printed by the job control code and builtins when a job
7328 is stopped is `Stopped(@var{signame})', where @var{signame} is, for
7329 example, @code{SIGTSTP}.
7332 Alias expansion is always enabled, even in non-interactive shells.
7335 Reserved words appearing in a context where reserved words are recognized
7336 do not undergo alias expansion.
7339 The @sc{posix} @env{PS1} and @env{PS2} expansions of @samp{!} to
7340 the history number and @samp{!!} to @samp{!} are enabled,
7341 and parameter expansion is performed on the values of @env{PS1} and
7342 @env{PS2} regardless of the setting of the @code{promptvars} option.
7345 The @sc{posix} startup files are executed (@env{$ENV}) rather than
7346 the normal Bash files.
7349 Tilde expansion is only performed on assignments preceding a command
7350 name, rather than on all assignment statements on the line.
7353 The default history file is @file{~/.sh_history} (this is the
7354 default value of @env{$HISTFILE}).
7357 Redirection operators do not perform filename expansion on the word
7358 in the redirection unless the shell is interactive.
7361 Redirection operators do not perform word splitting on the word in the
7365 Function names must be valid shell @code{name}s. That is, they may not
7366 contain characters other than letters, digits, and underscores, and
7367 may not start with a digit. Declaring a function with an invalid name
7368 causes a fatal syntax error in non-interactive shells.
7371 Function names may not be the same as one of the @sc{posix} special
7375 @sc{posix} special builtins are found before shell functions
7376 during command lookup.
7379 Literal tildes that appear as the first character in elements of
7380 the @env{PATH} variable are not expanded as described above
7381 under @ref{Tilde Expansion}.
7384 The @code{time} reserved word may be used by itself as a command. When
7385 used in this way, it displays timing statistics for the shell and its
7386 completed children. The @env{TIMEFORMAT} variable controls the format
7387 of the timing information.
7390 When parsing and expanding a $@{@dots{}@} expansion that appears within
7391 double quotes, single quotes are no longer special and cannot be used to
7392 quote a closing brace or other special character, unless the operator is
7393 one of those defined to perform pattern removal. In this case, they do
7394 not have to appear as matched pairs.
7397 The parser does not recognize @code{time} as a reserved word if the next
7398 token begins with a @samp{-}.
7401 The @samp{!} character does not introduce history expansion within a
7402 double-quoted string, even if the @code{histexpand} option is enabled.
7405 If a @sc{posix} special builtin returns an error status, a
7406 non-interactive shell exits. The fatal errors are those listed in
7407 the @sc{posix} standard, and include things like passing incorrect options,
7408 redirection errors, variable assignment errors for assignments preceding
7409 the command name, and so on.
7412 A non-interactive shell exits with an error status if a variable
7413 assignment error occurs when no command name follows the assignment
7415 A variable assignment error occurs, for example, when trying to assign
7416 a value to a readonly variable.
7419 A non-interactive shell exits with an error status if a variable
7420 assignment error occurs in an assignment statement preceding a special
7421 builtin, but not with any other simple command.
7424 A non-interactive shell exits with an error status if the iteration
7425 variable in a @code{for} statement or the selection variable in a
7426 @code{select} statement is a readonly variable.
7429 Non-interactive shells exit if @var{filename} in @code{.} @var{filename}
7433 Non-interactive shells exit if a syntax error in an arithmetic expansion
7434 results in an invalid expression.
7437 Non-interactive shells exit on word expansion errors.
7440 Non-interactive shells exit if there is a syntax error in a script read
7441 with the @code{.} or @code{source} builtins, or in a string processed by
7442 the @code{eval} builtin.
7445 Process substitution is not available.
7448 While variable indirection is available, it may not be applied to the
7449 @samp{#} and @samp{?} special parameters.
7452 Assignment statements preceding @sc{posix} special builtins
7453 persist in the shell environment after the builtin completes.
7456 Assignment statements preceding shell function calls persist in the
7457 shell environment after the function returns, as if a @sc{posix}
7458 special builtin command had been executed.
7461 The @code{command} builtin does not prevent builtins that take assignment
7462 statements as arguments from expanding them as assignment statements;
7463 when not in @sc{posix} mode, assignment builtins lose their assignment
7464 statement expansion properties when preceded by @code{command}.
7467 The @code{bg} builtin uses the required format to describe each job placed
7468 in the background, which does not include an indication of whether the job
7469 is the current or previous job.
7472 The output of @samp{kill -l} prints all the signal names on a single line,
7473 separated by spaces, without the @samp{SIG} prefix.
7476 The @code{kill} builtin does not accept signal names with a @samp{SIG}
7480 The @code{export} and @code{readonly} builtin commands display their
7481 output in the format required by @sc{posix}.
7484 The @code{trap} builtin displays signal names without the leading
7488 The @code{trap} builtin doesn't check the first argument for a possible
7489 signal specification and revert the signal handling to the original
7490 disposition if it is, unless that argument consists solely of digits and
7491 is a valid signal number. If users want to reset the handler for a given
7492 signal to the original disposition, they should use @samp{-} as the
7496 The @code{.} and @code{source} builtins do not search the current directory
7497 for the filename argument if it is not found by searching @env{PATH}.
7500 Enabling @sc{posix} mode has the effect of setting the
7501 @code{inherit_errexit} option, so
7502 subshells spawned to execute command substitutions inherit the value of
7503 the @option{-e} option from the parent shell.
7504 When the @code{inherit_errexit} option is not enabled,
7505 Bash clears the @option{-e} option in such subshells.
7508 When the @code{alias} builtin displays alias definitions, it does not
7509 display them with a leading @samp{alias } unless the @option{-p} option
7513 When the @code{set} builtin is invoked without options, it does not display
7514 shell function names and definitions.
7517 When the @code{set} builtin is invoked without options, it displays
7518 variable values without quotes, unless they contain shell metacharacters,
7519 even if the result contains nonprinting characters.
7522 When the @code{cd} builtin is invoked in @var{logical} mode, and the pathname
7523 constructed from @code{$PWD} and the directory name supplied as an argument
7524 does not refer to an existing directory, @code{cd} will fail instead of
7525 falling back to @var{physical} mode.
7528 The @code{pwd} builtin verifies that the value it prints is the same as the
7529 current directory, even if it is not asked to check the file system with the
7533 When listing the history, the @code{fc} builtin does not include an
7534 indication of whether or not a history entry has been modified.
7537 The default editor used by @code{fc} is @code{ed}.
7540 The @code{type} and @code{command} builtins will not report a non-executable
7541 file as having been found, though the shell will attempt to execute such a
7542 file if it is the only so-named file found in @code{$PATH}.
7545 The @code{vi} editing mode will invoke the @code{vi} editor directly when
7546 the @samp{v} command is run, instead of checking @code{$VISUAL} and
7550 When the @code{xpg_echo} option is enabled, Bash does not attempt to interpret
7551 any arguments to @code{echo} as options. Each argument is displayed, after
7552 escape characters are converted.
7555 The @code{ulimit} builtin uses a block size of 512 bytes for the @option{-c}
7556 and @option{-f} options.
7559 The arrival of @code{SIGCHLD} when a trap is set on @code{SIGCHLD} does
7560 not interrupt the @code{wait} builtin and cause it to return immediately.
7561 The trap command is run once for each child that exits.
7564 The @code{read} builtin may be interrupted by a signal for which a trap
7566 If Bash receives a trapped signal while executing @code{read}, the trap
7567 handler executes and @code{read} returns an exit status greater than 128.
7571 There is other @sc{posix} behavior that Bash does not implement by
7572 default even when in @sc{posix} mode.
7578 The @code{fc} builtin checks @code{$EDITOR} as a program to edit history
7579 entries if @code{FCEDIT} is unset, rather than defaulting directly to
7580 @code{ed}. @code{fc} uses @code{ed} if @code{EDITOR} is unset.
7583 As noted above, Bash requires the @code{xpg_echo} option to be enabled for
7584 the @code{echo} builtin to be fully conformant.
7588 Bash can be configured to be @sc{posix}-conformant by default, by specifying
7589 the @option{--enable-strict-posix-default} to @code{configure} when building
7590 (@pxref{Optional Features}).
7593 @chapter Job Control
7595 This chapter discusses what job control is, how it works, and how
7596 Bash allows you to access its facilities.
7599 * Job Control Basics:: How job control works.
7600 * Job Control Builtins:: Bash builtin commands used to interact
7602 * Job Control Variables:: Variables Bash uses to customize job
7606 @node Job Control Basics
7607 @section Job Control Basics
7611 @cindex suspending jobs
7614 refers to the ability to selectively stop (suspend)
7615 the execution of processes and continue (resume)
7616 their execution at a later point. A user typically employs
7617 this facility via an interactive interface supplied jointly
7618 by the operating system kernel's terminal driver and Bash.
7620 The shell associates a @var{job} with each pipeline. It keeps a
7621 table of currently executing jobs, which may be listed with the
7622 @code{jobs} command. When Bash starts a job
7623 asynchronously, it prints a line that looks
7629 indicating that this job is job number 1 and that the process @sc{id}
7630 of the last process in the pipeline associated with this job is
7631 25647. All of the processes in a single pipeline are members of
7632 the same job. Bash uses the @var{job} abstraction as the
7633 basis for job control.
7635 To facilitate the implementation of the user interface to job
7636 control, the operating system maintains the notion of a current terminal
7637 process group @sc{id}. Members of this process group (processes whose
7638 process group @sc{id} is equal to the current terminal process group
7639 @sc{id}) receive keyboard-generated signals such as @code{SIGINT}.
7640 These processes are said to be in the foreground. Background
7641 processes are those whose process group @sc{id} differs from the
7642 terminal's; such processes are immune to keyboard-generated
7643 signals. Only foreground processes are allowed to read from or, if
7644 the user so specifies with @code{stty tostop}, write to the terminal.
7645 Background processes which attempt to
7646 read from (write to when @code{stty tostop} is in effect) the
7647 terminal are sent a @code{SIGTTIN} (@code{SIGTTOU})
7648 signal by the kernel's terminal driver,
7649 which, unless caught, suspends the process.
7651 If the operating system on which Bash is running supports
7652 job control, Bash contains facilities to use it. Typing the
7653 @var{suspend} character (typically @samp{^Z}, Control-Z) while a
7654 process is running causes that process to be stopped and returns
7655 control to Bash. Typing the @var{delayed suspend} character
7656 (typically @samp{^Y}, Control-Y) causes the process to be stopped
7657 when it attempts to read input from the terminal, and control to
7658 be returned to Bash. The user then manipulates the state of
7659 this job, using the @code{bg} command to continue it in the
7660 background, the @code{fg} command to continue it in the
7661 foreground, or the @code{kill} command to kill it. A @samp{^Z}
7662 takes effect immediately, and has the additional side effect of
7663 causing pending output and typeahead to be discarded.
7665 There are a number of ways to refer to a job in the shell. The
7666 character @samp{%} introduces a job specification (@var{jobspec}).
7668 Job number @code{n} may be referred to as @samp{%n}.
7669 The symbols @samp{%%} and @samp{%+} refer to the shell's notion of the
7670 current job, which is the last job stopped while it was in the foreground
7671 or started in the background.
7672 A single @samp{%} (with no accompanying job specification) also refers
7674 The previous job may be referenced using @samp{%-}.
7675 If there is only a single job, @samp{%+} and @samp{%-} can both be used
7676 to refer to that job.
7677 In output pertaining to jobs (e.g., the output of the @code{jobs}
7678 command), the current job is always flagged with a @samp{+}, and the
7679 previous job with a @samp{-}.
7681 A job may also be referred to
7682 using a prefix of the name used to start it, or using a substring
7683 that appears in its command line. For example, @samp{%ce} refers
7684 to a stopped @code{ce} job. Using @samp{%?ce}, on the
7685 other hand, refers to any job containing the string @samp{ce} in
7686 its command line. If the prefix or substring matches more than one job,
7687 Bash reports an error.
7689 Simply naming a job can be used to bring it into the foreground:
7690 @samp{%1} is a synonym for @samp{fg %1}, bringing job 1 from the
7691 background into the foreground. Similarly, @samp{%1 &} resumes
7692 job 1 in the background, equivalent to @samp{bg %1}
7694 The shell learns immediately whenever a job changes state.
7695 Normally, Bash waits until it is about to print a prompt
7696 before reporting changes in a job's status so as to not interrupt
7698 If the @option{-b} option to the @code{set} builtin is enabled,
7699 Bash reports such changes immediately (@pxref{The Set Builtin}).
7700 Any trap on @code{SIGCHLD} is executed for each child process
7703 If an attempt to exit Bash is made while jobs are stopped, (or running, if
7704 the @code{checkjobs} option is enabled -- see @ref{The Shopt Builtin}), the
7705 shell prints a warning message, and if the @code{checkjobs} option is
7706 enabled, lists the jobs and their statuses.
7707 The @code{jobs} command may then be used to inspect their status.
7708 If a second attempt to exit is made without an intervening command,
7709 Bash does not print another warning, and any stopped jobs are terminated.
7711 @node Job Control Builtins
7712 @section Job Control Builtins
7719 bg [@var{jobspec} @dots{}]
7722 Resume each suspended job @var{jobspec} in the background, as if it
7723 had been started with @samp{&}.
7724 If @var{jobspec} is not supplied, the current job is used.
7725 The return status is zero unless it is run when job control is not
7726 enabled, or, when run with job control enabled, any
7727 @var{jobspec} was not found or specifies a job
7728 that was started without job control.
7736 Resume the job @var{jobspec} in the foreground and make it the current job.
7737 If @var{jobspec} is not supplied, the current job is used.
7738 The return status is that of the command placed into the foreground,
7739 or non-zero if run when job control is disabled or, when run with
7740 job control enabled, @var{jobspec} does not specify a valid job or
7741 @var{jobspec} specifies a job that was started without job control.
7746 jobs [-lnprs] [@var{jobspec}]
7747 jobs -x @var{command} [@var{arguments}]
7750 The first form lists the active jobs. The options have the
7755 List process @sc{id}s in addition to the normal information.
7758 Display information only about jobs that have changed status since
7759 the user was last notified of their status.
7762 List only the process @sc{id} of the job's process group leader.
7765 Display only running jobs.
7768 Display only stopped jobs.
7771 If @var{jobspec} is given,
7772 output is restricted to information about that job.
7773 If @var{jobspec} is not supplied, the status of all jobs is
7776 If the @option{-x} option is supplied, @code{jobs} replaces any
7777 @var{jobspec} found in @var{command} or @var{arguments} with the
7778 corresponding process group @sc{id}, and executes @var{command},
7779 passing it @var{argument}s, returning its exit status.
7784 kill [-s @var{sigspec}] [-n @var{signum}] [-@var{sigspec}] @var{jobspec} or @var{pid}
7785 kill -l|-L [@var{exit_status}]
7788 Send a signal specified by @var{sigspec} or @var{signum} to the process
7789 named by job specification @var{jobspec} or process @sc{id} @var{pid}.
7790 @var{sigspec} is either a case-insensitive signal name such as
7791 @code{SIGINT} (with or without the @code{SIG} prefix)
7792 or a signal number; @var{signum} is a signal number.
7793 If @var{sigspec} and @var{signum} are not present, @code{SIGTERM} is used.
7794 The @option{-l} option lists the signal names.
7795 If any arguments are supplied when @option{-l} is given, the names of the
7796 signals corresponding to the arguments are listed, and the return status
7798 @var{exit_status} is a number specifying a signal number or the exit
7799 status of a process terminated by a signal.
7800 The @option{-L} option is equivalent to @option{-l}.
7801 The return status is zero if at least one signal was successfully sent,
7802 or non-zero if an error occurs or an invalid option is encountered.
7807 wait [-n] [@var{jobspec} or @var{pid} @dots{}]
7810 Wait until the child process specified by each process @sc{id} @var{pid}
7811 or job specification @var{jobspec} exits and return the exit status of the
7812 last command waited for.
7813 If a job spec is given, all processes in the job are waited for.
7814 If no arguments are given, all currently active child processes are
7815 waited for, and the return status is zero.
7816 If the @option{-n} option is supplied, @code{wait} waits for any job to
7817 terminate and returns its exit status.
7818 If neither @var{jobspec} nor @var{pid} specifies an active child process
7819 of the shell, the return status is 127.
7824 disown [-ar] [-h] [@var{jobspec} @dots{} | @var{pid} @dots{} ]
7827 Without options, remove each @var{jobspec} from the table of
7829 If the @option{-h} option is given, the job is not removed from the table,
7830 but is marked so that @code{SIGHUP} is not sent to the job if the shell
7831 receives a @code{SIGHUP}.
7832 If @var{jobspec} is not present, and neither the @option{-a} nor the
7833 @option{-r} option is supplied, the current job is used.
7834 If no @var{jobspec} is supplied, the @option{-a} option means to remove or
7835 mark all jobs; the @option{-r} option without a @var{jobspec}
7836 argument restricts operation to running jobs.
7844 Suspend the execution of this shell until it receives a
7845 @code{SIGCONT} signal.
7846 A login shell cannot be suspended; the @option{-f}
7847 option can be used to override this and force the suspension.
7850 When job control is not active, the @code{kill} and @code{wait}
7851 builtins do not accept @var{jobspec} arguments. They must be
7852 supplied process @sc{id}s.
7854 @node Job Control Variables
7855 @section Job Control Variables
7860 This variable controls how the shell interacts with the user and
7861 job control. If this variable exists then single word simple
7862 commands without redirections are treated as candidates for resumption
7863 of an existing job. There is no ambiguity allowed; if there is
7864 more than one job beginning with the string typed, then
7865 the most recently accessed job will be selected.
7866 The name of a stopped job, in this context, is the command line
7867 used to start it. If this variable is set to the value @samp{exact},
7868 the string supplied must match the name of a stopped job exactly;
7869 if set to @samp{substring},
7870 the string supplied needs to match a substring of the name of a
7871 stopped job. The @samp{substring} value provides functionality
7872 analogous to the @samp{%?} job @sc{id} (@pxref{Job Control Basics}).
7873 If set to any other value, the supplied string must
7874 be a prefix of a stopped job's name; this provides functionality
7875 analogous to the @samp{%} job @sc{id}.
7879 @set readline-appendix
7880 @set history-appendix
7881 @cindex Readline, how to use
7882 @include rluser.texi
7883 @cindex History, how to use
7884 @include hsuser.texi
7885 @clear readline-appendix
7886 @clear history-appendix
7888 @node Installing Bash
7889 @chapter Installing Bash
7891 This chapter provides basic instructions for installing Bash on
7892 the various supported platforms. The distribution supports the
7893 @sc{gnu} operating systems, nearly every version of Unix, and several
7894 non-Unix systems such as BeOS and Interix.
7895 Other independent ports exist for
7896 @sc{ms-dos}, @sc{os/2}, and Windows platforms.
7899 * Basic Installation:: Installation instructions.
7900 * Compilers and Options:: How to set special options for various
7902 * Compiling For Multiple Architectures:: How to compile Bash for more
7903 than one kind of system from
7904 the same source tree.
7905 * Installation Names:: How to set the various paths used by the installation.
7906 * Specifying the System Type:: How to configure Bash for a particular system.
7907 * Sharing Defaults:: How to share default configuration values among GNU
7909 * Operation Controls:: Options recognized by the configuration program.
7910 * Optional Features:: How to enable and disable optional features when
7914 @node Basic Installation
7915 @section Basic Installation
7916 @cindex installation
7917 @cindex configuration
7918 @cindex Bash installation
7919 @cindex Bash configuration
7921 These are installation instructions for Bash.
7923 The simplest way to compile Bash is:
7927 @code{cd} to the directory containing the source code and type
7928 @samp{./configure} to configure Bash for your system. If you're
7929 using @code{csh} on an old version of System V, you might need to
7930 type @samp{sh ./configure} instead to prevent @code{csh} from trying
7931 to execute @code{configure} itself.
7933 Running @code{configure} takes some time.
7934 While running, it prints messages telling which features it is
7938 Type @samp{make} to compile Bash and build the @code{bashbug} bug
7942 Optionally, type @samp{make tests} to run the Bash test suite.
7945 Type @samp{make install} to install @code{bash} and @code{bashbug}.
7946 This will also install the manual pages and Info file.
7950 The @code{configure} shell script attempts to guess correct
7951 values for various system-dependent variables used during
7952 compilation. It uses those values to create a @file{Makefile} in
7953 each directory of the package (the top directory, the
7954 @file{builtins}, @file{doc}, and @file{support} directories,
7955 each directory under @file{lib}, and several others). It also creates a
7956 @file{config.h} file containing system-dependent definitions.
7957 Finally, it creates a shell script named @code{config.status} that you
7958 can run in the future to recreate the current configuration, a
7959 file @file{config.cache} that saves the results of its tests to
7960 speed up reconfiguring, and a file @file{config.log} containing
7961 compiler output (useful mainly for debugging @code{configure}).
7963 @file{config.cache} contains results you don't want to keep, you
7964 may remove or edit it.
7966 To find out more about the options and arguments that the
7967 @code{configure} script understands, type
7970 bash-2.04$ ./configure --help
7974 at the Bash prompt in your Bash source directory.
7976 If you need to do unusual things to compile Bash, please
7977 try to figure out how @code{configure} could check whether or not
7978 to do them, and mail diffs or instructions to
7979 @email{bash-maintainers@@gnu.org} so they can be
7980 considered for the next release.
7982 The file @file{configure.ac} is used to create @code{configure}
7983 by a program called Autoconf. You only need
7984 @file{configure.ac} if you want to change it or regenerate
7985 @code{configure} using a newer version of Autoconf. If
7986 you do this, make sure you are using Autoconf version 2.50 or
7989 You can remove the program binaries and object files from the
7990 source code directory by typing @samp{make clean}. To also remove the
7991 files that @code{configure} created (so you can compile Bash for
7992 a different kind of computer), type @samp{make distclean}.
7994 @node Compilers and Options
7995 @section Compilers and Options
7997 Some systems require unusual options for compilation or linking
7998 that the @code{configure} script does not know about. You can
7999 give @code{configure} initial values for variables by setting
8000 them in the environment. Using a Bourne-compatible shell, you
8001 can do that on the command line like this:
8004 CC=c89 CFLAGS=-O2 LIBS=-lposix ./configure
8007 On systems that have the @code{env} program, you can do it like this:
8010 env CPPFLAGS=-I/usr/local/include LDFLAGS=-s ./configure
8013 The configuration process uses GCC to build Bash if it
8016 @node Compiling For Multiple Architectures
8017 @section Compiling For Multiple Architectures
8019 You can compile Bash for more than one kind of computer at the
8020 same time, by placing the object files for each architecture in their
8021 own directory. To do this, you must use a version of @code{make} that
8022 supports the @code{VPATH} variable, such as GNU @code{make}.
8024 directory where you want the object files and executables to go and run
8025 the @code{configure} script from the source directory. You may need to
8026 supply the @option{--srcdir=PATH} argument to tell @code{configure} where the
8027 source files are. @code{configure} automatically checks for the
8028 source code in the directory that @code{configure} is in and in `..'.
8030 If you have to use a @code{make} that does not supports the @code{VPATH}
8031 variable, you can compile Bash for one architecture at a
8032 time in the source code directory. After you have installed
8033 Bash for one architecture, use @samp{make distclean} before
8034 reconfiguring for another architecture.
8036 Alternatively, if your system supports symbolic links, you can use the
8037 @file{support/mkclone} script to create a build tree which has
8038 symbolic links back to each file in the source directory. Here's an
8039 example that creates a build directory in the current directory from a
8040 source directory @file{/usr/gnu/src/bash-2.0}:
8043 bash /usr/gnu/src/bash-2.0/support/mkclone -s /usr/gnu/src/bash-2.0 .
8047 The @code{mkclone} script requires Bash, so you must have already built
8048 Bash for at least one architecture before you can create build
8049 directories for other architectures.
8051 @node Installation Names
8052 @section Installation Names
8054 By default, @samp{make install} will install into
8055 @file{/usr/local/bin}, @file{/usr/local/man}, etc. You can
8056 specify an installation prefix other than @file{/usr/local} by
8057 giving @code{configure} the option @option{--prefix=@var{PATH}},
8058 or by specifying a value for the @code{DESTDIR} @samp{make}
8059 variable when running @samp{make install}.
8061 You can specify separate installation prefixes for
8062 architecture-specific files and architecture-independent files.
8063 If you give @code{configure} the option
8064 @option{--exec-prefix=@var{PATH}}, @samp{make install} will use
8065 @var{PATH} as the prefix for installing programs and libraries.
8066 Documentation and other data files will still use the regular prefix.
8068 @node Specifying the System Type
8069 @section Specifying the System Type
8071 There may be some features @code{configure} can not figure out
8072 automatically, but need to determine by the type of host Bash
8073 will run on. Usually @code{configure} can figure that
8074 out, but if it prints a message saying it can not guess the host
8075 type, give it the @option{--host=TYPE} option. @samp{TYPE} can
8076 either be a short name for the system type, such as @samp{sun4},
8077 or a canonical name with three fields: @samp{CPU-COMPANY-SYSTEM}
8078 (e.g., @samp{i386-unknown-freebsd4.2}).
8080 See the file @file{support/config.sub} for the possible
8081 values of each field.
8083 @node Sharing Defaults
8084 @section Sharing Defaults
8086 If you want to set default values for @code{configure} scripts to
8087 share, you can create a site shell script called
8088 @code{config.site} that gives default values for variables like
8089 @code{CC}, @code{cache_file}, and @code{prefix}. @code{configure}
8090 looks for @file{PREFIX/share/config.site} if it exists, then
8091 @file{PREFIX/etc/config.site} if it exists. Or, you can set the
8092 @code{CONFIG_SITE} environment variable to the location of the site
8093 script. A warning: the Bash @code{configure} looks for a site script,
8094 but not all @code{configure} scripts do.
8096 @node Operation Controls
8097 @section Operation Controls
8099 @code{configure} recognizes the following options to control how it
8104 @item --cache-file=@var{file}
8105 Use and save the results of the tests in
8106 @var{file} instead of @file{./config.cache}. Set @var{file} to
8107 @file{/dev/null} to disable caching, for debugging
8111 Print a summary of the options to @code{configure}, and exit.
8116 Do not print messages saying which checks are being made.
8118 @item --srcdir=@var{dir}
8119 Look for the Bash source code in directory @var{dir}. Usually
8120 @code{configure} can determine that directory automatically.
8123 Print the version of Autoconf used to generate the @code{configure}
8127 @code{configure} also accepts some other, not widely used, boilerplate
8128 options. @samp{configure --help} prints the complete list.
8130 @node Optional Features
8131 @section Optional Features
8133 The Bash @code{configure} has a number of @option{--enable-@var{feature}}
8134 options, where @var{feature} indicates an optional part of Bash.
8135 There are also several @option{--with-@var{package}} options,
8136 where @var{package} is something like @samp{bash-malloc} or @samp{purify}.
8137 To turn off the default use of a package, use
8138 @option{--without-@var{package}}. To configure Bash without a feature
8139 that is enabled by default, use @option{--disable-@var{feature}}.
8141 Here is a complete list of the @option{--enable-} and
8142 @option{--with-} options that the Bash @code{configure} recognizes.
8146 Define if you are using the Andrew File System from Transarc.
8148 @item --with-bash-malloc
8149 Use the Bash version of
8150 @code{malloc} in the directory @file{lib/malloc}. This is not the same
8151 @code{malloc} that appears in @sc{gnu} libc, but an older version
8152 originally derived from the 4.2 @sc{bsd} @code{malloc}. This @code{malloc}
8153 is very fast, but wastes some space on each allocation.
8154 This option is enabled by default.
8155 The @file{NOTES} file contains a list of systems for
8156 which this should be turned off, and @code{configure} disables this
8157 option automatically for a number of systems.
8160 Use the curses library instead of the termcap library. This should
8161 be supplied if your system has an inadequate or incomplete termcap
8164 @item --with-gnu-malloc
8165 A synonym for @code{--with-bash-malloc}.
8167 @item --with-installed-readline[=@var{PREFIX}]
8168 Define this to make Bash link with a locally-installed version of Readline
8169 rather than the version in @file{lib/readline}. This works only with
8170 Readline 5.0 and later versions. If @var{PREFIX} is @code{yes} or not
8171 supplied, @code{configure} uses the values of the make variables
8172 @code{includedir} and @code{libdir}, which are subdirectories of @code{prefix}
8173 by default, to find the installed version of Readline if it is not in
8174 the standard system include and library directories.
8175 If @var{PREFIX} is @code{no}, Bash links with the version in
8176 @file{lib/readline}.
8177 If @var{PREFIX} is set to any other value, @code{configure} treats it as
8178 a directory pathname and looks for
8179 the installed version of Readline in subdirectories of that directory
8180 (include files in @var{PREFIX}/@code{include} and the library in
8181 @var{PREFIX}/@code{lib}).
8184 Define this to use the Purify memory allocation checker from Rational
8187 @item --enable-minimal-config
8188 This produces a shell with minimal features, close to the historical
8192 There are several @option{--enable-} options that alter how Bash is
8193 compiled and linked, rather than changing run-time features.
8196 @item --enable-largefile
8197 Enable support for @uref{http://www.sas.com/standards/large_file/x_open.20Mar96.html,
8198 large files} if the operating system requires special compiler options
8199 to build programs which can access large files. This is enabled by
8200 default, if the operating system provides large file support.
8202 @item --enable-profiling
8203 This builds a Bash binary that produces profiling information to be
8204 processed by @code{gprof} each time it is executed.
8206 @item --enable-static-link
8207 This causes Bash to be linked statically, if @code{gcc} is being used.
8208 This could be used to build a version to use as root's shell.
8211 The @samp{minimal-config} option can be used to disable all of
8212 the following options, but it is processed first, so individual
8213 options may be enabled using @samp{enable-@var{feature}}.
8215 All of the following options except for @samp{disabled-builtins},
8216 @samp{direxpand-default}, and
8217 @samp{xpg-echo-default} are
8218 enabled by default, unless the operating system does not provide the
8222 @item --enable-alias
8223 Allow alias expansion and include the @code{alias} and @code{unalias}
8224 builtins (@pxref{Aliases}).
8226 @item --enable-arith-for-command
8227 Include support for the alternate form of the @code{for} command
8228 that behaves like the C language @code{for} statement
8229 (@pxref{Looping Constructs}).
8231 @item --enable-array-variables
8232 Include support for one-dimensional array shell variables
8235 @item --enable-bang-history
8236 Include support for @code{csh}-like history substitution
8237 (@pxref{History Interaction}).
8239 @item --enable-brace-expansion
8240 Include @code{csh}-like brace expansion
8241 ( @code{b@{a,b@}c} @expansion{} @code{bac bbc} ).
8242 See @ref{Brace Expansion}, for a complete description.
8244 @item --enable-casemod-attributes
8245 Include support for case-modifying attributes in the @code{declare} builtin
8246 and assignment statements. Variables with the @var{uppercase} attribute,
8247 for example, will have their values converted to uppercase upon assignment.
8249 @item --enable-casemod-expansion
8250 Include support for case-modifying word expansions.
8252 @item --enable-command-timing
8253 Include support for recognizing @code{time} as a reserved word and for
8254 displaying timing statistics for the pipeline following @code{time}
8255 (@pxref{Pipelines}).
8256 This allows pipelines as well as shell builtins and functions to be timed.
8258 @item --enable-cond-command
8259 Include support for the @code{[[} conditional command.
8260 (@pxref{Conditional Constructs}).
8262 @item --enable-cond-regexp
8263 Include support for matching @sc{posix} regular expressions using the
8264 @samp{=~} binary operator in the @code{[[} conditional command.
8265 (@pxref{Conditional Constructs}).
8267 @item --enable-coprocesses
8268 Include support for coprocesses and the @code{coproc} reserved word
8269 (@pxref{Pipelines}).
8271 @item --enable-debugger
8272 Include support for the bash debugger (distributed separately).
8274 @item --enable-direxpand-default
8275 Cause the @code{direxpand} shell option (@pxref{The Shopt Builtin})
8276 to be enabled by default when the shell starts.
8277 It is normally disabled by default.
8279 @item --enable-directory-stack
8280 Include support for a @code{csh}-like directory stack and the
8281 @code{pushd}, @code{popd}, and @code{dirs} builtins
8282 (@pxref{The Directory Stack}).
8284 @item --enable-disabled-builtins
8285 Allow builtin commands to be invoked via @samp{builtin xxx}
8286 even after @code{xxx} has been disabled using @samp{enable -n xxx}.
8287 See @ref{Bash Builtins}, for details of the @code{builtin} and
8288 @code{enable} builtin commands.
8290 @item --enable-dparen-arithmetic
8291 Include support for the @code{((@dots{}))} command
8292 (@pxref{Conditional Constructs}).
8294 @item --enable-extended-glob
8295 Include support for the extended pattern matching features described
8296 above under @ref{Pattern Matching}.
8298 @item --enable-extended-glob-default
8299 Set the default value of the @var{extglob} shell option described
8300 above under @ref{The Shopt Builtin} to be enabled.
8302 @item --enable-function-import
8303 Include support for importing function definitions exported by another
8304 instance of the shell from the environment. This option is enabled by
8307 @item --enable-glob-asciirange-default
8308 Set the default value of the @var{globasciiranges} shell option described
8309 above under @ref{The Shopt Builtin} to be enabled.
8310 This controls the behavior of character ranges when used in pattern matching
8311 bracket expressions.
8313 @item --enable-help-builtin
8314 Include the @code{help} builtin, which displays help on shell builtins and
8315 variables (@pxref{Bash Builtins}).
8317 @item --enable-history
8318 Include command history and the @code{fc} and @code{history}
8319 builtin commands (@pxref{Bash History Facilities}).
8321 @item --enable-job-control
8322 This enables the job control features (@pxref{Job Control}),
8323 if the operating system supports them.
8325 @item --enable-multibyte
8326 This enables support for multibyte characters if the operating
8327 system provides the necessary support.
8329 @item --enable-net-redirections
8330 This enables the special handling of filenames of the form
8331 @code{/dev/tcp/@var{host}/@var{port}} and
8332 @code{/dev/udp/@var{host}/@var{port}}
8333 when used in redirections (@pxref{Redirections}).
8335 @item --enable-process-substitution
8336 This enables process substitution (@pxref{Process Substitution}) if
8337 the operating system provides the necessary support.
8339 @item --enable-progcomp
8340 Enable the programmable completion facilities
8341 (@pxref{Programmable Completion}).
8342 If Readline is not enabled, this option has no effect.
8344 @item --enable-prompt-string-decoding
8345 Turn on the interpretation of a number of backslash-escaped characters
8346 in the @env{$PS1}, @env{$PS2}, @env{$PS3}, and @env{$PS4} prompt
8347 strings. See @ref{Controlling the Prompt}, for a complete list of prompt
8348 string escape sequences.
8350 @item --enable-readline
8351 Include support for command-line editing and history with the Bash
8352 version of the Readline library (@pxref{Command Line Editing}).
8354 @item --enable-restricted
8355 Include support for a @dfn{restricted shell}. If this is enabled, Bash,
8356 when called as @code{rbash}, enters a restricted mode. See
8357 @ref{The Restricted Shell}, for a description of restricted mode.
8359 @item --enable-select
8360 Include the @code{select} compound command, which allows the generation of
8361 simple menus (@pxref{Conditional Constructs}).
8363 @item --enable-separate-helpfiles
8364 Use external files for the documentation displayed by the @code{help} builtin
8365 instead of storing the text internally.
8367 @item --enable-single-help-strings
8368 Store the text displayed by the @code{help} builtin as a single string for
8369 each help topic. This aids in translating the text to different languages.
8370 You may need to disable this if your compiler cannot handle very long string
8373 @item --enable-strict-posix-default
8374 Make Bash @sc{posix}-conformant by default (@pxref{Bash POSIX Mode}).
8376 @item --enable-usg-echo-default
8377 A synonym for @code{--enable-xpg-echo-default}.
8379 @item --enable-xpg-echo-default
8380 Make the @code{echo} builtin expand backslash-escaped characters by default,
8381 without requiring the @option{-e} option.
8382 This sets the default value of the @code{xpg_echo} shell option to @code{on},
8383 which makes the Bash @code{echo} behave more like the version specified in
8384 the Single Unix Specification, version 3.
8385 @xref{Bash Builtins}, for a description of the escape sequences that
8386 @code{echo} recognizes.
8389 The file @file{config-top.h} contains C Preprocessor
8390 @samp{#define} statements for options which are not settable from
8392 Some of these are not meant to be changed; beware of the consequences if
8394 Read the comments associated with each definition for more
8395 information about its effect.
8397 @node Reporting Bugs
8398 @appendix Reporting Bugs
8400 Please report all bugs you find in Bash.
8401 But first, you should
8402 make sure that it really is a bug, and that it appears in the latest
8404 The latest version of Bash is always available for FTP from
8405 @uref{ftp://ftp.gnu.org/pub/gnu/bash/}.
8407 Once you have determined that a bug actually exists, use the
8408 @code{bashbug} command to submit a bug report.
8409 If you have a fix, you are encouraged to mail that as well!
8410 Suggestions and `philosophical' bug reports may be mailed
8411 to @email{bug-bash@@gnu.org} or posted to the Usenet
8412 newsgroup @code{gnu.bash.bug}.
8414 All bug reports should include:
8417 The version number of Bash.
8419 The hardware and operating system.
8421 The compiler used to compile Bash.
8423 A description of the bug behaviour.
8425 A short script or `recipe' which exercises the bug and may be used
8430 @code{bashbug} inserts the first three items automatically into
8431 the template it provides for filing a bug report.
8433 Please send all reports concerning this manual to
8434 @email{bug-bash@@gnu.org}.
8436 @node Major Differences From The Bourne Shell
8437 @appendix Major Differences From The Bourne Shell
8439 Bash implements essentially the same grammar, parameter and
8440 variable expansion, redirection, and quoting as the Bourne Shell.
8441 Bash uses the @sc{posix} standard as the specification of
8442 how these features are to be implemented. There are some
8443 differences between the traditional Bourne shell and Bash; this
8444 section quickly details the differences of significance. A
8445 number of these differences are explained in greater depth in
8447 This section uses the version of @code{sh} included in SVR4.2 (the
8448 last version of the historical Bourne shell) as the baseline reference.
8453 Bash is @sc{posix}-conformant, even where the @sc{posix} specification
8454 differs from traditional @code{sh} behavior (@pxref{Bash POSIX Mode}).
8457 Bash has multi-character invocation options (@pxref{Invoking Bash}).
8460 Bash has command-line editing (@pxref{Command Line Editing}) and
8461 the @code{bind} builtin.
8464 Bash provides a programmable word completion mechanism
8465 (@pxref{Programmable Completion}), and builtin commands
8466 @code{complete}, @code{compgen}, and @code{compopt}, to
8470 Bash has command history (@pxref{Bash History Facilities}) and the
8471 @code{history} and @code{fc} builtins to manipulate it.
8472 The Bash history list maintains timestamp information and uses the
8473 value of the @code{HISTTIMEFORMAT} variable to display it.
8476 Bash implements @code{csh}-like history expansion
8477 (@pxref{History Interaction}).
8480 Bash has one-dimensional array variables (@pxref{Arrays}), and the
8481 appropriate variable expansions and assignment syntax to use them.
8482 Several of the Bash builtins take options to act on arrays.
8483 Bash provides a number of built-in array variables.
8486 The @code{$'@dots{}'} quoting syntax, which expands ANSI-C
8487 backslash-escaped characters in the text between the single quotes,
8488 is supported (@pxref{ANSI-C Quoting}).
8491 Bash supports the @code{$"@dots{}"} quoting syntax to do
8492 locale-specific translation of the characters between the double
8493 quotes. The @option{-D}, @option{--dump-strings}, and @option{--dump-po-strings}
8494 invocation options list the translatable strings found in a script
8495 (@pxref{Locale Translation}).
8498 Bash implements the @code{!} keyword to negate the return value of
8499 a pipeline (@pxref{Pipelines}).
8500 Very useful when an @code{if} statement needs to act only if a test fails.
8501 The Bash @samp{-o pipefail} option to @code{set} will cause a pipeline to
8502 return a failure status if any command fails.
8505 Bash has the @code{time} reserved word and command timing (@pxref{Pipelines}).
8506 The display of the timing statistics may be controlled with the
8507 @env{TIMEFORMAT} variable.
8510 Bash implements the @code{for (( @var{expr1} ; @var{expr2} ; @var{expr3} ))}
8511 arithmetic for command, similar to the C language (@pxref{Looping Constructs}).
8514 Bash includes the @code{select} compound command, which allows the
8515 generation of simple menus (@pxref{Conditional Constructs}).
8518 Bash includes the @code{[[} compound command, which makes conditional
8519 testing part of the shell grammar (@pxref{Conditional Constructs}), including
8520 optional regular expression matching.
8523 Bash provides optional case-insensitive matching for the @code{case} and
8524 @code{[[} constructs.
8527 Bash includes brace expansion (@pxref{Brace Expansion}) and tilde
8528 expansion (@pxref{Tilde Expansion}).
8531 Bash implements command aliases and the @code{alias} and @code{unalias}
8532 builtins (@pxref{Aliases}).
8535 Bash provides shell arithmetic, the @code{((} compound command
8536 (@pxref{Conditional Constructs}),
8537 and arithmetic expansion (@pxref{Shell Arithmetic}).
8540 Variables present in the shell's initial environment are automatically
8541 exported to child processes. The Bourne shell does not normally do
8542 this unless the variables are explicitly marked using the @code{export}
8546 Bash supports the @samp{+=} assignment operator, which appends to the value
8547 of the variable named on the left hand side.
8550 Bash includes the @sc{posix} pattern removal @samp{%}, @samp{#}, @samp{%%}
8551 and @samp{##} expansions to remove leading or trailing substrings from
8552 variable values (@pxref{Shell Parameter Expansion}).
8555 The expansion @code{$@{#xx@}}, which returns the length of @code{$@{xx@}},
8556 is supported (@pxref{Shell Parameter Expansion}).
8559 The expansion @code{$@{var:}@var{offset}@code{[:}@var{length}@code{]@}},
8560 which expands to the substring of @code{var}'s value of length
8561 @var{length}, beginning at @var{offset}, is present
8562 (@pxref{Shell Parameter Expansion}).
8566 @code{$@{var/[/]}@var{pattern}@code{[/}@var{replacement}@code{]@}},
8567 which matches @var{pattern} and replaces it with @var{replacement} in
8568 the value of @code{var}, is available (@pxref{Shell Parameter Expansion}).
8571 The expansion @code{$@{!@var{prefix}*@}} expansion, which expands to
8572 the names of all shell variables whose names begin with @var{prefix},
8573 is available (@pxref{Shell Parameter Expansion}).
8576 Bash has @var{indirect} variable expansion using @code{$@{!word@}}
8577 (@pxref{Shell Parameter Expansion}).
8580 Bash can expand positional parameters beyond @code{$9} using
8581 @code{$@{@var{num}@}}.
8584 The @sc{posix} @code{$()} form of command substitution
8585 is implemented (@pxref{Command Substitution}),
8586 and preferred to the Bourne shell's @code{``} (which
8587 is also implemented for backwards compatibility).
8590 Bash has process substitution (@pxref{Process Substitution}).
8593 Bash automatically assigns variables that provide information about the
8594 current user (@env{UID}, @env{EUID}, and @env{GROUPS}), the current host
8595 (@env{HOSTTYPE}, @env{OSTYPE}, @env{MACHTYPE}, and @env{HOSTNAME}),
8596 and the instance of Bash that is running (@env{BASH},
8597 @env{BASH_VERSION}, and @env{BASH_VERSINFO}). @xref{Bash Variables},
8601 The @env{IFS} variable is used to split only the results of expansion,
8602 not all words (@pxref{Word Splitting}).
8603 This closes a longstanding shell security hole.
8606 The filename expansion bracket expression code uses @samp{!} and @samp{^}
8607 to negate the set of characters between the brackets.
8608 The Bourne shell uses only @samp{!}.
8611 Bash implements the full set of @sc{posix} filename expansion operators,
8612 including @var{character classes}, @var{equivalence classes}, and
8613 @var{collating symbols} (@pxref{Filename Expansion}).
8616 Bash implements extended pattern matching features when the @code{extglob}
8617 shell option is enabled (@pxref{Pattern Matching}).
8620 It is possible to have a variable and a function with the same name;
8621 @code{sh} does not separate the two name spaces.
8624 Bash functions are permitted to have local variables using the
8625 @code{local} builtin, and thus useful recursive functions may be written
8626 (@pxref{Bash Builtins}).
8629 Variable assignments preceding commands affect only that command, even
8630 builtins and functions (@pxref{Environment}).
8631 In @code{sh}, all variable assignments
8632 preceding commands are global unless the command is executed from the
8636 Bash performs filename expansion on filenames specified as operands
8637 to input and output redirection operators (@pxref{Redirections}).
8640 Bash contains the @samp{<>} redirection operator, allowing a file to be
8641 opened for both reading and writing, and the @samp{&>} redirection
8642 operator, for directing standard output and standard error to the same
8643 file (@pxref{Redirections}).
8646 Bash includes the @samp{<<<} redirection operator, allowing a string to
8647 be used as the standard input to a command.
8650 Bash implements the @samp{[n]<&@var{word}} and @samp{[n]>&@var{word}}
8651 redirection operators, which move one file descriptor to another.
8654 Bash treats a number of filenames specially when they are
8655 used in redirection operators (@pxref{Redirections}).
8658 Bash can open network connections to arbitrary machines and services
8659 with the redirection operators (@pxref{Redirections}).
8662 The @code{noclobber} option is available to avoid overwriting existing
8663 files with output redirection (@pxref{The Set Builtin}).
8664 The @samp{>|} redirection operator may be used to override @code{noclobber}.
8667 The Bash @code{cd} and @code{pwd} builtins (@pxref{Bourne Shell Builtins})
8668 each take @option{-L} and @option{-P} options to switch between logical and
8672 Bash allows a function to override a builtin with the same name, and provides
8673 access to that builtin's functionality within the function via the
8674 @code{builtin} and @code{command} builtins (@pxref{Bash Builtins}).
8677 The @code{command} builtin allows selective disabling of functions
8678 when command lookup is performed (@pxref{Bash Builtins}).
8681 Individual builtins may be enabled or disabled using the @code{enable}
8682 builtin (@pxref{Bash Builtins}).
8685 The Bash @code{exec} builtin takes additional options that allow users
8686 to control the contents of the environment passed to the executed
8687 command, and what the zeroth argument to the command is to be
8688 (@pxref{Bourne Shell Builtins}).
8691 Shell functions may be exported to children via the environment
8692 using @code{export -f} (@pxref{Shell Functions}).
8695 The Bash @code{export}, @code{readonly}, and @code{declare} builtins can
8696 take a @option{-f} option to act on shell functions, a @option{-p} option to
8697 display variables with various attributes set in a format that can be
8698 used as shell input, a @option{-n} option to remove various variable
8699 attributes, and @samp{name=value} arguments to set variable attributes
8700 and values simultaneously.
8703 The Bash @code{hash} builtin allows a name to be associated with
8704 an arbitrary filename, even when that filename cannot be found by
8705 searching the @env{$PATH}, using @samp{hash -p}
8706 (@pxref{Bourne Shell Builtins}).
8709 Bash includes a @code{help} builtin for quick reference to shell
8710 facilities (@pxref{Bash Builtins}).
8713 The @code{printf} builtin is available to display formatted output
8714 (@pxref{Bash Builtins}).
8717 The Bash @code{read} builtin (@pxref{Bash Builtins})
8718 will read a line ending in @samp{\} with
8719 the @option{-r} option, and will use the @env{REPLY} variable as a
8720 default if no non-option arguments are supplied.
8721 The Bash @code{read} builtin
8722 also accepts a prompt string with the @option{-p} option and will use
8723 Readline to obtain the line when given the @option{-e} option.
8724 The @code{read} builtin also has additional options to control input:
8725 the @option{-s} option will turn off echoing of input characters as
8726 they are read, the @option{-t} option will allow @code{read} to time out
8727 if input does not arrive within a specified number of seconds, the
8728 @option{-n} option will allow reading only a specified number of
8729 characters rather than a full line, and the @option{-d} option will read
8730 until a particular character rather than newline.
8733 The @code{return} builtin may be used to abort execution of scripts
8734 executed with the @code{.} or @code{source} builtins
8735 (@pxref{Bourne Shell Builtins}).
8738 Bash includes the @code{shopt} builtin, for finer control of shell
8739 optional capabilities (@pxref{The Shopt Builtin}), and allows these options
8740 to be set and unset at shell invocation (@pxref{Invoking Bash}).
8743 Bash has much more optional behavior controllable with the @code{set}
8744 builtin (@pxref{The Set Builtin}).
8747 The @samp{-x} (@option{xtrace}) option displays commands other than
8748 simple commands when performing an execution trace
8749 (@pxref{The Set Builtin}).
8752 The @code{test} builtin (@pxref{Bourne Shell Builtins})
8753 is slightly different, as it implements the @sc{posix} algorithm,
8754 which specifies the behavior based on the number of arguments.
8757 Bash includes the @code{caller} builtin, which displays the context of
8758 any active subroutine call (a shell function or a script executed with
8759 the @code{.} or @code{source} builtins). This supports the bash
8763 The @code{trap} builtin (@pxref{Bourne Shell Builtins}) allows a
8764 @code{DEBUG} pseudo-signal specification, similar to @code{EXIT}.
8765 Commands specified with a @code{DEBUG} trap are executed before every
8766 simple command, @code{for} command, @code{case} command,
8767 @code{select} command, every arithmetic @code{for} command, and before
8768 the first command executes in a shell function.
8769 The @code{DEBUG} trap is not inherited by shell functions unless the
8770 function has been given the @code{trace} attribute or the
8771 @code{functrace} option has been enabled using the @code{shopt} builtin.
8772 The @code{extdebug} shell option has additional effects on the
8775 The @code{trap} builtin (@pxref{Bourne Shell Builtins}) allows an
8776 @code{ERR} pseudo-signal specification, similar to @code{EXIT} and @code{DEBUG}.
8777 Commands specified with an @code{ERR} trap are executed after a simple
8778 command fails, with a few exceptions.
8779 The @code{ERR} trap is not inherited by shell functions unless the
8780 @code{-o errtrace} option to the @code{set} builtin is enabled.
8782 The @code{trap} builtin (@pxref{Bourne Shell Builtins}) allows a
8783 @code{RETURN} pseudo-signal specification, similar to
8784 @code{EXIT} and @code{DEBUG}.
8785 Commands specified with an @code{RETURN} trap are executed before
8786 execution resumes after a shell function or a shell script executed with
8787 @code{.} or @code{source} returns.
8788 The @code{RETURN} trap is not inherited by shell functions unless the
8789 function has been given the @code{trace} attribute or the
8790 @code{functrace} option has been enabled using the @code{shopt} builtin.
8793 The Bash @code{type} builtin is more extensive and gives more information
8794 about the names it finds (@pxref{Bash Builtins}).
8797 The Bash @code{umask} builtin permits a @option{-p} option to cause
8798 the output to be displayed in the form of a @code{umask} command
8799 that may be reused as input (@pxref{Bourne Shell Builtins}).
8802 Bash implements a @code{csh}-like directory stack, and provides the
8803 @code{pushd}, @code{popd}, and @code{dirs} builtins to manipulate it
8804 (@pxref{The Directory Stack}).
8805 Bash also makes the directory stack visible as the value of the
8806 @env{DIRSTACK} shell variable.
8809 Bash interprets special backslash-escaped characters in the prompt
8810 strings when interactive (@pxref{Controlling the Prompt}).
8813 The Bash restricted mode is more useful (@pxref{The Restricted Shell});
8814 the SVR4.2 shell restricted mode is too limited.
8817 The @code{disown} builtin can remove a job from the internal shell
8818 job table (@pxref{Job Control Builtins}) or suppress the sending
8819 of @code{SIGHUP} to a job when the shell exits as the result of a
8823 Bash includes a number of features to support a separate debugger for
8827 The SVR4.2 shell has two privilege-related builtins
8828 (@code{mldmode} and @code{priv}) not present in Bash.
8831 Bash does not have the @code{stop} or @code{newgrp} builtins.
8834 Bash does not use the @env{SHACCT} variable or perform shell accounting.
8837 The SVR4.2 @code{sh} uses a @env{TIMEOUT} variable like Bash uses
8843 More features unique to Bash may be found in @ref{Bash Features}.
8846 @appendixsec Implementation Differences From The SVR4.2 Shell
8848 Since Bash is a completely new implementation, it does not suffer from
8849 many of the limitations of the SVR4.2 shell. For instance:
8854 Bash does not fork a subshell when redirecting into or out of
8855 a shell control structure such as an @code{if} or @code{while}
8859 Bash does not allow unbalanced quotes. The SVR4.2 shell will silently
8860 insert a needed closing quote at @code{EOF} under certain circumstances.
8861 This can be the cause of some hard-to-find errors.
8864 The SVR4.2 shell uses a baroque memory management scheme based on
8865 trapping @code{SIGSEGV}. If the shell is started from a process with
8866 @code{SIGSEGV} blocked (e.g., by using the @code{system()} C library
8867 function call), it misbehaves badly.
8870 In a questionable attempt at security, the SVR4.2 shell,
8871 when invoked without the @option{-p} option, will alter its real
8872 and effective @sc{uid} and @sc{gid} if they are less than some
8873 magic threshold value, commonly 100.
8874 This can lead to unexpected results.
8877 The SVR4.2 shell does not allow users to trap @code{SIGSEGV},
8878 @code{SIGALRM}, or @code{SIGCHLD}.
8881 The SVR4.2 shell does not allow the @env{IFS}, @env{MAILCHECK},
8882 @env{PATH}, @env{PS1}, or @env{PS2} variables to be unset.
8885 The SVR4.2 shell treats @samp{^} as the undocumented equivalent of
8889 Bash allows multiple option arguments when it is invoked (@code{-x -v});
8890 the SVR4.2 shell allows only one option argument (@code{-xv}). In
8891 fact, some versions of the shell dump core if the second argument begins
8895 The SVR4.2 shell exits a script if any builtin fails; Bash exits
8896 a script only if one of the @sc{posix} special builtins fails, and
8897 only for certain failures, as enumerated in the @sc{posix} standard.
8900 The SVR4.2 shell behaves differently when invoked as @code{jsh}
8901 (it turns on job control).
8904 @node GNU Free Documentation License
8905 @appendix GNU Free Documentation License
8913 * Builtin Index:: Index of Bash builtin commands.
8914 * Reserved Word Index:: Index of Bash reserved words.
8915 * Variable Index:: Quick reference helps you find the
8917 * Function Index:: Index of bindable Readline functions.
8918 * Concept Index:: General index for concepts described in
8923 @appendixsec Index of Shell Builtin Commands
8926 @node Reserved Word Index
8927 @appendixsec Index of Shell Reserved Words
8930 @node Variable Index
8931 @appendixsec Parameter and Variable Index
8934 @node Function Index
8935 @appendixsec Function Index
8939 @appendixsec Concept Index