1 \input texinfo.tex @c -*- texinfo -*-
3 @setfilename bashref.info
4 @settitle Bash Reference Manual
8 last change: Wed Mar 25 11:36:48 EST 1998
13 @set UPDATED 1 April 1998
14 @set UPDATE-MONTH April 1998
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, 1993, 1996, 1997 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{UPDATED}
69 @author Chet Ramey, Case Western Reserve University
70 @author Brian Fox, Free Software Foundation
72 @vskip 0pt plus 1filll
73 Copyright @copyright{} 1991, 1993, 1996 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 * Bourne Shell Features:: Features similar to those found in the
128 * Bash Features:: Features found only in Bash.
130 * Job Control:: A chapter describing what job control is
131 and how Bash allows you to use it.
133 * Using History Interactively:: Chapter dealing with history expansion
136 * Command Line Editing:: Chapter describing the command line
139 * Installing Bash:: How to build and install Bash on your system.
141 * Reporting Bugs:: How to report bugs in Bash.
143 * Builtin Index:: Index of Bash builtin commands.
145 * Reserved Word Index:: Index of Bash reserved words.
147 * Variable Index:: Quick reference helps you find the
150 * Function Index:: Index of bindable Readline functions.
152 * Concept Index:: General index for concepts described in
158 @chapter Introduction
160 * What is Bash?:: A short description of Bash.
162 * What is a shell?:: A brief introduction to shells.
166 @section What is Bash?
168 Bash is the shell, or command language interpreter,
169 that will appear in the @sc{GNU} operating system.
170 The name is an acronym for the @samp{Bourne-Again SHell},
171 a pun on Steve Bourne, the author of the direct ancestor of the current
172 Unix shell @code{/bin/sh},
173 which appeared in the Seventh Edition Bell Labs Research version
176 Bash is an @code{sh}-compatible shell that incorporates useful
177 features from the Korn shell @code{ksh} and the C shell @code{csh}.
178 It is intended to be a conformant implementation of the @sc{IEEE}
179 @sc{POSIX} Shell and Tools specification (@sc{IEEE} Working Group 1003.2).
180 It offers functional improvements over @code{sh} for both interactive and
183 While the @sc{GNU} operating system will include a version
184 of @code{csh}, Bash will be the default shell.
185 Like other @sc{GNU} software, Bash is quite portable. It currently runs
186 on nearly every version of Unix and a few other operating systems @minus{}
187 independently-supported ports exist for @sc{MS-DOS}, @sc{OS/2},
188 Windows @sc{95}, and Windows @sc{NT}.
190 @node What is a shell?
191 @section What is a shell?
193 At its base, a shell is simply a macro processor that executes
194 commands. A Unix shell is both a command interpreter, which
195 provides the user interface to the rich set of Unix utilities,
196 and a programming language, allowing these utilitites to be
197 combined. Files containing commands can be created, and become
198 commands themselves. These new commands have the same status as
199 system commands in directories like @file{/bin}, allowing users
200 or groups to establish custom environments.
202 A shell allows execution of Unix commands, both synchronously and
204 The shell waits for synchronous commands to complete before accepting
205 more input; asynchronous commands continue to execute in parallel
206 with the shell while it reads and executes additional commands.
207 The @dfn{redirection} constructs permit
208 fine-grained control of the input and output of those commands,
209 and the shell allows control over the contents of their
210 environment. Unix shells also provide a small set of built-in
211 commands (@dfn{builtins}) implementing functionality impossible
212 (e.g., @code{cd}, @code{break}, @code{continue}, and
213 @code{exec}), or inconvenient (@code{history}, @code{getopts},
214 @code{kill}, or @code{pwd}, for example) to obtain via separate
215 utilities. Shells may be used interactively or
216 non-interactively: they accept input typed from the keyboard or
217 from a file. All of the shell builtins are described in
220 While executing commands is essential, most of the power (and
221 complexity) of shells is due to their embedded programming
222 languages. Like any high-level language, the shell provides
223 variables, flow control constructs, quoting, and functions.
225 Shells have begun offering features geared specifically for
226 interactive use rather than to augment the programming language.
227 These interactive features include job control, command line
228 editing, history and aliases. Each of these features is
229 described in this manual.
233 These definitions are used throughout the remainder of this manual.
239 A family of open system standards based on Unix. Bash
240 is concerned with @sc{POSIX} 1003.2, the Shell and Tools Standard.
243 A space or tab character.
247 A command that is implemented internally by the shell itself, rather
248 than by an executable program somewhere in the file system.
250 @item control operator
251 @cindex control operator
252 A @code{word} that performs a control function. It is a @code{newline}
253 or one of the following:
254 @samp{||}, @samp{&&}, @samp{&}, @samp{;}, @samp{;;},
255 @samp{|}, @samp{(}, or @samp{)}.
259 The value returned by a command to its caller.
263 A unit of text that is the result of one of the shell expansions. After
264 expansion, when executing a command, the resulting fields are used as
265 the command name and arguments.
269 A string of characters used to identify a file.
273 A set of processes comprising a pipeline, and any processes descended
274 from it, that are all in the same process group.
278 A mechanism by which users can selectively stop (suspend) and restart
279 (resume) execution of processes.
282 @cindex metacharacter
283 A character that, when unquoted, separates words. A metacharacter is
284 a @code{blank} or one of the following characters:
285 @samp{|}, @samp{&}, @samp{;}, @samp{(}, @samp{)}, @samp{<}, or
291 A @code{word} consisting solely of letters, numbers, and underscores,
292 and beginning with a letter or underscore. @code{Name}s are used as
293 shell variable and function names.
294 Also referred to as an @code{identifier}.
297 @cindex operator, shell
298 A @code{control operator} or a @code{redirection operator}.
299 @xref{Redirections}, for a list of redirection operators.
302 @cindex process group
303 A collection of related processes each having the same process
306 @item process group ID
307 @cindex process group ID
308 A unique identifer that represents a @code{process group}
312 @cindex reserved word
313 A @code{word} that has a special meaning to the shell. Most reserved
314 words introduce shell flow control constructs, such as @code{for} and
318 @cindex return status
319 A synonym for @code{exit status}.
323 A mechanism by which a process may be notified by the kernal
324 of an event occurring in the system.
326 @item special builtin
327 @cindex special builtin
328 A shell builtin command that has been classified as special by the
329 @sc{POSIX.2} standard.
333 A sequence of characters considered a single unit by the shell. It is
334 either a @code{word} or an @code{operator}.
338 A @code{token} that is not an @code{operator}.
341 @node Basic Shell Features
342 @chapter Basic Shell Features
345 Bash is an acronym for @samp{Bourne-Again SHell}.
347 the traditional Unix shell originally written by Stephen Bourne.
348 All of the Bourne shell builtin commands are available in Bash,
349 and the rules for evaluation and quoting are taken from the @sc{POSIX}
350 1003.2 specification for the `standard' Unix shell.
352 This chapter briefly summarizes the shell's `building blocks':
353 commands, control structures, shell functions, shell @i{parameters},
355 @i{redirections}, which are a way to direct input and output from
356 and to named files, and how the shell executes commands.
359 * Shell Syntax:: What your input means to the shell.
360 * Shell Commands:: The types of commands you can use.
361 * Shell Functions:: Grouping commands by name.
362 * Shell Parameters:: Special shell variables.
363 * Shell Expansions:: How Bash expands variables and the various
364 expansions available.
365 * Redirections:: A way to control where input and output go.
366 * Executing Commands:: What happens when you run a command.
367 * Shell Scripts:: Executing files of shell commands.
371 @section Shell Syntax
373 * Shell Operation:: The basic operation of the shell.
375 * Quoting:: How to remove the special meaning from characters.
377 * Comments:: How to specify comments.
380 @node Shell Operation
381 @subsection Shell Operation
383 The following is a brief description of the shell's operation when it
384 reads and executes a command. Basically, the shell does the
389 Reads its input from a file (@pxref{Shell Scripts}), from a string
390 supplied as an argument to the @samp{-c} invocation option
391 (@pxref{Invoking Bash}), or from the user's terminal.
394 Breaks the input into words and operators, obeying the quoting rules
395 described in @ref{Quoting}. These tokens are separated by
396 @code{metacharacters}. Alias expansion is performed by this step
400 Parses the tokens into simple and compound commands
401 (@pxref{Shell Commands}).
404 Performs the various shell expansions (@pxref{Shell Expansions}), breaking
405 the expanded tokens into lists of filenames (@pxref{Filename Expansion})
406 and commands and arguments.
409 Performs any necessary redirections (@pxref{Redirections}) and removes
410 the redirection operators and their operands from the argument list.
413 Executes the command (@pxref{Executing Commands}).
416 Optionally waits for the command to complete and collects its exit
417 status (@pxref{Exit Status}).
425 * Escape Character:: How to remove the special meaning from a single
427 * Single Quotes:: How to inhibit all interpretation of a sequence
429 * Double Quotes:: How to suppress most of the interpretation of a
430 sequence of characters.
431 * ANSI-C Quoting:: How to expand ANSI-C sequences in quoted strings.
433 * Locale Translation:: How to translate strings into different languages.
436 Quoting is used to remove the special meaning of certain
437 characters or words to the shell. Quoting can be used to
438 disable special treatment for special characters, to prevent
439 reserved words from being recognized as such, and to prevent
442 Each of the shell metacharacters (@pxref{Definitions})
443 has special meaning to the shell and must be quoted if it is to
444 represent itself. There are three quoting mechanisms: the
445 @var{escape character}, single quotes, and double quotes.
447 @node Escape Character
448 @subsubsection Escape Character
449 A non-quoted backslash @samp{\} is the Bash escape character.
450 It preserves the literal value of the next character that follows,
451 with the exception of @code{newline}. If a @code{\newline} pair
452 appears, and the backslash itself is not quoted, the @code{\newline}
453 is treated as a line continuation (that is, it is removed from
454 the input stream and effectively ignored).
457 @subsubsection Single Quotes
459 Enclosing characters in single quotes preserves the literal value
460 of each character within the quotes. A single quote may not occur
461 between single quotes, even when preceded by a backslash.
464 @subsubsection Double Quotes
466 Enclosing characters in double quotes preserves the literal value
467 of all characters within the quotes, with the exception of
468 @samp{$}, @samp{`}, and @samp{\}.
469 The characters @samp{$} and @samp{`}
470 retain their special meaning within double quotes (@pxref{Shell Expansions}).
471 The backslash retains its special meaning only when followed by one of
472 the following characters:
473 @samp{$}, @samp{`}, @samp{"}, @samp{\}, or @code{newline}.
474 Within double quotes, backslashes that are followed by one of these
475 characters are removed. Backslashes preceding characters without a
476 special meaning are left unmodified.
477 A double quote may be quoted within double quotes by preceding it with
480 The special parameters @samp{*} and @samp{@@} have special meaning
481 when in double quotes (@pxref{Shell Parameter Expansion}).
484 @subsubsection ANSI-C Quoting
485 @cindex quoting, ANSI
487 Words of the form @code{$'@var{string}'} are treated specially. The
488 word expands to @var{string}, with backslash-escaped characters replaced
489 as specifed by the ANSI C standard. Backslash escape sequences, if
490 present, are decoded as follows:
498 an escape character (not ANSI C)
512 the character whose @code{ASCII} code is the octal value @var{nnn}
513 (one to three digits)
515 the character whose @code{ASCII} code is the hexadecimal value @var{nnn}
516 (one to three digits)
520 The result is single-quoted, as if the dollar sign had not been present.
522 @node Locale Translation
523 @subsubsection Locale-Specific Translation
526 A double-quoted string preceded by a dollar sign (@samp{$}) will cause
527 the string to be translated according to the current locale.
528 If the current locale is @code{C} or @code{POSIX}, the dollar sign
530 If the string is translated and replaced, the replacement is
535 @cindex comments, shell
537 In a non-interactive shell, or an interactive shell in which the
538 @code{interactive_comments} option to the @code{shopt}
539 builtin is enabled (@pxref{Bash Builtins}),
540 a word beginning with @samp{#}
541 causes that word and all remaining characters on that line to
542 be ignored. An interactive shell without the @code{interactive_comments}
543 option enabled does not allow comments. The @code{interactive_comments}
544 option is on by default in interactive shells.
545 @xref{Is This Shell Interactive?}, for a description of what makes
549 @section Shell Commands
550 @cindex commands, shell
552 * Simple Commands:: The most common type of command.
553 * Pipelines:: Connecting the input and output of several
555 * Lists:: How to execute commands sequentially.
556 * Looping Constructs:: Shell commands for iterative action.
557 * Conditional Constructs:: Shell commands for conditional execution.
558 * Command Grouping:: Ways to group commands.
561 @node Simple Commands
562 @subsection Simple Commands
563 @cindex commands, simple
565 A simple command is the kind of command encountered most often.
566 It's just a sequence of words separated by @code{blank}s, terminated
567 by one of the shell's control operators (@pxref{Definitions}). The
568 first word generally specifies a command to be executed.
570 The return status (@pxref{Exit Status}) of a simple command is
571 its exit status as provided
572 by the @sc{POSIX.1} @code{waitpid} function, or 128+@var{n} if the command
573 was terminated by signal @var{n}.
576 @subsection Pipelines
578 @cindex commands, pipelines
580 A @code{pipeline} is a sequence of simple commands separated by
585 @cindex command timing
586 The format for a pipeline is
588 [@code{time} [@code{-p}]] [@code{!}] @var{command1} [@code{|} @var{command2} @dots{}]
592 The output of each command in the pipeline is connected to the input of
593 the next command. That is, each command reads the previous command's
596 The reserved word @code{time} causes timing statistics
597 to be printed for the pipeline once it finishes.
598 The statistics currently consist of elapsed (wall-clock) time and
599 user and system time consumed by the command's execution.
600 The @samp{-p} option changes the output format to that specified
602 The @code{TIMEFORMAT} variable may be set to a format string that
603 specifies how the timing information should be displayed.
604 @xref{Bash Variables}, for a description of the available formats.
605 The use of @code{time} as a reserved word permits the timing of
606 shell builtins, shell functions, and pipelines. An external
607 @code{time} command cannot time these easily.
609 If the pipeline is not executed asynchronously (@pxref{Lists}), the
610 shell waits for all commands in the pipeline to complete.
612 Each command in a pipeline is executed in its own subshell
613 (@pxref{Command Execution Environment}). The exit
614 status of a pipeline is the exit status of the last command in the
615 pipeline. If the reserved word @samp{!} precedes the pipeline, the
616 exit status is the logical negation of the exit status of the last command.
619 @subsection Lists of Commands
620 @cindex commands, lists
622 A @code{list} is a sequence of one or more pipelines separated by one
623 of the operators @samp{;}, @samp{&}, @samp{&&}, or @samp{||},
624 and optionally terminated by one of @samp{;}, @samp{&}, or a
627 Of these list operators, @samp{&&} and @samp{||}
628 have equal precedence, followed by @samp{;} and @samp{&},
629 which have equal precedence.
631 If a command is terminated by the control operator @samp{&},
632 the shell executes the command asynchronously in a subshell.
633 This is known as executing the command in the @var{background}.
634 The shell does not wait for the command to finish, and the return
636 The standard input for asynchronous commands, in the absence of any
637 explicit redirections, is redirected from @code{/dev/null}.
639 Commands separated by a @samp{;} are executed sequentially; the shell
640 waits for each command to terminate in turn. The return status is the
641 exit status of the last command executed.
643 The control operators @samp{&&} and @samp{||}
644 denote @sc{AND} lists and @sc{OR} lists, respectively.
645 An @sc{AND} list has the form
647 @var{command} && @var{command2}
651 @var{command2} is executed if, and only if, @var{command}
652 returns an exit status of zero.
654 An @sc{OR} list has the form
656 @var{command} || @var{command2}
660 @var{command2} is executed if, and only if, @var{command}
661 returns a non-zero exit status.
664 @sc{AND} and @sc{OR} lists is the exit status of the last command
665 executed in the list.
667 @node Looping Constructs
668 @subsection Looping Constructs
669 @cindex commands, looping
671 Bash supports the following looping constructs.
673 Note that wherever you see a @samp{;} in the description of a
674 command's syntax, it may be replaced with one or more newlines.
681 The syntax of the @code{until} command is:
683 until @var{test-commands}; do @var{consequent-commands}; done
685 Execute @var{consequent-commands} as long as
686 @var{test-commands} has an exit status which is not zero.
687 The return status is the exit status of the last command executed
688 in @var{consequent-commands}, or zero if none was executed.
692 The syntax of the @code{while} command is:
694 while @var{test-commands}; do @var{consequent-commands}; done
697 Execute @var{consequent-commands} as long as
698 @var{test-commands} has an exit status of zero.
699 The return status is the exit status of the last command executed
700 in @var{consequent-commands}, or zero if none was executed.
704 The syntax of the @code{for} command is:
707 for @var{name} [in @var{words} @dots{}]; do @var{commands}; done
709 Expand @var{words}, and execute @var{commands} once for each member
710 in the resultant list, with @var{name} bound to the current member.
711 If @samp{in @var{words}} is not present, @samp{in "$@@"} is assumed.
712 The return status is the exit status of the last command that executes.
713 If there are no items in the expansion of @var{words}, no commands are
714 executed, and the return status is zero.
717 The @code{break} and @code{continue} builtins (@pxref{Bourne Shell Builtins})
718 may be used to control loop execution.
720 @node Conditional Constructs
721 @subsection Conditional Constructs
722 @cindex commands, conditional
731 The syntax of the @code{if} command is:
734 if @var{test-commands}; then
735 @var{consequent-commands};
736 [elif @var{more-test-commands}; then
737 @var{more-consequents};]
738 [else @var{alternate-consequents};]
742 The @var{test-commands} list is executed, and if its return status is zero,
743 the @var{consequent-commands} list is executed.
744 If @var{test-commands} returns a non-zero status, each @code{elif} list
745 is executed in turn, and if its exit status is zero,
746 the corresponding @var{more-consequents} is executed and the
748 If @samp{else @var{alternate-consequents}} is present, and
749 the final command in the final @code{if} or @code{elif} clause
750 has a non-zero exit status, then @var{alternate-consequents} is executed.
751 The return status is the exit status of the last command executed, or
752 zero if no condition tested true.
758 The syntax of the @code{case} command is:
761 @code{case @var{word} in [ [(] @var{pattern} [| @var{pattern}]@dots{}) @var{command-list} ;;]@dots{} esac}
764 @code{case} will selectively execute the @var{command-list} corresponding to
765 the first @var{pattern} that matches @var{word}.
766 The @samp{|} is used to separate multiple patterns, and the @samp{)}
767 operator terminates a pattern list.
768 A list of patterns and an associated command-list is known
769 as a @var{clause}. Each clause must be terminated with @samp{;;}.
770 The @var{word} undergoes tilde expansion, parameter expansion, command
771 substitution, arithmetic expansion, and quote removal before matching is
772 attempted. Each @var{pattern} undergoes tilde expansion, parameter
773 expansion, command substitution, and arithmetic expansion.
775 There may be an arbitrary number of @code{case} clauses, each terminated
776 by a @samp{;;}. The first pattern that matches determines the
777 command-list that is executed.
779 Here is an example using @code{case} in a script that could be used to
780 describe one interesting feature of an animal:
783 echo -n "Enter the name of an animal: "
785 echo -n "The $ANIMAL has "
787 horse | dog | cat) echo -n "four";;
788 man | kangaroo ) echo -n "two";;
789 *) echo -n "an unknown number of";;
795 The return status is zero if no @var{pattern} is matched. Otherwise, the
796 return status is the exit status of the @var{command-list} executed.
801 The @code{select} construct allows the easy generation of menus.
802 It has almost the same syntax as the @code{for} command:
805 select @var{name} [in @var{words} @dots{}]; do @var{commands}; done
808 The list of words following @code{in} is expanded, generating a list
809 of items. The set of expanded words is printed on the standard
810 error output stream, each preceded by a number. If the
811 @samp{in @var{words}} is omitted, the positional parameters are printed,
812 as if @samp{in "$@@"} had been specifed.
813 The @code{PS3} prompt is then displayed and a line is read from the
815 If the line consists of a number corresponding to one of the displayed
816 words, then the value of @var{name} is set to that word.
817 If the line is empty, the words and prompt are displayed again.
818 If @code{EOF} is read, the @code{select} command completes.
819 Any other value read causes @var{name} to be set to null.
820 The line read is saved in the variable @code{REPLY}.
822 The @var{commands} are executed after each selection until a
823 @code{break} or @code{return} command is executed, at which
824 point the @code{select} command completes.
826 Here is an example that allows the user to pick a filename from the
827 current directory, and displays the name and index of the file
833 echo you picked $fname \($REPLY\)
840 (( @var{expression} ))
843 The arithmetic @var{expression} is evaluated according to the rules
844 described below (@pxref{Shell Arithmetic}).
845 If the value of the expression is non-zero, the return status is 0;
846 otherwise the return status is 1. This is exactly equivalent to
848 let "@var{expression}"
851 @xref{Bash Builtins}, for a full description of the @code{let} builtin.
857 [[ @var{expression} ]]
860 Return a status of 0 or 1 depending on the evaluation of
861 the conditional expression @var{expression}.
862 Expressions are composed of the primaries described below in
863 @ref{Bash Conditional Expressions}.
864 Word splitting and filename expansion are not performed on the words
865 between the @samp{[[} and @samp{]]}; tilde expansion, parameter and
866 variable expansion, arithmetic expansion, command substitution, process
867 substitution, and quote removal are performed.
869 When the @samp{==} and @samp{!=} operators are used, the string to the
870 right of the operator is considered a pattern and matched according
871 to the rules described below in @ref{Pattern Matching}.
872 The return value is 0 if the string matches or does not match
873 the pattern, respectively, and 1 otherwise.
874 Any part of the pattern may be quoted to force it to be matched as a
877 Expressions may be combined using the following operators, listed
878 in decreasing order of precedence:
881 @item ( @var{expression} )
882 Returns the value of @var{expression}.
883 This may be used to override the normal precedence of operators.
885 @item ! @var{expression}
886 True if @var{expression} is false.
888 @item @var{expression1} && @var{expression2}
889 True if both @var{expression1} and @var{expression2} are true.
891 @item @var{expression1} || @var{expression2}
892 True if either @var{expression1} or @var{expression2} is true.
895 The && and || commands do not execute @var{expression2} if the
896 value of @var{expression1} is sufficient to determine the return
897 value of the entire conditional expression.
901 @node Command Grouping
902 @subsection Grouping Commands
903 @cindex commands, grouping
905 Bash provides two ways to group a list of commands to be executed
906 as a unit. When commands are grouped, redirections may be applied
907 to the entire command list. For example, the output of all the
908 commands in the list may be redirected to a single stream.
916 Placing a list of commands between parentheses causes a subshell
917 to be created, and each of the commands in @var{list} to be executed
918 in that subshell. Since the @var{list} is executed in a subshell,
919 variable assignments do not remain in effect after the subshell completes.
928 Placing a list of commands between curly braces causes the list to
929 be executed in the current shell context. No subshell is created.
930 The semicolon (or newline) following @var{list} is required.
933 In addition to the creation of a subshell, there is a subtle difference
934 between these two constructs due to historical reasons. The braces
935 are @code{reserved words}, so they must be separated from the @var{list}
936 by @code{blank}s. The parentheses are @code{operators}, and are
937 recognized as separate tokens by the shell even if they are not separated
938 from the @var{list} by whitespace.
940 The exit status of both of these constructs is the exit status of
943 @node Shell Functions
944 @section Shell Functions
945 @cindex shell function
946 @cindex functions, shell
948 Shell functions are a way to group commands for later execution
949 using a single name for the group. They are executed just like
950 a "regular" command. Shell functions are executed in the current
951 shell context; no new process is created to interpret them.
953 Functions are declared using this syntax:
956 [ @code{function} ] @var{name} () @{ @var{command-list}; @}
959 This defines a shell function named @var{name}. The reserved
960 word @code{function} is optional.
961 If the @code{function} reserved
962 word is supplied, the parentheses are optional.
963 The @var{body} of the function is the @var{command-list} between @{ and @}.
964 This list is executed whenever @var{name} is specified as the
965 name of a command. The exit status of a function is
966 the exit status of the last command executed in the body.
968 When a function is executed, the arguments to the
969 function become the positional parameters
970 during its execution (@pxref{Positional Parameters}).
971 The special parameter @samp{#} that expands to the number of
972 positional parameters is updated to reflect the change.
973 Positional parameter @code{0} is unchanged.
975 If the builtin command @code{return}
976 is executed in a function, the function completes and
977 execution resumes with the next command after the function
978 call. When a function completes, the values of the
979 positional parameters and the special parameter @samp{#}
980 are restored to the values they had prior to the function's
981 execution. If a numeric argument is given to @code{return},
982 that is the function's return status; otherwise the functions's
983 return status is the exit status of the last command executed
984 before the @code{return}.
986 Variables local to the function may be declared with the
987 @code{local} builtin. These variables are visible only to
988 the function and the commands it invokes.
990 Functions may be recursive. No limit is placed on the number of
993 @node Shell Parameters
994 @section Shell Parameters
996 @cindex variable, shell
997 @cindex shell variable
1000 * Positional Parameters:: The shell's command-line arguments.
1001 * Special Parameters:: Parameters with special meanings.
1004 A @var{parameter} is an entity that stores values.
1005 It can be a @code{name}, a number, or one of the special characters
1007 For the shell's purposes, a @var{variable} is a parameter denoted by a
1010 A parameter is set if it has been assigned a value. The null string is
1011 a valid value. Once a variable is set, it may be unset only by using
1012 the @code{unset} builtin command.
1014 A variable may be assigned to by a statement of the form
1016 @var{name}=[@var{value}]
1020 is not given, the variable is assigned the null string. All
1021 @var{value}s undergo tilde expansion, parameter and variable expansion,
1022 command substitution, arithmetic expansion, and quote
1023 removal (detailed below). If the variable has its @code{integer}
1024 attribute set (see the description of the @code{declare} builtin in
1025 @ref{Bash Builtins}), then @var{value}
1026 is subject to arithmetic expansion even if the @code{$((@dots{}))}
1027 expansion is not used (@pxref{Arithmetic Expansion}).
1028 Word splitting is not performed, with the exception
1029 of @code{"$@@"} as explained below.
1030 Filename expansion is not performed.
1032 @node Positional Parameters
1033 @subsection Positional Parameters
1034 @cindex parameters, positional
1036 A @var{positional parameter} is a parameter denoted by one or more
1037 digits, other than the single digit @code{0}. Positional parameters are
1038 assigned from the shell's arguments when it is invoked,
1039 and may be reassigned using the @code{set} builtin command.
1040 Positional parameter @code{N} may be referenced as @code{$@{N@}}.
1041 Positional parameters may not be assigned to
1042 with assignment statements. The positional parameters are
1043 temporarily replaced when a shell function is executed
1044 (@pxref{Shell Functions}).
1046 When a positional parameter consisting of more than a single
1047 digit is expanded, it must be enclosed in braces.
1049 @node Special Parameters
1050 @subsection Special Parameters
1051 @cindex parameters, special
1053 The shell treats several parameters specially. These parameters may
1054 only be referenced; assignment to them is not allowed.
1059 Expands to the positional parameters, starting from one. When the
1060 expansion occurs within double quotes, it expands to a single word
1061 with the value of each parameter separated by the first character
1063 special variable. That is, @code{"$*"} is equivalent
1064 to @code{"$1@var{c}$2@var{c}@dots{}"}, where @var{c}
1065 is the first character of the value of the @code{IFS}
1067 If @code{IFS} is unset, the parameters are separated by spaces.
1068 If @code{IFS} is null, the parameters are joined without intervening
1073 Expands to the positional parameters, starting from one. When the
1074 expansion occurs within double quotes, each parameter expands to a
1075 separate word. That is, @code{"$@@"} is equivalent to
1076 @code{"$1" "$2" @dots{}}.
1077 When there are no positional parameters, @code{"$@@"} and
1079 expand to nothing (i.e., they are removed).
1082 Expands to the number of positional parameters in decimal.
1085 Expands to the exit status of the most recently executed foreground
1089 Expands to the current option flags as specified upon invocation,
1091 builtin command, or those set by the shell itself
1092 (such as the @samp{-i} option).
1095 Expands to the process @sc{ID} of the shell. In a @code{()} subshell, it
1096 expands to the process @sc{ID} of the invoking shell, not the subshell.
1099 Expands to the process @sc{ID} of the most recently executed background
1100 (asynchronous) command.
1103 Expands to the name of the shell or shell script. This is set at
1104 shell initialization. If Bash is invoked with a file of commands
1105 (@pxref{Shell Scripts}), @code{$0} is set to the name of that file.
1106 If Bash is started with the @samp{-c} option (@pxref{Invoking Bash}),
1107 then @code{$0} is set to the first argument after the string to be
1108 executed, if one is present. Otherwise, it is set
1109 to the filename used to invoke Bash, as given by argument zero.
1112 At shell startup, set to the absolute filename of the shell or shell
1113 script being executed as passed in the argument list.
1114 Subsequently, expands to the last argument to the previous command,
1116 Also set to the full pathname of each command executed and placed in
1117 the environment exported to that command.
1118 When checking mail, this parameter holds the name of the mail file.
1121 @node Shell Expansions
1122 @section Shell Expansions
1125 Expansion is performed on the command line after it has been split into
1126 @code{token}s. There are seven kinds of expansion performed:
1128 @item brace expansion
1129 @item tilde expansion
1130 @item parameter and variable expansion
1131 @item command substitution
1132 @item arithmetic expansion
1133 @item word splitting
1134 @item filename expansion
1138 * Brace Expansion:: Expansion of expressions within braces.
1139 * Tilde Expansion:: Expansion of the ~ character.
1140 * Shell Parameter Expansion:: How Bash expands variables to their values.
1141 * Command Substitution:: Using the output of a command as an argument.
1142 * Arithmetic Expansion:: How to use arithmetic in shell expansions.
1143 * Process Substitution:: A way to write and read to and from a
1145 * Word Splitting:: How the results of expansion are split into separate
1147 * Filename Expansion:: A shorthand for specifying filenames matching patterns.
1148 * Quote Removal:: How and when quote characters are removed from
1152 The order of expansions is: brace expansion, tilde expansion,
1153 parameter, variable, and arithmetic expansion and
1154 command substitution
1155 (done in a left-to-right fashion), word splitting, and filename
1158 On systems that can support it, there is an additional expansion
1159 available: @var{process substitution}. This is performed at the
1160 same time as parameter, variable, and arithmetic expansion and
1161 command substitution.
1163 Only brace expansion, word splitting, and filename expansion
1164 can change the number of words of the expansion; other expansions
1165 expand a single word to a single word.
1166 The only exceptions to this are the expansions of
1167 @code{"$@@"} (@pxref{Special Parameters}) and @code{"$@{@var{name}[@@]@}"}
1170 After all expansions, @code{quote removal} (@pxref{Quote Removal})
1173 @node Brace Expansion
1174 @subsection Brace Expansion
1175 @cindex brace expansion
1176 @cindex expansion, brace
1179 is a mechanism by which arbitrary strings
1180 may be generated. This mechanism is similar to
1181 @var{filename expansion} (@pxref{Filename Expansion}),
1182 but the file names generated
1183 need not exist. Patterns to be brace expanded take
1184 the form of an optional @var{preamble},
1185 followed by a series of comma-separated strings
1186 between a pair of braces, followed by an optional @var{postscript}.
1187 The preamble is prepended to each string contained
1188 within the braces, and the postscript is then appended
1189 to each resulting string, expanding left to right.
1191 Brace expansions may be nested. The results of each expanded
1192 string are not sorted; left to right order is preserved.
1195 bash$ echo a@{d,c,b@}e
1199 Brace expansion is performed before any other expansions,
1200 and any characters special to other expansions are preserved
1201 in the result. It is strictly textual. Bash
1202 does not apply any syntactic interpretation to the context of the
1203 expansion or the text between the braces.
1205 A correctly-formed brace expansion must contain unquoted opening
1206 and closing braces, and at least one unquoted comma.
1207 Any incorrectly formed brace expansion is left unchanged.
1209 This construct is typically used as shorthand when the common
1210 prefix of the strings to be generated is longer than in the
1213 mkdir /usr/local/src/bash/@{old,new,dist,bugs@}
1217 chown root /usr/@{ucb/@{ex,edit@},lib/@{ex?.?*,how_ex@}@}
1220 @node Tilde Expansion
1221 @subsection Tilde Expansion
1222 @cindex tilde expansion
1223 @cindex expansion, tilde
1225 If a word begins with an unquoted tilde character (@samp{~}), all of the
1226 characters up to the first unquoted slash (or all characters,
1227 if there is no unquoted slash) are considered a @var{tilde-prefix}.
1228 If none of the characters in the tilde-prefix are quoted, the
1229 characters in the tilde-prefix following the tilde are treated as a
1230 possible @var{login name}.
1231 If this login name is the null string, the tilde is replaced with the
1232 value of the @code{HOME} shell variable.
1233 If @code{HOME} is unset, the home directory of the user executing the
1234 shell is substituted instead.
1235 Otherwise, the tilde-prefix is replaced with the home directory
1236 associated with the specified login name.
1238 If the tilde-prefix is @samp{~+}, the value of
1239 the shell variable @code{PWD} replaces the tilde-prefix.
1240 If the tilde-prefix is @samp{~-}, the value of the shell variable
1241 @code{OLDPWD}, if it is set, is substituted.
1243 If the characters following the tilde in the tilde-prefix consist of a
1244 number @var{N}, optionally prefixed by a @samp{+} or a @samp{-},
1245 the tilde-prefix is replaced with the
1246 corresponding element from the directory stack, as it would be displayed
1247 by the @code{dirs} builtin invoked with the characters following tilde
1248 in the tilde-prefix as an argument (@pxref{The Directory Stack}).
1249 If the tilde-prefix, sans the tilde, consists of a number without a
1250 leading @samp{+} or @samp{-}, @samp{+} is assumed.
1252 If the login name is invalid, or the tilde expansion fails, the word is
1255 Each variable assignment is checked for unquoted tilde-prefixes immediately
1256 following a @samp{:} or @samp{=}.
1257 In these cases, tilde expansion is also performed.
1258 Consequently, one may use file names with tildes in assignments to
1259 @code{PATH}, @code{MAILPATH}, and @code{CDPATH},
1260 and the shell assigns the expanded value.
1262 The following table shows how Bash treats unquoted tilde-prefixes:
1266 The value of @code{$HOME}
1271 The subdirectory @code{foo} of the home directory of the user
1278 @file{$@{OLDPWD-'~-'@}/foo}
1281 The string that would be displayed by @samp{dirs +@var{N}}
1284 The string that would be displayed by @samp{dirs +@var{N}}
1287 The string that would be displayed by @samp{dirs -@var{N}}
1291 @node Shell Parameter Expansion
1292 @subsection Shell Parameter Expansion
1293 @cindex parameter expansion
1294 @cindex expansion, parameter
1296 The @samp{$} character introduces parameter expansion,
1297 command substitution, or arithmetic expansion. The parameter name
1298 or symbol to be expanded may be enclosed in braces, which
1299 are optional but serve to protect the variable to be expanded from
1300 characters immediately following it which could be
1301 interpreted as part of the name.
1303 When braces are used, the matching ending brace is the first @samp{@}}
1304 not escaped by a backslash or within a quoted string, and not within an
1305 embedded arithmetic expansion, command substitution, or parameter
1308 The basic form of parameter expansion is $@{@var{parameter}@}.
1309 The value of @var{parameter} is substituted. The braces are required
1310 when @var{parameter}
1311 is a positional parameter with more than one digit,
1312 or when @var{parameter}
1313 is followed by a character that is not to be
1314 interpreted as part of its name.
1316 If the first character of @var{parameter} is an exclamation point,
1317 a level of variable indirection is introduced.
1318 Bash uses the value of the variable formed from the rest of
1319 @var{parameter} as the name of the variable; this variable is then
1320 expanded and that value is used in the rest of the substitution, rather
1321 than the value of @var{parameter} itself.
1322 This is known as @code{indirect expansion}.
1324 In each of the cases below, @var{word} is subject to tilde expansion,
1325 parameter expansion, command substitution, and arithmetic expansion.
1326 When not performing substring expansion, Bash tests for a parameter
1327 that is unset or null; omitting the colon results in a test only for a
1328 parameter that is unset.
1332 @item $@{@var{parameter}:@minus{}@var{word}@}
1333 If @var{parameter} is unset or null, the expansion of
1334 @var{word} is substituted. Otherwise, the value of
1335 @var{parameter} is substituted.
1337 @item $@{@var{parameter}:=@var{word}@}
1339 is unset or null, the expansion of @var{word}
1340 is assigned to @var{parameter}.
1341 The value of @var{parameter}
1342 is then substituted. Positional parameters and special parameters may
1343 not be assigned to in this way.
1345 @item $@{@var{parameter}:?@var{word}@}
1347 is null or unset, the expansion of @var{word} (or a message
1348 to that effect if @var{word}
1349 is not present) is written to the standard error and the shell, if it
1350 is not interactive, exits. Otherwise, the value of @var{parameter} is
1353 @item $@{@var{parameter}:+@var{word}@}
1355 is null or unset, nothing is substituted, otherwise the expansion of
1356 @var{word} is substituted.
1358 @item $@{@var{parameter}:@var{offset}@}
1359 @itemx $@{@var{parameter}:@var{offset}:@var{length}@}
1360 Expands to up to @var{length} characters of @var{parameter},
1361 starting at the character specified by @var{offset}.
1362 If @var{length} is omitted, expands to the substring of
1363 @var{parameter}, starting at the character specified by @var{offset}.
1364 @var{length} and @var{offset} are arithmetic expressions
1365 (@pxref{Shell Arithmetic}).
1366 This is referred to as Substring Expansion.
1368 @var{length} must evaluate to a number greater than or equal to zero.
1369 If @var{offset} evaluates to a number less than zero, the value
1370 is used as an offset from the end of the value of @var{parameter}.
1371 If @var{parameter} is @samp{@@}, the result is @var{length} positional
1372 parameters beginning at @var{offset}.
1373 If @var{parameter} is an array name indexed by @samp{@@} or @samp{*},
1374 the result is the @var{length}
1375 members of the array beginning with @code{$@{@var{parameter}[@var{offset}]@}}.
1376 Substring indexing is zero-based unless the positional parameters
1377 are used, in which case the indexing starts at 1.
1379 @item $@{#@var{parameter}@}
1380 The length in characters of the expanded value of @var{parameter} is
1382 If @var{parameter} is @samp{*} or @samp{@@}, the value substituted
1383 is the number of positional parameters.
1384 If @var{parameter} is an array name subscripted by @samp{*} or @samp{@@},
1385 the value substituted is the number of elements in the array.
1387 @item $@{@var{parameter}#@var{word}@}
1388 @itemx $@{@var{parameter}##@var{word}@}
1390 is expanded to produce a pattern just as in filename
1391 expansion (@pxref{Filename Expansion}). If the pattern matches
1392 the beginning of the expanded value of @var{parameter},
1393 then the result of the expansion is the expanded value of @var{parameter}
1394 with the shortest matching pattern (the @samp{#} case) or the
1395 longest matching pattern (the @samp{##} case) deleted.
1396 If @var{parameter} is @samp{@@} or @samp{*},
1397 the pattern removal operation is applied to each positional
1398 parameter in turn, and the expansion is the resultant list.
1399 If @var{parameter} is an array variable subscripted with
1400 @samp{@@} or @samp{*},
1401 the pattern removal operation is applied to each member of the
1402 array in turn, and the expansion is the resultant list.
1404 @item $@{@var{parameter}%@var{word}@}
1405 @itemx $@{@var{parameter}%%@var{word}@}
1406 The @var{word} is expanded to produce a pattern just as in
1408 If the pattern matches a trailing portion of the expanded value of
1409 @var{parameter}, then the result of the expansion is the value of
1410 @var{parameter} with the shortest matching pattern (the @samp{%} case)
1411 or the longest matching pattern (the @samp{%%} case) deleted.
1412 If @var{parameter} is @samp{@@} or @samp{*},
1413 the pattern removal operation is applied to each positional
1414 parameter in turn, and the expansion is the resultant list.
1416 is an array variable subscripted with @samp{@@} or @samp{*},
1417 the pattern removal operation is applied to each member of the
1418 array in turn, and the expansion is the resultant list.
1420 @item $@{@var{parameter}/@var{pattern}/@var{string}@}
1421 @itemx $@{@var{parameter}//@var{pattern}/@var{string}@}
1423 The @var{pattern} is expanded to produce a pattern just as in
1425 @var{Parameter} is expanded and the longest match of @var{pattern}
1426 against its value is replaced with @var{string}.
1427 In the first form, only the first match is replaced.
1428 The second form causes all matches of @var{pattern} to be
1429 replaced with @var{string}.
1430 If @var{pattern} begins with @samp{#}, it must match at the beginning
1432 If @var{pattern} begins with @samp{%}, it must match at the end
1434 If @var{string} is null, matches of @var{pattern} are deleted
1435 and the @code{/} following @var{pattern} may be omitted.
1436 If @var{parameter} is @samp{@@} or @samp{*},
1437 the substitution operation is applied to each positional
1438 parameter in turn, and the expansion is the resultant list.
1440 is an array variable subscripted with @samp{@@} or @samp{*},
1441 the substitution operation is applied to each member of the
1442 array in turn, and the expansion is the resultant list.
1446 @node Command Substitution
1447 @subsection Command Substitution
1448 @cindex command substitution
1450 Command substitution allows the output of a command to replace
1451 the command name. There are two forms:
1462 Bash performs the expansion by executing @var{command} and
1463 replacing the command substitution with the standard output of the
1464 command, with any trailing newlines deleted.
1465 Embedded newlines are not deleted, but they may be removed during
1467 The command substitution @code{$(cat @var{file})} can be
1468 replaced by the equivalent but faster @code{$(< @var{file})}.
1470 When the old-style backquote form of substitution is used,
1471 backslash retains its literal meaning except when followed by
1472 @samp{$}, @samp{`}, or @samp{\}.
1473 The first backquote not preceded by a backslash terminates the
1474 command substitution.
1475 When using the @code{$(@var{command})} form, all characters between
1476 the parentheses make up the command; none are treated specially.
1478 Command substitutions may be nested. To nest when using the backquoted
1479 form, escape the inner backquotes with backslashes.
1481 If the substitution appears within double quotes, word splitting and
1482 filename expansion are not performed on the results.
1484 @node Arithmetic Expansion
1485 @subsection Arithmetic Expansion
1486 @cindex expansion, arithmetic
1487 @cindex arithmetic expansion
1489 Arithmetic expansion allows the evaluation of an arithmetic expression
1490 and the substitution of the result. The format for arithmetic expansion is:
1493 $(( @var{expression} ))
1496 The expression is treated as if it were within double quotes, but
1497 a double quote inside the parentheses is not treated specially.
1498 All tokens in the expression undergo parameter expansion, command
1499 substitution, and quote removal.
1500 Arithmetic substitutions may be nested.
1502 The evaluation is performed according to the rules listed below
1503 (@pxref{Shell Arithmetic}).
1504 If the expression is invalid, Bash prints a message indicating
1505 failure to the standard error and no substitution occurs.
1507 @node Process Substitution
1508 @subsection Process Substitution
1509 @cindex process substitution
1511 Process substitution is supported on systems that support named
1512 pipes (@sc{FIFO}s) or the @file{/dev/fd} method of naming open files.
1513 It takes the form of
1523 The process @var{list} is run with its input or output connected to a
1524 @sc{FIFO} or some file in @file{/dev/fd}. The name of this file is
1525 passed as an argument to the current command as the result of the
1526 expansion. If the @code{>(@var{list})} form is used, writing to
1527 the file will provide input for @var{list}. If the
1528 @code{<(@var{list})} form is used, the file passed as an
1529 argument should be read to obtain the output of @var{list}.
1531 When available, process substitution is performed simultaneously with
1532 parameter and variable expansion, command substitution, and arithmetic
1535 @node Word Splitting
1536 @subsection Word Splitting
1537 @cindex word splitting
1539 The shell scans the results of parameter expansion, command substitution,
1540 and arithmetic expansion that did not occur within double quotes for
1543 The shell treats each character of @code{$IFS}
1544 as a delimiter, and splits the results of the other
1545 expansions into words on these characters. If
1546 @code{IFS} is unset, or its value is exactly @code{<space><tab><newline>},
1547 the default, then any sequence of @code{IFS}
1548 characters serves to delimit words. If @code{IFS}
1549 has a value other than the default, then sequences of
1550 the whitespace characters @code{space} and @code{tab}
1551 are ignored at the beginning and end of the
1552 word, as long as the whitespace character is in the
1553 value of @code{IFS} (an @code{IFS} whitespace character).
1554 Any character in @code{IFS} that is not @code{IFS}
1555 whitespace, along with any adjacent @code{IFS}
1556 whitespace characters, delimits a field. A sequence of @code{IFS}
1557 whitespace characters is also treated as a delimiter.
1558 If the value of @code{IFS} is null, no word splitting occurs.
1560 Explicit null arguments (@code{""} or @code{''}) are retained.
1561 Unquoted implicit null arguments, resulting from the expansion of
1563 that have no values, are removed.
1564 If a parameter with no value is expanded within double quotes, a
1565 null argument results and is retained.
1567 Note that if no expansion occurs, no splitting
1570 @node Filename Expansion
1571 @subsection Filename Expansion
1573 * Pattern Matching:: How the shell matches patterns.
1575 @cindex expansion, filename
1576 @cindex expansion, pathname
1577 @cindex filename expansion
1578 @cindex pathname expansion
1580 After word splitting, unless the @samp{-f} option has been set
1581 (@pxref{The Set Builtin}), Bash scans each word for the characters
1582 @samp{*}, @samp{?}, @samp{(}, and @samp{[}.
1583 If one of these characters appears, then the word is
1584 regarded as a @var{pattern},
1585 and replaced with an alphabetically sorted list of
1586 file names matching the pattern. If no matching file names are found,
1587 and the shell option @code{nullglob} is disabled, the word is left
1589 If the @code{nullglob} option is set, and no matches are found, the word
1591 If the shell option @code{nocaseglob} is enabled, the match is performed
1592 without regard to the case of alphabetic characters.
1594 When a pattern is used for filename generation, the character @samp{.}
1595 at the start of a filename or immediately following a slash
1596 must be matched explicitly, unless the shell option @code{dotglob} is set.
1597 When matching a file name, the slash character must always be
1599 In other cases, the @samp{.} character is not treated specially.
1601 See the description of @code{shopt} in @ref{Bash Builtins},
1602 for a description of the @code{nocaseglob}, @code{nullglob},
1603 and @code{dotglob} options.
1605 The @code{GLOBIGNORE}
1606 shell variable may be used to restrict the set of filenames matching a
1607 pattern. If @code{GLOBIGNORE}
1608 is set, each matching filename that also matches one of the patterns in
1609 @code{GLOBIGNORE} is removed from the list of matches. The filenames
1610 @file{.} and @file{..}
1611 are always ignored, even when @code{GLOBIGNORE}
1612 is set. However, setting @code{GLOBIGNORE} has the effect of
1613 enabling the @code{dotglob}
1614 shell option, so all other filenames beginning with a
1615 @samp{.} will match.
1616 To get the old behavior of ignoring filenames beginning with a
1617 @samp{.}, make @samp{.*} one of the patterns in @code{GLOBIGNORE}.
1618 The @code{dotglob} option is disabled when @code{GLOBIGNORE}
1621 @node Pattern Matching
1622 @subsubsection Pattern Matching
1623 @cindex pattern matching
1624 @cindex matching, pattern
1626 Any character that appears in a pattern, other than the special pattern
1627 characters described below, matches itself. The NUL character may not
1628 occur in a pattern. The special pattern characters must be quoted if
1629 they are to be matched literally.
1631 The special pattern characters have the following meanings:
1634 Matches any string, including the null string.
1636 Matches any single character.
1638 Matches any one of the enclosed characters. A pair of characters
1639 separated by a minus sign denotes a @var{range};
1640 any character lexically between those two characters, inclusive,
1641 is matched. If the first character following the
1642 @samp{[} is a @samp{!} or a @samp{^}
1643 then any character not enclosed is matched. A @samp{@minus{}}
1644 may be matched by including it as the first or last character
1645 in the set. A @samp{]} may be matched by including it as the first
1646 character in the set.
1648 Within @samp{[} and @samp{]}, @var{character classes} can be specified
1650 @code{[:}@var{class}@code{:]}, where @var{class} is one of the
1651 following classes defined in the @sc{POSIX.2} standard:
1653 alnum alpha ascii blank cntrl digit graph lower
1654 print punct space upper xdigit
1657 A character class matches any character belonging to that class.
1659 Within @samp{[} and @samp{]}, an @var{equivalence class} can be
1660 specified using the syntax @code{[=}@var{c}@code{=]}, which
1661 matches all characters with the same collation weight (as defined
1662 by the current locale) as the character @var{c}.
1664 Within @samp{[} and @samp{]}, the syntax @code{[.}@var{symbol}@code{.]}
1665 matches the collating symbol @var{symbol}.
1668 If the @code{extglob} shell option is enabled using the @code{shopt}
1669 builtin, several extended pattern matching operators are recognized.
1670 In the following description, a @var{pattern-list} is a list of one
1671 or more patterns separated by a @samp{|}.
1672 Composite patterns may be formed using one or more of the following
1676 @item ?(@var{pattern-list})
1677 Matches zero or one occurrence of the given patterns.
1679 @item *(@var{pattern-list})
1680 Matches zero or more occurrences of the given patterns.
1682 @item +(@var{pattern-list})
1683 Matches one or more occurrences of the given patterns.
1685 @item @@(@var{pattern-list})
1686 Matches exactly one of the given patterns.
1688 @item !(@var{pattern-list})
1689 Matches anything except one of the given patterns.
1693 @subsection Quote Removal
1695 After the preceding expansions, all unquoted occurrences of the
1696 characters @samp{\}, @samp{'}, and @samp{"} that did not
1697 result from one of the above expansions are removed.
1700 @section Redirections
1703 Before a command is executed, its input and output
1704 may be @var{redirected}
1705 using a special notation interpreted by the shell.
1706 Redirection may also be used to open and close files for the
1707 current shell execution environment. The following redirection
1708 operators may precede or appear anywhere within a
1709 simple command or may follow a command.
1710 Redirections are processed in the order they appear, from
1713 In the following descriptions, if the file descriptor number is
1714 omitted, and the first character of the redirection operator is
1715 @samp{<}, the redirection refers to the standard input (file
1716 descriptor 0). If the first character of the redirection operator
1717 is @samp{>}, the redirection refers to the standard output (file
1720 The word following the redirection operator in the following
1721 descriptions, unless otherwise noted, is subjected to brace expansion,
1722 tilde expansion, parameter expansion, command substitution, arithmetic
1723 expansion, quote removal, and filename expansion.
1724 If it expands to more than one word, Bash reports an error.
1726 Note that the order of redirections is significant. For example,
1729 ls > @var{dirlist} 2>&1
1732 directs both standard output and standard error to the file
1733 @var{dirlist}, while the command
1735 ls 2>&1 > @var{dirlist}
1738 directs only the standard output to file @var{dirlist},
1739 because the standard error was duplicated as standard output
1740 before the standard output was redirected to @var{dirlist}.
1742 A failure to open or create a file causes the redirection to fail.
1744 @subsection Redirecting Input
1745 Redirection of input causes the file whose name results from
1746 the expansion of @var{word}
1747 to be opened for reading on file descriptor @code{n},
1748 or the standard input (file descriptor 0) if @code{n}
1751 The general format for redirecting input is:
1756 @subsection Redirecting Output
1757 Redirection of output causes the file whose name results from
1758 the expansion of @var{word}
1759 to be opened for writing on file descriptor @code{n},
1760 or the standard output (file descriptor 1) if @code{n}
1761 is not specified. If the file does not exist it is created;
1762 if it does exist it is truncated to zero size.
1764 The general format for redirecting output is:
1769 If the redirection operator is @samp{>}, and the @code{noclobber}
1770 option to the @code{set} builtin has been enabled, the redirection
1771 will fail if the filename whose name results from the expansion of
1772 @var{word} exists and is a regular file.
1773 If the redirection operator is @samp{>|}, or the redirection operator is
1774 @samp{>} and the @code{noclobber} option is not enabled, the redirection
1775 is attempted even if the file named by @var{word} exists.
1777 @subsection Appending Redirected Output
1778 Redirection of output in this fashion
1779 causes the file whose name results from
1780 the expansion of @var{word}
1781 to be opened for appending on file descriptor @code{n},
1782 or the standard output (file descriptor 1) if @code{n}
1783 is not specified. If the file does not exist it is created.
1785 The general format for appending output is:
1790 @subsection Redirecting Standard Output and Standard Error
1791 Bash allows both the
1792 standard output (file descriptor 1) and
1793 the standard error output (file descriptor 2)
1794 to be redirected to the file whose name is the
1795 expansion of @var{word} with this construct.
1797 There are two formats for redirecting standard output and
1808 Of the two forms, the first is preferred.
1809 This is semantically equivalent to
1814 @subsection Here Documents
1815 This type of redirection instructs the shell to read input from the
1816 current source until a line containing only @var{word}
1817 (with no trailing blanks) is seen. All of
1818 the lines read up to that point are then used as the standard
1819 input for a command.
1821 The format of here-documents is as follows:
1823 <<[@minus{}]@var{word}
1828 No parameter expansion, command substitution, filename
1829 expansion, or arithmetic expansion is performed on
1830 @var{word}. If any characters in @var{word} are quoted, the
1831 @var{delimiter} is the result of quote removal on @var{word},
1832 and the lines in the here-document are not expanded.
1833 If @var{word} is unquoted,
1834 all lines of the here-document are subjected to parameter expansion,
1835 command substitution, and arithmetic expansion. In the latter
1836 case, the pair @code{\newline} is ignored, and @samp{\}
1837 must be used to quote the characters
1838 @samp{\}, @samp{$}, and @samp{`}.
1840 If the redirection operator is @samp{<<-},
1841 then all leading tab characters are stripped from input lines and the
1842 line containing @var{delimiter}.
1843 This allows here-documents within shell scripts to be indented in a
1846 @subsection Duplicating File Descriptors
1847 The redirection operator
1852 is used to duplicate input file descriptors.
1854 expands to one or more digits, the file descriptor denoted by @code{n}
1855 is made to be a copy of that file descriptor.
1856 If the digits in @var{word} do not specify a file descriptor open for
1857 input, a redirection error occurs.
1859 evaluates to @samp{-}, file descriptor @code{n} is closed. If
1860 @code{n} is not specified, the standard input (file descriptor 0) is used.
1867 is used similarly to duplicate output file descriptors. If
1869 is not specified, the standard output (file descriptor 1) is used.
1870 If the digits in @var{word} do not specify a file descriptor open for
1871 output, a redirection error occurs.
1872 As a special case, if @code{n} is omitted, and @var{word} does not
1873 expand to one or more digits, the standard output and standard
1874 error are redirected as described previously.
1876 @subsection Opening File Descriptors for Reading and Writing
1877 The redirection operator
1882 causes the file whose name is the expansion of @var{word}
1883 to be opened for both reading and writing on file descriptor
1884 @code{n}, or on file descriptor 0 if @code{n}
1885 is not specified. If the file does not exist, it is created.
1887 @node Executing Commands
1888 @section Executing Commands
1891 * Simple Command Expansion:: How Bash expands simple commands before
1894 * Command Search and Execution:: How Bash finds commands and runs them.
1896 * Command Execution Environment:: The environment in which Bash
1897 executes commands that are not
1900 * Environment:: The environment given to a command.
1902 * Exit Status:: The status returned by commands and how Bash
1905 * Signals:: What happens when Bash or a command it runs
1910 @node Simple Command Expansion
1911 @subsection Simple Command Expansion
1912 @cindex command expansion
1914 When a simple command is executed, the shell performs the following
1915 expansions, assignments, and redirections, from left to right.
1919 The words that the parser has marked as variable assignments (those
1920 preceding the command name) and redirections are saved for later
1924 The words that are not variable assignments or redirections are
1925 expanded (@pxref{Shell Expansions}).
1926 If any words remain after expansion, the first word
1927 is taken to be the name of the command and the remaining words are
1931 Redirections are performed as described above (@pxref{Redirections}).
1934 The text after the @samp{=} in each variable assignment undergoes tilde
1935 expansion, parameter expansion, command substitution, arithmetic expansion,
1936 and quote removal before being assigned to the variable.
1939 If no command name results, the variable assignments affect the current
1940 shell environment. Otherwise, the variables are added to the environment
1941 of the executed command and do not affect the current shell environment.
1942 If any of the assignments attempts to assign a value to a readonly variable,
1943 an error occurs, and the command exits with a non-zero status.
1945 If no command name results, redirections are performed, but do not
1946 affect the current shell environment. A redirection error causes the
1947 command to exit with a non-zero status.
1949 If there is a command name left after expansion, execution proceeds as
1950 described below. Otherwise, the command exits. If one of the expansions
1951 contained a command substitution, the exit status of the command is
1952 the exit status of the last command substitution performed. If there
1953 were no command substitutions, the command exits with a status of zero.
1955 @node Command Search and Execution
1956 @subsection Command Search and Execution
1957 @cindex command execution
1958 @cindex command search
1960 After a command has been split into words, if it results in a
1961 simple command and an optional list of arguments, the following
1966 If the command name contains no slashes, the shell attempts to
1967 locate it. If there exists a shell function by that name, that
1968 function is invoked as described above in @ref{Shell Functions}.
1971 If the name does not match a function, the shell searches for
1972 it in the list of shell builtins. If a match is found, that
1976 If the name is neither a shell function nor a builtin,
1977 and contains no slashes, Bash searches each element of
1978 @code{$PATH} for a directory containing an executable file
1979 by that name. Bash uses a hash table to remember the full
1980 pathnames of executable files to avoid multiple @code{PATH} searches
1981 (see the description of @code{hash} in @ref{Bourne Shell Builtins}).
1982 A full search of the directories in @code{$PATH}
1983 is performed only if the command is not found in the hash table.
1984 If the search is unsuccessful, the shell prints an error
1985 message and returns an exit status of 127.
1988 If the search is successful, or if the command name contains
1989 one or more slashes, the shell executes the named program in
1990 a separate execution environment.
1991 Argument 0 is set to the name given, and the remaining arguments
1992 to the command are set to the arguments supplied, if any.
1995 If this execution fails because the file is not in executable
1996 format, and the file is not a directory, it is assumed to be a
1997 @var{shell script} and the shell executes it as described in
1998 @ref{Shell Scripts}.
2001 If the command was not begun asynchronously, the shell waits for
2002 the command to complete and collects its exit status.
2006 @node Command Execution Environment
2007 @subsection Command Execution Environment
2008 @cindex execution environment
2010 The shell has an @var{execution environment}, which consists of the
2015 open files inherited by the shell at invocation, as modified by
2016 redirections supplied to the @code{exec} builtin
2019 the current working directory as set by @code{cd}, @code{pushd}, or
2020 @code{popd}, or inherited by the shell at invocation
2023 the file creation mode mask as set by @code{umask} or inherited from
2027 current traps set by @code{trap}
2030 shell parameters that are set by variable assignment or with @code{set}
2031 or inherited from the shell's parent in the environment
2034 shell functions defined during execution or inherited from the shell's
2035 parent in the environment
2038 options enabled at invocation (either by default or with command-line
2039 arguments) or by @code{set}
2042 options enabled by @code{shopt}
2045 shell aliases defined with @code{alias} (@pxref{Aliases})
2048 various process IDs, including those of background jobs
2049 (@pxref{Lists}), the value of @code{$$}, and the value of
2054 When a simple command other than a builtin or shell function
2055 is to be executed, it
2056 is invoked in a separate execution environment that consists of
2057 the following. Unless otherwise noted, the values are inherited
2062 the shell's open files, plus any modifications and additions specified
2063 by redirections to the command
2066 the current working directory
2069 the file creation mode mask
2072 shell variables marked for export, along with variables exported for
2073 the command, passed in the environment (@pxref{Environment})
2076 traps caught by the shell are reset to the values inherited from the
2077 shell's parent, and traps ignored by the shell are ignored
2081 A command invoked in this separate environment cannot affect the
2082 shell's execution environment.
2084 Command substitution and asynchronous commands are invoked in a
2085 subshell environment that is a duplicate of the shell environment,
2086 except that traps caught by the shell are reset to the values
2087 that the shell inherited from its parent at invocation. Builtin
2088 commands that are invoked as part of a pipeline are also executed
2089 in a subshell environment. Changes made to the subshell environment
2090 cannot affect the shell's execution environment.
2093 @subsection Environment
2096 When a program is invoked it is given an array of strings
2097 called the @var{environment}.
2098 This is a list of name-value pairs, of the form @code{name=value}.
2100 Bash allows you to manipulate the environment in several
2101 ways. On invocation, the shell scans its own environment and
2102 creates a parameter for each name found, automatically marking
2104 to child processes. Executed commands inherit the environment.
2105 The @code{export} and @samp{declare -x}
2106 commands allow parameters and functions to be added to and
2107 deleted from the environment. If the value of a parameter
2108 in the environment is modified, the new value becomes part
2109 of the environment, replacing the old. The environment
2110 inherited by any executed command consists of the shell's
2111 initial environment, whose values may be modified in the shell,
2112 less any pairs removed by the @code{unset} and @samp{export -n}
2113 commands, plus any additions via the @code{export} and
2114 @samp{declare -x} commands.
2116 The environment for any simple command
2117 or function may be augmented temporarily by prefixing it with
2118 parameter assignments, as described in @ref{Shell Parameters}.
2119 These assignment statements affect only the environment seen
2122 If the @samp{-k} option is set (@pxref{The Set Builtin}), then all
2123 parameter assignments are placed in the environment for a command,
2124 not just those that precede the command name.
2126 When Bash invokes an external command, the variable @samp{$_}
2127 is set to the full path name of the command and passed to that
2128 command in its environment.
2131 @subsection Exit Status
2134 For the shell's purposes, a command which exits with a
2135 zero exit status has succeeded.
2136 A non-zero exit status indicates failure.
2137 This seemingly counter-intuitive scheme is used so there
2138 is one well-defined way to indicate success and a variety of
2139 ways to indicate various failure modes.
2140 When a command terminates on a fatal signal whose number is @var{n},
2141 Bash uses the value 128+@var{n} as the exit status.
2143 If a command is not found, the child process created to
2144 execute it returns a status of 127. If a command is found
2145 but is not executable, the return status is 126.
2147 If a command fails because of an error during expansion or redirection,
2148 the exit status is greater than zero.
2150 The exit status is used by the Bash conditional commands
2151 (@pxref{Conditional Constructs}) and some of the list
2152 constructs (@pxref{Lists}).
2154 All of the Bash builtins return an exit status of zero if they succeed
2155 and a non-zero status on failure, so they may be used by the
2156 conditional and list constructs.
2157 All builtins return an exit status of 2 to indicate incorrect usage.
2161 @cindex signal handling
2163 When Bash is interactive, in the absence of any traps, it ignores
2164 @code{SIGTERM} (so that @samp{kill 0} does not kill an interactive shell),
2166 is caught and handled (so that the @code{wait} builtin is interruptible).
2167 When Bash receives a @code{SIGINT}, it breaks out of any executing loops.
2168 In all cases, Bash ignores @code{SIGQUIT}.
2169 If job control is in effect (@pxref{Job Control}), Bash
2170 ignores @code{SIGTTIN}, @code{SIGTTOU}, and @code{SIGTSTP}.
2172 Commands started by Bash have signal handlers set to the
2173 values inherited by the shell from its parent.
2174 When job control is not in effect, asynchronous commands
2175 ignore @code{SIGINT} and @code{SIGQUIT} as well.
2176 Commands run as a result of
2177 command substitution ignore the keyboard-generated job control signals
2178 @code{SIGTTIN}, @code{SIGTTOU}, and @code{SIGTSTP}.
2180 The shell exits by default upon receipt of a @code{SIGHUP}.
2181 Before exiting, it resends the @code{SIGHUP} to all jobs, running
2183 Stopped jobs are sent @code{SIGCONT} to ensure that they receive
2185 To prevent the shell from sending the @code{SIGHUP} signal to a
2186 particular job, it should be removed
2187 from the jobs table with the @code{disown}
2188 builtin (@pxref{Job Control Builtins}) or marked
2189 to not receive @code{SIGHUP} using @code{disown -h}.
2191 If the @code{huponexit} shell option has been set with @code{shopt}
2192 (@pxref{Bash Builtins}), Bash sends a @code{SIGHUP} to all jobs when
2193 an interactive login shell exits.
2195 When Bash receives a signal for which a trap has been set while waiting
2196 for a command to complete, the trap will not be executed until the
2198 When Bash is waiting for an asynchronous
2199 command via the @code{wait} builtin, the reception of a signal for
2200 which a trap has been set will cause the @code{wait} builtin to return
2201 immediately with an exit status greater than 128, immediately after
2202 which the trap is executed.
2205 @section Shell Scripts
2206 @cindex shell script
2208 A shell script is a text file containing shell commands. When such
2209 a file is used as the first non-option argument when invoking Bash,
2210 and neither the @samp{-c} nor @samp{-s} option is supplied
2211 (@pxref{Invoking Bash}),
2212 Bash reads and executes commands from the file, then exits. This
2213 mode of operation creates a non-interactive shell. When Bash runs
2214 a shell script, it sets the special parameter @code{0} to the name
2215 of the file, rather than the name of the shell, and the positional
2216 parameters are set to the remaining arguments, if any are given.
2217 If no additional arguments are supplied, the positional parameters
2220 A shell script may be made executable by using the @code{chmod} command
2221 to turn on the execute bit. When Bash finds such a file while
2222 searching the @code{$PATH} for a command, it spawns a subshell to
2223 execute it. In other words, executing
2225 filename @var{arguments}
2228 is equivalent to executing
2230 bash filename @var{arguments}
2234 if @code{filename} is an executable shell script.
2235 This subshell reinitializes itself, so that the effect is as if a
2236 new shell had been invoked to interpret the script, with the
2237 exception that the locations of commands remembered by the parent
2238 (see the description of @code{hash} in @ref{Bourne Shell Builtins})
2239 are retained by the child.
2241 Most versions of Unix make this a part of the kernel's command
2242 execution mechanism. If the first line of a script begins with
2243 the two characters @samp{#!}, the remainder of the line specifies
2244 an interpreter for the program. The arguments to the interpreter
2245 consist of a single optional argument following the interpreter
2246 name on the first line of the script file, followed by the name of
2247 the script file, followed by the rest of the arguments. Bash
2248 will perform this action on operating systems that do not handle it
2249 themselves. Note that some older versions of Unix limit the interpreter
2250 name and argument to a maximum of 32 characters.
2252 @node Bourne Shell Features
2253 @chapter Bourne Shell Style Features
2256 * Bourne Shell Builtins:: Builtin commands inherited from the Bourne
2258 * Bourne Shell Variables:: Variables which Bash uses in the same way
2259 as the Bourne Shell.
2260 * Other Bourne Shell Features:: Addtional aspects of Bash which behave in
2261 the same way as the Bourne Shell.
2264 This section briefly summarizes things which Bash inherits from
2265 the Bourne Shell: builtins, variables, and other features.
2266 It also lists the significant differences between Bash and the Bourne Shell.
2267 Many of the builtins have been extended by @sc{POSIX} or Bash.
2269 @node Bourne Shell Builtins
2270 @section Bourne Shell Builtins
2272 The following shell builtin commands are inherited from the Bourne
2273 Shell. These commands are implemented as specified by the @sc{POSIX}
2282 Do nothing beyond expanding @var{arguments} and performing redirections.
2283 The return status is zero.
2290 Read and execute commands from the @var{filename} argument in the
2291 current shell context. If @var{filename} does not contain a slash,
2292 the @code{$PATH} variable is used to find
2293 @var{filename}. The current directory is searched if @var{filename}
2294 is not found in @code{$PATH}.
2295 The return status is the exit status of the last command executed, or
2296 zero if no commands are executed. If @var{filename} is not found, or
2297 cannot be read, the return status is non-zero.
2304 Exit from a @code{for}, @code{while}, @code{until}, or @code{select} loop.
2305 If @var{n} is supplied, the @var{n}th enclosing loop is exited.
2306 @var{n} must be greater than or equal to 1.
2307 The return status is zero unless @var{n} is not greater than or equal to 1.
2312 cd [-LP] [@var{directory}]
2314 Change the current working directory to @var{directory}. If @var{directory}
2315 is not given, the value of the @code{HOME} shell variable is used. If the
2316 shell variable @code{CDPATH} exists, it is used as a search path. If
2317 @var{directory} begins with a slash, @code{CDPATH} is not used.
2318 The @samp{-P} option means
2319 to not follow symbolic links; symbolic links are followed by default
2320 or with the @samp{-L} option.
2321 If @var{directory} is @samp{-}, it is equivalent to @code{$OLDPWD}.
2322 The return status is zero if the directory is successfully changed,
2330 Resume the next iteration of an enclosing @code{for}, @code{while},
2331 @code{until}, or @code{select} loop.
2332 If @var{n} is supplied, the execution of the @var{n}th enclosing loop
2334 @var{n} must be greater than or equal to 1.
2335 The return status is zero unless @var{n} is not greater than or equal to 1.
2340 eval [@var{arguments}]
2342 The arguments are concatenated together into a single command, which is
2343 then read and executed, and its exit status returned as the exit status
2345 If there are no arguments or only empty arguments, the return status is
2351 exec [-cl] [-a @var{name}] [@var{command} [@var{arguments}]]
2354 is supplied, it replaces the shell without creating a new process.
2355 If the @samp{-l} option is supplied, the shell places a dash in the
2356 zeroth arg passed to @var{command}.
2357 This is what the @code{login} program does.
2358 The @samp{-c} option causes @var{command} to be executed with an empty
2360 If @samp{-a} is supplied, the shell passes @var{name} as the zeroth
2361 argument to @var{command}.
2362 If no @var{command} is specified, redirections may be used to affect
2363 the current shell environment. If there are no redirection errors, the
2364 return status is zero; otherwise the return status is non-zero.
2371 Exit the shell, returning a status of @var{n} to the shell's parent.
2372 Any trap on @code{EXIT} is executed before the shell terminates.
2377 export [-fn] [-p] [@var{name}[=@var{value}]]
2379 Mark each @var{name} to be passed to child processes
2380 in the environment. If the @samp{-f} option is supplied, the @var{name}s
2381 refer to shell functions; otherwise the names refer to shell variables.
2382 The @samp{-n} option means to no longer mark each @var{name} for export.
2383 If no @var{names} are supplied, or if the @samp{-p} option is given, a
2384 list of exported names is displayed.
2385 The @samp{-p} option displays output in a form that may be reused as input.
2386 The return status is zero unless an invalid option is supplied, one of
2387 the names is not a valid shell variable name, or @samp{-f} is supplied
2388 with a name that is not a shell function.
2393 getopts @var{optstring} @var{name} [@var{args}]
2395 @code{getopts} is used by shell scripts to parse positional parameters.
2396 @var{optstring} contains the option letters to be recognized; if a letter
2397 is followed by a colon, the option is expected to have an
2398 argument, which should be separated from it by white space.
2399 Each time it is invoked, @code{getopts}
2400 places the next option in the shell variable @var{name}, initializing
2401 @var{name} if it does not exist,
2402 and the index of the next argument to be processed into the
2403 variable @code{OPTIND}.
2404 @code{OPTIND} is initialized to 1 each time the shell or a shell script
2406 When an option requires an argument,
2407 @code{getopts} places that argument into the variable @code{OPTARG}.
2408 The shell does not reset @code{OPTIND} automatically; it must be manually
2409 reset between multiple calls to @code{getopts} within the same shell
2410 invocation if a new set of parameters is to be used.
2412 When the end of options is encountered, @code{getopts} exits with a
2413 return value greater than zero.
2414 @code{OPTIND} is set to the index of the first non-option argument,
2415 and @code{name} is set to @samp{?}.
2418 normally parses the positional parameters, but if more arguments are
2419 given in @var{args}, @code{getopts} parses those instead.
2421 @code{getopts} can report errors in two ways. If the first character of
2422 @var{optstring} is a colon, @var{silent}
2423 error reporting is used. In normal operation diagnostic messages
2424 are printed when invalid options or missing option arguments are
2426 If the variable @code{OPTERR}
2427 is set to 0, no error messages will be displayed, even if the first
2428 character of @code{optstring} is not a colon.
2430 If an invalid option is seen,
2431 @code{getopts} places @samp{?} into @var{name} and, if not silent,
2432 prints an error message and unsets @code{OPTARG}.
2433 If @code{getopts} is silent, the option character found is placed in
2434 @code{OPTARG} and no diagnostic message is printed.
2436 If a required argument is not found, and @code{getopts}
2437 is not silent, a question mark (@samp{?}) is placed in @var{name},
2438 @code{OPTARG} is unset, and a diagnostic message is printed.
2439 If @code{getopts} is silent, then a colon (@samp{:}) is placed in
2440 @var{name} and @code{OPTARG} is set to the option character found.
2445 hash [-r] [-p @var{filename}] [@var{name}]
2447 Remember the full pathnames of commands specified as @var{name} arguments,
2448 so they need not be searched for on subsequent invocations.
2449 The commands are found by searching through the directories listed in
2451 The @samp{-p} option inhibits the path search, and @var{filename} is
2452 used as the location of @var{name}.
2453 The @samp{-r} option causes the shell to forget all remembered locations.
2454 If no arguments are given, information about remembered commands is printed.
2455 The return status is zero unless a @var{name} is not found or an invalid
2463 Print the current working directory.
2464 If the @samp{-P} option is supplied, the path printed will not
2465 contain symbolic links.
2466 If the @samp{-L} option is supplied, the path printed may contain
2468 The return status is zero unless an error is encountered while
2469 determining the name of the current directory or an invalid option
2475 readonly [-apf] [@var{name}] @dots{}
2477 Mark each @var{name} as readonly.
2478 The values of these names may not be changed by subsequent assignment.
2479 If the @samp{-f} option is supplied, each @var{name} refers to a shell
2481 The @samp{-a} option means each @var{name} refers to an array variable.
2482 If no @var{name} arguments are given, or if the @samp{-p}
2483 option is supplied, a list of all readonly names is printed.
2484 The @samp{-p} option causes output to be displayed in a format that
2485 may be reused as input.
2486 The return status is zero unless an invalid option is supplied, one of
2487 the @var{name} arguments is not a valid shell variable or function name,
2488 or the @samp{-f} option is supplied with a name that is not a shell function.
2495 Cause a shell function to exit with the return value @var{n}.
2496 This may also be used to terminate execution of a script being executed
2497 with the @code{.} builtin, returning either @var{n} or the exit status
2498 of the last command executed within the script as the exit status of the
2500 The return status is false if @code{return} is used outside a function
2501 and not during the execution of a script by @samp{.}.
2508 Shift the positional parameters to the left by @var{n}.
2509 The positional parameters from @var{n}+1 @dots{} @code{$#} are
2510 renamed to @code{$1} @dots{} @code{$#}-@var{n}+1.
2511 Parameters represented by the numbers @code{$#} to @var{n}+1 are unset.
2512 @var{n} must be a non-negative number less than or equal to @code{$#}.
2513 If @var{n} is zero or greater than @code{$#}, the positional parameters
2515 The return status is zero unless @var{n} is greater than @code{$#} or
2516 less than zero, non-zero otherwise.
2522 Evaluate a conditional expression @var{expr}.
2523 Each operator and operand must be a separate argument.
2524 Expressions are composed of the primaries described below in
2525 @ref{Bash Conditional Expressions}.
2527 Expressions may be combined using the following operators, listed in
2528 decreasing order of precedence.
2532 True if @var{expr} is false.
2534 @item ( @var{expr} )
2535 Returns the value of @var{expr}.
2536 This may be used to override the normal precedence of operators.
2538 @item @var{expr1} -a @var{expr2}
2539 True if both @var{expr1} and @var{expr2} are true.
2541 @item @var{expr1} -o @var{expr2}
2542 True if either @var{expr1} or @var{expr2} is true.
2545 The @code{test} and @code{[} builtins evaluate conditional
2546 expressions using a set of rules based on the number of arguments.
2550 The expression is false.
2553 The expression is true if and only if the argument is not null.
2556 If the first argument is @samp{!}, the expression is true if and
2557 only if the second argument is null.
2558 If the first argument is one of the unary conditional operators
2559 (@pxref{Bash Conditional Expressions}), the expression
2560 is true if the unary test is true.
2561 If the first argument is not a valid unary operator, the expression is
2565 If the second argument is one of the binary conditional
2566 operators (@pxref{Bash Conditional Expressions}), the
2567 result of the expression is the result of the binary test using the
2568 first and third arguments as operands.
2569 If the first argument is @samp{!}, the value is the negation of
2570 the two-argument test using the second and third arguments.
2571 If the first argument is exactly @samp{(} and the third argument is
2572 exactly @samp{)}, the result is the one-argument test of the second
2574 Otherwise, the expression is false.
2575 The @samp{-a} and @samp{-o} operators are considered binary operators
2579 If the first argument is @samp{!}, the result is the negation of
2580 the three-argument expression composed of the remaining arguments.
2581 Otherwise, the expression is parsed and evaluated according to
2582 precedence using the rules listed above.
2584 @item 5 or more arguments
2585 The expression is parsed and evaluated according to precedence
2586 using the rules listed above.
2594 Print out the user and system times used by the shell and its children.
2595 The return status is zero.
2600 trap [-lp] [@var{arg}] [@var{sigspec} @dots{}]
2602 The commands in @var{arg} are to be read and executed when the
2603 shell receives signal @var{sigspec}. If @var{arg} is absent or
2604 equal to @samp{-}, all specified signals are reset to the values
2605 they had when the shell was started.
2606 If @var{arg} is the null string, then the signal specified by
2607 each @var{sigspec} is ignored by the shell and commands it invokes.
2608 If @var{arg} is @samp{-p}, the shell displays the trap commands
2609 associated with each @var{sigspec}. If no arguments are supplied, or
2610 only @samp{-p} is given, @code{trap} prints the list of commands
2611 associated with each signal number in a form that may be reused as
2613 Each @var{sigspec} is either a signal name such as @code{SIGINT} (with
2614 or without the @code{SIG} prefix) or a signal number.
2616 is @code{0} or @code{EXIT}, @var{arg} is executed when the shell exits.
2617 If a @var{sigspec} is @code{DEBUG}, the command @var{arg} is executed
2618 after every simple command.
2619 The @samp{-l} option causes the shell to print a list of signal names
2620 and their corresponding numbers.
2622 Signals ignored upon entry to the shell cannot be trapped or reset.
2623 Trapped signals are reset to their original values in a child
2624 process when it is created.
2626 The return status is zero unless a @var{sigspec} does not specify a
2632 umask [-p] [-S] [@var{mode}]
2634 Set the shell process's file creation mask to @var{mode}. If
2635 @var{mode} begins with a digit, it is interpreted as an octal number;
2636 if not, it is interpreted as a symbolic mode mask similar
2637 to that accepted by the @code{chmod} command. If @var{mode} is
2638 omitted, the current value of the mask is printed. If the @samp{-S}
2639 option is supplied without a @var{mode} argument, the mask is printed
2640 in a symbolic format.
2641 If the @samp{-p} option is supplied, and @var{mode}
2642 is omitted, the output is in a form that may be reused as input.
2643 The return status is zero if the mode is successfully changed or if
2644 no @var{mode} argument is supplied, and non-zero otherwise.
2649 unset [-fv] [@var{name}]
2651 Each variable or function @var{name} is removed.
2652 If no options are supplied, or the @samp{-v} option is given, each
2653 @var{name} refers to a shell variable.
2654 If the @samp{-f} option is given, the @var{name}s refer to shell
2655 functions, and the function definition is removed.
2656 Readonly variables and functions may not be unset.
2657 The return status is zero unless a @var{name} does not exist or is
2661 @node Bourne Shell Variables
2662 @section Bourne Shell Variables
2664 Bash uses certain shell variables in the same way as the Bourne shell.
2665 In some cases, Bash assigns a default value to the variable.
2670 A colon-separated list of directories used as a search path for
2671 the @code{cd} builtin command.
2674 The current user's home directory; the default for the @code{cd} builtin
2676 The value of this variable is also used by tilde expansion
2677 (@pxref{Tilde Expansion}).
2680 A list of characters that separate fields; used when the shell splits
2681 words as part of expansion.
2684 If this parameter is set to a filename and the @code{MAILPATH} variable
2685 is not set, Bash informs the user of the arrival of mail in
2689 A colon-separated list of filenames which the shell periodically checks
2691 Each list entry can specify the message that is printed when new mail
2692 arrives in the mail file by separating the file name from the message with
2694 When used in the text of the message, @code{$_} expands to the name of
2695 the current mail file.
2698 The value of the last option argument processed by the @code{getopts} builtin.
2701 The index of the last option argument processed by the @code{getopts} builtin.
2704 A colon-separated list of directories in which the shell looks for
2708 The primary prompt string. The default value is @samp{\s-\v\$ }.
2711 The secondary prompt string. The default value is @samp{> }.
2715 @node Other Bourne Shell Features
2716 @section Other Bourne Shell Features
2719 * Major Differences From The Bourne Shell:: Major differences between
2720 Bash and the Bourne shell.
2723 Bash implements essentially the same grammar, parameter and
2724 variable expansion, redirection, and quoting as the Bourne Shell.
2725 Bash uses the @sc{POSIX} 1003.2 standard as the specification of
2726 how these features are to be implemented. There are some
2727 differences between the traditional Bourne shell and Bash; this
2728 section quickly details the differences of significance. A
2729 number of these differences are explained in greater depth in
2730 subsequent sections.
2732 @node Major Differences From The Bourne Shell
2733 @subsection Major Differences From The SVR4.2 Bourne Shell
2738 Bash is @sc{POSIX}-conformant, even where the @sc{POSIX} specification
2739 differs from traditional @code{sh} behavior.
2742 Bash has multi-character invocation options (@pxref{Invoking Bash}).
2745 Bash has command-line editing (@pxref{Command Line Editing}) and
2746 the @code{bind} builtin.
2749 Bash has command history (@pxref{Bash History Facilities}) and the
2750 @code{history} and @code{fc} builtins to manipulate it.
2753 Bash implements @code{csh}-like history expansion
2754 (@pxref{History Interaction}).
2757 Bash has one-dimensional array variables (@pxref{Arrays}), and the
2758 appropriate variable expansions and assignment syntax to use them.
2759 Several of the Bash builtins take options to act on arrays.
2760 Bash provides a number of built-in array variables.
2763 The @code{$'@dots{}'} quoting syntax, which expands ANSI-C
2764 backslash-escaped characters in the text between the single quotes,
2765 is supported (@pxref{ANSI-C Quoting}).
2768 Bash supports the @code{$"@dots{}"} quoting syntax to do
2769 locale-specific translation of the characters between the double
2770 quotes. The @samp{-D}, @samp{--dump-strings}, and @samp{--dump-po-strings}
2771 invocation options list the translatable strings found in a script
2772 (@pxref{Locale Translation}).
2775 Bash implements the @code{!} keyword to negate the return value of
2776 a pipeline (@pxref{Pipelines}).
2777 Very useful when an @code{if} statement needs to act only if a test fails.
2780 Bash has the @code{time} reserved word and command timing (@pxref{Pipelines}).
2781 The display of the timing statistics may be controlled with the
2782 @code{TIMEFORMAT} variable.
2785 Bash includes the @code{select} compound command, which allows the
2786 generation of simple menus (@pxref{Conditional Constructs}).
2789 Bash includes the @code{[[} compound command, which makes conditional
2790 testing part of the shell grammar (@pxref{Conditional Constructs}).
2793 Bash includes brace expansion (@pxref{Brace Expansion}) and tilde
2794 expansion (@pxref{Tilde Expansion}).
2797 Bash implements command aliases and the @code{alias} and @code{unalias}
2798 builtins (@pxref{Aliases}).
2801 Bash provides shell arithmetic, the @code{((} compound command
2802 (@pxref{Conditional Constructs}),
2803 and arithmetic expansion (@pxref{Shell Arithmetic}).
2806 Variables present in the shell's initial environment are automatically
2807 exported to child processes. The Bourne shell does not normally do
2808 this unless the variables are explicitly marked using the @code{export}
2812 Bash includes the @sc{POSIX} pattern removal @samp{%}, @samp{#}, @samp{%%}
2813 and @samp{##} expansions to remove leading or trailing substrings from
2814 variable values (@pxref{Shell Parameter Expansion}).
2817 The expansion @code{$@{#xx@}}, which returns the length of @code{$@{xx@}},
2818 is supported (@pxref{Shell Parameter Expansion}).
2821 The expansion @code{$@{var:}@var{offset}@code{[:}@var{length}@code{]@}},
2822 which expands to the substring of @code{var}'s value of length
2823 @var{length}, beginning at @var{offset}, is present
2824 (@pxref{Shell Parameter Expansion}).
2828 @code{$@{var/[/]}@var{pattern}@code{[/}@var{replacement}@code{]@}},
2829 which matches @var{pattern} and replaces it with @var{replacement} in
2830 the value of @code{var}, is available (@pxref{Shell Parameter Expansion}).
2833 Bash has @var{indirect} variable expansion using @code{$@{!word@}}
2834 (@pxref{Shell Parameter Expansion}).
2837 Bash can expand positional parameters beyond @code{$9} using
2838 @code{$@{@var{num}@}}.
2841 The @sc{POSIX} @code{$()} form of command substitution
2842 is implemented (@pxref{Command Substitution}),
2843 and preferred to the Bourne shell's @code{``} (which
2844 is also implemented for backwards compatibility).
2847 Bash has process substitution (@pxref{Process Substitution}).
2850 Bash automatically assigns variables that provide information about the
2851 current user (@code{UID}, @code{EUID}, and @code{GROUPS}), the current host
2852 (@code{HOSTTYPE}, @code{OSTYPE}, @code{MACHTYPE}, and @code{HOSTNAME}),
2853 and the instance of Bash that is running (@code{BASH},
2854 @code{BASH_VERSION}, and @code{BASH_VERSINFO}). @xref{Bash Variables},
2858 The @code{IFS} variable is used to split only the results of expansion,
2859 not all words (@pxref{Word Splitting}).
2860 This closes a longstanding shell security hole.
2863 Bash implements the full set of @sc{POSIX.2} filename expansion operators,
2864 including @var{character classes}, @var{equivalence classes}, and
2865 @var{collating symbols} (@pxref{Filename Expansion}).
2868 Bash implements extended pattern matching features when the @code{extglob}
2869 shell option is enabled (@pxref{Pattern Matching}).
2872 It is possible to have a variable and a function with the same name;
2873 @code{sh} does not separate the two name spaces.
2876 Bash functions are permitted to have local variables using the
2877 @code{local} builtin, and thus useful recursive functions may be written.
2880 Variable assignments preceding commands affect only that command, even
2881 builtins and functions (@pxref{Environment}).
2882 In @code{sh}, all variable assignments
2883 preceding commands are global unless the command is executed from the
2887 Bash performs filename expansion on filenames specified as operands
2888 to input and output redirection operators.
2891 Bash contains the @samp{<>} redirection operator, allowing a file to be
2892 opened for both reading and writing, and the @samp{&>} redirection
2893 operator, for directing standard output and standard error to the same
2894 file (@pxref{Redirections}).
2897 The @code{noclobber} option is available to avoid overwriting existing
2898 files with output redirection (@pxref{The Set Builtin}).
2899 The @samp{>|} redirection operator may be used to override @code{noclobber}.
2902 The Bash @code{cd} and @code{pwd} builtins (@pxref{Bourne Shell Builtins})
2903 each take @samp{-L} and @samp{-P} builtins to switch between logical and
2907 Bash allows a function to override a builtin with the same name, and provides
2908 access to that builtin's functionality within the function via the
2909 @code{builtin} and @code{command} builtins (@pxref{Bash Builtins}).
2912 The @code{command} builtin allows selective disabling of functions
2913 when command lookup is performed (@pxref{Bash Builtins}).
2916 Individual builtins may be enabled or disabled using the @code{enable}
2917 builtin (@pxref{Bash Builtins}).
2920 The Bash @code{exec} builtin takes additional options that allow users
2921 to control the contents of the environment passed to the executed
2922 command, and what the zeroth argument to the command is to be
2923 (@pxref{Bourne Shell Builtins}).
2926 Shell functions may be exported to children via the environment
2927 using @code{export -f} (@pxref{Shell Functions}).
2930 The Bash @code{export}, @code{readonly}, and @code{declare} builtins can
2931 take a @samp{-f} option to act on shell functions, a @samp{-p} option to
2932 display variables with various attributes set in a format that can be
2933 used as shell input, a @samp{-n} option to remove various variable
2934 attributes, and @samp{name=value} arguments to set variable attributes
2935 and values simultaneously.
2938 The Bash @code{hash} builtin allows a name to be associated with
2939 an arbitrary filename, even when that filename cannot be found by
2940 searching the @code{$PATH}, using @samp{hash -p}
2941 (@pxref{Bourne Shell Builtins}).
2944 Bash includes a @code{help} builtin for quick reference to shell
2945 facilities (@pxref{Bash Builtins}).
2948 The @code{printf} builtin is available to display formatted output
2949 (@pxref{Bash Builtins}).
2952 The Bash @code{read} builtin (@pxref{Bash Builtins})
2953 will read a line ending in @samp{\} with
2954 the @samp{-r} option, and will use the @code{REPLY} variable as a
2955 default if no arguments are supplied. The Bash @code{read} builtin
2956 also accepts a prompt string with the @samp{-p} option and will use
2957 Readline to obtain the line when given the @samp{-e} option.
2960 The @code{return} builtin may be used to abort execution of scripts
2961 executed with the @code{.} or @code{source} builtins
2962 (@pxref{Bourne Shell Builtins}).
2965 Bash includes the @code{shopt} builtin, for finer control of shell
2966 optional capabilities (@pxref{Bash Builtins}).
2969 Bash has much more optional behavior controllable with the @code{set}
2970 builtin (@pxref{The Set Builtin}).
2973 The @code{test} builtin (@pxref{Bourne Shell Builtins})
2974 is slightly different, as it implements the @sc{POSIX} algorithm,
2975 which specifies the behavior based on the number of arguments.
2978 The @code{trap} builtin (@pxref{Bourne Shell Builtins})
2979 allows a @code{DEBUG} pseudo-signal specification,
2980 similar to @code{EXIT}. Commands specified with a @code{DEBUG} trap are
2981 executed after every simple command. The @code{DEBUG} trap is not
2982 inherited by shell functions.
2985 The Bash @code{type} builtin is more extensive and gives more information
2986 about the names it finds (@pxref{Bash Builtins}).
2989 The Bash @code{umask} builtin permits a @samp{-p} option to cause
2990 the output to be displayed in the form of a @code{umask} command
2991 that may be reused as input (@pxref{Bourne Shell Builtins}).
2994 Bash implements a @code{csh}-like directory stack, and provides the
2995 @code{pushd}, @code{popd}, and @code{dirs} builtins to manipulate it
2996 (@pxref{The Directory Stack}).
2997 Bash also makes the directory stack visible as the value of the
2998 @code{DIRSTACK} shell variable.
3001 Bash interprets special backslash-escaped characters in the prompt
3002 strings when interactive (@pxref{Printing a Prompt}).
3005 The Bash restricted mode is more useful (@pxref{The Restricted Shell});
3006 the @sc{SVR4.2} shell restricted mode is too limited.
3009 The @code{disown} builtin can remove a job from the internal shell
3010 job table (@pxref{Job Control Builtins}) or suppress the sending
3011 of @code{SIGHUP} to a job when the shell exits as the result of a
3015 The @sc{SVR4.2} shell has two privilege-related builtins
3016 (@code{mldmode} and @code{priv}) not present in Bash.
3019 Bash does not have the @code{stop} or @code{newgrp} builtins.
3022 Bash does not use the @code{SHACCT} variable or perform shell accounting.
3025 The @sc{SVR4.2} @code{sh} uses a @code{TIMEOUT} variable like Bash uses
3031 More features unique to Bash may be found in @ref{Bash Features}.
3033 @subsection Implementation Differences From The SVR4.2 Shell
3035 Since Bash is a completely new implementation, it does not suffer from
3036 many of the limitations of the @sc{SVR4.2} shell. For instance:
3041 Bash does not fork a subshell when redirecting into or out of
3042 a shell control structure such as an @code{if} or @code{while}
3046 Bash does not allow unbalanced quotes. The @sc{SVR4.2} shell will silently
3047 insert a needed closing quote at @code{EOF} under certain circumstances.
3048 This can be the cause of some hard-to-find errors.
3051 The @sc{SVR4.2} shell uses a baroque memory management scheme based on
3052 trapping @code{SIGSEGV}. If the shell is started from a process with
3053 @code{SIGSEGV} blocked (e.g., by using the @code{system()} C library
3054 function call), it misbehaves badly.
3057 In a questionable attempt at security, the @sc{SVR4.2} shell,
3058 when invoked without the @samp{-p} option, will alter its real
3059 and effective @sc{UID} and @sc{GID} if they are less than some
3060 magic threshold value, commonly 100.
3061 This can lead to unexpected results.
3064 The @sc{SVR4.2} shell does not allow users to trap @code{SIGSEGV},
3065 @code{SIGALRM}, or @code{SIGCHLD}.
3068 The @sc{SVR4.2} shell does not allow the @code{IFS}, @code{MAILCHECK},
3069 @code{PATH}, @code{PS1}, or @code{PS2} variables to be unset.
3072 The @sc{SVR4.2} shell treats @samp{^} as the undocumented equivalent of
3076 Bash allows multiple option arguments when it is invoked (@code{-x -v});
3077 the @sc{SVR4.2} shell allows only one option argument (@code{-xv}). In
3078 fact, some versions of the shell dump core if the second argument begins
3082 The @sc{SVR4.2} shell exits a script if any builtin fails; Bash exits
3083 a script only if one of the @sc{POSIX.2} special builtins fails, and
3084 only for certain failures, as enumerated in the @sc{POSIX.2} standard.
3087 The @sc{SVR4.2} shell behaves differently when invoked as @code{jsh}
3088 (it turns on job control).
3092 @chapter Bash Features
3094 This section describes features unique to Bash.
3097 * Invoking Bash:: Command line options that you can give
3099 * Bash Startup Files:: When and how Bash executes scripts.
3100 * Is This Shell Interactive?:: Determining the state of a running Bash.
3101 * Bash Builtins:: Table of builtins specific to Bash.
3102 * The Set Builtin:: This builtin is so overloaded it
3103 deserves its own section.
3104 * Bash Conditional Expressions:: Primitives used in composing expressions for
3105 the @code{test} builtin.
3106 * Bash Variables:: List of variables that exist in Bash.
3107 * Shell Arithmetic:: Arithmetic on shell variables.
3108 * Aliases:: Substituting one command for another.
3109 * Arrays:: Array Variables.
3110 * The Directory Stack:: History of visited directories.
3111 * Printing a Prompt:: Controlling the PS1 string.
3112 * The Restricted Shell:: A more controlled mode of shell execution.
3113 * Bash POSIX Mode:: Making Bash behave more closely to what
3114 the POSIX standard specifies.
3118 @section Invoking Bash
3121 bash [long-opt] [-ir] [-abefhkmnptuvxdBCDHP] [-o @var{option}] [@var{argument} @dots{}]
3122 bash [long-opt] [-abefhkmnptuvxdBCDHP] [-o @var{option}] -c @var{string} [@var{argument} @dots{}]
3123 bash [long-opt] -s [-abefhkmnptuvxdBCDHP] [-o @var{option}] [@var{argument} @dots{}]
3126 In addition to the single-character shell command-line options
3127 (@pxref{The Set Builtin}), there are several multi-character
3128 options that you can use. These options must appear on the command
3129 line before the single-character options in order for them
3133 @item --dump-po-strings
3134 Equivalent to @samp{-D}, but the output is in the GNU @code{gettext}
3135 PO (portable object) file format.
3137 @item --dump-strings
3138 Equivalent to @samp{-D}.
3141 Display a usage message on standard output and exit sucessfully.
3144 Make this shell act as if it were directly invoked by login.
3145 This is equivalent to @samp{exec -l bash} but can be issued from
3146 another shell, such as @code{csh}. @samp{exec bash --login}
3147 will replace the current shell with a Bash login shell.
3150 Do not use the @sc{GNU} Readline library (@pxref{Command Line Editing})
3151 to read interactive command lines.
3154 Don't load the system-wide startup file @file{/etc/profile}
3155 or any of the personal initialization files
3156 @file{~/.bash_profile}, @file{~/.bash_login}, or @file{~/.profile}
3157 when Bash is invoked as a login shell.
3160 Don't read the @file{~/.bashrc} initialization file in an
3161 interactive shell. This is on by default if the shell is
3162 invoked as @code{sh}.
3165 Change the behavior of Bash where the default operation differs
3166 from the @sc{POSIX} 1003.2 standard to match the standard. This
3167 is intended to make Bash behave as a strict superset of that
3168 standard. @xref{Bash POSIX Mode}, for a description of the Bash
3171 @item --rcfile @var{filename}
3172 Execute commands from @var{filename} (instead of @file{~/.bashrc})
3173 in an interactive shell.
3176 Make the shell a restricted shell (@pxref{The Restricted Shell}).
3179 Equivalent to @samp{-v}.
3182 Show version information for this instance of
3183 Bash on the standard output and exit successfully.
3187 There are several single-character options that may be supplied at
3188 invocation which are not available with the @code{set} builtin.
3191 @item -c @var{string}
3192 Read and execute commands from @var{string} after processing the
3193 options, then exit. Any remaining arguments are assigned to the
3194 positional parameters, starting with @code{$0}.
3197 Force the shell to run interactively.
3200 Make the shell a restricted shell (@pxref{The Restricted Shell}).
3203 If this option is present, or if no arguments remain after option
3204 processing, then commands are read from the standard input.
3205 This option allows the positional parameters to be set
3206 when invoking an interactive shell.
3209 A list of all double-quoted strings preceded by @samp{$}
3210 is printed on the standard ouput.
3211 These are the strings that
3212 are subject to language translation when the current locale
3213 is not @code{C} or @code{POSIX} (@pxref{Locale Translation}).
3214 This implies the @samp{-n} option; no commands will be executed.
3217 A @code{--} signals the end of options and disables further option
3219 Any arguments after the @code{--} are treated as filenames and arguments.
3223 @cindex interactive shell
3224 An @emph{interactive} shell is one whose input and output are both
3225 connected to terminals (as determined by @code{isatty(3)}), or one
3226 started with the @samp{-i} option.
3228 If arguments remain after option processing, and neither the
3229 @samp{-c} nor the @samp{-s}
3230 option has been supplied, the first argument is assumed to
3231 be the name of a file containing shell commands (@pxref{Shell Scripts}).
3232 When Bash is invoked in this fashion, @code{$0}
3233 is set to the name of the file, and the positional parameters
3234 are set to the remaining arguments.
3235 Bash reads and executes commands from this file, then exits.
3236 Bash's exit status is the exit status of the last command executed
3237 in the script. If no commands are executed, the exit status is 0.
3239 @node Bash Startup Files
3240 @section Bash Startup Files
3241 @cindex startup files
3243 This section describs how Bash executes its startup files.
3244 If any of the files exist but cannot be read, Bash reports an error.
3245 Tildes are expanded in file names as described above under
3246 Tilde Expansion (@pxref{Tilde Expansion}).
3248 When Bash is invoked as an interactive login shell, it first reads and
3249 executes commands from the file @file{/etc/profile}, if that file exists.
3250 After reading that file, it looks for @file{~/.bash_profile},
3251 @file{~/.bash_login}, and @file{~/.profile}, in that order, and reads
3252 and executes commands from the first one that exists and is readable.
3253 The @samp{--noprofile} option may be used when the shell is started to
3254 inhibit this behavior.
3256 When a login shell exits, Bash reads and executes commands from
3257 the file @file{~/.bash_logout}, if it exists.
3259 When an interactive shell that is not a login shell is started, Bash
3260 reads and executes commands from @file{~/.bashrc}, if that file exists.
3261 This may be inhibited by using the @samp{--norc} option.
3262 The @samp{--rcfile @var{file}} option will force Bash to read and
3263 execute commands from @var{file} instead of @file{~/.bashrc}.
3265 So, typically, your @file{~/.bash_profile} contains the line
3267 @code{if [ -f @file{~/.bashrc} ]; then . @file{~/.bashrc}; fi}
3270 after (or before) any login-specific initializations.
3272 When Bash is started non-interactively, to run a shell script,
3273 for example, it looks for the variable @code{BASH_ENV} in the environment,
3274 expands its value if it appears there, and uses the expanded value as
3275 the name of a file to read and execute. Bash behaves as if the
3276 following command were executed:
3278 @code{if [ -n "$BASH_ENV" ]; then . "$BASH_ENV"; fi}
3281 but the value of the @code{PATH} variable is not used to search for the
3284 If Bash is invoked with the name @code{sh}, it tries to mimic the
3285 startup behavior of historical versions of @code{sh} as closely as
3286 possible, while conforming to the @sc{POSIX} standard as well.
3288 When invoked as an interactive login shell, it first attempts to read
3289 and execute commands from @file{/etc/profile} and @file{~/.profile}, in
3291 The @samp{--noprofile} option may be used to inhibit this behavior.
3292 When invoked as an interactive shell with the name @code{sh}, Bash
3293 looks for the variable @code{ENV}, expands its value if it is defined,
3294 and uses the expanded value as the name of a file to read and execute.
3295 Since a shell invoked as @code{sh} does not attempt to read and execute
3296 commands from any other startup files, the @samp{--rcfile} option has
3298 A non-interactive shell invoked with the name @code{sh} does not attempt
3299 to read any startup files.
3301 When invoked as @code{sh}, Bash enters @sc{POSIX} mode after
3302 the startup files are read.
3304 When Bash is started in @sc{POSIX} mode, as with the
3305 @samp{--posix} command line option, it follows the @sc{POSIX} standard
3307 In this mode, interactive shells expand the @code{ENV} variable
3308 and commands are read and executed from the file whose name is the
3310 No other startup files are read.
3312 Bash attempts to determine when it is being run by the remote shell
3313 daemon, usually @code{rshd}. If Bash determines it is being run by
3314 rshd, it reads and executes commands from @file{~/.bashrc}, if that
3315 file exists and is readable.
3316 It will not do this if invoked as @code{sh}.
3317 The @samp{--norc} option may be used to inhibit this behavior, and the
3318 @samp{--rcfile} option may be used to force another file to be read, but
3319 @code{rshd} does not generally invoke the shell with those options or
3320 allow them to be specified.
3322 @node Is This Shell Interactive?
3323 @section Is This Shell Interactive?
3324 @cindex interactive shell
3326 As defined in @ref{Invoking Bash}, an interactive shell
3327 is one whose input and output are both
3328 connected to terminals (as determined by @code{isatty(3)}),
3329 or one started with the @samp{-i} option.
3331 To determine within a startup script whether Bash is
3332 running interactively or not, examine the variable
3333 @code{$PS1}; it is unset in non-interactive shells, and set in
3334 interactive shells. Thus:
3337 if [ -z "$PS1" ]; then
3338 echo This shell is not interactive
3340 echo This shell is interactive
3344 Alternatively, startup scripts may test the value of the @samp{-}
3346 It contains @code{i} when the shell is interactive. For example:
3350 *i*) echo This shell is interactive ;;
3351 *) echo This shell is not interactive ;;
3356 @section Bash Builtin Commands
3358 This section describes builtin commands which are unique to
3359 or have been extended in Bash.
3366 bind [-m @var{keymap}] [-lpsvPSV]
3367 bind [-m @var{keymap}] [-q @var{function}] [-u @var{function}] [-r @var{keyseq}]
3368 bind [-m @var{keymap}] -f @var{filename}
3369 bind [-m @var{keymap}] @var{keyseq:function-name}
3372 Display current Readline (@pxref{Command Line Editing})
3373 key and function bindings, or
3374 bind a key sequence to a Readline function or macro. The
3375 binding syntax accepted is identical to that of
3376 @file{.inputrc} (@pxref{Readline Init File}),
3377 but each binding must be passed as a separate argument: e.g.,
3378 @samp{"\C-x\C-r":re-read-init-file}.
3379 Options, if supplied, have the following meanings:
3382 @item -m @var{keymap}
3383 Use @var{keymap} as the keymap to be affected by
3384 the subsequent bindings. Acceptable @var{keymap}
3387 @code{emacs-standard},
3391 @code{vi-command}, and
3393 @code{vi} is equivalent to @code{vi-command};
3394 @code{emacs} is equivalent to @code{emacs-standard}.
3397 List the names of all Readline functions.
3400 Display Readline function names and bindings in such a way that they
3404 List current Readline function names and bindings.
3407 Display Readline variable names and values in such a way that they
3411 List current Readline variable names and values.
3414 Display Readline key sequences bound to macros and the strings they output
3415 in such a way that they can be re-read.
3418 Display Readline key sequences bound to macros and the strings they output.
3420 @item -f @var{filename}
3421 Read key bindings from @var{filename}.
3423 @item -q @var{function}
3424 Query about which keys invoke the named @var{function}.
3426 @item -u @var{function}
3427 Unbind all keys bound to the named @var{function}.
3429 @item -r @var{keyseq}
3430 Remove any current binding for @var{keyseq}.
3435 The return status is zero unless an invalid option is supplied or an
3441 builtin [@var{shell-builtin} [@var{args}]]
3443 Run a shell builtin, passing it @var{args}, and return its exit status.
3444 This is useful when defining a shell function with the same
3445 name as a shell builtin, retaining the functionality of the builtin within
3447 The return status is non-zero if @var{shell-builtin} is not a shell
3453 command [-pVv] @var{command} [@var{arguments} @dots{}]
3455 Runs @var{command} with @var{arguments} ignoring any shell function
3456 named @var{command}.
3457 Only shell builtin commands or commands found by searching the
3458 @code{PATH} are executed.
3459 If there is a shell function named @code{ls}, running @samp{command ls}
3460 within the function will execute the external command @code{ls}
3461 instead of calling the function recursively.
3462 The @samp{-p} option means to use a default value for @code{$PATH}
3463 that is guaranteed to find all of the standard utilities.
3464 The return status in this case is 127 if @var{command} cannot be
3465 found or an error occurred, and the exit status of @var{command}
3468 If either the @samp{-V} or @samp{-v} option is supplied, a
3469 description of @var{command} is printed. The @samp{-v} option
3470 causes a single word indicating the command or file name used to
3471 invoke @var{command} to be displayed; the @samp{-V} option produces
3472 a more verbose description. In this case, the return status is
3473 zero if @var{command} is found, and non-zero if not.
3478 declare [-afFrxi] [-p] [@var{name}[=@var{value}]]
3481 Declare variables and give them attributes. If no @var{name}s
3482 are given, then display the values of variables instead.
3484 The @samp{-p} option will display the attributes and values of each
3485 @var{name}. When @samp{-p} is used, additional options are ignored.
3486 The @samp{-F} option inhibits the display of function definitions;
3487 only the function name and attributes are printed. @samp{-F} implies
3488 @samp{-f}. The following options can be used to restrict output
3489 to variables with the specified attributes or to give variables
3494 Each @var{name} is an array variable (@pxref{Arrays}).
3497 Use function names only.
3500 The variable is to be treated as
3501 an integer; arithmetic evaluation (@pxref{Shell Arithmetic}) is
3502 performed when the variable is assigned a value.
3505 Make @var{name}s readonly. These names cannot then be assigned values
3506 by subsequent assignment statements or unset.
3509 Mark each @var{name} for export to subsequent commands via
3513 Using @samp{+} instead of @samp{-} turns off the attribute instead.
3514 When used in a function, @code{declare} makes each @var{name} local,
3515 as with the @code{local} command.
3517 The return status is zero unless an invalid option is encountered,
3518 an attempt is made to define a function using @code{-f foo=bar},
3519 an attempt is made to assign a value to a readonly variable,
3520 an attempt is made to assign a value to an array variable without
3521 using the compound assignment syntax (@pxref{Arrays}),
3522 one of the @var{names} is not a valid shell variable name,
3523 an attempt is made to turn off readonly status for a readonly variable,
3524 an attempt is made to turn off array status for an array variable,
3525 or an attempt is made to display a non-existent function with @samp{-f}.
3530 echo [-neE] [@var{arg} @dots{}]
3532 Output the @var{arg}s, separated by spaces, terminated with a
3534 The return status is always 0.
3535 If @samp{-n} is specified, the trailing newline is suppressed.
3536 If the @samp{-e} option is given, interpretation of the following
3537 backslash-escaped characters is enabled.
3538 The @samp{-E} option disables the interpretation of these escape characters,
3539 even on systems where they are interpreted by default.
3540 @code{echo} interprets the following escape sequences:
3547 suppress trailing newline
3563 the character whose @code{ASCII} code is the octal value @var{nnn}
3564 (one to three digits)
3566 the character whose @code{ASCII} code is the hexadecimal value @var{nnn}
3567 (one to three digits)
3573 enable [-n] [-p] [-f @var{filename}] [-ads] [@var{name} @dots{}]
3575 Enable and disable builtin shell commands.
3576 Disabling a builtin allows a disk command which has the same name
3577 as a shell builtin to be executed with specifying a full pathname,
3578 even though the shell normally searches for builtins before disk commands.
3579 If @samp{-n} is used, the @var{name}s become disabled. Otherwise
3580 @var{name}s are enabled. For example, to use the @code{test} binary
3581 found via @code{$PATH} instead of the shell builtin version, type
3582 @samp{enable -n test}.
3584 If the @samp{-p} option is supplied, or no @var{name} arguments appear,
3585 a list of shell builtins is printed. With no other arguments, the list
3586 consists of all enabled shell builtins.
3587 The @samp{-a} option means to list
3588 each builtin with an indication of whether or not it is enabled.
3590 The @samp{-f} option means to load the new builtin command @var{name}
3591 from shared object @var{filename}, on systems that support dynamic loading.
3592 The @samp{-d} option will delete a builtin loaded with @samp{-f}.
3594 If there are no options, a list of the shell builtins is displayed.
3595 The @samp{-s} option restricts @code{enable} to the @sc{POSIX} special
3596 builtins. If @samp{-s} is used with @samp{-f}, the new builtin becomes
3599 The return status is zero unless a @var{name} is not a shell builtin
3600 or there is an error loading a new builtin from a shared object.
3605 help [@var{pattern}]
3607 Display helpful information about builtin commands.
3608 If @var{pattern} is specified, @code{help} gives detailed help
3609 on all commands matching @var{pattern}, otherwise a list of
3610 the builtins is printed. The return status is zero unless no
3611 command matches @var{pattern}.
3616 let @var{expression} [@var{expression}]
3618 The @code{let} builtin allows arithmetic to be performed on shell
3619 variables. Each @var{expression} is evaluated according to the
3620 rules given below in @ref{Shell Arithmetic}. If the
3621 last @var{expression} evaluates to 0, @code{let} returns 1;
3622 otherwise 0 is returned.
3627 local @var{name}[=@var{value}]
3629 For each argument, a local variable named @var{name} is created,
3630 and assigned @var{value}.
3631 @code{local} can only be used within a function; it makes the variable
3632 @var{name} have a visible scope restricted to that function and its
3633 children. The return status is zero unless @code{local} is used outside
3634 a function or an invalid @var{name} is supplied.
3641 Exit a login shell, returning a status of @var{n} to the shell's
3647 @code{printf} @var{format} [@var{arguments}]
3649 Write the formatted @var{arguments} to the standard output under the
3650 control of the @var{format}.
3651 The @var{format} is a character string which contains three types of objects:
3652 plain characters, which are simply copied to standard output, character
3653 escape sequences, which are converted and copied to the standard output, and
3654 format specifications, each of which causes printing of the next successive
3656 In addition to the standard @code{printf(1)} formats, @samp{%b} causes
3657 @code{printf} to expand backslash escape sequences in the corresponding
3658 @var{argument}, and @samp{%q} causes @code{printf} to output the
3659 corresponding @var{argument} in a format that can be reused as shell input.
3661 The @var{format} is reused as necessary to consume all of the @var{arguments}.
3662 If the @var{format} requires more @var{arguments} than are supplied, the
3663 extra format specifications behave as if a zero value or null string, as
3664 appropriate, had been supplied.
3669 read [-a @var{aname}] [-p @var{prompt}] [-er] [@var{name} @dots{}]
3671 One line is read from the standard input, and the first word
3672 is assigned to the first @var{name}, the second word to the second @var{name},
3673 and so on, with leftover words and their intervening separators assigned
3674 to the last @var{name}.
3675 If there are fewer words read from the standard input than names,
3676 the remaining names are assigned empty values.
3677 The characters in the value of the @code{IFS} variable
3678 are used to split the line into words.
3679 If no names are supplied, the line read is assigned to the
3680 variable @code{REPLY}.
3681 The return code is zero, unless end-of-file is encountered.
3682 Options, if supplied, have the following meanings:
3686 If this option is given, a backslash-newline pair is not ignored, and
3687 the backslash is considered to be part of the line.
3689 @item -p @var{prompt}
3690 Display @var{prompt}, without a
3691 trailing newline, before attempting to read any input. The prompt
3692 is displayed only if input is coming from a terminal.
3694 @item -a @var{aname}
3695 The words are assigned to sequential indices of the array variable
3696 @var{aname}, starting at 0.
3697 All elements are removed from @var{aname} before the assignment.
3698 Other @var{name} arguments are ignored.
3701 Readline (@pxref{Command Line Editing})
3702 is used to obtain the line.
3708 shopt [-pqsu] [-o] [@var{optname} @dots{}]
3710 Toggle the values of variables controlling optional shell behavior.
3711 With no options, or with the @samp{-p} option, a list of all settable
3712 options is displayed, with an indication of whether or not each is set.
3713 The @samp{-p} option causes output to be displayed in a form that
3714 may be reused as input.
3715 Other options have the following meanings:
3719 Enable (set) each @var{optname}.
3722 Disable (unset) each @var{optname}.
3725 Suppresses normal output; the return status
3726 indicates whether the @var{optname} is set or unset.
3727 If multiple @var{optname} arguments are given with @samp{-q},
3728 the return status is zero if all @var{optnames} are enabled;
3732 Restricts the values of
3733 @var{optname} to be those defined for the @samp{-o} option to the
3734 @code{set} builtin (@pxref{The Set Builtin}).
3737 If either @samp{-s} or @samp{-u}
3738 is used with no @var{optname} arguments, the display is limited to
3739 those options which are set or unset, respectively.
3741 Unless otherwise noted, the @code{shopt} options are disabled (off)
3744 The return status when listing options is zero if all @var{optnames}
3745 are enabled, non-zero otherwise. When setting or unsetting options,
3746 the return status is zero unless an @var{optname} is not a valid shell
3749 The list of @code{shopt} options is:
3752 If this is set, an argument to the @code{cd}
3753 builtin command that
3754 is not a directory is assumed to be the name of a variable whose
3755 value is the directory to change to.
3758 If set, minor errors in the spelling of a directory component in a
3759 @code{cd} command will be corrected.
3760 The errors checked for are transposed characters,
3761 a missing character, and a character too many.
3762 If a correction is found, the corrected path is printed,
3763 and the command proceeds.
3764 This option is only used by interactive shells.
3767 If this is set, Bash checks that a command found in the hash
3768 table exists before trying to execute it. If a hashed command no
3769 longer exists, a normal path search is performed.
3772 If set, Bash checks the window size after each command
3773 and, if necessary, updates the values of
3774 @code{LINES} and @code{COLUMNS}.
3778 attempts to save all lines of a multiple-line
3779 command in the same history entry. This allows
3780 easy re-editing of multi-line commands.
3783 If set, Bash includes filenames beginning with a `.' in
3784 the results of filename expansion.
3787 If this is set, a non-interactive shell will not exit if
3788 it cannot execute the file specified as an argument to the @code{exec}
3789 builtin command. An interactive shell does not exit if @code{exec}
3792 @item expand_aliases
3793 If set, aliases are expanded as described below< under Aliases
3795 This option is enabled by default for interactive shells.
3798 If set, the extended pattern matching features described above
3799 (@pxref{Pattern Matching}) are enabled.
3802 If set, the history list is appended to the file named by the value
3803 of the @code{HISTFILE}
3804 variable when the shell exits, rather than overwriting the file.
3807 If set, and Readline
3808 is being used, a user is given the opportunity to re-edit a
3809 failed history substitution.
3812 If set, and Readline
3813 is being used, the results of history substitution are not immediately
3814 passed to the shell parser. Instead, the resulting line is loaded into
3815 the Readline editing buffer, allowing further modification.
3818 If set, and Readline is being used, Bash will attempt to perform
3819 hostname completion when a word containing a @samp{@@} is being
3820 completed (@pxref{Commands For Completion}). This option is enabled
3824 If set, Bash will send @code{SIGHUP} to all jobs when an interactive
3825 login shell exits (@pxref{Signals}).
3827 @item interactive_comments
3828 Allow a word beginning with @samp{#}
3829 to cause that word and all remaining characters on that
3830 line to be ignored in an interactive shell.
3831 This option is enabled by default.
3834 If enabled, and the @code{cmdhist}
3835 option is enabled, multi-line commands are saved to the history with
3836 embedded newlines rather than using semicolon separators where possible.
3839 If set, and a file that Bash is checking for mail has been
3840 accessed since the last time it was checked, the message
3841 @code{"The mail in @var{mailfile} has been read"} is displayed.
3844 If set, Bash matches filenames in a case-insensitive fashion when
3845 performing filename expansion.
3848 If set, Bash allows filename patterns which match no
3849 files to expand to a null string, rather than themselves.
3852 If set, prompt strings undergo variable and parameter expansion after
3853 being expanded (@pxref{Printing a Prompt}).
3854 This option is enabled by default.
3857 If this is set, the @code{shift}
3858 builtin prints an error message when the shift count exceeds the
3859 number of positional parameters.
3862 If set, the @code{source} builtin uses the value of @code{PATH}
3863 to find the directory containing the file supplied as an argument.
3864 This option is enabled by default.
3868 The return status when listing options is zero if all @var{optnames}
3869 are enabled, non-zero otherwise.
3870 When setting or unsetting options, the return status is zero unless an
3871 @var{optname} is not a valid shell option.
3876 source @var{filename}
3878 A synonym for @code{.} (@pxref{Bourne Shell Builtins}).
3883 type [-atp] [@var{name} @dots{}]
3885 For each @var{name}, indicate how it would be interpreted if used as a
3888 If the @samp{-t} option is used, @code{type} prints a single word
3889 which is one of @samp{alias}, @samp{function}, @samp{builtin},
3890 @samp{file} or @samp{keyword},
3891 if @var{name} is an alias, shell function, shell builtin,
3892 disk file, or shell reserved word, respectively.
3893 If the @var{name} is not found, then nothing is printed, and
3894 @code{type} returns a failure status.
3896 If the @samp{-p} option is used, @code{type} either returns the name
3897 of the disk file that would be executed, or nothing if @samp{-t}
3898 would not return @samp{file}.
3900 If the @samp{-a} option is used, @code{type} returns all of the places
3901 that contain an executable named @var{file}.
3902 This includes aliases and functions, if and only if the @samp{-p} option
3905 The return status is zero if any of the @var{names} are found, non-zero
3911 typeset [-afFrxi] [-p] [@var{name}[=@var{value}]]
3913 The @code{typeset} command is supplied for compatibility with the Korn
3914 shell; however, it has been deprecated in favor of the @code{declare}
3920 ulimit [-acdflmnpstuvSH] [@var{limit}]
3922 @code{ulimit} provides control over the resources available to processes
3923 started by the shell, on systems that allow such control. If an
3924 option is given, it is interpreted as follows:
3927 Change and report the soft limit associated with a resource.
3930 Change and report the hard limit associated with a resource.
3933 All current limits are reported.
3936 The maximum size of core files created.
3939 The maximum size of a process's data segment.
3942 The maximum size of files created by the shell.
3945 The maximum size that may be locked into memory.
3948 The maximum resident set size.
3951 The maximum number of open file descriptors.
3954 The pipe buffer size.
3957 The maximum stack size.
3960 The maximum amount of cpu time in seconds.
3963 The maximum number of processes available to a single user.
3966 The maximum amount of virtual memory available to the process.
3970 If @var{limit} is given, it is the new value of the specified resource.
3971 Otherwise, the current value of the soft limit for the specified resource
3972 is printed, unless the @samp{-H} option is supplied.
3973 When setting new limits, if neither @samp{-H} nor @samp{-S} is supplied,
3974 both the hard and soft limits are set.
3975 If no option is given, then @samp{-f} is assumed. Values are in 1024-byte
3976 increments, except for @samp{-t}, which is in seconds, @samp{-p},
3977 which is in units of 512-byte blocks, and @samp{-n} and @samp{-u}, which
3978 are unscaled values.
3980 The return status is zero unless an invalid option is supplied, a
3981 non-numeric argument other than @code{unlimited} is supplied as a
3982 @var{limit}, or an error occurs while setting a new limit.
3986 @node The Set Builtin
3987 @section The Set Builtin
3989 This builtin is so complicated that it deserves its own section.
3995 set [--abefhkmnptuvxBCHP] [-o @var{option}] [@var{argument} @dots{}]
3998 If no options or arguments are supplied, @code{set} displays the names
3999 and values of all shell variables and functions, sorted according to the
4000 current locale, in a format that may be reused as input.
4002 When options are supplied, they set or unset shell attributes.
4003 Options, if specified, have the following meanings:
4007 Mark variables which are modified or created for export.
4010 Cause the status of terminated background jobs to be reported
4011 immediately, rather than before printing the next primary prompt.
4014 Exit immediately if a simple command (@pxref{Simple Commands}) exits
4015 with a non-zero status, unless the command that fails is part of an
4016 @code{until} or @code{while} loop, part of an @code{if} statement,
4017 part of a @code{&&} or @code{||} list, or if the command's return
4018 status is being inverted using @code{!}.
4021 Disable file name generation (globbing).
4024 Locate and remember (hash) commands as they are looked up for execution.
4025 This option is enabled by default.
4028 All arguments in the form of assignment statements are placed
4029 in the environment for a command, not just those that precede
4033 Job control is enabled (@pxref{Job Control}).
4036 Read commands but do not execute them; this may be used to check a
4037 script for syntax errors.
4038 This option is ignored by interactive shells.
4040 @item -o @var{option-name}
4042 Set the option corresponding to @var{option-name}:
4052 Use an @code{emacs}-style line editing interface (@pxref{Command Line Editing}).
4064 Enable command history, as described in @ref{Bash History Facilities}.
4065 This option is on by default in interactive shells.
4068 An interactive shell will not exit upon reading EOF.
4098 Change the behavior of Bash where the default operation differs
4099 from the @sc{POSIX} 1003.2 standard to match the standard
4100 (@pxref{Bash POSIX Mode}).
4101 This is intended to make Bash behave as a strict superset of that
4111 Use a @code{vi}-style line editing interface.
4118 Turn on privileged mode.
4119 In this mode, the @code{$BASH_ENV} and @code{$ENV} files are not
4120 processed, shell functions are not inherited from the environment,
4121 and the @code{SHELLOPTS} variable, if it appears in the environment,
4123 This is enabled automatically
4124 on startup if the effective user (group) id is not equal to the real
4125 user (group) id. Turning this option off causes the effective user
4126 and group ids to be set to the real user and group ids.
4129 Exit after reading and executing one command.
4132 Treat unset variables as an error when performing parameter expansion.
4133 An error message will be written to the standard error, and a non-interactive
4137 Print shell input lines as they are read.
4140 Print a trace of simple commands and their arguments after they are
4141 expanded and before they are executed.
4144 The shell will perform brace expansion (@pxref{Brace Expansion}).
4145 This option is on by default.
4148 Prevent output redirection using @samp{>}, @samp{>&}, and @samp{<>}
4149 from overwriting existing files.
4152 Enable @samp{!} style history substitution (@pxref{History Interaction}).
4153 This option is on by default for interactive shells.
4156 If set, do not follow symbolic links when performing commands such as
4157 @code{cd} which change the current directory. The physical directory
4158 is used instead. By default, Bash follows
4159 the logical chain of directories when performing commands
4160 which change the current directory.
4162 For example, if @file{/usr/sys} is a symbolic link to @file{/usr/local/sys}
4165 $ cd /usr/sys; echo $PWD
4172 If @code{set -P} is on, then:
4174 $ cd /usr/sys; echo $PWD
4181 If no arguments follow this option, then the positional parameters are
4182 unset. Otherwise, the positional parameters are set to the
4183 @var{arguments}, even if some of them begin with a @samp{-}.
4186 Signal the end of options, cause all remaining @var{arguments}
4187 to be assigned to the positional parameters. The @samp{-x}
4188 and @samp{-v} options are turned off.
4189 If there are no arguments, the positional parameters remain unchanged.
4192 Using @samp{+} rather than @samp{-} causes these options to be
4193 turned off. The options can also be used upon invocation of the
4194 shell. The current set of options may be found in @code{$-}.
4196 The remaining N @var{arguments} are positional parameters and are
4197 assigned, in order, to @code{$1}, @code{$2}, @dots{} @code{$N}.
4198 The special parameter @code{#} is set to N.
4200 The return status is always zero unless an invalid option is supplied.
4203 @node Bash Conditional Expressions
4204 @section Bash Conditional Expressions
4205 @cindex expressions, conditional
4207 Conditional expressions are used by the @code{[[} compound command
4208 and the @code{test} and @code{[} builtin commands.
4210 Expressions may be unary or binary.
4211 Unary expressions are often used to examine the status of a file.
4212 There are string operators and numeric comparison operators as well.
4213 If any @var{file} argument to one of the primaries is of the form
4214 @file{/dev/fd/@var{N}}, then file descriptor @var{N} is checked.
4218 True if @var{file} exists.
4221 True if @var{file} exists and is a block special file.
4224 True if @var{file} exists and is a character special file.
4227 True if @var{file} exists and is a directory.
4230 True if @var{file} exists.
4233 True if @var{file} exists and is a regular file.
4236 True if @var{file} exists and its set-group-id bit is set.
4239 True if @var{file} exists and its "sticky" bit is set.
4242 True if @var{file} exists and is a named pipe (FIFO).
4245 True if @var{file} exists and is readable.
4248 True if @var{file} exists and has a size greater than zero.
4251 True if file descriptor @var{fd} is open and refers to a terminal.
4254 True if @var{file} exists and its set-user-id bit is set.
4257 True if @var{file} exists and is writable.
4260 True if @var{file} exists and is executable.
4263 True if @var{file} exists and is owned by the effective user id.
4266 True if @var{file} exists and is owned by the effective group id.
4269 True if @var{file} exists and is a symbolic link.
4272 True if @var{file} exists and is a socket.
4275 True if @var{file} exists and has been modified since it was last read.
4277 @item @var{file1} -nt @var{file2}
4278 True if @var{file1} is newer (according to
4279 modification date) than @var{file2}.
4281 @item @var{file1} -ot @var{file2}
4282 True if @var{file1} is older than @var{file2}.
4284 @item @var{file1} -ef @var{file2}
4285 True if @var{file1} and @var{file2} have the same device and
4288 @item -o @var{optname}
4289 True if shell option @var{optname} is enabled.
4290 The list of options appears in the description of the @samp{-o}
4291 option to the @code{set} builtin (@pxref{The Set Builtin}).
4293 @item -z @var{string}
4294 True if the length of @var{string} is zero.
4296 @item -n @var{string}
4298 True if the length of @var{string} is non-zero.
4300 @item @var{string1} == @var{string2}
4301 True if the strings are equal.
4302 @samp{=} may be used in place of @samp{==}.
4304 @item @var{string1} != @var{string2}
4305 True if the strings are not equal.
4307 @item @var{string1} < @var{string2}
4308 True if @var{string1} sorts before @var{string2} lexicographically
4309 in the current locale.
4311 @item @var{string1} > @var{string2}
4312 True if @var{string1} sorts after @var{string2} lexicographically
4313 in the current locale.
4315 @item @var{arg1} OP @var{arg2}
4317 @samp{-eq}, @samp{-ne}, @samp{-lt}, @samp{-le}, @samp{-gt}, or @samp{-ge}.
4318 These arithmetic binary operators return true if @var{arg1}
4319 is equal to, not equal to, less than, less than or equal to,
4320 greater than, or greater than or equal to @var{arg2},
4321 respectively. @var{Arg1} and @var{arg2}
4322 may be positive or negative integers.
4326 @node Bash Variables
4327 @section Bash Variables
4329 These variables are set or used by Bash, but other shells
4330 do not normally treat them specially.
4335 The full pathname used to execute the current instance of Bash.
4338 If this variable is set when Bash is invoked to execute a shell
4339 script, its value is expanded and used as the name of a startup file
4340 to read before executing the script. @xref{Bash Startup Files}.
4343 The version number of the current instance of Bash.
4346 A readonly array variable whose members hold version information for
4347 this instance of Bash.
4348 The values assigned to the array members are as follows:
4352 @item BASH_VERSINFO[0]
4353 The major version number (the @var{release}).
4355 @item BASH_VERSINFO[1]
4356 The minor version number (the @var{version}).
4358 @item BASH_VERSINFO[2]
4361 @item BASH_VERSINFO[3]
4364 @item BASH_VERSINFO[4]
4365 The release status (e.g., @var{beta1}).
4367 @item BASH_VERSINFO[5]
4368 The value of @code{MACHTYPE}.
4373 An array variable (@pxref{Arrays})
4374 containing the current contents of the directory stack.
4375 Directories appear in the stack in the order they are displayed by the
4376 @code{dirs} builtin.
4377 Assigning to members of this array variable may be used to modify
4378 directories already in the stack, but the @code{pushd} and @code{popd}
4379 builtins must be used to add and remove directories.
4380 Assignment to this variable will not change the current directory.
4381 If @code{DIRSTACK} is unset, it loses its special properties, even if
4382 it is subsequently reset.
4385 The numeric effective user id of the current user. This variable
4389 The editor used as a default by the @samp{-e} option to the @code{fc}
4393 A colon-separated list of suffixes to ignore when performing
4394 filename completion.
4395 A file name whose suffix matches one of the entries in
4397 is excluded from the list of matched file names. A sample
4398 value is @samp{.o:~}
4401 A colon-separated list of patterns defining the set of filenames to
4402 be ignored by filename expansion.
4403 If a filename matched by a filename expansion pattern also matches one
4404 of the patterns in @code{GLOBIGNORE}, it is removed from the list
4408 An array variable containing the list of groups of which the current
4409 user is a member. This variable is readonly.
4412 Up to three characters which control history expansion, quick
4413 substitution, and tokenization (@pxref{History Interaction}).
4414 The first character is the
4415 @dfn{history-expansion-char}, that is, the character which signifies the
4416 start of a history expansion, normally @samp{!}. The second character is the
4417 character which signifies `quick substitution' when seen as the first
4418 character on a line, normally @samp{^}. The optional third character is the
4419 character which indicates that the remainder of the line is a comment when
4420 found as the first character of a word, usually @samp{#}. The history
4421 comment character causes history substitution to be skipped for the
4422 remaining words on the line. It does not necessarily cause the shell
4423 parser to treat the rest of the line as a comment.
4426 The history number, or index in the history list, of the current
4427 command. If @code{HISTCMD} is unset, it loses its special properties,
4428 even if it is subsequently reset.
4431 Set to a value of @samp{ignorespace}, it means don't enter lines which
4432 begin with a space or tab into the history list. Set to a value
4433 of @samp{ignoredups}, it means don't enter lines which match the last
4434 entered line. A value of @samp{ignoreboth} combines the two options.
4435 Unset, or set to any other value than those above, means to save
4436 all lines on the history list.
4437 The second and subsequent lines of a multi-line compound command are
4438 not tested, and are added to the history regardless of the value of
4442 A colon-separated list of patterns used to decide which command
4443 lines should be saved on the history list. Each pattern is
4444 anchored at the beginning of the line and must fully specify the
4445 line (no implicit @samp{*} is appended). Each pattern is tested
4446 against the line after the checks specified by @code{HISTCONTROL}
4447 are applied. In addition to the normal shell pattern matching
4448 characters, @samp{&} matches the previous history line. @samp{&}
4449 may be escaped using a backslash. The backslash is removed
4450 before attempting a match.
4451 The second and subsequent lines of a multi-line compound command are
4452 not tested, and are added to the history regardless of the value of
4455 @code{HISTIGNORE} subsumes the function of @code{HISTCONTROL}. A
4456 pattern of @samp{&} is identical to @code{ignoredups}, and a
4457 pattern of @samp{[ ]*} is identical to @code{ignorespace}.
4458 Combining these two patterns, separating them with a colon,
4459 provides the functionality of @code{ignoreboth}.
4462 The name of the file to which the command history is saved. The
4463 default is @file{~/.bash_history}.
4466 The maximum number of commands to remember on the history list.
4467 The default value is 500.
4470 The maximum number of lines contained in the history file. When this
4471 variable is assigned a value, the history file is truncated, if
4472 necessary, to contain no more than that number of lines. The default
4473 value is 500. The history file is also truncated to this size after
4474 writing it when an interactive shell exits.
4477 Contains the name of a file in the same format as @file{/etc/hosts} that
4478 should be read when the shell needs to complete a hostname. You can
4479 change the file interactively; the next time you attempt to complete a
4480 hostname, Bash will add the contents of the new file to the already
4484 The name of the current host.
4487 A string describing the machine Bash is running on.
4490 Controls the action of the shell on receipt of an @code{EOF} character
4491 as the sole input. If set, the value denotes the number
4492 of consecutive @code{EOF} characters that can be read as the
4493 first character on an input line
4494 before the shell will exit. If the variable exists but does not
4495 have a numeric value (or has no value) then the default is 10.
4496 If the variable does not exist, then @code{EOF} signifies the end of
4497 input to the shell. This is only in effect for interactive shells.
4500 The name of the Readline startup file, overriding the default
4501 of @file{~/.inputrc}.
4504 Used to determine the locale category for any category not specifically
4505 selected with a variable starting with @code{LC_}.
4508 This variable overrides the value of @code{LANG} and any other
4509 @code{LC_} variable specifying a locale category.
4512 This variable determines the collation order used when sorting the
4513 results of filename expansion, and
4514 determines the behavior of range expressions, equivalence classes,
4515 and collating sequences within filename expansion and pattern matching
4516 (@pxref{Filename Expansion}).
4519 This variable determines the interpretation of characters and the
4520 behavior of character classes within filename expansion and pattern
4521 matching (@pxref{Filename Expansion}).
4524 This variable determines the locale used to translate double-quoted
4525 strings preceded by a @samp{$} (@pxref{Locale Translation}).
4528 The line number in the script or shell function currently executing.
4531 A string that fully describes the system type on which Bash
4532 is executing, in the standard GNU @var{cpu-company-system} format.
4535 How often (in seconds) that the shell should check for mail in the
4536 files specified in the @code{MAILPATH} or @code{MAIL} variables.
4539 The previous working directory as set by the @code{cd} builtin.
4542 If set to the value 1, Bash displays error messages
4543 generated by the @code{getopts} builtin command.
4546 A string describing the operating system Bash is running on.
4549 An array variable (@pxref{Arrays})
4550 containing a list of exit status values from the processes
4551 in the most-recently-executed foreground pipeline (which may
4552 contain only a single command).
4555 The process id of the shell's parent process. This variable
4558 @item PROMPT_COMMAND
4559 If present, this contains a string which is a command to execute
4560 before the printing of each primary prompt (@code{$PS1}).
4563 The value of this variable is used as the prompt for the
4564 @code{select} command. If this variable is not set, the
4565 @code{select} command prompts with @samp{#? }
4568 This is the prompt printed before the command line is echoed
4569 when the @samp{-x} option is set (@pxref{The Set Builtin}).
4570 The first character of @code{PS4} is replicated multiple times, as
4571 necessary, to indicate multiple levels of indirection.
4572 The default is @samp{+ }.
4575 The current working directory as set by the @code{cd} builtin.
4578 Each time this parameter is referenced, a random integer
4579 between 0 and 32767 is generated. Assigning a value to this
4580 variable seeds the random number generator.
4583 The default variable for the @code{read} builtin.
4586 This variable expands to the number of seconds since the
4587 shell was started. Assignment to this variable resets
4588 the count to the value assigned, and the expanded value
4589 becomes the value assigned plus the number of seconds
4590 since the assignment.
4593 A colon-separated list of enabled shell options. Each word in
4594 the list is a valid argument for the @samp{-o} option to the
4595 @code{set} builtin command (@pxref{The Set Builtin}).
4596 The options appearing in @code{SHELLOPTS} are those reported
4597 as @samp{on} by @samp{set -o}.
4598 If this variable is in the environment when Bash
4599 starts up, each shell option in the list will be enabled before
4600 reading any startup files. This variable is readonly.
4603 Incremented by one each time a new instance of Bash is started. This is
4604 intended to be a count of how deeply your Bash shells are nested.
4607 The value of this parameter is used as a format string specifying
4608 how the timing information for pipelines prefixed with the @code{time}
4609 reserved word should be displayed.
4610 The @samp{%} character introduces an
4611 escape sequence that is expanded to a time value or other
4613 The escape sequences and their meanings are as
4614 follows; the braces denote optional portions.
4621 @item %[@var{p}][l]R
4622 The elapsed time in seconds.
4624 @item %[@var{p}][l]U
4625 The number of CPU seconds spent in user mode.
4627 @item %[@var{p}][l]S
4628 The number of CPU seconds spent in system mode.
4631 The CPU percentage, computed as (%U + %S) / %R.
4634 The optional @var{p} is a digit specifying the precision, the number of
4635 fractional digits after a decimal point.
4636 A value of 0 causes no decimal point or fraction to be output.
4637 At most three places after the decimal point may be specified; values
4638 of @var{p} greater than 3 are changed to 3.
4639 If @var{p} is not specified, the value 3 is used.
4641 The optional @code{l} specifies a longer format, including minutes, of
4642 the form @var{MM}m@var{SS}.@var{FF}s.
4643 The value of @var{p} determines whether or not the fraction is included.
4645 If this variable is not set, Bash acts as if it had the value
4647 @code{$'\nreal\t%3lR\nuser\t%3lU\nsys\t%3lS'}
4649 If the value is null, no timing information is displayed.
4650 A trailing newline is added when the format string is displayed.
4653 If set to a value greater than zero, the value is interpreted as
4654 the number of seconds to wait for input after issuing the primary
4656 Bash terminates after that number of seconds if input does
4660 The numeric real user id of the current user. This variable is readonly.
4664 @node Shell Arithmetic
4665 @section Shell Arithmetic
4666 @cindex arithmetic, shell
4667 @cindex shell arithmetic
4668 @cindex expressions, arithmetic
4669 @cindex evaluation, arithmetic
4670 @cindex arithmetic evaluation
4672 The shell allows arithmetic expressions to be evaluated, as one of
4673 the shell expansions or by the @code{let} builtin.
4675 Evaluation is done in long integers with no check for overflow,
4676 though division by 0 is trapped and flagged as an error. The
4677 following list of operators is grouped into levels of
4678 equal-precedence operators. The levels are listed in order of
4679 decreasing precedence.
4683 unary minus and plus
4686 logical and bitwise negation
4692 multiplication, division, remainder
4695 addition, subtraction
4698 left and right bitwise shifts
4704 equality and inequality
4710 bitwise exclusive OR
4721 @item expr ? expr : expr
4722 conditional evaluation
4724 @item = *= /= %= += -= <<= >>= &= ^= |=
4728 Shell variables are allowed as operands; parameter expansion is
4729 performed before the expression is evaluated.
4730 The value of a parameter is coerced to a long integer within
4731 an expression. A shell variable need not have its integer attribute
4732 turned on to be used in an expression.
4734 Constants with a leading 0 are interpreted as octal numbers.
4735 A leading @samp{0x} or @samp{0X} denotes hexadecimal. Otherwise,
4736 numbers take the form [@var{base}@code{#}]@var{n}, where @var{base}
4737 is a decimal number between 2 and 64 representing the arithmetic
4738 base, and @var{n} is a number in that base. If @var{base} is
4739 omitted, then base 10 is used.
4740 The digits greater than 9 are represented by the lowercase letters,
4741 the uppercase letters, @samp{_}, and @samp{@@}, in that order.
4742 If @var{base} is less than or equal to 36, lowercase and uppercase
4743 letters may be used interchangably to represent numbers between 10
4746 Operators are evaluated in order of precedence. Sub-expressions in
4747 parentheses are evaluated first and may override the precedence
4752 @cindex alias expansion
4755 * Alias Builtins:: Builtins commands to maniuplate aliases.
4758 Aliases allow a string to be substituted for a word when it is used
4759 as the first word of a simple command.
4760 The shell maintains a list of @var{aliases}
4761 that may be set and unset with the @code{alias} and
4762 @code{unalias} builtin commands.
4764 The first word of each simple command, if unquoted, is checked to see
4766 If so, that word is replaced by the text of the alias.
4767 The alias name and the replacement text may contain any valid
4768 shell input, including shell metacharacters, with the exception
4769 that the alias name may not contain @samp{=}.
4770 The first word of the replacement text is tested for
4771 aliases, but a word that is identical to an alias being expanded
4772 is not expanded a second time. This means that one may alias
4773 @code{ls} to @code{"ls -F"},
4774 for instance, and Bash does not try to recursively expand the
4775 replacement text. If the last character of the alias value is a
4776 space or tab character, then the next command word following the
4777 alias is also checked for alias expansion.
4779 Aliases are created and listed with the @code{alias}
4780 command, and removed with the @code{unalias} command.
4782 There is no mechanism for using arguments in the replacement text,
4784 If arguments are needed, a shell function should be used
4785 (@pxref{Shell Functions}).
4787 Aliases are not expanded when the shell is not interactive,
4788 unless the @code{expand_aliases} shell option is set using
4789 @code{shopt} (@pxref{Bash Builtins}).
4791 The rules concerning the definition and use of aliases are
4792 somewhat confusing. Bash
4793 always reads at least one complete line
4794 of input before executing any
4795 of the commands on that line. Aliases are expanded when a
4796 command is read, not when it is executed. Therefore, an
4797 alias definition appearing on the same line as another
4798 command does not take effect until the next line of input is read.
4799 The commands following the alias definition
4800 on that line are not affected by the new alias.
4801 This behavior is also an issue when functions are executed.
4802 Aliases are expanded when a function definition is read,
4803 not when the function is executed, because a function definition
4804 is itself a compound command. As a consequence, aliases
4805 defined in a function are not available until after that
4806 function is executed. To be safe, always put
4807 alias definitions on a separate line, and do not use @code{alias}
4808 in compound commands.
4810 For almost every purpose, aliases are superseded by
4813 @node Alias Builtins
4814 @subsection Alias Builtins
4821 alias [@code{-p}] [@var{name}[=@var{value}] @dots{}]
4824 Without arguments or with the @samp{-p} option, @code{alias} prints
4825 the list of aliases on the standard output in a form that allows
4826 them to be reused as input.
4827 If arguments are supplied, an alias is defined for each @var{name}
4828 whose @var{value} is given. If no @var{value} is given, the name
4829 and value of the alias is printed.
4834 unalias [-a] [@var{name} @dots{} ]
4837 Remove each @var{name} from the list of aliases. If @samp{-a} is
4838 supplied, all aliases are removed.
4845 Bash provides one-dimensional array variables. Any variable may be used as
4846 an array; the @code{declare} builtin will explicitly declare an array.
4848 limit on the size of an array, nor any requirement that members
4849 be indexed or assigned contiguously. Arrays are zero-based.
4851 An array is created automatically if any variable is assigned to using
4854 name[@var{subscript}]=@var{value}
4859 is treated as an arithmetic expression that must evaluate to a number
4860 greater than or equal to zero. To explicitly declare an array, use
4862 declare -a @var{name}
4867 declare -a @var{name}[@var{subscript}]
4870 is also accepted; the @var{subscript} is ignored. Attributes may be
4871 specified for an array variable using the @code{declare} and
4872 @code{readonly} builtins. Each attribute applies to all members of
4875 Arrays are assigned to using compound assignments of the form
4877 name=(value@var{1} @dots{} value@var{n})
4881 @var{value} is of the form @code{[[@var{subscript}]=]}@var{string}. If
4882 the optional subscript is supplied, that index is assigned to;
4883 otherwise the index of the element assigned is the last index assigned
4884 to by the statement plus one. Indexing starts at zero.
4885 This syntax is also accepted by the @code{declare}
4886 builtin. Individual array elements may be assigned to using the
4887 @code{name[}@var{subscript}@code{]=}@var{value} syntax introduced above.
4889 Any element of an array may be referenced using
4890 @code{$@{name[}@var{subscript}@code{]@}}.
4891 The braces are required to avoid
4892 conflicts with the shell's filename expansion operators. If the
4893 @var{subscript} is @samp{@@} or @samp{*}, the word expands to all members
4894 of the array @var{name}. These subscripts differ only when the word
4895 appears within double quotes. If the word is double-quoted,
4896 @code{$@{name[*]@}} expands to a single word with
4897 the value of each array member separated by the first character of the
4898 @code{IFS} variable, and @code{$@{name[@@]@}} expands each element of
4899 @var{name} to a separate word. When there are no array members,
4900 @code{$@{name[@@]@}} expands to nothing. This is analogous to the
4901 expansion of the special parameters @samp{@@} and @samp{*}.
4902 @code{$@{#name[}@var{subscript}@code{]@}} expands to the length of
4903 @code{$@{name[}@var{subscript}@code{]@}}.
4904 If @var{subscript} is @samp{@@} or
4905 @samp{*}, the expansion is the number of elements in the array.
4906 Referencing an array variable without a subscript is equivalent to
4907 referencing element zero.
4909 The @code{unset} builtin is used to destroy arrays.
4910 @code{unset} @code{name[@var{subscript}]}
4911 destroys the array element at index @var{subscript}.
4912 @code{unset} @var{name}, where @var{name} is an array, removes the
4913 entire array. A subscript of @samp{*} or @samp{@@} also removes the
4916 The @code{declare}, @code{local}, and @code{readonly}
4917 builtins each accept a @samp{-a}
4918 option to specify an array. The @code{read}
4919 builtin accepts a @samp{-a}
4920 option to assign a list of words read from the standard input
4921 to an array, and can read values from the standard input into
4922 individual array elements. The @code{set} and @code{declare}
4923 builtins display array values in a way that allows them to be
4926 @node The Directory Stack
4927 @section The Directory Stack
4928 @cindex directory stack
4930 The directory stack is a list of recently-visited directories. The
4931 @code{pushd} builtin adds directories to the stack as it changes
4932 the current directory, and the @code{popd} builtin removes specified
4933 directories from the stack and changes the current directory to
4934 the directory removed. The @code{dirs} builtin displays the contents
4935 of the directory stack.
4937 The contents of the directory stack are also visible
4938 as the value of the @code{DIRSTACK} shell variable.
4945 dirs [+@var{N} | -@var{N}] [-clvp]
4947 Display the list of currently remembered directories. Directories
4948 are added to the list with the @code{pushd} command; the
4949 @code{popd} command removes directories from the list.
4952 Displays the @var{N}th directory (counting from the left of the
4953 list printed by @code{dirs} when invoked without options), starting
4956 Displays the @var{N}th directory (counting from the right of the
4957 list printed by @code{dirs} when invoked without options), starting
4960 Clears the directory stack by deleting all of the elements.
4962 Produces a longer listing; the default listing format uses a
4963 tilde to denote the home directory.
4965 Causes @code{dirs} to print the directory stack with one entry per
4968 Causes @code{dirs} to print the directory stack with one entry per
4969 line, prefixing each entry with its index in the stack.
4975 popd [+@var{N} | -@var{N}] [-n]
4978 Remove the top entry from the directory stack, and @code{cd}
4979 to the new top directory.
4980 When no arguments are given, @code{popd}
4981 removes the top directory from the stack and
4982 performs a @code{cd} to the new top directory. The
4983 elements are numbered from 0 starting at the first directory listed with
4984 @code{dirs}; i.e., @code{popd} is equivalent to @code{popd +0}.
4987 Removes the @var{N}th directory (counting from the left of the
4988 list printed by @code{dirs}), starting with zero.
4990 Removes the @var{N}th directory (counting from the right of the
4991 list printed by @code{dirs}), starting with zero.
4993 Suppresses the normal change of directory when removing directories
4994 from the stack, so that only the stack is manipulated.
5000 pushd [@var{dir} | @var{+N} | @var{-N}] [-n]
5003 Save the current directory on the top of the directory stack
5004 and then @code{cd} to @var{dir}.
5005 With no arguments, @code{pushd} exchanges the top two directories.
5009 Brings the @var{N}th directory (counting from the left of the
5010 list printed by @code{dirs}, starting with zero) to the top of
5011 the list by rotating the stack.
5013 Brings the @var{N}th directory (counting from the right of the
5014 list printed by @code{dirs}, starting with zero) to the top of
5015 the list by rotating the stack.
5017 Suppresses the normal change of directory when adding directories
5018 to the stack, so that only the stack is manipulated.
5020 Makes the current working directory be the top of the stack, and then
5021 executes the equivalent of `@code{cd} @var{dir}'.
5022 @code{cd}s to @var{dir}.
5027 @node Printing a Prompt
5028 @section Controlling the Prompt
5031 The value of the variable @code{PROMPT_COMMAND} is examined just before
5032 Bash prints each primary prompt. If it is set and non-null, then the
5033 value is executed just as if it had been typed on the command line.
5035 In addition, the following table describes the special characters which
5036 can appear in the prompt variables:
5042 The date, in "Weekday Month Date" format (e.g., "Tue May 26").
5044 An escape character.
5046 The hostname, up to the first `.'.
5054 The name of the shell, the basename of @code{$0} (the portion
5055 following the final slash).
5057 The time, in 24-hour HH:MM:SS format.
5059 The time, in 12-hour HH:MM:SS format.
5061 The time, in 12-hour am/pm format.
5063 The username of the current user.
5065 The version of Bash (e.g., 2.00)
5067 The release of Bash, version + patchlevel (e.g., 2.00.0)
5069 The current working directory.
5071 The basename of @code{$PWD}.
5073 The history number of this command.
5075 The command number of this command.
5077 If the effective uid is 0, @code{#}, otherwise @code{$}.
5079 The character whose ASCII code is the octal value @var{nnn}.
5083 Begin a sequence of non-printing characters. This could be used to
5084 embed a terminal control sequence into the prompt.
5086 End a sequence of non-printing characters.
5089 @node The Restricted Shell
5090 @section The Restricted Shell
5091 @cindex restricted shell
5093 If Bash is started with the name @code{rbash}, or the
5095 option is supplied at invocation, the shell becomes restricted.
5096 A restricted shell is used to
5097 set up an environment more controlled than the standard shell.
5098 A restricted shell behaves identically to @code{bash}
5099 with the exception that the following are disallowed:
5102 Changing directories with the @code{cd} builtin.
5104 Setting or unsetting the values of the @code{SHELL} or @code{PATH}
5107 Specifying command names containing slashes.
5109 Specifying a filename containing a slash as an argument to the @code{.}
5112 Importing function definitions from the shell environment at startup.
5114 Parsing the value of @code{SHELLOPTS} from the shell environment at startup.
5116 Redirecting output using the @samp{>}, @samp{>|}, @samp{<>}, @samp{>&},
5117 @samp{&>}, and @samp{>>} redirection operators.
5119 Using the @code{exec} builtin to replace the shell with another command.
5121 Adding or deleting builtin commands with the
5122 @samp{-f} and @samp{-d} options to the @code{enable} builtin.
5124 Specifying the @samp{-p} option to the @code{command} builtin.
5126 Turning off restricted mode with @samp{set +r} or @samp{set +o restricted}.
5129 @node Bash POSIX Mode
5130 @section Bash POSIX Mode
5133 Starting Bash with the @samp{--posix} command-line option or executing
5134 @samp{set -o posix} while Bash is running will cause Bash to conform more
5135 closely to the @sc{POSIX.2} standard by changing the behavior to match that
5136 specified by @sc{POSIX.2} in areas where the Bash default differs.
5138 The following list is what's changed when `@sc{POSIX} mode' is in effect:
5142 When a command in the hash table no longer exists, Bash will re-search
5143 @code{$PATH} to find the new location. This is also available with
5144 @samp{shopt -s checkhash}.
5147 The @samp{>&} redirection does not redirect stdout and stderr.
5150 The message printed by the job control code and builtins when a job
5151 exits with a non-zero status is `Done(status)'.
5154 Reserved words may not be aliased.
5157 The @sc{POSIX.2} @code{PS1} and @code{PS2} expansions of @samp{!} to
5158 the history number and @samp{!!} to @samp{!} are enabled,
5159 and parameter expansion is performed on the values of @code{PS1} and
5160 @code{PS2} regardless of the setting of the @code{promptvars} option.
5163 Interactive comments are enabled by default. (Bash has them on by
5167 The @sc{POSIX.2} startup files are executed (@code{$ENV}) rather than
5168 the normal Bash files.
5171 Tilde expansion is only performed on assignments preceding a command
5172 name, rather than on all assignment statements on the line.
5175 The default history file is @file{~/.sh_history} (this is the
5176 default value of @code{$HISTFILE}).
5179 The output of @samp{kill -l} prints all the signal names on a single line,
5180 separated by spaces.
5183 Non-interactive shells exit if @var{filename} in @code{.} @var{filename}
5187 Non-interactive shells exit if a syntax error in an arithmetic expansion
5188 results in an invalid expression.
5191 Redirection operators do not perform filename expansion on the word
5192 in the redirection unless the shell is interactive.
5195 Function names must be valid shell @code{name}s. That is, they may not
5196 contain characters other than letters, digits, and underscores, and
5197 may not start with a digit. Declaring a function with an invalid name
5198 causes a fatal syntax error in non-interactive shells.
5201 @sc{POSIX.2} `special' builtins are found before shell functions
5202 during command lookup.
5205 If a @sc{POSIX.2} special builtin returns an error status, a
5206 non-interactive shell exits. The fatal errors are those listed in
5207 the POSIX.2 standard, and include things like passing incorrect options,
5208 redirection errors, variable assignment errors for assignments preceding
5209 the command name, and so on.
5212 If the @code{cd} builtin finds a directory to change to
5213 using @code{$CDPATH}, the
5214 value it assigns to the @code{PWD} variable does not contain any
5215 symbolic links, as if @samp{cd -P} had been executed.
5218 If @code{$CDPATH} is set, the @code{cd} builtin will not implicitly
5219 append the current directory to it. This means that @code{cd} will
5220 fail if no valid directory name can be constructed from
5221 any of the entries in @code{$CDPATH}, even if the a directory with
5222 the same name as the name given as an argument to @code{cd} exists
5223 in the current directory.
5226 A non-interactive shell exits with an error status if a variable
5227 assignment error occurs when no command name follows the assignment
5229 A variable assignment error occurs, for example, when trying to assign
5230 a value to a readonly variable.
5233 A non-interactive shell exits with an error status if the iteration
5234 variable in a @code{for} statement or the selection variable in a
5235 @code{select} statement is a readonly variable.
5238 Process substitution is not available.
5241 Assignment statements preceding @sc{POSIX.2} special builtins
5242 persist in the shell environment after the builtin completes.
5245 The @code{export} and @code{readonly} builtin commands display their
5246 output in the format required by @sc{POSIX.2}.
5250 There is other @sc{POSIX.2} behavior that Bash does not implement.
5255 Assignment statements affect the execution environment of all
5256 builtins, not just special ones.
5260 @chapter Job Control
5262 This chapter discusses what job control is, how it works, and how
5263 Bash allows you to access its facilities.
5266 * Job Control Basics:: How job control works.
5267 * Job Control Builtins:: Bash builtin commands used to interact
5269 * Job Control Variables:: Variables Bash uses to customize job
5273 @node Job Control Basics
5274 @section Job Control Basics
5278 @cindex suspending jobs
5281 refers to the ability to selectively stop (suspend)
5282 the execution of processes and continue (resume)
5283 their execution at a later point. A user typically employs
5284 this facility via an interactive interface supplied jointly
5285 by the system's terminal driver and Bash.
5287 The shell associates a @var{job} with each pipeline. It keeps a
5288 table of currently executing jobs, which may be listed with the
5289 @code{jobs} command. When Bash starts a job
5290 asynchronously, it prints a line that looks
5296 indicating that this job is job number 1 and that the process @sc{ID}
5297 of the last process in the pipeline associated with this job is
5298 25647. All of the processes in a single pipeline are members of
5299 the same job. Bash uses the @var{job} abstraction as the
5300 basis for job control.
5302 To facilitate the implementation of the user interface to job
5303 control, the system maintains the notion of a current terminal
5304 process group @sc{ID}. Members of this process group (processes whose
5305 process group @sc{ID} is equal to the current terminal process group
5306 @sc{ID}) receive keyboard-generated signals such as @code{SIGINT}.
5307 These processes are said to be in the foreground. Background
5308 processes are those whose process group @sc{ID} differs from the
5309 terminal's; such processes are immune to keyboard-generated
5310 signals. Only foreground processes are allowed to read from or
5311 write to the terminal. Background processes which attempt to
5312 read from (write to) the terminal are sent a @code{SIGTTIN}
5313 (@code{SIGTTOU}) signal by the terminal driver, which, unless
5314 caught, suspends the process.
5316 If the operating system on which Bash is running supports
5317 job control, Bash contains facilities to use it. Typing the
5318 @var{suspend} character (typically @samp{^Z}, Control-Z) while a
5319 process is running causes that process to be stopped and returns
5320 control to Bash. Typing the @var{delayed suspend} character
5321 (typically @samp{^Y}, Control-Y) causes the process to be stopped
5322 when it attempts to read input from the terminal, and control to
5323 be returned to Bash. The user then manipulates the state of
5324 this job, using the @code{bg} command to continue it in the
5325 background, the @code{fg} command to continue it in the
5326 foreground, or the @code{kill} command to kill it. A @samp{^Z}
5327 takes effect immediately, and has the additional side effect of
5328 causing pending output and typeahead to be discarded.
5330 There are a number of ways to refer to a job in the shell. The
5331 character @samp{%} introduces a job name. Job number @code{n}
5332 may be referred to as @samp{%n}. A job may also be referred to
5333 using a prefix of the name used to start it, or using a substring
5334 that appears in its command line. For example, @samp{%ce} refers
5335 to a stopped @code{ce} job. Using @samp{%?ce}, on the
5336 other hand, refers to any job containing the string @samp{ce} in
5337 its command line. If the prefix or substring matches more than one job,
5338 Bash reports an error. The symbols @samp{%%} and
5339 @samp{%+} refer to the shell's notion of the current job, which
5340 is the last job stopped while it was in the foreground or started
5341 in the background. The
5342 previous job may be referenced using @samp{%-}. In output
5343 pertaining to jobs (e.g., the output of the @code{jobs} command),
5344 the current job is always flagged with a @samp{+}, and the
5345 previous job with a @samp{-}.
5347 Simply naming a job can be used to bring it into the foreground:
5348 @samp{%1} is a synonym for @samp{fg %1}, bringing job 1 from the
5349 background into the foreground. Similarly, @samp{%1 &} resumes
5350 job 1 in the background, equivalent to @samp{bg %1}
5352 The shell learns immediately whenever a job changes state.
5353 Normally, Bash waits until it is about to print a prompt
5354 before reporting changes in a job's status so as to not interrupt
5355 any other output. If the
5356 the @samp{-b} option to the @code{set} builtin is enabled,
5357 Bash reports such changes immediately (@pxref{The Set Builtin}).
5359 If an attempt to exit Bash is while jobs are stopped, the
5360 shell prints a message warning that there are stopped jobs.
5361 The @code{jobs} command may then be used to inspect their status.
5362 If a second attempt to exit is made without an intervening command,
5363 Bash does not print another warning, and the stopped jobs are terminated.
5365 @node Job Control Builtins
5366 @section Job Control Builtins
5375 Resume the suspended job @var{jobspec} in the background, as if it
5376 had been started with @samp{&}.
5377 If @var{jobspec} is not supplied, the current job is used.
5378 The return status is zero unless it is run when job control is not
5379 enabled, or, when run with job control enabled, if @var{jobspec} was
5380 not found or @var{jobspec} specifies a job that was started without
5388 Resume the job @var{jobspec} in the foreground and make it the current job.
5389 If @var{jobspec} is not supplied, the current job is used.
5390 The return status is that of the command placed into the foreground,
5391 or non-zero if run when job control is disabled or, when run with
5392 job control enabled, @var{jobspec} does not specify a valid job or
5393 @var{jobspec} specifies a job that was started without job control.
5398 jobs [-lpnrs] [@var{jobspec}]
5399 jobs -x @var{command} [@var{arguments}]
5402 The first form lists the active jobs. The options have the
5407 List process @sc{ID}s in addition to the normal information.
5410 Display information only about jobs that have changed status since
5411 the user was last notified of their status.
5414 List only the process @sc{ID} of the job's process group leader.
5417 Restrict output to running jobs.
5420 Restrict output to stopped jobs.
5423 If @var{jobspec} is given,
5424 output is restricted to information about that job.
5425 If @var{jobspec} is not supplied, the status of all jobs is
5428 If the @samp{-x} option is supplied, @code{jobs} replaces any
5429 @var{jobspec} found in @var{command} or @var{arguments} with the
5430 corresponding process group @sc{ID}, and executes @var{command},
5431 passing it @var{argument}s, returning its exit status.
5436 kill [-s @var{sigspec}] [-n @var{signum}] [-@var{sigspec}] @var{jobspec} or @var{pid}
5437 kill -l [@var{exit_status}]
5439 Send a signal specified by @var{sigspec} or @var{signum} to the process
5440 named by job specification @var{jobspec} or process ID @var{pid}.
5441 @var{sigspec} is either a signal name such as @code{SIGINT} (with or without
5442 the @code{SIG} prefix) or a signal number; @var{signum} is a signal number.
5443 If @var{sigspec} and @var{signum} are not present, @code{SIGTERM} is used.
5444 The @samp{-l} option lists the signal names.
5445 If any arguments are supplied when @samp{-l} is given, the names of the
5446 signals corresponding to the arguments are listed, and the return status
5448 @var{exit_status} is a number specifying a signal number or the exit
5449 status of a process terminated by a signal.
5450 The return status is zero if at least one signal was successfully sent,
5451 or non-zero if an error occurs or an invalid option is encountered.
5456 wait [@var{jobspec}|@var{pid}]
5458 Wait until the child process specified by process @sc{ID} @var{pid} or job
5459 specification @var{jobspec} exits and return the exit status of the last
5461 If a job spec is given, all processes in the job are waited for.
5462 If no arguments are given, all currently active child processes are
5463 waited for, and the return status is zero.
5464 If neither @var{jobspec} nor @var{pid} specifies an active child process
5465 of the shell, the return status is 127.
5470 disown [-ar] [-h] [@var{jobspec} @dots{}]
5472 Without options, each @var{jobspec} is removed from the table of
5474 If the @samp{-h} option is given, the job is not removed from the table,
5475 but is marked so that @code{SIGHUP} is not sent to the job if the shell
5476 receives a @code{SIGHUP}.
5477 If @var{jobspec} is not present, and neither the @samp{-a} nor @samp{-r}
5478 option is supplied, the current job is used.
5479 If no @var{jobspec} is supplied, the @samp{-a} option means to remove or
5480 mark all jobs; the @samp{-r} option without a @var{jobspec}
5481 argument restricts operation to running jobs.
5488 Suspend the execution of this shell until it receives a
5489 @code{SIGCONT} signal. The @samp{-f} option means to suspend
5490 even if the shell is a login shell.
5494 When job control is not active, the @code{kill} and @code{wait}
5495 builtins do not accept @var{jobspec} arguments. They must be
5496 supplied process @sc{ID}s.
5498 @node Job Control Variables
5499 @section Job Control Variables
5504 This variable controls how the shell interacts with the user and
5505 job control. If this variable exists then single word simple
5506 commands without redirections are treated as candidates for resumption
5507 of an existing job. There is no ambiguity allowed; if there is
5508 more than one job beginning with the string typed, then
5509 the most recently accessed job will be selected.
5510 The name of a stopped job, in this context, is the command line
5511 used to start it. If this variable is set to the value @samp{exact},
5512 the string supplied must match the name of a stopped job exactly;
5513 if set to @samp{substring},
5514 the string supplied needs to match a substring of the name of a
5515 stopped job. The @samp{substring} value provides functionality
5516 analogous to the @samp{%?} job @sc{ID} (@pxref{Job Control Basics}).
5517 If set to any other value, the supplied string must
5518 be a prefix of a stopped job's name; this provides functionality
5519 analogous to the @samp{%} job @sc{ID}.
5523 @set readline-appendix
5524 @set history-appendix
5525 @cindex History, how to use
5526 @include hsuser.texinfo
5527 @cindex Readline, how to use
5528 @include rluser.texinfo
5529 @clear readline-appendix
5530 @clear history-appendix
5532 @node Installing Bash
5533 @chapter Installing Bash
5535 This chapter provides basic instructions for installing Bash on
5536 the various supported platforms. The distribution supports nearly every
5537 version of Unix (and, someday, @sc{GNU}). Other independent ports exist for
5538 @sc{MS-DOS}, @sc{OS/2}, Windows @sc{95}, and Windows @sc{NT}.
5541 * Basic Installation:: Installation instructions.
5543 * Compilers and Options:: How to set special options for various
5546 * Compiling For Multiple Architectures:: How to compile Bash for more
5547 than one kind of system from
5548 the same source tree.
5550 * Installation Names:: How to set the various paths used by the installation.
5552 * Specifying the System Type:: How to configure Bash for a particular system.
5554 * Sharing Defaults:: How to share default configuration values among GNU
5557 * Operation Controls:: Options recognized by the configuration program.
5559 * Optional Features:: How to enable and disable optional features when
5563 @node Basic Installation
5564 @section Basic Installation
5565 @cindex installation
5566 @cindex configuration
5567 @cindex Bash installation
5568 @cindex Bash configuration
5570 These are installation instructions for Bash.
5572 The @code{configure} shell script attempts to guess correct
5573 values for various system-dependent variables used during
5574 compilation. It uses those values to create a @file{Makefile} in
5575 each directory of the package (the top directory, the
5576 @file{builtins} and @file{doc} directories, and the
5577 each directory under @file{lib}). It also creates a
5578 @file{config.h} file containing system-dependent definitions.
5579 Finally, it creates a shell script named @code{config.status} that you
5580 can run in the future to recreate the current configuration, a
5581 file @file{config.cache} that saves the results of its tests to
5582 speed up reconfiguring, and a file @file{config.log} containing
5583 compiler output (useful mainly for debugging @code{configure}).
5585 @file{config.cache} contains results you don't want to keep, you
5586 may remove or edit it.
5588 If you need to do unusual things to compile Bash, please
5589 try to figure out how @code{configure} could check whether or not
5590 to do them, and mail diffs or instructions to
5591 @email{bash-maintainers@@gnu.org} so they can be
5592 considered for the next release.
5594 The file @file{configure.in} is used to create @code{configure}
5595 by a program called Autoconf. You only need
5596 @file{configure.in} if you want to change it or regenerate
5597 @code{configure} using a newer version of Autoconf. If
5598 you do this, make sure you are using Autoconf version 2.10 or
5601 If you need to change @file{configure.in} or regenerate
5602 @code{configure}, you will need to create two files:
5603 @file{_distribution} and @file{_patchlevel}. @file{_distribution}
5604 should contain the major and minor version numbers of the Bash
5605 distribution, for example @samp{2.01}. @file{_patchlevel} should
5606 contain the patch level of the Bash distribution, @samp{0} for
5607 example. The script @file{support/mkconffiles} has been provided
5608 to automate the creation of these files.
5610 The simplest way to compile Bash is:
5614 @code{cd} to the directory containing the source code and type
5615 @samp{./configure} to configure Bash for your system. If you're
5616 using @code{csh} on an old version of System V, you might need to
5617 type @samp{sh ./configure} instead to prevent @code{csh} from trying
5618 to execute @code{configure} itself.
5620 Running @code{configure} takes awhile. While running, it prints some
5621 messages telling which features it is checking for.
5624 Type @samp{make} to compile Bash and build the @code{bashbug} bug
5628 Optionally, type @samp{make tests} to run the Bash test suite.
5631 Type @samp{make install} to install @code{bash} and @code{bashbug}.
5632 This will also install the manual pages and Info file.
5636 You can remove the program binaries and object files from the
5637 source code directory by typing @samp{make clean}. To also remove the
5638 files that @code{configure} created (so you can compile Bash for
5639 a different kind of computer), type @samp{make distclean}.
5641 @node Compilers and Options
5642 @section Compilers and Options
5644 Some systems require unusual options for compilation or linking
5645 that the @code{configure} script does not know about. You can
5646 give @code{configure} initial values for variables by setting
5647 them in the environment. Using a Bourne-compatible shell, you
5648 can do that on the command line like this:
5651 CC=c89 CFLAGS=-O2 LIBS=-lposix ./configure
5654 On systems that have the @code{env} program, you can do it like this:
5657 env CPPFLAGS=-I/usr/local/include LDFLAGS=-s ./configure
5660 The configuration process uses GCC to build Bash if it
5663 @node Compiling For Multiple Architectures
5664 @section Compiling For Multiple Architectures
5666 You can compile Bash for more than one kind of computer at the
5667 same time, by placing the object files for each architecture in their
5668 own directory. To do this, you must use a version of @code{make} that
5669 supports the @code{VPATH} variable, such as GNU @code{make}.
5671 directory where you want the object files and executables to go and run
5672 the @code{configure} script from the source directory. You may need to
5673 supply the @samp{--srcdir=PATH} argument to tell @code{configure} where the
5674 source files are. @code{configure} automatically checks for the
5675 source code in the directory that @code{configure} is in and in `..'.
5677 If you have to use a @code{make} that does not supports the @code{VPATH}
5678 variable, you can compile Bash for one architecture at a
5679 time in the source code directory. After you have installed
5680 Bash for one architecture, use @samp{make distclean} before
5681 reconfiguring for another architecture.
5683 Alternatively, if your system supports symbolic links, you can use the
5684 @file{support/mkclone} script to create a build tree which has
5685 symbolic links back to each file in the source directory. Here's an
5686 example that creates a build directory in the current directory from a
5687 source directory @file{/usr/gnu/src/bash-2.0}:
5690 bash /usr/gnu/src/bash-2.0/support/mkclone -s /usr/gnu/src/bash-2.0 .
5694 The @code{mkclone} script requires Bash, so you must have already built
5695 Bash for at least one architecture before you can create build
5696 directories for other architectures.
5698 @node Installation Names
5699 @section Installation Names
5701 By default, @samp{make install} will install into
5702 @file{/usr/local/bin}, @file{/usr/local/man}, etc. You can
5703 specify an installation prefix other than @file{/usr/local} by
5704 giving @code{configure} the option @samp{--prefix=PATH}.
5706 You can specify separate installation prefixes for
5707 architecture-specific files and architecture-independent files.
5708 If you give @code{configure} the option
5709 @samp{--exec-prefix=PATH}, @samp{make install} will use @samp{PATH} as the
5710 prefix for installing programs and libraries. Documentation and
5711 other data files will still use the regular prefix.
5713 @node Specifying the System Type
5714 @section Specifying the System Type
5716 There may be some features @code{configure} can not figure out
5717 automatically, but needs to determine by the type of host Bash
5718 will run on. Usually @code{configure} can figure that
5719 out, but if it prints a message saying it can not guess the host
5720 type, give it the @samp{--host=TYPE} option. @samp{TYPE} can
5721 either be a short name for the system type, such as @samp{sun4},
5722 or a canonical name with three fields: @samp{CPU-COMPANY-SYSTEM}
5723 (e.g., @samp{sparc-sun-sunos4.1.2}).
5725 @noindent See the file @file{support/config.sub} for the possible
5726 values of each field.
5728 @node Sharing Defaults
5729 @section Sharing Defaults
5731 If you want to set default values for @code{configure} scripts to
5732 share, you can create a site shell script called
5733 @code{config.site} that gives default values for variables like
5734 @code{CC}, @code{cache_file}, and @code{prefix}. @code{configure}
5735 looks for @file{PREFIX/share/config.site} if it exists, then
5736 @file{PREFIX/etc/config.site} if it exists. Or, you can set the
5737 @code{CONFIG_SITE} environment variable to the location of the site
5738 script. A warning: the Bash @code{configure} looks for a site script,
5739 but not all @code{configure} scripts do.
5741 @node Operation Controls
5742 @section Operation Controls
5744 @code{configure} recognizes the following options to control how it
5749 @item --cache-file=@var{FILE}
5750 Use and save the results of the tests in
5751 @var{FILE} instead of @file{./config.cache}. Set @var{FILE} to
5752 @file{/dev/null} to disable caching, for debugging
5756 Print a summary of the options to @code{configure}, and exit.
5761 Do not print messages saying which checks are being made.
5763 @item --srcdir=@var{DIR}
5764 Look for the Bash source code in directory @var{DIR}. Usually
5765 @code{configure} can determine that directory automatically.
5768 Print the version of Autoconf used to generate the @code{configure}
5772 @code{configure} also accepts some other, not widely used, boilerplate
5775 @node Optional Features
5776 @section Optional Features
5778 The Bash @code{configure} has a number of @samp{--enable-@var{FEATURE}}
5779 options, where @var{FEATURE} indicates an optional part of Bash.
5780 There are also several @samp{--with-@var{PACKAGE}} options,
5781 where @var{PACKAGE} is something like @samp{gnu-malloc} or @samp{purify}.
5782 To turn off the default use of a package, use
5783 @samp{--without-@var{PACKAGE}}. To configure Bash without a feature
5784 that is enabled by default, use @samp{--disable-@var{FEATURE}}.
5786 Here is a complete list of the @samp{--enable-} and
5787 @samp{--with-} options that the Bash @code{configure} recognizes.
5791 Define if you are using the Andrew File System from Transarc.
5794 Use the curses library instead of the termcap library. This should
5795 be supplied if your system has an inadequate or incomplete termcap
5798 @item --with-glibc-malloc
5799 Use the @sc{GNU} libc version of @code{malloc} in
5800 @file{lib/malloc/gmalloc.c}. This is not the version of @code{malloc}
5801 that appears in glibc version 2, but a modified version of the
5802 @code{malloc} from glibc version 1. This is somewhat slower than the
5803 default @code{malloc}, but wastes less space on a per-allocation
5804 basis, and will return memory to the operating system under
5807 @item --with-gnu-malloc
5808 Use the @sc{GNU} version of
5809 @code{malloc} in @file{lib/malloc/malloc.c}. This is not the same
5810 @code{malloc} that appears in @sc{GNU} libc, but an older version
5811 derived from the 4.2 @sc{BSD} @code{malloc}. This @code{malloc} is
5812 very fast, but wastes some space on each allocation.
5813 This option is enabled by default.
5814 The @file{NOTES} file contains a list of systems for
5815 which this should be turned off, and @code{configure} disables this
5816 option automatically for a number of systems.
5819 Define this to use the Purify memory allocation checker from Pure
5822 @item --enable-minimal-config
5823 This produces a shell with minimal features, close to the historical
5827 There are several @samp{--enable-} options that alter how Bash is
5828 compiled and linked, rather than changing run-time features.
5831 @item --enable-profiling
5832 This builds a Bash binary that produces profiling information to be
5833 processed by @code{gprof} each time it is executed.
5835 @item --enable-static-link
5836 This causes Bash to be linked statically, if @code{gcc} is being used.
5837 This could be used to build a version to use as root's shell.
5840 The @samp{minimal-config} option can be used to disable all of
5841 the following options, but it is processed first, so individual
5842 options may be enabled using @samp{enable-@var{FEATURE}}.
5844 All of the following options except for @samp{disabled-builtins} and
5845 @samp{usg-echo-default} are
5846 enabled by default, unless the operating system does not provide the
5850 @item --enable-alias
5851 Allow alias expansion and include the @code{alias} and @code{unalias}
5852 builtins (@pxref{Aliases}).
5854 @item --enable-array-variables
5855 Include support for one-dimensional array shell variables
5858 @item --enable-bang-history
5859 Include support for @code{csh}-like history substitution
5860 (@pxref{History Interaction}).
5862 @item --enable-brace-expansion
5863 Include @code{csh}-like brace expansion
5864 ( @code{b@{a,b@}c} @expansion{} @code{bac bbc} ).
5865 See @ref{Brace Expansion}, for a complete description.
5867 @item --enable-command-timing
5868 Include support for recognizing @code{time} as a reserved word and for
5869 displaying timing statistics for the pipeline following @code{time}. This
5870 allows pipelines as well as shell builtins and functions to be timed.
5872 @item --enable-cond-command
5873 Include support for the @code{[[} conditional command
5874 (@pxref{Conditional Constructs}).
5876 @item --enable-directory-stack
5877 Include support for a @code{csh}-like directory stack and the
5878 @code{pushd}, @code{popd}, and @code{dirs} builtins
5879 (@pxref{The Directory Stack}).
5881 @item --enable-disabled-builtins
5882 Allow builtin commands to be invoked via @samp{builtin xxx}
5883 even after @code{xxx} has been disabled using @samp{enable -n xxx}.
5884 See @ref{Bash Builtins}, for details of the @code{builtin} and
5885 @code{enable} builtin commands.
5887 @item --enable-dparen-arithmetic
5888 Include support for the @code{((@dots{}))} command
5889 (@pxref{Conditional Constructs}).
5891 @item --enable-extended-glob
5892 Include support for the extended pattern matching features described
5893 above under @ref{Pattern Matching}.
5895 @item --enable-help-builtin
5896 Include the @code{help} builtin, which displays help on shell builtins and
5899 @item --enable-history
5900 Include command history and the @code{fc} and @code{history}
5903 @item --enable-job-control
5904 This enables the job control features (@pxref{Job Control}),
5905 if the operating system supports them.
5907 @item --enable-process-substitution
5908 This enables process substitution (@pxref{Process Substitution}) if
5909 the operating system provides the necessary support.
5911 @item --enable-prompt-string-decoding
5912 Turn on the interpretation of a number of backslash-escaped characters
5913 in the @code{$PS1}, @code{$PS2}, @code{$PS3}, and @code{$PS4} prompt
5914 strings. See @ref{Printing a Prompt}, for a complete list of prompt
5915 string escape sequences.
5917 @item --enable-readline
5918 Include support for command-line editing and history with the Bash
5919 version of the Readline library (@pxref{Command Line Editing}).
5921 @item --enable-restricted
5922 Include support for a @dfn{restricted shell}. If this is enabled, Bash,
5923 when called as @code{rbash}, enters a restricted mode. See
5924 @ref{The Restricted Shell}, for a description of restricted mode.
5926 @item --enable-select
5927 Include the @code{select} builtin, which allows the generation of simple
5928 menus (@pxref{Conditional Constructs}).
5930 @item --enable-usg-echo-default
5931 Make the @code{echo} builtin expand backslash-escaped characters by default,
5932 without requiring the @samp{-e} option. This makes the Bash @code{echo}
5933 behave more like the System V version.
5937 The file @file{config.h.top} contains C Preprocessor
5938 @samp{#define} statements for options which are not settable from
5940 Some of these are not meant to be changed; beware of the consequences if
5942 Read the comments associated with each definition for more
5943 information about its effect.
5945 @node Reporting Bugs
5946 @appendix Reporting Bugs
5948 Please report all bugs you find in Bash.
5949 But first, you should
5950 make sure that it really is a bug, and that it appears in the latest
5951 version of Bash that you have.
5953 Once you have determined that a bug actually exists, use the
5954 @code{bashbug} command to submit a bug report.
5955 If you have a fix, you are encouraged to mail that as well!
5956 Suggestions and `philosophical' bug reports may be mailed
5957 to @email{bug-bash@@gnu.org} or posted to the Usenet
5958 newsgroup @code{gnu.bash.bug}.
5960 All bug reports should include:
5963 The version number of Bash.
5965 The hardware and operating system.
5967 The compiler used to compile Bash.
5969 A description of the bug behaviour.
5971 A short script or `recipe' which exercises the bug and may be used
5976 @code{bashbug} inserts the first three items automatically into
5977 the template it provides for filing a bug report.
5979 Please send all reports concerning this manual to
5980 @email{chet@@po.CWRU.Edu}.
5983 @appendix Index of Shell Builtin Commands
5986 @node Reserved Word Index
5987 @appendix Shell Reserved Words
5990 @node Variable Index
5991 @appendix Parameter and Variable Index
5994 @node Function Index
5995 @appendix Function Index
5999 @appendix Concept Index