1 \input texinfo.tex @c -*- texinfo -*-
3 @setfilename bashref.info
4 @settitle Bash Reference Manual
8 Last Change: Tue Mar 14 11:38:10 EST 2000
13 @set UPDATED 14 March 2000
14 @set UPDATE-MONTH March 2000
20 @setchapternewpage odd
26 @dircategory Utilities
28 * Bash: (bash). The GNU Bourne-Again SHell.
32 This text is a brief description of the features that are present in
35 This is Edition @value{EDITION}, last updated @value{UPDATED},
36 of @cite{The GNU Bash Reference Manual},
37 for @code{Bash}, Version @value{VERSION}.
39 Copyright (C) 1991-1999 Free Software Foundation, Inc.
41 Permission is granted to make and distribute verbatim copies of
42 this manual provided the copyright notice and this permission notice
43 are preserved on all copies.
46 Permission is granted to process this file through TeX and print the
47 results, provided the printed document carries copying permission
48 notice identical to this one except for the removal of this paragraph
49 (this paragraph not being relevant to the printed manual).
52 Permission is granted to copy and distribute modified versions of this
53 manual under the conditions for verbatim copying, provided that the entire
54 resulting derived work is distributed under the terms of a permission
55 notice identical to this one.
57 Permission is granted to copy and distribute translations of this manual
58 into another language, under the above conditions for modified versions,
59 except that this permission notice may be stated in a translation approved
60 by the Free Software Foundation.
65 @title Bash Reference Manual
66 @subtitle Reference Documentation for Bash
67 @subtitle Edition @value{EDITION}, for @code{Bash} Version @value{VERSION}.
68 @subtitle @value{UPDATE-MONTH}
69 @author Chet Ramey, Case Western Reserve University
70 @author Brian Fox, Free Software Foundation
72 @vskip 0pt plus 1filll
73 Copyright @copyright{} 1991-1999 Free Software Foundation, Inc.
75 Permission is granted to make and distribute verbatim copies of
76 this manual provided the copyright notice and this permission notice
77 are preserved on all copies.
79 Permission is granted to copy and distribute modified versions of this
80 manual under the conditions for verbatim copying, provided that the entire
81 resulting derived work is distributed under the terms of a permission
82 notice identical to this one.
84 Permission is granted to copy and distribute translations of this manual
85 into another language, under the above conditions for modified versions,
86 except that this permission notice may be stated in a translation approved
87 by the Free Software Foundation.
91 @node Top, Introduction, (dir), (dir)
96 This text is a brief description of the features that are present in
99 This is Edition @value{EDITION}, last updated @value{UPDATED},
100 of @cite{The GNU Bash Reference Manual},
101 for @code{Bash}, Version @value{VERSION}.
103 Copyright (C) 1991, 1993, 1996 Free Software Foundation, Inc.
105 Bash contains features that appear in other popular shells, and some
106 features that only appear in Bash. Some of the shells that Bash has
107 borrowed concepts from are the Bourne Shell (@file{sh}), the Korn Shell
108 (@file{ksh}), and the C-shell (@file{csh} and its successor,
109 @file{tcsh}). The following menu breaks the features up into
110 categories based upon which one of these other shells inspired the
113 This manual is meant as a brief introduction to features found in
114 Bash. The Bash manual page should be used as the definitive
115 reference on shell behavior.
118 * Introduction:: An introduction to the shell.
120 * Definitions:: Some definitions used in the rest of this
123 * Basic Shell Features:: The shell "building blocks".
125 * Shell Builtin Commands:: Commands that are a part of the shell.
127 * Shell Variables:: Variables used or set by Bash.
129 * Bash Features:: Features found only in Bash.
131 * Job Control:: A chapter describing what job control is
132 and how Bash allows you to use it.
134 * Using History Interactively:: Chapter dealing with history expansion
137 * Command Line Editing:: Chapter describing the command line
140 * Installing Bash:: How to build and install Bash on your system.
142 * Reporting Bugs:: How to report bugs in Bash.
144 * Major Differences From The Bourne Shell:: A terse list of the differences
145 between Bash and historical
148 * Builtin Index:: Index of Bash builtin commands.
150 * Reserved Word Index:: Index of Bash reserved words.
152 * Variable Index:: Quick reference helps you find the
155 * Function Index:: Index of bindable Readline functions.
157 * Concept Index:: General index for concepts described in
163 @chapter Introduction
165 * What is Bash?:: A short description of Bash.
167 * What is a shell?:: A brief introduction to shells.
171 @section What is Bash?
173 Bash is the shell, or command language interpreter,
174 for the @sc{gnu} operating system.
175 The name is an acronym for the @samp{Bourne-Again SHell},
176 a pun on Stephen Bourne, the author of the direct ancestor of
177 the current Unix shell @code{/bin/sh},
178 which appeared in the Seventh Edition Bell Labs Research version
181 Bash is largely compatible with @code{sh} and incorporates useful
182 features from the Korn shell @code{ksh} and the C shell @code{csh}.
183 It is intended to be a conformant implementation of the @sc{ieee}
184 @sc{posix} Shell and Tools specification (@sc{ieee} Working Group 1003.2).
185 It offers functional improvements over @code{sh} for both interactive and
188 While the @sc{gnu} operating system provides other shells, including
189 a version of @code{csh}, Bash is the default shell.
190 Like other @sc{gnu} software, Bash is quite portable. It currently runs
191 on nearly every version of Unix and a few other operating systems @minus{}
192 independently-supported ports exist for @sc{ms-dos}, @sc{os/2},
193 Windows @sc{95/98}, and Windows @sc{nt}.
195 @node What is a shell?
196 @section What is a shell?
198 At its base, a shell is simply a macro processor that executes
199 commands. A Unix shell is both a command interpreter, which
200 provides the user interface to the rich set of @sc{gnu} utilities,
201 and a programming language, allowing these utilitites to be
202 combined. Files containing commands can be created, and become
203 commands themselves. These new commands have the same status as
204 system commands in directories such as @file{/bin}, allowing users
205 or groups to establish custom environments.
207 A shell allows execution of @sc{gnu} commands, both synchronously and
209 The shell waits for synchronous commands to complete before accepting
210 more input; asynchronous commands continue to execute in parallel
211 with the shell while it reads and executes additional commands.
212 The @dfn{redirection} constructs permit
213 fine-grained control of the input and output of those commands.
214 Moreover, the shell allows control over the contents of commands'
216 Shells may be used interactively or non-interactively: they accept
217 input typed from the keyboard or from a file.
219 Shells also provide a small set of built-in
220 commands (@dfn{builtins}) implementing functionality impossible
221 or inconvenient to obtain via separate utilities.
222 For example, @code{cd}, @code{break}, @code{continue}, and
223 @code{exec}) cannot be implemented outside of the shell because
224 they directly manipulate the shell itself.
225 The @code{history}, @code{getopts}, @code{kill}, or @code{pwd}
226 builtins, among others, could be implemented in separate utilities,
227 but they are more convenient to use as builtin commands.
228 All of the shell builtins are described in
231 While executing commands is essential, most of the power (and
232 complexity) of shells is due to their embedded programming
233 languages. Like any high-level language, the shell provides
234 variables, flow control constructs, quoting, and functions.
236 Shells offer features geared specifically for
237 interactive use rather than to augment the programming language.
238 These interactive features include job control, command line
239 editing, history and aliases. Each of these features is
240 described in this manual.
244 These definitions are used throughout the remainder of this manual.
250 A family of open system standards based on Unix. Bash
251 is concerned with @sc{posix} 1003.2, the Shell and Tools Standard.
254 A space or tab character.
258 A command that is implemented internally by the shell itself, rather
259 than by an executable program somewhere in the file system.
261 @item control operator
262 @cindex control operator
263 A @code{word} that performs a control function. It is a @code{newline}
264 or one of the following:
265 @samp{||}, @samp{&&}, @samp{&}, @samp{;}, @samp{;;},
266 @samp{|}, @samp{(}, or @samp{)}.
270 The value returned by a command to its caller.
274 A unit of text that is the result of one of the shell expansions. After
275 expansion, when executing a command, the resulting fields are used as
276 the command name and arguments.
280 A string of characters used to identify a file.
284 A set of processes comprising a pipeline, and any processes descended
285 from it, that are all in the same process group.
289 A mechanism by which users can selectively stop (suspend) and restart
290 (resume) execution of processes.
293 @cindex metacharacter
294 A character that, when unquoted, separates words. A metacharacter is
295 a @code{blank} or one of the following characters:
296 @samp{|}, @samp{&}, @samp{;}, @samp{(}, @samp{)}, @samp{<}, or
302 A @code{word} consisting solely of letters, numbers, and underscores,
303 and beginning with a letter or underscore. @code{Name}s are used as
304 shell variable and function names.
305 Also referred to as an @code{identifier}.
308 @cindex operator, shell
309 A @code{control operator} or a @code{redirection operator}.
310 @xref{Redirections}, for a list of redirection operators.
313 @cindex process group
314 A collection of related processes each having the same process
317 @item process group ID
318 @cindex process group ID
319 A unique identifer that represents a @code{process group}
323 @cindex reserved word
324 A @code{word} that has a special meaning to the shell. Most reserved
325 words introduce shell flow control constructs, such as @code{for} and
329 @cindex return status
330 A synonym for @code{exit status}.
334 A mechanism by which a process may be notified by the kernel
335 of an event occurring in the system.
337 @item special builtin
338 @cindex special builtin
339 A shell builtin command that has been classified as special by the
340 @sc{posix} 1003.2 standard.
344 A sequence of characters considered a single unit by the shell. It is
345 either a @code{word} or an @code{operator}.
349 A @code{token} that is not an @code{operator}.
352 @node Basic Shell Features
353 @chapter Basic Shell Features
356 Bash is an acronym for @samp{Bourne-Again SHell}.
358 the traditional Unix shell originally written by Stephen Bourne.
359 All of the Bourne shell builtin commands are available in Bash,
360 and the rules for evaluation and quoting are taken from the @sc{posix}
361 1003.2 specification for the `standard' Unix shell.
363 This chapter briefly summarizes the shell's `building blocks':
364 commands, control structures, shell functions, shell @i{parameters},
366 @i{redirections}, which are a way to direct input and output from
367 and to named files, and how the shell executes commands.
370 * Shell Syntax:: What your input means to the shell.
371 * Shell Commands:: The types of commands you can use.
372 * Shell Functions:: Grouping commands by name.
373 * Shell Parameters:: Special shell variables.
374 * Shell Expansions:: How Bash expands variables and the various
375 expansions available.
376 * Redirections:: A way to control where input and output go.
377 * Executing Commands:: What happens when you run a command.
378 * Shell Scripts:: Executing files of shell commands.
382 @section Shell Syntax
384 * Shell Operation:: The basic operation of the shell.
386 * Quoting:: How to remove the special meaning from characters.
388 * Comments:: How to specify comments.
391 When the shell reads input, it proceeds through a
392 sequence of operations. If the input indicates the beginning of a
393 comment, the shell ignores the comment symbol (@samp{#}), and the rest
396 Otherwise, roughly speaking, the shell reads its input and
397 divides the input into words and operators, employing the quoting rules
398 to select which meanings to assign various words and characters.
400 The shell then parses these tokens into commands and other constructs,
401 removes the special meaning of certain words or characters, expands
402 others, redirects input and output as needed, executes the specified
403 command, waits for the command's exit status, and makes that exit status
404 available for further inspection or processing.
406 @node Shell Operation
407 @subsection Shell Operation
409 The following is a brief description of the shell's operation when it
410 reads and executes a command. Basically, the shell does the
415 Reads its input from a file (@pxref{Shell Scripts}), from a string
416 supplied as an argument to the @samp{-c} invocation option
417 (@pxref{Invoking Bash}), or from the user's terminal.
420 Breaks the input into words and operators, obeying the quoting rules
421 described in @ref{Quoting}. These tokens are separated by
422 @code{metacharacters}. Alias expansion is performed by this step
426 Parses the tokens into simple and compound commands
427 (@pxref{Shell Commands}).
430 Performs the various shell expansions (@pxref{Shell Expansions}), breaking
431 the expanded tokens into lists of filenames (@pxref{Filename Expansion})
432 and commands and arguments.
435 Performs any necessary redirections (@pxref{Redirections}) and removes
436 the redirection operators and their operands from the argument list.
439 Executes the command (@pxref{Executing Commands}).
442 Optionally waits for the command to complete and collects its exit
443 status (@pxref{Exit Status}).
451 * Escape Character:: How to remove the special meaning from a single
453 * Single Quotes:: How to inhibit all interpretation of a sequence
455 * Double Quotes:: How to suppress most of the interpretation of a
456 sequence of characters.
457 * ANSI-C Quoting:: How to expand ANSI-C sequences in quoted strings.
459 * Locale Translation:: How to translate strings into different languages.
462 Quoting is used to remove the special meaning of certain
463 characters or words to the shell. Quoting can be used to
464 disable special treatment for special characters, to prevent
465 reserved words from being recognized as such, and to prevent
468 Each of the shell metacharacters (@pxref{Definitions})
469 has special meaning to the shell and must be quoted if it is to
471 When the command history expansion facilities are being used, the
472 @var{history expansion} character, usually @samp{!}, must be quoted
473 to prevent history expansion. @xref{Bash History Facilities} for
474 more details concerning history expansion.
475 There are three quoting mechanisms: the
476 @var{escape character}, single quotes, and double quotes.
478 @node Escape Character
479 @subsubsection Escape Character
480 A non-quoted backslash @samp{\} is the Bash escape character.
481 It preserves the literal value of the next character that follows,
482 with the exception of @code{newline}. If a @code{\newline} pair
483 appears, and the backslash itself is not quoted, the @code{\newline}
484 is treated as a line continuation (that is, it is removed from
485 the input stream and effectively ignored).
488 @subsubsection Single Quotes
490 Enclosing characters in single quotes (@samp{'}) preserves the literal value
491 of each character within the quotes. A single quote may not occur
492 between single quotes, even when preceded by a backslash.
495 @subsubsection Double Quotes
497 Enclosing characters in double quotes (@samp{"}) preserves the literal value
498 of all characters within the quotes, with the exception of
499 @samp{$}, @samp{`}, and @samp{\}.
500 The characters @samp{$} and @samp{`}
501 retain their special meaning within double quotes (@pxref{Shell Expansions}).
502 The backslash retains its special meaning only when followed by one of
503 the following characters:
504 @samp{$}, @samp{`}, @samp{"}, @samp{\}, or @code{newline}.
505 Within double quotes, backslashes that are followed by one of these
506 characters are removed. Backslashes preceding characters without a
507 special meaning are left unmodified.
508 A double quote may be quoted within double quotes by preceding it with
511 The special parameters @samp{*} and @samp{@@} have special meaning
512 when in double quotes (@pxref{Shell Parameter Expansion}).
515 @subsubsection ANSI-C Quoting
516 @cindex quoting, ANSI
518 Words of the form @code{$'@var{string}'} are treated specially. The
519 word expands to @var{string}, with backslash-escaped characters replaced
520 as specifed by the ANSI C standard. Backslash escape sequences, if
521 present, are decoded as follows:
529 an escape character (not ANSI C)
545 the character whose @code{ASCII} code is the octal value @var{nnn}
546 (one to three digits)
548 the character whose @code{ASCII} code is the hexadecimal value @var{nnn}
549 (one to three digits)
553 The expanded result is single-quoted, as if the dollar sign had not
556 @node Locale Translation
557 @subsubsection Locale-Specific Translation
560 A double-quoted string preceded by a dollar sign (@samp{$}) will cause
561 the string to be translated according to the current locale.
562 If the current locale is @code{C} or @code{POSIX}, the dollar sign
564 If the string is translated and replaced, the replacement is
569 @cindex comments, shell
571 In a non-interactive shell, or an interactive shell in which the
572 @code{interactive_comments} option to the @code{shopt}
573 builtin is enabled (@pxref{Bash Builtins}),
574 a word beginning with @samp{#}
575 causes that word and all remaining characters on that line to
576 be ignored. An interactive shell without the @code{interactive_comments}
577 option enabled does not allow comments. The @code{interactive_comments}
578 option is on by default in interactive shells.
579 @xref{Interactive Shells}, for a description of what makes
583 @section Shell Commands
584 @cindex commands, shell
586 A simple shell command such as @code{echo a b c} consists of the command
587 itself followed by arguments, separated by spaces.
589 More complex shell commands are composed of simple commands arranged together
590 in a variety of ways: in a pipeline in which the output of one command
591 becomes the input of a second, in a loop or conditional construct, or in
595 * Simple Commands:: The most common type of command.
596 * Pipelines:: Connecting the input and output of several
598 * Lists:: How to execute commands sequentially.
599 * Looping Constructs:: Shell commands for iterative action.
600 * Conditional Constructs:: Shell commands for conditional execution.
601 * Command Grouping:: Ways to group commands.
604 @node Simple Commands
605 @subsection Simple Commands
606 @cindex commands, simple
608 A simple command is the kind of command encountered most often.
609 It's just a sequence of words separated by @code{blank}s, terminated
610 by one of the shell's control operators (@pxref{Definitions}). The
611 first word generally specifies a command to be executed, with the
612 rest of the words being that command's arguments.
614 The return status (@pxref{Exit Status}) of a simple command is
615 its exit status as provided
616 by the @sc{posix} 1003.1 @code{waitpid} function, or 128+@var{n} if
617 the command was terminated by signal @var{n}.
620 @subsection Pipelines
622 @cindex commands, pipelines
624 A @code{pipeline} is a sequence of simple commands separated by
629 @cindex command timing
630 The format for a pipeline is
632 [@code{time} [@code{-p}]] [@code{!}] @var{command1} [@code{|} @var{command2} @dots{}]
636 The output of each command in the pipeline is connected to the input of
637 the next command. That is, each command reads the previous command's
640 The reserved word @code{time} causes timing statistics
641 to be printed for the pipeline once it finishes.
642 The statistics currently consist of elapsed (wall-clock) time and
643 user and system time consumed by the command's execution.
644 The @samp{-p} option changes the output format to that specified
646 The @code{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 If the pipeline is not executed asynchronously (@pxref{Lists}), the
654 shell waits for all commands in the pipeline to complete.
656 Each command in a pipeline is executed in its own subshell
657 (@pxref{Command Execution Environment}). The exit
658 status of a pipeline is the exit status of the last command in the
659 pipeline. If the reserved word @samp{!} precedes the pipeline, the
660 exit status is the logical negation of the exit status of the last command.
663 @subsection Lists of Commands
664 @cindex commands, lists
666 A @code{list} is a sequence of one or more pipelines separated by one
667 of the operators @samp{;}, @samp{&}, @samp{&&}, or @samp{||},
668 and optionally terminated by one of @samp{;}, @samp{&}, or a
671 Of these list operators, @samp{&&} and @samp{||}
672 have equal precedence, followed by @samp{;} and @samp{&},
673 which have equal precedence.
675 If a command is terminated by the control operator @samp{&},
676 the shell executes the command asynchronously in a subshell.
677 This is known as executing the command in the @var{background}.
678 The shell does not wait for the command to finish, and the return
680 When job control is not active (@pxref{Job Control}),
681 the standard input for asynchronous commands, in the absence of any
682 explicit redirections, is redirected from @code{/dev/null}.
684 Commands separated by a @samp{;} are executed sequentially; the shell
685 waits for each command to terminate in turn. The return status is the
686 exit status of the last command executed.
688 The control operators @samp{&&} and @samp{||}
689 denote @sc{and} lists and @sc{or} lists, respectively.
690 An @sc{and} list has the form
692 @var{command1} && @var{command2}
696 @var{command2} is executed if, and only if, @var{command1}
697 returns an exit status of zero.
699 An @sc{or} list has the form
701 @var{command1} || @var{command2}
705 @var{command2} is executed if, and only if, @var{command1}
706 returns a non-zero exit status.
709 @sc{and} and @sc{or} lists is the exit status of the last command
710 executed in the list.
712 @node Looping Constructs
713 @subsection Looping Constructs
714 @cindex commands, looping
716 Bash supports the following looping constructs.
718 Note that wherever a @samp{;} appears in the description of a
719 command's syntax, it may be replaced with one or more newlines.
726 The syntax of the @code{until} command is:
728 until @var{test-commands}; do @var{consequent-commands}; done
730 Execute @var{consequent-commands} as long as
731 @var{test-commands} has an exit status which is not zero.
732 The return status is the exit status of the last command executed
733 in @var{consequent-commands}, or zero if none was executed.
737 The syntax of the @code{while} command is:
739 while @var{test-commands}; do @var{consequent-commands}; done
742 Execute @var{consequent-commands} as long as
743 @var{test-commands} has an exit status of zero.
744 The return status is the exit status of the last command executed
745 in @var{consequent-commands}, or zero if none was executed.
749 The syntax of the @code{for} command is:
752 for @var{name} [in @var{words} @dots{}]; do @var{commands}; done
754 Expand @var{words}, and execute @var{commands} once for each member
755 in the resultant list, with @var{name} bound to the current member.
756 If @samp{in @var{words}} is not present, the @code{for} command
757 executes the @var{commands} once for each positional parameter that is
758 set, as if @samp{in "$@@"} had been specified
759 (@pxref{Special Parameters}).
760 The return status is the exit status of the last command that executes.
761 If there are no items in the expansion of @var{words}, no commands are
762 executed, and the return status is zero.
764 An alternate form of the @code{for} command is also supported:
767 for (( @var{expr1} ; @var{expr2} ; @var{expr3} )) ; do @var{commands} ; done
769 First, the arithmetic expression @var{expr1} is evaluated according
770 to the rules described below (@pxref{Shell Arithmetic}).
771 The arithmetic expression @var{expr2} is then evaluated repeatedly
772 until it evaluates to zero.
773 Each time @var{expr2} evaluates to a non-zero value, @var{commands} are
774 executed and the arithmetic expression @var{expr3} is evaluated.
775 If any expression is omitted, it behaves as if it evaluates to 1.
776 The return value is the exit status of the last command in @var{list}
777 that is executed, or false if any of the expressions is invalid.
781 The @code{break} and @code{continue} builtins (@pxref{Bourne Shell Builtins})
782 may be used to control loop execution.
784 @node Conditional Constructs
785 @subsection Conditional Constructs
786 @cindex commands, conditional
795 The syntax of the @code{if} command is:
798 if @var{test-commands}; then
799 @var{consequent-commands};
800 [elif @var{more-test-commands}; then
801 @var{more-consequents};]
802 [else @var{alternate-consequents};]
806 The @var{test-commands} list is executed, and if its return status is zero,
807 the @var{consequent-commands} list is executed.
808 If @var{test-commands} returns a non-zero status, each @code{elif} list
809 is executed in turn, and if its exit status is zero,
810 the corresponding @var{more-consequents} is executed and the
812 If @samp{else @var{alternate-consequents}} is present, and
813 the final command in the final @code{if} or @code{elif} clause
814 has a non-zero exit status, then @var{alternate-consequents} is executed.
815 The return status is the exit status of the last command executed, or
816 zero if no condition tested true.
822 The syntax of the @code{case} command is:
825 @code{case @var{word} in [ [(] @var{pattern} [| @var{pattern}]@dots{}) @var{command-list} ;;]@dots{} esac}
828 @code{case} will selectively execute the @var{command-list} corresponding to
829 the first @var{pattern} that matches @var{word}.
830 The @samp{|} is used to separate multiple patterns, and the @samp{)}
831 operator terminates a pattern list.
832 A list of patterns and an associated command-list is known
833 as a @var{clause}. Each clause must be terminated with @samp{;;}.
834 The @var{word} undergoes tilde expansion, parameter expansion, command
835 substitution, arithmetic expansion, and quote removal before matching is
836 attempted. Each @var{pattern} undergoes tilde expansion, parameter
837 expansion, command substitution, and arithmetic expansion.
839 There may be an arbitrary number of @code{case} clauses, each terminated
840 by a @samp{;;}. The first pattern that matches determines the
841 command-list that is executed.
843 Here is an example using @code{case} in a script that could be used to
844 describe one interesting feature of an animal:
847 echo -n "Enter the name of an animal: "
849 echo -n "The $ANIMAL has "
851 horse | dog | cat) echo -n "four";;
852 man | kangaroo ) echo -n "two";;
853 *) echo -n "an unknown number of";;
859 The return status is zero if no @var{pattern} is matched. Otherwise, the
860 return status is the exit status of the @var{command-list} executed.
865 The @code{select} construct allows the easy generation of menus.
866 It has almost the same syntax as the @code{for} command:
869 select @var{name} [in @var{words} @dots{}]; do @var{commands}; done
872 The list of words following @code{in} is expanded, generating a list
873 of items. The set of expanded words is printed on the standard
874 error output stream, each preceded by a number. If the
875 @samp{in @var{words}} is omitted, the positional parameters are printed,
876 as if @samp{in "$@@"} had been specifed.
877 The @code{PS3} prompt is then displayed and a line is read from the
879 If the line consists of a number corresponding to one of the displayed
880 words, then the value of @var{name} is set to that word.
881 If the line is empty, the words and prompt are displayed again.
882 If @code{EOF} is read, the @code{select} command completes.
883 Any other value read causes @var{name} to be set to null.
884 The line read is saved in the variable @code{REPLY}.
886 The @var{commands} are executed after each selection until a
887 @code{break} or @code{return} command is executed, at which
888 point the @code{select} command completes.
890 Here is an example that allows the user to pick a filename from the
891 current directory, and displays the name and index of the file
897 echo you picked $fname \($REPLY\)
904 (( @var{expression} ))
907 The arithmetic @var{expression} is evaluated according to the rules
908 described below (@pxref{Shell Arithmetic}).
909 If the value of the expression is non-zero, the return status is 0;
910 otherwise the return status is 1. This is exactly equivalent to
912 let "@var{expression}"
915 @xref{Bash Builtins}, for a full description of the @code{let} builtin.
921 [[ @var{expression} ]]
924 Return a status of 0 or 1 depending on the evaluation of
925 the conditional expression @var{expression}.
926 Expressions are composed of the primaries described below in
927 @ref{Bash Conditional Expressions}.
928 Word splitting and filename expansion are not performed on the words
929 between the @samp{[[} and @samp{]]}; tilde expansion, parameter and
930 variable expansion, arithmetic expansion, command substitution, process
931 substitution, and quote removal are performed.
933 When the @samp{==} and @samp{!=} operators are used, the string to the
934 right of the operator is considered a pattern and matched according
935 to the rules described below in @ref{Pattern Matching}.
936 The return value is 0 if the string matches or does not match
937 the pattern, respectively, and 1 otherwise.
938 Any part of the pattern may be quoted to force it to be matched as a
941 Expressions may be combined using the following operators, listed
942 in decreasing order of precedence:
945 @item ( @var{expression} )
946 Returns the value of @var{expression}.
947 This may be used to override the normal precedence of operators.
949 @item ! @var{expression}
950 True if @var{expression} is false.
952 @item @var{expression1} && @var{expression2}
953 True if both @var{expression1} and @var{expression2} are true.
955 @item @var{expression1} || @var{expression2}
956 True if either @var{expression1} or @var{expression2} is true.
959 The @code{&&} and @code{||} commands do not execute @var{expression2} if the
960 value of @var{expression1} is sufficient to determine the return
961 value of the entire conditional expression.
965 @node Command Grouping
966 @subsection Grouping Commands
967 @cindex commands, grouping
969 Bash provides two ways to group a list of commands to be executed
970 as a unit. When commands are grouped, redirections may be applied
971 to the entire command list. For example, the output of all the
972 commands in the list may be redirected to a single stream.
980 Placing a list of commands between parentheses causes a subshell
981 to be created, and each of the commands in @var{list} to be executed
982 in that subshell. Since the @var{list} is executed in a subshell,
983 variable assignments do not remain in effect after the subshell completes.
992 Placing a list of commands between curly braces causes the list to
993 be executed in the current shell context. No subshell is created.
994 The semicolon (or newline) following @var{list} is required.
997 In addition to the creation of a subshell, there is a subtle difference
998 between these two constructs due to historical reasons. The braces
999 are @code{reserved words}, so they must be separated from the @var{list}
1000 by @code{blank}s. The parentheses are @code{operators}, and are
1001 recognized as separate tokens by the shell even if they are not separated
1002 from the @var{list} by whitespace.
1004 The exit status of both of these constructs is the exit status of
1007 @node Shell Functions
1008 @section Shell Functions
1009 @cindex shell function
1010 @cindex functions, shell
1012 Shell functions are a way to group commands for later execution
1013 using a single name for the group. They are executed just like
1014 a "regular" command.
1015 When the name of a shell function is used as a simple command name,
1016 the list of commands associated with that function name is executed.
1017 Shell functions are executed in the current
1018 shell context; no new process is created to interpret them.
1020 Functions are declared using this syntax:
1023 [ @code{function} ] @var{name} () @{ @var{command-list}; @}
1026 This defines a shell function named @var{name}. The reserved
1027 word @code{function} is optional.
1028 If the @code{function} reserved
1029 word is supplied, the parentheses are optional.
1030 The @var{body} of the function is the @var{command-list} between @{ and @}.
1031 This list is executed whenever @var{name} is specified as the
1032 name of a command. The exit status of a function is
1033 the exit status of the last command executed in the body.
1035 Note that for historical reasons, the curly braces that surround
1036 the body of the function must be separated from the body by
1037 @code{blank}s or newlines.
1038 This is because the braces are reserved words and are only recognized
1039 as such when they are separated by whitespace.
1040 Also, the @var{command-list} must be terminated with a semicolon
1043 When a function is executed, the arguments to the
1044 function become the positional parameters
1045 during its execution (@pxref{Positional Parameters}).
1046 The special parameter @samp{#} that expands to the number of
1047 positional parameters is updated to reflect the change.
1048 Positional parameter @code{0} is unchanged.
1049 The @code{FUNCNAME} variable is set to the name of the function
1050 while the function is executing.
1052 If the builtin command @code{return}
1053 is executed in a function, the function completes and
1054 execution resumes with the next command after the function
1055 call. When a function completes, the values of the
1056 positional parameters and the special parameter @samp{#}
1057 are restored to the values they had prior to the function's
1058 execution. If a numeric argument is given to @code{return},
1059 that is the function's return status; otherwise the functions's
1060 return status is the exit status of the last command executed
1061 before the @code{return}.
1063 Variables local to the function may be declared with the
1064 @code{local} builtin. These variables are visible only to
1065 the function and the commands it invokes.
1067 Functions may be recursive. No limit is placed on the number of
1070 @node Shell Parameters
1071 @section Shell Parameters
1073 @cindex variable, shell
1074 @cindex shell variable
1077 * Positional Parameters:: The shell's command-line arguments.
1078 * Special Parameters:: Parameters with special meanings.
1081 A @var{parameter} is an entity that stores values.
1082 It can be a @code{name}, a number, or one of the special characters
1084 For the shell's purposes, a @var{variable} is a parameter denoted by a
1087 A parameter is set if it has been assigned a value. The null string is
1088 a valid value. Once a variable is set, it may be unset only by using
1089 the @code{unset} builtin command.
1091 A variable may be assigned to by a statement of the form
1093 @var{name}=[@var{value}]
1097 is not given, the variable is assigned the null string. All
1098 @var{value}s undergo tilde expansion, parameter and variable expansion,
1099 command substitution, arithmetic expansion, and quote
1100 removal (detailed below). If the variable has its @code{integer}
1101 attribute set (see the description of the @code{declare} builtin in
1102 @ref{Bash Builtins}), then @var{value}
1103 is subject to arithmetic expansion even if the @code{$((@dots{}))}
1104 expansion is not used (@pxref{Arithmetic Expansion}).
1105 Word splitting is not performed, with the exception
1106 of @code{"$@@"} as explained below.
1107 Filename expansion is not performed.
1109 @node Positional Parameters
1110 @subsection Positional Parameters
1111 @cindex parameters, positional
1113 A @var{positional parameter} is a parameter denoted by one or more
1114 digits, other than the single digit @code{0}. Positional parameters are
1115 assigned from the shell's arguments when it is invoked,
1116 and may be reassigned using the @code{set} builtin command.
1117 Positional parameter @code{N} may be referenced as @code{$@{N@}}, or
1118 as @code{$N} when @code{N} consists of a single digit.
1119 Positional parameters may not be assigned to with assignment statements.
1120 The @code{set} and @code{shift} builtins are used to set and
1121 unset them (@pxref{Shell Builtin Commands}).
1122 The positional parameters are
1123 temporarily replaced when a shell function is executed
1124 (@pxref{Shell Functions}).
1126 When a positional parameter consisting of more than a single
1127 digit is expanded, it must be enclosed in braces.
1129 @node Special Parameters
1130 @subsection Special Parameters
1131 @cindex parameters, special
1133 The shell treats several parameters specially. These parameters may
1134 only be referenced; assignment to them is not allowed.
1139 Expands to the positional parameters, starting from one. When the
1140 expansion occurs within double quotes, it expands to a single word
1141 with the value of each parameter separated by the first character
1143 special variable. That is, @code{"$*"} is equivalent
1144 to @code{"$1@var{c}$2@var{c}@dots{}"}, where @var{c}
1145 is the first character of the value of the @code{IFS}
1147 If @code{IFS} is unset, the parameters are separated by spaces.
1148 If @code{IFS} is null, the parameters are joined without intervening
1153 Expands to the positional parameters, starting from one. When the
1154 expansion occurs within double quotes, each parameter expands to a
1155 separate word. That is, @code{"$@@"} is equivalent to
1156 @code{"$1" "$2" @dots{}}.
1157 When there are no positional parameters, @code{"$@@"} and
1159 expand to nothing (i.e., they are removed).
1162 Expands to the number of positional parameters in decimal.
1165 Expands to the exit status of the most recently executed foreground
1169 (A hyphen.) Expands to the current option flags as specified upon
1170 invocation, by the @code{set}
1171 builtin command, or those set by the shell itself
1172 (such as the @samp{-i} option).
1175 Expands to the process @sc{id} of the shell. In a @code{()} subshell, it
1176 expands to the process @sc{id} of the invoking shell, not the subshell.
1179 Expands to the process @sc{id} of the most recently executed background
1180 (asynchronous) command.
1183 Expands to the name of the shell or shell script. This is set at
1184 shell initialization. If Bash is invoked with a file of commands
1185 (@pxref{Shell Scripts}), @code{$0} is set to the name of that file.
1186 If Bash is started with the @samp{-c} option (@pxref{Invoking Bash}),
1187 then @code{$0} is set to the first argument after the string to be
1188 executed, if one is present. Otherwise, it is set
1189 to the filename used to invoke Bash, as given by argument zero.
1193 At shell startup, set to the absolute filename of the shell or shell
1194 script being executed as passed in the argument list.
1195 Subsequently, expands to the last argument to the previous command,
1197 Also set to the full pathname of each command executed and placed in
1198 the environment exported to that command.
1199 When checking mail, this parameter holds the name of the mail file.
1202 @node Shell Expansions
1203 @section Shell Expansions
1206 Expansion is performed on the command line after it has been split into
1207 @code{token}s. There are seven kinds of expansion performed:
1209 @item brace expansion
1210 @item tilde expansion
1211 @item parameter and variable expansion
1212 @item command substitution
1213 @item arithmetic expansion
1214 @item word splitting
1215 @item filename expansion
1219 * Brace Expansion:: Expansion of expressions within braces.
1220 * Tilde Expansion:: Expansion of the ~ character.
1221 * Shell Parameter Expansion:: How Bash expands variables to their values.
1222 * Command Substitution:: Using the output of a command as an argument.
1223 * Arithmetic Expansion:: How to use arithmetic in shell expansions.
1224 * Process Substitution:: A way to write and read to and from a
1226 * Word Splitting:: How the results of expansion are split into separate
1228 * Filename Expansion:: A shorthand for specifying filenames matching patterns.
1229 * Quote Removal:: How and when quote characters are removed from
1233 The order of expansions is: brace expansion, tilde expansion,
1234 parameter, variable, and arithmetic expansion and
1235 command substitution
1236 (done in a left-to-right fashion), word splitting, and filename
1239 On systems that can support it, there is an additional expansion
1240 available: @var{process substitution}. This is performed at the
1241 same time as parameter, variable, and arithmetic expansion and
1242 command substitution.
1244 Only brace expansion, word splitting, and filename expansion
1245 can change the number of words of the expansion; other expansions
1246 expand a single word to a single word.
1247 The only exceptions to this are the expansions of
1248 @code{"$@@"} (@pxref{Special Parameters}) and @code{"$@{@var{name}[@@]@}"}
1251 After all expansions, @code{quote removal} (@pxref{Quote Removal})
1254 @node Brace Expansion
1255 @subsection Brace Expansion
1256 @cindex brace expansion
1257 @cindex expansion, brace
1259 Brace expansion is a mechanism by which arbitrary strings may be generated.
1260 This mechanism is similar to
1261 @var{filename expansion} (@pxref{Filename Expansion}),
1262 but the file names generated need not exist.
1263 Patterns to be brace expanded take the form of an optional @var{preamble},
1264 followed by a series of comma-separated strings between a pair of braces,
1265 followed by an optional @var{postscript}.
1266 The preamble is prefixed to each string contained within the braces, and
1267 the postscript is then appended to each resulting string, expanding left
1270 Brace expansions may be nested.
1271 The results of each expanded string are not sorted; left to right order
1275 bash$ echo a@{d,c,b@}e
1279 Brace expansion is performed before any other expansions,
1280 and any characters special to other expansions are preserved
1281 in the result. It is strictly textual. Bash
1282 does not apply any syntactic interpretation to the context of the
1283 expansion or the text between the braces.
1284 To avoid conflicts with parameter expansion, the string @samp{$@{}
1285 is not considered eligible for brace expansion.
1287 A correctly-formed brace expansion must contain unquoted opening
1288 and closing braces, and at least one unquoted comma.
1289 Any incorrectly formed brace expansion is left unchanged.
1291 This construct is typically used as shorthand when the common
1292 prefix of the strings to be generated is longer than in the
1295 mkdir /usr/local/src/bash/@{old,new,dist,bugs@}
1299 chown root /usr/@{ucb/@{ex,edit@},lib/@{ex?.?*,how_ex@}@}
1302 @node Tilde Expansion
1303 @subsection Tilde Expansion
1304 @cindex tilde expansion
1305 @cindex expansion, tilde
1307 If a word begins with an unquoted tilde character (@samp{~}), all of the
1308 characters up to the first unquoted slash (or all characters,
1309 if there is no unquoted slash) are considered a @var{tilde-prefix}.
1310 If none of the characters in the tilde-prefix are quoted, the
1311 characters in the tilde-prefix following the tilde are treated as a
1312 possible @var{login name}.
1313 If this login name is the null string, the tilde is replaced with the
1314 value of the @code{HOME} shell variable.
1315 If @code{HOME} is unset, the home directory of the user executing the
1316 shell is substituted instead.
1317 Otherwise, the tilde-prefix is replaced with the home directory
1318 associated with the specified login name.
1320 If the tilde-prefix is @samp{~+}, the value of
1321 the shell variable @code{PWD} replaces the tilde-prefix.
1322 If the tilde-prefix is @samp{~-}, the value of the shell variable
1323 @code{OLDPWD}, if it is set, is substituted.
1325 If the characters following the tilde in the tilde-prefix consist of a
1326 number @var{N}, optionally prefixed by a @samp{+} or a @samp{-},
1327 the tilde-prefix is replaced with the
1328 corresponding element from the directory stack, as it would be displayed
1329 by the @code{dirs} builtin invoked with the characters following tilde
1330 in the tilde-prefix as an argument (@pxref{The Directory Stack}).
1331 If the tilde-prefix, sans the tilde, consists of a number without a
1332 leading @samp{+} or @samp{-}, @samp{+} is assumed.
1334 If the login name is invalid, or the tilde expansion fails, the word is
1337 Each variable assignment is checked for unquoted tilde-prefixes immediately
1338 following a @samp{:} or @samp{=}.
1339 In these cases, tilde expansion is also performed.
1340 Consequently, one may use file names with tildes in assignments to
1341 @code{PATH}, @code{MAILPATH}, and @code{CDPATH},
1342 and the shell assigns the expanded value.
1344 The following table shows how Bash treats unquoted tilde-prefixes:
1348 The value of @code{$HOME}
1353 The subdirectory @code{foo} of the home directory of the user
1360 @file{$@{OLDPWD-'~-'@}/foo}
1363 The string that would be displayed by @samp{dirs +@var{N}}
1366 The string that would be displayed by @samp{dirs +@var{N}}
1369 The string that would be displayed by @samp{dirs -@var{N}}
1373 @node Shell Parameter Expansion
1374 @subsection Shell Parameter Expansion
1375 @cindex parameter expansion
1376 @cindex expansion, parameter
1378 The @samp{$} character introduces parameter expansion,
1379 command substitution, or arithmetic expansion. The parameter name
1380 or symbol to be expanded may be enclosed in braces, which
1381 are optional but serve to protect the variable to be expanded from
1382 characters immediately following it which could be
1383 interpreted as part of the name.
1385 When braces are used, the matching ending brace is the first @samp{@}}
1386 not escaped by a backslash or within a quoted string, and not within an
1387 embedded arithmetic expansion, command substitution, or parameter
1390 The basic form of parameter expansion is $@{@var{parameter}@}.
1391 The value of @var{parameter} is substituted. The braces are required
1392 when @var{parameter}
1393 is a positional parameter with more than one digit,
1394 or when @var{parameter}
1395 is followed by a character that is not to be
1396 interpreted as part of its name.
1398 If the first character of @var{parameter} is an exclamation point,
1399 a level of variable indirection is introduced.
1400 Bash uses the value of the variable formed from the rest of
1401 @var{parameter} as the name of the variable; this variable is then
1402 expanded and that value is used in the rest of the substitution, rather
1403 than the value of @var{parameter} itself.
1404 This is known as @code{indirect expansion}.
1405 The exception to this is the expansion of $@{!@var{prefix*@}}
1408 In each of the cases below, @var{word} is subject to tilde expansion,
1409 parameter expansion, command substitution, and arithmetic expansion.
1411 When not performing substring expansion, Bash tests for a parameter
1412 that is unset or null; omitting the colon results in a test only for a
1413 parameter that is unset. Put another way, if the colon is included,
1414 the operator tests for both existence and that the value is not null;
1415 if the colon is omitted, the operator tests only for existence.
1419 @item $@{@var{parameter}:@minus{}@var{word}@}
1420 If @var{parameter} is unset or null, the expansion of
1421 @var{word} is substituted. Otherwise, the value of
1422 @var{parameter} is substituted.
1424 @item $@{@var{parameter}:=@var{word}@}
1426 is unset or null, the expansion of @var{word}
1427 is assigned to @var{parameter}.
1428 The value of @var{parameter}
1429 is then substituted. Positional parameters and special parameters may
1430 not be assigned to in this way.
1432 @item $@{@var{parameter}:?@var{word}@}
1434 is null or unset, the expansion of @var{word} (or a message
1435 to that effect if @var{word}
1436 is not present) is written to the standard error and the shell, if it
1437 is not interactive, exits. Otherwise, the value of @var{parameter} is
1440 @item $@{@var{parameter}:+@var{word}@}
1442 is null or unset, nothing is substituted, otherwise the expansion of
1443 @var{word} is substituted.
1445 @item $@{@var{parameter}:@var{offset}@}
1446 @itemx $@{@var{parameter}:@var{offset}:@var{length}@}
1447 Expands to up to @var{length} characters of @var{parameter}
1448 starting at the character specified by @var{offset}.
1449 If @var{length} is omitted, expands to the substring of
1450 @var{parameter} starting at the character specified by @var{offset}.
1451 @var{length} and @var{offset} are arithmetic expressions
1452 (@pxref{Shell Arithmetic}).
1453 This is referred to as Substring Expansion.
1455 @var{length} must evaluate to a number greater than or equal to zero.
1456 If @var{offset} evaluates to a number less than zero, the value
1457 is used as an offset from the end of the value of @var{parameter}.
1458 If @var{parameter} is @samp{@@}, the result is @var{length} positional
1459 parameters beginning at @var{offset}.
1460 If @var{parameter} is an array name indexed by @samp{@@} or @samp{*},
1461 the result is the @var{length}
1462 members of the array beginning with @code{$@{@var{parameter}[@var{offset}]@}}.
1463 Substring indexing is zero-based unless the positional parameters
1464 are used, in which case the indexing starts at 1.
1466 @item $@{!@var{prefix}*@}
1467 Expands to the names of variables whose names begin with @var{prefix},
1468 separated by the first character of the @code{IFS} special variable.
1470 @item $@{#@var{parameter}@}
1471 The length in characters of the expanded value of @var{parameter} is
1473 If @var{parameter} is @samp{*} or @samp{@@}, the value substituted
1474 is the number of positional parameters.
1475 If @var{parameter} is an array name subscripted by @samp{*} or @samp{@@},
1476 the value substituted is the number of elements in the array.
1478 @item $@{@var{parameter}#@var{word}@}
1479 @itemx $@{@var{parameter}##@var{word}@}
1481 is expanded to produce a pattern just as in filename
1482 expansion (@pxref{Filename Expansion}). If the pattern matches
1483 the beginning of the expanded value of @var{parameter},
1484 then the result of the expansion is the expanded value of @var{parameter}
1485 with the shortest matching pattern (the @samp{#} case) or the
1486 longest matching pattern (the @samp{##} case) deleted.
1487 If @var{parameter} is @samp{@@} or @samp{*},
1488 the pattern removal operation is applied to each positional
1489 parameter in turn, and the expansion is the resultant list.
1490 If @var{parameter} is an array variable subscripted with
1491 @samp{@@} or @samp{*},
1492 the pattern removal operation is applied to each member of the
1493 array in turn, and the expansion is the resultant list.
1495 @item $@{@var{parameter}%@var{word}@}
1496 @itemx $@{@var{parameter}%%@var{word}@}
1497 The @var{word} is expanded to produce a pattern just as in
1499 If the pattern matches a trailing portion of the expanded value of
1500 @var{parameter}, then the result of the expansion is the value of
1501 @var{parameter} with the shortest matching pattern (the @samp{%} case)
1502 or the longest matching pattern (the @samp{%%} case) deleted.
1503 If @var{parameter} is @samp{@@} or @samp{*},
1504 the pattern removal operation is applied to each positional
1505 parameter in turn, and the expansion is the resultant list.
1507 is an array variable subscripted with @samp{@@} or @samp{*},
1508 the pattern removal operation is applied to each member of the
1509 array in turn, and the expansion is the resultant list.
1511 @item $@{@var{parameter}/@var{pattern}/@var{string}@}
1512 @itemx $@{@var{parameter}//@var{pattern}/@var{string}@}
1514 The @var{pattern} is expanded to produce a pattern just as in
1516 @var{Parameter} is expanded and the longest match of @var{pattern}
1517 against its value is replaced with @var{string}.
1518 In the first form, only the first match is replaced.
1519 The second form causes all matches of @var{pattern} to be
1520 replaced with @var{string}.
1521 If @var{pattern} begins with @samp{#}, it must match at the beginning
1522 of the expanded value of @var{parameter}.
1523 If @var{pattern} begins with @samp{%}, it must match at the end
1524 of the expanded value of @var{parameter}.
1525 If @var{string} is null, matches of @var{pattern} are deleted
1526 and the @code{/} following @var{pattern} may be omitted.
1527 If @var{parameter} is @samp{@@} or @samp{*},
1528 the substitution operation is applied to each positional
1529 parameter in turn, and the expansion is the resultant list.
1531 is an array variable subscripted with @samp{@@} or @samp{*},
1532 the substitution operation is applied to each member of the
1533 array in turn, and the expansion is the resultant list.
1537 @node Command Substitution
1538 @subsection Command Substitution
1539 @cindex command substitution
1541 Command substitution allows the output of a command to replace
1543 Command substitution occurs when a command is enclosed as follows:
1554 Bash performs the expansion by executing @var{command} and
1555 replacing the command substitution with the standard output of the
1556 command, with any trailing newlines deleted.
1557 Embedded newlines are not deleted, but they may be removed during
1559 The command substitution @code{$(cat @var{file})} can be
1560 replaced by the equivalent but faster @code{$(< @var{file})}.
1562 When the old-style backquote form of substitution is used,
1563 backslash retains its literal meaning except when followed by
1564 @samp{$}, @samp{`}, or @samp{\}.
1565 The first backquote not preceded by a backslash terminates the
1566 command substitution.
1567 When using the @code{$(@var{command})} form, all characters between
1568 the parentheses make up the command; none are treated specially.
1570 Command substitutions may be nested. To nest when using the backquoted
1571 form, escape the inner backquotes with backslashes.
1573 If the substitution appears within double quotes, word splitting and
1574 filename expansion are not performed on the results.
1576 @node Arithmetic Expansion
1577 @subsection Arithmetic Expansion
1578 @cindex expansion, arithmetic
1579 @cindex arithmetic expansion
1581 Arithmetic expansion allows the evaluation of an arithmetic expression
1582 and the substitution of the result. The format for arithmetic expansion is:
1585 $(( @var{expression} ))
1588 The expression is treated as if it were within double quotes, but
1589 a double quote inside the parentheses is not treated specially.
1590 All tokens in the expression undergo parameter expansion, command
1591 substitution, and quote removal.
1592 Arithmetic substitutions may be nested.
1594 The evaluation is performed according to the rules listed below
1595 (@pxref{Shell Arithmetic}).
1596 If the expression is invalid, Bash prints a message indicating
1597 failure to the standard error and no substitution occurs.
1599 @node Process Substitution
1600 @subsection Process Substitution
1601 @cindex process substitution
1603 Process substitution is supported on systems that support named
1604 pipes (@sc{fifo}s) or the @file{/dev/fd} method of naming open files.
1605 It takes the form of
1615 The process @var{list} is run with its input or output connected to a
1616 @sc{fifo} or some file in @file{/dev/fd}. The name of this file is
1617 passed as an argument to the current command as the result of the
1618 expansion. If the @code{>(@var{list})} form is used, writing to
1619 the file will provide input for @var{list}. If the
1620 @code{<(@var{list})} form is used, the file passed as an
1621 argument should be read to obtain the output of @var{list}.
1622 Note that no space may appear between the @code{<} or @code{>}
1623 and the left parenthesis, otherwise the construct would be interpreted
1626 When available, process substitution is performed simultaneously with
1627 parameter and variable expansion, command substitution, and arithmetic
1630 @node Word Splitting
1631 @subsection Word Splitting
1632 @cindex word splitting
1634 The shell scans the results of parameter expansion, command substitution,
1635 and arithmetic expansion that did not occur within double quotes for
1638 The shell treats each character of @code{$IFS}
1639 as a delimiter, and splits the results of the other
1640 expansions into words on these characters. If
1641 @code{IFS} is unset, or its value is exactly @code{<space><tab><newline>},
1642 the default, then any sequence of @code{IFS}
1643 characters serves to delimit words. If @code{IFS}
1644 has a value other than the default, then sequences of
1645 the whitespace characters @code{space} and @code{tab}
1646 are ignored at the beginning and end of the
1647 word, as long as the whitespace character is in the
1648 value of @code{IFS} (an @code{IFS} whitespace character).
1649 Any character in @code{IFS} that is not @code{IFS}
1650 whitespace, along with any adjacent @code{IFS}
1651 whitespace characters, delimits a field. A sequence of @code{IFS}
1652 whitespace characters is also treated as a delimiter.
1653 If the value of @code{IFS} is null, no word splitting occurs.
1655 Explicit null arguments (@code{""} or @code{''}) are retained.
1656 Unquoted implicit null arguments, resulting from the expansion of
1657 parameters that have no values, are removed.
1658 If a parameter with no value is expanded within double quotes, a
1659 null argument results and is retained.
1661 Note that if no expansion occurs, no splitting
1664 @node Filename Expansion
1665 @subsection Filename Expansion
1667 * Pattern Matching:: How the shell matches patterns.
1669 @cindex expansion, filename
1670 @cindex expansion, pathname
1671 @cindex filename expansion
1672 @cindex pathname expansion
1674 After word splitting, unless the @samp{-f} option has been set
1675 (@pxref{The Set Builtin}), Bash scans each word for the characters
1676 @samp{*}, @samp{?}, and @samp{[}.
1677 If one of these characters appears, then the word is
1678 regarded as a @var{pattern},
1679 and replaced with an alphabetically sorted list of
1680 file names matching the pattern. If no matching file names are found,
1681 and the shell option @code{nullglob} is disabled, the word is left
1683 If the @code{nullglob} option is set, and no matches are found, the word
1685 If the shell option @code{nocaseglob} is enabled, the match is performed
1686 without regard to the case of alphabetic characters.
1688 When a pattern is used for filename generation, the character @samp{.}
1689 at the start of a filename or immediately following a slash
1690 must be matched explicitly, unless the shell option @code{dotglob} is set.
1691 When matching a file name, the slash character must always be
1693 In other cases, the @samp{.} character is not treated specially.
1695 See the description of @code{shopt} in @ref{Bash Builtins},
1696 for a description of the @code{nocaseglob}, @code{nullglob},
1697 and @code{dotglob} options.
1699 The @code{GLOBIGNORE}
1700 shell variable may be used to restrict the set of filenames matching a
1701 pattern. If @code{GLOBIGNORE}
1702 is set, each matching filename that also matches one of the patterns in
1703 @code{GLOBIGNORE} is removed from the list of matches. The filenames
1704 @file{.} and @file{..}
1705 are always ignored, even when @code{GLOBIGNORE}
1706 is set. However, setting @code{GLOBIGNORE} has the effect of
1707 enabling the @code{dotglob}
1708 shell option, so all other filenames beginning with a
1709 @samp{.} will match.
1710 To get the old behavior of ignoring filenames beginning with a
1711 @samp{.}, make @samp{.*} one of the patterns in @code{GLOBIGNORE}.
1712 The @code{dotglob} option is disabled when @code{GLOBIGNORE}
1715 @node Pattern Matching
1716 @subsubsection Pattern Matching
1717 @cindex pattern matching
1718 @cindex matching, pattern
1720 Any character that appears in a pattern, other than the special pattern
1721 characters described below, matches itself. The @sc{nul} character may not
1722 occur in a pattern. The special pattern characters must be quoted if
1723 they are to be matched literally.
1725 The special pattern characters have the following meanings:
1728 Matches any string, including the null string.
1730 Matches any single character.
1732 Matches any one of the enclosed characters. A pair of characters
1733 separated by a minus sign denotes a @var{range};
1734 any character lexically between those two characters, inclusive,
1735 is matched. If the first character following the
1736 @samp{[} is a @samp{!} or a @samp{^}
1737 then any character not enclosed is matched. A @samp{@minus{}}
1738 may be matched by including it as the first or last character
1739 in the set. A @samp{]} may be matched by including it as the first
1740 character in the set.
1742 Within @samp{[} and @samp{]}, @var{character classes} can be specified
1744 @code{[:}@var{class}@code{:]}, where @var{class} is one of the
1745 following classes defined in the @sc{posix} 1003.2 standard:
1747 alnum alpha ascii blank cntrl digit graph lower
1748 print punct space upper xdigit
1751 A character class matches any character belonging to that class.
1753 Within @samp{[} and @samp{]}, an @var{equivalence class} can be
1754 specified using the syntax @code{[=}@var{c}@code{=]}, which
1755 matches all characters with the same collation weight (as defined
1756 by the current locale) as the character @var{c}.
1758 Within @samp{[} and @samp{]}, the syntax @code{[.}@var{symbol}@code{.]}
1759 matches the collating symbol @var{symbol}.
1762 If the @code{extglob} shell option is enabled using the @code{shopt}
1763 builtin, several extended pattern matching operators are recognized.
1764 In the following description, a @var{pattern-list} is a list of one
1765 or more patterns separated by a @samp{|}.
1766 Composite patterns may be formed using one or more of the following
1770 @item ?(@var{pattern-list})
1771 Matches zero or one occurrence of the given patterns.
1773 @item *(@var{pattern-list})
1774 Matches zero or more occurrences of the given patterns.
1776 @item +(@var{pattern-list})
1777 Matches one or more occurrences of the given patterns.
1779 @item @@(@var{pattern-list})
1780 Matches exactly one of the given patterns.
1782 @item !(@var{pattern-list})
1783 Matches anything except one of the given patterns.
1787 @subsection Quote Removal
1789 After the preceding expansions, all unquoted occurrences of the
1790 characters @samp{\}, @samp{'}, and @samp{"} that did not
1791 result from one of the above expansions are removed.
1794 @section Redirections
1797 Before a command is executed, its input and output
1798 may be @var{redirected}
1799 using a special notation interpreted by the shell.
1800 Redirection may also be used to open and close files for the
1801 current shell execution environment. The following redirection
1802 operators may precede or appear anywhere within a
1803 simple command or may follow a command.
1804 Redirections are processed in the order they appear, from
1807 In the following descriptions, if the file descriptor number is
1808 omitted, and the first character of the redirection operator is
1809 @samp{<}, the redirection refers to the standard input (file
1810 descriptor 0). If the first character of the redirection operator
1811 is @samp{>}, the redirection refers to the standard output (file
1814 The word following the redirection operator in the following
1815 descriptions, unless otherwise noted, is subjected to brace expansion,
1816 tilde expansion, parameter expansion, command substitution, arithmetic
1817 expansion, quote removal, filename expansion, and word splitting.
1818 If it expands to more than one word, Bash reports an error.
1820 Note that the order of redirections is significant. For example,
1823 ls > @var{dirlist} 2>&1
1826 directs both standard output (file descriptor 1) and standard error
1827 (file descriptor 2) to the file @var{dirlist}, while the command
1829 ls 2>&1 > @var{dirlist}
1832 directs only the standard output to file @var{dirlist},
1833 because the standard error was duplicated as standard output
1834 before the standard output was redirected to @var{dirlist}.
1836 Bash handles several filenames specially when they are used in
1837 redirections, as described in the following table:
1840 @item /dev/fd/@var{fd}
1841 If @var{fd} is a valid integer, file descriptor @var{fd} is duplicated.
1844 File descriptor 0 is duplicated.
1847 File descriptor 1 is duplicated.
1850 File descriptor 2 is duplicated.
1852 @item /dev/tcp/@var{host}/@var{port}
1853 If @var{host} is a valid hostname or Internet address, and @var{port}
1854 is an integer port number, Bash attempts to open a TCP connection
1855 to the corresponding socket.
1857 @item /dev/udp/@var{host}/@var{port}
1858 If @var{host} is a valid hostname or Internet address, and @var{port}
1859 is an integer port number, Bash attempts to open a UDP connection
1860 to the corresponding socket.
1864 A failure to open or create a file causes the redirection to fail.
1866 @subsection Redirecting Input
1867 Redirection of input causes the file whose name results from
1868 the expansion of @var{word}
1869 to be opened for reading on file descriptor @code{n},
1870 or the standard input (file descriptor 0) if @code{n}
1873 The general format for redirecting input is:
1878 @subsection Redirecting Output
1879 Redirection of output causes the file whose name results from
1880 the expansion of @var{word}
1881 to be opened for writing on file descriptor @code{n},
1882 or the standard output (file descriptor 1) if @code{n}
1883 is not specified. If the file does not exist it is created;
1884 if it does exist it is truncated to zero size.
1886 The general format for redirecting output is:
1891 If the redirection operator is @samp{>}, and the @code{noclobber}
1892 option to the @code{set} builtin has been enabled, the redirection
1893 will fail if the file whose name results from the expansion of
1894 @var{word} exists and is a regular file.
1895 If the redirection operator is @samp{>|}, or the redirection operator is
1896 @samp{>} and the @code{noclobber} option is not enabled, the redirection
1897 is attempted even if the file named by @var{word} exists.
1899 @subsection Appending Redirected Output
1900 Redirection of output in this fashion
1901 causes the file whose name results from
1902 the expansion of @var{word}
1903 to be opened for appending on file descriptor @code{n},
1904 or the standard output (file descriptor 1) if @code{n}
1905 is not specified. If the file does not exist it is created.
1907 The general format for appending output is:
1912 @subsection Redirecting Standard Output and Standard Error
1913 Bash allows both the
1914 standard output (file descriptor 1) and
1915 the standard error output (file descriptor 2)
1916 to be redirected to the file whose name is the
1917 expansion of @var{word} with this construct.
1919 There are two formats for redirecting standard output and
1930 Of the two forms, the first is preferred.
1931 This is semantically equivalent to
1936 @subsection Here Documents
1937 This type of redirection instructs the shell to read input from the
1938 current source until a line containing only @var{word}
1939 (with no trailing blanks) is seen. All of
1940 the lines read up to that point are then used as the standard
1941 input for a command.
1943 The format of here-documents is as follows:
1945 <<[@minus{}]@var{word}
1950 No parameter expansion, command substitution, arithmetic expansion,
1951 or filename expansion is performed on
1952 @var{word}. If any characters in @var{word} are quoted, the
1953 @var{delimiter} is the result of quote removal on @var{word},
1954 and the lines in the here-document are not expanded.
1955 If @var{word} is unquoted,
1956 all lines of the here-document are subjected to parameter expansion,
1957 command substitution, and arithmetic expansion. In the latter
1958 case, the character sequence @code{\newline} is ignored, and @samp{\}
1959 must be used to quote the characters
1960 @samp{\}, @samp{$}, and @samp{`}.
1962 If the redirection operator is @samp{<<-},
1963 then all leading tab characters are stripped from input lines and the
1964 line containing @var{delimiter}.
1965 This allows here-documents within shell scripts to be indented in a
1968 @subsection Duplicating File Descriptors
1969 The redirection operator
1974 is used to duplicate input file descriptors.
1976 expands to one or more digits, the file descriptor denoted by @code{n}
1977 is made to be a copy of that file descriptor.
1978 If the digits in @var{word} do not specify a file descriptor open for
1979 input, a redirection error occurs.
1981 evaluates to @samp{-}, file descriptor @code{n} is closed. If
1982 @code{n} is not specified, the standard input (file descriptor 0) is used.
1989 is used similarly to duplicate output file descriptors. If
1991 is not specified, the standard output (file descriptor 1) is used.
1992 If the digits in @var{word} do not specify a file descriptor open for
1993 output, a redirection error occurs.
1994 As a special case, if @code{n} is omitted, and @var{word} does not
1995 expand to one or more digits, the standard output and standard
1996 error are redirected as described previously.
1998 @subsection Opening File Descriptors for Reading and Writing
1999 The redirection operator
2004 causes the file whose name is the expansion of @var{word}
2005 to be opened for both reading and writing on file descriptor
2006 @code{n}, or on file descriptor 0 if @code{n}
2007 is not specified. If the file does not exist, it is created.
2009 @node Executing Commands
2010 @section Executing Commands
2013 * Simple Command Expansion:: How Bash expands simple commands before
2016 * Command Search and Execution:: How Bash finds commands and runs them.
2018 * Command Execution Environment:: The environment in which Bash
2019 executes commands that are not
2022 * Environment:: The environment given to a command.
2024 * Exit Status:: The status returned by commands and how Bash
2027 * Signals:: What happens when Bash or a command it runs
2032 @node Simple Command Expansion
2033 @subsection Simple Command Expansion
2034 @cindex command expansion
2036 When a simple command is executed, the shell performs the following
2037 expansions, assignments, and redirections, from left to right.
2041 The words that the parser has marked as variable assignments (those
2042 preceding the command name) and redirections are saved for later
2046 The words that are not variable assignments or redirections are
2047 expanded (@pxref{Shell Expansions}).
2048 If any words remain after expansion, the first word
2049 is taken to be the name of the command and the remaining words are
2053 Redirections are performed as described above (@pxref{Redirections}).
2056 The text after the @samp{=} in each variable assignment undergoes tilde
2057 expansion, parameter expansion, command substitution, arithmetic expansion,
2058 and quote removal before being assigned to the variable.
2061 If no command name results, the variable assignments affect the current
2062 shell environment. Otherwise, the variables are added to the environment
2063 of the executed command and do not affect the current shell environment.
2064 If any of the assignments attempts to assign a value to a readonly variable,
2065 an error occurs, and the command exits with a non-zero status.
2067 If no command name results, redirections are performed, but do not
2068 affect the current shell environment. A redirection error causes the
2069 command to exit with a non-zero status.
2071 If there is a command name left after expansion, execution proceeds as
2072 described below. Otherwise, the command exits. If one of the expansions
2073 contained a command substitution, the exit status of the command is
2074 the exit status of the last command substitution performed. If there
2075 were no command substitutions, the command exits with a status of zero.
2077 @node Command Search and Execution
2078 @subsection Command Search and Execution
2079 @cindex command execution
2080 @cindex command search
2082 After a command has been split into words, if it results in a
2083 simple command and an optional list of arguments, the following
2088 If the command name contains no slashes, the shell attempts to
2089 locate it. If there exists a shell function by that name, that
2090 function is invoked as described in @ref{Shell Functions}.
2093 If the name does not match a function, the shell searches for
2094 it in the list of shell builtins. If a match is found, that
2098 If the name is neither a shell function nor a builtin,
2099 and contains no slashes, Bash searches each element of
2100 @code{$PATH} for a directory containing an executable file
2101 by that name. Bash uses a hash table to remember the full
2102 pathnames of executable files to avoid multiple @code{PATH} searches
2103 (see the description of @code{hash} in @ref{Bourne Shell Builtins}).
2104 A full search of the directories in @code{$PATH}
2105 is performed only if the command is not found in the hash table.
2106 If the search is unsuccessful, the shell prints an error
2107 message and returns an exit status of 127.
2110 If the search is successful, or if the command name contains
2111 one or more slashes, the shell executes the named program in
2112 a separate execution environment.
2113 Argument 0 is set to the name given, and the remaining arguments
2114 to the command are set to the arguments supplied, if any.
2117 If this execution fails because the file is not in executable
2118 format, and the file is not a directory, it is assumed to be a
2119 @var{shell script} and the shell executes it as described in
2120 @ref{Shell Scripts}.
2123 If the command was not begun asynchronously, the shell waits for
2124 the command to complete and collects its exit status.
2128 @node Command Execution Environment
2129 @subsection Command Execution Environment
2130 @cindex execution environment
2132 The shell has an @var{execution environment}, which consists of the
2137 open files inherited by the shell at invocation, as modified by
2138 redirections supplied to the @code{exec} builtin
2141 the current working directory as set by @code{cd}, @code{pushd}, or
2142 @code{popd}, or inherited by the shell at invocation
2145 the file creation mode mask as set by @code{umask} or inherited from
2149 current traps set by @code{trap}
2152 shell parameters that are set by variable assignment or with @code{set}
2153 or inherited from the shell's parent in the environment
2156 shell functions defined during execution or inherited from the shell's
2157 parent in the environment
2160 options enabled at invocation (either by default or with command-line
2161 arguments) or by @code{set}
2164 options enabled by @code{shopt}
2167 shell aliases defined with @code{alias} (@pxref{Aliases})
2170 various process @sc{id}s, including those of background jobs
2171 (@pxref{Lists}), the value of @code{$$}, and the value of
2176 When a simple command other than a builtin or shell function
2177 is to be executed, it
2178 is invoked in a separate execution environment that consists of
2179 the following. Unless otherwise noted, the values are inherited
2184 the shell's open files, plus any modifications and additions specified
2185 by redirections to the command
2188 the current working directory
2191 the file creation mode mask
2194 shell variables marked for export, along with variables exported for
2195 the command, passed in the environment (@pxref{Environment})
2198 traps caught by the shell are reset to the values inherited from the
2199 shell's parent, and traps ignored by the shell are ignored
2203 A command invoked in this separate environment cannot affect the
2204 shell's execution environment.
2206 Command substitution and asynchronous commands are invoked in a
2207 subshell environment that is a duplicate of the shell environment,
2208 except that traps caught by the shell are reset to the values
2209 that the shell inherited from its parent at invocation. Builtin
2210 commands that are invoked as part of a pipeline are also executed
2211 in a subshell environment. Changes made to the subshell environment
2212 cannot affect the shell's execution environment.
2215 @subsection Environment
2218 When a program is invoked it is given an array of strings
2219 called the @var{environment}.
2220 This is a list of name-value pairs, of the form @code{name=value}.
2222 Bash provides several ways to manipulate the environment.
2223 On invocation, the shell scans its own environment and
2224 creates a parameter for each name found, automatically marking
2226 to child processes. Executed commands inherit the environment.
2227 The @code{export} and @samp{declare -x}
2228 commands allow parameters and functions to be added to and
2229 deleted from the environment. If the value of a parameter
2230 in the environment is modified, the new value becomes part
2231 of the environment, replacing the old. The environment
2232 inherited by any executed command consists of the shell's
2233 initial environment, whose values may be modified in the shell,
2234 less any pairs removed by the @code{unset} and @samp{export -n}
2235 commands, plus any additions via the @code{export} and
2236 @samp{declare -x} commands.
2238 The environment for any simple command
2239 or function may be augmented temporarily by prefixing it with
2240 parameter assignments, as described in @ref{Shell Parameters}.
2241 These assignment statements affect only the environment seen
2244 If the @samp{-k} option is set (@pxref{The Set Builtin}), then all
2245 parameter assignments are placed in the environment for a command,
2246 not just those that precede the command name.
2248 When Bash invokes an external command, the variable @samp{$_}
2249 is set to the full path name of the command and passed to that
2250 command in its environment.
2253 @subsection Exit Status
2256 For the shell's purposes, a command which exits with a
2257 zero exit status has succeeded.
2258 A non-zero exit status indicates failure.
2259 This seemingly counter-intuitive scheme is used so there
2260 is one well-defined way to indicate success and a variety of
2261 ways to indicate various failure modes.
2262 When a command terminates on a fatal signal whose number is @var{N},
2263 Bash uses the value 128+@var{N} as the exit status.
2265 If a command is not found, the child process created to
2266 execute it returns a status of 127. If a command is found
2267 but is not executable, the return status is 126.
2269 If a command fails because of an error during expansion or redirection,
2270 the exit status is greater than zero.
2272 The exit status is used by the Bash conditional commands
2273 (@pxref{Conditional Constructs}) and some of the list
2274 constructs (@pxref{Lists}).
2276 All of the Bash builtins return an exit status of zero if they succeed
2277 and a non-zero status on failure, so they may be used by the
2278 conditional and list constructs.
2279 All builtins return an exit status of 2 to indicate incorrect usage.
2283 @cindex signal handling
2285 When Bash is interactive, in the absence of any traps, it ignores
2286 @code{SIGTERM} (so that @samp{kill 0} does not kill an interactive shell),
2288 is caught and handled (so that the @code{wait} builtin is interruptible).
2289 When Bash receives a @code{SIGINT}, it breaks out of any executing loops.
2290 In all cases, Bash ignores @code{SIGQUIT}.
2291 If job control is in effect (@pxref{Job Control}), Bash
2292 ignores @code{SIGTTIN}, @code{SIGTTOU}, and @code{SIGTSTP}.
2294 Commands started by Bash have signal handlers set to the
2295 values inherited by the shell from its parent.
2296 When job control is not in effect, asynchronous commands
2297 ignore @code{SIGINT} and @code{SIGQUIT} as well.
2298 Commands run as a result of
2299 command substitution ignore the keyboard-generated job control signals
2300 @code{SIGTTIN}, @code{SIGTTOU}, and @code{SIGTSTP}.
2302 The shell exits by default upon receipt of a @code{SIGHUP}.
2303 Before exiting, it resends the @code{SIGHUP} to all jobs, running
2305 Stopped jobs are sent @code{SIGCONT} to ensure that they receive
2307 To prevent the shell from sending the @code{SIGHUP} signal to a
2308 particular job, it should be removed
2309 from the jobs table with the @code{disown}
2310 builtin (@pxref{Job Control Builtins}) or marked
2311 to not receive @code{SIGHUP} using @code{disown -h}.
2313 If the @code{huponexit} shell option has been set with @code{shopt}
2314 (@pxref{Bash Builtins}), Bash sends a @code{SIGHUP} to all jobs when
2315 an interactive login shell exits.
2317 When Bash receives a signal for which a trap has been set while waiting
2318 for a command to complete, the trap will not be executed until the
2320 When Bash is waiting for an asynchronous
2321 command via the @code{wait} builtin, the reception of a signal for
2322 which a trap has been set will cause the @code{wait} builtin to return
2323 immediately with an exit status greater than 128, immediately after
2324 which the trap is executed.
2327 @section Shell Scripts
2328 @cindex shell script
2330 A shell script is a text file containing shell commands. When such
2331 a file is used as the first non-option argument when invoking Bash,
2332 and neither the @samp{-c} nor @samp{-s} option is supplied
2333 (@pxref{Invoking Bash}),
2334 Bash reads and executes commands from the file, then exits. This
2335 mode of operation creates a non-interactive shell. When Bash runs
2336 a shell script, it sets the special parameter @code{0} to the name
2337 of the file, rather than the name of the shell, and the positional
2338 parameters are set to the remaining arguments, if any are given.
2339 If no additional arguments are supplied, the positional parameters
2342 A shell script may be made executable by using the @code{chmod} command
2343 to turn on the execute bit. When Bash finds such a file while
2344 searching the @code{$PATH} for a command, it spawns a subshell to
2345 execute it. In other words, executing
2347 filename @var{arguments}
2350 is equivalent to executing
2352 bash filename @var{arguments}
2356 if @code{filename} is an executable shell script.
2357 This subshell reinitializes itself, so that the effect is as if a
2358 new shell had been invoked to interpret the script, with the
2359 exception that the locations of commands remembered by the parent
2360 (see the description of @code{hash} in @ref{Bourne Shell Builtins})
2361 are retained by the child.
2363 Most versions of Unix make this a part of the operating system's command
2364 execution mechanism. If the first line of a script begins with
2365 the two characters @samp{#!}, the remainder of the line specifies
2366 an interpreter for the program.
2367 Thus, you can specify Bash, @code{awk}, Perl, or some other
2368 interpreter and write the rest of the script file in that language.
2370 The arguments to the interpreter
2371 consist of a single optional argument following the interpreter
2372 name on the first line of the script file, followed by the name of
2373 the script file, followed by the rest of the arguments. Bash
2374 will perform this action on operating systems that do not handle it
2375 themselves. Note that some older versions of Unix limit the interpreter
2376 name and argument to a maximum of 32 characters.
2378 Bash scripts often begin with @code{#! /bin/bash} (assuming that
2379 Bash has been installed in @file{/bin}), since this ensures that
2380 Bash will be used to interpret the script, even if it is executed
2381 under another shell.
2383 @node Shell Builtin Commands
2384 @chapter Shell Builtin Commands
2387 * Bourne Shell Builtins:: Builtin commands inherited from the Bourne
2389 * Bash Builtins:: Table of builtins specific to Bash.
2390 * The Set Builtin:: This builtin is so overloaded it
2391 deserves its own section.
2392 * Special Builtins:: Builtin commands classified specially by
2396 Builtin commands are contained within the shell itself.
2397 When the name of a builtin command is used as the first word of
2398 a simple command (@pxref{Simple Commands}), the shell executes
2399 the command directly, without invoking another program.
2400 Builtin commands are necessary to implement functionality impossible
2401 or inconvenient to obtain with separate utilities.
2403 This section briefly the builtins which Bash inherits from
2404 the Bourne Shell, as well as the builtin commands which are unique
2405 to or have been extended in Bash.
2407 Several builtin commands are described in other chapters: builtin
2408 commands which provide the Bash interface to the job control
2409 facilities (@pxref{Job Control Builtins}), the directory stack
2410 (@pxref{Directory Stack Builtins}), the command history
2411 (@pxref{Bash History Builtins}), and the programmable completion
2412 facilities (@pxref{Programmable Completion Builtins}).
2414 Many of the builtins have been extended by @sc{posix} or Bash.
2416 @node Bourne Shell Builtins
2417 @section Bourne Shell Builtins
2419 The following shell builtin commands are inherited from the Bourne Shell.
2420 These commands are implemented as specified by the @sc{posix} 1003.2 standard.
2423 @item : @r{(a colon)}
2428 Do nothing beyond expanding @var{arguments} and performing redirections.
2429 The return status is zero.
2431 @item . @r{(a period)}
2434 . @var{filename} [@var{arguments}]
2436 Read and execute commands from the @var{filename} argument in the
2437 current shell context. If @var{filename} does not contain a slash,
2438 the @code{PATH} variable is used to find
2439 @var{filename}. The current directory is searched if @var{filename}
2440 is not found in @code{$PATH}.
2441 If any @var{arguments} are supplied, they become the positional
2442 parameters when @var{filename} is executed. Otherwise the positional
2443 parameters are unchanged.
2444 The return status is the exit status of the last command executed, or
2445 zero if no commands are executed. If @var{filename} is not found, or
2446 cannot be read, the return status is non-zero.
2447 This builtin is equivalent to @code{source}.
2454 Exit from a @code{for}, @code{while}, @code{until}, or @code{select} loop.
2455 If @var{n} is supplied, the @var{n}th enclosing loop is exited.
2456 @var{n} must be greater than or equal to 1.
2457 The return status is zero unless @var{n} is not greater than or equal to 1.
2462 cd [-LP] [@var{directory}]
2464 Change the current working directory to @var{directory}. If @var{directory}
2465 is not given, the value of the @code{HOME} shell variable is used. If the
2466 shell variable @code{CDPATH} exists, it is used as a search path. If
2467 @var{directory} begins with a slash, @code{CDPATH} is not used.
2468 The @samp{-P} option means
2469 to not follow symbolic links; symbolic links are followed by default
2470 or with the @samp{-L} option.
2471 If @var{directory} is @samp{-}, it is equivalent to @code{$OLDPWD}.
2472 The return status is zero if the directory is successfully changed,
2480 Resume the next iteration of an enclosing @code{for}, @code{while},
2481 @code{until}, or @code{select} loop.
2482 If @var{n} is supplied, the execution of the @var{n}th enclosing loop
2484 @var{n} must be greater than or equal to 1.
2485 The return status is zero unless @var{n} is not greater than or equal to 1.
2490 eval [@var{arguments}]
2492 The arguments are concatenated together into a single command, which is
2493 then read and executed, and its exit status returned as the exit status
2495 If there are no arguments or only empty arguments, the return status is
2501 exec [-cl] [-a @var{name}] [@var{command} [@var{arguments}]]
2504 is supplied, it replaces the shell without creating a new process.
2505 If the @samp{-l} option is supplied, the shell places a dash at the
2506 beginning of the zeroth arg passed to @var{command}.
2507 This is what the @code{login} program does.
2508 The @samp{-c} option causes @var{command} to be executed with an empty
2510 If @samp{-a} is supplied, the shell passes @var{name} as the zeroth
2511 argument to @var{command}.
2512 If no @var{command} is specified, redirections may be used to affect
2513 the current shell environment. If there are no redirection errors, the
2514 return status is zero; otherwise the return status is non-zero.
2521 Exit the shell, returning a status of @var{n} to the shell's parent.
2522 If @var{n} is omitted, the exit status is that of the last command executed.
2523 Any trap on @code{EXIT} is executed before the shell terminates.
2528 export [-fn] [-p] [@var{name}[=@var{value}]]
2530 Mark each @var{name} to be passed to child processes
2531 in the environment. If the @samp{-f} option is supplied, the @var{name}s
2532 refer to shell functions; otherwise the names refer to shell variables.
2533 The @samp{-n} option means to no longer mark each @var{name} for export.
2534 If no @var{names} are supplied, or if the @samp{-p} option is given, a
2535 list of exported names is displayed.
2536 The @samp{-p} option displays output in a form that may be reused as input.
2537 The return status is zero unless an invalid option is supplied, one of
2538 the names is not a valid shell variable name, or @samp{-f} is supplied
2539 with a name that is not a shell function.
2544 getopts @var{optstring} @var{name} [@var{args}]
2546 @code{getopts} is used by shell scripts to parse positional parameters.
2547 @var{optstring} contains the option characters to be recognized; if a
2548 character is followed by a colon, the option is expected to have an
2549 argument, which should be separated from it by white space.
2550 The colon (@samp{:}) and question mark (@samp{?}) may not be
2551 used as option characters.
2552 Each time it is invoked, @code{getopts}
2553 places the next option in the shell variable @var{name}, initializing
2554 @var{name} if it does not exist,
2555 and the index of the next argument to be processed into the
2556 variable @code{OPTIND}.
2557 @code{OPTIND} is initialized to 1 each time the shell or a shell script
2559 When an option requires an argument,
2560 @code{getopts} places that argument into the variable @code{OPTARG}.
2561 The shell does not reset @code{OPTIND} automatically; it must be manually
2562 reset between multiple calls to @code{getopts} within the same shell
2563 invocation if a new set of parameters is to be used.
2565 When the end of options is encountered, @code{getopts} exits with a
2566 return value greater than zero.
2567 @code{OPTIND} is set to the index of the first non-option argument,
2568 and @code{name} is set to @samp{?}.
2571 normally parses the positional parameters, but if more arguments are
2572 given in @var{args}, @code{getopts} parses those instead.
2574 @code{getopts} can report errors in two ways. If the first character of
2575 @var{optstring} is a colon, @var{silent}
2576 error reporting is used. In normal operation diagnostic messages
2577 are printed when invalid options or missing option arguments are
2579 If the variable @code{OPTERR}
2580 is set to 0, no error messages will be displayed, even if the first
2581 character of @code{optstring} is not a colon.
2583 If an invalid option is seen,
2584 @code{getopts} places @samp{?} into @var{name} and, if not silent,
2585 prints an error message and unsets @code{OPTARG}.
2586 If @code{getopts} is silent, the option character found is placed in
2587 @code{OPTARG} and no diagnostic message is printed.
2589 If a required argument is not found, and @code{getopts}
2590 is not silent, a question mark (@samp{?}) is placed in @var{name},
2591 @code{OPTARG} is unset, and a diagnostic message is printed.
2592 If @code{getopts} is silent, then a colon (@samp{:}) is placed in
2593 @var{name} and @code{OPTARG} is set to the option character found.
2598 hash [-r] [-p @var{filename}] [@var{name}]
2600 Remember the full pathnames of commands specified as @var{name} arguments,
2601 so they need not be searched for on subsequent invocations.
2602 The commands are found by searching through the directories listed in
2604 The @samp{-p} option inhibits the path search, and @var{filename} is
2605 used as the location of @var{name}.
2606 The @samp{-r} option causes the shell to forget all remembered locations.
2607 If no arguments are given, information about remembered commands is printed.
2608 The return status is zero unless a @var{name} is not found or an invalid
2616 Print the absolute pathname of the current working directory.
2617 If the @samp{-P} option is supplied, the pathname printed will not
2618 contain symbolic links.
2619 If the @samp{-L} option is supplied, the pathname printed may contain
2621 The return status is zero unless an error is encountered while
2622 determining the name of the current directory or an invalid option
2628 readonly [-apf] [@var{name}] @dots{}
2630 Mark each @var{name} as readonly.
2631 The values of these names may not be changed by subsequent assignment.
2632 If the @samp{-f} option is supplied, each @var{name} refers to a shell
2634 The @samp{-a} option means each @var{name} refers to an array variable.
2635 If no @var{name} arguments are given, or if the @samp{-p}
2636 option is supplied, a list of all readonly names is printed.
2637 The @samp{-p} option causes output to be displayed in a format that
2638 may be reused as input.
2639 The return status is zero unless an invalid option is supplied, one of
2640 the @var{name} arguments is not a valid shell variable or function name,
2641 or the @samp{-f} option is supplied with a name that is not a shell function.
2648 Cause a shell function to exit with the return value @var{n}.
2649 If @var{n} is not supplied, the return value is the exit status of the
2650 last command executed in the function.
2651 This may also be used to terminate execution of a script being executed
2652 with the @code{.} (or @code{source}) builtin, returning either @var{n} or
2653 the exit status of the last command executed within the script as the exit
2654 status of the script.
2655 The return status is false if @code{return} is used outside a function
2656 and not during the execution of a script by @code{.} or @code{source}.
2663 Shift the positional parameters to the left by @var{n}.
2664 The positional parameters from @var{n}+1 @dots{} @code{$#} are
2665 renamed to @code{$1} @dots{} @code{$#}-@var{n}+1.
2666 Parameters represented by the numbers @code{$#} to @var{n}+1 are unset.
2667 @var{n} must be a non-negative number less than or equal to @code{$#}.
2668 If @var{n} is zero or greater than @code{$#}, the positional parameters
2670 If @var{n} is not supplied, it is assumed to be 1.
2671 The return status is zero unless @var{n} is greater than @code{$#} or
2672 less than zero, non-zero otherwise.
2678 Evaluate a conditional expression @var{expr}.
2679 Each operator and operand must be a separate argument.
2680 Expressions are composed of the primaries described below in
2681 @ref{Bash Conditional Expressions}.
2683 When the @code{[} form is used, the last argument to the command must
2686 Expressions may be combined using the following operators, listed in
2687 decreasing order of precedence.
2691 True if @var{expr} is false.
2693 @item ( @var{expr} )
2694 Returns the value of @var{expr}.
2695 This may be used to override the normal precedence of operators.
2697 @item @var{expr1} -a @var{expr2}
2698 True if both @var{expr1} and @var{expr2} are true.
2700 @item @var{expr1} -o @var{expr2}
2701 True if either @var{expr1} or @var{expr2} is true.
2704 The @code{test} and @code{[} builtins evaluate conditional
2705 expressions using a set of rules based on the number of arguments.
2709 The expression is false.
2712 The expression is true if and only if the argument is not null.
2715 If the first argument is @samp{!}, the expression is true if and
2716 only if the second argument is null.
2717 If the first argument is one of the unary conditional operators
2718 (@pxref{Bash Conditional Expressions}), the expression
2719 is true if the unary test is true.
2720 If the first argument is not a valid unary operator, the expression is
2724 If the second argument is one of the binary conditional
2725 operators (@pxref{Bash Conditional Expressions}), the
2726 result of the expression is the result of the binary test using the
2727 first and third arguments as operands.
2728 If the first argument is @samp{!}, the value is the negation of
2729 the two-argument test using the second and third arguments.
2730 If the first argument is exactly @samp{(} and the third argument is
2731 exactly @samp{)}, the result is the one-argument test of the second
2733 Otherwise, the expression is false.
2734 The @samp{-a} and @samp{-o} operators are considered binary operators
2738 If the first argument is @samp{!}, the result is the negation of
2739 the three-argument expression composed of the remaining arguments.
2740 Otherwise, the expression is parsed and evaluated according to
2741 precedence using the rules listed above.
2743 @item 5 or more arguments
2744 The expression is parsed and evaluated according to precedence
2745 using the rules listed above.
2753 Print out the user and system times used by the shell and its children.
2754 The return status is zero.
2759 trap [-lp] [@var{arg}] [@var{sigspec} @dots{}]
2761 The commands in @var{arg} are to be read and executed when the
2762 shell receives signal @var{sigspec}. If @var{arg} is absent or
2763 equal to @samp{-}, all specified signals are reset to the values
2764 they had when the shell was started.
2765 If @var{arg} is the null string, then the signal specified by
2766 each @var{sigspec} is ignored by the shell and commands it invokes.
2767 If @var{arg} is not present and @samp{-p} has been supplied,
2768 the shell displays the trap commands associated with each @var{sigspec}.
2769 If no arguments are supplied, or
2770 only @samp{-p} is given, @code{trap} prints the list of commands
2771 associated with each signal number in a form that may be reused as
2773 Each @var{sigspec} is either a signal name such as @code{SIGINT} (with
2774 or without the @code{SIG} prefix) or a signal number.
2776 is @code{0} or @code{EXIT}, @var{arg} is executed when the shell exits.
2777 If a @var{sigspec} is @code{DEBUG}, the command @var{arg} is executed
2778 after every simple command.
2779 The @samp{-l} option causes the shell to print a list of signal names
2780 and their corresponding numbers.
2782 Signals ignored upon entry to the shell cannot be trapped or reset.
2783 Trapped signals are reset to their original values in a child
2784 process when it is created.
2786 The return status is zero unless a @var{sigspec} does not specify a
2792 umask [-p] [-S] [@var{mode}]
2794 Set the shell process's file creation mask to @var{mode}. If
2795 @var{mode} begins with a digit, it is interpreted as an octal number;
2796 if not, it is interpreted as a symbolic mode mask similar
2797 to that accepted by the @code{chmod} command. If @var{mode} is
2798 omitted, the current value of the mask is printed. If the @samp{-S}
2799 option is supplied without a @var{mode} argument, the mask is printed
2800 in a symbolic format.
2801 If the @samp{-p} option is supplied, and @var{mode}
2802 is omitted, the output is in a form that may be reused as input.
2803 The return status is zero if the mode is successfully changed or if
2804 no @var{mode} argument is supplied, and non-zero otherwise.
2806 Note that when the mode is interpreted as an octal number, each number
2807 of the umask is subtracted from @code{7}. Thus, a umask of @code{022}
2808 results in permissions of @code{755}.
2813 unset [-fv] [@var{name}]
2815 Each variable or function @var{name} is removed.
2816 If no options are supplied, or the @samp{-v} option is given, each
2817 @var{name} refers to a shell variable.
2818 If the @samp{-f} option is given, the @var{name}s refer to shell
2819 functions, and the function definition is removed.
2820 Readonly variables and functions may not be unset.
2821 The return status is zero unless a @var{name} does not exist or is
2826 @section Bash Builtin Commands
2828 This section describes builtin commands which are unique to
2829 or have been extended in Bash.
2830 Some of these commands are specified in the @sc{posix} 1003.2 standard.
2837 alias [@code{-p}] [@var{name}[=@var{value}] @dots{}]
2840 Without arguments or with the @samp{-p} option, @code{alias} prints
2841 the list of aliases on the standard output in a form that allows
2842 them to be reused as input.
2843 If arguments are supplied, an alias is defined for each @var{name}
2844 whose @var{value} is given. If no @var{value} is given, the name
2845 and value of the alias is printed.
2846 Aliases are described in @ref{Aliases}.
2851 bind [-m @var{keymap}] [-lpsvPSV]
2852 bind [-m @var{keymap}] [-q @var{function}] [-u @var{function}] [-r @var{keyseq}]
2853 bind [-m @var{keymap}] -f @var{filename}
2854 bind [-m @var{keymap}] -x @var{keyseq:shell-command}
2855 bind [-m @var{keymap}] @var{keyseq:function-name}
2858 Display current Readline (@pxref{Command Line Editing})
2859 key and function bindings, or
2860 bind a key sequence to a Readline function or macro. The
2861 binding syntax accepted is identical to that of
2862 a Readline initialization file (@pxref{Readline Init File}),
2863 but each binding must be passed as a separate argument: e.g.,
2864 @samp{"\C-x\C-r":re-read-init-file}.
2865 Options, if supplied, have the following meanings:
2868 @item -m @var{keymap}
2869 Use @var{keymap} as the keymap to be affected by
2870 the subsequent bindings. Acceptable @var{keymap}
2873 @code{emacs-standard},
2877 @code{vi-command}, and
2879 @code{vi} is equivalent to @code{vi-command};
2880 @code{emacs} is equivalent to @code{emacs-standard}.
2883 List the names of all Readline functions.
2886 Display Readline function names and bindings in such a way that they
2887 can be used as input or in a Readline initialization file.
2890 List current Readline function names and bindings.
2893 Display Readline variable names and values in such a way that they
2894 can be used as input or in a Readline initialization file.
2897 List current Readline variable names and values.
2900 Display Readline key sequences bound to macros and the strings they output
2901 in such a way that they can be used as input or in a Readline
2902 initialization file.
2905 Display Readline key sequences bound to macros and the strings they output.
2907 @item -f @var{filename}
2908 Read key bindings from @var{filename}.
2910 @item -q @var{function}
2911 Query about which keys invoke the named @var{function}.
2913 @item -u @var{function}
2914 Unbind all keys bound to the named @var{function}.
2916 @item -r @var{keyseq}
2917 Remove any current binding for @var{keyseq}.
2919 @item -x @var{keyseq:shell-command}
2920 Cause @var{shell-command} to be executed whenever @var{keyseq} is
2926 The return status is zero unless an invalid option is supplied or an
2932 builtin [@var{shell-builtin} [@var{args}]]
2934 Run a shell builtin, passing it @var{args}, and return its exit status.
2935 This is useful when defining a shell function with the same
2936 name as a shell builtin, retaining the functionality of the builtin within
2938 The return status is non-zero if @var{shell-builtin} is not a shell
2944 command [-pVv] @var{command} [@var{arguments} @dots{}]
2946 Runs @var{command} with @var{arguments} ignoring any shell function
2947 named @var{command}.
2948 Only shell builtin commands or commands found by searching the
2949 @code{PATH} are executed.
2950 If there is a shell function named @code{ls}, running @samp{command ls}
2951 within the function will execute the external command @code{ls}
2952 instead of calling the function recursively.
2953 The @samp{-p} option means to use a default value for @code{$PATH}
2954 that is guaranteed to find all of the standard utilities.
2955 The return status in this case is 127 if @var{command} cannot be
2956 found or an error occurred, and the exit status of @var{command}
2959 If either the @samp{-V} or @samp{-v} option is supplied, a
2960 description of @var{command} is printed. The @samp{-v} option
2961 causes a single word indicating the command or file name used to
2962 invoke @var{command} to be displayed; the @samp{-V} option produces
2963 a more verbose description. In this case, the return status is
2964 zero if @var{command} is found, and non-zero if not.
2969 declare [-afFrxi] [-p] [@var{name}[=@var{value}]]
2972 Declare variables and give them attributes. If no @var{name}s
2973 are given, then display the values of variables instead.
2975 The @samp{-p} option will display the attributes and values of each
2976 @var{name}. When @samp{-p} is used, additional options are ignored.
2977 The @samp{-F} option inhibits the display of function definitions;
2978 only the function name and attributes are printed. @samp{-F} implies
2979 @samp{-f}. The following options can be used to restrict output
2980 to variables with the specified attributes or to give variables
2985 Each @var{name} is an array variable (@pxref{Arrays}).
2988 Use function names only.
2991 The variable is to be treated as
2992 an integer; arithmetic evaluation (@pxref{Shell Arithmetic}) is
2993 performed when the variable is assigned a value.
2996 Make @var{name}s readonly. These names cannot then be assigned values
2997 by subsequent assignment statements or unset.
3000 Mark each @var{name} for export to subsequent commands via
3004 Using @samp{+} instead of @samp{-} turns off the attribute instead.
3005 When used in a function, @code{declare} makes each @var{name} local,
3006 as with the @code{local} command.
3008 The return status is zero unless an invalid option is encountered,
3009 an attempt is made to define a function using @samp{-f foo=bar},
3010 an attempt is made to assign a value to a readonly variable,
3011 an attempt is made to assign a value to an array variable without
3012 using the compound assignment syntax (@pxref{Arrays}),
3013 one of the @var{names} is not a valid shell variable name,
3014 an attempt is made to turn off readonly status for a readonly variable,
3015 an attempt is made to turn off array status for an array variable,
3016 or an attempt is made to display a non-existent function with @samp{-f}.
3021 echo [-neE] [@var{arg} @dots{}]
3023 Output the @var{arg}s, separated by spaces, terminated with a
3025 The return status is always 0.
3026 If @samp{-n} is specified, the trailing newline is suppressed.
3027 If the @samp{-e} option is given, interpretation of the following
3028 backslash-escaped characters is enabled.
3029 The @samp{-E} option disables the interpretation of these escape characters,
3030 even on systems where they are interpreted by default.
3031 The @code{xpg_echo} shell option may be used to
3032 dynamically determine whether or not @code{echo} expands these
3033 escape characters by default.
3034 @code{echo} interprets the following escape sequences:
3041 suppress trailing newline
3057 the character whose @code{ASCII} code is the octal value @var{nnn}
3058 (one to three digits)
3060 the character whose @code{ASCII} code is the hexadecimal value @var{nnn}
3061 (one to three digits)
3067 enable [-n] [-p] [-f @var{filename}] [-ads] [@var{name} @dots{}]
3069 Enable and disable builtin shell commands.
3070 Disabling a builtin allows a disk command which has the same name
3071 as a shell builtin to be executed without specifying a full pathname,
3072 even though the shell normally searches for builtins before disk commands.
3073 If @samp{-n} is used, the @var{name}s become disabled. Otherwise
3074 @var{name}s are enabled. For example, to use the @code{test} binary
3075 found via @code{$PATH} instead of the shell builtin version, type
3076 @samp{enable -n test}.
3078 If the @samp{-p} option is supplied, or no @var{name} arguments appear,
3079 a list of shell builtins is printed. With no other arguments, the list
3080 consists of all enabled shell builtins.
3081 The @samp{-a} option means to list
3082 each builtin with an indication of whether or not it is enabled.
3084 The @samp{-f} option means to load the new builtin command @var{name}
3085 from shared object @var{filename}, on systems that support dynamic loading.
3086 The @samp{-d} option will delete a builtin loaded with @samp{-f}.
3088 If there are no options, a list of the shell builtins is displayed.
3089 The @samp{-s} option restricts @code{enable} to the @sc{posix} special
3090 builtins. If @samp{-s} is used with @samp{-f}, the new builtin becomes
3091 a special builtin (@pxref{Special Builtins}).
3093 The return status is zero unless a @var{name} is not a shell builtin
3094 or there is an error loading a new builtin from a shared object.
3099 help [-s] [@var{pattern}]
3101 Display helpful information about builtin commands.
3102 If @var{pattern} is specified, @code{help} gives detailed help
3103 on all commands matching @var{pattern}, otherwise a list of
3104 the builtins is printed.
3105 The @samp{-s} option restricts the information displayed to a short
3107 The return status is zero unless no command matches @var{pattern}.
3112 let @var{expression} [@var{expression}]
3114 The @code{let} builtin allows arithmetic to be performed on shell
3115 variables. Each @var{expression} is evaluated according to the
3116 rules given below in @ref{Shell Arithmetic}. If the
3117 last @var{expression} evaluates to 0, @code{let} returns 1;
3118 otherwise 0 is returned.
3123 local [@var{option}] @var{name}[=@var{value}]
3125 For each argument, a local variable named @var{name} is created,
3126 and assigned @var{value}.
3127 The @var{option} can be any of the options accepted by @code{declare}.
3128 @code{local} can only be used within a function; it makes the variable
3129 @var{name} have a visible scope restricted to that function and its
3130 children. The return status is zero unless @code{local} is used outside
3131 a function, an invalid @var{name} is supplied, or @var{name} is a
3139 Exit a login shell, returning a status of @var{n} to the shell's
3145 @code{printf} @var{format} [@var{arguments}]
3147 Write the formatted @var{arguments} to the standard output under the
3148 control of the @var{format}.
3149 The @var{format} is a character string which contains three types of objects:
3150 plain characters, which are simply copied to standard output, character
3151 escape sequences, which are converted and copied to the standard output, and
3152 format specifications, each of which causes printing of the next successive
3154 In addition to the standard @code{printf(1)} formats, @samp{%b} causes
3155 @code{printf} to expand backslash escape sequences in the corresponding
3156 @var{argument}, and @samp{%q} causes @code{printf} to output the
3157 corresponding @var{argument} in a format that can be reused as shell input.
3159 The @var{format} is reused as necessary to consume all of the @var{arguments}.
3160 If the @var{format} requires more @var{arguments} than are supplied, the
3161 extra format specifications behave as if a zero value or null string, as
3162 appropriate, had been supplied. The return value is zero on success,
3163 non-zero on failure.
3168 read [-ers] [-a @var{aname}] [-p @var{prompt}] [-t @var{timeout}] [-n @var{nchars}] [-d @var{delim}] [@var{name} @dots{}]
3170 One line is read from the standard input, and the first word
3171 is assigned to the first @var{name}, the second word to the second @var{name},
3172 and so on, with leftover words and their intervening separators assigned
3173 to the last @var{name}.
3174 If there are fewer words read from the standard input than names,
3175 the remaining names are assigned empty values.
3176 The characters in the value of the @code{IFS} variable
3177 are used to split the line into words.
3178 The backslash character @samp{\} may be used to remove any special
3179 meaning for the next character read and for line continuation.
3180 If no names are supplied, the line read is assigned to the
3181 variable @code{REPLY}.
3182 The return code is zero, unless end-of-file is encountered or @code{read}
3184 Options, if supplied, have the following meanings:
3187 @item -a @var{aname}
3188 The words are assigned to sequential indices of the array variable
3189 @var{aname}, starting at 0.
3190 All elements are removed from @var{aname} before the assignment.
3191 Other @var{name} arguments are ignored.
3193 @item -d @var{delim}
3194 The first character of @var{delim} is used to terminate the input line,
3195 rather than newline.
3198 Readline (@pxref{Command Line Editing}) is used to obtain the line.
3200 @item -n @var{nchars}
3201 @code{read} returns after reading @var{nchars} characters rather than
3202 waiting for a complete line of input.
3204 @item -p @var{prompt}
3205 Display @var{prompt}, without a trailing newline, before attempting
3207 The prompt is displayed only if input is coming from a terminal.
3210 If this option is given, backslash does not act as an escape character.
3211 The backslash is considered to be part of the line.
3212 In particular, a backslash-newline pair may not be used as a line
3216 Silent mode. If input is coming from a terminal, characters are
3219 @item -t @var{timeout}
3220 Cause @code{read} to time out and return failure if a complete line of
3221 input is not read within @var{timeout} seconds.
3222 This option has no effect if @code{read} is not reading input from the
3230 shopt [-pqsu] [-o] [@var{optname} @dots{}]
3232 Toggle the values of variables controlling optional shell behavior.
3233 With no options, or with the @samp{-p} option, a list of all settable
3234 options is displayed, with an indication of whether or not each is set.
3235 The @samp{-p} option causes output to be displayed in a form that
3236 may be reused as input.
3237 Other options have the following meanings:
3241 Enable (set) each @var{optname}.
3244 Disable (unset) each @var{optname}.
3247 Suppresses normal output; the return status
3248 indicates whether the @var{optname} is set or unset.
3249 If multiple @var{optname} arguments are given with @samp{-q},
3250 the return status is zero if all @var{optnames} are enabled;
3254 Restricts the values of
3255 @var{optname} to be those defined for the @samp{-o} option to the
3256 @code{set} builtin (@pxref{The Set Builtin}).
3259 If either @samp{-s} or @samp{-u}
3260 is used with no @var{optname} arguments, the display is limited to
3261 those options which are set or unset, respectively.
3263 Unless otherwise noted, the @code{shopt} options are disabled (off)
3266 The return status when listing options is zero if all @var{optnames}
3267 are enabled, non-zero otherwise. When setting or unsetting options,
3268 the return status is zero unless an @var{optname} is not a valid shell
3271 The list of @code{shopt} options is:
3274 If this is set, an argument to the @code{cd}
3275 builtin command that
3276 is not a directory is assumed to be the name of a variable whose
3277 value is the directory to change to.
3280 If set, minor errors in the spelling of a directory component in a
3281 @code{cd} command will be corrected.
3282 The errors checked for are transposed characters,
3283 a missing character, and a character too many.
3284 If a correction is found, the corrected path is printed,
3285 and the command proceeds.
3286 This option is only used by interactive shells.
3289 If this is set, Bash checks that a command found in the hash
3290 table exists before trying to execute it. If a hashed command no
3291 longer exists, a normal path search is performed.
3294 If set, Bash checks the window size after each command
3295 and, if necessary, updates the values of
3296 @code{LINES} and @code{COLUMNS}.
3300 attempts to save all lines of a multiple-line
3301 command in the same history entry. This allows
3302 easy re-editing of multi-line commands.
3305 If set, Bash includes filenames beginning with a `.' in
3306 the results of filename expansion.
3309 If this is set, a non-interactive shell will not exit if
3310 it cannot execute the file specified as an argument to the @code{exec}
3311 builtin command. An interactive shell does not exit if @code{exec}
3314 @item expand_aliases
3315 If set, aliases are expanded as described below under Aliases,
3317 This option is enabled by default for interactive shells.
3320 If set, the extended pattern matching features described above
3321 (@pxref{Pattern Matching}) are enabled.
3324 If set, the history list is appended to the file named by the value
3325 of the @code{HISTFILE}
3326 variable when the shell exits, rather than overwriting the file.
3329 If set, and Readline
3330 is being used, a user is given the opportunity to re-edit a
3331 failed history substitution.
3334 If set, and Readline
3335 is being used, the results of history substitution are not immediately
3336 passed to the shell parser. Instead, the resulting line is loaded into
3337 the Readline editing buffer, allowing further modification.
3340 If set, and Readline is being used, Bash will attempt to perform
3341 hostname completion when a word containing a @samp{@@} is being
3342 completed (@pxref{Commands For Completion}). This option is enabled
3346 If set, Bash will send @code{SIGHUP} to all jobs when an interactive
3347 login shell exits (@pxref{Signals}).
3349 @item interactive_comments
3350 Allow a word beginning with @samp{#}
3351 to cause that word and all remaining characters on that
3352 line to be ignored in an interactive shell.
3353 This option is enabled by default.
3356 If enabled, and the @code{cmdhist}
3357 option is enabled, multi-line commands are saved to the history with
3358 embedded newlines rather than using semicolon separators where possible.
3361 If set, and a file that Bash is checking for mail has been
3362 accessed since the last time it was checked, the message
3363 @code{"The mail in @var{mailfile} has been read"} is displayed.
3365 @item no_empty_cmd_completion
3366 If set, and Readline is being used, Bash will not attempt to search
3367 the @code{PATH} for possible completions when completion is attempted
3371 If set, Bash matches filenames in a case-insensitive fashion when
3372 performing filename expansion.
3375 If set, Bash allows filename patterns which match no
3376 files to expand to a null string, rather than themselves.
3379 If set, the programmable completion facilities
3380 (@pxref{Programmable Completion}) are enabled.
3381 This option is enabled by default.
3384 If set, prompt strings undergo variable and parameter expansion after
3385 being expanded (@pxref{Printing a Prompt}).
3386 This option is enabled by default.
3388 @item restricted_shell
3389 The shell sets this option if it is started in restricted mode
3390 (@pxref{The Restricted Shell}).
3391 The value may not be changed.
3392 This is not reset when the startup files are executed, allowing
3393 the startup files to discover whether or not a shell is restricted.
3396 If this is set, the @code{shift}
3397 builtin prints an error message when the shift count exceeds the
3398 number of positional parameters.
3401 If set, the @code{source} builtin uses the value of @code{PATH}
3402 to find the directory containing the file supplied as an argument.
3403 This option is enabled by default.
3406 If set, the @code{echo} builtin expands backslash-escape sequences
3412 The return status when listing options is zero if all @var{optnames}
3413 are enabled, non-zero otherwise.
3414 When setting or unsetting options, the return status is zero unless an
3415 @var{optname} is not a valid shell option.
3420 source @var{filename}
3422 A synonym for @code{.} (@pxref{Bourne Shell Builtins}).
3427 type [-atp] [@var{name} @dots{}]
3429 For each @var{name}, indicate how it would be interpreted if used as a
3432 If the @samp{-t} option is used, @code{type} prints a single word
3433 which is one of @samp{alias}, @samp{function}, @samp{builtin},
3434 @samp{file} or @samp{keyword},
3435 if @var{name} is an alias, shell function, shell builtin,
3436 disk file, or shell reserved word, respectively.
3437 If the @var{name} is not found, then nothing is printed, and
3438 @code{type} returns a failure status.
3440 If the @samp{-p} option is used, @code{type} either returns the name
3441 of the disk file that would be executed, or nothing if @samp{-t}
3442 would not return @samp{file}.
3444 If the @samp{-a} option is used, @code{type} returns all of the places
3445 that contain an executable named @var{file}.
3446 This includes aliases and functions, if and only if the @samp{-p} option
3449 The return status is zero if any of the @var{names} are found, non-zero
3455 typeset [-afFrxi] [-p] [@var{name}[=@var{value}]]
3457 The @code{typeset} command is supplied for compatibility with the Korn
3458 shell; however, it has been deprecated in favor of the @code{declare}
3464 ulimit [-acdflmnpstuvSH] [@var{limit}]
3466 @code{ulimit} provides control over the resources available to processes
3467 started by the shell, on systems that allow such control. If an
3468 option is given, it is interpreted as follows:
3471 Change and report the soft limit associated with a resource.
3474 Change and report the hard limit associated with a resource.
3477 All current limits are reported.
3480 The maximum size of core files created.
3483 The maximum size of a process's data segment.
3486 The maximum size of files created by the shell.
3489 The maximum size that may be locked into memory.
3492 The maximum resident set size.
3495 The maximum number of open file descriptors.
3498 The pipe buffer size.
3501 The maximum stack size.
3504 The maximum amount of cpu time in seconds.
3507 The maximum number of processes available to a single user.
3510 The maximum amount of virtual memory available to the process.
3514 If @var{limit} is given, it is the new value of the specified resource.
3515 Otherwise, the current value of the soft limit for the specified resource
3516 is printed, unless the @samp{-H} option is supplied.
3517 When setting new limits, if neither @samp{-H} nor @samp{-S} is supplied,
3518 both the hard and soft limits are set.
3519 If no option is given, then @samp{-f} is assumed. Values are in 1024-byte
3520 increments, except for @samp{-t}, which is in seconds, @samp{-p},
3521 which is in units of 512-byte blocks, and @samp{-n} and @samp{-u}, which
3522 are unscaled values.
3524 The return status is zero unless an invalid option is supplied, a
3525 non-numeric argument other than @code{unlimited} is supplied as a
3526 @var{limit}, or an error occurs while setting a new limit.
3531 unalias [-a] [@var{name} @dots{} ]
3534 Remove each @var{name} from the list of aliases. If @samp{-a} is
3535 supplied, all aliases are removed.
3536 Aliases are described in @ref{Aliases}.
3540 @node The Set Builtin
3541 @section The Set Builtin
3543 This builtin is so complicated that it deserves its own section.
3549 set [--abefhkmnptuvxBCHP] [-o @var{option}] [@var{argument} @dots{}]
3552 If no options or arguments are supplied, @code{set} displays the names
3553 and values of all shell variables and functions, sorted according to the
3554 current locale, in a format that may be reused as input.
3556 When options are supplied, they set or unset shell attributes.
3557 Options, if specified, have the following meanings:
3561 Mark variables which are modified or created for export.
3564 Cause the status of terminated background jobs to be reported
3565 immediately, rather than before printing the next primary prompt.
3568 Exit immediately if a simple command (@pxref{Simple Commands}) exits
3569 with a non-zero status, unless the command that fails is part of an
3570 @code{until} or @code{while} loop, part of an @code{if} statement,
3571 part of a @code{&&} or @code{||} list, or if the command's return
3572 status is being inverted using @code{!}.
3575 Disable file name generation (globbing).
3578 Locate and remember (hash) commands as they are looked up for execution.
3579 This option is enabled by default.
3582 All arguments in the form of assignment statements are placed
3583 in the environment for a command, not just those that precede
3587 Job control is enabled (@pxref{Job Control}).
3590 Read commands but do not execute them; this may be used to check a
3591 script for syntax errors.
3592 This option is ignored by interactive shells.
3594 @item -o @var{option-name}
3596 Set the option corresponding to @var{option-name}:
3606 Use an @code{emacs}-style line editing interface (@pxref{Command Line Editing}).
3618 Enable command history, as described in @ref{Bash History Facilities}.
3619 This option is on by default in interactive shells.
3622 An interactive shell will not exit upon reading EOF.
3652 Change the behavior of Bash where the default operation differs
3653 from the @sc{posix} 1003.2 standard to match the standard
3654 (@pxref{Bash POSIX Mode}).
3655 This is intended to make Bash behave as a strict superset of that
3665 Use a @code{vi}-style line editing interface.
3672 Turn on privileged mode.
3673 In this mode, the @code{$BASH_ENV} and @code{$ENV} files are not
3674 processed, shell functions are not inherited from the environment,
3675 and the @code{SHELLOPTS} variable, if it appears in the environment,
3677 If the shell is started with the effective user (group) id not equal to the
3678 real user (group) id, and the @code{-p} option is not supplied, these actions
3679 are taken and the effective user id is set to the real user id.
3680 If the @code{-p} option is supplied at startup, the effective user id is
3682 Turning this option off causes the effective user
3683 and group ids to be set to the real user and group ids.
3686 Exit after reading and executing one command.
3689 Treat unset variables as an error when performing parameter expansion.
3690 An error message will be written to the standard error, and a non-interactive
3694 Print shell input lines as they are read.
3697 Print a trace of simple commands and their arguments after they are
3698 expanded and before they are executed.
3701 The shell will perform brace expansion (@pxref{Brace Expansion}).
3702 This option is on by default.
3705 Prevent output redirection using @samp{>}, @samp{>&}, and @samp{<>}
3706 from overwriting existing files.
3709 Enable @samp{!} style history substitution (@pxref{History Interaction}).
3710 This option is on by default for interactive shells.
3713 If set, do not follow symbolic links when performing commands such as
3714 @code{cd} which change the current directory. The physical directory
3715 is used instead. By default, Bash follows
3716 the logical chain of directories when performing commands
3717 which change the current directory.
3719 For example, if @file{/usr/sys} is a symbolic link to @file{/usr/local/sys}
3722 $ cd /usr/sys; echo $PWD
3729 If @code{set -P} is on, then:
3731 $ cd /usr/sys; echo $PWD
3738 If no arguments follow this option, then the positional parameters are
3739 unset. Otherwise, the positional parameters are set to the
3740 @var{arguments}, even if some of them begin with a @samp{-}.
3743 Signal the end of options, cause all remaining @var{arguments}
3744 to be assigned to the positional parameters. The @samp{-x}
3745 and @samp{-v} options are turned off.
3746 If there are no arguments, the positional parameters remain unchanged.
3749 Using @samp{+} rather than @samp{-} causes these options to be
3750 turned off. The options can also be used upon invocation of the
3751 shell. The current set of options may be found in @code{$-}.
3753 The remaining N @var{arguments} are positional parameters and are
3754 assigned, in order, to @code{$1}, @code{$2}, @dots{} @code{$N}.
3755 The special parameter @code{#} is set to N.
3757 The return status is always zero unless an invalid option is supplied.
3760 @node Special Builtins
3761 @section Special Builtins
3762 @cindex special builtin
3764 For historical reasons, the @sc{posix} 1003.2 standard has classified
3765 several builtin commands as @emph{special}.
3766 When Bash is executing in @sc{posix} mode, the special builtins
3767 differ from other builtin commands in three respects:
3771 Special builtins are found before shell functions during command lookup.
3774 If a special builtin returns an error status, a non-interactive shell exits.
3777 Assignment statements preceding the command stay in effect in the shell
3778 environment after the command completes.
3781 When Bash is not executing in @sc{posix} mode, these builtins behave no
3782 differently than the rest of the Bash builtin commands.
3783 The Bash @sc{posix} mode is described in @ref{Bash POSIX Mode}.
3785 These are the @sc{posix} special builtins:
3787 @w{break : . continue eval exec exit export readonly return set}
3788 @w{shift trap unset}
3791 @node Shell Variables
3792 @chapter Shell Variables
3795 * Bourne Shell Variables:: Variables which Bash uses in the same way
3796 as the Bourne Shell.
3797 * Bash Variables:: List of variables that exist in Bash.
3800 This chapter describes the shell variables that Bash uses.
3801 Bash automatically assigns default values to a number of variables.
3803 @node Bourne Shell Variables
3804 @section Bourne Shell Variables
3806 Bash uses certain shell variables in the same way as the Bourne shell.
3807 In some cases, Bash assigns a default value to the variable.
3812 A colon-separated list of directories used as a search path for
3813 the @code{cd} builtin command.
3816 The current user's home directory; the default for the @code{cd} builtin
3818 The value of this variable is also used by tilde expansion
3819 (@pxref{Tilde Expansion}).
3822 A list of characters that separate fields; used when the shell splits
3823 words as part of expansion.
3826 If this parameter is set to a filename and the @code{MAILPATH} variable
3827 is not set, Bash informs the user of the arrival of mail in
3831 A colon-separated list of filenames which the shell periodically checks
3833 Each list entry can specify the message that is printed when new mail
3834 arrives in the mail file by separating the file name from the message with
3836 When used in the text of the message, @code{$_} expands to the name of
3837 the current mail file.
3840 The value of the last option argument processed by the @code{getopts} builtin.
3843 The index of the last option argument processed by the @code{getopts} builtin.
3846 A colon-separated list of directories in which the shell looks for
3850 The primary prompt string. The default value is @samp{\s-\v\$ }.
3851 @xref{Printing a Prompt}, for the complete list of escape
3852 sequences that are expanded before @code{PS1} is displayed.
3855 The secondary prompt string. The default value is @samp{> }.
3859 @node Bash Variables
3860 @section Bash Variables
3862 These variables are set or used by Bash, but other shells
3863 do not normally treat them specially.
3865 A few variables used by Bash are described in different chapters:
3866 variables for controlling the job control facilities
3867 (@pxref{Job Control Variables}).
3872 The full pathname used to execute the current instance of Bash.
3875 If this variable is set when Bash is invoked to execute a shell
3876 script, its value is expanded and used as the name of a startup file
3877 to read before executing the script. @xref{Bash Startup Files}.
3880 The version number of the current instance of Bash.
3883 A readonly array variable (@pxref{Arrays})
3884 whose members hold version information for this instance of Bash.
3885 The values assigned to the array members are as follows:
3889 @item BASH_VERSINFO[0]
3890 The major version number (the @var{release}).
3892 @item BASH_VERSINFO[1]
3893 The minor version number (the @var{version}).
3895 @item BASH_VERSINFO[2]
3898 @item BASH_VERSINFO[3]
3901 @item BASH_VERSINFO[4]
3902 The release status (e.g., @var{beta1}).
3904 @item BASH_VERSINFO[5]
3905 The value of @code{MACHTYPE}.
3910 An array variable consisting of the individual
3911 words in the current command line.
3912 This variable is available only in shell functions invoked by the
3913 programmable completion facilities (@pxref{Programmable Completion}).
3916 An index into @code{$@{COMP_WORDS@}} of the word containing the current
3918 This variable is available only in shell functions invoked by the
3919 programmable completion facilities (@pxref{Programmable Completion}).
3922 The current command line.
3923 This variable is available only in shell functions and external
3924 commands invoked by the
3925 programmable completion facilities (@pxref{Programmable Completion}).
3928 The index of the current cursor position relative to the beginning of
3929 the current command.
3930 If the current cursor position is at the end of the current command,
3931 the value of this variable is equal to @code{$@{#COMP_LINE@}}.
3932 This variable is available only in shell functions and external
3933 commands invoked by the
3934 programmable completion facilities (@pxref{Programmable Completion}).
3937 An array variable from which Bash reads the possible completions
3938 generated by a shell function invoked by the programmable completion
3939 facility (@pxref{Programmable Completion}).
3942 An array variable containing the current contents of the directory stack.
3943 Directories appear in the stack in the order they are displayed by the
3944 @code{dirs} builtin.
3945 Assigning to members of this array variable may be used to modify
3946 directories already in the stack, but the @code{pushd} and @code{popd}
3947 builtins must be used to add and remove directories.
3948 Assignment to this variable will not change the current directory.
3949 If @code{DIRSTACK} is unset, it loses its special properties, even if
3950 it is subsequently reset.
3953 The numeric effective user id of the current user. This variable
3957 The editor used as a default by the @samp{-e} option to the @code{fc}
3961 A colon-separated list of suffixes to ignore when performing
3962 filename completion.
3963 A file name whose suffix matches one of the entries in
3965 is excluded from the list of matched file names. A sample
3966 value is @samp{.o:~}
3969 A colon-separated list of patterns defining the set of filenames to
3970 be ignored by filename expansion.
3971 If a filename matched by a filename expansion pattern also matches one
3972 of the patterns in @code{GLOBIGNORE}, it is removed from the list
3976 An array variable containing the list of groups of which the current
3978 Assignments to @code{GROUPS} have no effect and are silently discarded.
3979 If @code{GROUPS} is unset, it loses its special properties, even if it is
3983 Up to three characters which control history expansion, quick
3984 substitution, and tokenization (@pxref{History Interaction}).
3985 The first character is the
3986 @var{history expansion} character, that is, the character which signifies the
3987 start of a history expansion, normally @samp{!}. The second character is the
3988 character which signifies `quick substitution' when seen as the first
3989 character on a line, normally @samp{^}. The optional third character is the
3990 character which indicates that the remainder of the line is a comment when
3991 found as the first character of a word, usually @samp{#}. The history
3992 comment character causes history substitution to be skipped for the
3993 remaining words on the line. It does not necessarily cause the shell
3994 parser to treat the rest of the line as a comment.
3997 The history number, or index in the history list, of the current
3998 command. If @code{HISTCMD} is unset, it loses its special properties,
3999 even if it is subsequently reset.
4002 The name of any currently-executing shell function.
4003 This variable exists only when a shell function is executing.
4004 Assignments to @code{FUNCNAME} have no effect and are silently discarded.
4005 If @code{FUNCNAME} is unset, it loses its special properties, even if
4006 it is subsequently reset.
4009 A value of @samp{ignorespace} means to not enter lines which
4010 begin with a space or tab into the history list.
4011 A value of @samp{ignoredups} means to not enter lines which match the last
4013 A value of @samp{ignoreboth} combines the two options.
4014 Unset, or set to any other value than those above, means to save
4015 all lines on the history list.
4016 The second and subsequent lines of a multi-line compound command are
4017 not tested, and are added to the history regardless of the value of
4021 A colon-separated list of patterns used to decide which command
4022 lines should be saved on the history list. Each pattern is
4023 anchored at the beginning of the line and must match the complete
4024 line (no implicit @samp{*} is appended). Each pattern is tested
4025 against the line after the checks specified by @code{HISTCONTROL}
4026 are applied. In addition to the normal shell pattern matching
4027 characters, @samp{&} matches the previous history line. @samp{&}
4028 may be escaped using a backslash; the backslash is removed
4029 before attempting a match.
4030 The second and subsequent lines of a multi-line compound command are
4031 not tested, and are added to the history regardless of the value of
4034 @code{HISTIGNORE} subsumes the function of @code{HISTCONTROL}. A
4035 pattern of @samp{&} is identical to @code{ignoredups}, and a
4036 pattern of @samp{[ ]*} is identical to @code{ignorespace}.
4037 Combining these two patterns, separating them with a colon,
4038 provides the functionality of @code{ignoreboth}.
4041 The name of the file to which the command history is saved. The
4042 default value is @file{~/.bash_history}.
4045 The maximum number of commands to remember on the history list.
4046 The default value is 500.
4049 The maximum number of lines contained in the history file. When this
4050 variable is assigned a value, the history file is truncated, if
4051 necessary, to contain no more than that number of lines.
4052 The history file is also truncated to this size after
4053 writing it when an interactive shell exits.
4054 The default value is 500.
4057 Contains the name of a file in the same format as @file{/etc/hosts} that
4058 should be read when the shell needs to complete a hostname.
4059 The list of possible hostname completions may be changed while the shell
4061 the next time hostname completion is attempted after the
4062 value is changed, Bash adds the contents of the new file to the
4064 If @code{HOSTFILE} is set, but has no value, Bash attempts to read
4065 @file{/etc/hosts} to obtain the list of possible hostname completions.
4066 When @code{HOSTFILE} is unset, the hostname list is cleared.
4069 The name of the current host.
4072 A string describing the machine Bash is running on.
4075 Controls the action of the shell on receipt of an @code{EOF} character
4076 as the sole input. If set, the value denotes the number
4077 of consecutive @code{EOF} characters that can be read as the
4078 first character on an input line
4079 before the shell will exit. If the variable exists but does not
4080 have a numeric value (or has no value) then the default is 10.
4081 If the variable does not exist, then @code{EOF} signifies the end of
4082 input to the shell. This is only in effect for interactive shells.
4085 The name of the Readline initialization file, overriding the default
4086 of @file{~/.inputrc}.
4089 Used to determine the locale category for any category not specifically
4090 selected with a variable starting with @code{LC_}.
4093 This variable overrides the value of @code{LANG} and any other
4094 @code{LC_} variable specifying a locale category.
4097 This variable determines the collation order used when sorting the
4098 results of filename expansion, and
4099 determines the behavior of range expressions, equivalence classes,
4100 and collating sequences within filename expansion and pattern matching
4101 (@pxref{Filename Expansion}).
4104 This variable determines the interpretation of characters and the
4105 behavior of character classes within filename expansion and pattern
4106 matching (@pxref{Filename Expansion}).
4109 This variable determines the locale used to translate double-quoted
4110 strings preceded by a @samp{$} (@pxref{Locale Translation}).
4113 This variable determines the locale category used for number formatting.
4116 The line number in the script or shell function currently executing.
4119 A string that fully describes the system type on which Bash
4120 is executing, in the standard @sc{gnu} @var{cpu-company-system} format.
4123 How often (in seconds) that the shell should check for mail in the
4124 files specified in the @code{MAILPATH} or @code{MAIL} variables.
4127 The previous working directory as set by the @code{cd} builtin.
4130 If set to the value 1, Bash displays error messages
4131 generated by the @code{getopts} builtin command.
4134 A string describing the operating system Bash is running on.
4137 An array variable (@pxref{Arrays})
4138 containing a list of exit status values from the processes
4139 in the most-recently-executed foreground pipeline (which may
4140 contain only a single command).
4143 The process @sc{id} of the shell's parent process. This variable
4146 @item PROMPT_COMMAND
4147 If set, the value is interpreted as a command to execute
4148 before the printing of each primary prompt (@code{$PS1}).
4151 The value of this variable is used as the prompt for the
4152 @code{select} command. If this variable is not set, the
4153 @code{select} command prompts with @samp{#? }
4156 The value is the prompt printed before the command line is echoed
4157 when the @samp{-x} option is set (@pxref{The Set Builtin}).
4158 The first character of @code{PS4} is replicated multiple times, as
4159 necessary, to indicate multiple levels of indirection.
4160 The default is @samp{+ }.
4163 The current working directory as set by the @code{cd} builtin.
4166 Each time this parameter is referenced, a random integer
4167 between 0 and 32767 is generated. Assigning a value to this
4168 variable seeds the random number generator.
4171 The default variable for the @code{read} builtin.
4174 This variable expands to the number of seconds since the
4175 shell was started. Assignment to this variable resets
4176 the count to the value assigned, and the expanded value
4177 becomes the value assigned plus the number of seconds
4178 since the assignment.
4181 A colon-separated list of enabled shell options. Each word in
4182 the list is a valid argument for the @samp{-o} option to the
4183 @code{set} builtin command (@pxref{The Set Builtin}).
4184 The options appearing in @code{SHELLOPTS} are those reported
4185 as @samp{on} by @samp{set -o}.
4186 If this variable is in the environment when Bash
4187 starts up, each shell option in the list will be enabled before
4188 reading any startup files. This variable is readonly.
4191 Incremented by one each time a new instance of Bash is started. This is
4192 intended to be a count of how deeply your Bash shells are nested.
4195 The value of this parameter is used as a format string specifying
4196 how the timing information for pipelines prefixed with the @code{time}
4197 reserved word should be displayed.
4198 The @samp{%} character introduces an
4199 escape sequence that is expanded to a time value or other
4201 The escape sequences and their meanings are as
4202 follows; the braces denote optional portions.
4209 @item %[@var{p}][l]R
4210 The elapsed time in seconds.
4212 @item %[@var{p}][l]U
4213 The number of CPU seconds spent in user mode.
4215 @item %[@var{p}][l]S
4216 The number of CPU seconds spent in system mode.
4219 The CPU percentage, computed as (%U + %S) / %R.
4222 The optional @var{p} is a digit specifying the precision, the number of
4223 fractional digits after a decimal point.
4224 A value of 0 causes no decimal point or fraction to be output.
4225 At most three places after the decimal point may be specified; values
4226 of @var{p} greater than 3 are changed to 3.
4227 If @var{p} is not specified, the value 3 is used.
4229 The optional @code{l} specifies a longer format, including minutes, of
4230 the form @var{MM}m@var{SS}.@var{FF}s.
4231 The value of @var{p} determines whether or not the fraction is included.
4233 If this variable is not set, Bash acts as if it had the value
4235 @code{$'\nreal\t%3lR\nuser\t%3lU\nsys\t%3lS'}
4237 If the value is null, no timing information is displayed.
4238 A trailing newline is added when the format string is displayed.
4241 If set to a value greater than zero, the value is interpreted as
4242 the number of seconds to wait for input after issuing the primary
4243 prompt when the shell is interactive.
4244 Bash terminates after that number of seconds if input does
4248 The numeric real user id of the current user. This variable is readonly.
4253 @chapter Bash Features
4255 This section describes features unique to Bash.
4258 * Invoking Bash:: Command line options that you can give
4260 * Bash Startup Files:: When and how Bash executes scripts.
4261 * Interactive Shells:: What an interactive shell is.
4262 * Bash Conditional Expressions:: Primitives used in composing expressions for
4263 the @code{test} builtin.
4264 * Shell Arithmetic:: Arithmetic on shell variables.
4265 * Aliases:: Substituting one command for another.
4266 * Arrays:: Array Variables.
4267 * The Directory Stack:: History of visited directories.
4268 * Printing a Prompt:: Controlling the PS1 string.
4269 * The Restricted Shell:: A more controlled mode of shell execution.
4270 * Bash POSIX Mode:: Making Bash behave more closely to what
4271 the POSIX standard specifies.
4275 @section Invoking Bash
4278 bash [long-opt] [-ir] [-abefhkmnptuvxdBCDHP] [-o @var{option}] [@var{argument} @dots{}]
4279 bash [long-opt] [-abefhkmnptuvxdBCDHP] [-o @var{option}] -c @var{string} [@var{argument} @dots{}]
4280 bash [long-opt] -s [-abefhkmnptuvxdBCDHP] [-o @var{option}] [@var{argument} @dots{}]
4283 In addition to the single-character shell command-line options
4284 (@pxref{The Set Builtin}), there are several multi-character
4285 options that you can use. These options must appear on the command
4286 line before the single-character options in order for them
4290 @item --dump-po-strings
4291 A list of all double-quoted strings preceded by @samp{$}
4292 is printed on the standard ouput
4293 in the @sc{gnu} @code{gettext} PO (portable object) file format.
4294 Equivalent to @samp{-D} except for the output format.
4296 @item --dump-strings
4297 Equivalent to @samp{-D}.
4300 Display a usage message on standard output and exit sucessfully.
4303 Make this shell act as if it were directly invoked by login.
4304 This is equivalent to @samp{exec -l bash} but can be issued from
4305 another shell, such as @code{csh}. @samp{exec bash --login}
4306 will replace the current shell with a Bash login shell.
4307 @xref{Bash Startup Files}, for a description of the special behavior
4311 Do not use the @sc{gnu} Readline library (@pxref{Command Line Editing})
4312 to read command lines when the shell is interactive.
4315 Don't load the system-wide startup file @file{/etc/profile}
4316 or any of the personal initialization files
4317 @file{~/.bash_profile}, @file{~/.bash_login}, or @file{~/.profile}
4318 when Bash is invoked as a login shell.
4321 Don't read the @file{~/.bashrc} initialization file in an
4322 interactive shell. This is on by default if the shell is
4323 invoked as @code{sh}.
4326 Change the behavior of Bash where the default operation differs
4327 from the @sc{posix} 1003.2 standard to match the standard. This
4328 is intended to make Bash behave as a strict superset of that
4329 standard. @xref{Bash POSIX Mode}, for a description of the Bash
4332 @item --rcfile @var{filename}
4333 Execute commands from @var{filename} (instead of @file{~/.bashrc})
4334 in an interactive shell.
4337 Make the shell a restricted shell (@pxref{The Restricted Shell}).
4340 Equivalent to @samp{-v}. Print shell input lines as they're read.
4343 Show version information for this instance of
4344 Bash on the standard output and exit successfully.
4348 There are several single-character options that may be supplied at
4349 invocation which are not available with the @code{set} builtin.
4352 @item -c @var{string}
4353 Read and execute commands from @var{string} after processing the
4354 options, then exit. Any remaining arguments are assigned to the
4355 positional parameters, starting with @code{$0}.
4358 Force the shell to run interactively. Interactive shells are
4359 described in @ref{Interactive Shells}.
4362 Make the shell a restricted shell (@pxref{The Restricted Shell}).
4365 If this option is present, or if no arguments remain after option
4366 processing, then commands are read from the standard input.
4367 This option allows the positional parameters to be set
4368 when invoking an interactive shell.
4371 A list of all double-quoted strings preceded by @samp{$}
4372 is printed on the standard ouput.
4373 These are the strings that
4374 are subject to language translation when the current locale
4375 is not @code{C} or @code{POSIX} (@pxref{Locale Translation}).
4376 This implies the @samp{-n} option; no commands will be executed.
4379 A @code{--} signals the end of options and disables further option
4381 Any arguments after the @code{--} are treated as filenames and arguments.
4385 @cindex interactive shell
4386 An @emph{interactive} shell is one started without non-option arguments,
4387 unless @samp{-s} is specified,
4388 without specifying the @samp{-c} option, and whose input and output are both
4389 connected to terminals (as determined by @code{isatty(3)}), or one
4390 started with the @samp{-i} option. @xref{Interactive Shells} for more
4393 If arguments remain after option processing, and neither the
4394 @samp{-c} nor the @samp{-s}
4395 option has been supplied, the first argument is assumed to
4396 be the name of a file containing shell commands (@pxref{Shell Scripts}).
4397 When Bash is invoked in this fashion, @code{$0}
4398 is set to the name of the file, and the positional parameters
4399 are set to the remaining arguments.
4400 Bash reads and executes commands from this file, then exits.
4401 Bash's exit status is the exit status of the last command executed
4402 in the script. If no commands are executed, the exit status is 0.
4404 @node Bash Startup Files
4405 @section Bash Startup Files
4406 @cindex startup files
4408 This section describs how Bash executes its startup files.
4409 If any of the files exist but cannot be read, Bash reports an error.
4410 Tildes are expanded in file names as described above under
4411 Tilde Expansion (@pxref{Tilde Expansion}).
4413 Interactive shells are described in @ref{Interactive Shells}.
4415 @subsubheading Invoked as an interactive login shell, or with @samp{--login}
4417 When Bash is invoked as an interactive login shell, or as a
4418 non-interactive shell with the @samp{--login} option, it first reads and
4419 executes commands from the file @file{/etc/profile}, if that file exists.
4420 After reading that file, it looks for @file{~/.bash_profile},
4421 @file{~/.bash_login}, and @file{~/.profile}, in that order, and reads
4422 and executes commands from the first one that exists and is readable.
4423 The @samp{--noprofile} option may be used when the shell is started to
4424 inhibit this behavior.
4426 When a login shell exits, Bash reads and executes commands from
4427 the file @file{~/.bash_logout}, if it exists.
4429 @subsubheading Invoked as an interactive non-login shell
4431 When an interactive shell that is not a login shell is started, Bash
4432 reads and executes commands from @file{~/.bashrc}, if that file exists.
4433 This may be inhibited by using the @samp{--norc} option.
4434 The @samp{--rcfile @var{file}} option will force Bash to read and
4435 execute commands from @var{file} instead of @file{~/.bashrc}.
4437 So, typically, your @file{~/.bash_profile} contains the line
4439 @code{if [ -f ~/.bashrc ]; then . ~/.bashrc; fi}
4442 after (or before) any login-specific initializations.
4444 @subsubheading Invoked non-interactively
4446 When Bash is started non-interactively, to run a shell script,
4447 for example, it looks for the variable @code{BASH_ENV} in the environment,
4448 expands its value if it appears there, and uses the expanded value as
4449 the name of a file to read and execute. Bash behaves as if the
4450 following command were executed:
4452 @code{if [ -n "$BASH_ENV" ]; then . "$BASH_ENV"; fi}
4455 but the value of the @code{PATH} variable is not used to search for the
4458 @subsubheading Invoked with name @code{sh}
4460 If Bash is invoked with the name @code{sh}, it tries to mimic the
4461 startup behavior of historical versions of @code{sh} as closely as
4462 possible, while conforming to the @sc{posix} standard as well.
4464 When invoked as an interactive login shell, or as a non-interactive
4465 shell with the @samp{--login} option, it first attempts to read
4466 and execute commands from @file{/etc/profile} and @file{~/.profile}, in
4468 The @samp{--noprofile} option may be used to inhibit this behavior.
4469 When invoked as an interactive shell with the name @code{sh}, Bash
4470 looks for the variable @code{ENV}, expands its value if it is defined,
4471 and uses the expanded value as the name of a file to read and execute.
4472 Since a shell invoked as @code{sh} does not attempt to read and execute
4473 commands from any other startup files, the @samp{--rcfile} option has
4475 A non-interactive shell invoked with the name @code{sh} does not attempt
4476 to read any other startup files.
4478 When invoked as @code{sh}, Bash enters @sc{posix} mode after
4479 the startup files are read.
4481 @subsubheading Invoked in @sc{posix} mode
4483 When Bash is started in @sc{posix} mode, as with the
4484 @samp{--posix} command line option, it follows the @sc{posix} standard
4486 In this mode, interactive shells expand the @code{ENV} variable
4487 and commands are read and executed from the file whose name is the
4489 No other startup files are read.
4491 @subsubheading Invoked by remote shell daemon
4493 Bash attempts to determine when it is being run by the remote shell
4494 daemon, usually @code{rshd}. If Bash determines it is being run by
4495 rshd, it reads and executes commands from @file{~/.bashrc}, if that
4496 file exists and is readable.
4497 It will not do this if invoked as @code{sh}.
4498 The @samp{--norc} option may be used to inhibit this behavior, and the
4499 @samp{--rcfile} option may be used to force another file to be read, but
4500 @code{rshd} does not generally invoke the shell with those options or
4501 allow them to be specified.
4503 @subsubheading Invoked with unequal effective and real @sc{uid/gid}s
4505 If Bash is started with the effective user (group) id not equal to the
4506 real user (group) id, and the @code{-p} option is not supplied, no startup
4507 files are read, shell functions are not inherited from the environment,
4508 the @code{SHELLOPTS} variable, if it appears in the environment, is ignored,
4509 and the effective user id is set to the real user id.
4510 If the @code{-p} option is supplied at invocation, the startup behavior is
4511 the same, but the effective user id is not reset.
4513 @node Interactive Shells
4514 @section Interactive Shells
4515 @cindex interactive shell
4516 @cindex shell, interactive
4519 * What is an Interactive Shell?:: What determines whether a shell is Interactive.
4520 * Is this Shell Interactive?:: How to tell if a shell is interactive.
4521 * Interactive Shell Behavior:: What changes in a interactive shell?
4524 @node What is an Interactive Shell?
4525 @subsection What is an Interactive Shell?
4527 An interactive shell
4528 is one started without non-option arguments, unless @samp{-s} is
4529 specified, without specifiying the @samp{-c} option, and
4530 whose input and output are both
4531 connected to terminals (as determined by @code{isatty(3)}),
4532 or one started with the @samp{-i} option.
4534 An interactive shell generally reads from and writes to a user's
4537 The @samp{-s} invocation option may be used to set the positional parameters
4538 when an interactive shell is started.
4540 @node Is this Shell Interactive?
4541 @subsection Is this Shell Interactive?
4543 To determine within a startup script whether or not Bash is
4544 running interactively,
4545 test the value of the @samp{-} special parameter.
4546 It contains @code{i} when the shell is interactive. For example:
4550 *i*) echo This shell is interactive ;;
4551 *) echo This shell is not interactive ;;
4555 Alternatively, startup scripts may examine the variable
4556 @code{$PS1}; it is unset in non-interactive shells, and set in
4557 interactive shells. Thus:
4560 if [ -z "$PS1" ]; then
4561 echo This shell is not interactive
4563 echo This shell is interactive
4567 @node Interactive Shell Behavior
4568 @subsection Interactive Shell Behavior
4570 When the shell is running interactively, it changes its behavior in
4575 Startup files are read and executed as described in @ref{Bash Startup Files}.
4578 Job Control (@pxref{Job Control}) is enabled by default. When job
4579 control is in effect, Bash ignores the keyboard-generated job control
4580 signals @code{SIGTTIN}, @code{SIGTTOU}, and @code{SIGTSTP}.
4583 Bash expands and displays @code{$PS1} before reading the first line
4584 of a command, and expands and displays @code{$PS2} before reading the
4585 second and subsequent lines of a multi-line command.
4588 Bash executes the value of the @code{PROMPT_COMMAND} variable as a command
4589 before printing the primary prompt, @code{$PS1}
4590 (@pxref{Bash Variables}).
4593 Readline (@pxref{Command Line Editing}) is used to read commands from
4594 the user's terminal.
4597 Bash inspects the value of the @code{ignoreeof} option to @code{set -o}
4598 instead of exiting immediately when it receives an @code{EOF} on its
4599 standard input when reading a command (@pxref{The Set Builtin}).
4602 Command history (@pxref{Bash History Facilities})
4603 and history expansion (@pxref{History Interaction})
4604 are enabled by default.
4605 Bash will save the command history to the file named by @code{$HISTFILE}
4606 when an interactive shell exits.
4609 Alias expansion (@pxref{Aliases}) is performed by default.
4612 In the absence of any traps, Bash ignores @code{SIGTERM}
4616 In the absence of any traps, @code{SIGINT} is caught and handled
4618 @code{SIGINT} will interrupt some shell builtins.
4621 An interactive login shell sends a @code{SIGHUP} to all jobs on exit
4622 if the @code{hupoxexit} shell option has been enabled (@pxref{Signals}).
4625 The @samp{-n} invocation option is ignored, and @samp{set -n} has
4626 no effect (@pxref{The Set Builtin}).
4629 Bash will check for mail periodically, depending on the values of the
4630 @code{MAIL}, @code{MAILPATH}, and @code{MAILCHECK} shell variables
4631 (@pxref{Bash Variables}).
4634 Expansion errors due to references to unbound shell variables after
4635 @samp{set -u} has been enabled will not cause the shell to exit
4636 (@pxref{The Set Builtin}).
4639 The shell will not exit on expansion errors caused by @var{var} being unset
4640 or null in @code{$@{@var{var}:?@var{word}@}} expansions
4641 (@pxref{Shell Parameter Expansion}).
4644 Redirection errors encountered by shell builtins will not cause the
4648 When running in @sc{posix} mode, a special builtin returning an error
4649 status will not cause the shell to exit (@pxref{Bash POSIX Mode}).
4651 A failed @code{exec} will not cause the shell to exit
4652 (@pxref{Bourne Shell Builtins}).
4655 Parser syntax errors will not cause the shell to exit.
4658 Simple spelling correction for directory arguments to the @code{cd}
4659 builtin is enabled by default (see the description of the @code{cdspell}
4660 option to the @code{shopt} builtin in @ref{Bash Builtins}).
4663 The shell will check the value of the @code{TMOUT} variable and exit
4664 if a command is not read within the specified number of seconds after
4665 printing @code{$PS1} (@pxref{Bash Variables}).
4669 @node Bash Conditional Expressions
4670 @section Bash Conditional Expressions
4671 @cindex expressions, conditional
4673 Conditional expressions are used by the @code{[[} compound command
4674 and the @code{test} and @code{[} builtin commands.
4676 Expressions may be unary or binary.
4677 Unary expressions are often used to examine the status of a file.
4678 There are string operators and numeric comparison operators as well.
4679 If the @var{file} argument to one of the primaries is of the form
4680 @file{/dev/fd/@var{N}}, then file descriptor @var{N} is checked.
4681 If the @var{file} argument to one of the primaries is one of
4682 @file{/dev/stdin}, @file{/dev/stdout}, or @file{/dev/stderr}, file
4683 descriptor 0, 1, or 2, respectively, is checked.
4687 True if @var{file} exists.
4690 True if @var{file} exists and is a block special file.
4693 True if @var{file} exists and is a character special file.
4696 True if @var{file} exists and is a directory.
4699 True if @var{file} exists.
4702 True if @var{file} exists and is a regular file.
4705 True if @var{file} exists and its set-group-id bit is set.
4708 True if @var{file} exists and is a symbolic link.
4711 True if @var{file} exists and its "sticky" bit is set.
4714 True if @var{file} exists and is a named pipe (FIFO).
4717 True if @var{file} exists and is readable.
4720 True if @var{file} exists and has a size greater than zero.
4723 True if file descriptor @var{fd} is open and refers to a terminal.
4726 True if @var{file} exists and its set-user-id bit is set.
4729 True if @var{file} exists and is writable.
4732 True if @var{file} exists and is executable.
4735 True if @var{file} exists and is owned by the effective user id.
4738 True if @var{file} exists and is owned by the effective group id.
4741 True if @var{file} exists and is a symbolic link.
4744 True if @var{file} exists and is a socket.
4747 True if @var{file} exists and has been modified since it was last read.
4749 @item @var{file1} -nt @var{file2}
4750 True if @var{file1} is newer (according to
4751 modification date) than @var{file2}.
4753 @item @var{file1} -ot @var{file2}
4754 True if @var{file1} is older than @var{file2}.
4756 @item @var{file1} -ef @var{file2}
4757 True if @var{file1} and @var{file2} have the same device and
4760 @item -o @var{optname}
4761 True if shell option @var{optname} is enabled.
4762 The list of options appears in the description of the @samp{-o}
4763 option to the @code{set} builtin (@pxref{The Set Builtin}).
4765 @item -z @var{string}
4766 True if the length of @var{string} is zero.
4768 @item -n @var{string}
4770 True if the length of @var{string} is non-zero.
4772 @item @var{string1} == @var{string2}
4773 True if the strings are equal.
4774 @samp{=} may be used in place of @samp{==}.
4776 @item @var{string1} != @var{string2}
4777 True if the strings are not equal.
4779 @item @var{string1} < @var{string2}
4780 True if @var{string1} sorts before @var{string2} lexicographically
4781 in the current locale.
4783 @item @var{string1} > @var{string2}
4784 True if @var{string1} sorts after @var{string2} lexicographically
4785 in the current locale.
4787 @item @var{arg1} OP @var{arg2}
4789 @samp{-eq}, @samp{-ne}, @samp{-lt}, @samp{-le}, @samp{-gt}, or @samp{-ge}.
4790 These arithmetic binary operators return true if @var{arg1}
4791 is equal to, not equal to, less than, less than or equal to,
4792 greater than, or greater than or equal to @var{arg2},
4793 respectively. @var{Arg1} and @var{arg2}
4794 may be positive or negative integers.
4798 @node Shell Arithmetic
4799 @section Shell Arithmetic
4800 @cindex arithmetic, shell
4801 @cindex shell arithmetic
4802 @cindex expressions, arithmetic
4803 @cindex evaluation, arithmetic
4804 @cindex arithmetic evaluation
4806 The shell allows arithmetic expressions to be evaluated, as one of
4807 the shell expansions or by the @code{let} builtin.
4809 Evaluation is done in long integers with no check for overflow,
4810 though division by 0 is trapped and flagged as an error.
4811 The operators and their precedence and associativity are the same
4812 as in the C language.
4813 The following list of operators is grouped into levels of
4814 equal-precedence operators.
4815 The levels are listed in order of decreasing precedence.
4819 @item @var{id}++ @var{id}--
4820 variable post-increment and post-decrement
4822 @item ++@var{id} --@var{id}
4823 variable pre-increment and pre-decrement
4826 unary minus and plus
4829 logical and bitwise negation
4835 multiplication, division, remainder
4838 addition, subtraction
4841 left and right bitwise shifts
4847 equality and inequality
4853 bitwise exclusive OR
4864 @item expr ? expr : expr
4865 conditional evaluation
4867 @item = *= /= %= += -= <<= >>= &= ^= |=
4874 Shell variables are allowed as operands; parameter expansion is
4875 performed before the expression is evaluated.
4876 Within an expression, shell variables may also be referenced by name
4877 without using the parameter expansion syntax.
4878 The value of a variable is evaluated as an arithmetic expression
4879 when it is referenced.
4880 A shell variable need not have its integer attribute turned on
4881 to be used in an expression.
4883 Constants with a leading 0 are interpreted as octal numbers.
4884 A leading @samp{0x} or @samp{0X} denotes hexadecimal. Otherwise,
4885 numbers take the form [@var{base}@code{#}]@var{n}, where @var{base}
4886 is a decimal number between 2 and 64 representing the arithmetic
4887 base, and @var{n} is a number in that base. If @var{base}@code{#} is
4888 omitted, then base 10 is used.
4889 The digits greater than 9 are represented by the lowercase letters,
4890 the uppercase letters, @samp{_}, and @samp{@@}, in that order.
4891 If @var{base} is less than or equal to 36, lowercase and uppercase
4892 letters may be used interchangably to represent numbers between 10
4895 Operators are evaluated in order of precedence. Sub-expressions in
4896 parentheses are evaluated first and may override the precedence
4901 @cindex alias expansion
4903 @var{Aliases} allow a string to be substituted for a word when it is used
4904 as the first word of a simple command.
4905 The shell maintains a list of aliases that may be set and unset with
4906 the @code{alias} and @code{unalias} builtin commands.
4908 The first word of each simple command, if unquoted, is checked to see
4910 If so, that word is replaced by the text of the alias.
4911 The alias name and the replacement text may contain any valid
4912 shell input, including shell metacharacters, with the exception
4913 that the alias name may not contain @samp{=}.
4914 The first word of the replacement text is tested for
4915 aliases, but a word that is identical to an alias being expanded
4916 is not expanded a second time. This means that one may alias
4917 @code{ls} to @code{"ls -F"},
4918 for instance, and Bash does not try to recursively expand the
4919 replacement text. If the last character of the alias value is a
4920 space or tab character, then the next command word following the
4921 alias is also checked for alias expansion.
4923 Aliases are created and listed with the @code{alias}
4924 command, and removed with the @code{unalias} command.
4926 There is no mechanism for using arguments in the replacement text,
4928 If arguments are needed, a shell function should be used
4929 (@pxref{Shell Functions}).
4931 Aliases are not expanded when the shell is not interactive,
4932 unless the @code{expand_aliases} shell option is set using
4933 @code{shopt} (@pxref{Bash Builtins}).
4935 The rules concerning the definition and use of aliases are
4936 somewhat confusing. Bash
4937 always reads at least one complete line
4938 of input before executing any
4939 of the commands on that line. Aliases are expanded when a
4940 command is read, not when it is executed. Therefore, an
4941 alias definition appearing on the same line as another
4942 command does not take effect until the next line of input is read.
4943 The commands following the alias definition
4944 on that line are not affected by the new alias.
4945 This behavior is also an issue when functions are executed.
4946 Aliases are expanded when a function definition is read,
4947 not when the function is executed, because a function definition
4948 is itself a compound command. As a consequence, aliases
4949 defined in a function are not available until after that
4950 function is executed. To be safe, always put
4951 alias definitions on a separate line, and do not use @code{alias}
4952 in compound commands.
4954 For almost every purpose, shell functions are preferred over aliases.
4960 Bash provides one-dimensional array variables. Any variable may be used as
4961 an array; the @code{declare} builtin will explicitly declare an array.
4963 limit on the size of an array, nor any requirement that members
4964 be indexed or assigned contiguously. Arrays are zero-based.
4966 An array is created automatically if any variable is assigned to using
4969 name[@var{subscript}]=@var{value}
4974 is treated as an arithmetic expression that must evaluate to a number
4975 greater than or equal to zero. To explicitly declare an array, use
4977 declare -a @var{name}
4982 declare -a @var{name}[@var{subscript}]
4985 is also accepted; the @var{subscript} is ignored. Attributes may be
4986 specified for an array variable using the @code{declare} and
4987 @code{readonly} builtins. Each attribute applies to all members of
4990 Arrays are assigned to using compound assignments of the form
4992 name=(value@var{1} @dots{} value@var{n})
4996 @var{value} is of the form @code{[[@var{subscript}]=]}@var{string}. If
4997 the optional subscript is supplied, that index is assigned to;
4998 otherwise the index of the element assigned is the last index assigned
4999 to by the statement plus one. Indexing starts at zero.
5000 This syntax is also accepted by the @code{declare}
5001 builtin. Individual array elements may be assigned to using the
5002 @code{name[}@var{subscript}@code{]=}@var{value} syntax introduced above.
5004 Any element of an array may be referenced using
5005 @code{$@{name[}@var{subscript}@code{]@}}.
5006 The braces are required to avoid
5007 conflicts with the shell's filename expansion operators. If the
5008 @var{subscript} is @samp{@@} or @samp{*}, the word expands to all members
5009 of the array @var{name}. These subscripts differ only when the word
5010 appears within double quotes. If the word is double-quoted,
5011 @code{$@{name[*]@}} expands to a single word with
5012 the value of each array member separated by the first character of the
5013 @code{IFS} variable, and @code{$@{name[@@]@}} expands each element of
5014 @var{name} to a separate word. When there are no array members,
5015 @code{$@{name[@@]@}} expands to nothing. This is analogous to the
5016 expansion of the special parameters @samp{@@} and @samp{*}.
5017 @code{$@{#name[}@var{subscript}@code{]@}} expands to the length of
5018 @code{$@{name[}@var{subscript}@code{]@}}.
5019 If @var{subscript} is @samp{@@} or
5020 @samp{*}, the expansion is the number of elements in the array.
5021 Referencing an array variable without a subscript is equivalent to
5022 referencing element zero.
5024 The @code{unset} builtin is used to destroy arrays.
5025 @code{unset} @var{name[subscript]}
5026 destroys the array element at index @var{subscript}.
5027 @code{unset} @var{name}, where @var{name} is an array, removes the
5028 entire array. A subscript of @samp{*} or @samp{@@} also removes the
5031 The @code{declare}, @code{local}, and @code{readonly}
5032 builtins each accept a @samp{-a}
5033 option to specify an array. The @code{read}
5034 builtin accepts a @samp{-a}
5035 option to assign a list of words read from the standard input
5036 to an array, and can read values from the standard input into
5037 individual array elements. The @code{set} and @code{declare}
5038 builtins display array values in a way that allows them to be
5041 @node The Directory Stack
5042 @section The Directory Stack
5043 @cindex directory stack
5046 * Directory Stack Builtins:: Bash builtin commands to manipulate
5047 the directory stack.
5050 The directory stack is a list of recently-visited directories. The
5051 @code{pushd} builtin adds directories to the stack as it changes
5052 the current directory, and the @code{popd} builtin removes specified
5053 directories from the stack and changes the current directory to
5054 the directory removed. The @code{dirs} builtin displays the contents
5055 of the directory stack.
5057 The contents of the directory stack are also visible
5058 as the value of the @code{DIRSTACK} shell variable.
5060 @node Directory Stack Builtins
5061 @subsection Directory Stack Builtins
5068 dirs [+@var{N} | -@var{N}] [-clpv]
5070 Display the list of currently remembered directories. Directories
5071 are added to the list with the @code{pushd} command; the
5072 @code{popd} command removes directories from the list.
5075 Displays the @var{N}th directory (counting from the left of the
5076 list printed by @code{dirs} when invoked without options), starting
5079 Displays the @var{N}th directory (counting from the right of the
5080 list printed by @code{dirs} when invoked without options), starting
5083 Clears the directory stack by deleting all of the elements.
5085 Produces a longer listing; the default listing format uses a
5086 tilde to denote the home directory.
5088 Causes @code{dirs} to print the directory stack with one entry per
5091 Causes @code{dirs} to print the directory stack with one entry per
5092 line, prefixing each entry with its index in the stack.
5098 popd [+@var{N} | -@var{N}] [-n]
5101 Remove the top entry from the directory stack, and @code{cd}
5102 to the new top directory.
5103 When no arguments are given, @code{popd}
5104 removes the top directory from the stack and
5105 performs a @code{cd} to the new top directory. The
5106 elements are numbered from 0 starting at the first directory listed with
5107 @code{dirs}; i.e., @code{popd} is equivalent to @code{popd +0}.
5110 Removes the @var{N}th directory (counting from the left of the
5111 list printed by @code{dirs}), starting with zero.
5113 Removes the @var{N}th directory (counting from the right of the
5114 list printed by @code{dirs}), starting with zero.
5116 Suppresses the normal change of directory when removing directories
5117 from the stack, so that only the stack is manipulated.
5123 pushd [@var{dir} | @var{+N} | @var{-N}] [-n]
5126 Save the current directory on the top of the directory stack
5127 and then @code{cd} to @var{dir}.
5128 With no arguments, @code{pushd} exchanges the top two directories.
5132 Brings the @var{N}th directory (counting from the left of the
5133 list printed by @code{dirs}, starting with zero) to the top of
5134 the list by rotating the stack.
5136 Brings the @var{N}th directory (counting from the right of the
5137 list printed by @code{dirs}, starting with zero) to the top of
5138 the list by rotating the stack.
5140 Suppresses the normal change of directory when adding directories
5141 to the stack, so that only the stack is manipulated.
5143 Makes the current working directory be the top of the stack, and then
5144 executes the equivalent of `@code{cd} @var{dir}'.
5145 @code{cd}s to @var{dir}.
5150 @node Printing a Prompt
5151 @section Controlling the Prompt
5154 The value of the variable @code{PROMPT_COMMAND} is examined just before
5155 Bash prints each primary prompt. If @code{PROMPT_COMMAND} is set and
5156 has a non-null value, then the
5157 value is executed just as if it had been typed on the command line.
5159 In addition, the following table describes the special characters which
5160 can appear in the prompt variables:
5166 The date, in "Weekday Month Date" format (e.g., "Tue May 26").
5168 An escape character.
5170 The hostname, up to the first `.'.
5174 The number of jobs currently managed by the shell.
5176 The basename of the shell's terminal device name.
5182 The name of the shell, the basename of @code{$0} (the portion
5183 following the final slash).
5185 The time, in 24-hour HH:MM:SS format.
5187 The time, in 12-hour HH:MM:SS format.
5189 The time, in 12-hour am/pm format.
5191 The username of the current user.
5193 The version of Bash (e.g., 2.00)
5195 The release of Bash, version + patchlevel (e.g., 2.00.0)
5197 The current working directory.
5199 The basename of @code{$PWD}.
5201 The history number of this command.
5203 The command number of this command.
5205 If the effective uid is 0, @code{#}, otherwise @code{$}.
5207 The character whose ASCII code is the octal value @var{nnn}.
5211 Begin a sequence of non-printing characters. This could be used to
5212 embed a terminal control sequence into the prompt.
5214 End a sequence of non-printing characters.
5217 The command number and the history number are usually different:
5218 the history number of a command is its position in the history
5219 list, which may include commands restored from the history file
5220 (@pxref{Bash History Facilities}), while the command number is
5221 the position in the sequence of commands executed during the current
5224 After the string is decoded, it is expanded via
5225 parameter expansion, command substitution, arithmetic
5226 expansion, and quote removal, subject to the value of the
5227 @code{promptvars} shell option (@pxref{Bash Builtins}).
5229 @node The Restricted Shell
5230 @section The Restricted Shell
5231 @cindex restricted shell
5233 If Bash is started with the name @code{rbash}, or the
5235 option is supplied at invocation, the shell becomes restricted.
5236 A restricted shell is used to
5237 set up an environment more controlled than the standard shell.
5238 A restricted shell behaves identically to @code{bash}
5239 with the exception that the following are disallowed:
5242 Changing directories with the @code{cd} builtin.
5244 Setting or unsetting the values of the @code{SHELL}, @code{PATH},
5245 @code{ENV}, or @code{BASH_ENV} variables.
5247 Specifying command names containing slashes.
5249 Specifying a filename containing a slash as an argument to the @code{.}
5252 Specifying a filename containing a slash as an argument to the @samp{-p}
5253 option to the @code{hash} builtin command.
5255 Importing function definitions from the shell environment at startup.
5257 Parsing the value of @code{SHELLOPTS} from the shell environment at startup.
5259 Redirecting output using the @samp{>}, @samp{>|}, @samp{<>}, @samp{>&},
5260 @samp{&>}, and @samp{>>} redirection operators.
5262 Using the @code{exec} builtin to replace the shell with another command.
5264 Adding or deleting builtin commands with the
5265 @samp{-f} and @samp{-d} options to the @code{enable} builtin.
5267 Specifying the @samp{-p} option to the @code{command} builtin.
5269 Turning off restricted mode with @samp{set +r} or @samp{set +o restricted}.
5272 @node Bash POSIX Mode
5273 @section Bash POSIX Mode
5276 Starting Bash with the @samp{--posix} command-line option or executing
5277 @samp{set -o posix} while Bash is running will cause Bash to conform more
5278 closely to the @sc{posix} 1003.2 standard by changing the behavior to
5279 match that specified by @sc{posix} in areas where the Bash default differs.
5281 The following list is what's changed when `@sc{posix} mode' is in effect:
5285 When a command in the hash table no longer exists, Bash will re-search
5286 @code{$PATH} to find the new location. This is also available with
5287 @samp{shopt -s checkhash}.
5290 The @samp{>&} redirection does not redirect stdout and stderr.
5293 The message printed by the job control code and builtins when a job
5294 exits with a non-zero status is `Done(status)'.
5297 Reserved words may not be aliased.
5300 The @sc{posix} 1003.2 @code{PS1} and @code{PS2} expansions of @samp{!} to
5301 the history number and @samp{!!} to @samp{!} are enabled,
5302 and parameter expansion is performed on the values of @code{PS1} and
5303 @code{PS2} regardless of the setting of the @code{promptvars} option.
5306 Interactive comments are enabled by default. (Bash has them on by
5310 The @sc{posix} 1003.2 startup files are executed (@code{$ENV}) rather than
5311 the normal Bash files.
5314 Tilde expansion is only performed on assignments preceding a command
5315 name, rather than on all assignment statements on the line.
5318 The default history file is @file{~/.sh_history} (this is the
5319 default value of @code{$HISTFILE}).
5322 The output of @samp{kill -l} prints all the signal names on a single line,
5323 separated by spaces.
5326 Non-interactive shells exit if @var{filename} in @code{.} @var{filename}
5330 Non-interactive shells exit if a syntax error in an arithmetic expansion
5331 results in an invalid expression.
5334 Redirection operators do not perform filename expansion on the word
5335 in the redirection unless the shell is interactive.
5338 Redirection operators do not perform word splitting on the word in the
5342 Function names must be valid shell @code{name}s. That is, they may not
5343 contain characters other than letters, digits, and underscores, and
5344 may not start with a digit. Declaring a function with an invalid name
5345 causes a fatal syntax error in non-interactive shells.
5348 @sc{posix} 1003.2 `special' builtins are found before shell functions
5349 during command lookup.
5352 If a @sc{posix} 1003.2 special builtin returns an error status, a
5353 non-interactive shell exits. The fatal errors are those listed in
5354 the POSIX.2 standard, and include things like passing incorrect options,
5355 redirection errors, variable assignment errors for assignments preceding
5356 the command name, and so on.
5359 If the @code{cd} builtin finds a directory to change to
5360 using @code{$CDPATH}, the
5361 value it assigns to the @code{PWD} variable does not contain any
5362 symbolic links, as if @samp{cd -P} had been executed.
5365 If @code{$CDPATH} is set, the @code{cd} builtin will not implicitly
5366 append the current directory to it. This means that @code{cd} will
5367 fail if no valid directory name can be constructed from
5368 any of the entries in @code{$CDPATH}, even if the a directory with
5369 the same name as the name given as an argument to @code{cd} exists
5370 in the current directory.
5373 A non-interactive shell exits with an error status if a variable
5374 assignment error occurs when no command name follows the assignment
5376 A variable assignment error occurs, for example, when trying to assign
5377 a value to a readonly variable.
5380 A non-interactive shell exits with an error status if the iteration
5381 variable in a @code{for} statement or the selection variable in a
5382 @code{select} statement is a readonly variable.
5385 Process substitution is not available.
5388 Assignment statements preceding @sc{posix} 1003.2 special builtins
5389 persist in the shell environment after the builtin completes.
5392 The @code{export} and @code{readonly} builtin commands display their
5393 output in the format required by @sc{posix} 1003.2.
5397 There is other @sc{posix} 1003.2 behavior that Bash does not implement.
5402 Assignment statements affect the execution environment of all
5403 builtins, not just special ones.
5407 @chapter Job Control
5409 This chapter discusses what job control is, how it works, and how
5410 Bash allows you to access its facilities.
5413 * Job Control Basics:: How job control works.
5414 * Job Control Builtins:: Bash builtin commands used to interact
5416 * Job Control Variables:: Variables Bash uses to customize job
5420 @node Job Control Basics
5421 @section Job Control Basics
5425 @cindex suspending jobs
5428 refers to the ability to selectively stop (suspend)
5429 the execution of processes and continue (resume)
5430 their execution at a later point. A user typically employs
5431 this facility via an interactive interface supplied jointly
5432 by the system's terminal driver and Bash.
5434 The shell associates a @var{job} with each pipeline. It keeps a
5435 table of currently executing jobs, which may be listed with the
5436 @code{jobs} command. When Bash starts a job
5437 asynchronously, it prints a line that looks
5443 indicating that this job is job number 1 and that the process @sc{id}
5444 of the last process in the pipeline associated with this job is
5445 25647. All of the processes in a single pipeline are members of
5446 the same job. Bash uses the @var{job} abstraction as the
5447 basis for job control.
5449 To facilitate the implementation of the user interface to job
5450 control, the operating system maintains the notion of a current terminal
5451 process group @sc{id}. Members of this process group (processes whose
5452 process group @sc{id} is equal to the current terminal process group
5453 @sc{id}) receive keyboard-generated signals such as @code{SIGINT}.
5454 These processes are said to be in the foreground. Background
5455 processes are those whose process group @sc{id} differs from the
5456 terminal's; such processes are immune to keyboard-generated
5457 signals. Only foreground processes are allowed to read from or
5458 write to the terminal. Background processes which attempt to
5459 read from (write to) the terminal are sent a @code{SIGTTIN}
5460 (@code{SIGTTOU}) signal by the terminal driver, which, unless
5461 caught, suspends the process.
5463 If the operating system on which Bash is running supports
5464 job control, Bash contains facilities to use it. Typing the
5465 @var{suspend} character (typically @samp{^Z}, Control-Z) while a
5466 process is running causes that process to be stopped and returns
5467 control to Bash. Typing the @var{delayed suspend} character
5468 (typically @samp{^Y}, Control-Y) causes the process to be stopped
5469 when it attempts to read input from the terminal, and control to
5470 be returned to Bash. The user then manipulates the state of
5471 this job, using the @code{bg} command to continue it in the
5472 background, the @code{fg} command to continue it in the
5473 foreground, or the @code{kill} command to kill it. A @samp{^Z}
5474 takes effect immediately, and has the additional side effect of
5475 causing pending output and typeahead to be discarded.
5477 There are a number of ways to refer to a job in the shell. The
5478 character @samp{%} introduces a job name.
5480 Job number @code{n} may be referred to as @samp{%n}.
5481 The symbols @samp{%%} and
5482 @samp{%+} refer to the shell's notion of the current job, which
5483 is the last job stopped while it was in the foreground or started
5484 in the background. The
5485 previous job may be referenced using @samp{%-}. In output
5486 pertaining to jobs (e.g., the output of the @code{jobs} command),
5487 the current job is always flagged with a @samp{+}, and the
5488 previous job with a @samp{-}.
5490 A job may also be referred to
5491 using a prefix of the name used to start it, or using a substring
5492 that appears in its command line. For example, @samp{%ce} refers
5493 to a stopped @code{ce} job. Using @samp{%?ce}, on the
5494 other hand, refers to any job containing the string @samp{ce} in
5495 its command line. If the prefix or substring matches more than one job,
5496 Bash reports an error.
5498 Simply naming a job can be used to bring it into the foreground:
5499 @samp{%1} is a synonym for @samp{fg %1}, bringing job 1 from the
5500 background into the foreground. Similarly, @samp{%1 &} resumes
5501 job 1 in the background, equivalent to @samp{bg %1}
5503 The shell learns immediately whenever a job changes state.
5504 Normally, Bash waits until it is about to print a prompt
5505 before reporting changes in a job's status so as to not interrupt
5506 any other output. If the
5507 the @samp{-b} option to the @code{set} builtin is enabled,
5508 Bash reports such changes immediately (@pxref{The Set Builtin}).
5510 If an attempt to exit Bash is while jobs are stopped, the
5511 shell prints a message warning that there are stopped jobs.
5512 The @code{jobs} command may then be used to inspect their status.
5513 If a second attempt to exit is made without an intervening command,
5514 Bash does not print another warning, and the stopped jobs are terminated.
5516 @node Job Control Builtins
5517 @section Job Control Builtins
5526 Resume the suspended job @var{jobspec} in the background, as if it
5527 had been started with @samp{&}.
5528 If @var{jobspec} is not supplied, the current job is used.
5529 The return status is zero unless it is run when job control is not
5530 enabled, or, when run with job control enabled, if @var{jobspec} was
5531 not found or @var{jobspec} specifies a job that was started without
5539 Resume the job @var{jobspec} in the foreground and make it the current job.
5540 If @var{jobspec} is not supplied, the current job is used.
5541 The return status is that of the command placed into the foreground,
5542 or non-zero if run when job control is disabled or, when run with
5543 job control enabled, @var{jobspec} does not specify a valid job or
5544 @var{jobspec} specifies a job that was started without job control.
5549 jobs [-lnprs] [@var{jobspec}]
5550 jobs -x @var{command} [@var{arguments}]
5553 The first form lists the active jobs. The options have the
5558 List process @sc{id}s in addition to the normal information.
5561 Display information only about jobs that have changed status since
5562 the user was last notified of their status.
5565 List only the process @sc{id} of the job's process group leader.
5568 Restrict output to running jobs.
5571 Restrict output to stopped jobs.
5574 If @var{jobspec} is given,
5575 output is restricted to information about that job.
5576 If @var{jobspec} is not supplied, the status of all jobs is
5579 If the @samp{-x} option is supplied, @code{jobs} replaces any
5580 @var{jobspec} found in @var{command} or @var{arguments} with the
5581 corresponding process group @sc{id}, and executes @var{command},
5582 passing it @var{argument}s, returning its exit status.
5587 kill [-s @var{sigspec}] [-n @var{signum}] [-@var{sigspec}] @var{jobspec} or @var{pid}
5588 kill -l [@var{exit_status}]
5590 Send a signal specified by @var{sigspec} or @var{signum} to the process
5591 named by job specification @var{jobspec} or process @sc{id} @var{pid}.
5592 @var{sigspec} is either a signal name such as @code{SIGINT} (with or without
5593 the @code{SIG} prefix) or a signal number; @var{signum} is a signal number.
5594 If @var{sigspec} and @var{signum} are not present, @code{SIGTERM} is used.
5595 The @samp{-l} option lists the signal names.
5596 If any arguments are supplied when @samp{-l} is given, the names of the
5597 signals corresponding to the arguments are listed, and the return status
5599 @var{exit_status} is a number specifying a signal number or the exit
5600 status of a process terminated by a signal.
5601 The return status is zero if at least one signal was successfully sent,
5602 or non-zero if an error occurs or an invalid option is encountered.
5607 wait [@var{jobspec} or @var{pid}]
5609 Wait until the child process specified by process @sc{id} @var{pid} or job
5610 specification @var{jobspec} exits and return the exit status of the last
5612 If a job spec is given, all processes in the job are waited for.
5613 If no arguments are given, all currently active child processes are
5614 waited for, and the return status is zero.
5615 If neither @var{jobspec} nor @var{pid} specifies an active child process
5616 of the shell, the return status is 127.
5621 disown [-ar] [-h] [@var{jobspec} @dots{}]
5623 Without options, each @var{jobspec} is removed from the table of
5625 If the @samp{-h} option is given, the job is not removed from the table,
5626 but is marked so that @code{SIGHUP} is not sent to the job if the shell
5627 receives a @code{SIGHUP}.
5628 If @var{jobspec} is not present, and neither the @samp{-a} nor @samp{-r}
5629 option is supplied, the current job is used.
5630 If no @var{jobspec} is supplied, the @samp{-a} option means to remove or
5631 mark all jobs; the @samp{-r} option without a @var{jobspec}
5632 argument restricts operation to running jobs.
5639 Suspend the execution of this shell until it receives a
5640 @code{SIGCONT} signal. The @samp{-f} option means to suspend
5641 even if the shell is a login shell.
5645 When job control is not active, the @code{kill} and @code{wait}
5646 builtins do not accept @var{jobspec} arguments. They must be
5647 supplied process @sc{id}s.
5649 @node Job Control Variables
5650 @section Job Control Variables
5655 This variable controls how the shell interacts with the user and
5656 job control. If this variable exists then single word simple
5657 commands without redirections are treated as candidates for resumption
5658 of an existing job. There is no ambiguity allowed; if there is
5659 more than one job beginning with the string typed, then
5660 the most recently accessed job will be selected.
5661 The name of a stopped job, in this context, is the command line
5662 used to start it. If this variable is set to the value @samp{exact},
5663 the string supplied must match the name of a stopped job exactly;
5664 if set to @samp{substring},
5665 the string supplied needs to match a substring of the name of a
5666 stopped job. The @samp{substring} value provides functionality
5667 analogous to the @samp{%?} job @sc{id} (@pxref{Job Control Basics}).
5668 If set to any other value, the supplied string must
5669 be a prefix of a stopped job's name; this provides functionality
5670 analogous to the @samp{%} job @sc{id}.
5674 @set readline-appendix
5675 @set history-appendix
5676 @cindex Readline, how to use
5677 @include rluser.texinfo
5678 @cindex History, how to use
5679 @include hsuser.texinfo
5680 @clear readline-appendix
5681 @clear history-appendix
5683 @node Installing Bash
5684 @chapter Installing Bash
5686 This chapter provides basic instructions for installing Bash on
5687 the various supported platforms. The distribution supports the
5688 @sc{gnu} operating systems, nearly every version of Unix, and several
5689 non-Unix systems such as BeOS and Interix.
5690 Other independent ports exist for
5691 @sc{ms-dos}, @sc{os/2}, Windows @sc{95/98}, and Windows @sc{nt}.
5694 * Basic Installation:: Installation instructions.
5696 * Compilers and Options:: How to set special options for various
5699 * Compiling For Multiple Architectures:: How to compile Bash for more
5700 than one kind of system from
5701 the same source tree.
5703 * Installation Names:: How to set the various paths used by the installation.
5705 * Specifying the System Type:: How to configure Bash for a particular system.
5707 * Sharing Defaults:: How to share default configuration values among GNU
5710 * Operation Controls:: Options recognized by the configuration program.
5712 * Optional Features:: How to enable and disable optional features when
5716 @node Basic Installation
5717 @section Basic Installation
5718 @cindex installation
5719 @cindex configuration
5720 @cindex Bash installation
5721 @cindex Bash configuration
5723 These are installation instructions for Bash.
5725 The simplest way to compile Bash is:
5729 @code{cd} to the directory containing the source code and type
5730 @samp{./configure} to configure Bash for your system. If you're
5731 using @code{csh} on an old version of System V, you might need to
5732 type @samp{sh ./configure} instead to prevent @code{csh} from trying
5733 to execute @code{configure} itself.
5735 Running @code{configure} takes some time.
5736 While running, it prints messages telling which features it is
5740 Type @samp{make} to compile Bash and build the @code{bashbug} bug
5744 Optionally, type @samp{make tests} to run the Bash test suite.
5747 Type @samp{make install} to install @code{bash} and @code{bashbug}.
5748 This will also install the manual pages and Info file.
5752 The @code{configure} shell script attempts to guess correct
5753 values for various system-dependent variables used during
5754 compilation. It uses those values to create a @file{Makefile} in
5755 each directory of the package (the top directory, the
5756 @file{builtins}, @file{doc}, and @file{support} directories,
5757 each directory under @file{lib}, and several others). It also creates a
5758 @file{config.h} file containing system-dependent definitions.
5759 Finally, it creates a shell script named @code{config.status} that you
5760 can run in the future to recreate the current configuration, a
5761 file @file{config.cache} that saves the results of its tests to
5762 speed up reconfiguring, and a file @file{config.log} containing
5763 compiler output (useful mainly for debugging @code{configure}).
5765 @file{config.cache} contains results you don't want to keep, you
5766 may remove or edit it.
5768 To find out more about the options and arguments that the
5769 @code{configure} script understands, type
5772 bash-2.04$ ./configure --help
5776 at the Bash prompt in your Bash source directory.
5778 If you need to do unusual things to compile Bash, please
5779 try to figure out how @code{configure} could check whether or not
5780 to do them, and mail diffs or instructions to
5781 @email{bash-maintainers@@gnu.org} so they can be
5782 considered for the next release.
5784 The file @file{configure.in} is used to create @code{configure}
5785 by a program called Autoconf. You only need
5786 @file{configure.in} if you want to change it or regenerate
5787 @code{configure} using a newer version of Autoconf. If
5788 you do this, make sure you are using Autoconf version 2.10 or
5791 If you need to change @file{configure.in} or regenerate
5792 @code{configure}, you will need to create two files:
5793 @file{_distribution} and @file{_patchlevel}. @file{_distribution}
5794 should contain the major and minor version numbers of the Bash
5795 distribution, for example @samp{2.01}. @file{_patchlevel} should
5796 contain the patch level of the Bash distribution, @samp{0} for
5797 example. The script @file{support/mkconffiles} has been provided
5798 to automate the creation of these files.
5800 You can remove the program binaries and object files from the
5801 source code directory by typing @samp{make clean}. To also remove the
5802 files that @code{configure} created (so you can compile Bash for
5803 a different kind of computer), type @samp{make distclean}.
5805 @node Compilers and Options
5806 @section Compilers and Options
5808 Some systems require unusual options for compilation or linking
5809 that the @code{configure} script does not know about. You can
5810 give @code{configure} initial values for variables by setting
5811 them in the environment. Using a Bourne-compatible shell, you
5812 can do that on the command line like this:
5815 CC=c89 CFLAGS=-O2 LIBS=-lposix ./configure
5818 On systems that have the @code{env} program, you can do it like this:
5821 env CPPFLAGS=-I/usr/local/include LDFLAGS=-s ./configure
5824 The configuration process uses GCC to build Bash if it
5827 @node Compiling For Multiple Architectures
5828 @section Compiling For Multiple Architectures
5830 You can compile Bash for more than one kind of computer at the
5831 same time, by placing the object files for each architecture in their
5832 own directory. To do this, you must use a version of @code{make} that
5833 supports the @code{VPATH} variable, such as GNU @code{make}.
5835 directory where you want the object files and executables to go and run
5836 the @code{configure} script from the source directory. You may need to
5837 supply the @samp{--srcdir=PATH} argument to tell @code{configure} where the
5838 source files are. @code{configure} automatically checks for the
5839 source code in the directory that @code{configure} is in and in `..'.
5841 If you have to use a @code{make} that does not supports the @code{VPATH}
5842 variable, you can compile Bash for one architecture at a
5843 time in the source code directory. After you have installed
5844 Bash for one architecture, use @samp{make distclean} before
5845 reconfiguring for another architecture.
5847 Alternatively, if your system supports symbolic links, you can use the
5848 @file{support/mkclone} script to create a build tree which has
5849 symbolic links back to each file in the source directory. Here's an
5850 example that creates a build directory in the current directory from a
5851 source directory @file{/usr/gnu/src/bash-2.0}:
5854 bash /usr/gnu/src/bash-2.0/support/mkclone -s /usr/gnu/src/bash-2.0 .
5858 The @code{mkclone} script requires Bash, so you must have already built
5859 Bash for at least one architecture before you can create build
5860 directories for other architectures.
5862 @node Installation Names
5863 @section Installation Names
5865 By default, @samp{make install} will install into
5866 @file{/usr/local/bin}, @file{/usr/local/man}, etc. You can
5867 specify an installation prefix other than @file{/usr/local} by
5868 giving @code{configure} the option @samp{--prefix=@var{PATH}}.
5870 You can specify separate installation prefixes for
5871 architecture-specific files and architecture-independent files.
5872 If you give @code{configure} the option
5873 @samp{--exec-prefix=@var{PATH}}, @samp{make install} will use
5874 @var{PATH} as the prefix for installing programs and libraries.
5875 Documentation and other data files will still use the regular prefix.
5877 @node Specifying the System Type
5878 @section Specifying the System Type
5880 There may be some features @code{configure} can not figure out
5881 automatically, but needs to determine by the type of host Bash
5882 will run on. Usually @code{configure} can figure that
5883 out, but if it prints a message saying it can not guess the host
5884 type, give it the @samp{--host=TYPE} option. @samp{TYPE} can
5885 either be a short name for the system type, such as @samp{sun4},
5886 or a canonical name with three fields: @samp{CPU-COMPANY-SYSTEM}
5887 (e.g., @samp{sparc-sun-sunos4.1.2}).
5889 See the file @file{support/config.sub} for the possible
5890 values of each field.
5892 @node Sharing Defaults
5893 @section Sharing Defaults
5895 If you want to set default values for @code{configure} scripts to
5896 share, you can create a site shell script called
5897 @code{config.site} that gives default values for variables like
5898 @code{CC}, @code{cache_file}, and @code{prefix}. @code{configure}
5899 looks for @file{PREFIX/share/config.site} if it exists, then
5900 @file{PREFIX/etc/config.site} if it exists. Or, you can set the
5901 @code{CONFIG_SITE} environment variable to the location of the site
5902 script. A warning: the Bash @code{configure} looks for a site script,
5903 but not all @code{configure} scripts do.
5905 @node Operation Controls
5906 @section Operation Controls
5908 @code{configure} recognizes the following options to control how it
5913 @item --cache-file=@var{file}
5914 Use and save the results of the tests in
5915 @var{file} instead of @file{./config.cache}. Set @var{file} to
5916 @file{/dev/null} to disable caching, for debugging
5920 Print a summary of the options to @code{configure}, and exit.
5925 Do not print messages saying which checks are being made.
5927 @item --srcdir=@var{dir}
5928 Look for the Bash source code in directory @var{dir}. Usually
5929 @code{configure} can determine that directory automatically.
5932 Print the version of Autoconf used to generate the @code{configure}
5936 @code{configure} also accepts some other, not widely used, boilerplate
5937 options. @samp{configure --help} prints the complete list.
5939 @node Optional Features
5940 @section Optional Features
5942 The Bash @code{configure} has a number of @samp{--enable-@var{feature}}
5943 options, where @var{feature} indicates an optional part of Bash.
5944 There are also several @samp{--with-@var{package}} options,
5945 where @var{package} is something like @samp{bash-malloc} or @samp{purify}.
5946 To turn off the default use of a package, use
5947 @samp{--without-@var{package}}. To configure Bash without a feature
5948 that is enabled by default, use @samp{--disable-@var{feature}}.
5950 Here is a complete list of the @samp{--enable-} and
5951 @samp{--with-} options that the Bash @code{configure} recognizes.
5955 Define if you are using the Andrew File System from Transarc.
5957 @item --with-bash-malloc
5958 Use the Bash version of
5959 @code{malloc} in @file{lib/malloc/malloc.c}. This is not the same
5960 @code{malloc} that appears in @sc{gnu} libc, but an older version
5961 derived from the 4.2 @sc{bsd} @code{malloc}. This @code{malloc} is
5962 very fast, but wastes some space on each allocation.
5963 This option is enabled by default.
5964 The @file{NOTES} file contains a list of systems for
5965 which this should be turned off, and @code{configure} disables this
5966 option automatically for a number of systems.
5969 Use the curses library instead of the termcap library. This should
5970 be supplied if your system has an inadequate or incomplete termcap
5973 @item --with-glibc-malloc
5974 Use the @sc{gnu} libc version of @code{malloc} in
5975 @file{lib/malloc/gmalloc.c}. This is not the version of @code{malloc}
5976 that appears in glibc version 2, but a modified version of the
5977 @code{malloc} from glibc version 1. This is somewhat slower than the
5978 default @code{malloc}, but wastes less space on a per-allocation
5979 basis, and will return memory to the operating system under
5980 certain circumstances.
5982 @item --with-gnu-malloc
5983 A synonym for @code{--with-bash-malloc}.
5985 @item --with-installed-readline
5986 Define this to make Bash link with a locally-installed version of Readline
5987 rather than the version in @file{lib/readline}. This works only with
5988 Readline 4.1 and later versions.
5991 Define this to use the Purify memory allocation checker from Rational
5994 @item --enable-minimal-config
5995 This produces a shell with minimal features, close to the historical
5999 There are several @samp{--enable-} options that alter how Bash is
6000 compiled and linked, rather than changing run-time features.
6003 @item --enable-profiling
6004 This builds a Bash binary that produces profiling information to be
6005 processed by @code{gprof} each time it is executed.
6007 @item --enable-static-link
6008 This causes Bash to be linked statically, if @code{gcc} is being used.
6009 This could be used to build a version to use as root's shell.
6012 The @samp{minimal-config} option can be used to disable all of
6013 the following options, but it is processed first, so individual
6014 options may be enabled using @samp{enable-@var{feature}}.
6016 All of the following options except for @samp{disabled-builtins} and
6017 @samp{xpg-echo-default} are
6018 enabled by default, unless the operating system does not provide the
6022 @item --enable-alias
6023 Allow alias expansion and include the @code{alias} and @code{unalias}
6024 builtins (@pxref{Aliases}).
6026 @item --enable-arith-for-command
6027 Include support for the alternate form of the @code{for} command
6028 that behaves like the C language @code{for} statement
6029 (@pxref{Looping Constructs}).
6031 @item --enable-array-variables
6032 Include support for one-dimensional array shell variables
6035 @item --enable-bang-history
6036 Include support for @code{csh}-like history substitution
6037 (@pxref{History Interaction}).
6039 @item --enable-brace-expansion
6040 Include @code{csh}-like brace expansion
6041 ( @code{b@{a,b@}c} @expansion{} @code{bac bbc} ).
6042 See @ref{Brace Expansion}, for a complete description.
6044 @item --enable-command-timing
6045 Include support for recognizing @code{time} as a reserved word and for
6046 displaying timing statistics for the pipeline following @code{time}
6047 (@pxref{Pipelines}).
6048 This allows pipelines as well as shell builtins and functions to be timed.
6050 @item --enable-cond-command
6051 Include support for the @code{[[} conditional command
6052 (@pxref{Conditional Constructs}).
6054 @item --enable-directory-stack
6055 Include support for a @code{csh}-like directory stack and the
6056 @code{pushd}, @code{popd}, and @code{dirs} builtins
6057 (@pxref{The Directory Stack}).
6059 @item --enable-disabled-builtins
6060 Allow builtin commands to be invoked via @samp{builtin xxx}
6061 even after @code{xxx} has been disabled using @samp{enable -n xxx}.
6062 See @ref{Bash Builtins}, for details of the @code{builtin} and
6063 @code{enable} builtin commands.
6065 @item --enable-dparen-arithmetic
6066 Include support for the @code{((@dots{}))} command
6067 (@pxref{Conditional Constructs}).
6069 @item --enable-extended-glob
6070 Include support for the extended pattern matching features described
6071 above under @ref{Pattern Matching}.
6073 @item --enable-help-builtin
6074 Include the @code{help} builtin, which displays help on shell builtins and
6075 variables (@pxref{Bash Builtins}).
6077 @item --enable-history
6078 Include command history and the @code{fc} and @code{history}
6079 builtin commands (@pxref{Bash History Facilities}).
6081 @item --enable-job-control
6082 This enables the job control features (@pxref{Job Control}),
6083 if the operating system supports them.
6085 @item --enable-net-redirections
6086 This enables the special handling of filenames of the form
6087 @code{/dev/tcp/@var{host}/@var{port}} and
6088 @code{/dev/udp/@var{host}/@var{port}}
6089 when used in redirections (@pxref{Redirections}).
6091 @item --enable-process-substitution
6092 This enables process substitution (@pxref{Process Substitution}) if
6093 the operating system provides the necessary support.
6095 @item --enable-prompt-string-decoding
6096 Turn on the interpretation of a number of backslash-escaped characters
6097 in the @code{$PS1}, @code{$PS2}, @code{$PS3}, and @code{$PS4} prompt
6098 strings. See @ref{Printing a Prompt}, for a complete list of prompt
6099 string escape sequences.
6101 @item --enable-progcomp
6102 Enable the programmable completion facilities
6103 (@pxref{Programmable Completion}).
6104 If Readline is not enabled, this option has no effect.
6106 @item --enable-readline
6107 Include support for command-line editing and history with the Bash
6108 version of the Readline library (@pxref{Command Line Editing}).
6110 @item --enable-restricted
6111 Include support for a @dfn{restricted shell}. If this is enabled, Bash,
6112 when called as @code{rbash}, enters a restricted mode. See
6113 @ref{The Restricted Shell}, for a description of restricted mode.
6115 @item --enable-select
6116 Include the @code{select} builtin, which allows the generation of simple
6117 menus (@pxref{Conditional Constructs}).
6119 @item --enable-usg-echo-default
6120 A synonym for @code{--enable-xpg-echo-default}.
6122 @item --enable-xpg-echo-default
6123 Make the @code{echo} builtin expand backslash-escaped characters by default,
6124 without requiring the @samp{-e} option.
6125 This sets the default value of the @code{xpg_echo} shell option to @code{on},
6126 which makes the Bash @code{echo} behave more like the version specified in
6127 the Single Unix Specification, version 2.
6128 @xref{Bash Builtins}, for a description of the escape sequences that
6129 @code{echo} recognizes.
6133 The file @file{config-top.h} contains C Preprocessor
6134 @samp{#define} statements for options which are not settable from
6136 Some of these are not meant to be changed; beware of the consequences if
6138 Read the comments associated with each definition for more
6139 information about its effect.
6141 @node Reporting Bugs
6142 @appendix Reporting Bugs
6144 Please report all bugs you find in Bash.
6145 But first, you should
6146 make sure that it really is a bug, and that it appears in the latest
6147 version of Bash that you have.
6149 Once you have determined that a bug actually exists, use the
6150 @code{bashbug} command to submit a bug report.
6151 If you have a fix, you are encouraged to mail that as well!
6152 Suggestions and `philosophical' bug reports may be mailed
6153 to @email{bug-bash@@gnu.org} or posted to the Usenet
6154 newsgroup @code{gnu.bash.bug}.
6156 All bug reports should include:
6159 The version number of Bash.
6161 The hardware and operating system.
6163 The compiler used to compile Bash.
6165 A description of the bug behaviour.
6167 A short script or `recipe' which exercises the bug and may be used
6172 @code{bashbug} inserts the first three items automatically into
6173 the template it provides for filing a bug report.
6175 Please send all reports concerning this manual to
6176 @email{chet@@po.CWRU.Edu}.
6178 @node Major Differences From The Bourne Shell
6179 @appendix Major Differences From The Bourne Shell
6181 Bash implements essentially the same grammar, parameter and
6182 variable expansion, redirection, and quoting as the Bourne Shell.
6183 Bash uses the @sc{posix} 1003.2 standard as the specification of
6184 how these features are to be implemented. There are some
6185 differences between the traditional Bourne shell and Bash; this
6186 section quickly details the differences of significance. A
6187 number of these differences are explained in greater depth in
6189 This section uses the version of @code{sh} included SVR4.2 as
6190 the baseline reference.
6195 Bash is @sc{posix}-conformant, even where the @sc{posix} specification
6196 differs from traditional @code{sh} behavior.
6199 Bash has multi-character invocation options (@pxref{Invoking Bash}).
6202 Bash has command-line editing (@pxref{Command Line Editing}) and
6203 the @code{bind} builtin.
6206 Bash provides a programmable word completion mechanism
6207 (@pxref{Programmable Completion}), and two builtin commands,
6208 @code{complete} and @code{compgen}, to manipulate it.
6211 Bash has command history (@pxref{Bash History Facilities}) and the
6212 @code{history} and @code{fc} builtins to manipulate it.
6215 Bash implements @code{csh}-like history expansion
6216 (@pxref{History Interaction}).
6219 Bash has one-dimensional array variables (@pxref{Arrays}), and the
6220 appropriate variable expansions and assignment syntax to use them.
6221 Several of the Bash builtins take options to act on arrays.
6222 Bash provides a number of built-in array variables.
6225 The @code{$'@dots{}'} quoting syntax, which expands ANSI-C
6226 backslash-escaped characters in the text between the single quotes,
6227 is supported (@pxref{ANSI-C Quoting}).
6230 Bash supports the @code{$"@dots{}"} quoting syntax to do
6231 locale-specific translation of the characters between the double
6232 quotes. The @samp{-D}, @samp{--dump-strings}, and @samp{--dump-po-strings}
6233 invocation options list the translatable strings found in a script
6234 (@pxref{Locale Translation}).
6237 Bash implements the @code{!} keyword to negate the return value of
6238 a pipeline (@pxref{Pipelines}).
6239 Very useful when an @code{if} statement needs to act only if a test fails.
6242 Bash has the @code{time} reserved word and command timing (@pxref{Pipelines}).
6243 The display of the timing statistics may be controlled with the
6244 @code{TIMEFORMAT} variable.
6247 Bash implements the @code{for (( @var{expr1} ; @var{expr2} ; @var{expr3} ))}
6248 arithmetic for command, similar to the C language (@pxref{Looping Constructs}).
6251 Bash includes the @code{select} compound command, which allows the
6252 generation of simple menus (@pxref{Conditional Constructs}).
6255 Bash includes the @code{[[} compound command, which makes conditional
6256 testing part of the shell grammar (@pxref{Conditional Constructs}).
6259 Bash includes brace expansion (@pxref{Brace Expansion}) and tilde
6260 expansion (@pxref{Tilde Expansion}).
6263 Bash implements command aliases and the @code{alias} and @code{unalias}
6264 builtins (@pxref{Aliases}).
6267 Bash provides shell arithmetic, the @code{((} compound command
6268 (@pxref{Conditional Constructs}),
6269 and arithmetic expansion (@pxref{Shell Arithmetic}).
6272 Variables present in the shell's initial environment are automatically
6273 exported to child processes. The Bourne shell does not normally do
6274 this unless the variables are explicitly marked using the @code{export}
6278 Bash includes the @sc{posix} pattern removal @samp{%}, @samp{#}, @samp{%%}
6279 and @samp{##} expansions to remove leading or trailing substrings from
6280 variable values (@pxref{Shell Parameter Expansion}).
6283 The expansion @code{$@{#xx@}}, which returns the length of @code{$@{xx@}},
6284 is supported (@pxref{Shell Parameter Expansion}).
6287 The expansion @code{$@{var:}@var{offset}@code{[:}@var{length}@code{]@}},
6288 which expands to the substring of @code{var}'s value of length
6289 @var{length}, beginning at @var{offset}, is present
6290 (@pxref{Shell Parameter Expansion}).
6294 @code{$@{var/[/]}@var{pattern}@code{[/}@var{replacement}@code{]@}},
6295 which matches @var{pattern} and replaces it with @var{replacement} in
6296 the value of @code{var}, is available (@pxref{Shell Parameter Expansion}).
6299 The expansion @code{$@{!@var{prefix@}*}} expansion, which expands to
6300 the names of all shell variables whose names begin with @var{prefix},
6301 is available (@pxref{Shell Parameter Expansion}).
6304 Bash has @var{indirect} variable expansion using @code{$@{!word@}}
6305 (@pxref{Shell Parameter Expansion}).
6308 Bash can expand positional parameters beyond @code{$9} using
6309 @code{$@{@var{num}@}}.
6312 The @sc{posix} @code{$()} form of command substitution
6313 is implemented (@pxref{Command Substitution}),
6314 and preferred to the Bourne shell's @code{``} (which
6315 is also implemented for backwards compatibility).
6318 Bash has process substitution (@pxref{Process Substitution}).
6321 Bash automatically assigns variables that provide information about the
6322 current user (@code{UID}, @code{EUID}, and @code{GROUPS}), the current host
6323 (@code{HOSTTYPE}, @code{OSTYPE}, @code{MACHTYPE}, and @code{HOSTNAME}),
6324 and the instance of Bash that is running (@code{BASH},
6325 @code{BASH_VERSION}, and @code{BASH_VERSINFO}). @xref{Bash Variables},
6329 The @code{IFS} variable is used to split only the results of expansion,
6330 not all words (@pxref{Word Splitting}).
6331 This closes a longstanding shell security hole.
6334 Bash implements the full set of @sc{posix} 1003.2 filename expansion operators,
6335 including @var{character classes}, @var{equivalence classes}, and
6336 @var{collating symbols} (@pxref{Filename Expansion}).
6339 Bash implements extended pattern matching features when the @code{extglob}
6340 shell option is enabled (@pxref{Pattern Matching}).
6343 It is possible to have a variable and a function with the same name;
6344 @code{sh} does not separate the two name spaces.
6347 Bash functions are permitted to have local variables using the
6348 @code{local} builtin, and thus useful recursive functions may be written
6349 (@pxref{Bash Builtins}).
6352 Variable assignments preceding commands affect only that command, even
6353 builtins and functions (@pxref{Environment}).
6354 In @code{sh}, all variable assignments
6355 preceding commands are global unless the command is executed from the
6359 Bash performs filename expansion on filenames specified as operands
6360 to input and output redirection operators (@pxref{Redirections}).
6363 Bash contains the @samp{<>} redirection operator, allowing a file to be
6364 opened for both reading and writing, and the @samp{&>} redirection
6365 operator, for directing standard output and standard error to the same
6366 file (@pxref{Redirections}).
6369 Bash treats a number of filenames specially when they are
6370 used in redirection operators (@pxref{Redirections}).
6373 Bash can open network connections to arbitrary machines and services
6374 with the redirection operators (@pxref{Redirections}).
6377 The @code{noclobber} option is available to avoid overwriting existing
6378 files with output redirection (@pxref{The Set Builtin}).
6379 The @samp{>|} redirection operator may be used to override @code{noclobber}.
6382 The Bash @code{cd} and @code{pwd} builtins (@pxref{Bourne Shell Builtins})
6383 each take @samp{-L} and @samp{-P} builtins to switch between logical and
6387 Bash allows a function to override a builtin with the same name, and provides
6388 access to that builtin's functionality within the function via the
6389 @code{builtin} and @code{command} builtins (@pxref{Bash Builtins}).
6392 The @code{command} builtin allows selective disabling of functions
6393 when command lookup is performed (@pxref{Bash Builtins}).
6396 Individual builtins may be enabled or disabled using the @code{enable}
6397 builtin (@pxref{Bash Builtins}).
6400 The Bash @code{exec} builtin takes additional options that allow users
6401 to control the contents of the environment passed to the executed
6402 command, and what the zeroth argument to the command is to be
6403 (@pxref{Bourne Shell Builtins}).
6406 Shell functions may be exported to children via the environment
6407 using @code{export -f} (@pxref{Shell Functions}).
6410 The Bash @code{export}, @code{readonly}, and @code{declare} builtins can
6411 take a @samp{-f} option to act on shell functions, a @samp{-p} option to
6412 display variables with various attributes set in a format that can be
6413 used as shell input, a @samp{-n} option to remove various variable
6414 attributes, and @samp{name=value} arguments to set variable attributes
6415 and values simultaneously.
6418 The Bash @code{hash} builtin allows a name to be associated with
6419 an arbitrary filename, even when that filename cannot be found by
6420 searching the @code{$PATH}, using @samp{hash -p}
6421 (@pxref{Bourne Shell Builtins}).
6424 Bash includes a @code{help} builtin for quick reference to shell
6425 facilities (@pxref{Bash Builtins}).
6428 The @code{printf} builtin is available to display formatted output
6429 (@pxref{Bash Builtins}).
6432 The Bash @code{read} builtin (@pxref{Bash Builtins})
6433 will read a line ending in @samp{\} with
6434 the @samp{-r} option, and will use the @code{REPLY} variable as a
6435 default if no non-option arguments are supplied.
6436 The Bash @code{read} builtin
6437 also accepts a prompt string with the @samp{-p} option and will use
6438 Readline to obtain the line when given the @samp{-e} option.
6439 The @code{read} builtin also has additional options to control input:
6440 the @samp{-s} option will turn off echoing of input characters as
6441 they are read, the @samp{-t} option will allow @code{read} to time out
6442 if input does not arrive within a specified number of seconds, the
6443 @samp{-n} option will allow reading only a specified number of
6444 characters rather than a full line, and the @samp{-d} option will read
6445 until a particular character rather than newline.
6448 The @code{return} builtin may be used to abort execution of scripts
6449 executed with the @code{.} or @code{source} builtins
6450 (@pxref{Bourne Shell Builtins}).
6453 Bash includes the @code{shopt} builtin, for finer control of shell
6454 optional capabilities (@pxref{Bash Builtins}).
6457 Bash has much more optional behavior controllable with the @code{set}
6458 builtin (@pxref{The Set Builtin}).
6461 The @code{test} builtin (@pxref{Bourne Shell Builtins})
6462 is slightly different, as it implements the @sc{posix} algorithm,
6463 which specifies the behavior based on the number of arguments.
6466 The @code{trap} builtin (@pxref{Bourne Shell Builtins})
6467 allows a @code{DEBUG} pseudo-signal specification,
6468 similar to @code{EXIT}. Commands specified with a @code{DEBUG} trap are
6469 executed after every simple command. The @code{DEBUG} trap is not
6470 inherited by shell functions.
6473 The Bash @code{type} builtin is more extensive and gives more information
6474 about the names it finds (@pxref{Bash Builtins}).
6477 The Bash @code{umask} builtin permits a @samp{-p} option to cause
6478 the output to be displayed in the form of a @code{umask} command
6479 that may be reused as input (@pxref{Bourne Shell Builtins}).
6482 Bash implements a @code{csh}-like directory stack, and provides the
6483 @code{pushd}, @code{popd}, and @code{dirs} builtins to manipulate it
6484 (@pxref{The Directory Stack}).
6485 Bash also makes the directory stack visible as the value of the
6486 @code{DIRSTACK} shell variable.
6489 Bash interprets special backslash-escaped characters in the prompt
6490 strings when interactive (@pxref{Printing a Prompt}).
6493 The Bash restricted mode is more useful (@pxref{The Restricted Shell});
6494 the SVR4.2 shell restricted mode is too limited.
6497 The @code{disown} builtin can remove a job from the internal shell
6498 job table (@pxref{Job Control Builtins}) or suppress the sending
6499 of @code{SIGHUP} to a job when the shell exits as the result of a
6503 The SVR4.2 shell has two privilege-related builtins
6504 (@code{mldmode} and @code{priv}) not present in Bash.
6507 Bash does not have the @code{stop} or @code{newgrp} builtins.
6510 Bash does not use the @code{SHACCT} variable or perform shell accounting.
6513 The SVR4.2 @code{sh} uses a @code{TIMEOUT} variable like Bash uses
6519 More features unique to Bash may be found in @ref{Bash Features}.
6522 @appendixsec Implementation Differences From The SVR4.2 Shell
6524 Since Bash is a completely new implementation, it does not suffer from
6525 many of the limitations of the SVR4.2 shell. For instance:
6530 Bash does not fork a subshell when redirecting into or out of
6531 a shell control structure such as an @code{if} or @code{while}
6535 Bash does not allow unbalanced quotes. The SVR4.2 shell will silently
6536 insert a needed closing quote at @code{EOF} under certain circumstances.
6537 This can be the cause of some hard-to-find errors.
6540 The SVR4.2 shell uses a baroque memory management scheme based on
6541 trapping @code{SIGSEGV}. If the shell is started from a process with
6542 @code{SIGSEGV} blocked (e.g., by using the @code{system()} C library
6543 function call), it misbehaves badly.
6546 In a questionable attempt at security, the SVR4.2 shell,
6547 when invoked without the @samp{-p} option, will alter its real
6548 and effective @sc{uid} and @sc{gid} if they are less than some
6549 magic threshold value, commonly 100.
6550 This can lead to unexpected results.
6553 The SVR4.2 shell does not allow users to trap @code{SIGSEGV},
6554 @code{SIGALRM}, or @code{SIGCHLD}.
6557 The SVR4.2 shell does not allow the @code{IFS}, @code{MAILCHECK},
6558 @code{PATH}, @code{PS1}, or @code{PS2} variables to be unset.
6561 The SVR4.2 shell treats @samp{^} as the undocumented equivalent of
6565 Bash allows multiple option arguments when it is invoked (@code{-x -v});
6566 the SVR4.2 shell allows only one option argument (@code{-xv}). In
6567 fact, some versions of the shell dump core if the second argument begins
6571 The SVR4.2 shell exits a script if any builtin fails; Bash exits
6572 a script only if one of the @sc{posix} 1003.2 special builtins fails, and
6573 only for certain failures, as enumerated in the @sc{posix} 1003.2 standard.
6576 The SVR4.2 shell behaves differently when invoked as @code{jsh}
6577 (it turns on job control).
6581 @unnumbered Index of Shell Builtin Commands
6584 @node Reserved Word Index
6585 @unnumbered Index of Shell Reserved Words
6588 @node Variable Index
6589 @unnumbered Parameter and Variable Index
6592 @node Function Index
6593 @unnumbered Function Index
6597 @unnumbered Concept Index