1 \input texinfo.tex @c -*- texinfo -*-
3 @setfilename bashref.info
4 @settitle Bash Reference Manual
8 last change: Mon Nov 25 11:47:06 EST 1996
13 @set UPDATED 25 November 1996
14 @set UPDATE-MONTH November 1996
20 @setchapternewpage odd
27 This text is a brief description of the features that are present in
30 This is Edition @value{EDITION}, last updated @value{UPDATED},
31 of @cite{The GNU Bash Reference Manual},
32 for @code{Bash}, Version @value{VERSION}.
34 Copyright (C) 1991, 1993, 1996 Free Software Foundation, Inc.
36 Permission is granted to make and distribute verbatim copies of
37 this manual provided the copyright notice and this permission notice
38 are preserved on all copies.
41 Permission is granted to process this file through TeX and print the
42 results, provided the printed document carries copying permission
43 notice identical to this one except for the removal of this paragraph
44 (this paragraph not being relevant to the printed manual).
47 Permission is granted to copy and distribute modified versions of this
48 manual under the conditions for verbatim copying, provided that the entire
49 resulting derived work is distributed under the terms of a permission
50 notice identical to this one.
52 Permission is granted to copy and distribute translations of this manual
53 into another language, under the above conditions for modified versions,
54 except that this permission notice may be stated in a translation approved
60 @title Bash Reference Manual
61 @subtitle Reference Documentation for Bash
62 @subtitle Edition @value{EDITION}, for @code{bash} Version @value{VERSION}.
63 @subtitle @value{UPDATED}
64 @author Chet Ramey, Case Western Reserve University
65 @author Brian Fox, Free Software Foundation
67 @vskip 0pt plus 1filll
68 Copyright @copyright{} 1991, 1993, 1996 Free Software Foundation, Inc.
70 Permission is granted to make and distribute verbatim copies of
71 this manual provided the copyright notice and this permission notice
72 are preserved on all copies.
74 Permission is granted to copy and distribute modified versions of this
75 manual under the conditions for verbatim copying, provided that the entire
76 resulting derived work is distributed under the terms of a permission
77 notice identical to this one.
79 Permission is granted to copy and distribute translations of this manual
80 into another language, under the above conditions for modified versions,
81 except that this permission notice may be stated in a translation approved
82 by the Free Software Foundation.
86 @node Top, Introduction, (dir), (dir)
91 This text is a brief description of the features that are present in
94 This is Edition @value{EDITION}, last updated @value{UPDATED},
95 of @cite{The GNU Bash Reference Manual},
96 for @code{Bash}, Version @value{VERSION}.
98 Copyright (C) 1991, 1993, 1996 Free Software Foundation, Inc.
100 Bash contains features that appear in other popular shells, and some
101 features that only appear in Bash. Some of the shells that Bash has
102 borrowed concepts from are the Bourne Shell (@file{sh}), the Korn Shell
103 (@file{ksh}), and the C-shell (@file{csh} and its successor,
104 @file{tcsh}). The following menu breaks the features up into
105 categories based upon which one of these other shells inspired the
108 This manual is meant as a brief introduction to features found in
109 Bash. The Bash manual page should be used as the definitive
110 reference on shell behavior.
113 * Introduction:: An introduction to the shell.
115 * Definitions:: Some definitions used in the rest of this
118 * Basic Shell Features:: The shell "building blocks".
120 * Bourne Shell Features:: Features similar to those found in the
123 * Csh Features:: Features originally found in the
126 * Korn Shell Features:: Features originally found in the Korn
129 * Bash Features:: Features found only in Bash.
131 * Job Control:: A chapter describing what job control is
132 and how Bash allows you to use it.
134 * Using History Interactively:: Chapter dealing with history expansion
137 * Command Line Editing:: Chapter describing the command line
140 * Installing Bash:: How to build and install Bash on your system.
142 * Reporting Bugs:: How to report bugs in Bash.
144 * Builtin Index:: Index of Bash builtin commands.
146 * Reserved Word Index:: Index of Bash reserved words.
148 * Variable Index:: Quick reference helps you find the
151 * Function Index:: Index of bindable Readline functions.
153 * Concept Index:: General index for concepts described in
159 @chapter Introduction
161 * What is Bash?:: A short description of Bash.
163 * What is a shell?:: A brief introduction to shells.
167 @section What is Bash?
169 Bash is the shell, or command language interpreter,
170 that will appear in the @sc{GNU} operating system.
171 The name is an acronym for the @samp{Bourne-Again SHell},
172 a pun on Steve Bourne, the author of the direct ancestor of the current
173 Unix shell @code{/bin/sh},
174 which appeared in the Seventh Edition Bell Labs Research version
177 Bash is an @code{sh}-compatible shell that incorporates useful
178 features from the Korn shell @code{ksh} and the C shell @code{csh}.
179 It is ultimately intended to be a
180 conformant implementation of the @sc{IEEE} @sc{POSIX} Shell and Tools
181 specification (@sc{IEEE} Working Group 1003.2). It offers functional
182 improvements over @code{sh} for both interactive and programming use.
184 While the @sc{GNU} operating system will include a version
185 of @code{csh}, Bash will be the default shell.
186 Like other @sc{GNU} software, Bash is quite portable. It currently runs
187 on nearly every version of Unix and a few other operating systems @minus{}
188 independently-supported ports exist for @sc{OS/2} 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. The shell reads commands either from a terminal or a
198 file. Files containing commands can be created, and become
199 commands themselves. These new commands have the same status as
200 system commands in directories like @file{/bin}, allowing users
201 or groups to establish custom environments.
203 A shell allows execution of Unix commands, both synchronously and
204 asynchronously. The @dfn{redirection} constructs permit
205 fine-grained control of the input and output of those commands,
206 and the shell allows control over the contents of their
207 environment. Unix shells also provide a small set of built-in
208 commands (@dfn{builtins}) implementing functionality impossible
209 (e.g., @code{cd}, @code{break}, @code{continue}, and
210 @code{exec}), or inconvenient (@code{history}, @code{getopts},
211 @code{kill}, or @code{pwd}, for example) to obtain via separate
212 utilities. Shells may be used interactively or
213 non-interactively: they accept input typed from the keyboard or
214 from a file. All of the shell builtins are described in
217 While executing commands is essential, most of the power (and
218 complexity) of shells is due to their embedded programming
219 languages. Like any high-level language, the shell provides
220 variables, flow control constructs, quoting, and functions.
222 Shells have begun offering features geared specifically for
223 interactive use rather than to augment the programming language.
224 These interactive features include job control, command line
225 editing, history and aliases. Each of these features is
226 described in this manual.
230 These definitions are used throughout the remainder of this manual.
236 A family of open system standards based on Unix. Bash
237 is concerned with @sc{POSIX} 1003.2, the Shell and Tools Standard.
240 A space or tab character.
244 A command that is implemented internally by the shell itself, rather
245 than by an executable program somewhere in the file system.
247 @item control operator
248 @cindex control operator
249 A @code{word} that performs a control function. It is a @code{newline}
250 or one of the following:
251 @samp{||}, @samp{&&}, @samp{&}, @samp{;}, @samp{;;},
252 @samp{|}, @samp{(}, or @samp{)}.
256 The value returned by a command to its caller.
260 A unit of text that is the result of one of the shell expansions. After
261 expansion, when executing a command, the resulting fields are used as
262 the command name and arguments.
266 A string of characters used to identify a file.
270 A set of processes comprising a pipeline, and any processes descended
271 from it, that are all in the same process group.
275 A mechanism by which users can selectively start and stop execution
279 @cindex metacharacter
280 A character that, when unquoted, separates words. A metacharacter is
281 a @code{blank} or one of the following characters:
282 @samp{|}, @samp{&}, @samp{;}, @samp{(}, @samp{)}, @samp{<}, or
288 A @code{word} consisting solely of letters, numbers, and underscores,
289 and beginning with a letter or underscore. @code{Name}s are used as
290 shell variable and function names.
291 Also referred to as an @code{identifier}.
294 @cindex operator, shell
295 A @code{control operator} or a @code{redirection operator}.
296 @xref{Redirections}, for a list of redirection operators.
299 @cindex process group
300 A collection of related processes each having the same process
303 @item process group ID
304 @cindex process group ID
305 A unique identifer that represents a @code{process group}
309 @cindex reserved word
310 A @code{word} that has a special meaning to the shell. Most reserved
311 words introduce shell flow control constructs, such as @code{for} and
315 @cindex return status
316 A synonym for @code{exit status}.
320 A mechanism by which a process may be notified by the kernal
321 of an event occurring in the system.
323 @item special builtin
324 @cindex special builtin
325 A shell builtin command that has been classified as special by the
326 @sc{POSIX.2} standard.
330 A sequence of characters considered a single unit by the shell. It is
331 either a @code{word} or an @code{operator}.
335 A @code{token} that is not an @code{operator}.
338 @node Basic Shell Features
339 @chapter Basic Shell Features
342 Bash is an acronym for @samp{Bourne-Again SHell}.
344 the traditional Unix shell originally written by Stephen Bourne.
345 All of the Bourne shell builtin commands are available in Bash,
346 and the rules for evaluation and quoting are taken from the @sc{POSIX}
347 1003.2 specification for the `standard' Unix shell.
349 This chapter briefly summarizes the shell's "building blocks":
350 commands, control structures, shell functions, shell @i{parameters},
352 @i{redirections}, which are a way to direct input and output from
353 and to named files, and how the shell executes commands.
356 * Shell Syntax:: What your input means to the shell.
357 * Simple Commands:: The most common type of command.
358 * Pipelines:: Connecting the input and output of several
360 * Lists:: How to execute commands sequentially.
361 * Looping Constructs:: Shell commands for iterative action.
362 * Conditional Constructs:: Shell commands for conditional execution.
363 * Command Grouping:: Ways to group commands.
364 * Shell Functions:: Grouping commands by name.
365 * Shell Parameters:: Special shell variables.
366 * Shell Expansions:: How Bash expands variables and the various
367 expansions available.
368 * Redirections:: A way to control where input and output go.
369 * Executing Commands:: What happens when you run a command.
370 * Shell Scripts:: Executing files of shell commands.
374 @section Shell Syntax
376 * Shell Operation:: The basic operation of the shell.
378 * Quoting:: How to remove the special meaning from characters.
380 * Comments:: How to specify comments.
383 @node Shell Operation
384 @subsection Shell Operation
386 The following is a brief description of the shell's operation when it
387 reads and executes a command. Basically, the shell does the
392 Reads its input from a file (@pxref{Shell Scripts}), from a string
393 supplied as an argument to the @samp{-c} invocation option
394 (@pxref{Invoking Bash}), or from the user's terminal.
397 Breaks the input into words and operators, obeying the quoting rules
398 described in @ref{Quoting}. Tokens are separated by
399 @code{metacharacters}. Alias expansion is performed by this step
403 Parses the tokens into simple and compound commands.
406 Performs the various shell expansions (@pxref{Shell Expansions}), breaking
407 the expanded tokens into lists of filenames (@pxref{Filename Expansion})
408 and commands and arguments.
411 Performs any necessary redirections (@pxref{Redirections}) and removes
412 the redirection operators and their operands from the argument list.
415 Executes the command (@pxref{Executing Commands}).
418 Optionally waits for the command to complete and collects its exit
427 * Escape Character:: How to remove the special meaning from a single
429 * Single Quotes:: How to inhibit all interpretation of a sequence
431 * Double Quotes:: How to suppress most of the interpretation of a
432 sequence of characters.
433 * ANSI-C Quoting:: How to expand ANSI-C sequences in quoted strings.
435 * Locale Translation:: How to translate strings into different languages.
438 Quoting is used to remove the special meaning of certain
439 characters or words to the shell. Quoting can be used to
440 disable special treatment for special characters, to prevent
441 reserved words from being recognized as such, and to prevent
444 Each of the shell @code{metacharacters} (@pxref{Definitions})
445 has special meaning to the shell and must be quoted if they are to
446 represent themselves. There are three quoting mechanisms: the
447 @var{escape character}, single quotes, and double quotes.
449 @node Escape Character
450 @subsubsection Escape Character
451 A non-quoted backslash @samp{\} is the Bash escape character.
452 It preserves the literal value of the next character that follows,
453 with the exception of @code{newline}. If a @code{\newline} pair
454 appears, and the backslash is not quoted, the @code{\newline}
455 is treated as a line continuation (that is, it is effectively ignored).
458 @subsubsection Single Quotes
460 Enclosing characters in single quotes preserves the literal value
461 of each character within the quotes. A single quote may not occur
462 between single quotes, even when preceded by a backslash.
465 @subsubsection Double Quotes
467 Enclosing characters in double quotes preserves the literal value
468 of all characters within the quotes, with the exception of
469 @samp{$}, @samp{`}, and @samp{\}.
470 The characters @samp{$} and @samp{`}
471 retain their special meaning within double quotes. The backslash
472 retains its special meaning only when followed by one of the following
474 @samp{$}, @samp{`}, @samp{"}, @samp{\}, or @code{newline}.
475 A double quote may be quoted within double quotes by preceding it with
478 The special parameters @samp{*} and @samp{@@} have special meaning
479 when in double quotes (@pxref{Shell Parameter Expansion}).
482 @subsubsection ANSI-C Quoting
483 @cindex quoting, ANSI
485 Words of the form @code{$'@var{string}'} are treated specially. The
486 word expands to @var{string}, with backslash-escaped characters replaced
487 as specifed by the ANSI C standard. Backslash escape sequences, if
488 present, are decoded as follows:
496 an escape character (not ANSI C)
510 the character whose @code{ASCII} code is @var{nnn} in octal
514 The result is single-quoted, as if the dollar sign had not been present.
516 @node Locale Translation
517 @subsubsection Locale-Specific Translation
520 A double-quoted string preceded by a dollar sign (@samp{$}) will cause
521 the string to be translated according to the current locale.
522 If the current locale is @code{C} or @code{POSIX}, the dollar sign
524 If the string is translated and replaced, the replacement is
529 @cindex comments, shell
531 In a non-interactive shell, or an interactive shell in which the
532 @code{interactive_comments} option to the @code{shopt}
533 builtin is enabled (@pxref{Bash Builtins}),
534 a word beginning with @samp{#}
535 causes that word and all remaining characters on that line to
536 be ignored. An interactive shell without the @code{interactive_comments}
537 option enabled does not allow comments. The @code{interactive_comments}
538 option is on by default in interactive shells.
540 @node Simple Commands
541 @section Simple Commands
542 @cindex commands, simple
544 A simple command is the kind of command you'll encounter most often.
545 It's just a sequence of words separated by @code{blank}s, terminated
546 by one of the shell control operators (@pxref{Definitions}). The
547 first word generally specifies a command to be executed.
549 The return status (@pxref{Exit Status}) of a simple command is
550 its exit status as provided
551 by the @sc{POSIX.1} @code{waitpid} function, or 128+@var{n} if the command
552 was terminated by signal @var{n}.
557 @cindex commands, pipelines
559 A @code{pipeline} is a sequence of simple commands separated by
564 @cindex command timing
565 The format for a pipeline is
567 [@code{time} [@code{-p}]] [@code{!}] @var{command1} [@code{|} @var{command2} @dots{}]
571 The output of each command in the pipeline is connected to the input of
572 the next command. That is, each command reads the previous command's
575 The reserved word @code{time} causes timing statistics
576 to be printed for the pipeline once it finishes.
577 The @samp{-p} option changes the output format to that specified
579 The @code{TIMEFORMAT} variable may be set to a format string that
580 specifies how the timing information should be displayed.
581 @xref{Bash Variables}, for a description of the available formats.
583 Each command in a pipeline is executed in its own subshell. The exit
584 status of a pipeline is the exit status of the last command in the
585 pipeline. If the reserved word @samp{!} precedes the pipeline, the
586 exit status is the logical @sc{NOT} of the exit status of the last command.
589 @section Lists of Commands
590 @cindex commands, lists
592 A @code{list} is a sequence of one or more pipelines separated by one
593 of the operators @samp{;}, @samp{&}, @samp{&&}, or @samp{||},
594 and optionally terminated by one of @samp{;}, @samp{&}, or a
597 Of these list operators, @samp{&&} and @samp{||}
598 have equal precedence, followed by @samp{;} and @samp{&},
599 which have equal precedence.
601 If a command is terminated by the control operator @samp{&},
602 the shell executes the command in the @var{background}
603 in a subshell. The shell does not wait for the command to
604 finish, and the return status is 0 (true). Commands separated by a
605 @samp{;} are executed sequentially; the shell waits for each
606 command to terminate in turn. The return status is the
607 exit status of the last command executed.
609 The control operators @samp{&&} and @samp{||}
610 denote @sc{AND} lists and @sc{OR} lists, respectively.
611 An @sc{AND} list has the form
613 @var{command} && @var{command2}
617 @var{command2} is executed if, and only if, @var{command}
618 returns an exit status of zero.
620 An @sc{OR} list has the form
622 @var{command} || @var{command2}
626 @var{command2} is executed if and only if @var{command}
627 returns a non-zero exit status.
630 @sc{AND} and @sc{OR} lists is the exit status of the last command
631 executed in the list.
633 @node Looping Constructs
634 @section Looping Constructs
635 @cindex commands, looping
637 Note that wherever you see a @samp{;} in the description of a
638 command's syntax, it may be replaced indiscriminately with
639 one or more newlines.
641 Bash supports the following looping constructs.
648 The syntax of the @code{until} command is:
650 until @var{test-commands}; do @var{consequent-commands}; done
652 Execute @var{consequent-commands} as long as the final command in
653 @var{test-commands} has an exit status which is not zero.
657 The syntax of the @code{while} command is:
659 while @var{test-commands}; do @var{consequent-commands}; done
662 Execute @var{consequent-commands} as long as the final command in
663 @var{test-commands} has an exit status of zero.
667 The syntax of the @code{for} command is:
670 for @var{name} [in @var{words} @dots{}]; do @var{commands}; done
672 Execute @var{commands} for each member in @var{words}, with @var{name}
673 bound to the current member. If @samp{in @var{words}} is not
674 present, @samp{in "$@@"} is assumed.
678 The @code{break} and @code{continue} builtins (@pxref{Bourne Shell Builtins})
679 may be used to control loop execution.
681 @node Conditional Constructs
682 @section Conditional Constructs
683 @cindex commands, conditional
692 The syntax of the @code{if} command is:
695 if @var{test-commands}; then
696 @var{consequent-commands};
697 [elif @var{more-test-commands}; then
698 @var{more-consequents};]
699 [else @var{alternate-consequents};]
703 Execute @var{consequent-commands} only if the final command in
704 @var{test-commands} has an exit status of zero.
705 Otherwise, each @code{elif} list is executed in turn,
706 and if its exit status is zero,
707 the corresponding @var{more-consequents} is executed and the
709 If @samp{else @var{alternate-consequents}} is present, and
710 the final command in the final @code{if} or @code{elif} clause
711 has a non-zero exit status, then execute @var{alternate-consequents}.
717 The syntax of the @code{case} command is:
720 @code{case @var{word} in [@var{pattern} [| @var{pattern}]@dots{}) @var{commands} ;;]@dots{} esac}
723 Selectively execute @var{commands} based upon @var{word} matching
724 @var{pattern}. The @samp{|} is used to separate multiple patterns.
726 Here is an example using @code{case} in a script that could be used to
727 describe one interesting feature of an animal:
730 echo -n "Enter the name of an animal: "
732 echo -n "The $ANIMAL has "
734 horse | dog | cat) echo -n "four";;
735 man | kangaroo ) echo -n "two";;
736 *) echo -n "an unknown number of";;
743 (( @var{expression} ))
746 The @var{expression} is evaluated according to the rules described
747 below ((@pxref{Arithmetic Evaluation}).
748 If the value of the expression is non-zero, the return status is 0;
749 otherwise the return status is 1. This is exactly equivalent to
751 let "@var{expression}"
756 The @code{select} construct, which allows users to choose from a list
757 of items presented as a menu, is also available.
758 @xref{Korn Shell Constructs}, for a full description of @code{select}.
760 @node Command Grouping
761 @section Grouping Commands
762 @cindex commands, grouping
764 Bash provides two ways to group a list of commands to be executed
765 as a unit. When commands are grouped, redirections may be applied
766 to the entire command list. For example, the output of all the
767 commands in the list may be redirected to a single stream.
775 Placing a list of commands between parentheses causes a subshell
776 to be created, and each of the commands to be executed in that
777 subshell. Since the @var{list} is executed in a subshell, variable
778 assignments do not remain in effect after the subshell completes.
787 Placing a list of commands between curly braces causes the list to
788 be executed in the current shell context. No subshell is created.
789 The semicolon following @var{list} is required.
792 In addition to the creation of a subshell, there is a subtle difference
793 between these two constructs due to historical reasons. The braces
794 are @code{reserved words}, so they must be separated from the @var{list}
795 by @code{blank}s. The parentheses are @code{operators}, and are
796 recognized as separate tokens by the shell even if they are not separated
797 from @code{list} by whitespace.
799 The exit status of both of these constructs is the exit status of
802 @node Shell Functions
803 @section Shell Functions
804 @cindex shell function
805 @cindex functions, shell
807 Shell functions are a way to group commands for later execution
808 using a single name for the group. They are executed just like
809 a "regular" command. Shell functions are executed in the current
810 shell context; no new process is created to interpret them.
812 Functions are declared using this syntax:
815 [ @code{function} ] @var{name} () @{ @var{command-list}; @}
818 This defines a shell function named @var{name}. The reserved
819 word @code{function} is optional. The @var{body} of the
820 function is the @var{command-list} between @{ and @}. This list
821 is executed whenever @var{name} is specified as the
822 name of a command. The exit status of a function is
823 the exit status of the last command executed in the body.
825 When a function is executed, the arguments to the
826 function become the positional parameters
827 during its execution (@pxref{Positional Parameters}).
828 The special parameter
829 @samp{#} that gives the number of positional parameters
830 is updated to reflect the change. Positional parameter @code{0}
833 If the builtin command @code{return}
834 is executed in a function, the function completes and
835 execution resumes with the next command after the function
836 call. When a function completes, the values of the
837 positional parameters and the special parameter @samp{#}
838 are restored to the values they had prior to function
839 execution. If a numeric argument is given to @code{return},
840 that is the function return status.
842 Variables local to the function may be declared with the
843 @code{local} builtin. These variables are visible only to
844 the function and the commands it invokes.
846 Functions may be recursive. No limit is placed on the number of
849 @node Shell Parameters
850 @section Shell Parameters
852 @cindex variable, shell
853 @cindex shell variable
856 * Positional Parameters:: The shell's command-line arguments.
857 * Special Parameters:: Parameters with special meanings.
860 A @var{parameter} is an entity that stores values.
861 It can be a @code{name}, a number, or one of the special characters
863 For the shell's purposes, a @var{variable} is a parameter denoted by a
866 A parameter is set if it has been assigned a value. The null string is
867 a valid value. Once a variable is set, it may be unset only by using
868 the @code{unset} builtin command.
870 A variable may be assigned to by a statement of the form
872 @var{name}=[@var{value}]
876 is not given, the variable is assigned the null string. All
877 @var{value}s undergo tilde expansion, parameter and variable expansion,
878 command substitution, arithmetic expansion, and quote
879 removal (detailed below). If the variable has its @samp{-i} attribute
880 set (see the description of the @code{declare} builtin in
881 @ref{Bash Builtins}), then @var{value}
882 is subject to arithmetic expansion even if the @code{$((@dots{}))}
883 syntax does not appear (@pxref{Arithmetic Expansion}).
884 Word splitting is not performed, with the exception
885 of @code{"$@@"} as explained below.
886 Filename expansion is not performed.
888 @node Positional Parameters
889 @subsection Positional Parameters
890 @cindex parameters, positional
892 A @var{positional parameter}
893 is a parameter denoted by one or more
894 digits, other than the single digit @code{0}. Positional parameters are
895 assigned from the shell's arguments when it is invoked,
896 and may be reassigned using the @code{set}
897 builtin command. Positional parameters may not be assigned to
898 with assignment statements. The positional parameters are
899 temporarily replaced when a shell function is executed
900 (@pxref{Shell Functions}).
902 When a positional parameter consisting of more than a single
903 digit is expanded, it must be enclosed in braces.
905 @node Special Parameters
906 @subsection Special Parameters
907 @cindex parameters, special
909 The shell treats several parameters specially. These parameters may
910 only be referenced; assignment to them is not allowed.
915 Expands to the positional parameters, starting from one. When the
916 expansion occurs within double quotes, it expands to a single word
917 with the value of each parameter separated by the first character
919 special variable. That is, @code{"$*"} is equivalent
920 to @code{"$1@var{c}$2@var{c}@dots{}"}, where @var{c}
921 is the first character of the value of the @code{IFS}
922 variable. If @code{IFS}
923 is null or unset, the parameters are separated by spaces.
926 Expands to the positional parameters, starting from one. When the
927 expansion occurs within double quotes, each parameter expands as a
928 separate word. That is, @code{"$@@"} is equivalent to
929 @code{"$1" "$2" @dots{}}.
930 When there are no positional parameters, @code{"$@@"} and
932 expand to nothing (i.e., they are removed).
935 Expands to the number of positional parameters in decimal.
938 Expands to the exit status of the most recently executed foreground
942 Expands to the current option flags as specified upon invocation,
944 builtin command, or those set by the shell itself
945 (such as the @samp{-i} option).
948 Expands to the process @sc{ID} of the shell. In a @code{()} subshell, it
949 expands to the process @sc{ID} of the current shell, not the
953 Expands to the process @sc{ID} of the most recently executed background
954 (asynchronous) command.
957 Expands to the name of the shell or shell script. This is set at
958 shell initialization. If Bash is invoked with a file of commands,
959 @code{$0} is set to the name of that file. If Bash
960 is started with the @samp{-c} option, then @code{$0}
961 is set to the first argument after the string to be
962 executed, if one is present. Otherwise, it is set
963 to the filename used to invoke Bash, as given by argument zero.
966 At shell startup, set to the absolute filename of the shell or shell
967 script being executed as passed in the argument list.
968 Subsequently, expands to the last argument to the previous command,
970 Also set to the full filename of each command executed and placed in
971 the environment exported to that command.
972 When checking mail, this parameter holds the name of the mail file.
975 @node Shell Expansions
976 @section Shell Expansions
979 Expansion is performed on the command line after it has been split into
980 @code{token}s. There are seven kinds of expansion performed:
982 @item brace expansion
983 @item tilde expansion
984 @item parameter and variable expansion
985 @item command substitution
986 @item arithmetic expansion
988 @item filename expansion
992 * Shell Parameter Expansion:: How Bash expands variables to their values.
993 * Command Substitution:: Using the output of a command as an argument.
994 * Process Substitution:: A way to write and read to and from a
996 * Word Splitting:: How the results of expansion are split into separate
998 * Filename Expansion:: A shorthand for specifying filenames matching patterns.
999 * Quote Removal:: How and when quote characters are removed from
1003 Brace expansion, tilde expansion, and arithmetic expansion are described
1004 in other sections. For brace expansion, see @ref{Brace Expansion}; for
1005 tilde expansion, see @ref{Tilde Expansion}; and for arithmetic expansion,
1006 see @ref{Arithmetic Expansion}.
1008 The order of expansions is: brace expansion, tilde expansion,
1009 parameter, variable, and arithmetic expansion and
1010 command substitution
1011 (done in a left-to-right fashion), word splitting, and filename
1014 On systems that can support it, there is an additional expansion
1015 available: @var{process substitution}. This is performed at the
1016 same time as parameter, variable, and arithemtic expansion and
1017 command substitution.
1019 Only brace expansion, word splitting, and filename expansion
1020 can change the number of words of the expansion; other expansions
1021 expand a single word to a single word.
1022 The only exceptions to this are the expansions of
1023 @code{"$@@"} (@pxref{Special Parameters}) and @code{"$@{[@@]@}"}
1026 After all expansions, @code{quote removal} (@pxref{Quote Removal})
1029 @node Shell Parameter Expansion
1030 @subsection Shell Parameter Expansion
1031 @cindex parameter expansion
1032 @cindex expansion, parameter
1034 The @samp{$} character introduces parameter expansion,
1035 command substitution, or arithmetic expansion. The parameter name
1036 or symbol to be expanded may be enclosed in braces, which
1037 are optional but serve to protect the variable to be expanded from
1038 characters immediately following it which could be
1039 interpreted as part of the name.
1041 The basic form of parameter expansion is $@{@var{parameter}@}.
1042 The value of @var{parameter} is substituted. The braces are required
1043 when @var{parameter}
1044 is a positional parameter with more than one digit,
1045 or when @var{parameter}
1046 is followed by a character that is not to be
1047 interpreted as part of its name.
1049 If the first character of @var{parameter} is an exclamation point,
1050 a level of variable indirection is introduced.
1051 Bash uses the value of the variable formed from the rest of
1052 @var{parameter} as the name of the variable; this variable is then
1053 expanded and that value used in the rest of the substitution, rather
1054 than the value of @var{parameter} itself.
1055 This is known as @code{indirect expansion}.
1057 In each of the cases below, @var{word} is subject to tilde expansion,
1058 parameter expansion, command substitution, and arithmetic expansion.
1059 When not performing substring expansion, Bash tests for a parameter
1060 that is unset or null; omitting the colon results in a test only for a
1061 parameter that is unset.
1065 @item $@{@var{parameter}:@minus{}@var{word}@}
1066 If @var{parameter} is unset or null, the expansion of
1067 @var{word} is substituted. Otherwise, the value of
1068 @var{parameter} is substituted.
1070 @item $@{@var{parameter}:=@var{word}@}
1072 is unset or null, the expansion of @var{word}
1073 is assigned to @var{parameter}.
1074 The value of @var{parameter}
1075 is then substituted. Positional parameters and special parameters may
1076 not be assigned to in this way.
1078 @item $@{@var{parameter}:?@var{word}@}
1080 is null or unset, the expansion of @var{word} (or a message
1081 to that effect if @var{word}
1082 is not present) is written to the standard error and the shell, if it
1083 is not interactive, exits. Otherwise, the value of @var{parameter} is
1086 @item $@{@var{parameter}:+@var{word}@}
1088 is null or unset, nothing is substituted, otherwise the expansion of
1089 @var{word} is substituted.
1091 @item $@{@var{parameter}:@var{offset}@}
1092 @itemx $@{@var{parameter}:@var{offset}:@var{length}@}
1093 Expands to up to @var{length} characters of @var{parameter},
1094 starting at @var{offset}.
1095 If @var{length} is omitted, expands to the substring of
1096 @var{parameter}, starting at the character specified by @var{offset}.
1097 @var{length} and @var{offset} are arithmetic expressions
1098 (@pxref{Arithmetic Evaluation}).
1099 This is referred to as Substring Expansion.
1101 @var{length} must evaluate to a number greater than or equal to zero.
1102 If @var{offset} evaluates to a number less than zero, the value
1103 is used as an offset from the end of the value of @var{parameter}.
1104 If @var{parameter} is @samp{@@}, the result is @var{length} positional
1105 parameters beginning at @var{offset}.
1106 If @var{parameter} is an array name indexed by @samp{@@} or @samp{*},
1107 the result is the @var{length}
1108 members of the array beginning with $@{@var{parameter}[@var{offset}]@}.
1109 Substring indexing is zero-based unless the positional parameters are
1110 used, in which case the indexing starts at 1.
1112 @item $@{#@var{parameter}@}
1113 The length in characters of the value of @var{parameter} is substituted.
1115 is @samp{*} or @samp{@@},
1116 the length substituted is the number of positional parameters.
1118 is an array name subscripted
1119 by @samp{*} or @samp{@@},
1120 the length substituted is the number of elements in the array.
1122 @item $@{@var{parameter}#@var{word}@}
1123 @itemx $@{@var{parameter}##@var{word}@}
1125 is expanded to produce a pattern just as in filename
1126 expansion (@pxref{Filename Expansion}). If the pattern matches
1127 the beginning of the value of @var{parameter},
1128 then the expansion is the value of @var{parameter}
1129 with the shortest matching pattern (the @samp{#} case) or the
1130 longest matching pattern (the @samp{##} case) deleted.
1131 If @var{parameter} is @samp{@@} or @samp{*},
1132 the pattern removal operation is applied to each positional
1133 parameter in turn, and the expansion is the resultant list.
1134 If @var{parameter} is an array variable subscripted with
1135 @samp{@@} or @samp{*},
1136 the pattern removal operation is applied to each member of the
1137 array in turn, and the expansion is the resultant list.
1139 @item $@{@var{parameter}%@var{word}@}
1140 @itemx $@{@var{parameter}%%@var{word}@}
1141 The @var{word} is expanded to produce a pattern just as in
1143 If the pattern matches a trailing portion of the value of
1144 @var{parameter}, then the expansion is the value of @var{parameter}
1145 with the shortest matching pattern (the @samp{%} case) or the
1146 longest matching pattern (the @samp{%%} case) deleted.
1147 If @var{parameter} is @samp{@@} or @samp{*},
1148 the pattern removal operation is applied to each positional
1149 parameter in turn, and the expansion is the resultant list.
1151 is an array variable subscripted with @samp{@@} or @samp{*},
1152 the pattern removal operation is applied to each member of the
1153 array in turn, and the expansion is the resultant list.
1155 @item $@{@var{parameter}/@var{pattern}/@var{string}@}
1156 @itemx $@{@var{parameter}//@var{pattern}/@var{string}@}
1158 The @var{pattern} is expanded to produce a pattern just as in
1160 @var{Parameter} is expanded and the longest match of @var{pattern}
1161 against its value is replaced with @var{string}.
1162 In the first form, only the first match is replaced.
1163 The second form causes all matches of @var{pattern} to be
1164 replaced with @var{string}.
1165 If @var{pattern} begins with @samp{#}, it must match at the beginning
1167 If @var{pattern} begins with @samp{%}, it must match at the end
1169 If @var{string} is null, matches of @var{pattern} are deleted
1170 and the @code{/} following @var{pattern} may be omitted.
1171 If @var{parameter} is @samp{@@} or @samp{*},
1172 the substitution operation is applied to each positional
1173 parameter in turn, and the expansion is the resultant list.
1175 is an array variable subscripted with @samp{@@} or @samp{*},
1176 the substitution operation is applied to each member of the
1177 array in turn, and the expansion is the resultant list.
1181 @node Command Substitution
1182 @subsection Command Substitution
1183 @cindex command substitution
1185 Command substitution allows the output of a command to replace
1186 the command name. There are two forms:
1197 Bash performs the expansion by executing @var{command} and
1198 replacing the command substitution with the standard output of the
1199 command, with any trailing newlines deleted.
1201 When the old-style backquote form of substitution is used,
1202 backslash retains its literal meaning except when followed by
1203 @samp{$}, @samp{`}, or @samp{\}.
1204 When using the @code{$(@var{command})} form, all characters between
1205 the parentheses make up the command; none are treated specially.
1207 Command substitutions may be nested. To nest when using the old form,
1208 escape the inner backquotes with backslashes.
1210 If the substitution appears within double quotes, word splitting and
1211 filename expansion are not performed on the results.
1213 @node Process Substitution
1214 @subsection Process Substitution
1215 @cindex process substitution
1217 Process substitution is supported on systems that support named
1218 pipes (@sc{FIFO}s) or the @file{/dev/fd} method of naming open files.
1219 It takes the form of
1229 The process @var{list} is run with its input or output connected to a
1230 @sc{FIFO} or some file in @file{/dev/fd}. The name of this file is
1231 passed as an argument to the current command as the result of the
1232 expansion. If the @code{>(@var{list})} form is used, writing to
1233 the file will provide input for @var{list}. If the
1234 @code{<(@var{list})} form is used, the file passed as an
1235 argument should be read to obtain the output of @var{list}.
1237 On systems that support it, process substitution is performed
1238 simultaneously with parameter and variable expansion,
1239 command substitution, and arithmetic expansion.
1241 @node Word Splitting
1242 @subsection Word Splitting
1243 @cindex word splitting
1245 The shell scans the results of parameter expansion, command substitution,
1246 and arithmetic expansion that did not occur within double quotes for
1249 The shell treats each character of @code{$IFS}
1250 as a delimiter, and splits the results of the other
1251 expansions into words on these characters. If
1252 @code{IFS} is unset, or its value is exactly @code{<space><tab><newline>},
1253 the default, then any sequence of @code{IFS}
1254 characters serves to delimit words. If @code{IFS}
1255 has a value other than the default, then sequences of
1256 the whitespace characters @code{space} and @code{tab}
1257 are ignored at the beginning and end of the
1258 word, as long as the whitespace character is in the
1259 value of @code{IFS} (an @code{IFS} whitespace character).
1260 Any character in @code{IFS} that is not @code{IFS}
1261 whitespace, along with any adjacent @code{IFS}
1262 whitespace characters, delimits a field. A sequence of @code{IFS}
1263 whitespace characters is also treated as a delimiter.
1264 If the value of @code{IFS} is null, no word splitting occurs.
1266 Explicit null arguments (@code{""} or @code{''}) are retained.
1267 Unquoted implicit null arguments, resulting from the expansion of
1269 that have no values, are removed.
1270 If a parameter with no value is expanded within double quotes, a
1271 null argument results and is retained.
1273 Note that if no expansion occurs, no splitting
1276 @node Filename Expansion
1277 @subsection Filename Expansion
1278 @cindex expansion, filename
1279 @cindex expansion, pathname
1280 @cindex filename expansion
1281 @cindex pathname expansion
1283 After word splitting,
1284 unless the @samp{-f}
1285 option has been set (@pxref{The Set Builtin}),
1286 Bash scans each word for the characters
1287 @samp{*}, @samp{?}, and @samp{[}.
1288 If one of these characters appears, then the word is
1289 regarded as a @var{pattern},
1290 and replaced with an alphabetically sorted list of
1291 file names matching the pattern. If no matching file names are found,
1292 and the shell option @code{nullglob} is disabled, the word is left
1293 unchanged. If the option is set, and no matches are found, the word
1294 is removed. When a pattern is used for filename generation,
1295 the character @samp{.}
1296 at the start of a filename or immediately following a slash
1297 must be matched explicitly, unless the shell option @code{dotglob}
1298 is set. The slash character must always be matched explicitly.
1299 In other cases, the @samp{.} character is not treated specially.
1300 See the description of @code{shopt} in @ref{Bash Builtins},
1301 for a description of the @code{nullglob} and @code{dotglob} options.
1303 The @code{GLOBIGNORE}
1304 shell variable may be used to restrict the set of filenames matching a
1305 @var{pattern}. If @code{GLOBIGNORE}
1306 is set, each matching filename that also matches one of the patterns in
1307 @code{GLOBIGNORE} is removed from the list of matches. The filenames
1308 @file{.} and @file{..}
1309 are always ignored, even when @code{GLOBIGNORE}.
1310 is set. However, setting @code{GLOBIGNORE} has the effect of
1311 enabling the @code{dotglob}
1312 shell option, so all other filenames beginning with a
1313 @samp{.} will match.
1314 To get the old behavior of ignoring filenames beginning with a
1315 @samp{.}, make @samp{.*} one of the patterns in @code{GLOBIGNORE}.
1316 The @code{dotglob} option is disabled when @code{GLOBIGNORE}
1319 The special pattern characters have the following meanings:
1322 Matches any string, including the null string.
1324 Matches any single character.
1326 Matches any one of the enclosed characters. A pair of characters
1327 separated by a minus sign denotes a @var{range};
1328 any character lexically between those two characters, inclusive,
1329 is matched. If the first character following the
1330 @samp{[} is a @samp{!} or a @samp{^}
1331 then any character not enclosed is matched. A @samp{@minus{}}
1332 may be matched by including it as the first or last character
1333 in the set. A @samp{]} may be matched by including it as the first
1334 character in the set.
1338 @subsection Quote Removal
1340 After the preceding expansions, all unquoted occurrences of the
1341 characters @samp{\}, @samp{'}, and @samp{"} that did not
1342 result from one of the above expansions are removed.
1345 @section Redirections
1348 Before a command is executed, its input and output
1349 may be @var{redirected}
1350 using a special notation interpreted by the shell.
1351 Redirection may also be used to open and close files for the
1352 current shell execution environment. The following redirection
1353 operators may precede or appear anywhere within a
1354 simple command or may follow a command.
1355 Redirections are processed in the order they appear, from
1358 In the following descriptions, if the file descriptor number is
1359 omitted, and the first character of the redirection operator is
1360 @samp{<}, the redirection refers to the standard input (file
1361 descriptor 0). If the first character of the redirection operator
1362 is @samp{>}, the redirection refers to the standard output (file
1365 The word that follows the redirection operator in the following
1366 descriptions is subjected to brace expansion, tilde expansion,
1367 parameter expansion, command substitution, arithmetic expansion,
1368 quote removal, and filename expansion. If it expands to more
1369 than one word, Bash reports an error.
1371 Note that the order of redirections is significant. For example,
1374 ls > @var{dirlist} 2>&1
1377 directs both standard output and standard error to the file
1378 @var{dirlist}, while the command
1380 ls 2>&1 > @var{dirlist}
1383 directs only the standard output to file @var{dirlist},
1384 because the standard error was duplicated as standard output
1385 before the standard output was redirected to @var{dirlist}.
1387 @subsection Redirecting Input
1388 Redirection of input causes the file whose name results from
1389 the expansion of @var{word}
1390 to be opened for reading on file descriptor @code{n},
1391 or the standard input (file descriptor 0) if @code{n}
1394 The general format for redirecting input is:
1399 @subsection Redirecting Output
1400 Redirection of output causes the file whose name results from
1401 the expansion of @var{word}
1402 to be opened for writing on file descriptor @code{n},
1403 or the standard output (file descriptor 1) if @code{n}
1404 is not specified. If the file does not exist it is created;
1405 if it does exist it is truncated to zero size.
1407 The general format for redirecting output is:
1412 If the redirection operator is @samp{>}, and the @samp{-C} option to the
1413 @code{set} builtin has been enabled, the redirection will fail if the
1414 filename whose name results from the expansion of @var{word} exists.
1415 If the redirection operator is @samp{>|},
1416 then the value of the @samp{-C} option to the @code{set}
1417 builtin command is not tested, and the redirection is attempted even
1418 if the file named by @var{word} exists.
1420 @subsection Appending Redirected Output
1421 Redirection of output in this fashion
1422 causes the file whose name results from
1423 the expansion of @var{word}
1424 to be opened for appending on file descriptor @code{n},
1425 or the standard output (file descriptor 1) if @code{n}
1426 is not specified. If the file does not exist it is created.
1428 The general format for appending output is:
1433 @subsection Redirecting Standard Output and Standard Error
1434 Bash allows both the
1435 standard output (file descriptor 1) and
1436 the standard error output (file descriptor 2)
1437 to be redirected to the file whose name is the
1438 expansion of @var{word} with this construct.
1440 There are two formats for redirecting standard output and
1451 Of the two forms, the first is preferred.
1452 This is semantically equivalent to
1457 @subsection Here Documents
1458 This type of redirection instructs the shell to read input from the
1459 current source until a line containing only @var{word}
1460 (with no trailing blanks) is seen. All of
1461 the lines read up to that point are then used as the standard
1462 input for a command.
1464 The format of here-documents is as follows:
1466 <<[@minus{}]@var{word}
1471 No parameter expansion, command substitution, filename
1472 expansion, or arithmetic expansion is performed on
1473 @var{word}. If any characters in @var{word} are quoted, the
1474 @var{delimiter} is the result of quote removal on @var{word},
1475 and the lines in the here-document are not expanded. Otherwise,
1476 all lines of the here-document are subjected to parameter expansion,
1477 command substitution, and arithmetic expansion. In the latter
1478 case, the pair @code{\newline} is ignored, and @samp{\}
1479 must be used to quote the characters
1480 @samp{\}, @samp{$}, and @samp{`}.
1482 If the redirection operator is @samp{<<-},
1483 then all leading tab characters are stripped from input lines and the
1484 line containing @var{delimiter}.
1485 This allows here-documents within shell scripts to be indented in a
1488 @subsection Duplicating File Descriptors
1489 The redirection operator
1494 is used to duplicate input file descriptors.
1496 expands to one or more digits, the file descriptor denoted by @code{n}
1497 is made to be a copy of that file descriptor. If @var{word}
1498 evaluates to @samp{-}, file descriptor @code{n} is closed. If
1499 @code{n} is not specified, the standard input (file descriptor 0) is used.
1506 is used similarly to duplicate output file descriptors. If
1508 is not specified, the standard output (file descriptor 1) is used.
1509 As a special case, if @code{n} is omitted, and @var{word} does not
1510 expand to one or more digits, the standard output and standard
1511 error are redirected as described previously.
1513 @subsection Opening File Descriptors for Reading and Writing
1514 The redirection operator
1519 causes the file whose name is the expansion of @var{word}
1520 to be opened for both reading and writing on file descriptor
1521 @code{n}, or on file descriptor 0 if @code{n}
1522 is not specified. If the file does not exist, it is created.
1524 @node Executing Commands
1525 @section Executing Commands
1528 * Command Search and Execution:: How Bash finds commands and runs them.
1530 * Environment:: The environment given to a command.
1532 * Exit Status:: The status returned by commands and how Bash
1535 * Signals:: What happens when Bash or a command it runs
1539 @node Command Search and Execution
1540 @subsection Command Search and Execution
1541 @cindex command execution
1542 @cindex command search
1544 After a command has been split into words, if it results in a
1545 simple command and an optional list of arguments, the following
1550 If the command name contains no slashes, the shell attempts to
1551 locate it. If there exists a shell function by that name, that
1552 function is invoked as described above in @ref{Shell Functions}.
1555 If the name does not match a function, the shell searches for
1556 it in the list of shell builtins. If a match is found, that
1560 If the name is neither a shell function nor a builtin,
1561 and contains no slashes, Bash searches each element of
1562 @code{$PATH} for a directory containing an executable file
1563 by that name. Bash uses a hash table to remember the full
1564 filenames of executable files (see the description of
1565 @code{hash} in @ref{Bourne Shell Builtins}) to avoid multiple
1566 @code{PATH} searches.
1567 A full search of the directories in @code{$PATH}
1568 is performed only if the command is not found in the hash table.
1569 If the search is unsuccessful, the shell prints an error
1570 message and returns a nonzero exit status.
1573 If the search is successful, or if the command name contains
1574 one or more slashes, the shell executes the named program.
1575 Argument 0 is set to the name given, and the remaining arguments
1576 to the command are set to the arguments supplied, if any.
1579 If this execution fails because the file is not in executable
1580 format, and the file is not a directory, it is assumed to be
1581 @var{shell script} (@pxref{Shell Scripts}).
1585 @subsection Environment
1588 When a program is invoked it is given an array of strings
1589 called the @var{environment}.
1590 This is a list of name-value pairs, of the form @code{name=value}.
1592 Bash allows you to manipulate the environment in several
1593 ways. On invocation, the shell scans its own environment and
1594 creates a parameter for each name found, automatically marking
1596 to child processes. Executed commands inherit the environment.
1597 The @code{export} and @samp{declare -x}
1598 commands allow parameters and functions to be added to and
1599 deleted from the environment. If the value of a parameter
1600 in the environment is modified, the new value becomes part
1601 of the environment, replacing the old. The environment
1602 inherited by any executed command consists of the shell's
1603 initial environment, whose values may be modified in the shell,
1604 less any pairs removed by the @code{unset} command, plus any
1605 additions via the @code{export} and @samp{declare -x} commands.
1607 The environment for any simple command
1608 or function may be augmented temporarily by prefixing it with
1609 parameter assignments, as described in @ref{Shell Parameters}.
1610 These assignment statements affect only the environment seen
1613 If the @samp{-k} flag is set (@pxref{The Set Builtin}, then all
1614 parameter assignments are placed in the environment for a command,
1615 not just those that precede the command name.
1617 When Bash invokes an external command, the variable @samp{$_}
1618 is set to the full path name of the command and passed to that
1619 command in its environment.
1622 @subsection Exit Status
1625 For the purposes of the shell, a command which exits with a
1626 zero exit status has succeeded.
1627 A non-zero exit status indicates failure.
1628 This seemingly counter-intuitive scheme is used so there
1629 is one well-defined way to indicate success and a variety of
1630 ways to indicate various failure modes.
1631 When a command terminates on a fatal signal whose number is @var{n},
1632 Bash uses the value 128+@var{n} as the exit status.
1634 If a command is not found, the child process created to
1635 execute it returns a status of 127. If a command is found
1636 but is not executable, the return status is 126.
1638 The exit status is used by the Bash conditional commands
1639 (@pxref{Conditional Constructs}) and some of the list
1640 constructs (@pxref{Lists}).
1642 All of the Bash builtins return an exit status of zero if they succeed
1643 and a non-zero status on failure, so they may be used by the
1644 conditional and list constructs.
1648 @cindex signal handling
1650 When Bash is interactive, it ignores
1651 @code{SIGTERM} (so that @samp{kill 0} does not kill an interactive shell),
1653 is caught and handled (so that the @code{wait} builtin is interruptible).
1654 When Bash receives a @code{SIGINT}, it breaks out of any executing loops.
1655 In all cases, Bash ignores @code{SIGQUIT}.
1656 If job control is in effect (@pxref{Job Control}), Bash
1657 ignores @code{SIGTTIN}, @code{SIGTTOU}, and @code{SIGTSTP}.
1659 Synchronous jobs started by Bash have signals set to the
1660 values inherited by the shell from its parent. When job control
1661 is not in effect, background jobs (commands terminated with @samp{&})
1662 ignore @code{SIGINT} and @code{SIGQUIT}.
1663 Commands run as a result of command substitution ignore the
1664 keyboard-generated job control signals
1665 @code{SIGTTIN}, @code{SIGTTOU}, and @code{SIGTSTP}.
1667 The shell exits by default upon receipt of a @code{SIGHUP}.
1668 Before exiting, it resends the @code{SIGHUP}
1669 to all jobs, running or stopped. To prevent the shell from
1670 sending the @code{SIGHUP} signal to a particular job, remove it
1671 from the jobs table with the @code{disown} builtin
1672 (@pxref{Job Control Builtins})
1673 or use @code{disown -h} to mark it to not receive @code{SIGHUP}.
1676 @section Shell Scripts
1677 @cindex shell script
1679 A shell script is a text file containing shell commands. When such
1680 a file is used as the first non-option argument when invoking Bash,
1681 and neither the @samp{-c} nor @samp{-s} option is supplied
1682 (@pxref{Invoking Bash}),
1683 Bash reads and executes commands from the file, then exits. This
1684 mode of operation creates a non-interactive shell. When Bash runs
1685 a shell script, it sets the special parameter @code{0} to the name
1686 of the file, rather than the name of the shell, and the positional
1687 parameters are set to the remaining arguments, if any are given.
1688 If no additional arguments are supplied, the positional parameters
1691 A shell script may be made executable by using the @code{chmod} command
1692 to turn on the execute bit. When Bash finds such a file while
1693 searching the @code{$PATH} for a command, it spawns a subshell to
1694 execute it. In other words, executing
1696 filename @var{arguments}
1699 is equivalent to executing
1701 bash filename @var{arguments}
1705 if @code{filename} is an executable shell script.
1706 This subshell reinitializes itself, so that the effect is as if a
1707 new shell had been invoked to interpret the script.
1709 Most versions of Unix make this a part of the kernel's command
1710 execution mechanism. If the first line of a script begins with
1711 the two characters @samp{#!}, the remainder of the line specifies
1712 an interpreter for the program. The arguments to the interpreter
1713 consist of a single optional argument following the interpreter
1714 name on the first line of the script file, followed by the name of
1715 the script file, followed by the rest of the arguments. Bash
1716 will perform this action on operating systems that do not handle it
1717 themselves. Note that some older versions of Unix limit the interpreter
1718 name and argument to a maximum of 32 characters.
1720 @node Bourne Shell Features
1721 @chapter Bourne Shell Style Features
1724 * Bourne Shell Builtins:: Builtin commands inherited from the Bourne
1726 * Bourne Shell Variables:: Variables which Bash uses in the same way
1727 as the Bourne Shell.
1728 * Other Bourne Shell Features:: Addtional aspects of Bash which behave in
1729 the same way as the Bourne Shell.
1732 This section briefly summarizes things which Bash inherits from
1733 the Bourne Shell: builtins, variables,
1734 and other features. It also lists the significant differences
1735 between Bash and the Bourne Shell.
1737 @node Bourne Shell Builtins
1738 @section Bourne Shell Builtins
1740 The following shell builtin commands are inherited from the Bourne
1741 Shell. These commands are implemented as specified by the @sc{POSIX}
1750 Do nothing beyond expanding @var{arguments} and performing redirections.
1757 Read and execute commands from the @var{filename} argument in the
1758 current shell context.
1765 Exit from a @code{for}, @code{while}, @code{until}, or @code{select} loop.
1766 If @var{n} is supplied, the @var{n}th enclosing loop is exited.
1771 cd [-LP] [@var{directory}]
1773 Change the current working directory to @var{directory}. If @var{directory}
1774 is not given, the value of the @code{HOME} shell variable is used. If the
1775 shell variable @code{CDPATH} exists, it is used as a search path. If
1776 @var{directory} begins with a slash, @code{CDPATH} is not used.
1777 The @samp{-P} option means
1778 to not follow symbolic links; symlinks are followed by default or with the
1786 Resume the next iteration of an enclosing @code{for}, @code{while},
1787 @code{until}, or @code{select} loop.
1788 If @var{n} is supplied, the execution of the
1789 @var{n}th enclosing loop is resumed.
1794 eval [@var{arguments}]
1796 The arguments are concatenated together into a single
1797 command, which is then read and executed.
1802 exec [-cl] [-a @var{name}] [@var{command}] [@var{arguments}]
1805 is supplied, it replaces the shell.
1806 If the @samp{-l} option is supplied,
1807 the shell places a dash in the zeroth arg passed to @var{command}.
1808 This is what the @code{login} program does.
1809 The @samp{-c} option causes @var{command}
1810 to be executed with an empty environment.
1811 If @samp{-a} is supplied, the shell passes @var{name}
1812 as the zeroth argument to @var{command}.
1813 If no @var{command} is specified, redirections may be used to affect
1814 the current shell environment.
1821 Exit the shell, returning a status of @var{n} to the shell's parent.
1826 export [-fn] [-p] [@var{name}[=@var{value}]]
1828 Mark each @var{name} to be passed to child processes
1829 in the environment. If the @samp{-f} option is supplied, the @var{name}s
1830 refer to shell functions. The @samp{-n} option means to no longer mark
1831 each @var{name} for export.
1832 If no @var{names} are supplied, or if the @samp{-p} option is given, a
1833 list of exported names is displayed.
1838 getopts @var{optstring} @var{name} [@var{args}]
1840 @code{getopts} is used by shell scripts to parse positional parameters.
1841 @var{optstring} contains the option letters to be recognized; if a letter
1842 is followed by a colon, the option is expected to have an
1843 argument, which should be separated from it by white space.
1844 Each time it is invoked, @code{getopts}
1845 places the next option in the shell variable @var{name}, initializing
1846 @var{name} if it does not exist,
1847 and the index of the next argument to be processed into the
1848 variable @code{OPTIND}. @code{OPTIND}
1849 is initialized to 1 each time the shell or a shell script
1850 is invoked. When an option requires an argument,
1851 @code{getopts} places that argument into the variable @code{OPTARG}.
1852 The shell does not reset @code{OPTIND}
1853 automatically; it must be manually reset between multiple
1854 calls to @code{getopts}
1855 within the same shell invocation if a new set of parameters
1858 @code{getopts} can report errors in two ways. If the first character of
1859 @var{optstring} is a colon, @var{silent}
1860 error reporting is used. In normal operation diagnostic messages
1861 are printed when illegal options or missing option arguments are
1863 If the variable @code{OPTERR}
1864 is set to 0, no error message will be displayed, even if the first
1865 character of @code{optstring} is not a colon.
1867 If an illegal option is seen,
1868 @code{getopts} places @samp{?} into @var{name} and, if not silent,
1869 prints an error message and unsets @code{OPTARG}.
1870 If @code{getopts} is silent, the option character found is placed in
1871 @code{OPTARG} and no diagnostic message is printed.
1873 If a required argument is not found, and @code{getopts}
1874 is not silent, a question mark (@samp{?}) is placed in @var{name},
1875 @code{OPTARG} is unset, and a diagnostic message is printed.
1876 If @code{getopts} is silent, then a colon (@samp{:}) is placed in
1877 @var{name} and @code{OPTARG} is set to the option character found.
1880 normally parses the positional parameters, but if more arguments are
1881 given in @var{args}, @code{getopts} parses those instead.
1886 hash [-r] [-p @var{filename}] [@var{name}]
1888 Remember the full filenames of commands specified as arguments,
1889 so they need not be searched for on subsequent invocations. The
1890 commands are found by searching through the directories listed in
1891 @code{$PATH}. The @samp{-p} option inhibits the path search, and
1892 @var{filename} is used as the location of @var{name}.
1893 The @samp{-r} option causes the shell to forget
1894 all remembered locations. If no arguments are given, information
1895 about remembered commands is printed.
1902 Print the current working directory. If the @samp{-P} option is supplied,
1903 the path printed will not contain symbolic links. If the @samp{-L} option
1904 is supplied, the path printed may contain symbolic links.
1909 readonly [-apf] [@var{name}] @dots{}
1911 Mark each @var{name} as unchangable. The values of these names may not
1912 be changed by subsequent assignment. If the @samp{-f} option is supplied,
1913 each @var{name} refers to a shell function. The @samp{-a} option means
1914 each @var{name} refers to an array variable.
1915 If no @var{name} arguments are given, or if the @samp{-p}
1916 option is supplied, a list of all readonly names is printed.
1923 Cause a shell function to exit with value @var{n}. This may also be used
1924 to terminate execution of a script being executed with the @code{.}
1932 Shift positional parameters to the left by @var{n}.
1933 The positional parameters from @var{n}+1 @dots{}
1936 Parameters represented by the numbers
1937 @code{$#} to @var{n}+1 are unset. @var{n}
1938 must be a non-negative number less than or equal to @code{$#}.
1944 Evaluate a conditional expression (@pxref{Bash Conditional Expressions}).
1951 Print out the user and system times used by the shell and its children.
1956 trap [-lp] [@var{arg}] [@var{sigspec}]
1958 The commands in @var{arg} are to be read and executed when the
1959 shell receives signal @var{sigspec}. If @var{arg} is absent or
1960 equal to @samp{-}, all specified signals are reset to the values
1961 they had when the shell was started.
1962 If @var{arg} is the null string, then @var{sigspec} is ignored by
1963 the shell and commands it invokes.
1964 If @var{arg} is @samp{-p}, the shell displays the trap commands
1965 associated with each @var{sigspec}. If no arguments are supplied, or
1966 only @samp{-p} is given, @code{trap} prints the list of commands
1967 associated with each signal number. @var{sigspec} is either a signal
1968 name such as @code{SIGINT} or a signal number. If @var{sigspec} is
1969 @code{0} or @code{EXIT}, @var{arg} is executed when the shell exits.
1970 If @var{sigspec} is @code{DEBUG}, the command @var{arg} is executed
1971 after every simple command.
1972 The @samp{-l} option causes the shell to print a list of signal names
1973 and their corresponding numbers.
1975 Signals ignored upon entry to the shell cannot be trapped or reset.
1976 Trapped signals are reset to their original values in a child
1977 process when it is created.
1982 umask [-S] [@var{mode}]
1984 Set the shell process's file creation mask to @var{mode}. If
1985 @var{mode} begins with a digit, it is interpreted as an octal number;
1986 if not, it is interpreted as a symbolic mode mask similar
1987 to that accepted by the @code{chmod} command. If @var{mode} is
1988 omitted, the current value of the mask is printed. If the @samp{-S}
1989 option is supplied without a @var{mode} argument, the mask is printed
1990 in a symbolic format.
1995 unset [-fv] [@var{name}]
1997 Each variable or function @var{name} is removed.
1998 If no options are supplied, or the @samp{-v} option is given, each
1999 @var{name} refers to a shell variable.
2000 If the @samp{-f} option is given, the @var{name}s refer to shell
2001 functions, and the function definition is removed.
2002 Read-only variables and functions may not be unset.
2006 @node Bourne Shell Variables
2007 @section Bourne Shell Variables
2009 Bash uses certain shell variables in the same way as the Bourne shell.
2010 In some cases, Bash assigns a default value to the variable.
2015 A list of characters that separate fields; used when the shell splits
2016 words as part of expansion.
2019 A colon-separated list of directories in which the shell looks for
2023 The current user's home directory; the default for the @code{cd} builtin
2027 A colon-separated list of directories used as a search path for
2028 the @code{cd} command.
2031 A colon-separated list of files which the shell periodically checks
2032 for new mail. You can
2033 also specify what message is printed by separating the file name from
2034 the message with a @samp{?}. When used in the text of the message,
2035 @code{$_} stands for the name of the current mailfile.
2038 If this parameter is set to a filename and the @code{MAILPATH} variable
2039 is not set, Bash informs the user of the arrival of mail in
2043 The primary prompt string. The default value is @samp{\s-\v\$ }.
2046 The secondary prompt string. The default value is @samp{> }.
2049 The index of the last option processed by the
2050 @code{getopts} builtin.
2053 The value of the last option argument processed by the
2054 @code{getopts} builtin.
2058 @node Other Bourne Shell Features
2059 @section Other Bourne Shell Features
2062 * Major Differences From The Bourne Shell:: Major differences between
2063 Bash and the Bourne shell.
2066 Bash implements essentially the same grammar, parameter and variable
2067 expansion, redirection, and quoting as the Bourne Shell. Bash uses the
2068 @sc{POSIX} 1003.2 standard as the specification of how these features are to be
2069 implemented. There are some differences between the traditional Bourne
2070 shell and the @sc{POSIX} standard; this section quickly details the differences
2071 of significance. A number of these differences are explained in greater
2072 depth in subsequent sections.
2074 @node Major Differences From The Bourne Shell
2075 @subsection Major Differences From The SVR4.2 Bourne Shell
2077 Bash is @sc{POSIX}-conformant, even where the @sc{POSIX} specification
2078 differs from traditional @code{sh} behavior.
2080 Bash has multi-character invocation options (@pxref{Invoking Bash}).
2082 Bash has command-line editing (@pxref{Command Line Editing}) and
2083 the @code{bind} builtin.
2085 Bash has command history (@pxref{Bash History Facilities}) and the
2086 @code{history} and @code{fc} builtins to manipulate it.
2088 Bash implements @code{csh}-like history expansion (@pxref{History Interaction}).
2090 Bash has one-dimensional array variables (@pxref{Arrays}), and the
2091 appropriate variable expansions and assignment syntax to use them.
2092 Some of the Bash builtins take options to act on arrays. Bash provides
2093 some built-in array variables.
2095 Bash implements the @code{!} keyword to negate the return value of
2096 a pipeline (@pxref{Pipelines}).
2097 Very useful when an @code{if} statement needs to act only if a test fails.
2099 Bash includes the @code{select} compound command, which allows the
2100 generation of simple menus (@pxref{Korn Shell Constructs}).
2102 Bash includes brace expansion (@pxref{Brace Expansion}) and tilde
2103 expansion (@pxref{Tilde Expansion}).
2105 Bash implements command aliases and the @code{alias} and @code{unalias}
2106 builtins (@pxref{Aliases}).
2108 Bash provides shell arithmetic and arithmetic expansion
2109 (@pxref{Shell Arithmetic}).
2111 The @sc{POSIX} and @code{ksh}-style @code{$()} form of command substitution
2112 is implemented (@pxref{Command Substitution}),
2113 and preferred to the Bourne shell's @code{``} (which
2114 is also implemented for backwards compatibility).
2116 Variables present in the shell's initial environment are automatically
2117 exported to child processes. The Bourne shell does not normally do
2118 this unless the variables are explicitly marked using the @code{export}
2121 Bash includes the @sc{POSIX} and @code{ksh}-style pattern removal
2122 @samp{%}, @samp{#}, @samp{%%} and @samp{##} constructs to remove
2123 leading or trailing substrings from variable values
2124 (@pxref{Shell Parameter Expansion}).
2126 The expansion @code{$@{#xx@}}, which returns the length of @code{$xx},
2127 is supported (@pxref{Shell Parameter Expansion}).
2129 The @code{$'@dots{}'} quoting syntax, which expands ANSI-C
2130 backslash-escaped characters in the text between the single quotes,
2131 is supported (@pxref{ANSI-C Quoting}).
2133 Bash supports the @code{$"@dots{}"} quoting syntax to do
2134 locale-specific translation of the characters between the double
2135 quotes. The @samp{-D} and @samp{--dump-strings} invocation options
2136 list the translatable strings found in a script
2137 (@pxref{Locale Translation}).
2139 The expansion @code{$@{var:}@var{length}@code{[:}@var{offset}@code{]@}},
2140 which expands to the substring of @code{var}'s value of length
2141 @var{length}, optionally beginning at @var{offset}, is present
2142 (@pxref{Shell Parameter Expansion}).
2145 @code{$@{var/[/]}@var{pattern}@code{[/}@var{replacement}@code{]@}},
2146 which matches @var{pattern} and replaces it with @var{replacement} in
2147 the value of @code{var}, is available (@pxref{Shell Parameter Expansion}).
2149 Bash has @var{indirect} variable expansion using @code{$@{!word@}}
2150 (@pxref{Shell Parameter Expansion}).
2152 Bash can expand positional parameters beyond @code{$9} using
2153 @code{$@{@var{num}@}}.
2155 Bash has process substitution (@pxref{Process Substitution}).
2157 Bash automatically assigns variables that provide information about the
2158 current user (@code{UID} and @code{EUID}), the current host
2159 (@code{HOSTTYPE}, @code{OSTYPE}, @code{MACHTYPE}, and @code{HOSTNAME}),
2160 and the instance of Bash that is running (@code{BASH},
2161 @code{BASH_VERSION}, and @code{BASH_VERSINFO}. @xref{Bash Variables},
2164 The @code{IFS} variable is used to split only the results of expansion,
2165 not all words (@pxref{Word Splitting}).
2166 This closes a longstanding shell security hole.
2168 It is possible to have a variable and a function with the same name;
2169 @code{sh} does not separate the two name spaces.
2171 Bash functions are permitted to have local variables using the
2172 @code{local} builtin, and thus useful recursive functions may be written.
2174 Variable assignments preceding commands affect only that command, even
2175 builtins and functions. In @code{sh}, all variable assignments
2176 preceding commands are global unless the command is executed from the
2179 Bash performs filename expansion on filenames specified as operands
2180 to output redirection operators.
2182 Bash contains the @samp{<>} redirection operator, allowing a file to be
2183 opened for both reading and writing, and the @samp{&>} redirection
2184 operator, for directing standard output and standard error to the same
2185 file (@pxref{Redirections}).
2187 The @code{noclobber} option is available to avoid overwriting existing
2188 files with output redirection (@pxref{The Set Builtin}).
2189 The @samp{>|} redirection operator may be used to override @code{noclobber}.
2191 Bash interprets special backslash-escaped characters in the prompt
2192 strings when interactive (@pxref{Printing a Prompt}).
2194 Bash allows you to write a function to override a builtin, and provides
2195 access to that builtin's functionality within the function via the
2196 @code{builtin} and @code{command} builtins (@pxref{Bash Builtins}).
2198 The @code{command} builtin allows selective disabling of functions
2199 when command lookup is performed (@pxref{Bash Builtins}).
2201 Individual builtins may be enabled or disabled using the @code{enable}
2202 builtin (@pxref{Bash Builtins}).
2204 The Bash @code{hash} builtin allows a name to be associated with
2205 an arbitrary filename, even when that filename cannot be found by
2206 searching the @code{$PATH}, using @samp{hash -p}.
2208 Shell functions may be exported to children via the environment
2209 (@pxref{Shell Functions}).
2211 Bash includes a @code{help} builtin for quick reference to shell
2212 facilities (@pxref{Bash Builtins}).
2214 The Bash @code{read} builtin (@pxref{Bash Builtins})
2215 will read a line ending in @samp{\} with
2216 the @samp{-r} option, and will use the @code{REPLY} variable as a
2217 default if no arguments are supplied. The Bash @code{read} builtin
2218 also accepts a prompt string with the @samp{-p} option and will use
2219 Readline to obtain the line when given the @samp{-e} option.
2221 Bash includes the @code{shopt} builtin, for finer control of shell
2222 optional capabilities (@pxref{Bash Builtins}).
2224 Bash has much more optional behavior controllable with the @code{set}
2225 builtin (@pxref{The Set Builtin}).
2227 The @code{disown} builtin can remove a job from the internal shell
2228 job table (@pxref{Job Control Builtins}).
2230 The @code{return} builtin may be used to abort execution of scripts
2231 executed with the @code{.} or @code{source} builtins
2232 (@pxref{Bourne Shell Builtins}).
2234 The @code{test} builtin (@pxref{Bourne Shell Builtins})
2235 is slightly different, as it implements the
2236 @sc{POSIX} 1003.2 algorithm, which specifies the behavior based on the
2237 number of arguments.
2239 The @code{trap} builtin (@pxref{Bourne Shell Builtins})
2240 allows a @code{DEBUG} pseudo-signal specification,
2241 similar to @code{EXIT}. Commands specified with a @code{DEBUG} trap are
2242 executed after every simple command. The @code{DEBUG} trap is not
2243 inherited by shell functions.
2245 The Bash @code{export}, @code{readonly}, and @code{declare} builtins can
2246 take a @samp{-f} option to act on shell functions, a @samp{-p} option to
2247 display variables with various attributes set in a format that can be
2248 used as shell input, a @samp{-n} option to remove various variable
2249 attributes, and @samp{name=value} arguments to set variable attributes
2250 and values simultaneously.
2252 The Bash @code{cd} and @code{pwd} builtins each take @samp{-L} and
2253 @samp{-P} builtins to switch between logical and physical modes.
2255 The Bash @code{type} builtin is more extensive and gives more information
2256 about the names it finds.
2258 Bash implements a @code{csh}-like directory stack, and provides the
2259 @code{pushd}, @code{popd}, and @code{dirs} builtins to manipulate it.
2260 Bash also makes the directory stack visible as the value of the
2261 @code{DIRSTACK} shell variable.
2263 The Bash restricted mode is more useful (@pxref{The Restricted Shell});
2264 the @sc{SVR4.2} shell restricted mode is too limited.
2266 Bash has the @code{time} reserved word and command timing (@pxref{Pipelines}).
2267 The display of the timing statistics may be controlled with the
2268 @code{TIMEFORMAT} variable.
2270 The @sc{SVR4.2} shell has two privilege-related builtins
2271 (@code{mldmode} and @code{priv}) not present in Bash.
2273 Bash does not have the @code{stop} or @code{newgrp} builtins.
2275 Bash does not use the @code{SHACCT} variable or perform shell accounting.
2277 The @sc{SVR4.2} @code{sh} uses a @code{TIMEOUT} variable like Bash uses
2280 More features unique to Bash may be found in
2281 @ref{Bash Features}.
2283 @subsection Implementation Differences From The SVR4.2 Shell
2285 Since Bash is a completely new implementation, it does not suffer from
2286 many of the limitations of the @sc{SVR4.2} shell. For instance:
2291 Bash does not fork a subshell when redirecting into or out of
2292 a shell control structure such as an @code{if} or @code{while}
2296 Bash does not allow unbalanced quotes. The @sc{SVR4.2} shell will silently
2297 insert a needed closing quote at @code{EOF} under certain circumstances.
2298 This can be the cause of some hard-to-find errors.
2301 The @sc{SVR4.2} shell uses a baroque memory management scheme based on
2302 trapping @code{SIGSEGV}. If the shell is started from a process with
2303 @code{SIGSEGV} blocked (e.g., by using the @code{system()} C library
2304 function call), the shell misbehaves badly.
2307 In a questionable attempt at security, the @sc{SVR4.2} shell
2309 and effective @sc{UID} and @sc{GID} if they are less than some
2310 threshold value, commonly 100. This can lead to unexpected results.
2313 The @sc{SVR4.2} shell does not allow users to trap @code{SIGALRM} or
2317 For some reason, the @sc{SVR4.2} shell does not allow the @code{MAILCHECK}
2318 variable to be unset.
2321 The @sc{SVR4.2} shell treats @samp{^} as the undocumented equivalent of
2325 Bash allows multiple option arguments when it is invoked (@code{-x -v});
2326 the @sc{SVR4.2} shell allows only one option argument (@code{-xv}). In
2327 fact, some versions of the shell dump core if the second argument begins
2331 The @sc{SVR4.2} shell exits a script if any builtin fails; Bash exits
2332 a script only if one of the @sc{POSIX.2} special builtins fails, and
2333 only for certain failures, as enumerated in the @code{POSIX.2} standard.
2336 The @sc{SVR4.2} shell behaves differently when invoked as @code{jsh}
2337 (it turns on job control).
2341 @chapter C-Shell Style Features
2343 The C-Shell (@dfn{@code{csh}}) was created by Bill Joy at The
2344 University of California at Berkeley. It
2345 is generally considered to have better features for interactive use than
2346 the original Bourne shell. Some of the @code{csh} features present in
2347 Bash include job control, history expansion, `protected' redirection, and
2348 several variables to control the interactive behaviour of the shell
2349 (e.g., @code{IGNOREEOF}).
2351 @xref{Using History Interactively}, for details on history expansion.
2354 * Brace Expansion:: Expansion of expressions within braces.
2355 * Tilde Expansion:: Expansion of the ~ character.
2356 * C Shell Builtins:: Builtin commands adopted from the C Shell.
2357 * C Shell Variables:: Variables which Bash uses in essentially
2358 the same way as the C Shell.
2361 @node Brace Expansion
2362 @section Brace Expansion
2363 @cindex brace expansion
2364 @cindex expansion, brace
2367 is a mechanism by which arbitrary strings
2368 may be generated. This mechanism is similar to
2369 @var{filename expansion} (@pxref{Filename Expansion}),
2370 but the file names generated
2371 need not exist. Patterns to be brace expanded take
2372 the form of an optional @var{preamble},
2373 followed by a series of comma-separated strings
2374 between a pair of braces, followed by an optional @var{postamble}.
2375 The preamble is prepended to each string contained
2376 within the braces, and the postamble is then appended
2377 to each resulting string, expanding left to right.
2379 Brace expansions may be nested. The results of each expanded
2380 string are not sorted; left to right order is preserved.
2383 bash$ echo a@{d,c,b@}e
2387 Brace expansion is performed before any other expansions,
2388 and any characters special to other expansions are preserved
2389 in the result. It is strictly textual. Bash
2390 does not apply any syntactic interpretation to the context of the
2391 expansion or the text between the braces.
2393 A correctly-formed brace expansion must contain unquoted opening
2394 and closing braces, and at least one unquoted comma.
2395 Any incorrectly formed brace expansion is left unchanged.
2397 This construct is typically used as shorthand when the common
2398 prefix of the strings to be generated is longer than in the
2401 mkdir /usr/local/src/bash/@{old,new,dist,bugs@}
2405 chown root /usr/@{ucb/@{ex,edit@},lib/@{ex?.?*,how_ex@}@}
2408 @node Tilde Expansion
2409 @section Tilde Expansion
2410 @cindex tilde expansion
2411 @cindex expansion, tilde
2413 Bash has tilde (~) expansion, similar, but not identical, to that of
2414 @code{csh}. The following table shows what unquoted words beginning
2415 with a tilde expand to.
2419 The current value of @code{$HOME}.
2424 The subdirectory @code{foo} of the home directory of the user
2434 Bash will also tilde expand words following redirection operators
2435 and words following @samp{=} in assignment statements.
2437 @node C Shell Builtins
2438 @section C Shell Builtins
2440 Bash has several builtin commands whose definition is very similar
2447 pushd [@var{dir} | @var{+N} | @var{-N}] [-n]
2450 Save the current directory on a list and then @code{cd} to
2452 arguments, exchanges the top two directories.
2456 Brings the @var{N}th directory (counting from the left of the
2457 list printed by @code{dirs}) to the top of the list by rotating
2460 Brings the @var{N}th directory (counting from the right of the
2461 list printed by @code{dirs}) to the top of the list by rotating
2464 Suppresses the normal change of directory when adding directories
2465 to the stack, so that only the stack is manipulated.
2467 Makes the current working directory be the top of the stack, and then
2468 @code{cd}s to @var{dir}. You can see the saved directory list
2469 with the @code{dirs} command.
2475 popd [+@var{N} | -@var{N}] [-n]
2478 Pop the directory stack, and @code{cd} to the new top directory. When
2479 no arguments are given, @code{popd}
2480 removes the top directory from the stack and
2481 performs a @code{cd} to the new top directory. The
2482 elements are numbered from 0 starting at the first directory listed with
2483 @code{dirs}; i.e., @code{popd} is equivalent to @code{popd +0}.
2486 Removes the @var{N}th directory (counting from the left of the
2487 list printed by @code{dirs}), starting with zero.
2489 Removes the @var{N}th directory (counting from the right of the
2490 list printed by @code{dirs}), starting with zero.
2492 Suppresses the normal change of directory when removing directories
2493 from the stack, so that only the stack is manipulated.
2499 dirs [+@var{N} | -@var{N}] [-clvp]
2501 Display the list of currently remembered directories. Directories
2502 find their way onto the list with the @code{pushd} command; you can get
2503 back up through the list with the @code{popd} command.
2506 Displays the @var{N}th directory (counting from the left of the
2507 list printed by @code{dirs} when invoked without options), starting
2510 Displays the @var{N}th directory (counting from the right of the
2511 list printed by @code{dirs} when invoked without options), starting
2514 Clears the directory stack by deleting all of the elements.
2516 Produces a longer listing; the default listing format uses a
2517 tilde to denote the home directory.
2519 Causes @code{dirs} to print the directory stack with one entry per
2522 Causes @code{dirs} to print the directory stack with one entry per
2523 line, prepending each entry with its index in the stack.
2529 history [-c] [@var{n}]
2530 history [-anrw] [@var{filename}]
2531 history -ps @var{arg}
2534 Display the history list with line numbers. Lines prefixed with
2535 with a @samp{*} have been modified. An argument of @var{n} says
2536 to list only the last @var{n} lines. Options, if supplied, have
2537 the following meanings:
2541 Write out the current history to the history file.
2544 Read the current history file and append its contents to
2549 history lines (history lines entered since the beginning of the
2550 current Bash session) to the history file.
2553 Append the history lines not already read from the history file
2554 to the current history list. These are lines appended to the history
2555 file since the beginning of the current Bash session.
2558 Clear the history list. This may be combined
2559 with the other options to replace the history list completely.
2562 The @var{arg}s are added to the end of
2563 the history list as a single entry.
2566 Perform history substitution on the @var{arg}s and display the result
2567 on the standard output, without storing the results in the history list.
2570 When the @samp{-w}, @samp{-r}, @samp{-a}, or @samp{-n} option is
2571 used, if @var{filename}
2572 is given, then it is used as the history file. If not, then
2573 the value of the @code{HISTFILE} variable is used.
2581 A synonym for @code{.} (@pxref{Bourne Shell Builtins}).
2585 @node C Shell Variables
2586 @section C Shell Variables
2591 If this variable is set, its value is used the number of consecutive
2592 @code{EOF}s Bash will read before exiting. By default, Bash will exit
2593 upon reading a single @code{EOF}. If @code{IGNOREEOF} is not set to
2594 a numeric value, Bash acts as if its value were 10.
2598 @node Korn Shell Features
2599 @chapter Korn Shell Style Features
2601 This section describes features primarily inspired by the
2602 Korn Shell (@code{ksh}). In some cases, the @sc{POSIX} 1003.2
2603 standard has adopted these commands and variables from the
2604 Korn Shell; Bash implements those features using the @sc{POSIX}
2605 standard as a guide.
2608 * Korn Shell Constructs:: Shell grammar constructs adopted from the
2610 * Korn Shell Builtins:: Builtin commands adopted from the Korn Shell.
2611 * Korn Shell Variables:: Variables which Bash uses in essentially
2612 the same way as the Korn Shell.
2613 * Aliases:: Substituting one command for another.
2616 @node Korn Shell Constructs
2617 @section Korn Shell Constructs
2619 Bash includes the Korn Shell @code{select} construct. This construct
2620 allows the easy generation of menus. It has almost the same syntax as
2621 the @code{for} command.
2623 The syntax of the @code{select} command is:
2626 select @var{name} [in @var{words} @dots{}]; do @var{commands}; done
2629 The list of words following @code{in} is expanded, generating a list
2630 of items. The set of expanded words is printed on the standard
2631 error, each preceded by a number. If the @samp{in @var{words}}
2632 is omitted, the positional parameters are printed. The
2633 @code{PS3} prompt is then displayed and a line is read from the standard
2634 input. If the line consists of a number corresponding to one of
2635 the displayed words, then the value of @var{name}
2636 is set to that word. If the line is empty, the words and prompt
2637 are displayed again. If @code{EOF} is read, the @code{select}
2638 command completes. Any other value read causes @var{name}
2639 to be set to null. The line read is saved in the variable
2642 The @var{commands} are executed after each selection until a
2643 @code{break} or @code{return} command is executed, at which
2644 point the @code{select} command completes.
2646 Bash also has adopted command timing from the Korn shell. If the
2647 @code{time} reserved word precedes a pipeline or simple command,
2648 timing statistics for the pipeline are displayed when it completes.
2649 The statistics currently consist of elapsed (wall-clock) time and
2650 user and system time consumed by the command's execution.
2652 The use of @code{time} as a reserved word permits the timing of
2653 shell builtins, shell functions, and pipelines. An external
2654 @code{time} command cannot time these easily.
2656 @node Korn Shell Builtins
2657 @section Korn Shell Builtins
2659 This section describes Bash builtin commands taken from @code{ksh}.
2666 @code{fc [-e @var{ename}] [-nlr] [@var{first}] [@var{last}]}
2667 @code{fc -s [@var{pat}=@var{rep}] [@var{command}]}
2670 Fix Command. In the first form, a range of commands from @var{first} to
2671 @var{last} is selected from the history list. Both @var{first} and
2672 @var{last} may be specified as a string (to locate the most recent
2673 command beginning with that string) or as a number (an index into the
2674 history list, where a negative number is used as an offset from the
2675 current command number). If @var{last} is not specified it is set to
2676 @var{first}. If @var{first} is not specified it is set to the previous
2677 command for editing and @minus{}16 for listing. If the @samp{-l} flag is
2678 given, the commands are listed on standard output. The @samp{-n} flag
2679 suppresses the command numbers when listing. The @samp{-r} flag
2680 reverses the order of the listing. Otherwise, the editor given by
2681 @var{ename} is invoked on a file containing those commands. If
2682 @var{ename} is not given, the value of the following variable expansion
2683 is used: @code{$@{FCEDIT:-$@{EDITOR:-vi@}@}}. This says to use the
2684 value of the @code{FCEDIT} variable if set, or the value of the
2685 @code{EDITOR} variable if that is set, or @code{vi} if neither is set.
2686 When editing is complete, the edited commands are echoed and executed.
2688 In the second form, @var{command} is re-executed after each instance
2689 of @var{pat} in the selected command is replaced by @var{rep}.
2691 A useful alias to use with the @code{fc} command is @code{r='fc -s'}, so
2692 that typing @samp{r cc} runs the last command beginning with @code{cc}
2693 and typing @samp{r} re-executes the last command (@pxref{Aliases}).
2697 The @code{let} builtin allows arithmetic to be performed on shell variables.
2698 For details, refer to @ref{Arithmetic Builtins}.
2702 The @code{typeset} command is supplied for compatibility with the Korn
2703 shell; however, it has been deprecated in favor of the
2704 @code{declare} command (@pxref{Bash Builtins}).
2708 @node Korn Shell Variables
2709 @section Korn Shell Variables
2714 The default variable for the @code{read} builtin.
2717 Each time this parameter is referenced, a random integer
2718 between 0 and 32767 is generated. Assigning a value to this
2719 variable seeds the random number generator.
2722 This variable expands to the number of seconds since the
2723 shell was started. Assignment to this variable resets
2724 the count to the value assigned, and the expanded value
2725 becomes the value assigned plus the number of seconds
2726 since the assignment.
2729 The value of this variable is used as the prompt for the
2730 @code{select} command. If this variable is not set, the
2731 @code{select} command prompts with @samp{#? }
2734 This is the prompt printed before the command line is echoed
2735 when the @samp{-x} option is set (@pxref{The Set Builtin}).
2736 The default is @samp{+ }.
2739 The current working directory as set by the @code{cd} builtin.
2742 The previous working directory as set by the @code{cd} builtin.
2745 If set to a value greater than zero, the value is interpreted as
2746 the number of seconds to wait for input after issuing the primary
2748 Bash terminates after that number of seconds if input does
2752 The line number in the script or shell function currently executing.
2755 If this variable is set when Bash is invoked to execute a shell
2756 script, its value is expanded and used as the name of a startup file
2757 to read before executing the script. @xref{Bash Startup Files}.
2760 The editor used as a default by the @code{fc} builtin command.
2766 @cindex alias expansion
2769 * Alias Builtins:: Builtins commands to maniuplate aliases.
2772 The shell maintains a list of @var{aliases}
2773 that may be set and unset with the @code{alias} and
2774 @code{unalias} builtin commands.
2776 The first word of each command, if unquoted,
2777 is checked to see if it has an
2778 alias. If so, that word is replaced by the text of the alias.
2779 The alias name and the replacement text may contain any valid
2780 shell input, including shell metacharacters, with the exception
2781 that the alias name may not contain @key{=}.
2782 The first word of the replacement text is tested for
2783 aliases, but a word that is identical to an alias being expanded
2784 is not expanded a second time. This means that one may alias
2785 @code{ls} to @code{"ls -F"},
2786 for instance, and Bash does not try to recursively expand the
2787 replacement text. If the last character of the alias value is a
2788 space or tab character, then the next command word following the
2789 alias is also checked for alias expansion.
2791 Aliases are created and listed with the @code{alias}
2792 command, and removed with the @code{unalias} command.
2794 There is no mechanism for using arguments in the replacement text,
2796 If arguments are needed, a shell function should be used
2797 (@pxref{Shell Functions}).
2799 Aliases are not expanded when the shell is not interactive,
2800 unless the @code{expand_aliases} shell option is set using
2801 @code{shopt} (@pxref{Bash Builtins}).
2803 The rules concerning the definition and use of aliases are
2804 somewhat confusing. Bash
2805 always reads at least one complete line
2806 of input before executing any
2807 of the commands on that line. Aliases are expanded when a
2808 command is read, not when it is executed. Therefore, an
2809 alias definition appearing on the same line as another
2810 command does not take effect until the next line of input is read.
2811 The commands following the alias definition
2812 on that line are not affected by the new alias.
2813 This behavior is also an issue when functions are executed.
2814 Aliases are expanded when the function definition is read,
2815 not when the function is executed, because a function definition
2816 is itself a compound command. As a consequence, aliases
2817 defined in a function are not available until after that
2818 function is executed. To be safe, always put
2819 alias definitions on a separate line, and do not use @code{alias}
2820 in compound commands.
2822 Note that for almost every purpose, aliases are superseded by
2825 @node Alias Builtins
2826 @subsection Alias Builtins
2833 alias [@code{-p}] [@var{name}[=@var{value}] @dots{}]
2836 Without arguments or with the @samp{-p} option, @code{alias} prints
2837 the list of aliases on the standard output in a form that allows
2838 them to be reused as input.
2839 If arguments are supplied, an alias is defined for each @var{name}
2840 whose @var{value} is given. If no @var{value} is given, the name
2841 and value of the alias is printed.
2846 unalias [-a] [@var{name} @dots{} ]
2849 Remove each @var{name} from the list of aliases. If @samp{-a} is
2850 supplied, all aliases are removed.
2854 @chapter Bash Features
2856 This section describes features unique to Bash.
2859 * Invoking Bash:: Command line options that you can give
2861 * Bash Startup Files:: When and how Bash executes scripts.
2862 * Is This Shell Interactive?:: Determining the state of a running Bash.
2863 * Bash Builtins:: Table of builtins specific to Bash.
2864 * The Set Builtin:: This builtin is so overloaded it
2865 deserves its own section.
2866 * Bash Conditional Expressions:: Primitives used in composing expressions for
2867 the @code{test} builtin.
2868 * Bash Variables:: List of variables that exist in Bash.
2869 * Shell Arithmetic:: Arithmetic on shell variables.
2870 * Arrays:: Array Variables
2871 * Printing a Prompt:: Controlling the PS1 string.
2872 * The Restricted Shell:: A more controlled mode of shell execution.
2873 * Bash POSIX Mode:: Making Bash behave more closely to what
2874 the POSIX standard specifies.
2878 @section Invoking Bash
2881 bash [long-opt] [-ir] [-abefhkmnptuvxdBCDHP] [-o @var{option}] [@var{argument} @dots{}]
2882 bash [long-opt] [-abefhkmnptuvxdBCDHP] [-o @var{option}] -c @var{string} [@var{argument} @dots{}]
2883 bash [long-opt] -s [-abefhkmnptuvxdBCDHP] [-o @var{option}] [@var{argument} @dots{}]
2886 In addition to the single-character shell command-line options
2887 (@pxref{The Set Builtin}), there are several multi-character
2888 options that you can use. These options must appear on the command
2889 line before the single-character options in order for them
2893 @item --dump-strings
2894 Equivalent to @samp{-D}.
2897 Display a usage message on standard output and exit sucessfully.
2900 Make this shell act as if it were directly invoked by login.
2901 This is equivalent to @samp{exec -l bash} but can be issued from
2902 another shell, such as @code{csh}. If you wanted to replace your
2903 current login shell with a Bash login shell, you would say
2904 @samp{exec bash --login}.
2907 Do not use the @sc{GNU} Readline library (@pxref{Command Line Editing})
2908 to read interactive command lines.
2911 Don't load the system-wide startup file @file{/etc/profile}
2912 or any of the personal initialization files
2913 @file{~/.bash_profile}, @file{~/.bash_login}, or @file{~/.profile}
2914 when Bash is invoked as a login shell.
2917 Don't read the @file{~/.bashrc} initialization file in an
2918 interactive shell. This is on by default if the shell is
2919 invoked as @code{sh}.
2922 Change the behavior of Bash where the default operation differs
2923 from the @sc{POSIX} 1003.2 standard to match the standard. This
2924 is intended to make Bash behave as a strict superset of that
2925 standard. @xref{Bash POSIX Mode}, for a description of the Bash
2928 @item --rcfile @var{filename}
2929 Execute commands from @var{filename} (instead of @file{~/.bashrc})
2930 in an interactive shell.
2933 Make the shell a restricted shell (@pxref{The Restricted Shell}).
2936 Equivalent to @samp{-v}.
2939 Show version information for this instance of
2940 Bash on the standard output and exit successfully.
2944 There are several single-character options you can give which are
2945 not available with the @code{set} builtin.
2948 @item -c @var{string}
2949 Read and execute commands from @var{string} after processing the
2950 options, then exit. Any remaining arguments are assigned to the
2951 positional parameters, starting with @code{$0}.
2954 Force the shell to run interactively.
2957 Make the shell restricted.
2960 If this flag is present, or if no arguments remain after option
2961 processing, then commands are read from the standard input.
2962 This option allows the positional parameters to be set
2963 when invoking an interactive shell.
2966 A list of all double-quoted strings preceded by @samp{$}
2967 is printed on the standard ouput.
2968 These are the strings that
2969 are subject to language translation when the current locale
2970 is not @code{C} or @code{POSIX} (@pxref{Locale Translation}).
2971 This implies the @samp{-n} option; no commands will be executed.
2975 @cindex interactive shell
2976 An @emph{interactive} shell is one whose input and output are both
2977 connected to terminals (as determined by @code{isatty()}), or one
2978 started with the @samp{-i} option.
2980 If arguments remain after option processing, and neither the
2981 @samp{-c} nor the @samp{-s}
2982 option has been supplied, the first argument is assumed to
2983 be the name of a file containing shell commands (@pxref{Shell Scripts}).
2984 When Bash is invoked in this fashion, @code{$0}
2985 is set to the name of the file, and the positional parameters
2986 are set to the remaining arguments.
2987 Bash reads and executes commands from this file, then exits.
2988 Bash's exit status is the exit status of the last command executed
2989 in the script. If no commands are executed, the exit status is 0.
2991 @node Bash Startup Files
2992 @section Bash Startup Files
2993 @cindex startup files
2995 This section describs how bash executes its startup files.
2996 If any of the files exist but cannot be read, bash reports an error.
2997 Tildes are expanded in file names as described above under
2998 Tilde Expansion (@pxref{Tilde Expansion}).
3000 When Bash is invoked as a login shell, it first reads and
3001 executes commands from the file @file{/etc/profile}, if that file exists.
3002 After reading that file, it looks for @file{~/.bash_profile},
3003 @file{~/.bash_login}, and @file{~/.profile}, in that order, and reads
3004 and executes commands from the first one that exists and is readable.
3005 The @samp{--noprofile} option may be used when the shell is started to
3006 inhibit this behavior.
3008 When a login shell exits, Bash reads and executes commands from
3009 the file @file{~/.bash_logout}, if it exists.
3011 When an interactive shell that is not a login shell is started, Bash
3012 reads and executes commands from @file{~/.bashrc}, if that file exists.
3013 This may be inhibited by using the @samp{--norc} option.
3014 The @samp{--rcfile @var{file}} option will force Bash to read and
3015 execute commands from @var{file} instead of @file{~/.bashrc}.
3017 So, typically, your @file{~/.bash_profile} contains the line
3019 @code{if [ -f @file{~/.bashrc} ]; then . @file{~/.bashrc}; fi}
3022 after (or before) any login-specific initializations.
3024 When Bash is started non-interactively, to run a shell script,
3025 for example, it looks for the variable @code{BASH_ENV} in the environment,
3026 expands its value if it appears there, and uses the expanded value as
3027 the name of a file to read and execute. Bash behaves as if the
3028 following command were executed:
3030 @code{if [ -n "$BASH_ENV" ]; then . "$BASH_ENV"; fi}
3033 but the value of the @code{PATH} variable is not used to search for the
3036 If Bash is invoked with the name @code{sh}, it tries to mimic the
3037 startup behavior of historical versions of @code{sh} as closely as
3038 possible, while conforming to the @sc{POSIX} standard as well.
3040 When invoked as a login shell, it first attempts to read and execute
3041 commands from @file{/etc/profile} and @file{~/.profile}, in that order.
3042 The @samp{--noprofile} option may be used to inhibit this behavior.
3043 When invoked as an interactive shell with the name @code{sh},
3044 @code{bash} looks for the variable @code{ENV},
3045 expands its value if it is defined, and uses the
3046 expanded value as the name of a file to read and execute.
3047 Since a shell invoked as @code{sh} does not attempt to read and execute
3048 commands from any other startup files, the @samp{--rcfile} option has
3050 A non-interactive shell invoked with the name @code{sh} does not attempt
3051 to read any startup files.
3053 When invoked as @code{sh}, Bash enters @sc{POSIX} mode after
3054 the startup files are read.
3056 When Bash is started in @sc{POSIX} mode, as with the
3057 @samp{--posix} command line option, it follows the @sc{POSIX} standard
3059 In this mode, the @code{ENV} variable is expanded and commands are read
3060 and executed from the file whose name is the expanded value.
3061 No other startup files are read.
3062 This is done by both interactive and non-interactive shells.
3064 Bash attempts to determine when it is being run by the remote shell
3065 daemon, usually @code{rshd}. If Bash determines it is being run by
3066 rshd, it reads and executes commands from @file{~/.bashrc}, if that
3067 file exists and is readable.
3068 It will not do this if invoked as @code{sh}.
3069 The @samp{--norc} option may be used to inhibit this behavior, and the
3070 @samp{--rcfile} option may be used to force another file to be read, but
3071 rshd does not generally invoke the shell with those options or allow
3072 them to be specified.
3074 @node Is This Shell Interactive?
3075 @section Is This Shell Interactive?
3076 @cindex interactive shell
3078 As defined in @ref{Invoking Bash}, an interactive shell
3079 is one whose input and output are both
3080 connected to terminals (as determined by @code{isatty(3)}),
3081 or one started with the @samp{-i} option.
3083 You may wish to determine within a startup script whether Bash is
3084 running interactively or not. To do this, examine the variable
3085 @code{$PS1}; it is unset in non-interactive shells, and set in
3086 interactive shells. Thus:
3089 if [ -z "$PS1" ]; then
3090 echo This shell is not interactive
3092 echo This shell is interactive
3097 @section Bash Builtin Commands
3099 This section describes builtin commands which are unique to
3100 or have been extended in Bash.
3107 bind [-m @var{keymap}] [-lpsvPSV] [-q @var{name}] [-r @var{keyseq}]
3108 bind [-m @var{keymap}] -f @var{filename}
3109 bind [-m @var{keymap}] @var{keyseq:function-name}
3112 Display current Readline (@pxref{Command Line Editing})
3113 key and function bindings, or
3114 bind a key sequence to a Readline function or macro. The
3115 binding syntax accepted is identical to that of
3116 @file{.inputrc} (@pxref{Readline Init File}),
3117 but each binding must be passed as a separate argument: e.g.,
3118 @samp{"\C-x\C-r":re-read-init-file}.
3119 Options, if supplied, have the following meanings:
3122 @item -m @var{keymap}
3123 Use @var{keymap} as the keymap to be affected by
3124 the subsequent bindings. Acceptable @var{keymap}
3127 @code{emacs-standard},
3131 @code{vi-command}, and
3133 @code{vi} is equivalent to @code{vi-command};
3134 @code{emacs} is equivalent to @code{emacs-standard}.
3137 List the names of all Readline functions
3140 Display Readline function names and bindings in such a way that they
3144 List current Readline function names and bindings
3147 Display Readline variable names and values in such a way that they
3151 List current Readline variable names and values
3154 Display Readline key sequences bound to macros and the strings they output
3155 in such a way that they can be re-read
3158 Display Readline key sequences bound to macros and the strings they output
3160 @item -f @var{filename}
3161 Read key bindings from @var{filename}
3164 Query about which keys invoke the named @var{function}
3166 @item -r @var{keyseq}
3167 Remove any current binding for @var{keyseq}
3174 builtin [@var{shell-builtin} [@var{args}]]
3176 Run a shell builtin. This is useful when you wish to rename a
3177 shell builtin to be a function, but need the functionality of the
3178 builtin within the function itself.
3183 command [-pVv] @var{command} [@var{args} @dots{}]
3185 Runs @var{command} with @var{arg} ignoring shell functions. If
3186 you have a shell function called @code{ls}, and you wish to call
3187 the command @code{ls}, you can say @samp{command ls}. The
3188 @samp{-p} option means to use a default value for @code{$PATH}
3189 that is guaranteed to find all of the standard utilities.
3191 If either the @samp{-V} or @samp{-v} option is supplied, a
3192 description of @var{command} is printed. The @samp{-v} option
3193 causes a single word indicating the command or file name used to
3194 invoke @var{command} to be printed; the @samp{-V} option produces
3195 a more verbose description.
3200 declare [-afFrxi] [-p] [@var{name}[=@var{value}]]
3203 Declare variables and give them attributes. If no @var{name}s
3204 are given, then display the values of variables instead.
3206 The @samp{-p} option will display the attributes and values of each
3207 @var{name}. When @samp{-p} is used, additional options are ignored.
3208 The @samp{-F} option inhibits the display of function definitions;
3209 only the function name and attributes are printed. @samp{-F} implies
3210 @samp{-f}. The following options can be used to restrict output
3211 to variables with the specified attributes or to give variables
3216 Each @var{name} is an array variable (@pxref{Arrays}).
3219 Use function names only.
3222 The variable is to be treated as
3223 an integer; arithmetic evaluation (@pxref{Shell Arithmetic}) is
3224 performed when the variable is assigned a value.
3227 Make @var{name}s readonly. These names cannot then be assigned values
3228 by subsequent assignment statements.
3231 Mark each @var{name} for export to subsequent commands via
3236 instead of @samp{-} turns off the attribute instead. When used in
3237 a function, @code{declare} makes each @var{name} local, as with the
3238 @code{local} command.
3243 echo [-neE] [arg @dots{}]
3245 Output the @code{arg}s, separated by spaces, terminated with a
3246 newline. The return status is always 0. If @samp{-n} is
3247 specified, the trailing newline is suppressed. If the @samp{-e}
3248 option is given, interpretation of the following backslash-escaped
3249 characters is enabled. The @samp{-E} option disables the interpretation
3250 of these escape characters, even on systems where they are interpreted
3252 @code{echo} interprets the following escape sequences:
3259 suppress trailing newline
3275 the character whose ASCII code is @code{nnn} (octal)
3281 enable [-n] [-p] [-f @var{filename}] [-ads] [@var{name} @dots{}]
3283 Enable and disable builtin shell commands. This allows you to
3284 use a disk command which has the same name as a shell builtin.
3285 If @samp{-n} is used, the @var{name}s become disabled. Otherwise
3286 @var{name}s are enabled. For example, to use the @code{test} binary
3287 found via @code{$PATH} instead of the shell builtin version, type
3288 @samp{enable -n test}.
3290 If the @samp{-p} option is supplied, or no @var{name} arguments appear,
3291 a list of shell builtins is printed. With no other arguments, the list
3292 consists of all enabled shell builtins.
3293 The @samp{-a} option means to list
3294 each builtin with an indication of whether or not it is enabled.
3296 The @samp{-f} option means to load the new builtin command @var{name}
3297 from shared object @var{filename}, on systems that support dynamic loading.
3298 The @samp{-d} option will delete a builtin loaded with @samp{-f}.
3299 If there are no options, a list of the shell builtins is displayed.
3300 The @samp{-s} option restricts @code{enable} to the @sc{POSIX.2} special
3301 builtins. If @samp{-s} is used with @samp{-f}, the new builtin becomes
3307 help [@var{pattern}]
3309 Display helpful information about builtin commands. If
3310 @var{pattern} is specified, @code{help} gives detailed help
3311 on all commands matching @var{pattern}, otherwise a list of
3312 the builtins is printed.
3317 local @var{name}[=@var{value}]
3319 For each argument, create a local variable called @var{name}, and
3320 give it @var{value}.
3321 @code{local} can only be used within a function; it makes the variable
3322 @var{name} have a visible scope restricted to that function and its
3330 Exit a login shell, returning a status of @var{n} to the shell's
3336 read [-a @var{aname}] [-p @var{prompt}] [-er] [@var{name} @dots{}]
3338 One line is read from the standard input, and the first word
3339 is assigned to the first
3340 @var{name}, the second word to the second @var{name},
3341 and so on, with leftover words assigned to the last @var{name}.
3342 Only the characters in the value of the @code{IFS} variable
3343 are recognized as word delimiters. If no names
3344 are supplied, the line read is assigned to the variable @code{REPLY}.
3345 The return code is zero, unless end-of-file is encountered. Options,
3346 if supplied, have the following meanings:
3350 If this option is given, a backslash-newline pair is not ignored, and
3351 the backslash is considered to be part of the line.
3353 @item -p @var{prompt}
3354 Display @code{prompt}, without a
3355 trailing newline, before attempting to read any input. The prompt
3356 is displayed only if input is coming from a terminal.
3358 @item -a @var{aname}
3359 The words are assigned to
3360 sequential indices of the array variable @var{aname}, starting at 0.
3363 Readline (@pxref{Command Line Editing})
3364 is used to obtain the line.
3370 shopt [-pqsu] [-o] [@var{optname} @dots{}]
3372 Toggle the values of variables controlling optional shell behavior.
3373 With no options, or with the @samp{-p}
3374 option, a list of all settable options is displayed, with
3375 an indication of whether or not each is set. Other options have
3376 the following meanings:
3380 Enable (set) each @var{optname}
3383 Disable (unset) each @var{optname}.
3386 Suppresses normal output; the return status
3387 indicates whether the @var{optname} is set or unset.
3388 If multiple @var{optname} arguments are given with @samp{-q},
3389 the return status is zero if all @var{optnames} are enabled;
3393 Restricts the values of
3394 @var{optname} to be those defined for the @samp{-o} option to the
3395 @code{set} builtin (@pxref{The Set Builtin}).
3399 @samp{-s} or @samp{-u}
3400 is used with no @var{optname} arguments, the display is limited to
3401 those options which are set or unset, respectively.
3403 Unless otherwise noted, the @code{shopt} options are disabled (off)
3406 The return status when listing options is zero if all @var{optnames}
3407 are enabled, non-zero otherwise. When setting or unsetting options,
3408 the return status is zero unless an @var{optname} is not a legal shell
3411 The list of @code{shopt} options is:
3414 If this is set, an argument to the @code{cd}
3415 builtin command that
3416 is not a directory is assumed to be the name of a variable whose
3417 value is the directory to change to.
3420 If set, minor errors in the spelling of a directory component in a
3421 @code{cd} command will be corrected.
3422 The errors checked for are transposed characters,
3423 a missing character, and a character too many.
3424 If a correction is found, the corrected path is printed,
3425 and the command proceeds.
3426 This option is enabled by default, but is only used by interactive shells.
3429 If this is set, Bash checks that a command found in the hash
3430 table exists before trying to execute it. If a hashed command no
3431 longer exists, a normal path search is performed.
3434 If set, Bash checks the window size after each command
3435 and, if necessary, updates the values of
3436 @code{LINES} and @code{COLUMNS}.
3440 attempts to save all lines of a multiple-line
3441 command in the same history entry. This allows
3442 easy re-editing of multi-line commands.
3445 If set, Bash includes filenames beginning with a `.' in
3446 the results of filename expansion.
3449 If this is set, a non-interactive shell will not exit if
3450 it cannot execute the file specified as an argument to the @code{exec}
3451 builtin command. An interactive shell does not exit if @code{exec}
3455 If set, the history list is appended to the file named by the value
3456 of the @code{HISTFILE}
3457 variable when the shell exits, rather than overwriting the file.
3460 If set, and Readline
3461 is being used, a user is given the opportunity to re-edit a
3462 failed history substitution.
3465 If set, and Readline
3466 is being used, the results of history substitution are not immediately
3467 passed to the shell parser. Instead, the resulting line is loaded into
3468 the Readline editing buffer, allowing further modification.
3471 If set, and Readline is being used, Bash will attempt to perform
3472 hostname completion when a word beginning with @samp{@@} is being
3473 completed (@pxref{Commands For Completion}).
3475 @item interactive_comments
3476 Allow a word beginning with @samp{#}
3477 to cause that word and all remaining characters on that
3478 line to be ignored in an interactive shell.
3479 This option is enabled by default.
3482 If enabled, and the @code{cmdhist}
3483 option is enabled, multi-line commands are saved to the history with
3484 embedded newlines rather than using semicolon separators where possible.
3487 If set, and a file that Bash is checking for mail has been
3488 accessed since the last time it was checked, the message
3489 @code{"The mail in @var{mailfile} has been read"} is displayed.
3492 If set, Bash allows filename patterns which match no
3493 files to expand to a null string, rather than themselves.
3496 If set, prompt strings undergo variable and parameter expansion after
3497 being expanded (@pxref{Printing a Prompt}).
3498 This option is enabled by default.
3501 If this is set, the @code{shift}
3502 builtin prints an error message when the shift count exceeds the
3503 number of positional parameters.
3506 If set, the @code{source} builtin uses the value of @code{PATH}
3507 to find the directory containing the file supplied as an argument.
3508 This is enabled by default.
3514 type [-all] [-type | -path] [@var{name} @dots{}]
3516 For each @var{name}, indicate how it would be interpreted if used as a
3519 If the @samp{-type} flag is used, @code{type} returns a single word
3520 which is one of @samp{alias}, @samp{function}, @samp{builtin},
3521 @samp{file} or @samp{keyword},
3522 if @var{name} is an alias, shell function, shell builtin,
3523 disk file, or shell reserved word, respectively.
3524 If the @var{name} is not found, then nothing is printed, and
3525 @code{type} returns a failure status.
3527 If the @samp{-path} flag is used, @code{type} either returns the name
3528 of the disk file that would be executed, or nothing if @samp{-type}
3529 would not return @samp{file}.
3531 If the @samp{-all} flag is used, returns all of the places that contain
3532 an executable named @var{file}. This includes aliases and functions,
3533 if and only if the @samp{-path} flag is not also used.
3535 @code{type} accepts @samp{-a}, @samp{-t}, and @samp{-p} as equivalent to
3536 @samp{-all}, @samp{-type}, and @samp{-path}, respectively.
3541 ulimit [-acdflmnpstuvSH] [@var{limit}]
3543 @code{ulimit} provides control over the resources available to processes
3544 started by the shell, on systems that allow such control. If an
3545 option is given, it is interpreted as follows:
3548 change and report the soft limit associated with a resource.
3551 change and report the hard limit associated with a resource.
3554 all current limits are reported.
3557 the maximum size of core files created.
3560 the maximum size of a process's data segment.
3563 the maximum size of files created by the shell.
3566 The maximum size that may be locked into memory.
3569 the maximum resident set size.
3572 the maximum number of open file descriptors.
3575 the pipe buffer size.
3578 the maximum stack size.
3581 the maximum amount of cpu time in seconds.
3584 the maximum number of processes available to a single user.
3587 the maximum amount of virtual memory available to the process.
3591 If @var{limit} is given, it is the new value of the specified resource.
3592 Otherwise, the current value of the soft limit for the specified resource
3593 is printed, unless the @samp{-H} option is supplied.
3594 When setting new limits, if neither @samp{-H} nor @samp{-S} is supplied,
3595 both the hard and soft limits are set.
3596 If no option is given, then @samp{-f} is assumed. Values are in 1024-byte
3597 increments, except for @samp{-t}, which is in seconds, @samp{-p},
3598 which is in units of 512-byte blocks, and @samp{-n} and @samp{-u}, which
3599 are unscaled values.
3603 @node The Set Builtin
3604 @section The Set Builtin
3606 This builtin is so overloaded that it deserves its own section.
3612 set [-abefhkmnptuvxdBCHP] [-o @var{option}] [@var{argument} @dots{}]
3617 Mark variables which are modified or created for export.
3620 Cause the status of terminated background jobs to be reported
3621 immediately, rather than before printing the next primary prompt.
3624 Exit immediately if a simple command exits with a non-zero status.
3627 Disable file name generation (globbing).
3630 Locate and remember (hash) commands as they are looked up for execution.
3633 All arguments in the form of assignment statements are placed
3634 in the environment for a command, not just those that precede
3638 Job control is enabled (@pxref{Job Control}).
3641 Read commands but do not execute them.
3643 @item -o @var{option-name}
3645 Set the flag corresponding to @var{option-name}:
3655 use an @code{emacs}-style line editing interface (@pxref{Command Line Editing}).
3667 Enable command history, as described in @ref{Bash History Facilities}.
3668 This option is on by default in interactive shells.
3671 the shell will not exit upon reading EOF.
3701 change the behavior of Bash where the default operation differs
3702 from the @sc{POSIX} 1003.2 standard to match the standard. This
3703 is intended to make Bash behave as a strict superset of that
3713 use a @code{vi}-style line editing interface.
3720 Turn on privileged mode.
3721 In this mode, the @code{$ENV}
3722 file is not processed, and shell functions
3723 are not inherited from the environment. This is enabled automatically
3724 on startup if the effective user (group) id is not equal to the real
3725 user (group) id. Turning this option off causes the effective user
3726 and group ids to be set to the real user and group ids.
3729 Exit after reading and executing one command.
3732 Treat unset variables as an error when substituting.
3735 Print shell input lines as they are read.
3738 Print commands and their arguments as they are executed.
3741 The shell will perform brace expansion (@pxref{Brace Expansion}).
3742 This option is on by default.
3745 Disallow output redirection to existing files.
3748 Enable @samp{!} style history substitution (@pxref{History Interaction}).
3749 This flag is on by default for interactive shells.
3752 If set, do not follow symbolic links when performing commands such as
3753 @code{cd} which change the current directory. The physical directory
3754 is used instead. By default, Bash follows
3755 the logical chain of directories when performing commands
3756 which change the current directory.
3758 For example, if @file{/usr/sys} is a link to @file{/usr/local/sys} then:
3760 $ cd /usr/sys; echo $PWD
3767 If @code{set -P} is on, then:
3769 $ cd /usr/sys; echo $PWD
3776 If no arguments follow this flag, then the positional parameters are
3777 unset. Otherwise, the positional parameters are set to the
3778 @var{arguments}, even if some of them begin with a @samp{-}.
3781 Signal the end of options, cause all remaining @var{arguments}
3782 to be assigned to the positional parameters. The @samp{-x}
3783 and @samp{-v} options are turned off.
3784 If there are no arguments, the positional parameters remain unchanged.
3787 Using @samp{+} rather than @samp{-} causes these flags to be
3788 turned off. The flags can also be used upon invocation of the
3789 shell. The current set of flags may be found in @code{$-}.
3791 The remaining N @var{arguments} are positional parameters and are
3792 assigned, in order, to @code{$1}, @code{$2}, @dots{} @code{$N}. If
3793 no arguments are given, all shell variables are printed.
3796 @node Bash Conditional Expressions
3797 @section Bash Conditional Expressions
3798 @cindex expressions, conditional
3800 Conditional expressions are used by the @code{test} and @code{[} builtins.
3802 Expressions may be unary or binary. Unary
3803 expressions are often used to examine the status of a file. There
3804 are string operators and numeric comparison operators as well. Each
3805 operator and operand must be a separate argument. If @var{file}
3806 is of the form @file{/dev/fd/@var{N}}, then file descriptor @var{N} is
3807 checked. Expressions are composed of the following primaries:
3811 True if @var{file} exists and is a block special file.
3814 True if @var{file} exists and is a character special file.
3817 True if @var{file} exists and is a directory.
3820 True if @var{file} exists.
3823 True if @var{file} exists and is a regular file.
3826 True if @var{file} exists and is set-group-id.
3829 True if @var{file} has its "sticky" bit set.
3832 True if @var{file} exists and is a symbolic link.
3835 True if @var{file} exists and is a named pipe.
3838 True if @var{file} exists and is readable.
3841 True if @var{file} exists and has a size greater than zero.
3844 True if @var{file} exists and is a socket.
3847 True if @var{fd} is opened on a terminal.
3850 True if @var{file} exists and its set-user-id bit is set.
3853 True if @var{file} exists and is writable.
3856 True if @var{file} exists and is executable.
3859 True if @var{file} exists and is owned by the effective user id.
3862 True if @var{file} exists and is owned by the effective group id.
3864 @item @var{file1} -nt @var{file2}
3865 True if @var{file1} is newer (according to
3866 modification date) than @var{file2}.
3868 @item @var{file1} -ot @var{file2}
3869 True if @var{file1} is older than @var{file2}.
3871 @item @var{file1} -ef @var{file2}
3872 True if @var{file1} and @var{file2} have the same device and
3875 @item -o @var{optname}
3876 True if shell option @var{optname} is enabled.
3877 The list of options appears in the description of the @samp{-o}
3878 option to the @code{set} builtin (@pxref{The Set Builtin}).
3880 @item -z @var{string}
3881 True if the length of @var{string} is zero.
3883 @item -n @var{string}
3885 True if the length of @var{string} is non-zero.
3887 @item @var{string1} = @var{string2}
3888 True if the strings are equal. @samp{==} may be used in place of
3891 @item @var{string1} != @var{string2}
3892 True if the strings are not equal.
3894 @item @var{string1} < @var{string2}
3895 True if @var{string1} sorts before @var{string2} lexicographically.
3897 @item @var{string1} > @var{string2}
3898 True if @var{string1} sorts after @var{string2} lexicographically.
3901 True if @var{expr} is false.
3903 @item @var{expr1} -a @var{expr2}
3904 True if both @var{expr1} and @var{expr2} are true.
3906 @item @var{expr1} -o @var{expr2}
3907 True if either @var{expr1} and @var{expr2} is true.
3909 @item @var{arg1} OP @var{arg2}
3911 @samp{-eq}, @samp{-ne}, @samp{-lt}, @samp{-le}, @samp{-gt}, or @samp{-ge}.
3912 These arithmetic binary operators return true if @var{arg1}
3913 is equal to, not equal to, less than, less than or equal to,
3914 greater than, or greater than or equal to @var{arg2},
3915 respectively. @var{Arg1} and @var{arg2}
3916 may be positive or negative integers.
3920 The Bash @code{test} and @code{[} builtins evaluate conditional
3921 expressions using a set of rules based on the number of arguments.
3922 These are the rules:
3926 The expression is false.
3928 The expression is true if and only if the argument is not null.
3930 If the first argument is @samp{!}, the expression is true if and
3931 only if the second argument is null. If the first argument is
3932 one of the listed unary operators, the expression is true if the
3933 unary test is true. If the first argument is not a legal unary
3934 operator, the expression is false.
3936 If the first argument is @samp{!}, the value is the negation of
3937 the two-argument test using the second and third arguments.
3938 If the second argument is one of the binary operators, the result
3939 of the expression is the result of the binary test using the first
3940 and third arguments as operands.
3941 If the first argument is exactly @samp{(} and the third argument is
3942 exactly @samp{)}, the result is the one-argument test of the second
3944 Otherwise, the expression is false.
3945 The @samp{-a} and @samp{-o} operators are considered binary operators
3948 If the first argument is @samp{!}, the result is the negation of
3949 the three-argument expression composed of the remaining arguments.
3950 Otherwise, the expression is parsed and evaluated according to
3951 precedence. @samp{-a} has a higher precedence than @samp{-o}.
3952 @item 5 or more arguments
3953 The expression is parsed and evaluated according to precedence,
3954 with @samp{-a} having a higher precedence than @samp{-o}.
3957 @node Bash Variables
3958 @section Bash Variables
3960 These variables are set or used by Bash, but other shells
3961 do not normally treat them specially.
3966 The value of this parameter is used as a format string specifying
3967 how the timing information for pipelines prefixed with the @code{time}
3968 reserved word should be displayed.
3969 The @samp{%} character introduces an
3970 escape sequence that is expanded to a time value or other
3972 The escape sequences and their meanings are as
3973 follows; the braces denote optional portions.
3980 @item %[@var{p}][l]R
3981 The elapsed time in seconds.
3983 @item %[@var{p}][l]U
3984 The number of CPU seconds spent in user mode.
3986 @item %[@var{p}][l]S
3987 The number of CPU seconds spent in system mode.
3990 The CPU percentage, computed as (%U + %S) / %R.
3993 The optional @var{p} is a digit specifying the precision, the number of
3994 fractional digits after a decimal point.
3995 A value of 0 causes no decimal point or fraction to be output.
3996 At most three places after the decimal point may be specified; values
3997 of @var{p} greater than 3 are changed to 3.
3998 If @var{p} is not specified, the value 3 is used.
4000 The optional @code{l} specifies a longer format, including minutes, of
4001 the form @var{MM}m@var{SS}.@var{FF}s.
4002 The value of @var{p} determines whether or not the fraction is included.
4004 If this variable is not set, bash acts as if it had the value
4005 @code{$'\nreal\t%3lR\nuser\t%3lU\nsys\t%3lS'}.
4006 If the value is null, no timing information is displayed.
4007 A trailing newline is added when the format string is displayed.
4010 Set to a value of @samp{ignorespace}, it means don't enter lines which
4011 begin with a space or tab into the history list. Set to a value
4012 of @samp{ignoredups}, it means don't enter lines which match the last
4013 entered line. A value of @samp{ignoreboth} combines the two options.
4014 Unset, or set to any other value than those above, means to save
4015 all lines on the history list.
4018 A colon-separated list of patterns used to decide which command
4019 lines should be saved on the history list. Each pattern is
4020 anchored at the beginning of the line and must fully specify the
4021 line (no implicit @samp{*} is appended). Each pattern is tested
4022 against the line after the checks specified by @code{HISTCONTROL}
4023 are applied. In addition to the normal shell pattern matching
4024 characters, @samp{&} matches the previous history line. @samp{&}
4025 may be escaped using a backslash. The backslash is removed
4026 before attempting a match.
4028 @code{HISTIGNORE} subsumes the function of @code{HISTCONTROL}. A
4029 pattern of @samp{&} is identical to @code{ignoredups}, and a
4030 pattern of @samp{[ ]*} is identical to @code{ignorespace}.
4031 Combining these two patterns, separating them with a colon,
4032 provides the functionality of @code{ignoreboth}.
4035 The name of the file to which the command history is saved. The
4036 default is @file{~/.bash_history}.
4039 If set, this is the maximum number of commands to remember in the
4043 The maximum number of lines contained in the history file. When this
4044 variable is assigned a value, the history file is truncated, if
4045 necessary, to contain no more than that number of lines. The default
4046 value is 500. The history file is also truncated to this size after
4047 writing it when an interactive shell exits.
4050 Up to three characters which control history expansion, quick
4051 substitution, and tokenization (@pxref{History Interaction}).
4052 The first character is the
4053 @dfn{history-expansion-char}, that is, the character which signifies the
4054 start of a history expansion, normally @samp{!}. The second character is the
4055 character which signifies `quick substitution' when seen as the first
4056 character on a line, normally @samp{^}. The optional third character is the
4057 character which signifies the remainder of the line is a comment, when
4058 found as the first character of a word, usually @samp{#}. The history
4059 comment character causes history substitution to be skipped for the
4060 remaining words on the line. It does not necessarily cause the shell
4061 parser to treat the rest of the line as a comment.
4064 The history number, or index in the history list, of the current
4065 command. If @code{HISTCMD} is unset, it loses its special properties,
4066 even if it is subsequently reset.
4069 Contains the name of a file in the same format as @file{/etc/hosts} that
4070 should be read when the shell needs to complete a hostname. You can
4071 change the file interactively; the next time you attempt to complete a
4072 hostname, Bash will add the contents of the new file to the already
4076 How often (in seconds) that the shell should check for mail
4077 in the files specified in @code{MAILPATH}.
4079 @item PROMPT_COMMAND
4080 If present, this contains a string which is a command to execute
4081 before the printing of each primary prompt (@code{$PS1}).
4084 The numeric real user id of the current user.
4087 The numeric effective user id of the current user.
4090 The process id of the shell's parent process.
4093 The name of the current host.
4096 A string describing the machine Bash is running on.
4099 A string describing the operating system Bash is running on.
4102 A string that fully describes the system type on which Bash
4103 is executing, in the standard GNU @var{cpu-company-system} format.
4106 A colon-separated list of enabled shell options. Each word in
4107 the list is a valid argument for the @samp{-o} option to the
4108 @code{set} builtin command (@pxref{The Set Builtin}).
4109 The options appearing in @code{SHELLOPTS} are those reported
4110 as @samp{on} by @samp{set -o}.
4111 If this variable is in the environment when Bash
4112 starts up, each shell option in the list will be enabled before
4113 reading any startup files. This variable is readonly.
4116 A colon-separated list of suffixes to ignore when performing
4117 filename completion.
4118 A file name whose suffix matches one of the entries in
4120 is excluded from the list of matched file names. A sample
4121 value is @samp{.o:~}
4124 A colon-separated list of patterns defining the set of filenames to
4125 be ignored by filename expansion.
4126 If a filename matched by a filename expansion pattern also matches one
4127 of the patterns in @code{GLOBIGNORE}, it is removed from the list
4131 An array variable (@pxref{Arrays})
4132 containing the current contents of the directory stack.
4133 Directories appear in the stack in the order they are displayed by the
4134 @code{dirs} builtin.
4135 Assigning to members of this array variable may be used to modify
4136 directories already in the stack, but the @code{pushd} and @code{popd}
4137 builtins must be used to add and remove directories.
4138 Assignment to this variable will not change the current directory.
4139 If @code{DIRSTACK} is unset, it loses its special properties, even if
4140 it is subsequently reset.
4143 An array variable (@pxref{Arrays})
4144 containing a list of exit status values from the processes
4145 in the most-recently-executed foreground pipeline (which may
4146 contain only a single command).
4149 The name of the Readline startup file, overriding the default
4150 of @file{~/.inputrc}.
4153 The full filename used to execute the current instance of Bash.
4156 The version number of the current instance of Bash.
4159 An array variable whose members hold version information for this
4161 The values assigned to the array members are as follows:
4165 @item BASH_VERSINFO[0]
4166 The major version number (the @var{release}).
4168 @item BASH_VERSINFO[1]
4169 The minor version number (the @var{version}).
4171 @item BASH_VERSINFO[2]
4174 @item BASH_VERSINFO[3]
4177 @item BASH_VERSINFO[4]
4178 The release status (e.g., @var{beta1}).
4180 @item BASH_VERSINFO[5]
4181 The value of @code{MACHTYPE}.
4186 Incremented by one each time a new instance of Bash is started. This is
4187 intended to be an account of how deeply your Bash shells are nested.
4190 If set to the value 1, Bash displays error messages
4191 generated by the @code{getopts} builtin command.
4194 Used to determine the locale category for any category not specifically
4195 selected with a variable starting with @code{LC_}.
4198 This variable overrides the value of @code{LANG} and any other
4199 @code{LC_} variable specifying a locale category.
4202 This variable determines the locale used to translate double-quoted
4203 strings preceded by a @samp{$}.
4206 Controls the action of the shell on receipt of an @code{EOF} character
4207 as the sole input. If set, then the value of it is the number
4208 of consecutive @code{EOF} characters that can be read as the
4209 first character on an input line
4210 before the shell will exit. If the variable exists but does not
4211 have a numeric value (or has no value) then the default is 10.
4212 If the variable does not exist, then @code{EOF} signifies the end of
4213 input to the shell. This is only in effect for interactive shells.
4217 @node Shell Arithmetic
4218 @section Shell Arithmetic
4219 @cindex arithmetic, shell
4222 * Arithmetic Evaluation:: How shell arithmetic works.
4223 * Arithmetic Expansion:: How to use arithmetic in shell expansions.
4224 * Arithmetic Builtins:: Builtin commands that use shell arithmetic.
4227 Bash includes several mechanisms to evaluate arithmetic expressions
4228 and display the result or use it as part of a command.
4230 @node Arithmetic Evaluation
4231 @subsection Arithmetic Evaluation
4232 @cindex expressions, arithmetic
4233 @cindex evaluation, arithmetic
4234 @cindex arithmetic evaluation
4236 The shell allows arithmetic expressions to be evaluated, as one of
4237 the shell expansions or by the @code{let} builtin.
4239 Evaluation is done in long integers with no check for overflow,
4240 though division by 0 is trapped and flagged as an error. The
4241 following list of operators is grouped into levels of
4242 equal-precedence operators. The levels are listed in order of
4243 decreasing precedence.
4247 unary minus and plus
4250 logical and bitwise negation
4253 multiplication, division, remainder
4256 addition, subtraction
4259 left and right bitwise shifts
4265 equality and inequality
4271 bitwise exclusive OR
4282 @item expr ? expr : expr
4283 conditional evaluation
4285 @item = *= /= %= += -= <<= >>= &= ^= |=
4289 Shell variables are allowed as operands; parameter expansion is
4290 performed before the expression is evaluated.
4291 The value of a parameter is coerced to a long integer within
4292 an expression. A shell variable need not have its integer attribute
4293 turned on to be used in an expression.
4295 Constants with a leading 0 are interpreted as octal numbers.
4296 A leading @samp{0x} or @samp{0X} denotes hexadecimal. Otherwise,
4297 numbers take the form [@var{base}@code{#}]@var{n}, where @var{base}
4298 is a decimal number between 2 and 64 representing the arithmetic
4299 base, and @var{n} is a number in that base. If @var{base} is
4300 omitted, then base 10 is used.
4301 The digits greater than 9 are represented by the lowercase letters,
4302 the uppercase letters, @samp{_}, and @samp{@@}, in that order.
4303 If @var{base} is less than or equal to 36, lowercase and uppercase
4304 letters may be used interchangably to represent numbers between 10
4307 Operators are evaluated in order of precedence. Sub-expressions in
4308 parentheses are evaluated first and may override the precedence
4311 @node Arithmetic Expansion
4312 @subsection Arithmetic Expansion
4313 @cindex expansion, arithmetic
4314 @cindex arithmetic expansion
4316 Arithmetic expansion allows the evaluation of an arithmetic expression
4317 and the substitution of the result. The format for arithmetic expansion is:
4320 $(( @var{expression} ))
4323 The expression is treated as if it were within double quotes, but
4324 a double quote inside the braces or parentheses is not treated
4325 specially. All tokens in the expression undergo parameter
4326 expansion, command substitution, and quote removal. Arithmetic
4327 substitutions may be nested.
4329 The evaluation is performed according to the rules listed above.
4330 If the expression is invalid, Bash
4331 prints a message indicating failure and no substitution occurs.
4333 @node Arithmetic Builtins
4334 @subsection Arithmetic Builtins
4341 let @var{expression} [@var{expression}]
4343 The @code{let} builtin allows arithmetic to be performed on shell
4344 variables. Each @var{expression} is evaluated according to the
4345 rules given previously (@pxref{Arithmetic Evaluation}). If the
4346 last @var{expression} evaluates to 0, @code{let} returns 1;
4347 otherwise 0 is returned.
4354 Bash provides one-dimensional array variables. Any variable may be used as
4355 an array; the @code{declare} builtin will explicitly declare an array.
4357 limit on the size of an array, nor any requirement that members
4358 be indexed or assigned contiguously. Arrays are zero-based.
4360 An array is created automatically if any variable is assigned to using
4363 name[@var{subscript}]=@var{value}
4368 is treated as an arithmetic expression that must evaluate to a number
4369 greater than or equal to zero. To explicitly declare an array, use
4371 declare -a @var{name}
4376 declare -a @var{name}[@var{subscript}]
4379 is also accepted; the @var{subscript} is ignored. Attributes may be
4380 specified for an array variable using the @code{declare} and
4381 @code{readonly} builtins. Each attribute applies to all members of
4384 Arrays are assigned to using compound assignments of the form
4386 name=(value@var{1} @dots{} value@var{n})
4390 @var{value} is of the form @code{[[@var{subscript}]=]}@var{string}. If
4391 the optional subscript is supplied, that index is assigned to;
4392 otherwise the index of the element assigned is the last index assigned
4393 to by the statement plus one. Indexing starts at zero.
4394 This syntax is also accepted by the @code{declare}
4395 builtin. Individual array elements may be assigned to using the
4396 @code{name[}@var{subscript}@code{]=}@var{value} syntax introduced above.
4398 Any element of an array may be referenced using
4399 @code{$@{name[}@var{subscript}@code{]@}}.
4400 The braces are required to avoid
4401 conflicts with the shell's filename expansion operators. If the
4402 @var{subscript} is @samp{@@} or @samp{*}, the word expands to all members
4403 of the array @var{name}. These subscripts differ only when the word
4404 appears within double quotes. If the word is double-quoted,
4405 @code{$@{name[*]@}} expands to a single word with
4406 the value of each array member separated by the first character of the
4407 @code{IFS} variable, and @code{$@{name[@@]@}} expands each element of
4408 @var{name} to a separate word. When there are no array members,
4409 @code{$@{name[@@]@}} expands to nothing. This is analogous to the
4410 expansion of the special parameters @samp{@@} and @samp{*}.
4411 @code{$@{#name[}@var{subscript}@code{]@}} expands to the length of
4412 @code{$@{name[}@var{subscript}@code{]@}}.
4413 If @var{subscript} is @samp{@@} or
4414 @samp{*}, the expansion is the number of elements in the array.
4415 Referencing an array variable without a subscript is equivalent to
4416 referencing element zero.
4418 The @code{unset} builtin is used to destroy arrays.
4419 @code{unset} @var{name[subscript]}
4420 destroys the array element at index @var{subscript}.
4421 @code{unset} @var{name}, where @var{name} is an array, removes the
4422 entire array. A subscript of @samp{*} or @samp{@@} also removes the
4425 The @code{declare}, @code{local}, and @code{readonly}
4426 builtins each accept a @samp{-a}
4427 option to specify an array. The @code{read}
4428 builtin accepts a @samp{-a}
4429 option to assign a list of words read from the standard input
4430 to an array, and can read values from the standard input into
4431 individual array elements. The @code{set} and @code{declare}
4432 builtins display array values in a way that allows them to be
4435 @node Printing a Prompt
4436 @section Controlling the Prompt
4439 The value of the variable @code{PROMPT_COMMAND} is examined just before
4440 Bash prints each primary prompt. If it is set and non-null, then the
4441 value is executed just as if you had typed it on the command line.
4443 In addition, the following table describes the special characters which
4444 can appear in the prompt variables:
4450 the date, in "Weekday Month Date" format (e.g., "Tue May 26").
4452 an escape character.
4454 the hostname, up to the first `.'.
4460 the name of the shell, the basename of @code{$0} (the portion
4461 following the final slash).
4463 the time, in 24-hour HH:MM:SS format.
4465 the time, in 12-hour HH:MM:SS format.
4467 the time, in 12-hour am/pm format.
4469 the version of Bash (e.g., 2.00)
4471 the release of Bash, version + patchlevel (e.g., 2.00.0)
4473 the current working directory.
4475 the basename of @code{$PWD}.
4479 the history number of this command.
4481 the command number of this command.
4483 if the effective uid is 0, @code{#}, otherwise @code{$}.
4485 the character corresponding to the octal number @code{nnn}.
4489 begin a sequence of non-printing characters. This could be used to
4490 embed a terminal control sequence into the prompt.
4492 end a sequence of non-printing characters.
4495 @node The Restricted Shell
4496 @section The Restricted Shell
4497 @cindex restricted shell
4499 If Bash is started with the name @code{rbash}, or the
4501 option is supplied at invocation, the shell becomes restricted.
4502 A restricted shell is used to
4503 set up an environment more controlled than the standard shell.
4504 A restricted shell behaves identically to @code{bash}
4505 with the exception that the following are disallowed:
4508 Changing directories with the @code{cd} builtin.
4510 Setting or unsetting the values of the @code{SHELL} or @code{PATH}
4513 Specifying command names containing slashes.
4515 Specifying a filename containing a slash as an argument to the @code{.}
4518 Importing function definitions from the shell environment at startup.
4520 Redirecting output using the @samp{>}, @samp{>|}, @samp{<>}, @samp{>&},
4521 @samp{&>}, and @samp{>>} redirection operators.
4523 Using the @code{exec} builtin to replace the shell with another command.
4525 Adding or deleting builtin commands with the
4526 @samp{-f} and @samp{-d} options to the @code{enable} builtin.
4528 Specifying the @samp{-p} option to the @code{command} builtin.
4530 Turning off restricted mode with @samp{set +r}.
4533 @node Bash POSIX Mode
4534 @section Bash POSIX Mode
4537 Starting Bash with the @samp{--posix} command-line option or executing
4538 @samp{set -o posix} while Bash is running will cause Bash to conform more
4539 closely to the @sc{POSIX.2} standard by changing the behavior to match that
4540 specified by @sc{POSIX.2} in areas where the Bash default differs.
4542 The following list is what's changed when `@sc{POSIX} mode' is in effect:
4546 When a command in the hash table no longer exists, Bash will re-search
4547 @code{$PATH} to find the new location. This is also available with
4548 @samp{shopt -s checkhash}.
4551 The @samp{>&} redirection does not redirect stdout and stderr.
4554 The message printed by the job control code and builtins when a job
4555 exits with a non-zero status is `Done(status)'.
4558 Reserved words may not be aliased.
4561 The @sc{POSIX.2} @code{PS1} and @code{PS2} expansions of @samp{!} to
4562 the history number and @samp{!!} to @samp{!} are enabled,
4563 and parameter expansion is performed on
4564 the value regardless of the setting of the @code{promptvars} option.
4567 Interactive comments are enabled by default. (Note that Bash has
4568 them on by default anyway.)
4571 The @sc{POSIX.2} startup files are executed (@code{$ENV}) rather than
4572 the normal Bash files.
4575 Tilde expansion is only performed on assignments preceding a command
4576 name, rather than on all assignment statements on the line.
4579 The default history file is @file{~/.sh_history} (this is the
4580 default value of @code{$HISTFILE}).
4583 The output of @samp{kill -l} prints all the signal names on a single line,
4584 separated by spaces.
4587 Non-interactive shells exit if @var{filename} in @code{.} @var{filename}
4591 Redirection operators do not perform filename expansion on the word
4592 in the redirection unless the shell is interactive.
4595 Function names must be valid shell @code{name}s. That is, they may not
4596 contain characters other than letters, digits, and underscores, and
4597 may not start with a digit. Declaring a function with an illegal name
4598 causes a fatal syntax error in non-interactive shells.
4601 @sc{POSIX.2} `special' builtins are found before shell functions
4602 during command lookup.
4605 If a @sc{POSIX.2} special builtin returns an error status, a
4606 non-interactive shell exits. The fatal errors are those listed in
4607 the POSIX.2 standard, and include things like passing incorrect options,
4608 redirection errors, variable assignment errors for assignments preceding
4609 the command name, and so on.
4613 The environment passed to executed commands is not sorted. Neither is
4614 the output of @code{set}. This is not strictly Posix.2 behavior, but
4615 @code{sh} does it this way. @code{ksh} does not. It's not necessary to
4616 sort the environment; no program should rely on it being sorted.
4620 If the @code{cd} builtin finds a directory to change to
4621 using @code{$CDPATH}, the
4622 value it assigns to the @code{PWD} variable does not contain any
4623 symbolic links, as if @samp{cd -P} had been executed.
4626 A non-interactive shell exits with an error status if a variable
4627 assignment error occurs when no command name follows the assignment
4629 A variable assignment error occurs, for example, when trying to assign
4630 a value to a read-only variable.
4633 A non-interactive shell exits with an error status if the iteration
4634 variable in a @code{for} statement or the selection variable in a
4635 @code{select} statement is a read-only variable.
4638 Process substitution is not available.
4641 Assignment statements preceding @sc{POSIX.2} @code{special} builtins
4642 persist in the shell environment after the builtin completes.
4646 There is other @sc{POSIX.2} behavior that Bash does not implement.
4651 Assignment statements affect the execution environment of all
4652 builtins, not just special ones.
4656 @chapter Job Control
4658 This chapter disusses what job control is, how it works, and how
4659 Bash allows you to access its facilities.
4662 * Job Control Basics:: How job control works.
4663 * Job Control Builtins:: Bash builtin commands used to interact
4665 * Job Control Variables:: Variables Bash uses to customize job
4669 @node Job Control Basics
4670 @section Job Control Basics
4674 @cindex suspending jobs
4677 refers to the ability to selectively stop (suspend)
4678 the execution of processes and continue (resume)
4679 their execution at a later point. A user typically employs
4680 this facility via an interactive interface supplied jointly
4681 by the system's terminal driver and Bash.
4683 The shell associates a @var{job} with each pipeline. It keeps a
4684 table of currently executing jobs, which may be listed with the
4685 @code{jobs} command. When Bash starts a job
4686 asynchronously (in the background), it prints a line that looks
4692 indicating that this job is job number 1 and that the process @sc{ID}
4693 of the last process in the pipeline associated with this job is
4694 25647. All of the processes in a single pipeline are members of
4695 the same job. Bash uses the @var{job} abstraction as the
4696 basis for job control.
4698 To facilitate the implementation of the user interface to job
4699 control, the system maintains the notion of a current terminal
4700 process group @sc{ID}. Members of this process group (processes whose
4701 process group @sc{ID} is equal to the current terminal process group
4702 @sc{ID}) receive keyboard-generated signals such as @code{SIGINT}.
4703 These processes are said to be in the foreground. Background
4704 processes are those whose process group @sc{ID} differs from the
4705 terminal's; such processes are immune to keyboard-generated
4706 signals. Only foreground processes are allowed to read from or
4707 write to the terminal. Background processes which attempt to
4708 read from (write to) the terminal are sent a @code{SIGTTIN}
4709 (@code{SIGTTOU}) signal by the terminal driver, which, unless
4710 caught, suspends the process.
4712 If the operating system on which Bash is running supports
4713 job control, Bash allows you to use it. Typing the
4714 @var{suspend} character (typically @samp{^Z}, Control-Z) while a
4715 process is running causes that process to be stopped and returns
4716 you to Bash. Typing the @var{delayed suspend} character
4717 (typically @samp{^Y}, Control-Y) causes the process to be stopped
4718 when it attempts to read input from the terminal, and control to
4719 be returned to Bash. You may then manipulate the state of
4720 this job, using the @code{bg} command to continue it in the
4721 background, the @code{fg} command to continue it in the
4722 foreground, or the @code{kill} command to kill it. A @samp{^Z}
4723 takes effect immediately, and has the additional side effect of
4724 causing pending output and typeahead to be discarded.
4726 There are a number of ways to refer to a job in the shell. The
4727 character @samp{%} introduces a job name. Job number @code{n}
4728 may be referred to as @samp{%n}. A job may also be referred to
4729 using a prefix of the name used to start it, or using a substring
4730 that appears in its command line. For example, @samp{%ce} refers
4731 to a stopped @code{ce} job. Using @samp{%?ce}, on the
4732 other hand, refers to any job containing the string @samp{ce} in
4733 its command line. If the prefix or substring matches more than one job,
4734 Bash reports an error. The symbols @samp{%%} and
4735 @samp{%+} refer to the shell's notion of the current job, which
4736 is the last job stopped while it was in the foreground. The
4737 previous job may be referenced using @samp{%-}. In output
4738 pertaining to jobs (e.g., the output of the @code{jobs} command),
4739 the current job is always flagged with a @samp{+}, and the
4740 previous job with a @samp{-}.
4742 Simply naming a job can be used to bring it into the foreground:
4743 @samp{%1} is a synonym for @samp{fg %1}, bringing job 1 from the
4744 background into the foreground. Similarly, @samp{%1 &} resumes
4745 job 1 in the background, equivalent to @samp{bg %1}
4747 The shell learns immediately whenever a job changes state.
4748 Normally, Bash waits until it is about to print a prompt
4749 before reporting changes in a job's status so as to not interrupt
4750 any other output. If the
4751 the @samp{-b} option to the @code{set} builtin is set,
4752 Bash reports such changes immediately (@pxref{The Set Builtin}).
4754 If you attempt to exit Bash while jobs are stopped, the
4755 shell prints a message warning you that you have stopped jobs.
4756 You may then use the
4757 @code{jobs} command to inspect their status. If you do this, or
4758 try to exit again immediately, you are not warned again, and the
4759 stopped jobs are terminated.
4761 @node Job Control Builtins
4762 @section Job Control Builtins
4771 Place @var{jobspec} into the background, as if it had been started
4772 with @samp{&}. If @var{jobspec} is not supplied, the current job
4780 Bring @var{jobspec} into the foreground and make it the current job.
4781 If @var{jobspec} is not supplied, the current job is used.
4786 jobs [-lpnrs] [@var{jobspec}]
4787 jobs -x @var{command} [@var{jobspec}]
4790 The first form lists the active jobs. The options have the
4795 List process @sc{ID}s in addition to the normal information
4798 Display information only about jobs that have changed status since
4799 you were last notified of their status.
4802 List only the process @sc{ID} of the job's process group
4806 Restrict output to running jobs.
4809 Restrict output to stopped jobs.
4812 If @var{jobspec} is given,
4813 output is restricted to information about that job.
4814 If @var{jobspec} is not supplied, the status of all jobs is
4817 If the @samp{-x} option is supplied, @code{jobs} replaces any
4818 @var{jobspec} found in @var{command} or @var{arguments} with the
4819 corresponding process group @sc{ID}, and executes @var{command},
4820 passing it @var{argument}s, returning its exit status.
4825 kill [-s @var{sigspec}] [-n @var{signum}] [-@var{sigspec}] @var{jobspec}
4826 kill -l [@var{sigspec}]
4828 Send a signal specified by @var{sigspec} or @var{signum} to the process
4829 named by @var{jobspec}. @var{sigspec} is either a signal name such as
4830 @code{SIGINT} or a signal number; @var{signum} is a signal number. If
4831 @var{sigspec} and @var{signum} are not present, @code{SIGTERM} is used.
4832 The @samp{-l} option lists the signal names, or the signal name
4833 corresponding to @var{sigspec}.
4838 wait [@var{jobspec}|@var{pid}]
4840 Wait until the child process specified by process @sc{ID} @var{pid} or job
4841 specification @var{jobspec} exits and report its exit status. If a job
4842 spec is given, all processes in the job are waited for. If no arguments
4843 are given, all currently active child processes are waited for.
4848 disown [-h] [@var{jobspec} @dots{}]
4850 Without options, each @var{jobspec} is removed from the table of
4852 If the @samp{-h} option is given, the job is not removed from the table,
4853 but is marked so that @code{SIGHUP} is not sent to the job if the shell
4854 receives a @code{SIGHUP}.
4855 If @var{jobspec} is not present, the current job is used.
4862 Suspend the execution of this shell until it receives a
4863 @code{SIGCONT} signal. The @samp{-f} option means to suspend
4864 even if the shell is a login shell.
4868 When job control is not active, the @code{kill} and @code{wait}
4869 builtins do not accept @var{jobspec} arguments. They must be
4870 supplied process @sc{ID}s.
4872 @node Job Control Variables
4873 @section Job Control Variables
4878 This variable controls how the shell interacts with the user and
4879 job control. If this variable exists then single word simple
4880 commands without redirects are treated as candidates for resumption
4881 of an existing job. There is no ambiguity allowed; if you have
4882 more than one job beginning with the string that you have typed, then
4883 the most recently accessed job will be selected.
4884 The name of a stopped job, in this context, is the command line
4885 used to start it. If this variable is set to the value @samp{exact},
4886 the string supplied must match the name of a stopped job exactly;
4887 if set to @samp{substring},
4888 the string supplied needs to match a substring of the name of a
4889 stopped job. The @samp{substring} value provides functionality
4890 analogous to the @samp{%?} job @sc{ID} (@pxref{Job Control Basics}).
4891 If set to any other value, the supplied string must
4892 be a prefix of a stopped job's name; this provides functionality
4893 analogous to the @samp{%} job @sc{ID}.
4897 @set readline-appendix
4898 @set history-appendix
4899 @cindex History, how to use
4900 @include hsuser.texinfo
4901 @cindex Readline, how to use
4902 @include rluser.texinfo
4903 @clear readline-appendix
4904 @clear history-appendix
4906 @node Installing Bash
4907 @chapter Installing Bash
4909 This chapter provides basic instructions for installing Bash on
4910 the various supported platforms. The distribution supports nearly every
4911 version of Unix (and, someday, @sc{GNU}). Other independent ports exist for
4912 @sc{OS/2}, Windows 95, and Windows @sc{NT}.
4915 * Basic Installation:: Generic installation instructions.
4917 * Compilers and Options:: How to set special options for various
4920 * Compiling For Multiple Architectures:: How to compile Bash for more
4921 than one kind of system from
4922 the same source tree.
4924 * Installation Names:: How to set the various paths used by the installation.
4926 * Specifying the System Type:: How to configure Bash for a particular system.
4928 * Sharing Defaults:: How to share default configuration values among GNU
4931 * Operation Controls:: Options recognized by the configuration program.
4933 * Optional Features:: How to enable and disable optional features when
4937 @node Basic Installation
4938 @section Basic Installation
4939 @cindex installation
4940 @cindex configuration
4941 @cindex Bash installation
4942 @cindex Bash configuration
4944 These are generic installation instructions for Bash.
4946 The @code{configure} shell script attempts to guess correct
4947 values for various system-dependent variables used during
4948 compilation. It uses those values to create a @file{Makefile} in
4949 each directory of the package (the top directory, the
4950 @file{builtins} and @file{doc} directories, and the
4951 each directory under @file{lib}). It also creates a
4952 @file{config.h} file containing system-dependent definitions.
4953 Finally, it creates a shell script named @code{config.status} that you
4954 can run in the future to recreate the current configuration, a
4955 file @file{config.cache} that saves the results of its tests to
4956 speed up reconfiguring, and a file @file{config.log} containing
4957 compiler output (useful mainly for debugging @code{configure}).
4959 @file{config.cache} contains results you don't want to keep, you
4960 may remove or edit it.
4962 If you need to do unusual things to compile the package, please
4963 try to figure out how @code{configure} could check whether or not
4964 to do them, and mail diffs or instructions to
4965 @code{bash-maintainers@@prep.ai.mit.edu} so they can be
4966 considered for the next release.
4968 The file @file{configure.in} is used to create @code{configure}
4969 by a program called Autoconf. You only need
4970 @file{configure.in} if you want to change it or regenerate
4971 @code{configure} using a newer version of Autoconf. If
4972 you do this, make sure you are using Autoconf version 2.9 or
4975 The simplest way to compile Bash is:
4979 @code{cd} to the directory containing the source code and type
4980 @samp{./configure} to configure Bash for your system. If you're
4981 using @code{csh} on an old version of System V, you might need to
4982 type @samp{sh ./configure} instead to prevent @code{csh} from trying
4983 to execute @code{configure} itself.
4985 Running @code{configure} takes awhile. While running, it prints some
4986 messages telling which features it is checking for.
4989 Type @samp{make} to compile Bash and build the @code{bashbug} bug
4993 Optionally, type @samp{make tests} to run the Bash test suite.
4996 Type @samp{make install} to install @code{bash} and @code{bashbug}.
4997 This will also install the manual pages and Info file.
5001 You can remove the program binaries and object files from the
5002 source code directory by typing @samp{make clean}. To also remove the
5003 files that @code{configure} created (so you can compile Bash for
5004 a different kind of computer), type @samp{make distclean}.
5006 @node Compilers and Options
5007 @section Compilers and Options
5009 Some systems require unusual options for compilation or linking
5010 that the @code{configure} script does not know about. You can
5011 give @code{configure} initial values for variables by setting
5012 them in the environment. Using a Bourne-compatible shell, you
5013 can do that on the command line like this:
5016 CC=c89 CFLAGS=-O2 LIBS=-lposix ./configure
5019 On systems that have the @code{env} program, you can do it like this:
5022 env CPPFLAGS=-I/usr/local/include LDFLAGS=-s ./configure
5025 The configuration process uses GCC to build Bash if it
5028 @node Compiling For Multiple Architectures
5029 @section Compiling For Multiple Architectures
5031 You can compile Bash for more than one kind of computer at the
5032 same time, by placing the object files for each architecture in their
5033 own directory. To do this, you must use a version of @code{make} that
5034 supports the @code{VPATH} variable, such as GNU @code{make}.
5036 directory where you want the object files and executables to go and run
5037 the @code{configure} script from the source directory. You may need to
5038 supply the @samp{--srcdir=PATH} argument to tell @code{configure} where the
5039 source files are. @code{configure} automatically checks for the
5040 source code in the directory that @code{configure} is in and in `..'.
5042 If you have to use a @code{make} that does not supports the @code{VPATH}
5043 variable, you can compile Bash for one architecture at a
5044 time in the source code directory. After you have installed
5045 Bash for one architecture, use @samp{make distclean} before
5046 reconfiguring for another architecture.
5048 Alternatively, if your system supports symbolic links, you can use the
5049 @file{support/mkclone} script to create a build tree which has
5050 symbolic links back to each file in the source directory. Here's an
5051 example that creates a build directory in the current directory from a
5052 source directory @file{/usr/gnu/src/bash-2.0}:
5055 bash /usr/gnu/src/bash-2.0/support/mkclone -s /usr/gnu/src/bash-2.0 .
5059 The @code{mkclone} script requires Bash, so you must have already built
5060 Bash for at least one architecture before you can create build
5061 directories for other architectures.
5063 @node Installation Names
5064 @section Installation Names
5066 By default, @samp{make install} will install into
5067 @file{/usr/local/bin}, @file{/usr/local/man}, etc. You can
5068 specify an installation prefix other than @file{/usr/local} by
5069 giving @code{configure} the option @samp{--prefix=PATH}.
5071 You can specify separate installation prefixes for
5072 architecture-specific files and architecture-independent files.
5073 If you give @code{configure} the option
5074 @samp{--exec-prefix=PATH}, the package will use @samp{PATH} as the
5075 prefix for installing programs and libraries. Documentation and
5076 other data files will still use the regular prefix.
5078 @node Specifying the System Type
5079 @section Specifying the System Type
5081 There may be some features @code{configure} can not figure out
5082 automatically, but needs to determine by the type of host the
5083 package will run on. Usually @code{configure} can figure that
5084 out, but if it prints a message saying it can not guess the host
5085 type, give it the @samp{--host=TYPE} option. @samp{TYPE} can
5086 either be a short name for the system type, such as @samp{sun4},
5087 or a canonical name with three fields: @samp{CPU-COMPANY-SYSTEM}
5088 (e.g., @samp{sparc-sun-sunos4.1.2}).
5090 @noindent See the file @file{support/config.sub} for the possible
5091 values of each field.
5093 @node Sharing Defaults
5094 @section Sharing Defaults
5096 If you want to set default values for @code{configure} scripts to
5097 share, you can create a site shell script called
5098 @code{config.site} that gives default values for variables like
5099 @code{CC}, @code{cache_file}, and @code{prefix}. @code{configure}
5100 looks for @file{PREFIX/share/config.site} if it exists, then
5101 @file{PREFIX/etc/config.site} if it exists. Or, you can set the
5102 @code{CONFIG_SITE} environment variable to the location of the site
5103 script. A warning: the Bash @code{configure} looks for a site script,
5104 but not all @code{configure} scripts do.
5106 @node Operation Controls
5107 @section Operation Controls
5109 @code{configure} recognizes the following options to control how it
5114 @item --cache-file=@var{FILE}
5115 Use and save the results of the tests in
5116 @var{FILE} instead of @file{./config.cache}. Set @var{FILE} to
5117 @file{/dev/null} to disable caching, for debugging
5121 Print a summary of the options to @code{configure}, and exit.
5126 Do not print messages saying which checks are being made.
5128 @item --srcdir=@var{DIR}
5129 Look for the Bash source code in directory @var{DIR}. Usually
5130 @code{configure} can determine that directory automatically.
5133 Print the version of Autoconf used to generate the @code{configure}
5137 @code{configure} also accepts some other, not widely used, boilerplate
5140 @node Optional Features
5141 @section Optional Features
5143 The Bash @code{configure} has a number of @samp{--enable-@var{FEATURE}}
5144 options, where @var{FEATURE} indicates an optional part of the
5145 package. There are also several @samp{--with-@var{PACKAGE}} options,
5146 where @var{PACKAGE} is something like @samp{gnu-malloc} or
5147 @samp{purify} (for the Purify memory allocation checker). To
5148 turn off the default use of a package, use
5149 @samp{--without-@var{PACKAGE}}. To configure Bash without a feature
5150 that is enabled by default, use @samp{--disable-@var{FEATURE}}.
5152 Here is a complete list of the @samp{--enable-} and
5153 @samp{--with-} options that the Bash @code{configure} recognizes.
5156 @item --with-gnu-malloc
5157 Use the @sc{GNU} version of
5158 @code{malloc} in @file{lib/malloc/malloc.c}. This is not the same
5159 @code{malloc} that appears in @sc{GNU} libc, but an older version
5160 derived from the 4.2 @sc{BSD} @code{malloc}. This @code{malloc} is
5161 very fast, but wastes a lot of space. This option is enabled by
5162 default. The @file{NOTES} file contains a list of systems for
5163 which this should be turned off.
5165 @item --with-glibc-malloc
5166 Use the @sc{GNU} libc version of @code{malloc} in
5167 @file{lib/malloc/gmalloc.c}. This is somewhat slower than the
5168 default @code{malloc}, but wastes considerably less space.
5171 Define if you are using the Andrew File System from Transarc.
5174 Define this to use the Purify memory allocation checker from Pure
5177 @item --enable-minimal-config
5178 This produces a shell with minimal features, close to the historical
5183 The @samp{minimal-config} option can be used to disable all of
5184 the following options, but it is processed first, so individual
5185 options may be enabled using @samp{enable-@var{FEATURE}}.
5187 All of the following options except for @samp{disabled-builtins} and
5188 @samp{usg-echo-default} are
5189 enabled by default, unless the operating system does not provide the
5193 @item --enable-job-control
5194 This enables job control features, if the @sc{OS} supports them.
5196 @item --enable-alias
5197 Allow alias expansion and include the @code{alias} and @code{unalias}
5200 @item --enable-readline
5201 Include support for command-line editing and history with the Bash
5202 version of the Readline library.
5204 @item --enable-history
5205 Include command history and the @code{fc} and @code{history}
5208 @item --enable-bang-history
5209 Include support for @code{csh}-like history substitution.
5211 @item --enable-directory-stack
5212 Include support for a @code{csh}-like directory stack and the
5213 @code{pushd}, @code{popd}, and @code{dirs} builtins.
5215 @item --enable-restricted
5216 Include support for a @dfn{restricted shell}. If this is enabled, Bash,
5217 when called as @code{rbash}, enters a restricted mode. See
5218 @ref{The Restricted Shell}, for a description of restricted mode.
5220 @item --enable-process-substitution
5221 This enables process substitution (@pxref{Process Substitution}) if
5222 the @sc{OS} provides the necessary support.
5224 @item --enable-prompt-string-decoding
5225 Turn on the interpretation of a number of backslash-escaped characters
5226 in the @code{$PS1}, @code{$PS2}, @code{$PS3}, and @code{$PS4} prompt
5229 @item --enable-select
5230 Include the @code{ksh} @code{select} builtin, which allows the
5231 generation of simple menus.
5233 @item --enable-help-builtin
5234 Include the @code{help} builtin, which displays help on shell builtins and
5237 @item --enable-array-variables
5238 Include support for one-dimensional array shell variables.
5240 @item --enable-dparen-arithmetic
5241 Include support for the @code{ksh} @code{((@dots{}))} command.
5243 @item --enable-brace-expansion
5244 Include @code{csh}-like brace expansion
5245 ( @code{b@{a,b@}c} @expansion{} @code{bac bbc} ).
5247 @item --enable-disabled-builtins
5248 Allow builtin commands to be invoked via @samp{builtin xxx}
5249 even after @code{xxx} has been disabled using @samp{enable -n xxx}.
5250 See @ref{Bash Builtins}, for details of the @code{builtin} and
5251 @code{enable} builtin commands.
5253 @item --enable-command-timing
5254 Include support for recognizing @code{time} as a reserved word and for
5255 displaying timing statistics for the pipeline following @code{time}. This
5256 allows pipelines as well as shell builtins and functions to be timed.
5258 @item --enable-usg-echo-default
5259 Make the @code{echo} builtin expand backslash-escaped characters by default,
5260 without requiring the @samp{-e} option. This makes the Bash @code{echo}
5261 behave more like the System V version.
5265 The file @file{config.h.top} contains C Preprocessor
5266 @samp{#define} statements for options which are not settable from
5268 Some of these are not meant to be changed; beware of the consequences if
5270 Read the comments associated with each definition for more
5271 information about its effect.
5273 @node Reporting Bugs
5274 @appendix Reporting Bugs
5276 Please report all bugs you find in Bash.
5277 But first, you should
5278 make sure that it really is a bug, and that it appears in the latest
5279 version of Bash that you have.
5281 Once you have determined that a bug actually exists, use the
5282 @code{bashbug} command to submit a bug report.
5283 If you have a fix, you are welcome to mail that as well!
5284 Suggestions and `philosophical' bug reports may be mailed
5285 to @code{bug-bash@@prep.ai.MIT.Edu} or posted to the Usenet
5286 newsgroup @code{gnu.bash.bug}.
5288 All bug reports should include:
5291 The version number of Bash.
5293 The hardware and operating system.
5295 The compiler used to compile Bash.
5297 A description of the bug behaviour.
5299 A short script or `recipe' which exercises the bug and may be used
5304 @code{bashbug} inserts the first three items automatically into
5305 the template it provides for filing a bug report.
5307 Please send all reports concerning this manual to
5308 @code{chet@@ins.CWRU.Edu}.
5311 @appendix Index of Shell Builtin Commands
5314 @node Reserved Word Index
5315 @appendix Shell Reserved Words
5318 @node Variable Index
5319 @appendix Parameter and Variable Index
5322 @node Function Index
5323 @appendix Function Index
5327 @appendix Concept Index