1 \input texinfo.tex @c -*- texinfo -*-
3 @setfilename bashref.info
4 @settitle Bash Reference Manual
8 last change: Mon May 19 12:55:22 EDT 1997
13 @set UPDATED 19 May 1997
14 @set UPDATE-MONTH May 1997
20 @setchapternewpage odd
25 @dircategory Utilities
27 * Bash: (bash). GNU Bourne-Again SHell
32 This text is a brief description of the features that are present in
35 This is Edition @value{EDITION}, last updated @value{UPDATED},
36 of @cite{The GNU Bash Reference Manual},
37 for @code{Bash}, Version @value{VERSION}.
39 Copyright (C) 1991, 1993, 1996 Free Software Foundation, Inc.
41 Permission is granted to make and distribute verbatim copies of
42 this manual provided the copyright notice and this permission notice
43 are preserved on all copies.
46 Permission is granted to process this file through TeX and print the
47 results, provided the printed document carries copying permission
48 notice identical to this one except for the removal of this paragraph
49 (this paragraph not being relevant to the printed manual).
52 Permission is granted to copy and distribute modified versions of this
53 manual under the conditions for verbatim copying, provided that the entire
54 resulting derived work is distributed under the terms of a permission
55 notice identical to this one.
57 Permission is granted to copy and distribute translations of this manual
58 into another language, under the above conditions for modified versions,
59 except that this permission notice may be stated in a translation approved
65 @title Bash Reference Manual
66 @subtitle Reference Documentation for Bash
67 @subtitle Edition @value{EDITION}, for @code{bash} Version @value{VERSION}.
68 @subtitle @value{UPDATED}
69 @author Chet Ramey, Case Western Reserve University
70 @author Brian Fox, Free Software Foundation
72 @vskip 0pt plus 1filll
73 Copyright @copyright{} 1991, 1993, 1996 Free Software Foundation, Inc.
75 Permission is granted to make and distribute verbatim copies of
76 this manual provided the copyright notice and this permission notice
77 are preserved on all copies.
79 Permission is granted to copy and distribute modified versions of this
80 manual under the conditions for verbatim copying, provided that the entire
81 resulting derived work is distributed under the terms of a permission
82 notice identical to this one.
84 Permission is granted to copy and distribute translations of this manual
85 into another language, under the above conditions for modified versions,
86 except that this permission notice may be stated in a translation approved
87 by the Free Software Foundation.
91 @node Top, Introduction, (dir), (dir)
96 This text is a brief description of the features that are present in
99 This is Edition @value{EDITION}, last updated @value{UPDATED},
100 of @cite{The GNU Bash Reference Manual},
101 for @code{Bash}, Version @value{VERSION}.
103 Copyright (C) 1991, 1993, 1996 Free Software Foundation, Inc.
105 Bash contains features that appear in other popular shells, and some
106 features that only appear in Bash. Some of the shells that Bash has
107 borrowed concepts from are the Bourne Shell (@file{sh}), the Korn Shell
108 (@file{ksh}), and the C-shell (@file{csh} and its successor,
109 @file{tcsh}). The following menu breaks the features up into
110 categories based upon which one of these other shells inspired the
113 This manual is meant as a brief introduction to features found in
114 Bash. The Bash manual page should be used as the definitive
115 reference on shell behavior.
118 * Introduction:: An introduction to the shell.
120 * Definitions:: Some definitions used in the rest of this
123 * Basic Shell Features:: The shell "building blocks".
125 * Bourne Shell Features:: Features similar to those found in the
128 * Csh Features:: Features originally found in the
131 * Korn Shell Features:: Features originally found in the Korn
134 * Bash Features:: Features found only in Bash.
136 * Job Control:: A chapter describing what job control is
137 and how Bash allows you to use it.
139 * Using History Interactively:: Chapter dealing with history expansion
142 * Command Line Editing:: Chapter describing the command line
145 * Installing Bash:: How to build and install Bash on your system.
147 * Reporting Bugs:: How to report bugs in Bash.
149 * Builtin Index:: Index of Bash builtin commands.
151 * Reserved Word Index:: Index of Bash reserved words.
153 * Variable Index:: Quick reference helps you find the
156 * Function Index:: Index of bindable Readline functions.
158 * Concept Index:: General index for concepts described in
164 @chapter Introduction
166 * What is Bash?:: A short description of Bash.
168 * What is a shell?:: A brief introduction to shells.
172 @section What is Bash?
174 Bash is the shell, or command language interpreter,
175 that will appear in the @sc{GNU} operating system.
176 The name is an acronym for the @samp{Bourne-Again SHell},
177 a pun on Steve Bourne, the author of the direct ancestor of the current
178 Unix shell @code{/bin/sh},
179 which appeared in the Seventh Edition Bell Labs Research version
182 Bash is an @code{sh}-compatible shell that incorporates useful
183 features from the Korn shell @code{ksh} and the C shell @code{csh}.
184 It is ultimately intended to be a
185 conformant implementation of the @sc{IEEE} @sc{POSIX} Shell and Tools
186 specification (@sc{IEEE} Working Group 1003.2). It offers functional
187 improvements over @code{sh} for both interactive and programming use.
189 While the @sc{GNU} operating system will include a version
190 of @code{csh}, Bash will be the default shell.
191 Like other @sc{GNU} software, Bash is quite portable. It currently runs
192 on nearly every version of Unix and a few other operating systems @minus{}
193 independently-supported ports exist for @sc{OS/2} and Windows @sc{NT}.
195 @node What is a shell?
196 @section What is a shell?
198 At its base, a shell is simply a macro processor that executes
199 commands. A Unix shell is both a command interpreter, which
200 provides the user interface to the rich set of Unix utilities,
201 and a programming language, allowing these utilitites to be
202 combined. The shell reads commands either from a terminal or a
203 file. Files containing commands can be created, and become
204 commands themselves. These new commands have the same status as
205 system commands in directories like @file{/bin}, allowing users
206 or groups to establish custom environments.
208 A shell allows execution of Unix commands, both synchronously and
209 asynchronously. The @dfn{redirection} constructs permit
210 fine-grained control of the input and output of those commands,
211 and the shell allows control over the contents of their
212 environment. Unix shells also provide a small set of built-in
213 commands (@dfn{builtins}) implementing functionality impossible
214 (e.g., @code{cd}, @code{break}, @code{continue}, and
215 @code{exec}), or inconvenient (@code{history}, @code{getopts},
216 @code{kill}, or @code{pwd}, for example) to obtain via separate
217 utilities. Shells may be used interactively or
218 non-interactively: they accept input typed from the keyboard or
219 from a file. All of the shell builtins are described in
222 While executing commands is essential, most of the power (and
223 complexity) of shells is due to their embedded programming
224 languages. Like any high-level language, the shell provides
225 variables, flow control constructs, quoting, and functions.
227 Shells have begun offering features geared specifically for
228 interactive use rather than to augment the programming language.
229 These interactive features include job control, command line
230 editing, history and aliases. Each of these features is
231 described in this manual.
235 These definitions are used throughout the remainder of this manual.
241 A family of open system standards based on Unix. Bash
242 is concerned with @sc{POSIX} 1003.2, the Shell and Tools Standard.
245 A space or tab character.
249 A command that is implemented internally by the shell itself, rather
250 than by an executable program somewhere in the file system.
252 @item control operator
253 @cindex control operator
254 A @code{word} that performs a control function. It is a @code{newline}
255 or one of the following:
256 @samp{||}, @samp{&&}, @samp{&}, @samp{;}, @samp{;;},
257 @samp{|}, @samp{(}, or @samp{)}.
261 The value returned by a command to its caller.
265 A unit of text that is the result of one of the shell expansions. After
266 expansion, when executing a command, the resulting fields are used as
267 the command name and arguments.
271 A string of characters used to identify a file.
275 A set of processes comprising a pipeline, and any processes descended
276 from it, that are all in the same process group.
280 A mechanism by which users can selectively stop (suspend) and restart
281 (resume) execution of processes.
284 @cindex metacharacter
285 A character that, when unquoted, separates words. A metacharacter is
286 a @code{blank} or one of the following characters:
287 @samp{|}, @samp{&}, @samp{;}, @samp{(}, @samp{)}, @samp{<}, or
293 A @code{word} consisting solely of letters, numbers, and underscores,
294 and beginning with a letter or underscore. @code{Name}s are used as
295 shell variable and function names.
296 Also referred to as an @code{identifier}.
299 @cindex operator, shell
300 A @code{control operator} or a @code{redirection operator}.
301 @xref{Redirections}, for a list of redirection operators.
304 @cindex process group
305 A collection of related processes each having the same process
308 @item process group ID
309 @cindex process group ID
310 A unique identifer that represents a @code{process group}
314 @cindex reserved word
315 A @code{word} that has a special meaning to the shell. Most reserved
316 words introduce shell flow control constructs, such as @code{for} and
320 @cindex return status
321 A synonym for @code{exit status}.
325 A mechanism by which a process may be notified by the kernal
326 of an event occurring in the system.
328 @item special builtin
329 @cindex special builtin
330 A shell builtin command that has been classified as special by the
331 @sc{POSIX.2} standard.
335 A sequence of characters considered a single unit by the shell. It is
336 either a @code{word} or an @code{operator}.
340 A @code{token} that is not an @code{operator}.
343 @node Basic Shell Features
344 @chapter Basic Shell Features
347 Bash is an acronym for @samp{Bourne-Again SHell}.
349 the traditional Unix shell originally written by Stephen Bourne.
350 All of the Bourne shell builtin commands are available in Bash,
351 and the rules for evaluation and quoting are taken from the @sc{POSIX}
352 1003.2 specification for the `standard' Unix shell.
354 This chapter briefly summarizes the shell's "building blocks":
355 commands, control structures, shell functions, shell @i{parameters},
357 @i{redirections}, which are a way to direct input and output from
358 and to named files, and how the shell executes commands.
361 * Shell Syntax:: What your input means to the shell.
362 * Simple Commands:: The most common type of command.
363 * Pipelines:: Connecting the input and output of several
365 * Lists:: How to execute commands sequentially.
366 * Looping Constructs:: Shell commands for iterative action.
367 * Conditional Constructs:: Shell commands for conditional execution.
368 * Command Grouping:: Ways to group commands.
369 * Shell Functions:: Grouping commands by name.
370 * Shell Parameters:: Special shell variables.
371 * Shell Expansions:: How Bash expands variables and the various
372 expansions available.
373 * Redirections:: A way to control where input and output go.
374 * Executing Commands:: What happens when you run a command.
375 * Shell Scripts:: Executing files of shell commands.
379 @section Shell Syntax
381 * Shell Operation:: The basic operation of the shell.
383 * Quoting:: How to remove the special meaning from characters.
385 * Comments:: How to specify comments.
388 @node Shell Operation
389 @subsection Shell Operation
391 The following is a brief description of the shell's operation when it
392 reads and executes a command. Basically, the shell does the
397 Reads its input from a file (@pxref{Shell Scripts}), from a string
398 supplied as an argument to the @samp{-c} invocation option
399 (@pxref{Invoking Bash}), or from the user's terminal.
402 Breaks the input into words and operators, obeying the quoting rules
403 described in @ref{Quoting}. Tokens are separated by
404 @code{metacharacters}. Alias expansion is performed by this step
408 Parses the tokens into simple and compound commands.
411 Performs the various shell expansions (@pxref{Shell Expansions}), breaking
412 the expanded tokens into lists of filenames (@pxref{Filename Expansion})
413 and commands and arguments.
416 Performs any necessary redirections (@pxref{Redirections}) and removes
417 the redirection operators and their operands from the argument list.
420 Executes the command (@pxref{Executing Commands}).
423 Optionally waits for the command to complete and collects its exit
432 * Escape Character:: How to remove the special meaning from a single
434 * Single Quotes:: How to inhibit all interpretation of a sequence
436 * Double Quotes:: How to suppress most of the interpretation of a
437 sequence of characters.
438 * ANSI-C Quoting:: How to expand ANSI-C sequences in quoted strings.
440 * Locale Translation:: How to translate strings into different languages.
443 Quoting is used to remove the special meaning of certain
444 characters or words to the shell. Quoting can be used to
445 disable special treatment for special characters, to prevent
446 reserved words from being recognized as such, and to prevent
449 Each of the shell @code{metacharacters} (@pxref{Definitions})
450 has special meaning to the shell and must be quoted if they are to
451 represent themselves. There are three quoting mechanisms: the
452 @var{escape character}, single quotes, and double quotes.
454 @node Escape Character
455 @subsubsection Escape Character
456 A non-quoted backslash @samp{\} is the Bash escape character.
457 It preserves the literal value of the next character that follows,
458 with the exception of @code{newline}. If a @code{\newline} pair
459 appears, and the backslash is not quoted, the @code{\newline}
460 is treated as a line continuation (that is, it is effectively ignored).
463 @subsubsection Single Quotes
465 Enclosing characters in single quotes preserves the literal value
466 of each character within the quotes. A single quote may not occur
467 between single quotes, even when preceded by a backslash.
470 @subsubsection Double Quotes
472 Enclosing characters in double quotes preserves the literal value
473 of all characters within the quotes, with the exception of
474 @samp{$}, @samp{`}, and @samp{\}.
475 The characters @samp{$} and @samp{`}
476 retain their special meaning within double quotes. The backslash
477 retains its special meaning only when followed by one of the following
479 @samp{$}, @samp{`}, @samp{"}, @samp{\}, or @code{newline}.
480 A double quote may be quoted within double quotes by preceding it with
483 The special parameters @samp{*} and @samp{@@} have special meaning
484 when in double quotes (@pxref{Shell Parameter Expansion}).
487 @subsubsection ANSI-C Quoting
488 @cindex quoting, ANSI
490 Words of the form @code{$'@var{string}'} are treated specially. The
491 word expands to @var{string}, with backslash-escaped characters replaced
492 as specifed by the ANSI C standard. Backslash escape sequences, if
493 present, are decoded as follows:
501 an escape character (not ANSI C)
515 the character whose @code{ASCII} code is @var{nnn} in octal
519 The result is single-quoted, as if the dollar sign had not been present.
521 @node Locale Translation
522 @subsubsection Locale-Specific Translation
525 A double-quoted string preceded by a dollar sign (@samp{$}) will cause
526 the string to be translated according to the current locale.
527 If the current locale is @code{C} or @code{POSIX}, the dollar sign
529 If the string is translated and replaced, the replacement is
534 @cindex comments, shell
536 In a non-interactive shell, or an interactive shell in which the
537 @code{interactive_comments} option to the @code{shopt}
538 builtin is enabled (@pxref{Bash Builtins}),
539 a word beginning with @samp{#}
540 causes that word and all remaining characters on that line to
541 be ignored. An interactive shell without the @code{interactive_comments}
542 option enabled does not allow comments. The @code{interactive_comments}
543 option is on by default in interactive shells.
545 @node Simple Commands
546 @section Simple Commands
547 @cindex commands, simple
549 A simple command is the kind of command you'll encounter most often.
550 It's just a sequence of words separated by @code{blank}s, terminated
551 by one of the shell control operators (@pxref{Definitions}). The
552 first word generally specifies a command to be executed.
554 The return status (@pxref{Exit Status}) of a simple command is
555 its exit status as provided
556 by the @sc{POSIX.1} @code{waitpid} function, or 128+@var{n} if the command
557 was terminated by signal @var{n}.
562 @cindex commands, pipelines
564 A @code{pipeline} is a sequence of simple commands separated by
569 @cindex command timing
570 The format for a pipeline is
572 [@code{time} [@code{-p}]] [@code{!}] @var{command1} [@code{|} @var{command2} @dots{}]
576 The output of each command in the pipeline is connected to the input of
577 the next command. That is, each command reads the previous command's
580 The reserved word @code{time} causes timing statistics
581 to be printed for the pipeline once it finishes.
582 The @samp{-p} option changes the output format to that specified
584 The @code{TIMEFORMAT} variable may be set to a format string that
585 specifies how the timing information should be displayed.
586 @xref{Bash Variables}, for a description of the available formats.
588 Each command in a pipeline is executed in its own subshell. The exit
589 status of a pipeline is the exit status of the last command in the
590 pipeline. If the reserved word @samp{!} precedes the pipeline, the
591 exit status is the logical @sc{NOT} of the exit status of the last command.
594 @section Lists of Commands
595 @cindex commands, lists
597 A @code{list} is a sequence of one or more pipelines separated by one
598 of the operators @samp{;}, @samp{&}, @samp{&&}, or @samp{||},
599 and optionally terminated by one of @samp{;}, @samp{&}, or a
602 Of these list operators, @samp{&&} and @samp{||}
603 have equal precedence, followed by @samp{;} and @samp{&},
604 which have equal precedence.
606 If a command is terminated by the control operator @samp{&},
607 the shell executes the command in the @var{background}
608 in a subshell. The shell does not wait for the command to
609 finish, and the return status is 0 (true). Commands separated by a
610 @samp{;} are executed sequentially; the shell waits for each
611 command to terminate in turn. The return status is the
612 exit status of the last command executed.
614 The control operators @samp{&&} and @samp{||}
615 denote @sc{AND} lists and @sc{OR} lists, respectively.
616 An @sc{AND} list has the form
618 @var{command} && @var{command2}
622 @var{command2} is executed if, and only if, @var{command}
623 returns an exit status of zero.
625 An @sc{OR} list has the form
627 @var{command} || @var{command2}
631 @var{command2} is executed if and only if @var{command}
632 returns a non-zero exit status.
635 @sc{AND} and @sc{OR} lists is the exit status of the last command
636 executed in the list.
638 @node Looping Constructs
639 @section Looping Constructs
640 @cindex commands, looping
642 Note that wherever you see a @samp{;} in the description of a
643 command's syntax, it may be replaced indiscriminately with
644 one or more newlines.
646 Bash supports the following looping constructs.
653 The syntax of the @code{until} command is:
655 until @var{test-commands}; do @var{consequent-commands}; done
657 Execute @var{consequent-commands} as long as the final command in
658 @var{test-commands} has an exit status which is not zero.
662 The syntax of the @code{while} command is:
664 while @var{test-commands}; do @var{consequent-commands}; done
667 Execute @var{consequent-commands} as long as the final command in
668 @var{test-commands} has an exit status of zero.
672 The syntax of the @code{for} command is:
675 for @var{name} [in @var{words} @dots{}]; do @var{commands}; done
677 Execute @var{commands} for each member in @var{words}, with @var{name}
678 bound to the current member. If @samp{in @var{words}} is not
679 present, @samp{in "$@@"} is assumed.
683 The @code{break} and @code{continue} builtins (@pxref{Bourne Shell Builtins})
684 may be used to control loop execution.
686 @node Conditional Constructs
687 @section Conditional Constructs
688 @cindex commands, conditional
697 The syntax of the @code{if} command is:
700 if @var{test-commands}; then
701 @var{consequent-commands};
702 [elif @var{more-test-commands}; then
703 @var{more-consequents};]
704 [else @var{alternate-consequents};]
708 Execute @var{consequent-commands} only if the final command in
709 @var{test-commands} has an exit status of zero.
710 Otherwise, each @code{elif} list is executed in turn,
711 and if its exit status is zero,
712 the corresponding @var{more-consequents} is executed and the
714 If @samp{else @var{alternate-consequents}} is present, and
715 the final command in the final @code{if} or @code{elif} clause
716 has a non-zero exit status, then execute @var{alternate-consequents}.
722 The syntax of the @code{case} command is:
725 @code{case @var{word} in [ ( @var{pattern} [| @var{pattern}]@dots{}) @var{commands} ;;]@dots{} esac}
728 Selectively execute @var{commands} based upon @var{word} matching
729 @var{pattern}. The @samp{|} is used to separate multiple patterns.
731 Here is an example using @code{case} in a script that could be used to
732 describe one interesting feature of an animal:
735 echo -n "Enter the name of an animal: "
737 echo -n "The $ANIMAL has "
739 horse | dog | cat) echo -n "four";;
740 man | kangaroo ) echo -n "two";;
741 *) echo -n "an unknown number of";;
748 (( @var{expression} ))
751 The @var{expression} is evaluated according to the rules described
752 below (@pxref{Arithmetic Evaluation}).
753 If the value of the expression is non-zero, the return status is 0;
754 otherwise the return status is 1. This is exactly equivalent to
756 let "@var{expression}"
761 The @code{select} construct, which allows users to choose from a list
762 of items presented as a menu, is also available.
763 @xref{Korn Shell Constructs}, for a full description of @code{select}.
765 @node Command Grouping
766 @section Grouping Commands
767 @cindex commands, grouping
769 Bash provides two ways to group a list of commands to be executed
770 as a unit. When commands are grouped, redirections may be applied
771 to the entire command list. For example, the output of all the
772 commands in the list may be redirected to a single stream.
780 Placing a list of commands between parentheses causes a subshell
781 to be created, and each of the commands to be executed in that
782 subshell. Since the @var{list} is executed in a subshell, variable
783 assignments do not remain in effect after the subshell completes.
792 Placing a list of commands between curly braces causes the list to
793 be executed in the current shell context. No subshell is created.
794 The semicolon following @var{list} is required.
797 In addition to the creation of a subshell, there is a subtle difference
798 between these two constructs due to historical reasons. The braces
799 are @code{reserved words}, so they must be separated from the @var{list}
800 by @code{blank}s. The parentheses are @code{operators}, and are
801 recognized as separate tokens by the shell even if they are not separated
802 from the @var{list} by whitespace.
804 The exit status of both of these constructs is the exit status of
807 @node Shell Functions
808 @section Shell Functions
809 @cindex shell function
810 @cindex functions, shell
812 Shell functions are a way to group commands for later execution
813 using a single name for the group. They are executed just like
814 a "regular" command. Shell functions are executed in the current
815 shell context; no new process is created to interpret them.
817 Functions are declared using this syntax:
820 [ @code{function} ] @var{name} () @{ @var{command-list}; @}
823 This defines a shell function named @var{name}. The reserved
824 word @code{function} is optional. The @var{body} of the
825 function is the @var{command-list} between @{ and @}. This list
826 is executed whenever @var{name} is specified as the
827 name of a command. The exit status of a function is
828 the exit status of the last command executed in the body.
830 When a function is executed, the arguments to the
831 function become the positional parameters
832 during its execution (@pxref{Positional Parameters}).
833 The special parameter @samp{#} that expands to the number of
834 positional parameters is updated to reflect the change.
835 Positional parameter @code{0} is unchanged.
837 If the builtin command @code{return}
838 is executed in a function, the function completes and
839 execution resumes with the next command after the function
840 call. When a function completes, the values of the
841 positional parameters and the special parameter @samp{#}
842 are restored to the values they had prior to function
843 execution. If a numeric argument is given to @code{return},
844 that is the function return status.
846 Variables local to the function may be declared with the
847 @code{local} builtin. These variables are visible only to
848 the function and the commands it invokes.
850 Functions may be recursive. No limit is placed on the number of
853 @node Shell Parameters
854 @section Shell Parameters
856 @cindex variable, shell
857 @cindex shell variable
860 * Positional Parameters:: The shell's command-line arguments.
861 * Special Parameters:: Parameters with special meanings.
864 A @var{parameter} is an entity that stores values.
865 It can be a @code{name}, a number, or one of the special characters
867 For the shell's purposes, a @var{variable} is a parameter denoted by a
870 A parameter is set if it has been assigned a value. The null string is
871 a valid value. Once a variable is set, it may be unset only by using
872 the @code{unset} builtin command.
874 A variable may be assigned to by a statement of the form
876 @var{name}=[@var{value}]
880 is not given, the variable is assigned the null string. All
881 @var{value}s undergo tilde expansion, parameter and variable expansion,
882 command substitution, arithmetic expansion, and quote
883 removal (detailed below). If the variable has its @samp{-i} attribute
884 set (see the description of the @code{declare} builtin in
885 @ref{Bash Builtins}), then @var{value}
886 is subject to arithmetic expansion even if the @code{$((@dots{}))}
887 syntax does not appear (@pxref{Arithmetic Expansion}).
888 Word splitting is not performed, with the exception
889 of @code{"$@@"} as explained below.
890 Filename expansion is not performed.
892 @node Positional Parameters
893 @subsection Positional Parameters
894 @cindex parameters, positional
896 A @var{positional parameter}
897 is a parameter denoted by one or more
898 digits, other than the single digit @code{0}. Positional parameters are
899 assigned from the shell's arguments when it is invoked,
900 and may be reassigned using the @code{set}
901 builtin command. Positional parameters may not be assigned to
902 with assignment statements. The positional parameters are
903 temporarily replaced when a shell function is executed
904 (@pxref{Shell Functions}).
906 When a positional parameter consisting of more than a single
907 digit is expanded, it must be enclosed in braces.
909 @node Special Parameters
910 @subsection Special Parameters
911 @cindex parameters, special
913 The shell treats several parameters specially. These parameters may
914 only be referenced; assignment to them is not allowed.
919 Expands to the positional parameters, starting from one. When the
920 expansion occurs within double quotes, it expands to a single word
921 with the value of each parameter separated by the first character
923 special variable. That is, @code{"$*"} is equivalent
924 to @code{"$1@var{c}$2@var{c}@dots{}"}, where @var{c}
925 is the first character of the value of the @code{IFS}
927 If @code{IFS} is unset, the parameters are separated by spaces.
928 If @code{IFS} is null, the parameters are joined without intervening
933 Expands to the positional parameters, starting from one. When the
934 expansion occurs within double quotes, each parameter expands as a
935 separate word. That is, @code{"$@@"} is equivalent to
936 @code{"$1" "$2" @dots{}}.
937 When there are no positional parameters, @code{"$@@"} and
939 expand to nothing (i.e., they are removed).
942 Expands to the number of positional parameters in decimal.
945 Expands to the exit status of the most recently executed foreground
949 Expands to the current option flags as specified upon invocation,
951 builtin command, or those set by the shell itself
952 (such as the @samp{-i} option).
955 Expands to the process @sc{ID} of the shell. In a @code{()} subshell, it
956 expands to the process @sc{ID} of the current shell, not the
960 Expands to the process @sc{ID} of the most recently executed background
961 (asynchronous) command.
964 Expands to the name of the shell or shell script. This is set at
965 shell initialization. If Bash is invoked with a file of commands,
966 @code{$0} is set to the name of that file. If Bash
967 is started with the @samp{-c} option, then @code{$0}
968 is set to the first argument after the string to be
969 executed, if one is present. Otherwise, it is set
970 to the filename used to invoke Bash, as given by argument zero.
973 At shell startup, set to the absolute filename of the shell or shell
974 script being executed as passed in the argument list.
975 Subsequently, expands to the last argument to the previous command,
977 Also set to the full filename of each command executed and placed in
978 the environment exported to that command.
979 When checking mail, this parameter holds the name of the mail file.
982 @node Shell Expansions
983 @section Shell Expansions
986 Expansion is performed on the command line after it has been split into
987 @code{token}s. There are seven kinds of expansion performed:
989 @item brace expansion
990 @item tilde expansion
991 @item parameter and variable expansion
992 @item command substitution
993 @item arithmetic expansion
995 @item filename expansion
999 * Shell Parameter Expansion:: How Bash expands variables to their values.
1000 * Command Substitution:: Using the output of a command as an argument.
1001 * Process Substitution:: A way to write and read to and from a
1003 * Word Splitting:: How the results of expansion are split into separate
1005 * Filename Expansion:: A shorthand for specifying filenames matching patterns.
1006 * Quote Removal:: How and when quote characters are removed from
1010 Brace expansion, tilde expansion, and arithmetic expansion are described
1011 in other sections. For brace expansion, see @ref{Brace Expansion}; for
1012 tilde expansion, see @ref{Tilde Expansion}; and for arithmetic expansion,
1013 see @ref{Arithmetic Expansion}.
1015 The order of expansions is: brace expansion, tilde expansion,
1016 parameter, variable, and arithmetic expansion and
1017 command substitution
1018 (done in a left-to-right fashion), word splitting, and filename
1021 On systems that can support it, there is an additional expansion
1022 available: @var{process substitution}. This is performed at the
1023 same time as parameter, variable, and arithemtic expansion and
1024 command substitution.
1026 Only brace expansion, word splitting, and filename expansion
1027 can change the number of words of the expansion; other expansions
1028 expand a single word to a single word.
1029 The only exceptions to this are the expansions of
1030 @code{"$@@"} (@pxref{Special Parameters}) and @code{"$@{@var{name}[@@]@}"}
1033 After all expansions, @code{quote removal} (@pxref{Quote Removal})
1036 @node Shell Parameter Expansion
1037 @subsection Shell Parameter Expansion
1038 @cindex parameter expansion
1039 @cindex expansion, parameter
1041 The @samp{$} character introduces parameter expansion,
1042 command substitution, or arithmetic expansion. The parameter name
1043 or symbol to be expanded may be enclosed in braces, which
1044 are optional but serve to protect the variable to be expanded from
1045 characters immediately following it which could be
1046 interpreted as part of the name.
1048 The basic form of parameter expansion is $@{@var{parameter}@}.
1049 The value of @var{parameter} is substituted. The braces are required
1050 when @var{parameter}
1051 is a positional parameter with more than one digit,
1052 or when @var{parameter}
1053 is followed by a character that is not to be
1054 interpreted as part of its name.
1056 If the first character of @var{parameter} is an exclamation point,
1057 a level of variable indirection is introduced.
1058 Bash uses the value of the variable formed from the rest of
1059 @var{parameter} as the name of the variable; this variable is then
1060 expanded and that value is used in the rest of the substitution, rather
1061 than the value of @var{parameter} itself.
1062 This is known as @code{indirect expansion}.
1064 In each of the cases below, @var{word} is subject to tilde expansion,
1065 parameter expansion, command substitution, and arithmetic expansion.
1066 When not performing substring expansion, Bash tests for a parameter
1067 that is unset or null; omitting the colon results in a test only for a
1068 parameter that is unset.
1072 @item $@{@var{parameter}:@minus{}@var{word}@}
1073 If @var{parameter} is unset or null, the expansion of
1074 @var{word} is substituted. Otherwise, the value of
1075 @var{parameter} is substituted.
1077 @item $@{@var{parameter}:=@var{word}@}
1079 is unset or null, the expansion of @var{word}
1080 is assigned to @var{parameter}.
1081 The value of @var{parameter}
1082 is then substituted. Positional parameters and special parameters may
1083 not be assigned to in this way.
1085 @item $@{@var{parameter}:?@var{word}@}
1087 is null or unset, the expansion of @var{word} (or a message
1088 to that effect if @var{word}
1089 is not present) is written to the standard error and the shell, if it
1090 is not interactive, exits. Otherwise, the value of @var{parameter} is
1093 @item $@{@var{parameter}:+@var{word}@}
1095 is null or unset, nothing is substituted, otherwise the expansion of
1096 @var{word} is substituted.
1098 @item $@{@var{parameter}:@var{offset}@}
1099 @itemx $@{@var{parameter}:@var{offset}:@var{length}@}
1100 Expands to up to @var{length} characters of @var{parameter},
1101 starting at @var{offset}.
1102 If @var{length} is omitted, expands to the substring of
1103 @var{parameter}, starting at the character specified by @var{offset}.
1104 @var{length} and @var{offset} are arithmetic expressions
1105 (@pxref{Arithmetic Evaluation}).
1106 This is referred to as Substring Expansion.
1108 @var{length} must evaluate to a number greater than or equal to zero.
1109 If @var{offset} evaluates to a number less than zero, the value
1110 is used as an offset from the end of the value of @var{parameter}.
1111 If @var{parameter} is @samp{@@}, the result is @var{length} positional
1112 parameters beginning at @var{offset}.
1113 If @var{parameter} is an array name indexed by @samp{@@} or @samp{*},
1114 the result is the @var{length}
1115 members of the array beginning with $@{@var{parameter}[@var{offset}]@}.
1116 Substring indexing is zero-based unless the positional parameters are
1117 used, in which case the indexing starts at 1.
1119 @item $@{#@var{parameter}@}
1120 The length in characters of the value of @var{parameter} is substituted.
1122 is @samp{*} or @samp{@@},
1123 the length substituted is the number of positional parameters.
1125 is an array name subscripted
1126 by @samp{*} or @samp{@@},
1127 the length substituted is the number of elements in the array.
1129 @item $@{@var{parameter}#@var{word}@}
1130 @itemx $@{@var{parameter}##@var{word}@}
1132 is expanded to produce a pattern just as in filename
1133 expansion (@pxref{Filename Expansion}). If the pattern matches
1134 the beginning of the value of @var{parameter},
1135 then the expansion is the value of @var{parameter}
1136 with the shortest matching pattern (the @samp{#} case) or the
1137 longest matching pattern (the @samp{##} case) deleted.
1138 If @var{parameter} is @samp{@@} or @samp{*},
1139 the pattern removal operation is applied to each positional
1140 parameter in turn, and the expansion is the resultant list.
1141 If @var{parameter} is an array variable subscripted with
1142 @samp{@@} or @samp{*},
1143 the pattern removal operation is applied to each member of the
1144 array in turn, and the expansion is the resultant list.
1146 @item $@{@var{parameter}%@var{word}@}
1147 @itemx $@{@var{parameter}%%@var{word}@}
1148 The @var{word} is expanded to produce a pattern just as in
1150 If the pattern matches a trailing portion of the value of
1151 @var{parameter}, then the expansion is the value of @var{parameter}
1152 with the shortest matching pattern (the @samp{%} case) or the
1153 longest matching pattern (the @samp{%%} case) deleted.
1154 If @var{parameter} is @samp{@@} or @samp{*},
1155 the pattern removal operation is applied to each positional
1156 parameter in turn, and the expansion is the resultant list.
1158 is an array variable subscripted with @samp{@@} or @samp{*},
1159 the pattern removal operation is applied to each member of the
1160 array in turn, and the expansion is the resultant list.
1162 @item $@{@var{parameter}/@var{pattern}/@var{string}@}
1163 @itemx $@{@var{parameter}//@var{pattern}/@var{string}@}
1165 The @var{pattern} is expanded to produce a pattern just as in
1167 @var{Parameter} is expanded and the longest match of @var{pattern}
1168 against its value is replaced with @var{string}.
1169 In the first form, only the first match is replaced.
1170 The second form causes all matches of @var{pattern} to be
1171 replaced with @var{string}.
1172 If @var{pattern} begins with @samp{#}, it must match at the beginning
1174 If @var{pattern} begins with @samp{%}, it must match at the end
1176 If @var{string} is null, matches of @var{pattern} are deleted
1177 and the @code{/} following @var{pattern} may be omitted.
1178 If @var{parameter} is @samp{@@} or @samp{*},
1179 the substitution operation is applied to each positional
1180 parameter in turn, and the expansion is the resultant list.
1182 is an array variable subscripted with @samp{@@} or @samp{*},
1183 the substitution operation is applied to each member of the
1184 array in turn, and the expansion is the resultant list.
1188 @node Command Substitution
1189 @subsection Command Substitution
1190 @cindex command substitution
1192 Command substitution allows the output of a command to replace
1193 the command name. There are two forms:
1204 Bash performs the expansion by executing @var{command} and
1205 replacing the command substitution with the standard output of the
1206 command, with any trailing newlines deleted.
1208 When the old-style backquote form of substitution is used,
1209 backslash retains its literal meaning except when followed by
1210 @samp{$}, @samp{`}, or @samp{\}.
1211 When using the @code{$(@var{command})} form, all characters between
1212 the parentheses make up the command; none are treated specially.
1214 Command substitutions may be nested. To nest when using the old form,
1215 escape the inner backquotes with backslashes.
1217 If the substitution appears within double quotes, word splitting and
1218 filename expansion are not performed on the results.
1220 @node Process Substitution
1221 @subsection Process Substitution
1222 @cindex process substitution
1224 Process substitution is supported on systems that support named
1225 pipes (@sc{FIFO}s) or the @file{/dev/fd} method of naming open files.
1226 It takes the form of
1236 The process @var{list} is run with its input or output connected to a
1237 @sc{FIFO} or some file in @file{/dev/fd}. The name of this file is
1238 passed as an argument to the current command as the result of the
1239 expansion. If the @code{>(@var{list})} form is used, writing to
1240 the file will provide input for @var{list}. If the
1241 @code{<(@var{list})} form is used, the file passed as an
1242 argument should be read to obtain the output of @var{list}.
1244 On systems that support it, process substitution is performed
1245 simultaneously with parameter and variable expansion,
1246 command substitution, and arithmetic expansion.
1248 @node Word Splitting
1249 @subsection Word Splitting
1250 @cindex word splitting
1252 The shell scans the results of parameter expansion, command substitution,
1253 and arithmetic expansion that did not occur within double quotes for
1256 The shell treats each character of @code{$IFS}
1257 as a delimiter, and splits the results of the other
1258 expansions into words on these characters. If
1259 @code{IFS} is unset, or its value is exactly @code{<space><tab><newline>},
1260 the default, then any sequence of @code{IFS}
1261 characters serves to delimit words. If @code{IFS}
1262 has a value other than the default, then sequences of
1263 the whitespace characters @code{space} and @code{tab}
1264 are ignored at the beginning and end of the
1265 word, as long as the whitespace character is in the
1266 value of @code{IFS} (an @code{IFS} whitespace character).
1267 Any character in @code{IFS} that is not @code{IFS}
1268 whitespace, along with any adjacent @code{IFS}
1269 whitespace characters, delimits a field. A sequence of @code{IFS}
1270 whitespace characters is also treated as a delimiter.
1271 If the value of @code{IFS} is null, no word splitting occurs.
1273 Explicit null arguments (@code{""} or @code{''}) are retained.
1274 Unquoted implicit null arguments, resulting from the expansion of
1276 that have no values, are removed.
1277 If a parameter with no value is expanded within double quotes, a
1278 null argument results and is retained.
1280 Note that if no expansion occurs, no splitting
1283 @node Filename Expansion
1284 @subsection Filename Expansion
1285 @cindex expansion, filename
1286 @cindex expansion, pathname
1287 @cindex filename expansion
1288 @cindex pathname expansion
1290 After word splitting,
1291 unless the @samp{-f}
1292 option has been set (@pxref{The Set Builtin}),
1293 Bash scans each word for the characters
1294 @samp{*}, @samp{?}, and @samp{[}.
1295 If one of these characters appears, then the word is
1296 regarded as a @var{pattern},
1297 and replaced with an alphabetically sorted list of
1298 file names matching the pattern. If no matching file names are found,
1299 and the shell option @code{nullglob} is disabled, the word is left
1300 unchanged. If the option is set, and no matches are found, the word
1301 is removed. When a pattern is used for filename generation,
1302 the character @samp{.}
1303 at the start of a filename or immediately following a slash
1304 must be matched explicitly, unless the shell option @code{dotglob}
1305 is set. The slash character must always be matched explicitly.
1306 In other cases, the @samp{.} character is not treated specially.
1307 See the description of @code{shopt} in @ref{Bash Builtins},
1308 for a description of the @code{nullglob} and @code{dotglob} options.
1310 The @code{GLOBIGNORE}
1311 shell variable may be used to restrict the set of filenames matching a
1312 @var{pattern}. If @code{GLOBIGNORE}
1313 is set, each matching filename that also matches one of the patterns in
1314 @code{GLOBIGNORE} is removed from the list of matches. The filenames
1315 @file{.} and @file{..}
1316 are always ignored, even when @code{GLOBIGNORE}.
1317 is set. However, setting @code{GLOBIGNORE} has the effect of
1318 enabling the @code{dotglob}
1319 shell option, so all other filenames beginning with a
1320 @samp{.} will match.
1321 To get the old behavior of ignoring filenames beginning with a
1322 @samp{.}, make @samp{.*} one of the patterns in @code{GLOBIGNORE}.
1323 The @code{dotglob} option is disabled when @code{GLOBIGNORE}
1326 The special pattern characters have the following meanings:
1329 Matches any string, including the null string.
1331 Matches any single character.
1333 Matches any one of the enclosed characters. A pair of characters
1334 separated by a minus sign denotes a @var{range};
1335 any character lexically between those two characters, inclusive,
1336 is matched. If the first character following the
1337 @samp{[} is a @samp{!} or a @samp{^}
1338 then any character not enclosed is matched. A @samp{@minus{}}
1339 may be matched by including it as the first or last character
1340 in the set. A @samp{]} may be matched by including it as the first
1341 character in the set.
1345 @subsection Quote Removal
1347 After the preceding expansions, all unquoted occurrences of the
1348 characters @samp{\}, @samp{'}, and @samp{"} that did not
1349 result from one of the above expansions are removed.
1352 @section Redirections
1355 Before a command is executed, its input and output
1356 may be @var{redirected}
1357 using a special notation interpreted by the shell.
1358 Redirection may also be used to open and close files for the
1359 current shell execution environment. The following redirection
1360 operators may precede or appear anywhere within a
1361 simple command or may follow a command.
1362 Redirections are processed in the order they appear, from
1365 In the following descriptions, if the file descriptor number is
1366 omitted, and the first character of the redirection operator is
1367 @samp{<}, the redirection refers to the standard input (file
1368 descriptor 0). If the first character of the redirection operator
1369 is @samp{>}, the redirection refers to the standard output (file
1372 The word that follows the redirection operator in the following
1373 descriptions is subjected to brace expansion, tilde expansion,
1374 parameter expansion, command substitution, arithmetic expansion,
1375 quote removal, and filename expansion. If it expands to more
1376 than one word, Bash reports an error.
1378 Note that the order of redirections is significant. For example,
1381 ls > @var{dirlist} 2>&1
1384 directs both standard output and standard error to the file
1385 @var{dirlist}, while the command
1387 ls 2>&1 > @var{dirlist}
1390 directs only the standard output to file @var{dirlist},
1391 because the standard error was duplicated as standard output
1392 before the standard output was redirected to @var{dirlist}.
1394 @subsection Redirecting Input
1395 Redirection of input causes the file whose name results from
1396 the expansion of @var{word}
1397 to be opened for reading on file descriptor @code{n},
1398 or the standard input (file descriptor 0) if @code{n}
1401 The general format for redirecting input is:
1406 @subsection Redirecting Output
1407 Redirection of output causes the file whose name results from
1408 the expansion of @var{word}
1409 to be opened for writing on file descriptor @code{n},
1410 or the standard output (file descriptor 1) if @code{n}
1411 is not specified. If the file does not exist it is created;
1412 if it does exist it is truncated to zero size.
1414 The general format for redirecting output is:
1419 If the redirection operator is @samp{>}, and the @samp{-C} option to the
1420 @code{set} builtin has been enabled, the redirection will fail if the
1421 filename whose name results from the expansion of @var{word} exists.
1422 If the redirection operator is @samp{>|},
1423 then the value of the @samp{-C} option to the @code{set}
1424 builtin command is not tested, and the redirection is attempted even
1425 if the file named by @var{word} exists.
1427 @subsection Appending Redirected Output
1428 Redirection of output in this fashion
1429 causes the file whose name results from
1430 the expansion of @var{word}
1431 to be opened for appending on file descriptor @code{n},
1432 or the standard output (file descriptor 1) if @code{n}
1433 is not specified. If the file does not exist it is created.
1435 The general format for appending output is:
1440 @subsection Redirecting Standard Output and Standard Error
1441 Bash allows both the
1442 standard output (file descriptor 1) and
1443 the standard error output (file descriptor 2)
1444 to be redirected to the file whose name is the
1445 expansion of @var{word} with this construct.
1447 There are two formats for redirecting standard output and
1458 Of the two forms, the first is preferred.
1459 This is semantically equivalent to
1464 @subsection Here Documents
1465 This type of redirection instructs the shell to read input from the
1466 current source until a line containing only @var{word}
1467 (with no trailing blanks) is seen. All of
1468 the lines read up to that point are then used as the standard
1469 input for a command.
1471 The format of here-documents is as follows:
1473 <<[@minus{}]@var{word}
1478 No parameter expansion, command substitution, filename
1479 expansion, or arithmetic expansion is performed on
1480 @var{word}. If any characters in @var{word} are quoted, the
1481 @var{delimiter} is the result of quote removal on @var{word},
1482 and the lines in the here-document are not expanded. Otherwise,
1483 all lines of the here-document are subjected to parameter expansion,
1484 command substitution, and arithmetic expansion. In the latter
1485 case, the pair @code{\newline} is ignored, and @samp{\}
1486 must be used to quote the characters
1487 @samp{\}, @samp{$}, and @samp{`}.
1489 If the redirection operator is @samp{<<-},
1490 then all leading tab characters are stripped from input lines and the
1491 line containing @var{delimiter}.
1492 This allows here-documents within shell scripts to be indented in a
1495 @subsection Duplicating File Descriptors
1496 The redirection operator
1501 is used to duplicate input file descriptors.
1503 expands to one or more digits, the file descriptor denoted by @code{n}
1504 is made to be a copy of that file descriptor. If @var{word}
1505 evaluates to @samp{-}, file descriptor @code{n} is closed. If
1506 @code{n} is not specified, the standard input (file descriptor 0) is used.
1513 is used similarly to duplicate output file descriptors. If
1515 is not specified, the standard output (file descriptor 1) is used.
1516 As a special case, if @code{n} is omitted, and @var{word} does not
1517 expand to one or more digits, the standard output and standard
1518 error are redirected as described previously.
1520 @subsection Opening File Descriptors for Reading and Writing
1521 The redirection operator
1526 causes the file whose name is the expansion of @var{word}
1527 to be opened for both reading and writing on file descriptor
1528 @code{n}, or on file descriptor 0 if @code{n}
1529 is not specified. If the file does not exist, it is created.
1531 @node Executing Commands
1532 @section Executing Commands
1535 * Command Search and Execution:: How Bash finds commands and runs them.
1537 * Environment:: The environment given to a command.
1539 * Exit Status:: The status returned by commands and how Bash
1542 * Signals:: What happens when Bash or a command it runs
1546 @node Command Search and Execution
1547 @subsection Command Search and Execution
1548 @cindex command execution
1549 @cindex command search
1551 After a command has been split into words, if it results in a
1552 simple command and an optional list of arguments, the following
1557 If the command name contains no slashes, the shell attempts to
1558 locate it. If there exists a shell function by that name, that
1559 function is invoked as described above in @ref{Shell Functions}.
1562 If the name does not match a function, the shell searches for
1563 it in the list of shell builtins. If a match is found, that
1567 If the name is neither a shell function nor a builtin,
1568 and contains no slashes, Bash searches each element of
1569 @code{$PATH} for a directory containing an executable file
1570 by that name. Bash uses a hash table to remember the full
1571 filenames of executable files (see the description of
1572 @code{hash} in @ref{Bourne Shell Builtins}) to avoid multiple
1573 @code{PATH} searches.
1574 A full search of the directories in @code{$PATH}
1575 is performed only if the command is not found in the hash table.
1576 If the search is unsuccessful, the shell prints an error
1577 message and returns a nonzero exit status.
1580 If the search is successful, or if the command name contains
1581 one or more slashes, the shell executes the named program.
1582 Argument 0 is set to the name given, and the remaining arguments
1583 to the command are set to the arguments supplied, if any.
1586 If this execution fails because the file is not in executable
1587 format, and the file is not a directory, it is assumed to be
1588 @var{shell script} (@pxref{Shell Scripts}).
1592 @subsection Environment
1595 When a program is invoked it is given an array of strings
1596 called the @var{environment}.
1597 This is a list of name-value pairs, of the form @code{name=value}.
1599 Bash allows you to manipulate the environment in several
1600 ways. On invocation, the shell scans its own environment and
1601 creates a parameter for each name found, automatically marking
1603 to child processes. Executed commands inherit the environment.
1604 The @code{export} and @samp{declare -x}
1605 commands allow parameters and functions to be added to and
1606 deleted from the environment. If the value of a parameter
1607 in the environment is modified, the new value becomes part
1608 of the environment, replacing the old. The environment
1609 inherited by any executed command consists of the shell's
1610 initial environment, whose values may be modified in the shell,
1611 less any pairs removed by the @code{unset} command, plus any
1612 additions via the @code{export} and @samp{declare -x} commands.
1614 The environment for any simple command
1615 or function may be augmented temporarily by prefixing it with
1616 parameter assignments, as described in @ref{Shell Parameters}.
1617 These assignment statements affect only the environment seen
1620 If the @samp{-k} flag is set (@pxref{The Set Builtin}, then all
1621 parameter assignments are placed in the environment for a command,
1622 not just those that precede the command name.
1624 When Bash invokes an external command, the variable @samp{$_}
1625 is set to the full path name of the command and passed to that
1626 command in its environment.
1629 @subsection Exit Status
1632 For the purposes of the shell, a command which exits with a
1633 zero exit status has succeeded.
1634 A non-zero exit status indicates failure.
1635 This seemingly counter-intuitive scheme is used so there
1636 is one well-defined way to indicate success and a variety of
1637 ways to indicate various failure modes.
1638 When a command terminates on a fatal signal whose number is @var{n},
1639 Bash uses the value 128+@var{n} as the exit status.
1641 If a command is not found, the child process created to
1642 execute it returns a status of 127. If a command is found
1643 but is not executable, the return status is 126.
1645 The exit status is used by the Bash conditional commands
1646 (@pxref{Conditional Constructs}) and some of the list
1647 constructs (@pxref{Lists}).
1649 All of the Bash builtins return an exit status of zero if they succeed
1650 and a non-zero status on failure, so they may be used by the
1651 conditional and list constructs.
1655 @cindex signal handling
1657 When Bash is interactive, it ignores
1658 @code{SIGTERM} (so that @samp{kill 0} does not kill an interactive shell),
1660 is caught and handled (so that the @code{wait} builtin is interruptible).
1661 When Bash receives a @code{SIGINT}, it breaks out of any executing loops.
1662 In all cases, Bash ignores @code{SIGQUIT}.
1663 If job control is in effect (@pxref{Job Control}), Bash
1664 ignores @code{SIGTTIN}, @code{SIGTTOU}, and @code{SIGTSTP}.
1666 Synchronous jobs started by Bash have signals set to the
1667 values inherited by the shell from its parent. When job control
1668 is not in effect, background jobs (commands terminated with @samp{&})
1669 ignore @code{SIGINT} and @code{SIGQUIT}.
1670 Commands run as a result of command substitution ignore the
1671 keyboard-generated job control signals
1672 @code{SIGTTIN}, @code{SIGTTOU}, and @code{SIGTSTP}.
1674 The shell exits by default upon receipt of a @code{SIGHUP}.
1675 Before exiting, it resends the @code{SIGHUP}
1676 to all jobs, running or stopped. To prevent the shell from
1677 sending the @code{SIGHUP} signal to a particular job, remove it
1678 from the jobs table with the @code{disown} builtin
1679 (@pxref{Job Control Builtins})
1680 or use @code{disown -h} to mark it to not receive @code{SIGHUP}.
1683 @section Shell Scripts
1684 @cindex shell script
1686 A shell script is a text file containing shell commands. When such
1687 a file is used as the first non-option argument when invoking Bash,
1688 and neither the @samp{-c} nor @samp{-s} option is supplied
1689 (@pxref{Invoking Bash}),
1690 Bash reads and executes commands from the file, then exits. This
1691 mode of operation creates a non-interactive shell. When Bash runs
1692 a shell script, it sets the special parameter @code{0} to the name
1693 of the file, rather than the name of the shell, and the positional
1694 parameters are set to the remaining arguments, if any are given.
1695 If no additional arguments are supplied, the positional parameters
1698 A shell script may be made executable by using the @code{chmod} command
1699 to turn on the execute bit. When Bash finds such a file while
1700 searching the @code{$PATH} for a command, it spawns a subshell to
1701 execute it. In other words, executing
1703 filename @var{arguments}
1706 is equivalent to executing
1708 bash filename @var{arguments}
1712 if @code{filename} is an executable shell script.
1713 This subshell reinitializes itself, so that the effect is as if a
1714 new shell had been invoked to interpret the script.
1716 Most versions of Unix make this a part of the kernel's command
1717 execution mechanism. If the first line of a script begins with
1718 the two characters @samp{#!}, the remainder of the line specifies
1719 an interpreter for the program. The arguments to the interpreter
1720 consist of a single optional argument following the interpreter
1721 name on the first line of the script file, followed by the name of
1722 the script file, followed by the rest of the arguments. Bash
1723 will perform this action on operating systems that do not handle it
1724 themselves. Note that some older versions of Unix limit the interpreter
1725 name and argument to a maximum of 32 characters.
1727 @node Bourne Shell Features
1728 @chapter Bourne Shell Style Features
1731 * Bourne Shell Builtins:: Builtin commands inherited from the Bourne
1733 * Bourne Shell Variables:: Variables which Bash uses in the same way
1734 as the Bourne Shell.
1735 * Other Bourne Shell Features:: Addtional aspects of Bash which behave in
1736 the same way as the Bourne Shell.
1739 This section briefly summarizes things which Bash inherits from
1740 the Bourne Shell: builtins, variables,
1741 and other features. It also lists the significant differences
1742 between Bash and the Bourne Shell.
1744 @node Bourne Shell Builtins
1745 @section Bourne Shell Builtins
1747 The following shell builtin commands are inherited from the Bourne
1748 Shell. These commands are implemented as specified by the @sc{POSIX}
1757 Do nothing beyond expanding @var{arguments} and performing redirections.
1764 Read and execute commands from the @var{filename} argument in the
1765 current shell context.
1772 Exit from a @code{for}, @code{while}, @code{until}, or @code{select} loop.
1773 If @var{n} is supplied, the @var{n}th enclosing loop is exited.
1778 cd [-LP] [@var{directory}]
1780 Change the current working directory to @var{directory}. If @var{directory}
1781 is not given, the value of the @code{HOME} shell variable is used. If the
1782 shell variable @code{CDPATH} exists, it is used as a search path. If
1783 @var{directory} begins with a slash, @code{CDPATH} is not used.
1784 The @samp{-P} option means
1785 to not follow symbolic links; symlinks are followed by default or with the
1793 Resume the next iteration of an enclosing @code{for}, @code{while},
1794 @code{until}, or @code{select} loop.
1795 If @var{n} is supplied, the execution of the
1796 @var{n}th enclosing loop is resumed.
1801 eval [@var{arguments}]
1803 The arguments are concatenated together into a single
1804 command, which is then read and executed.
1809 exec [-cl] [-a @var{name}] [@var{command}] [@var{arguments}]
1812 is supplied, it replaces the shell.
1813 If the @samp{-l} option is supplied,
1814 the shell places a dash in the zeroth arg passed to @var{command}.
1815 This is what the @code{login} program does.
1816 The @samp{-c} option causes @var{command}
1817 to be executed with an empty environment.
1818 If @samp{-a} is supplied, the shell passes @var{name}
1819 as the zeroth argument to @var{command}.
1820 If no @var{command} is specified, redirections may be used to affect
1821 the current shell environment.
1828 Exit the shell, returning a status of @var{n} to the shell's parent.
1833 export [-fn] [-p] [@var{name}[=@var{value}]]
1835 Mark each @var{name} to be passed to child processes
1836 in the environment. If the @samp{-f} option is supplied, the @var{name}s
1837 refer to shell functions. The @samp{-n} option means to no longer mark
1838 each @var{name} for export.
1839 If no @var{names} are supplied, or if the @samp{-p} option is given, a
1840 list of exported names is displayed.
1845 getopts @var{optstring} @var{name} [@var{args}]
1847 @code{getopts} is used by shell scripts to parse positional parameters.
1848 @var{optstring} contains the option letters to be recognized; if a letter
1849 is followed by a colon, the option is expected to have an
1850 argument, which should be separated from it by white space.
1851 Each time it is invoked, @code{getopts}
1852 places the next option in the shell variable @var{name}, initializing
1853 @var{name} if it does not exist,
1854 and the index of the next argument to be processed into the
1855 variable @code{OPTIND}. @code{OPTIND}
1856 is initialized to 1 each time the shell or a shell script
1857 is invoked. When an option requires an argument,
1858 @code{getopts} places that argument into the variable @code{OPTARG}.
1859 The shell does not reset @code{OPTIND}
1860 automatically; it must be manually reset between multiple
1861 calls to @code{getopts}
1862 within the same shell invocation if a new set of parameters
1865 @code{getopts} can report errors in two ways. If the first character of
1866 @var{optstring} is a colon, @var{silent}
1867 error reporting is used. In normal operation diagnostic messages
1868 are printed when illegal options or missing option arguments are
1870 If the variable @code{OPTERR}
1871 is set to 0, no error message will be displayed, even if the first
1872 character of @code{optstring} is not a colon.
1874 If an illegal option is seen,
1875 @code{getopts} places @samp{?} into @var{name} and, if not silent,
1876 prints an error message and unsets @code{OPTARG}.
1877 If @code{getopts} is silent, the option character found is placed in
1878 @code{OPTARG} and no diagnostic message is printed.
1880 If a required argument is not found, and @code{getopts}
1881 is not silent, a question mark (@samp{?}) is placed in @var{name},
1882 @code{OPTARG} is unset, and a diagnostic message is printed.
1883 If @code{getopts} is silent, then a colon (@samp{:}) is placed in
1884 @var{name} and @code{OPTARG} is set to the option character found.
1887 normally parses the positional parameters, but if more arguments are
1888 given in @var{args}, @code{getopts} parses those instead.
1893 hash [-r] [-p @var{filename}] [@var{name}]
1895 Remember the full filenames of commands specified as arguments,
1896 so they need not be searched for on subsequent invocations. The
1897 commands are found by searching through the directories listed in
1898 @code{$PATH}. The @samp{-p} option inhibits the path search, and
1899 @var{filename} is used as the location of @var{name}.
1900 The @samp{-r} option causes the shell to forget
1901 all remembered locations. If no arguments are given, information
1902 about remembered commands is printed.
1909 Print the current working directory. If the @samp{-P} option is supplied,
1910 the path printed will not contain symbolic links. If the @samp{-L} option
1911 is supplied, the path printed may contain symbolic links.
1916 readonly [-apf] [@var{name}] @dots{}
1918 Mark each @var{name} as unchangable. The values of these names may not
1919 be changed by subsequent assignment. If the @samp{-f} option is supplied,
1920 each @var{name} refers to a shell function. The @samp{-a} option means
1921 each @var{name} refers to an array variable.
1922 If no @var{name} arguments are given, or if the @samp{-p}
1923 option is supplied, a list of all readonly names is printed.
1930 Cause a shell function to exit with value @var{n}. This may also be used
1931 to terminate execution of a script being executed with the @code{.}
1939 Shift positional parameters to the left by @var{n}.
1940 The positional parameters from @var{n}+1 @dots{}
1943 Parameters represented by the numbers
1944 @code{$#} to @var{n}+1 are unset. @var{n}
1945 must be a non-negative number less than or equal to @code{$#}.
1951 Evaluate a conditional expression (@pxref{Bash Conditional Expressions}).
1958 Print out the user and system times used by the shell and its children.
1963 trap [-lp] [@var{arg}] [@var{sigspec} @dots{}]
1965 The commands in @var{arg} are to be read and executed when the
1966 shell receives signal @var{sigspec}. If @var{arg} is absent or
1967 equal to @samp{-}, all specified signals are reset to the values
1968 they had when the shell was started.
1969 If @var{arg} is the null string, then the signal specified by
1970 each @var{sigspec} is ignored by the shell and commands it invokes.
1971 If @var{arg} is @samp{-p}, the shell displays the trap commands
1972 associated with each @var{sigspec}. If no arguments are supplied, or
1973 only @samp{-p} is given, @code{trap} prints the list of commands
1974 associated with each signal number.
1975 Each @var{sigspec} is either a signal name such as @code{SIGINT} (with
1976 or without the @code{SIG} prefix) or a signal number.
1978 is @code{0} or @code{EXIT}, @var{arg} is executed when the shell exits.
1979 If a @var{sigspec} is @code{DEBUG}, the command @var{arg} is executed
1980 after every simple command.
1981 The @samp{-l} option causes the shell to print a list of signal names
1982 and their corresponding numbers.
1984 Signals ignored upon entry to the shell cannot be trapped or reset.
1985 Trapped signals are reset to their original values in a child
1986 process when it is created.
1991 umask [-S] [@var{mode}]
1993 Set the shell process's file creation mask to @var{mode}. If
1994 @var{mode} begins with a digit, it is interpreted as an octal number;
1995 if not, it is interpreted as a symbolic mode mask similar
1996 to that accepted by the @code{chmod} command. If @var{mode} is
1997 omitted, the current value of the mask is printed. If the @samp{-S}
1998 option is supplied without a @var{mode} argument, the mask is printed
1999 in a symbolic format.
2004 unset [-fv] [@var{name}]
2006 Each variable or function @var{name} is removed.
2007 If no options are supplied, or the @samp{-v} option is given, each
2008 @var{name} refers to a shell variable.
2009 If the @samp{-f} option is given, the @var{name}s refer to shell
2010 functions, and the function definition is removed.
2011 Read-only variables and functions may not be unset.
2015 @node Bourne Shell Variables
2016 @section Bourne Shell Variables
2018 Bash uses certain shell variables in the same way as the Bourne shell.
2019 In some cases, Bash assigns a default value to the variable.
2024 A list of characters that separate fields; used when the shell splits
2025 words as part of expansion.
2028 A colon-separated list of directories in which the shell looks for
2032 The current user's home directory; the default for the @code{cd} builtin
2036 A colon-separated list of directories used as a search path for
2037 the @code{cd} command.
2040 A colon-separated list of files which the shell periodically checks
2041 for new mail. You can
2042 also specify what message is printed by separating the file name from
2043 the message with a @samp{?}. When used in the text of the message,
2044 @code{$_} stands for the name of the current mailfile.
2047 If this parameter is set to a filename and the @code{MAILPATH} variable
2048 is not set, Bash informs the user of the arrival of mail in
2052 The primary prompt string. The default value is @samp{\s-\v\$ }.
2055 The secondary prompt string. The default value is @samp{> }.
2058 The index of the last option processed by the
2059 @code{getopts} builtin.
2062 The value of the last option argument processed by the
2063 @code{getopts} builtin.
2067 @node Other Bourne Shell Features
2068 @section Other Bourne Shell Features
2071 * Major Differences From The Bourne Shell:: Major differences between
2072 Bash and the Bourne shell.
2075 Bash implements essentially the same grammar, parameter and variable
2076 expansion, redirection, and quoting as the Bourne Shell. Bash uses the
2077 @sc{POSIX} 1003.2 standard as the specification of how these features are to be
2078 implemented. There are some differences between the traditional Bourne
2079 shell and the @sc{POSIX} standard; this section quickly details the differences
2080 of significance. A number of these differences are explained in greater
2081 depth in subsequent sections.
2083 @node Major Differences From The Bourne Shell
2084 @subsection Major Differences From The SVR4.2 Bourne Shell
2086 Bash is @sc{POSIX}-conformant, even where the @sc{POSIX} specification
2087 differs from traditional @code{sh} behavior.
2089 Bash has multi-character invocation options (@pxref{Invoking Bash}).
2091 Bash has command-line editing (@pxref{Command Line Editing}) and
2092 the @code{bind} builtin.
2094 Bash has command history (@pxref{Bash History Facilities}) and the
2095 @code{history} and @code{fc} builtins to manipulate it.
2097 Bash implements @code{csh}-like history expansion (@pxref{History Interaction}).
2099 Bash has one-dimensional array variables (@pxref{Arrays}), and the
2100 appropriate variable expansions and assignment syntax to use them.
2101 Some of the Bash builtins take options to act on arrays. Bash provides
2102 some built-in array variables.
2104 Bash implements the @code{!} keyword to negate the return value of
2105 a pipeline (@pxref{Pipelines}).
2106 Very useful when an @code{if} statement needs to act only if a test fails.
2108 Bash includes the @code{select} compound command, which allows the
2109 generation of simple menus (@pxref{Korn Shell Constructs}).
2111 Bash includes brace expansion (@pxref{Brace Expansion}) and tilde
2112 expansion (@pxref{Tilde Expansion}).
2114 Bash implements command aliases and the @code{alias} and @code{unalias}
2115 builtins (@pxref{Aliases}).
2117 Bash provides shell arithmetic and arithmetic expansion
2118 (@pxref{Shell Arithmetic}).
2120 The @sc{POSIX} and @code{ksh}-style @code{$()} form of command substitution
2121 is implemented (@pxref{Command Substitution}),
2122 and preferred to the Bourne shell's @code{``} (which
2123 is also implemented for backwards compatibility).
2125 Variables present in the shell's initial environment are automatically
2126 exported to child processes. The Bourne shell does not normally do
2127 this unless the variables are explicitly marked using the @code{export}
2130 Bash includes the @sc{POSIX} and @code{ksh}-style pattern removal
2131 @samp{%}, @samp{#}, @samp{%%} and @samp{##} constructs to remove
2132 leading or trailing substrings from variable values
2133 (@pxref{Shell Parameter Expansion}).
2135 The expansion @code{$@{#xx@}}, which returns the length of @code{$xx},
2136 is supported (@pxref{Shell Parameter Expansion}).
2138 The @code{$'@dots{}'} quoting syntax, which expands ANSI-C
2139 backslash-escaped characters in the text between the single quotes,
2140 is supported (@pxref{ANSI-C Quoting}).
2142 Bash supports the @code{$"@dots{}"} quoting syntax to do
2143 locale-specific translation of the characters between the double
2144 quotes. The @samp{-D} and @samp{--dump-strings} invocation options
2145 list the translatable strings found in a script
2146 (@pxref{Locale Translation}).
2148 The expansion @code{$@{var:}@var{offset}@code{[:}@var{length}@code{]@}},
2149 which expands to the substring of @code{var}'s value of length
2150 @var{length}, optionally beginning at @var{offset}, is present
2151 (@pxref{Shell Parameter Expansion}).
2154 @code{$@{var/[/]}@var{pattern}@code{[/}@var{replacement}@code{]@}},
2155 which matches @var{pattern} and replaces it with @var{replacement} in
2156 the value of @code{var}, is available (@pxref{Shell Parameter Expansion}).
2158 Bash has @var{indirect} variable expansion using @code{$@{!word@}}
2159 (@pxref{Shell Parameter Expansion}).
2161 Bash can expand positional parameters beyond @code{$9} using
2162 @code{$@{@var{num}@}}.
2164 Bash has process substitution (@pxref{Process Substitution}).
2166 Bash automatically assigns variables that provide information about the
2167 current user (@code{UID}, @code{EUID}, and @code{GROUPS}), the current host
2168 (@code{HOSTTYPE}, @code{OSTYPE}, @code{MACHTYPE}, and @code{HOSTNAME}),
2169 and the instance of Bash that is running (@code{BASH},
2170 @code{BASH_VERSION}, and @code{BASH_VERSINFO}. @xref{Bash Variables},
2173 The @code{IFS} variable is used to split only the results of expansion,
2174 not all words (@pxref{Word Splitting}).
2175 This closes a longstanding shell security hole.
2177 It is possible to have a variable and a function with the same name;
2178 @code{sh} does not separate the two name spaces.
2180 Bash functions are permitted to have local variables using the
2181 @code{local} builtin, and thus useful recursive functions may be written.
2183 Variable assignments preceding commands affect only that command, even
2184 builtins and functions (@pxref{Environment}).
2185 In @code{sh}, all variable assignments
2186 preceding commands are global unless the command is executed from the
2189 Bash performs filename expansion on filenames specified as operands
2190 to output redirection operators.
2192 Bash contains the @samp{<>} redirection operator, allowing a file to be
2193 opened for both reading and writing, and the @samp{&>} redirection
2194 operator, for directing standard output and standard error to the same
2195 file (@pxref{Redirections}).
2197 The @code{noclobber} option is available to avoid overwriting existing
2198 files with output redirection (@pxref{The Set Builtin}).
2199 The @samp{>|} redirection operator may be used to override @code{noclobber}.
2201 Bash interprets special backslash-escaped characters in the prompt
2202 strings when interactive (@pxref{Printing a Prompt}).
2204 Bash allows you to write a function to override a builtin, and provides
2205 access to that builtin's functionality within the function via the
2206 @code{builtin} and @code{command} builtins (@pxref{Bash Builtins}).
2208 The @code{command} builtin allows selective disabling of functions
2209 when command lookup is performed (@pxref{Bash Builtins}).
2211 Individual builtins may be enabled or disabled using the @code{enable}
2212 builtin (@pxref{Bash Builtins}).
2214 The Bash @code{hash} builtin allows a name to be associated with
2215 an arbitrary filename, even when that filename cannot be found by
2216 searching the @code{$PATH}, using @samp{hash -p}.
2218 Shell functions may be exported to children via the environment
2219 (@pxref{Shell Functions}).
2221 Bash includes a @code{help} builtin for quick reference to shell
2222 facilities (@pxref{Bash Builtins}).
2224 The Bash @code{read} builtin (@pxref{Bash Builtins})
2225 will read a line ending in @samp{\} with
2226 the @samp{-r} option, and will use the @code{REPLY} variable as a
2227 default if no arguments are supplied. The Bash @code{read} builtin
2228 also accepts a prompt string with the @samp{-p} option and will use
2229 Readline to obtain the line when given the @samp{-e} option.
2231 Bash includes the @code{shopt} builtin, for finer control of shell
2232 optional capabilities (@pxref{Bash Builtins}).
2234 Bash has much more optional behavior controllable with the @code{set}
2235 builtin (@pxref{The Set Builtin}).
2237 The @code{disown} builtin can remove a job from the internal shell
2238 job table (@pxref{Job Control Builtins}).
2240 The @code{return} builtin may be used to abort execution of scripts
2241 executed with the @code{.} or @code{source} builtins
2242 (@pxref{Bourne Shell Builtins}).
2244 The @code{test} builtin (@pxref{Bourne Shell Builtins})
2245 is slightly different, as it implements the
2246 @sc{POSIX} 1003.2 algorithm, which specifies the behavior based on the
2247 number of arguments.
2249 The @code{trap} builtin (@pxref{Bourne Shell Builtins})
2250 allows a @code{DEBUG} pseudo-signal specification,
2251 similar to @code{EXIT}. Commands specified with a @code{DEBUG} trap are
2252 executed after every simple command. The @code{DEBUG} trap is not
2253 inherited by shell functions.
2255 The Bash @code{export}, @code{readonly}, and @code{declare} builtins can
2256 take a @samp{-f} option to act on shell functions, a @samp{-p} option to
2257 display variables with various attributes set in a format that can be
2258 used as shell input, a @samp{-n} option to remove various variable
2259 attributes, and @samp{name=value} arguments to set variable attributes
2260 and values simultaneously.
2262 The Bash @code{cd} and @code{pwd} builtins (@pxref{Bourne Shell Builtins})
2263 each take @samp{-L} and @samp{-P} builtins to switch between logical and
2266 The Bash @code{type} builtin is more extensive and gives more information
2267 about the names it finds (@pxref{Bash Builtins}).
2269 Bash implements a @code{csh}-like directory stack, and provides the
2270 @code{pushd}, @code{popd}, and @code{dirs} builtins to manipulate it
2271 (@pxref{C Shell Builtins}).
2272 Bash also makes the directory stack visible as the value of the
2273 @code{DIRSTACK} shell variable.
2275 The Bash restricted mode is more useful (@pxref{The Restricted Shell});
2276 the @sc{SVR4.2} shell restricted mode is too limited.
2278 Bash has the @code{time} reserved word and command timing (@pxref{Pipelines}).
2279 The display of the timing statistics may be controlled with the
2280 @code{TIMEFORMAT} variable.
2282 The @sc{SVR4.2} shell has two privilege-related builtins
2283 (@code{mldmode} and @code{priv}) not present in Bash.
2285 Bash does not have the @code{stop} or @code{newgrp} builtins.
2287 Bash does not use the @code{SHACCT} variable or perform shell accounting.
2289 The @sc{SVR4.2} @code{sh} uses a @code{TIMEOUT} variable like Bash uses
2292 More features unique to Bash may be found in
2293 @ref{Bash Features}.
2295 @subsection Implementation Differences From The SVR4.2 Shell
2297 Since Bash is a completely new implementation, it does not suffer from
2298 many of the limitations of the @sc{SVR4.2} shell. For instance:
2303 Bash does not fork a subshell when redirecting into or out of
2304 a shell control structure such as an @code{if} or @code{while}
2308 Bash does not allow unbalanced quotes. The @sc{SVR4.2} shell will silently
2309 insert a needed closing quote at @code{EOF} under certain circumstances.
2310 This can be the cause of some hard-to-find errors.
2313 The @sc{SVR4.2} shell uses a baroque memory management scheme based on
2314 trapping @code{SIGSEGV}. If the shell is started from a process with
2315 @code{SIGSEGV} blocked (e.g., by using the @code{system()} C library
2316 function call), the shell misbehaves badly.
2319 In a questionable attempt at security, the @sc{SVR4.2} shell,
2320 when invoked without the @samp{-p} option, will alter its real
2321 and effective @sc{UID} and @sc{GID} if they are less than some
2322 magic threshold value, commonly 100.
2323 This can lead to unexpected results.
2326 The @sc{SVR4.2} shell does not allow users to trap @code{SIGALRM} or
2330 For some reason, the @sc{SVR4.2} shell does not allow the @code{MAILCHECK}
2331 variable to be unset.
2334 The @sc{SVR4.2} shell treats @samp{^} as the undocumented equivalent of
2338 Bash allows multiple option arguments when it is invoked (@code{-x -v});
2339 the @sc{SVR4.2} shell allows only one option argument (@code{-xv}). In
2340 fact, some versions of the shell dump core if the second argument begins
2344 The @sc{SVR4.2} shell exits a script if any builtin fails; Bash exits
2345 a script only if one of the @sc{POSIX.2} special builtins fails, and
2346 only for certain failures, as enumerated in the @sc{POSIX.2} standard.
2349 The @sc{SVR4.2} shell behaves differently when invoked as @code{jsh}
2350 (it turns on job control).
2354 @chapter C-Shell Style Features
2356 The C-Shell (@dfn{@code{csh}}) was created by Bill Joy at The
2357 University of California at Berkeley. It
2358 is generally considered to have better features for interactive use than
2359 the original Bourne shell. Some of the @code{csh} features present in
2360 Bash include job control, history expansion, `protected' redirection, and
2361 several variables to control the interactive behaviour of the shell
2362 (e.g., @code{IGNOREEOF}).
2364 @xref{Using History Interactively}, for details on history expansion.
2367 * Brace Expansion:: Expansion of expressions within braces.
2368 * Tilde Expansion:: Expansion of the ~ character.
2369 * C Shell Builtins:: Builtin commands adopted from the C Shell.
2370 * C Shell Variables:: Variables which Bash uses in essentially
2371 the same way as the C Shell.
2374 @node Brace Expansion
2375 @section Brace Expansion
2376 @cindex brace expansion
2377 @cindex expansion, brace
2380 is a mechanism by which arbitrary strings
2381 may be generated. This mechanism is similar to
2382 @var{filename expansion} (@pxref{Filename Expansion}),
2383 but the file names generated
2384 need not exist. Patterns to be brace expanded take
2385 the form of an optional @var{preamble},
2386 followed by a series of comma-separated strings
2387 between a pair of braces, followed by an optional @var{postamble}.
2388 The preamble is prepended to each string contained
2389 within the braces, and the postamble is then appended
2390 to each resulting string, expanding left to right.
2392 Brace expansions may be nested. The results of each expanded
2393 string are not sorted; left to right order is preserved.
2396 bash$ echo a@{d,c,b@}e
2400 Brace expansion is performed before any other expansions,
2401 and any characters special to other expansions are preserved
2402 in the result. It is strictly textual. Bash
2403 does not apply any syntactic interpretation to the context of the
2404 expansion or the text between the braces.
2406 A correctly-formed brace expansion must contain unquoted opening
2407 and closing braces, and at least one unquoted comma.
2408 Any incorrectly formed brace expansion is left unchanged.
2410 This construct is typically used as shorthand when the common
2411 prefix of the strings to be generated is longer than in the
2414 mkdir /usr/local/src/bash/@{old,new,dist,bugs@}
2418 chown root /usr/@{ucb/@{ex,edit@},lib/@{ex?.?*,how_ex@}@}
2421 @node Tilde Expansion
2422 @section Tilde Expansion
2423 @cindex tilde expansion
2424 @cindex expansion, tilde
2426 Bash has tilde (~) expansion, similar, but not identical, to that of
2427 @code{csh}. The following table shows what unquoted words beginning
2428 with a tilde expand to.
2432 The current value of @code{$HOME}.
2437 The subdirectory @code{foo} of the home directory of the user
2447 Bash will also tilde expand words following redirection operators
2448 and words following @samp{=} in assignment statements.
2450 @node C Shell Builtins
2451 @section C Shell Builtins
2453 Bash has several builtin commands whose definition is very similar
2460 pushd [@var{dir} | @var{+N} | @var{-N}] [-n]
2463 Save the current directory on a list and then @code{cd} to
2465 arguments, exchanges the top two directories.
2469 Brings the @var{N}th directory (counting from the left of the
2470 list printed by @code{dirs}, starting with zero) to the top of
2471 the list by rotating the stack.
2473 Brings the @var{N}th directory (counting from the right of the
2474 list printed by @code{dirs}, starting with zero) to the top of
2475 the list by rotating the stack.
2477 Suppresses the normal change of directory when adding directories
2478 to the stack, so that only the stack is manipulated.
2480 Makes the current working directory be the top of the stack, and then
2481 @code{cd}s to @var{dir}. You can see the saved directory list
2482 with the @code{dirs} command.
2488 popd [+@var{N} | -@var{N}] [-n]
2491 Pop the directory stack, and @code{cd} to the new top directory. When
2492 no arguments are given, @code{popd}
2493 removes the top directory from the stack and
2494 performs a @code{cd} to the new top directory. The
2495 elements are numbered from 0 starting at the first directory listed with
2496 @code{dirs}; i.e., @code{popd} is equivalent to @code{popd +0}.
2499 Removes the @var{N}th directory (counting from the left of the
2500 list printed by @code{dirs}), starting with zero.
2502 Removes the @var{N}th directory (counting from the right of the
2503 list printed by @code{dirs}), starting with zero.
2505 Suppresses the normal change of directory when removing directories
2506 from the stack, so that only the stack is manipulated.
2512 dirs [+@var{N} | -@var{N}] [-clvp]
2514 Display the list of currently remembered directories. Directories
2515 find their way onto the list with the @code{pushd} command; you can get
2516 back up through the list with the @code{popd} command.
2519 Displays the @var{N}th directory (counting from the left of the
2520 list printed by @code{dirs} when invoked without options), starting
2523 Displays the @var{N}th directory (counting from the right of the
2524 list printed by @code{dirs} when invoked without options), starting
2527 Clears the directory stack by deleting all of the elements.
2529 Produces a longer listing; the default listing format uses a
2530 tilde to denote the home directory.
2532 Causes @code{dirs} to print the directory stack with one entry per
2535 Causes @code{dirs} to print the directory stack with one entry per
2536 line, prepending each entry with its index in the stack.
2542 history [-c] [@var{n}]
2543 history [-anrw] [@var{filename}]
2544 history -ps @var{arg}
2547 Display the history list with line numbers. Lines prefixed with
2548 with a @samp{*} have been modified. An argument of @var{n} says
2549 to list only the last @var{n} lines. Options, if supplied, have
2550 the following meanings:
2554 Write out the current history to the history file.
2557 Read the current history file and append its contents to
2562 history lines (history lines entered since the beginning of the
2563 current Bash session) to the history file.
2566 Append the history lines not already read from the history file
2567 to the current history list. These are lines appended to the history
2568 file since the beginning of the current Bash session.
2571 Clear the history list. This may be combined
2572 with the other options to replace the history list completely.
2575 The @var{arg}s are added to the end of
2576 the history list as a single entry.
2579 Perform history substitution on the @var{arg}s and display the result
2580 on the standard output, without storing the results in the history list.
2583 When the @samp{-w}, @samp{-r}, @samp{-a}, or @samp{-n} option is
2584 used, if @var{filename}
2585 is given, then it is used as the history file. If not, then
2586 the value of the @code{HISTFILE} variable is used.
2594 A synonym for @code{.} (@pxref{Bourne Shell Builtins}).
2598 @node C Shell Variables
2599 @section C Shell Variables
2604 If this variable is set, its value is used the number of consecutive
2605 @code{EOF}s Bash will read before exiting. By default, Bash will exit
2606 upon reading a single @code{EOF}. If @code{IGNOREEOF} is not set to
2607 a numeric value, Bash acts as if its value were 10.
2611 @node Korn Shell Features
2612 @chapter Korn Shell Style Features
2614 This section describes features primarily inspired by the
2615 Korn Shell (@code{ksh}). In some cases, the @sc{POSIX} 1003.2
2616 standard has adopted these commands and variables from the
2617 Korn Shell; Bash implements those features using the @sc{POSIX}
2618 standard as a guide.
2621 * Korn Shell Constructs:: Shell grammar constructs adopted from the
2623 * Korn Shell Builtins:: Builtin commands adopted from the Korn Shell.
2624 * Korn Shell Variables:: Variables which Bash uses in essentially
2625 the same way as the Korn Shell.
2626 * Aliases:: Substituting one command for another.
2629 @node Korn Shell Constructs
2630 @section Korn Shell Constructs
2632 Bash includes the Korn Shell @code{select} construct. This construct
2633 allows the easy generation of menus. It has almost the same syntax as
2634 the @code{for} command.
2636 The syntax of the @code{select} command is:
2639 select @var{name} [in @var{words} @dots{}]; do @var{commands}; done
2642 The list of words following @code{in} is expanded, generating a list
2643 of items. The set of expanded words is printed on the standard
2644 error, each preceded by a number. If the @samp{in @var{words}}
2645 is omitted, the positional parameters are printed. The
2646 @code{PS3} prompt is then displayed and a line is read from the standard
2647 input. If the line consists of a number corresponding to one of
2648 the displayed words, then the value of @var{name}
2649 is set to that word. If the line is empty, the words and prompt
2650 are displayed again. If @code{EOF} is read, the @code{select}
2651 command completes. Any other value read causes @var{name}
2652 to be set to null. The line read is saved in the variable
2655 The @var{commands} are executed after each selection until a
2656 @code{break} or @code{return} command is executed, at which
2657 point the @code{select} command completes.
2659 Bash also has adopted command timing from the Korn shell. If the
2660 @code{time} reserved word precedes a pipeline, which may consist
2661 of a single command, timing statistics for the pipeline are displayed
2663 The statistics currently consist of elapsed (wall-clock) time and
2664 user and system time consumed by the command's execution.
2666 The use of @code{time} as a reserved word permits the timing of
2667 shell builtins, shell functions, and pipelines. An external
2668 @code{time} command cannot time these easily.
2670 @node Korn Shell Builtins
2671 @section Korn Shell Builtins
2673 This section describes Bash builtin commands taken from @code{ksh}.
2680 @code{fc [-e @var{ename}] [-nlr] [@var{first}] [@var{last}]}
2681 @code{fc -s [@var{pat}=@var{rep}] [@var{command}]}
2684 Fix Command. In the first form, a range of commands from @var{first} to
2685 @var{last} is selected from the history list. Both @var{first} and
2686 @var{last} may be specified as a string (to locate the most recent
2687 command beginning with that string) or as a number (an index into the
2688 history list, where a negative number is used as an offset from the
2689 current command number). If @var{last} is not specified it is set to
2690 @var{first}. If @var{first} is not specified it is set to the previous
2691 command for editing and @minus{}16 for listing. If the @samp{-l} flag is
2692 given, the commands are listed on standard output. The @samp{-n} flag
2693 suppresses the command numbers when listing. The @samp{-r} flag
2694 reverses the order of the listing. Otherwise, the editor given by
2695 @var{ename} is invoked on a file containing those commands. If
2696 @var{ename} is not given, the value of the following variable expansion
2697 is used: @code{$@{FCEDIT:-$@{EDITOR:-vi@}@}}. This says to use the
2698 value of the @code{FCEDIT} variable if set, or the value of the
2699 @code{EDITOR} variable if that is set, or @code{vi} if neither is set.
2700 When editing is complete, the edited commands are echoed and executed.
2702 In the second form, @var{command} is re-executed after each instance
2703 of @var{pat} in the selected command is replaced by @var{rep}.
2705 A useful alias to use with the @code{fc} command is @code{r='fc -s'}, so
2706 that typing @samp{r cc} runs the last command beginning with @code{cc}
2707 and typing @samp{r} re-executes the last command (@pxref{Aliases}).
2711 The @code{let} builtin allows arithmetic to be performed on shell variables.
2712 For details, refer to @ref{Arithmetic Builtins}.
2716 The @code{typeset} command is supplied for compatibility with the Korn
2717 shell; however, it has been deprecated in favor of the
2718 @code{declare} command (@pxref{Bash Builtins}).
2722 @node Korn Shell Variables
2723 @section Korn Shell Variables
2728 The default variable for the @code{read} builtin.
2731 Each time this parameter is referenced, a random integer
2732 between 0 and 32767 is generated. Assigning a value to this
2733 variable seeds the random number generator.
2736 This variable expands to the number of seconds since the
2737 shell was started. Assignment to this variable resets
2738 the count to the value assigned, and the expanded value
2739 becomes the value assigned plus the number of seconds
2740 since the assignment.
2743 The value of this variable is used as the prompt for the
2744 @code{select} command. If this variable is not set, the
2745 @code{select} command prompts with @samp{#? }
2748 This is the prompt printed before the command line is echoed
2749 when the @samp{-x} option is set (@pxref{The Set Builtin}).
2750 The default is @samp{+ }.
2753 The current working directory as set by the @code{cd} builtin.
2756 The previous working directory as set by the @code{cd} builtin.
2759 If set to a value greater than zero, the value is interpreted as
2760 the number of seconds to wait for input after issuing the primary
2762 Bash terminates after that number of seconds if input does
2766 The line number in the script or shell function currently executing.
2769 The editor used as a default by the @code{fc} builtin command.
2775 @cindex alias expansion
2778 * Alias Builtins:: Builtins commands to maniuplate aliases.
2781 The shell maintains a list of @var{aliases}
2782 that may be set and unset with the @code{alias} and
2783 @code{unalias} builtin commands.
2785 The first word of each command, if unquoted,
2786 is checked to see if it has an
2787 alias. If so, that word is replaced by the text of the alias.
2788 The alias name and the replacement text may contain any valid
2789 shell input, including shell metacharacters, with the exception
2790 that the alias name may not contain @key{=}.
2791 The first word of the replacement text is tested for
2792 aliases, but a word that is identical to an alias being expanded
2793 is not expanded a second time. This means that one may alias
2794 @code{ls} to @code{"ls -F"},
2795 for instance, and Bash does not try to recursively expand the
2796 replacement text. If the last character of the alias value is a
2797 space or tab character, then the next command word following the
2798 alias is also checked for alias expansion.
2800 Aliases are created and listed with the @code{alias}
2801 command, and removed with the @code{unalias} command.
2803 There is no mechanism for using arguments in the replacement text,
2805 If arguments are needed, a shell function should be used
2806 (@pxref{Shell Functions}).
2808 Aliases are not expanded when the shell is not interactive,
2809 unless the @code{expand_aliases} shell option is set using
2810 @code{shopt} (@pxref{Bash Builtins}).
2812 The rules concerning the definition and use of aliases are
2813 somewhat confusing. Bash
2814 always reads at least one complete line
2815 of input before executing any
2816 of the commands on that line. Aliases are expanded when a
2817 command is read, not when it is executed. Therefore, an
2818 alias definition appearing on the same line as another
2819 command does not take effect until the next line of input is read.
2820 The commands following the alias definition
2821 on that line are not affected by the new alias.
2822 This behavior is also an issue when functions are executed.
2823 Aliases are expanded when the function definition is read,
2824 not when the function is executed, because a function definition
2825 is itself a compound command. As a consequence, aliases
2826 defined in a function are not available until after that
2827 function is executed. To be safe, always put
2828 alias definitions on a separate line, and do not use @code{alias}
2829 in compound commands.
2831 Note that for almost every purpose, aliases are superseded by
2834 @node Alias Builtins
2835 @subsection Alias Builtins
2842 alias [@code{-p}] [@var{name}[=@var{value}] @dots{}]
2845 Without arguments or with the @samp{-p} option, @code{alias} prints
2846 the list of aliases on the standard output in a form that allows
2847 them to be reused as input.
2848 If arguments are supplied, an alias is defined for each @var{name}
2849 whose @var{value} is given. If no @var{value} is given, the name
2850 and value of the alias is printed.
2855 unalias [-a] [@var{name} @dots{} ]
2858 Remove each @var{name} from the list of aliases. If @samp{-a} is
2859 supplied, all aliases are removed.
2863 @chapter Bash Features
2865 This section describes features unique to Bash.
2868 * Invoking Bash:: Command line options that you can give
2870 * Bash Startup Files:: When and how Bash executes scripts.
2871 * Is This Shell Interactive?:: Determining the state of a running Bash.
2872 * Bash Builtins:: Table of builtins specific to Bash.
2873 * The Set Builtin:: This builtin is so overloaded it
2874 deserves its own section.
2875 * Bash Conditional Expressions:: Primitives used in composing expressions for
2876 the @code{test} builtin.
2877 * Bash Variables:: List of variables that exist in Bash.
2878 * Shell Arithmetic:: Arithmetic on shell variables.
2879 * Arrays:: Array Variables
2880 * Printing a Prompt:: Controlling the PS1 string.
2881 * The Restricted Shell:: A more controlled mode of shell execution.
2882 * Bash POSIX Mode:: Making Bash behave more closely to what
2883 the POSIX standard specifies.
2887 @section Invoking Bash
2890 bash [long-opt] [-ir] [-abefhkmnptuvxdBCDHP] [-o @var{option}] [@var{argument} @dots{}]
2891 bash [long-opt] [-abefhkmnptuvxdBCDHP] [-o @var{option}] -c @var{string} [@var{argument} @dots{}]
2892 bash [long-opt] -s [-abefhkmnptuvxdBCDHP] [-o @var{option}] [@var{argument} @dots{}]
2895 In addition to the single-character shell command-line options
2896 (@pxref{The Set Builtin}), there are several multi-character
2897 options that you can use. These options must appear on the command
2898 line before the single-character options in order for them
2902 @item --dump-strings
2903 Equivalent to @samp{-D}.
2906 Display a usage message on standard output and exit sucessfully.
2909 Make this shell act as if it were directly invoked by login.
2910 This is equivalent to @samp{exec -l bash} but can be issued from
2911 another shell, such as @code{csh}. If you wanted to replace your
2912 current login shell with a Bash login shell, you would say
2913 @samp{exec bash --login}.
2916 Do not use the @sc{GNU} Readline library (@pxref{Command Line Editing})
2917 to read interactive command lines.
2920 Don't load the system-wide startup file @file{/etc/profile}
2921 or any of the personal initialization files
2922 @file{~/.bash_profile}, @file{~/.bash_login}, or @file{~/.profile}
2923 when Bash is invoked as a login shell.
2926 Don't read the @file{~/.bashrc} initialization file in an
2927 interactive shell. This is on by default if the shell is
2928 invoked as @code{sh}.
2931 Change the behavior of Bash where the default operation differs
2932 from the @sc{POSIX} 1003.2 standard to match the standard. This
2933 is intended to make Bash behave as a strict superset of that
2934 standard. @xref{Bash POSIX Mode}, for a description of the Bash
2937 @item --rcfile @var{filename}
2938 Execute commands from @var{filename} (instead of @file{~/.bashrc})
2939 in an interactive shell.
2942 Make the shell a restricted shell (@pxref{The Restricted Shell}).
2945 Equivalent to @samp{-v}.
2948 Show version information for this instance of
2949 Bash on the standard output and exit successfully.
2953 There are several single-character options you can give which are
2954 not available with the @code{set} builtin.
2957 @item -c @var{string}
2958 Read and execute commands from @var{string} after processing the
2959 options, then exit. Any remaining arguments are assigned to the
2960 positional parameters, starting with @code{$0}.
2963 Force the shell to run interactively.
2966 Make the shell restricted.
2969 If this flag is present, or if no arguments remain after option
2970 processing, then commands are read from the standard input.
2971 This option allows the positional parameters to be set
2972 when invoking an interactive shell.
2975 A list of all double-quoted strings preceded by @samp{$}
2976 is printed on the standard ouput.
2977 These are the strings that
2978 are subject to language translation when the current locale
2979 is not @code{C} or @code{POSIX} (@pxref{Locale Translation}).
2980 This implies the @samp{-n} option; no commands will be executed.
2984 @cindex interactive shell
2985 An @emph{interactive} shell is one whose input and output are both
2986 connected to terminals (as determined by @code{isatty()}), or one
2987 started with the @samp{-i} option.
2989 If arguments remain after option processing, and neither the
2990 @samp{-c} nor the @samp{-s}
2991 option has been supplied, the first argument is assumed to
2992 be the name of a file containing shell commands (@pxref{Shell Scripts}).
2993 When Bash is invoked in this fashion, @code{$0}
2994 is set to the name of the file, and the positional parameters
2995 are set to the remaining arguments.
2996 Bash reads and executes commands from this file, then exits.
2997 Bash's exit status is the exit status of the last command executed
2998 in the script. If no commands are executed, the exit status is 0.
3000 @node Bash Startup Files
3001 @section Bash Startup Files
3002 @cindex startup files
3004 This section describs how Bash executes its startup files.
3005 If any of the files exist but cannot be read, Bash reports an error.
3006 Tildes are expanded in file names as described above under
3007 Tilde Expansion (@pxref{Tilde Expansion}).
3009 When Bash is invoked as an interactive login shell, it first reads and
3010 executes commands from the file @file{/etc/profile}, if that file exists.
3011 After reading that file, it looks for @file{~/.bash_profile},
3012 @file{~/.bash_login}, and @file{~/.profile}, in that order, and reads
3013 and executes commands from the first one that exists and is readable.
3014 The @samp{--noprofile} option may be used when the shell is started to
3015 inhibit this behavior.
3017 When a login shell exits, Bash reads and executes commands from
3018 the file @file{~/.bash_logout}, if it exists.
3020 When an interactive shell that is not a login shell is started, Bash
3021 reads and executes commands from @file{~/.bashrc}, if that file exists.
3022 This may be inhibited by using the @samp{--norc} option.
3023 The @samp{--rcfile @var{file}} option will force Bash to read and
3024 execute commands from @var{file} instead of @file{~/.bashrc}.
3026 So, typically, your @file{~/.bash_profile} contains the line
3028 @code{if [ -f @file{~/.bashrc} ]; then . @file{~/.bashrc}; fi}
3031 after (or before) any login-specific initializations.
3033 When Bash is started non-interactively, to run a shell script,
3034 for example, it looks for the variable @code{BASH_ENV} in the environment,
3035 expands its value if it appears there, and uses the expanded value as
3036 the name of a file to read and execute. Bash behaves as if the
3037 following command were executed:
3039 @code{if [ -n "$BASH_ENV" ]; then . "$BASH_ENV"; fi}
3042 but the value of the @code{PATH} variable is not used to search for the
3045 If Bash is invoked with the name @code{sh}, it tries to mimic the
3046 startup behavior of historical versions of @code{sh} as closely as
3047 possible, while conforming to the @sc{POSIX} standard as well.
3049 When invoked as a login shell, it first attempts to read and execute
3050 commands from @file{/etc/profile} and @file{~/.profile}, in that order.
3051 The @samp{--noprofile} option may be used to inhibit this behavior.
3052 When invoked as an interactive shell with the name @code{sh},
3053 @code{bash} looks for the variable @code{ENV},
3054 expands its value if it is defined, and uses the
3055 expanded value as the name of a file to read and execute.
3056 Since a shell invoked as @code{sh} does not attempt to read and execute
3057 commands from any other startup files, the @samp{--rcfile} option has
3059 A non-interactive shell invoked with the name @code{sh} does not attempt
3060 to read any startup files.
3062 When invoked as @code{sh}, Bash enters @sc{POSIX} mode after
3063 the startup files are read.
3065 When Bash is started in @sc{POSIX} mode, as with the
3066 @samp{--posix} command line option, it follows the @sc{POSIX} standard
3068 In this mode, the @code{ENV} variable is expanded and commands are read
3069 and executed from the file whose name is the expanded value.
3070 No other startup files are read.
3071 This is done by interactive shells only.
3073 Bash attempts to determine when it is being run by the remote shell
3074 daemon, usually @code{rshd}. If Bash determines it is being run by
3075 rshd, it reads and executes commands from @file{~/.bashrc}, if that
3076 file exists and is readable.
3077 It will not do this if invoked as @code{sh}.
3078 The @samp{--norc} option may be used to inhibit this behavior, and the
3079 @samp{--rcfile} option may be used to force another file to be read, but
3080 rshd does not generally invoke the shell with those options or allow
3081 them to be specified.
3083 @node Is This Shell Interactive?
3084 @section Is This Shell Interactive?
3085 @cindex interactive shell
3087 As defined in @ref{Invoking Bash}, an interactive shell
3088 is one whose input and output are both
3089 connected to terminals (as determined by @code{isatty(3)}),
3090 or one started with the @samp{-i} option.
3092 You may wish to determine within a startup script whether Bash is
3093 running interactively or not. To do this, examine the variable
3094 @code{$PS1}; it is unset in non-interactive shells, and set in
3095 interactive shells. Thus:
3098 if [ -z "$PS1" ]; then
3099 echo This shell is not interactive
3101 echo This shell is interactive
3105 Alternatively, you may test the value of the @samp{-} special parameter.
3106 It contains @code{i} when the shell is interactive. For example:
3110 *i*) echo This shell is interactive ;;
3111 *) echo This shell is not interactive ;;
3116 @section Bash Builtin Commands
3118 This section describes builtin commands which are unique to
3119 or have been extended in Bash.
3126 bind [-m @var{keymap}] [-lpsvPSV] [-q @var{name}] [-r @var{keyseq}]
3127 bind [-m @var{keymap}] -f @var{filename}
3128 bind [-m @var{keymap}] @var{keyseq:function-name}
3131 Display current Readline (@pxref{Command Line Editing})
3132 key and function bindings, or
3133 bind a key sequence to a Readline function or macro. The
3134 binding syntax accepted is identical to that of
3135 @file{.inputrc} (@pxref{Readline Init File}),
3136 but each binding must be passed as a separate argument: e.g.,
3137 @samp{"\C-x\C-r":re-read-init-file}.
3138 Options, if supplied, have the following meanings:
3141 @item -m @var{keymap}
3142 Use @var{keymap} as the keymap to be affected by
3143 the subsequent bindings. Acceptable @var{keymap}
3146 @code{emacs-standard},
3150 @code{vi-command}, and
3152 @code{vi} is equivalent to @code{vi-command};
3153 @code{emacs} is equivalent to @code{emacs-standard}.
3156 List the names of all Readline functions
3159 Display Readline function names and bindings in such a way that they
3163 List current Readline function names and bindings
3166 Display Readline variable names and values in such a way that they
3170 List current Readline variable names and values
3173 Display Readline key sequences bound to macros and the strings they output
3174 in such a way that they can be re-read
3177 Display Readline key sequences bound to macros and the strings they output
3179 @item -f @var{filename}
3180 Read key bindings from @var{filename}
3183 Query about which keys invoke the named @var{function}
3185 @item -r @var{keyseq}
3186 Remove any current binding for @var{keyseq}
3193 builtin [@var{shell-builtin} [@var{args}]]
3195 Run a shell builtin. This is useful when you wish to define a
3196 shell function with the same name as a shell builtin, but need the
3197 functionality of the builtin within the function itself.
3202 command [-pVv] @var{command} [@var{args} @dots{}]
3204 Runs @var{command} with @var{arg} ignoring shell functions. If
3205 you have a shell function called @code{ls}, and you wish to call
3206 the command @code{ls}, you can say @samp{command ls}. The
3207 @samp{-p} option means to use a default value for @code{$PATH}
3208 that is guaranteed to find all of the standard utilities.
3210 If either the @samp{-V} or @samp{-v} option is supplied, a
3211 description of @var{command} is printed. The @samp{-v} option
3212 causes a single word indicating the command or file name used to
3213 invoke @var{command} to be printed; the @samp{-V} option produces
3214 a more verbose description.
3219 declare [-afFrxi] [-p] [@var{name}[=@var{value}]]
3222 Declare variables and give them attributes. If no @var{name}s
3223 are given, then display the values of variables instead.
3225 The @samp{-p} option will display the attributes and values of each
3226 @var{name}. When @samp{-p} is used, additional options are ignored.
3227 The @samp{-F} option inhibits the display of function definitions;
3228 only the function name and attributes are printed. @samp{-F} implies
3229 @samp{-f}. The following options can be used to restrict output
3230 to variables with the specified attributes or to give variables
3235 Each @var{name} is an array variable (@pxref{Arrays}).
3238 Use function names only.
3241 The variable is to be treated as
3242 an integer; arithmetic evaluation (@pxref{Shell Arithmetic}) is
3243 performed when the variable is assigned a value.
3246 Make @var{name}s readonly. These names cannot then be assigned values
3247 by subsequent assignment statements.
3250 Mark each @var{name} for export to subsequent commands via
3255 instead of @samp{-} turns off the attribute instead. When used in
3256 a function, @code{declare} makes each @var{name} local, as with the
3257 @code{local} command.
3262 echo [-neE] [arg @dots{}]
3264 Output the @code{arg}s, separated by spaces, terminated with a
3265 newline. The return status is always 0. If @samp{-n} is
3266 specified, the trailing newline is suppressed. If the @samp{-e}
3267 option is given, interpretation of the following backslash-escaped
3268 characters is enabled. The @samp{-E} option disables the interpretation
3269 of these escape characters, even on systems where they are interpreted
3271 @code{echo} interprets the following escape sequences:
3278 suppress trailing newline
3294 the character whose ASCII code is @code{nnn} (octal)
3300 enable [-n] [-p] [-f @var{filename}] [-ads] [@var{name} @dots{}]
3302 Enable and disable builtin shell commands. This allows you to
3303 use a disk command which has the same name as a shell builtin.
3304 If @samp{-n} is used, the @var{name}s become disabled. Otherwise
3305 @var{name}s are enabled. For example, to use the @code{test} binary
3306 found via @code{$PATH} instead of the shell builtin version, type
3307 @samp{enable -n test}.
3309 If the @samp{-p} option is supplied, or no @var{name} arguments appear,
3310 a list of shell builtins is printed. With no other arguments, the list
3311 consists of all enabled shell builtins.
3312 The @samp{-a} option means to list
3313 each builtin with an indication of whether or not it is enabled.
3315 The @samp{-f} option means to load the new builtin command @var{name}
3316 from shared object @var{filename}, on systems that support dynamic loading.
3317 The @samp{-d} option will delete a builtin loaded with @samp{-f}.
3318 If there are no options, a list of the shell builtins is displayed.
3319 The @samp{-s} option restricts @code{enable} to the @sc{POSIX.2} special
3320 builtins. If @samp{-s} is used with @samp{-f}, the new builtin becomes
3326 help [@var{pattern}]
3328 Display helpful information about builtin commands. If
3329 @var{pattern} is specified, @code{help} gives detailed help
3330 on all commands matching @var{pattern}, otherwise a list of
3331 the builtins is printed.
3336 local @var{name}[=@var{value}]
3338 For each argument, create a local variable called @var{name}, and
3339 give it @var{value}.
3340 @code{local} can only be used within a function; it makes the variable
3341 @var{name} have a visible scope restricted to that function and its
3349 Exit a login shell, returning a status of @var{n} to the shell's
3355 read [-a @var{aname}] [-p @var{prompt}] [-er] [@var{name} @dots{}]
3357 One line is read from the standard input, and the first word
3358 is assigned to the first
3359 @var{name}, the second word to the second @var{name},
3360 and so on, with leftover words assigned to the last @var{name}.
3361 Only the characters in the value of the @code{IFS} variable
3362 are recognized as word delimiters. If no names
3363 are supplied, the line read is assigned to the variable @code{REPLY}.
3364 The return code is zero, unless end-of-file is encountered. Options,
3365 if supplied, have the following meanings:
3369 If this option is given, a backslash-newline pair is not ignored, and
3370 the backslash is considered to be part of the line.
3372 @item -p @var{prompt}
3373 Display @code{prompt}, without a
3374 trailing newline, before attempting to read any input. The prompt
3375 is displayed only if input is coming from a terminal.
3377 @item -a @var{aname}
3378 The words are assigned to
3379 sequential indices of the array variable @var{aname}, starting at 0.
3382 Readline (@pxref{Command Line Editing})
3383 is used to obtain the line.
3389 shopt [-pqsu] [-o] [@var{optname} @dots{}]
3391 Toggle the values of variables controlling optional shell behavior.
3392 With no options, or with the @samp{-p}
3393 option, a list of all settable options is displayed, with
3394 an indication of whether or not each is set. Other options have
3395 the following meanings:
3399 Enable (set) each @var{optname}
3402 Disable (unset) each @var{optname}.
3405 Suppresses normal output; the return status
3406 indicates whether the @var{optname} is set or unset.
3407 If multiple @var{optname} arguments are given with @samp{-q},
3408 the return status is zero if all @var{optnames} are enabled;
3412 Restricts the values of
3413 @var{optname} to be those defined for the @samp{-o} option to the
3414 @code{set} builtin (@pxref{The Set Builtin}).
3418 @samp{-s} or @samp{-u}
3419 is used with no @var{optname} arguments, the display is limited to
3420 those options which are set or unset, respectively.
3422 Unless otherwise noted, the @code{shopt} options are disabled (off)
3425 The return status when listing options is zero if all @var{optnames}
3426 are enabled, non-zero otherwise. When setting or unsetting options,
3427 the return status is zero unless an @var{optname} is not a legal shell
3430 The list of @code{shopt} options is:
3433 If this is set, an argument to the @code{cd}
3434 builtin command that
3435 is not a directory is assumed to be the name of a variable whose
3436 value is the directory to change to.
3439 If set, minor errors in the spelling of a directory component in a
3440 @code{cd} command will be corrected.
3441 The errors checked for are transposed characters,
3442 a missing character, and a character too many.
3443 If a correction is found, the corrected path is printed,
3444 and the command proceeds.
3445 This option is only used by interactive shells.
3448 If this is set, Bash checks that a command found in the hash
3449 table exists before trying to execute it. If a hashed command no
3450 longer exists, a normal path search is performed.
3453 If set, Bash checks the window size after each command
3454 and, if necessary, updates the values of
3455 @code{LINES} and @code{COLUMNS}.
3459 attempts to save all lines of a multiple-line
3460 command in the same history entry. This allows
3461 easy re-editing of multi-line commands.
3464 If set, Bash includes filenames beginning with a `.' in
3465 the results of filename expansion.
3468 If this is set, a non-interactive shell will not exit if
3469 it cannot execute the file specified as an argument to the @code{exec}
3470 builtin command. An interactive shell does not exit if @code{exec}
3474 If set, the history list is appended to the file named by the value
3475 of the @code{HISTFILE}
3476 variable when the shell exits, rather than overwriting the file.
3479 If set, and Readline
3480 is being used, a user is given the opportunity to re-edit a
3481 failed history substitution.
3484 If set, and Readline
3485 is being used, the results of history substitution are not immediately
3486 passed to the shell parser. Instead, the resulting line is loaded into
3487 the Readline editing buffer, allowing further modification.
3490 If set, and Readline is being used, Bash will attempt to perform
3491 hostname completion when a word beginning with @samp{@@} is being
3492 completed (@pxref{Commands For Completion}). This option is enabled
3495 @item interactive_comments
3496 Allow a word beginning with @samp{#}
3497 to cause that word and all remaining characters on that
3498 line to be ignored in an interactive shell.
3499 This option is enabled by default.
3502 If enabled, and the @code{cmdhist}
3503 option is enabled, multi-line commands are saved to the history with
3504 embedded newlines rather than using semicolon separators where possible.
3507 If set, and a file that Bash is checking for mail has been
3508 accessed since the last time it was checked, the message
3509 @code{"The mail in @var{mailfile} has been read"} is displayed.
3512 If set, Bash allows filename patterns which match no
3513 files to expand to a null string, rather than themselves.
3516 If set, prompt strings undergo variable and parameter expansion after
3517 being expanded (@pxref{Printing a Prompt}).
3518 This option is enabled by default.
3521 If this is set, the @code{shift}
3522 builtin prints an error message when the shift count exceeds the
3523 number of positional parameters.
3526 If set, the @code{source} builtin uses the value of @code{PATH}
3527 to find the directory containing the file supplied as an argument.
3528 This is enabled by default.
3534 type [-all] [-type | -path] [@var{name} @dots{}]
3536 For each @var{name}, indicate how it would be interpreted if used as a
3539 If the @samp{-type} flag is used, @code{type} returns a single word
3540 which is one of @samp{alias}, @samp{function}, @samp{builtin},
3541 @samp{file} or @samp{keyword},
3542 if @var{name} is an alias, shell function, shell builtin,
3543 disk file, or shell reserved word, respectively.
3544 If the @var{name} is not found, then nothing is printed, and
3545 @code{type} returns a failure status.
3547 If the @samp{-path} flag is used, @code{type} either returns the name
3548 of the disk file that would be executed, or nothing if @samp{-type}
3549 would not return @samp{file}.
3551 If the @samp{-all} flag is used, returns all of the places that contain
3552 an executable named @var{file}. This includes aliases and functions,
3553 if and only if the @samp{-path} flag is not also used.
3555 @code{type} accepts @samp{-a}, @samp{-t}, and @samp{-p} as equivalent to
3556 @samp{-all}, @samp{-type}, and @samp{-path}, respectively.
3561 ulimit [-acdflmnpstuvSH] [@var{limit}]
3563 @code{ulimit} provides control over the resources available to processes
3564 started by the shell, on systems that allow such control. If an
3565 option is given, it is interpreted as follows:
3568 change and report the soft limit associated with a resource.
3571 change and report the hard limit associated with a resource.
3574 all current limits are reported.
3577 the maximum size of core files created.
3580 the maximum size of a process's data segment.
3583 the maximum size of files created by the shell.
3586 The maximum size that may be locked into memory.
3589 the maximum resident set size.
3592 the maximum number of open file descriptors.
3595 the pipe buffer size.
3598 the maximum stack size.
3601 the maximum amount of cpu time in seconds.
3604 the maximum number of processes available to a single user.
3607 the maximum amount of virtual memory available to the process.
3611 If @var{limit} is given, it is the new value of the specified resource.
3612 Otherwise, the current value of the soft limit for the specified resource
3613 is printed, unless the @samp{-H} option is supplied.
3614 When setting new limits, if neither @samp{-H} nor @samp{-S} is supplied,
3615 both the hard and soft limits are set.
3616 If no option is given, then @samp{-f} is assumed. Values are in 1024-byte
3617 increments, except for @samp{-t}, which is in seconds, @samp{-p},
3618 which is in units of 512-byte blocks, and @samp{-n} and @samp{-u}, which
3619 are unscaled values.
3623 @node The Set Builtin
3624 @section The Set Builtin
3626 This builtin is so overloaded that it deserves its own section.
3632 set [-abefhkmnptuvxdBCHP] [-o @var{option}] [@var{argument} @dots{}]
3637 Mark variables which are modified or created for export.
3640 Cause the status of terminated background jobs to be reported
3641 immediately, rather than before printing the next primary prompt.
3644 Exit immediately if a simple command exits with a non-zero status.
3647 Disable file name generation (globbing).
3650 Locate and remember (hash) commands as they are looked up for execution.
3653 All arguments in the form of assignment statements are placed
3654 in the environment for a command, not just those that precede
3658 Job control is enabled (@pxref{Job Control}).
3661 Read commands but do not execute them.
3663 @item -o @var{option-name}
3665 Set the flag corresponding to @var{option-name}:
3675 use an @code{emacs}-style line editing interface (@pxref{Command Line Editing}).
3687 Enable command history, as described in @ref{Bash History Facilities}.
3688 This option is on by default in interactive shells.
3691 the shell will not exit upon reading EOF.
3721 change the behavior of Bash where the default operation differs
3722 from the @sc{POSIX} 1003.2 standard to match the standard. This
3723 is intended to make Bash behave as a strict superset of that
3733 use a @code{vi}-style line editing interface.
3740 Turn on privileged mode.
3741 In this mode, the @code{$BASH_ENV}
3742 file is not processed, and shell functions
3743 are not inherited from the environment. This is enabled automatically
3744 on startup if the effective user (group) id is not equal to the real
3745 user (group) id. Turning this option off causes the effective user
3746 and group ids to be set to the real user and group ids.
3749 Exit after reading and executing one command.
3752 Treat unset variables as an error when substituting.
3755 Print shell input lines as they are read.
3758 Print commands and their arguments as they are executed.
3761 The shell will perform brace expansion (@pxref{Brace Expansion}).
3762 This option is on by default.
3765 Disallow output redirection to existing files.
3768 Enable @samp{!} style history substitution (@pxref{History Interaction}).
3769 This flag is on by default for interactive shells.
3772 If set, do not follow symbolic links when performing commands such as
3773 @code{cd} which change the current directory. The physical directory
3774 is used instead. By default, Bash follows
3775 the logical chain of directories when performing commands
3776 which change the current directory.
3778 For example, if @file{/usr/sys} is a link to @file{/usr/local/sys} then:
3780 $ cd /usr/sys; echo $PWD
3787 If @code{set -P} is on, then:
3789 $ cd /usr/sys; echo $PWD
3796 If no arguments follow this flag, then the positional parameters are
3797 unset. Otherwise, the positional parameters are set to the
3798 @var{arguments}, even if some of them begin with a @samp{-}.
3801 Signal the end of options, cause all remaining @var{arguments}
3802 to be assigned to the positional parameters. The @samp{-x}
3803 and @samp{-v} options are turned off.
3804 If there are no arguments, the positional parameters remain unchanged.
3807 Using @samp{+} rather than @samp{-} causes these flags to be
3808 turned off. The flags can also be used upon invocation of the
3809 shell. The current set of flags may be found in @code{$-}.
3811 The remaining N @var{arguments} are positional parameters and are
3812 assigned, in order, to @code{$1}, @code{$2}, @dots{} @code{$N}. If
3813 no arguments are given, all shell variables are printed.
3816 @node Bash Conditional Expressions
3817 @section Bash Conditional Expressions
3818 @cindex expressions, conditional
3820 Conditional expressions are used by the @code{test} and @code{[} builtins.
3822 Expressions may be unary or binary. Unary
3823 expressions are often used to examine the status of a file. There
3824 are string operators and numeric comparison operators as well. Each
3825 operator and operand must be a separate argument. If @var{file}
3826 is of the form @file{/dev/fd/@var{N}}, then file descriptor @var{N} is
3827 checked. Expressions are composed of the following primaries:
3831 True if @var{file} exists and is a block special file.
3834 True if @var{file} exists and is a character special file.
3837 True if @var{file} exists and is a directory.
3840 True if @var{file} exists.
3843 True if @var{file} exists and is a regular file.
3846 True if @var{file} exists and is set-group-id.
3849 True if @var{file} has its "sticky" bit set.
3852 True if @var{file} exists and is a symbolic link.
3855 True if @var{file} exists and is a named pipe.
3858 True if @var{file} exists and is readable.
3861 True if @var{file} exists and has a size greater than zero.
3864 True if @var{file} exists and is a socket.
3867 True if @var{fd} is opened on a terminal.
3870 True if @var{file} exists and its set-user-id bit is set.
3873 True if @var{file} exists and is writable.
3876 True if @var{file} exists and is executable.
3879 True if @var{file} exists and is owned by the effective user id.
3882 True if @var{file} exists and is owned by the effective group id.
3884 @item @var{file1} -nt @var{file2}
3885 True if @var{file1} is newer (according to
3886 modification date) than @var{file2}.
3888 @item @var{file1} -ot @var{file2}
3889 True if @var{file1} is older than @var{file2}.
3891 @item @var{file1} -ef @var{file2}
3892 True if @var{file1} and @var{file2} have the same device and
3895 @item -o @var{optname}
3896 True if shell option @var{optname} is enabled.
3897 The list of options appears in the description of the @samp{-o}
3898 option to the @code{set} builtin (@pxref{The Set Builtin}).
3900 @item -z @var{string}
3901 True if the length of @var{string} is zero.
3903 @item -n @var{string}
3905 True if the length of @var{string} is non-zero.
3907 @item @var{string1} = @var{string2}
3908 True if the strings are equal. @samp{==} may be used in place of
3911 @item @var{string1} != @var{string2}
3912 True if the strings are not equal.
3914 @item @var{string1} < @var{string2}
3915 True if @var{string1} sorts before @var{string2} lexicographically.
3917 @item @var{string1} > @var{string2}
3918 True if @var{string1} sorts after @var{string2} lexicographically.
3921 True if @var{expr} is false.
3923 @item @var{expr1} -a @var{expr2}
3924 True if both @var{expr1} and @var{expr2} are true.
3926 @item @var{expr1} -o @var{expr2}
3927 True if either @var{expr1} and @var{expr2} is true.
3929 @item @var{arg1} OP @var{arg2}
3931 @samp{-eq}, @samp{-ne}, @samp{-lt}, @samp{-le}, @samp{-gt}, or @samp{-ge}.
3932 These arithmetic binary operators return true if @var{arg1}
3933 is equal to, not equal to, less than, less than or equal to,
3934 greater than, or greater than or equal to @var{arg2},
3935 respectively. @var{Arg1} and @var{arg2}
3936 may be positive or negative integers.
3940 The Bash @code{test} and @code{[} builtins evaluate conditional
3941 expressions using a set of rules based on the number of arguments.
3942 These are the rules:
3946 The expression is false.
3948 The expression is true if and only if the argument is not null.
3950 If the first argument is @samp{!}, the expression is true if and
3951 only if the second argument is null. If the first argument is
3952 one of the listed unary operators, the expression is true if the
3953 unary test is true. If the first argument is not a legal unary
3954 operator, the expression is false.
3956 If the first argument is @samp{!}, the value is the negation of
3957 the two-argument test using the second and third arguments.
3958 If the second argument is one of the binary operators, the result
3959 of the expression is the result of the binary test using the first
3960 and third arguments as operands.
3961 If the first argument is exactly @samp{(} and the third argument is
3962 exactly @samp{)}, the result is the one-argument test of the second
3964 Otherwise, the expression is false.
3965 The @samp{-a} and @samp{-o} operators are considered binary operators
3968 If the first argument is @samp{!}, the result is the negation of
3969 the three-argument expression composed of the remaining arguments.
3970 Otherwise, the expression is parsed and evaluated according to
3971 precedence. @samp{-a} has a higher precedence than @samp{-o}.
3972 @item 5 or more arguments
3973 The expression is parsed and evaluated according to precedence,
3974 with @samp{-a} having a higher precedence than @samp{-o}.
3977 @node Bash Variables
3978 @section Bash Variables
3980 These variables are set or used by Bash, but other shells
3981 do not normally treat them specially.
3986 If this variable is set when Bash is invoked to execute a shell
3987 script, its value is expanded and used as the name of a startup file
3988 to read before executing the script. @xref{Bash Startup Files}.
3991 The value of this parameter is used as a format string specifying
3992 how the timing information for pipelines prefixed with the @code{time}
3993 reserved word should be displayed.
3994 The @samp{%} character introduces an
3995 escape sequence that is expanded to a time value or other
3997 The escape sequences and their meanings are as
3998 follows; the braces denote optional portions.
4005 @item %[@var{p}][l]R
4006 The elapsed time in seconds.
4008 @item %[@var{p}][l]U
4009 The number of CPU seconds spent in user mode.
4011 @item %[@var{p}][l]S
4012 The number of CPU seconds spent in system mode.
4015 The CPU percentage, computed as (%U + %S) / %R.
4018 The optional @var{p} is a digit specifying the precision, the number of
4019 fractional digits after a decimal point.
4020 A value of 0 causes no decimal point or fraction to be output.
4021 At most three places after the decimal point may be specified; values
4022 of @var{p} greater than 3 are changed to 3.
4023 If @var{p} is not specified, the value 3 is used.
4025 The optional @code{l} specifies a longer format, including minutes, of
4026 the form @var{MM}m@var{SS}.@var{FF}s.
4027 The value of @var{p} determines whether or not the fraction is included.
4029 If this variable is not set, bash acts as if it had the value
4031 @code{$'\nreal\t%3lR\nuser\t%3lU\nsys\t%3lS'}.
4033 If the value is null, no timing information is displayed.
4034 A trailing newline is added when the format string is displayed.
4037 Set to a value of @samp{ignorespace}, it means don't enter lines which
4038 begin with a space or tab into the history list. Set to a value
4039 of @samp{ignoredups}, it means don't enter lines which match the last
4040 entered line. A value of @samp{ignoreboth} combines the two options.
4041 Unset, or set to any other value than those above, means to save
4042 all lines on the history list.
4045 A colon-separated list of patterns used to decide which command
4046 lines should be saved on the history list. Each pattern is
4047 anchored at the beginning of the line and must fully specify the
4048 line (no implicit @samp{*} is appended). Each pattern is tested
4049 against the line after the checks specified by @code{HISTCONTROL}
4050 are applied. In addition to the normal shell pattern matching
4051 characters, @samp{&} matches the previous history line. @samp{&}
4052 may be escaped using a backslash. The backslash is removed
4053 before attempting a match.
4055 @code{HISTIGNORE} subsumes the function of @code{HISTCONTROL}. A
4056 pattern of @samp{&} is identical to @code{ignoredups}, and a
4057 pattern of @samp{[ ]*} is identical to @code{ignorespace}.
4058 Combining these two patterns, separating them with a colon,
4059 provides the functionality of @code{ignoreboth}.
4062 The name of the file to which the command history is saved. The
4063 default is @file{~/.bash_history}.
4066 If set, this is the maximum number of commands to remember in the
4070 The maximum number of lines contained in the history file. When this
4071 variable is assigned a value, the history file is truncated, if
4072 necessary, to contain no more than that number of lines. The default
4073 value is 500. The history file is also truncated to this size after
4074 writing it when an interactive shell exits.
4077 Up to three characters which control history expansion, quick
4078 substitution, and tokenization (@pxref{History Interaction}).
4079 The first character is the
4080 @dfn{history-expansion-char}, that is, the character which signifies the
4081 start of a history expansion, normally @samp{!}. The second character is the
4082 character which signifies `quick substitution' when seen as the first
4083 character on a line, normally @samp{^}. The optional third character is the
4084 character which signifies the remainder of the line is a comment, when
4085 found as the first character of a word, usually @samp{#}. The history
4086 comment character causes history substitution to be skipped for the
4087 remaining words on the line. It does not necessarily cause the shell
4088 parser to treat the rest of the line as a comment.
4091 The history number, or index in the history list, of the current
4092 command. If @code{HISTCMD} is unset, it loses its special properties,
4093 even if it is subsequently reset.
4096 Contains the name of a file in the same format as @file{/etc/hosts} that
4097 should be read when the shell needs to complete a hostname. You can
4098 change the file interactively; the next time you attempt to complete a
4099 hostname, Bash will add the contents of the new file to the already
4103 How often (in seconds) that the shell should check for mail
4104 in the files specified in @code{MAILPATH}.
4106 @item PROMPT_COMMAND
4107 If present, this contains a string which is a command to execute
4108 before the printing of each primary prompt (@code{$PS1}).
4111 The numeric real user id of the current user.
4114 The numeric effective user id of the current user.
4117 An array variable containing the list of groups of which the current
4121 The process id of the shell's parent process.
4124 The name of the current host.
4127 A string describing the machine Bash is running on.
4130 A string describing the operating system Bash is running on.
4133 A string that fully describes the system type on which Bash
4134 is executing, in the standard GNU @var{cpu-company-system} format.
4137 A colon-separated list of enabled shell options. Each word in
4138 the list is a valid argument for the @samp{-o} option to the
4139 @code{set} builtin command (@pxref{The Set Builtin}).
4140 The options appearing in @code{SHELLOPTS} are those reported
4141 as @samp{on} by @samp{set -o}.
4142 If this variable is in the environment when Bash
4143 starts up, each shell option in the list will be enabled before
4144 reading any startup files. This variable is readonly.
4147 A colon-separated list of suffixes to ignore when performing
4148 filename completion.
4149 A file name whose suffix matches one of the entries in
4151 is excluded from the list of matched file names. A sample
4152 value is @samp{.o:~}
4155 A colon-separated list of patterns defining the set of filenames to
4156 be ignored by filename expansion.
4157 If a filename matched by a filename expansion pattern also matches one
4158 of the patterns in @code{GLOBIGNORE}, it is removed from the list
4162 An array variable (@pxref{Arrays})
4163 containing the current contents of the directory stack.
4164 Directories appear in the stack in the order they are displayed by the
4165 @code{dirs} builtin.
4166 Assigning to members of this array variable may be used to modify
4167 directories already in the stack, but the @code{pushd} and @code{popd}
4168 builtins must be used to add and remove directories.
4169 Assignment to this variable will not change the current directory.
4170 If @code{DIRSTACK} is unset, it loses its special properties, even if
4171 it is subsequently reset.
4174 An array variable (@pxref{Arrays})
4175 containing a list of exit status values from the processes
4176 in the most-recently-executed foreground pipeline (which may
4177 contain only a single command).
4180 The name of the Readline startup file, overriding the default
4181 of @file{~/.inputrc}.
4184 The full filename used to execute the current instance of Bash.
4187 The version number of the current instance of Bash.
4190 An array variable whose members hold version information for this
4192 The values assigned to the array members are as follows:
4196 @item BASH_VERSINFO[0]
4197 The major version number (the @var{release}).
4199 @item BASH_VERSINFO[1]
4200 The minor version number (the @var{version}).
4202 @item BASH_VERSINFO[2]
4205 @item BASH_VERSINFO[3]
4208 @item BASH_VERSINFO[4]
4209 The release status (e.g., @var{beta1}).
4211 @item BASH_VERSINFO[5]
4212 The value of @code{MACHTYPE}.
4217 Incremented by one each time a new instance of Bash is started. This is
4218 intended to be a count of how deeply your Bash shells are nested.
4221 If set to the value 1, Bash displays error messages
4222 generated by the @code{getopts} builtin command.
4225 Used to determine the locale category for any category not specifically
4226 selected with a variable starting with @code{LC_}.
4229 This variable overrides the value of @code{LANG} and any other
4230 @code{LC_} variable specifying a locale category.
4233 This variable determines the collation order used when sorting the
4234 results of filename expansion (@pxref{Filename Expansion}).
4237 This variable determines the locale used to translate double-quoted
4238 strings preceded by a @samp{$} (@pxref{Locale Translation}).
4241 Controls the action of the shell on receipt of an @code{EOF} character
4242 as the sole input. If set, then the value of it is the number
4243 of consecutive @code{EOF} characters that can be read as the
4244 first character on an input line
4245 before the shell will exit. If the variable exists but does not
4246 have a numeric value (or has no value) then the default is 10.
4247 If the variable does not exist, then @code{EOF} signifies the end of
4248 input to the shell. This is only in effect for interactive shells.
4252 @node Shell Arithmetic
4253 @section Shell Arithmetic
4254 @cindex arithmetic, shell
4257 * Arithmetic Evaluation:: How shell arithmetic works.
4258 * Arithmetic Expansion:: How to use arithmetic in shell expansions.
4259 * Arithmetic Builtins:: Builtin commands that use shell arithmetic.
4262 Bash includes several mechanisms to evaluate arithmetic expressions
4263 and display the result or use it as part of a command.
4265 @node Arithmetic Evaluation
4266 @subsection Arithmetic Evaluation
4267 @cindex expressions, arithmetic
4268 @cindex evaluation, arithmetic
4269 @cindex arithmetic evaluation
4271 The shell allows arithmetic expressions to be evaluated, as one of
4272 the shell expansions or by the @code{let} builtin.
4274 Evaluation is done in long integers with no check for overflow,
4275 though division by 0 is trapped and flagged as an error. The
4276 following list of operators is grouped into levels of
4277 equal-precedence operators. The levels are listed in order of
4278 decreasing precedence.
4282 unary minus and plus
4285 logical and bitwise negation
4288 multiplication, division, remainder
4291 addition, subtraction
4294 left and right bitwise shifts
4300 equality and inequality
4306 bitwise exclusive OR
4317 @item expr ? expr : expr
4318 conditional evaluation
4320 @item = *= /= %= += -= <<= >>= &= ^= |=
4324 Shell variables are allowed as operands; parameter expansion is
4325 performed before the expression is evaluated.
4326 The value of a parameter is coerced to a long integer within
4327 an expression. A shell variable need not have its integer attribute
4328 turned on to be used in an expression.
4330 Constants with a leading 0 are interpreted as octal numbers.
4331 A leading @samp{0x} or @samp{0X} denotes hexadecimal. Otherwise,
4332 numbers take the form [@var{base}@code{#}]@var{n}, where @var{base}
4333 is a decimal number between 2 and 64 representing the arithmetic
4334 base, and @var{n} is a number in that base. If @var{base} is
4335 omitted, then base 10 is used.
4336 The digits greater than 9 are represented by the lowercase letters,
4337 the uppercase letters, @samp{_}, and @samp{@@}, in that order.
4338 If @var{base} is less than or equal to 36, lowercase and uppercase
4339 letters may be used interchangably to represent numbers between 10
4342 Operators are evaluated in order of precedence. Sub-expressions in
4343 parentheses are evaluated first and may override the precedence
4346 @node Arithmetic Expansion
4347 @subsection Arithmetic Expansion
4348 @cindex expansion, arithmetic
4349 @cindex arithmetic expansion
4351 Arithmetic expansion allows the evaluation of an arithmetic expression
4352 and the substitution of the result. The format for arithmetic expansion is:
4355 $(( @var{expression} ))
4358 The expression is treated as if it were within double quotes, but
4359 a double quote inside the braces or parentheses is not treated
4360 specially. All tokens in the expression undergo parameter
4361 expansion, command substitution, and quote removal. Arithmetic
4362 substitutions may be nested.
4364 The evaluation is performed according to the rules listed above.
4365 If the expression is invalid, Bash
4366 prints a message indicating failure and no substitution occurs.
4368 @node Arithmetic Builtins
4369 @subsection Arithmetic Builtins
4376 let @var{expression} [@var{expression}]
4378 The @code{let} builtin allows arithmetic to be performed on shell
4379 variables. Each @var{expression} is evaluated according to the
4380 rules given previously (@pxref{Arithmetic Evaluation}). If the
4381 last @var{expression} evaluates to 0, @code{let} returns 1;
4382 otherwise 0 is returned.
4389 Bash provides one-dimensional array variables. Any variable may be used as
4390 an array; the @code{declare} builtin will explicitly declare an array.
4392 limit on the size of an array, nor any requirement that members
4393 be indexed or assigned contiguously. Arrays are zero-based.
4395 An array is created automatically if any variable is assigned to using
4398 name[@var{subscript}]=@var{value}
4403 is treated as an arithmetic expression that must evaluate to a number
4404 greater than or equal to zero. To explicitly declare an array, use
4406 declare -a @var{name}
4411 declare -a @var{name}[@var{subscript}]
4414 is also accepted; the @var{subscript} is ignored. Attributes may be
4415 specified for an array variable using the @code{declare} and
4416 @code{readonly} builtins. Each attribute applies to all members of
4419 Arrays are assigned to using compound assignments of the form
4421 name=(value@var{1} @dots{} value@var{n})
4425 @var{value} is of the form @code{[[@var{subscript}]=]}@var{string}. If
4426 the optional subscript is supplied, that index is assigned to;
4427 otherwise the index of the element assigned is the last index assigned
4428 to by the statement plus one. Indexing starts at zero.
4429 This syntax is also accepted by the @code{declare}
4430 builtin. Individual array elements may be assigned to using the
4431 @code{name[}@var{subscript}@code{]=}@var{value} syntax introduced above.
4433 Any element of an array may be referenced using
4434 @code{$@{name[}@var{subscript}@code{]@}}.
4435 The braces are required to avoid
4436 conflicts with the shell's filename expansion operators. If the
4437 @var{subscript} is @samp{@@} or @samp{*}, the word expands to all members
4438 of the array @var{name}. These subscripts differ only when the word
4439 appears within double quotes. If the word is double-quoted,
4440 @code{$@{name[*]@}} expands to a single word with
4441 the value of each array member separated by the first character of the
4442 @code{IFS} variable, and @code{$@{name[@@]@}} expands each element of
4443 @var{name} to a separate word. When there are no array members,
4444 @code{$@{name[@@]@}} expands to nothing. This is analogous to the
4445 expansion of the special parameters @samp{@@} and @samp{*}.
4446 @code{$@{#name[}@var{subscript}@code{]@}} expands to the length of
4447 @code{$@{name[}@var{subscript}@code{]@}}.
4448 If @var{subscript} is @samp{@@} or
4449 @samp{*}, the expansion is the number of elements in the array.
4450 Referencing an array variable without a subscript is equivalent to
4451 referencing element zero.
4453 The @code{unset} builtin is used to destroy arrays.
4454 @code{unset} @var{name[subscript]}
4455 destroys the array element at index @var{subscript}.
4456 @code{unset} @var{name}, where @var{name} is an array, removes the
4457 entire array. A subscript of @samp{*} or @samp{@@} also removes the
4460 The @code{declare}, @code{local}, and @code{readonly}
4461 builtins each accept a @samp{-a}
4462 option to specify an array. The @code{read}
4463 builtin accepts a @samp{-a}
4464 option to assign a list of words read from the standard input
4465 to an array, and can read values from the standard input into
4466 individual array elements. The @code{set} and @code{declare}
4467 builtins display array values in a way that allows them to be
4470 @node Printing a Prompt
4471 @section Controlling the Prompt
4474 The value of the variable @code{PROMPT_COMMAND} is examined just before
4475 Bash prints each primary prompt. If it is set and non-null, then the
4476 value is executed just as if you had typed it on the command line.
4478 In addition, the following table describes the special characters which
4479 can appear in the prompt variables:
4485 the date, in "Weekday Month Date" format (e.g., "Tue May 26").
4487 an escape character.
4489 the hostname, up to the first `.'.
4495 the name of the shell, the basename of @code{$0} (the portion
4496 following the final slash).
4498 the time, in 24-hour HH:MM:SS format.
4500 the time, in 12-hour HH:MM:SS format.
4502 the time, in 12-hour am/pm format.
4504 the version of Bash (e.g., 2.00)
4506 the release of Bash, version + patchlevel (e.g., 2.00.0)
4508 the current working directory.
4510 the basename of @code{$PWD}.
4514 the history number of this command.
4516 the command number of this command.
4518 if the effective uid is 0, @code{#}, otherwise @code{$}.
4520 the character corresponding to the octal number @code{nnn}.
4524 begin a sequence of non-printing characters. This could be used to
4525 embed a terminal control sequence into the prompt.
4527 end a sequence of non-printing characters.
4530 @node The Restricted Shell
4531 @section The Restricted Shell
4532 @cindex restricted shell
4534 If Bash is started with the name @code{rbash}, or the
4536 option is supplied at invocation, the shell becomes restricted.
4537 A restricted shell is used to
4538 set up an environment more controlled than the standard shell.
4539 A restricted shell behaves identically to @code{bash}
4540 with the exception that the following are disallowed:
4543 Changing directories with the @code{cd} builtin.
4545 Setting or unsetting the values of the @code{SHELL} or @code{PATH}
4548 Specifying command names containing slashes.
4550 Specifying a filename containing a slash as an argument to the @code{.}
4553 Importing function definitions from the shell environment at startup.
4555 Redirecting output using the @samp{>}, @samp{>|}, @samp{<>}, @samp{>&},
4556 @samp{&>}, and @samp{>>} redirection operators.
4558 Using the @code{exec} builtin to replace the shell with another command.
4560 Adding or deleting builtin commands with the
4561 @samp{-f} and @samp{-d} options to the @code{enable} builtin.
4563 Specifying the @samp{-p} option to the @code{command} builtin.
4565 Turning off restricted mode with @samp{set +r}.
4568 @node Bash POSIX Mode
4569 @section Bash POSIX Mode
4572 Starting Bash with the @samp{--posix} command-line option or executing
4573 @samp{set -o posix} while Bash is running will cause Bash to conform more
4574 closely to the @sc{POSIX.2} standard by changing the behavior to match that
4575 specified by @sc{POSIX.2} in areas where the Bash default differs.
4577 The following list is what's changed when `@sc{POSIX} mode' is in effect:
4581 When a command in the hash table no longer exists, Bash will re-search
4582 @code{$PATH} to find the new location. This is also available with
4583 @samp{shopt -s checkhash}.
4586 The @samp{>&} redirection does not redirect stdout and stderr.
4589 The message printed by the job control code and builtins when a job
4590 exits with a non-zero status is `Done(status)'.
4593 Reserved words may not be aliased.
4596 The @sc{POSIX.2} @code{PS1} and @code{PS2} expansions of @samp{!} to
4597 the history number and @samp{!!} to @samp{!} are enabled,
4598 and parameter expansion is performed on
4599 the value regardless of the setting of the @code{promptvars} option.
4602 Interactive comments are enabled by default. (Note that Bash has
4603 them on by default anyway.)
4606 The @sc{POSIX.2} startup files are executed (@code{$ENV}) rather than
4607 the normal Bash files.
4610 Tilde expansion is only performed on assignments preceding a command
4611 name, rather than on all assignment statements on the line.
4614 The default history file is @file{~/.sh_history} (this is the
4615 default value of @code{$HISTFILE}).
4618 The output of @samp{kill -l} prints all the signal names on a single line,
4619 separated by spaces.
4622 Non-interactive shells exit if @var{filename} in @code{.} @var{filename}
4626 Redirection operators do not perform filename expansion on the word
4627 in the redirection unless the shell is interactive.
4630 Function names must be valid shell @code{name}s. That is, they may not
4631 contain characters other than letters, digits, and underscores, and
4632 may not start with a digit. Declaring a function with an illegal name
4633 causes a fatal syntax error in non-interactive shells.
4636 @sc{POSIX.2} `special' builtins are found before shell functions
4637 during command lookup.
4640 If a @sc{POSIX.2} special builtin returns an error status, a
4641 non-interactive shell exits. The fatal errors are those listed in
4642 the POSIX.2 standard, and include things like passing incorrect options,
4643 redirection errors, variable assignment errors for assignments preceding
4644 the command name, and so on.
4647 If the @code{cd} builtin finds a directory to change to
4648 using @code{$CDPATH}, the
4649 value it assigns to the @code{PWD} variable does not contain any
4650 symbolic links, as if @samp{cd -P} had been executed.
4653 A non-interactive shell exits with an error status if a variable
4654 assignment error occurs when no command name follows the assignment
4656 A variable assignment error occurs, for example, when trying to assign
4657 a value to a read-only variable.
4660 A non-interactive shell exits with an error status if the iteration
4661 variable in a @code{for} statement or the selection variable in a
4662 @code{select} statement is a read-only variable.
4665 Process substitution is not available.
4668 Assignment statements preceding @sc{POSIX.2} @code{special} builtins
4669 persist in the shell environment after the builtin completes.
4672 The @code{export} and @code{readonly} builtin commands display their
4673 output in the format required by @sc{POSIX.2}.
4677 There is other @sc{POSIX.2} behavior that Bash does not implement.
4682 Assignment statements affect the execution environment of all
4683 builtins, not just special ones.
4687 @chapter Job Control
4689 This chapter disusses what job control is, how it works, and how
4690 Bash allows you to access its facilities.
4693 * Job Control Basics:: How job control works.
4694 * Job Control Builtins:: Bash builtin commands used to interact
4696 * Job Control Variables:: Variables Bash uses to customize job
4700 @node Job Control Basics
4701 @section Job Control Basics
4705 @cindex suspending jobs
4708 refers to the ability to selectively stop (suspend)
4709 the execution of processes and continue (resume)
4710 their execution at a later point. A user typically employs
4711 this facility via an interactive interface supplied jointly
4712 by the system's terminal driver and Bash.
4714 The shell associates a @var{job} with each pipeline. It keeps a
4715 table of currently executing jobs, which may be listed with the
4716 @code{jobs} command. When Bash starts a job
4717 asynchronously (in the background), it prints a line that looks
4723 indicating that this job is job number 1 and that the process @sc{ID}
4724 of the last process in the pipeline associated with this job is
4725 25647. All of the processes in a single pipeline are members of
4726 the same job. Bash uses the @var{job} abstraction as the
4727 basis for job control.
4729 To facilitate the implementation of the user interface to job
4730 control, the system maintains the notion of a current terminal
4731 process group @sc{ID}. Members of this process group (processes whose
4732 process group @sc{ID} is equal to the current terminal process group
4733 @sc{ID}) receive keyboard-generated signals such as @code{SIGINT}.
4734 These processes are said to be in the foreground. Background
4735 processes are those whose process group @sc{ID} differs from the
4736 terminal's; such processes are immune to keyboard-generated
4737 signals. Only foreground processes are allowed to read from or
4738 write to the terminal. Background processes which attempt to
4739 read from (write to) the terminal are sent a @code{SIGTTIN}
4740 (@code{SIGTTOU}) signal by the terminal driver, which, unless
4741 caught, suspends the process.
4743 If the operating system on which Bash is running supports
4744 job control, Bash allows you to use it. Typing the
4745 @var{suspend} character (typically @samp{^Z}, Control-Z) while a
4746 process is running causes that process to be stopped and returns
4747 you to Bash. Typing the @var{delayed suspend} character
4748 (typically @samp{^Y}, Control-Y) causes the process to be stopped
4749 when it attempts to read input from the terminal, and control to
4750 be returned to Bash. You may then manipulate the state of
4751 this job, using the @code{bg} command to continue it in the
4752 background, the @code{fg} command to continue it in the
4753 foreground, or the @code{kill} command to kill it. A @samp{^Z}
4754 takes effect immediately, and has the additional side effect of
4755 causing pending output and typeahead to be discarded.
4757 There are a number of ways to refer to a job in the shell. The
4758 character @samp{%} introduces a job name. Job number @code{n}
4759 may be referred to as @samp{%n}. A job may also be referred to
4760 using a prefix of the name used to start it, or using a substring
4761 that appears in its command line. For example, @samp{%ce} refers
4762 to a stopped @code{ce} job. Using @samp{%?ce}, on the
4763 other hand, refers to any job containing the string @samp{ce} in
4764 its command line. If the prefix or substring matches more than one job,
4765 Bash reports an error. The symbols @samp{%%} and
4766 @samp{%+} refer to the shell's notion of the current job, which
4767 is the last job stopped while it was in the foreground. The
4768 previous job may be referenced using @samp{%-}. In output
4769 pertaining to jobs (e.g., the output of the @code{jobs} command),
4770 the current job is always flagged with a @samp{+}, and the
4771 previous job with a @samp{-}.
4773 Simply naming a job can be used to bring it into the foreground:
4774 @samp{%1} is a synonym for @samp{fg %1}, bringing job 1 from the
4775 background into the foreground. Similarly, @samp{%1 &} resumes
4776 job 1 in the background, equivalent to @samp{bg %1}
4778 The shell learns immediately whenever a job changes state.
4779 Normally, Bash waits until it is about to print a prompt
4780 before reporting changes in a job's status so as to not interrupt
4781 any other output. If the
4782 the @samp{-b} option to the @code{set} builtin is set,
4783 Bash reports such changes immediately (@pxref{The Set Builtin}).
4785 If you attempt to exit Bash while jobs are stopped, the
4786 shell prints a message warning you that you have stopped jobs.
4787 You may then use the
4788 @code{jobs} command to inspect their status. If you do this, or
4789 try to exit again immediately, you are not warned again, and the
4790 stopped jobs are terminated.
4792 @node Job Control Builtins
4793 @section Job Control Builtins
4802 Place @var{jobspec} into the background, as if it had been started
4803 with @samp{&}. If @var{jobspec} is not supplied, the current job
4811 Bring @var{jobspec} into the foreground and make it the current job.
4812 If @var{jobspec} is not supplied, the current job is used.
4817 jobs [-lpnrs] [@var{jobspec}]
4818 jobs -x @var{command} [@var{jobspec}]
4821 The first form lists the active jobs. The options have the
4826 List process @sc{ID}s in addition to the normal information
4829 Display information only about jobs that have changed status since
4830 you were last notified of their status.
4833 List only the process @sc{ID} of the job's process group
4837 Restrict output to running jobs.
4840 Restrict output to stopped jobs.
4843 If @var{jobspec} is given,
4844 output is restricted to information about that job.
4845 If @var{jobspec} is not supplied, the status of all jobs is
4848 If the @samp{-x} option is supplied, @code{jobs} replaces any
4849 @var{jobspec} found in @var{command} or @var{arguments} with the
4850 corresponding process group @sc{ID}, and executes @var{command},
4851 passing it @var{argument}s, returning its exit status.
4856 kill [-s @var{sigspec}] [-n @var{signum}] [-@var{sigspec}] @var{jobspec}
4857 kill -l [@var{sigspec}]
4859 Send a signal specified by @var{sigspec} or @var{signum} to the process
4860 named by @var{jobspec}.
4861 @var{sigspec} is either a signal name such as @code{SIGINT} (with or without
4862 the @code{SIG} prefix) or a signal number; @var{signum} is a signal number.
4863 If @var{sigspec} and @var{signum} are not present, @code{SIGTERM} is used.
4864 The @samp{-l} option lists the signal names, or the signal name
4865 corresponding to @var{sigspec}.
4870 wait [@var{jobspec}|@var{pid}]
4872 Wait until the child process specified by process @sc{ID} @var{pid} or job
4873 specification @var{jobspec} exits and report its exit status. If a job
4874 spec is given, all processes in the job are waited for. If no arguments
4875 are given, all currently active child processes are waited for.
4880 disown [-h] [@var{jobspec} @dots{}]
4882 Without options, each @var{jobspec} is removed from the table of
4884 If the @samp{-h} option is given, the job is not removed from the table,
4885 but is marked so that @code{SIGHUP} is not sent to the job if the shell
4886 receives a @code{SIGHUP}.
4887 If @var{jobspec} is not present, the current job is used.
4894 Suspend the execution of this shell until it receives a
4895 @code{SIGCONT} signal. The @samp{-f} option means to suspend
4896 even if the shell is a login shell.
4900 When job control is not active, the @code{kill} and @code{wait}
4901 builtins do not accept @var{jobspec} arguments. They must be
4902 supplied process @sc{ID}s.
4904 @node Job Control Variables
4905 @section Job Control Variables
4910 This variable controls how the shell interacts with the user and
4911 job control. If this variable exists then single word simple
4912 commands without redirects are treated as candidates for resumption
4913 of an existing job. There is no ambiguity allowed; if there is
4914 more than one job beginning with the string typed, then
4915 the most recently accessed job will be selected.
4916 The name of a stopped job, in this context, is the command line
4917 used to start it. If this variable is set to the value @samp{exact},
4918 the string supplied must match the name of a stopped job exactly;
4919 if set to @samp{substring},
4920 the string supplied needs to match a substring of the name of a
4921 stopped job. The @samp{substring} value provides functionality
4922 analogous to the @samp{%?} job @sc{ID} (@pxref{Job Control Basics}).
4923 If set to any other value, the supplied string must
4924 be a prefix of a stopped job's name; this provides functionality
4925 analogous to the @samp{%} job @sc{ID}.
4929 @set readline-appendix
4930 @set history-appendix
4931 @cindex History, how to use
4932 @include hsuser.texinfo
4933 @cindex Readline, how to use
4934 @include rluser.texinfo
4935 @clear readline-appendix
4936 @clear history-appendix
4938 @node Installing Bash
4939 @chapter Installing Bash
4941 This chapter provides basic instructions for installing Bash on
4942 the various supported platforms. The distribution supports nearly every
4943 version of Unix (and, someday, @sc{GNU}). Other independent ports exist for
4944 @sc{OS/2}, Windows 95, and Windows @sc{NT}.
4947 * Basic Installation:: Installation instructions.
4949 * Compilers and Options:: How to set special options for various
4952 * Compiling For Multiple Architectures:: How to compile Bash for more
4953 than one kind of system from
4954 the same source tree.
4956 * Installation Names:: How to set the various paths used by the installation.
4958 * Specifying the System Type:: How to configure Bash for a particular system.
4960 * Sharing Defaults:: How to share default configuration values among GNU
4963 * Operation Controls:: Options recognized by the configuration program.
4965 * Optional Features:: How to enable and disable optional features when
4969 @node Basic Installation
4970 @section Basic Installation
4971 @cindex installation
4972 @cindex configuration
4973 @cindex Bash installation
4974 @cindex Bash configuration
4976 These are installation instructions for Bash.
4978 The @code{configure} shell script attempts to guess correct
4979 values for various system-dependent variables used during
4980 compilation. It uses those values to create a @file{Makefile} in
4981 each directory of the package (the top directory, the
4982 @file{builtins} and @file{doc} directories, and the
4983 each directory under @file{lib}). It also creates a
4984 @file{config.h} file containing system-dependent definitions.
4985 Finally, it creates a shell script named @code{config.status} that you
4986 can run in the future to recreate the current configuration, a
4987 file @file{config.cache} that saves the results of its tests to
4988 speed up reconfiguring, and a file @file{config.log} containing
4989 compiler output (useful mainly for debugging @code{configure}).
4991 @file{config.cache} contains results you don't want to keep, you
4992 may remove or edit it.
4994 If you need to do unusual things to compile the package, please
4995 try to figure out how @code{configure} could check whether or not
4996 to do them, and mail diffs or instructions to
4997 @code{bash-maintainers@@prep.ai.mit.edu} so they can be
4998 considered for the next release.
5000 The file @file{configure.in} is used to create @code{configure}
5001 by a program called Autoconf. You only need
5002 @file{configure.in} if you want to change it or regenerate
5003 @code{configure} using a newer version of Autoconf. If
5004 you do this, make sure you are using Autoconf version 2.10 or
5007 If you need to change @file{configure.in} or regenerate
5008 @code{configure}, you will need to create two files:
5009 @file{_distribution} and @file{_patchlevel}. @file{_distribution}
5010 should contain the major and minor version numbers of the Bash
5011 distribution, for example @samp{2.01}. @file{_patchlevel} should
5012 contain the patch level of the Bash distribution, @samp{0} for
5013 example. The script @file{support/mkconffiles} has been provided
5014 to automate the creation of these files.
5016 The simplest way to compile Bash is:
5020 @code{cd} to the directory containing the source code and type
5021 @samp{./configure} to configure Bash for your system. If you're
5022 using @code{csh} on an old version of System V, you might need to
5023 type @samp{sh ./configure} instead to prevent @code{csh} from trying
5024 to execute @code{configure} itself.
5026 Running @code{configure} takes awhile. While running, it prints some
5027 messages telling which features it is checking for.
5030 Type @samp{make} to compile Bash and build the @code{bashbug} bug
5034 Optionally, type @samp{make tests} to run the Bash test suite.
5037 Type @samp{make install} to install @code{bash} and @code{bashbug}.
5038 This will also install the manual pages and Info file.
5042 You can remove the program binaries and object files from the
5043 source code directory by typing @samp{make clean}. To also remove the
5044 files that @code{configure} created (so you can compile Bash for
5045 a different kind of computer), type @samp{make distclean}.
5047 @node Compilers and Options
5048 @section Compilers and Options
5050 Some systems require unusual options for compilation or linking
5051 that the @code{configure} script does not know about. You can
5052 give @code{configure} initial values for variables by setting
5053 them in the environment. Using a Bourne-compatible shell, you
5054 can do that on the command line like this:
5057 CC=c89 CFLAGS=-O2 LIBS=-lposix ./configure
5060 On systems that have the @code{env} program, you can do it like this:
5063 env CPPFLAGS=-I/usr/local/include LDFLAGS=-s ./configure
5066 The configuration process uses GCC to build Bash if it
5069 @node Compiling For Multiple Architectures
5070 @section Compiling For Multiple Architectures
5072 You can compile Bash for more than one kind of computer at the
5073 same time, by placing the object files for each architecture in their
5074 own directory. To do this, you must use a version of @code{make} that
5075 supports the @code{VPATH} variable, such as GNU @code{make}.
5077 directory where you want the object files and executables to go and run
5078 the @code{configure} script from the source directory. You may need to
5079 supply the @samp{--srcdir=PATH} argument to tell @code{configure} where the
5080 source files are. @code{configure} automatically checks for the
5081 source code in the directory that @code{configure} is in and in `..'.
5083 If you have to use a @code{make} that does not supports the @code{VPATH}
5084 variable, you can compile Bash for one architecture at a
5085 time in the source code directory. After you have installed
5086 Bash for one architecture, use @samp{make distclean} before
5087 reconfiguring for another architecture.
5089 Alternatively, if your system supports symbolic links, you can use the
5090 @file{support/mkclone} script to create a build tree which has
5091 symbolic links back to each file in the source directory. Here's an
5092 example that creates a build directory in the current directory from a
5093 source directory @file{/usr/gnu/src/bash-2.0}:
5096 bash /usr/gnu/src/bash-2.0/support/mkclone -s /usr/gnu/src/bash-2.0 .
5100 The @code{mkclone} script requires Bash, so you must have already built
5101 Bash for at least one architecture before you can create build
5102 directories for other architectures.
5104 @node Installation Names
5105 @section Installation Names
5107 By default, @samp{make install} will install into
5108 @file{/usr/local/bin}, @file{/usr/local/man}, etc. You can
5109 specify an installation prefix other than @file{/usr/local} by
5110 giving @code{configure} the option @samp{--prefix=PATH}.
5112 You can specify separate installation prefixes for
5113 architecture-specific files and architecture-independent files.
5114 If you give @code{configure} the option
5115 @samp{--exec-prefix=PATH}, the package will use @samp{PATH} as the
5116 prefix for installing programs and libraries. Documentation and
5117 other data files will still use the regular prefix.
5119 @node Specifying the System Type
5120 @section Specifying the System Type
5122 There may be some features @code{configure} can not figure out
5123 automatically, but needs to determine by the type of host the
5124 package will run on. Usually @code{configure} can figure that
5125 out, but if it prints a message saying it can not guess the host
5126 type, give it the @samp{--host=TYPE} option. @samp{TYPE} can
5127 either be a short name for the system type, such as @samp{sun4},
5128 or a canonical name with three fields: @samp{CPU-COMPANY-SYSTEM}
5129 (e.g., @samp{sparc-sun-sunos4.1.2}).
5131 @noindent See the file @file{support/config.sub} for the possible
5132 values of each field.
5134 @node Sharing Defaults
5135 @section Sharing Defaults
5137 If you want to set default values for @code{configure} scripts to
5138 share, you can create a site shell script called
5139 @code{config.site} that gives default values for variables like
5140 @code{CC}, @code{cache_file}, and @code{prefix}. @code{configure}
5141 looks for @file{PREFIX/share/config.site} if it exists, then
5142 @file{PREFIX/etc/config.site} if it exists. Or, you can set the
5143 @code{CONFIG_SITE} environment variable to the location of the site
5144 script. A warning: the Bash @code{configure} looks for a site script,
5145 but not all @code{configure} scripts do.
5147 @node Operation Controls
5148 @section Operation Controls
5150 @code{configure} recognizes the following options to control how it
5155 @item --cache-file=@var{FILE}
5156 Use and save the results of the tests in
5157 @var{FILE} instead of @file{./config.cache}. Set @var{FILE} to
5158 @file{/dev/null} to disable caching, for debugging
5162 Print a summary of the options to @code{configure}, and exit.
5167 Do not print messages saying which checks are being made.
5169 @item --srcdir=@var{DIR}
5170 Look for the Bash source code in directory @var{DIR}. Usually
5171 @code{configure} can determine that directory automatically.
5174 Print the version of Autoconf used to generate the @code{configure}
5178 @code{configure} also accepts some other, not widely used, boilerplate
5181 @node Optional Features
5182 @section Optional Features
5184 The Bash @code{configure} has a number of @samp{--enable-@var{FEATURE}}
5185 options, where @var{FEATURE} indicates an optional part of the
5186 package. There are also several @samp{--with-@var{PACKAGE}} options,
5187 where @var{PACKAGE} is something like @samp{gnu-malloc} or
5188 @samp{purify} (for the Purify memory allocation checker). To
5189 turn off the default use of a package, use
5190 @samp{--without-@var{PACKAGE}}. To configure Bash without a feature
5191 that is enabled by default, use @samp{--disable-@var{FEATURE}}.
5193 Here is a complete list of the @samp{--enable-} and
5194 @samp{--with-} options that the Bash @code{configure} recognizes.
5198 Define if you are using the Andrew File System from Transarc.
5201 Use the curses library instead of the termcap library. This should
5202 be supplied if your system has an inadequate or incomplete termcap
5205 @item --with-glibc-malloc
5206 Use the @sc{GNU} libc version of @code{malloc} in
5207 @file{lib/malloc/gmalloc.c}. This is somewhat slower than the
5208 default @code{malloc}, but wastes considerably less space.
5210 @item --with-gnu-malloc
5211 Use the @sc{GNU} version of
5212 @code{malloc} in @file{lib/malloc/malloc.c}. This is not the same
5213 @code{malloc} that appears in @sc{GNU} libc, but an older version
5214 derived from the 4.2 @sc{BSD} @code{malloc}. This @code{malloc} is
5215 very fast, but wastes a lot of space. This option is enabled by
5216 default. The @file{NOTES} file contains a list of systems for
5217 which this should be turned off, and @code{configure} disables this
5218 option automatically for a number of systems.
5221 Define this to use the Purify memory allocation checker from Pure
5224 @item --enable-minimal-config
5225 This produces a shell with minimal features, close to the historical
5230 The @samp{minimal-config} option can be used to disable all of
5231 the following options, but it is processed first, so individual
5232 options may be enabled using @samp{enable-@var{FEATURE}}.
5234 All of the following options except for @samp{disabled-builtins} and
5235 @samp{usg-echo-default} are
5236 enabled by default, unless the operating system does not provide the
5240 @item --enable-alias
5241 Allow alias expansion and include the @code{alias} and @code{unalias}
5244 @item --enable-array-variables
5245 Include support for one-dimensional array shell variables.
5247 @item --enable-bang-history
5248 Include support for @code{csh}-like history substitution.
5250 @item --enable-brace-expansion
5251 Include @code{csh}-like brace expansion
5252 ( @code{b@{a,b@}c} @expansion{} @code{bac bbc} ).
5254 @item --enable-command-timing
5255 Include support for recognizing @code{time} as a reserved word and for
5256 displaying timing statistics for the pipeline following @code{time}. This
5257 allows pipelines as well as shell builtins and functions to be timed.
5259 @item --enable-directory-stack
5260 Include support for a @code{csh}-like directory stack and the
5261 @code{pushd}, @code{popd}, and @code{dirs} builtins.
5263 @item --enable-disabled-builtins
5264 Allow builtin commands to be invoked via @samp{builtin xxx}
5265 even after @code{xxx} has been disabled using @samp{enable -n xxx}.
5266 See @ref{Bash Builtins}, for details of the @code{builtin} and
5267 @code{enable} builtin commands.
5269 @item --enable-dparen-arithmetic
5270 Include support for the @code{ksh} @code{((@dots{}))} command.
5272 @item --enable-help-builtin
5273 Include the @code{help} builtin, which displays help on shell builtins and
5276 @item --enable-history
5277 Include command history and the @code{fc} and @code{history}
5280 @item --enable-job-control
5281 This enables job control features, if the @sc{OS} supports them.
5283 @item --enable-process-substitution
5284 This enables process substitution (@pxref{Process Substitution}) if
5285 the @sc{OS} provides the necessary support.
5287 @item --enable-prompt-string-decoding
5288 Turn on the interpretation of a number of backslash-escaped characters
5289 in the @code{$PS1}, @code{$PS2}, @code{$PS3}, and @code{$PS4} prompt
5292 @item --enable-readline
5293 Include support for command-line editing and history with the Bash
5294 version of the Readline library.
5296 @item --enable-restricted
5297 Include support for a @dfn{restricted shell}. If this is enabled, Bash,
5298 when called as @code{rbash}, enters a restricted mode. See
5299 @ref{The Restricted Shell}, for a description of restricted mode.
5301 @item --enable-select
5302 Include the @code{ksh} @code{select} builtin, which allows the
5303 generation of simple menus.
5305 @item --enable-usg-echo-default
5306 Make the @code{echo} builtin expand backslash-escaped characters by default,
5307 without requiring the @samp{-e} option. This makes the Bash @code{echo}
5308 behave more like the System V version.
5312 The file @file{config.h.top} contains C Preprocessor
5313 @samp{#define} statements for options which are not settable from
5315 Some of these are not meant to be changed; beware of the consequences if
5317 Read the comments associated with each definition for more
5318 information about its effect.
5320 @node Reporting Bugs
5321 @appendix Reporting Bugs
5323 Please report all bugs you find in Bash.
5324 But first, you should
5325 make sure that it really is a bug, and that it appears in the latest
5326 version of Bash that you have.
5328 Once you have determined that a bug actually exists, use the
5329 @code{bashbug} command to submit a bug report.
5330 If you have a fix, you are encouraged to mail that as well!
5331 Suggestions and `philosophical' bug reports may be mailed
5332 to @code{bug-bash@@prep.ai.MIT.Edu} or posted to the Usenet
5333 newsgroup @code{gnu.bash.bug}.
5335 All bug reports should include:
5338 The version number of Bash.
5340 The hardware and operating system.
5342 The compiler used to compile Bash.
5344 A description of the bug behaviour.
5346 A short script or `recipe' which exercises the bug and may be used
5351 @code{bashbug} inserts the first three items automatically into
5352 the template it provides for filing a bug report.
5354 Please send all reports concerning this manual to
5355 @code{chet@@ins.CWRU.Edu}.
5358 @appendix Index of Shell Builtin Commands
5361 @node Reserved Word Index
5362 @appendix Shell Reserved Words
5365 @node Variable Index
5366 @appendix Parameter and Variable Index
5369 @node Function Index
5370 @appendix Function Index
5374 @appendix Concept Index