]> git.ipfire.org Git - thirdparty/bash.git/blob - doc/bashref.texi
Imported from ../bash-2.05.tar.gz.
[thirdparty/bash.git] / doc / bashref.texi
1 \input texinfo.tex @c -*- texinfo -*-
2 @c %**start of header
3 @setfilename bashref.info
4 @settitle Bash Reference Manual
5 @c %**end of header
6
7 @ignore
8 Last Change: Wed Mar 28 14:48:38 EST 2001
9 @end ignore
10
11 @set EDITION 2.5
12 @set VERSION 2.05
13 @set UPDATED 28 Mar 2001
14 @set UPDATE-MONTH Mar 2001
15
16 @iftex
17 @finalout
18 @end iftex
19
20 @setchapternewpage odd
21 @defcodeindex bt
22 @defcodeindex rw
23 @set BashFeatures
24
25 @ifinfo
26 @dircategory Utilities
27 @direntry
28 * Bash: (bash). The GNU Bourne-Again SHell.
29 @end direntry
30
31 @format
32 This text is a brief description of the features that are present in
33 the Bash shell.
34
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}.
38
39 Copyright (C) 1991-1999 Free Software Foundation, Inc.
40
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.
44
45 @ignore
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).
50
51 @end ignore
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.
56
57 Permission is granted to copy and distribute translations of this manual
58 into another language, under the above conditions for modified versions,
59 except that this permission notice may be stated in a translation approved
60 by the Free Software Foundation.
61 @end format
62 @end ifinfo
63
64 @titlepage
65 @title Bash Reference Manual
66 @subtitle Reference Documentation for Bash
67 @subtitle Edition @value{EDITION}, for @code{Bash} Version @value{VERSION}.
68 @subtitle @value{UPDATE-MONTH}
69 @author Chet Ramey, Case Western Reserve University
70 @author Brian Fox, Free Software Foundation
71 @page
72 @vskip 0pt plus 1filll
73 Copyright @copyright{} 1991-1999 Free Software Foundation, Inc.
74
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.
78
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.
83
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.
88 @end titlepage
89
90 @ifinfo
91 @node Top, Introduction, (dir), (dir)
92 @top Bash Features
93 @end ifinfo
94
95 @ifinfo
96 This text is a brief description of the features that are present in
97 the Bash shell.
98
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}.
102
103 Copyright (C) 1991, 1993, 1996 Free Software Foundation, Inc.
104
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
111 feature.
112
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.
116
117 @menu
118 * Introduction:: An introduction to the shell.
119
120 * Definitions:: Some definitions used in the rest of this
121 manual.
122
123 * Basic Shell Features:: The shell "building blocks".
124
125 * Shell Builtin Commands:: Commands that are a part of the shell.
126
127 * Shell Variables:: Variables used or set by Bash.
128
129 * Bash Features:: Features found only in Bash.
130
131 * Job Control:: A chapter describing what job control is
132 and how Bash allows you to use it.
133
134 * Using History Interactively:: Chapter dealing with history expansion
135 rules.
136
137 * Command Line Editing:: Chapter describing the command line
138 editing features.
139
140 * Installing Bash:: How to build and install Bash on your system.
141
142 * Reporting Bugs:: How to report bugs in Bash.
143
144 * Major Differences From The Bourne Shell:: A terse list of the differences
145 between Bash and historical
146 versions of /bin/sh.
147
148 * Builtin Index:: Index of Bash builtin commands.
149
150 * Reserved Word Index:: Index of Bash reserved words.
151
152 * Variable Index:: Quick reference helps you find the
153 variable you want.
154
155 * Function Index:: Index of bindable Readline functions.
156
157 * Concept Index:: General index for concepts described in
158 this manual.
159 @end menu
160 @end ifinfo
161
162 @node Introduction
163 @chapter Introduction
164 @menu
165 * What is Bash?:: A short description of Bash.
166
167 * What is a shell?:: A brief introduction to shells.
168 @end menu
169
170 @node What is Bash?
171 @section What is Bash?
172
173 Bash is the shell, or command language interpreter,
174 for the @sc{gnu} operating system.
175 The name is an acronym for the @samp{Bourne-Again SHell},
176 a pun on Stephen Bourne, the author of the direct ancestor of
177 the current Unix shell @code{/bin/sh},
178 which appeared in the Seventh Edition Bell Labs Research version
179 of Unix.
180
181 Bash is largely compatible with @code{sh} and incorporates useful
182 features from the Korn shell @code{ksh} and the C shell @code{csh}.
183 It is intended to be a conformant implementation of the @sc{ieee}
184 @sc{posix} Shell and Tools specification (@sc{ieee} Working Group 1003.2).
185 It offers functional improvements over @code{sh} for both interactive and
186 programming use.
187
188 While the @sc{gnu} operating system provides other shells, including
189 a version of @code{csh}, Bash is the default shell.
190 Like other @sc{gnu} software, Bash is quite portable. It currently runs
191 on nearly every version of Unix and a few other operating systems @minus{}
192 independently-supported ports exist for @sc{ms-dos}, @sc{os/2},
193 Windows @sc{95/98}, and Windows @sc{nt}.
194
195 @node What is a shell?
196 @section What is a shell?
197
198 At its base, a shell is simply a macro processor that executes
199 commands. A Unix shell is both a command interpreter, which
200 provides the user interface to the rich set of @sc{gnu} utilities,
201 and a programming language, allowing these utilitites to be
202 combined. Files containing commands can be created, and become
203 commands themselves. These new commands have the same status as
204 system commands in directories such as @file{/bin}, allowing users
205 or groups to establish custom environments.
206
207 A shell allows execution of @sc{gnu} commands, both synchronously and
208 asynchronously.
209 The shell waits for synchronous commands to complete before accepting
210 more input; asynchronous commands continue to execute in parallel
211 with the shell while it reads and executes additional commands.
212 The @dfn{redirection} constructs permit
213 fine-grained control of the input and output of those commands.
214 Moreover, the shell allows control over the contents of commands'
215 environments.
216 Shells may be used interactively or non-interactively: they accept
217 input typed from the keyboard or from a file.
218
219 Shells also provide a small set of built-in
220 commands (@dfn{builtins}) implementing functionality impossible
221 or inconvenient to obtain via separate utilities.
222 For example, @code{cd}, @code{break}, @code{continue}, and
223 @code{exec}) cannot be implemented outside of the shell because
224 they directly manipulate the shell itself.
225 The @code{history}, @code{getopts}, @code{kill}, or @code{pwd}
226 builtins, among others, could be implemented in separate utilities,
227 but they are more convenient to use as builtin commands.
228 All of the shell builtins are described in
229 subsequent sections.
230
231 While executing commands is essential, most of the power (and
232 complexity) of shells is due to their embedded programming
233 languages. Like any high-level language, the shell provides
234 variables, flow control constructs, quoting, and functions.
235
236 Shells offer features geared specifically for
237 interactive use rather than to augment the programming language.
238 These interactive features include job control, command line
239 editing, history and aliases. Each of these features is
240 described in this manual.
241
242 @node Definitions
243 @chapter Definitions
244 These definitions are used throughout the remainder of this manual.
245
246 @table @code
247
248 @item POSIX
249 @cindex POSIX
250 A family of open system standards based on Unix. Bash
251 is concerned with @sc{posix} 1003.2, the Shell and Tools Standard.
252
253 @item blank
254 A space or tab character.
255
256 @item builtin
257 @cindex builtin
258 A command that is implemented internally by the shell itself, rather
259 than by an executable program somewhere in the file system.
260
261 @item control operator
262 @cindex control operator
263 A @code{word} that performs a control function. It is a @code{newline}
264 or one of the following:
265 @samp{||}, @samp{&&}, @samp{&}, @samp{;}, @samp{;;},
266 @samp{|}, @samp{(}, or @samp{)}.
267
268 @item exit status
269 @cindex exit status
270 The value returned by a command to its caller.
271
272 @item field
273 @cindex field
274 A unit of text that is the result of one of the shell expansions. After
275 expansion, when executing a command, the resulting fields are used as
276 the command name and arguments.
277
278 @item filename
279 @cindex filename
280 A string of characters used to identify a file.
281
282 @item job
283 @cindex job
284 A set of processes comprising a pipeline, and any processes descended
285 from it, that are all in the same process group.
286
287 @item job control
288 @cindex job control
289 A mechanism by which users can selectively stop (suspend) and restart
290 (resume) execution of processes.
291
292 @item metacharacter
293 @cindex metacharacter
294 A character that, when unquoted, separates words. A metacharacter is
295 a @code{blank} or one of the following characters:
296 @samp{|}, @samp{&}, @samp{;}, @samp{(}, @samp{)}, @samp{<}, or
297 @samp{>}.
298
299 @item name
300 @cindex name
301 @cindex identifier
302 A @code{word} consisting solely of letters, numbers, and underscores,
303 and beginning with a letter or underscore. @code{Name}s are used as
304 shell variable and function names.
305 Also referred to as an @code{identifier}.
306
307 @item operator
308 @cindex operator, shell
309 A @code{control operator} or a @code{redirection operator}.
310 @xref{Redirections}, for a list of redirection operators.
311
312 @item process group
313 @cindex process group
314 A collection of related processes each having the same process
315 group @sc{id}.
316
317 @item process group ID
318 @cindex process group ID
319 A unique identifer that represents a @code{process group}
320 during its lifetime.
321
322 @item reserved word
323 @cindex reserved word
324 A @code{word} that has a special meaning to the shell. Most reserved
325 words introduce shell flow control constructs, such as @code{for} and
326 @code{while}.
327
328 @item return status
329 @cindex return status
330 A synonym for @code{exit status}.
331
332 @item signal
333 @cindex signal
334 A mechanism by which a process may be notified by the kernel
335 of an event occurring in the system.
336
337 @item special builtin
338 @cindex special builtin
339 A shell builtin command that has been classified as special by the
340 @sc{posix} 1003.2 standard.
341
342 @item token
343 @cindex token
344 A sequence of characters considered a single unit by the shell. It is
345 either a @code{word} or an @code{operator}.
346
347 @item word
348 @cindex word
349 A @code{token} that is not an @code{operator}.
350 @end table
351
352 @node Basic Shell Features
353 @chapter Basic Shell Features
354 @cindex Bourne shell
355
356 Bash is an acronym for @samp{Bourne-Again SHell}.
357 The Bourne shell is
358 the traditional Unix shell originally written by Stephen Bourne.
359 All of the Bourne shell builtin commands are available in Bash,
360 and the rules for evaluation and quoting are taken from the @sc{posix}
361 1003.2 specification for the `standard' Unix shell.
362
363 This chapter briefly summarizes the shell's `building blocks':
364 commands, control structures, shell functions, shell @i{parameters},
365 shell expansions,
366 @i{redirections}, which are a way to direct input and output from
367 and to named files, and how the shell executes commands.
368
369 @menu
370 * Shell Syntax:: What your input means to the shell.
371 * Shell Commands:: The types of commands you can use.
372 * Shell Functions:: Grouping commands by name.
373 * Shell Parameters:: Special shell variables.
374 * Shell Expansions:: How Bash expands variables and the various
375 expansions available.
376 * Redirections:: A way to control where input and output go.
377 * Executing Commands:: What happens when you run a command.
378 * Shell Scripts:: Executing files of shell commands.
379 @end menu
380
381 @node Shell Syntax
382 @section Shell Syntax
383 @menu
384 * Shell Operation:: The basic operation of the shell.
385
386 * Quoting:: How to remove the special meaning from characters.
387
388 * Comments:: How to specify comments.
389 @end menu
390
391 When the shell reads input, it proceeds through a
392 sequence of operations. If the input indicates the beginning of a
393 comment, the shell ignores the comment symbol (@samp{#}), and the rest
394 of that line.
395
396 Otherwise, roughly speaking, the shell reads its input and
397 divides the input into words and operators, employing the quoting rules
398 to select which meanings to assign various words and characters.
399
400 The shell then parses these tokens into commands and other constructs,
401 removes the special meaning of certain words or characters, expands
402 others, redirects input and output as needed, executes the specified
403 command, waits for the command's exit status, and makes that exit status
404 available for further inspection or processing.
405
406 @node Shell Operation
407 @subsection Shell Operation
408
409 The following is a brief description of the shell's operation when it
410 reads and executes a command. Basically, the shell does the
411 following:
412
413 @enumerate
414 @item
415 Reads its input from a file (@pxref{Shell Scripts}), from a string
416 supplied as an argument to the @option{-c} invocation option
417 (@pxref{Invoking Bash}), or from the user's terminal.
418
419 @item
420 Breaks the input into words and operators, obeying the quoting rules
421 described in @ref{Quoting}. These tokens are separated by
422 @code{metacharacters}. Alias expansion is performed by this step
423 (@pxref{Aliases}).
424
425 @item
426 Parses the tokens into simple and compound commands
427 (@pxref{Shell Commands}).
428
429 @item
430 Performs the various shell expansions (@pxref{Shell Expansions}), breaking
431 the expanded tokens into lists of filenames (@pxref{Filename Expansion})
432 and commands and arguments.
433
434 @item
435 Performs any necessary redirections (@pxref{Redirections}) and removes
436 the redirection operators and their operands from the argument list.
437
438 @item
439 Executes the command (@pxref{Executing Commands}).
440
441 @item
442 Optionally waits for the command to complete and collects its exit
443 status (@pxref{Exit Status}).
444
445 @end enumerate
446
447 @node Quoting
448 @subsection Quoting
449 @cindex quoting
450 @menu
451 * Escape Character:: How to remove the special meaning from a single
452 character.
453 * Single Quotes:: How to inhibit all interpretation of a sequence
454 of characters.
455 * Double Quotes:: How to suppress most of the interpretation of a
456 sequence of characters.
457 * ANSI-C Quoting:: How to expand ANSI-C sequences in quoted strings.
458
459 * Locale Translation:: How to translate strings into different languages.
460 @end menu
461
462 Quoting is used to remove the special meaning of certain
463 characters or words to the shell. Quoting can be used to
464 disable special treatment for special characters, to prevent
465 reserved words from being recognized as such, and to prevent
466 parameter expansion.
467
468 Each of the shell metacharacters (@pxref{Definitions})
469 has special meaning to the shell and must be quoted if it is to
470 represent itself.
471 When the command history expansion facilities are being used, the
472 @var{history expansion} character, usually @samp{!}, must be quoted
473 to prevent history expansion. @xref{Bash History Facilities}, for
474 more details concerning history expansion.
475 There are three quoting mechanisms: the
476 @var{escape character}, single quotes, and double quotes.
477
478 @node Escape Character
479 @subsubsection Escape Character
480 A non-quoted backslash @samp{\} is the Bash escape character.
481 It preserves the literal value of the next character that follows,
482 with the exception of @code{newline}. If a @code{\newline} pair
483 appears, and the backslash itself is not quoted, the @code{\newline}
484 is treated as a line continuation (that is, it is removed from
485 the input stream and effectively ignored).
486
487 @node Single Quotes
488 @subsubsection Single Quotes
489
490 Enclosing characters in single quotes (@samp{'}) preserves the literal value
491 of each character within the quotes. A single quote may not occur
492 between single quotes, even when preceded by a backslash.
493
494 @node Double Quotes
495 @subsubsection Double Quotes
496
497 Enclosing characters in double quotes (@samp{"}) preserves the literal value
498 of all characters within the quotes, with the exception of
499 @samp{$}, @samp{`}, and @samp{\}.
500 The characters @samp{$} and @samp{`}
501 retain their special meaning within double quotes (@pxref{Shell Expansions}).
502 The backslash retains its special meaning only when followed by one of
503 the following characters:
504 @samp{$}, @samp{`}, @samp{"}, @samp{\}, or @code{newline}.
505 Within double quotes, backslashes that are followed by one of these
506 characters are removed. Backslashes preceding characters without a
507 special meaning are left unmodified.
508 A double quote may be quoted within double quotes by preceding it with
509 a backslash.
510
511 The special parameters @samp{*} and @samp{@@} have special meaning
512 when in double quotes (@pxref{Shell Parameter Expansion}).
513
514 @node ANSI-C Quoting
515 @subsubsection ANSI-C Quoting
516 @cindex quoting, ANSI
517
518 Words of the form @code{$'@var{string}'} are treated specially. The
519 word expands to @var{string}, with backslash-escaped characters replaced
520 as specified by the ANSI C standard. Backslash escape sequences, if
521 present, are decoded as follows:
522
523 @table @code
524 @item \a
525 alert (bell)
526 @item \b
527 backspace
528 @item \e
529 an escape character (not ANSI C)
530 @item \f
531 form feed
532 @item \n
533 newline
534 @item \r
535 carriage return
536 @item \t
537 horizontal tab
538 @item \v
539 vertical tab
540 @item \\
541 backslash
542 @item \'
543 single quote
544 @item \@var{nnn}
545 the character whose @code{ASCII} code is the octal value @var{nnn}
546 (one to three digits)
547 @item \x@var{nnn}
548 the character whose @code{ASCII} code is the hexadecimal value @var{nnn}
549 (one to three digits)
550 @end table
551
552 @noindent
553 The expanded result is single-quoted, as if the dollar sign had not
554 been present.
555
556 @node Locale Translation
557 @subsubsection Locale-Specific Translation
558 @cindex localization
559
560 A double-quoted string preceded by a dollar sign (@samp{$}) will cause
561 the string to be translated according to the current locale.
562 If the current locale is @code{C} or @code{POSIX}, the dollar sign
563 is ignored.
564 If the string is translated and replaced, the replacement is
565 double-quoted.
566
567 Some systems use the message catalog selected by the @env{LC_MESSAGES}
568 shell variable. Others create the name of the message catalog from the
569 value of the @env{TEXTDOMAIN} shell variable, possibly adding a
570 suffix of @samp{.mo}. If you use the @env{TEXTDOMAIN} variable, you
571 may need to set the @env{TEXTDOMAINDIR} variable to the location of
572 the message catalog files.
573
574 @node Comments
575 @subsection Comments
576 @cindex comments, shell
577
578 In a non-interactive shell, or an interactive shell in which the
579 @code{interactive_comments} option to the @code{shopt}
580 builtin is enabled (@pxref{Bash Builtins}),
581 a word beginning with @samp{#}
582 causes that word and all remaining characters on that line to
583 be ignored. An interactive shell without the @code{interactive_comments}
584 option enabled does not allow comments. The @code{interactive_comments}
585 option is on by default in interactive shells.
586 @xref{Interactive Shells}, for a description of what makes
587 a shell interactive.
588
589 @node Shell Commands
590 @section Shell Commands
591 @cindex commands, shell
592
593 A simple shell command such as @code{echo a b c} consists of the command
594 itself followed by arguments, separated by spaces.
595
596 More complex shell commands are composed of simple commands arranged together
597 in a variety of ways: in a pipeline in which the output of one command
598 becomes the input of a second, in a loop or conditional construct, or in
599 some other grouping.
600
601 @menu
602 * Simple Commands:: The most common type of command.
603 * Pipelines:: Connecting the input and output of several
604 commands.
605 * Lists:: How to execute commands sequentially.
606 * Looping Constructs:: Shell commands for iterative action.
607 * Conditional Constructs:: Shell commands for conditional execution.
608 * Command Grouping:: Ways to group commands.
609 @end menu
610
611 @node Simple Commands
612 @subsection Simple Commands
613 @cindex commands, simple
614
615 A simple command is the kind of command encountered most often.
616 It's just a sequence of words separated by @code{blank}s, terminated
617 by one of the shell's control operators (@pxref{Definitions}). The
618 first word generally specifies a command to be executed, with the
619 rest of the words being that command's arguments.
620
621 The return status (@pxref{Exit Status}) of a simple command is
622 its exit status as provided
623 by the @sc{posix} 1003.1 @code{waitpid} function, or 128+@var{n} if
624 the command was terminated by signal @var{n}.
625
626 @node Pipelines
627 @subsection Pipelines
628 @cindex pipeline
629 @cindex commands, pipelines
630
631 A @code{pipeline} is a sequence of simple commands separated by
632 @samp{|}.
633
634 @rwindex time
635 @rwindex !
636 @cindex command timing
637 The format for a pipeline is
638 @example
639 [@code{time} [@code{-p}]] [@code{!}] @var{command1} [@code{|} @var{command2} @dots{}]
640 @end example
641
642 @noindent
643 The output of each command in the pipeline is connected to the input of
644 the next command. That is, each command reads the previous command's
645 output.
646
647 The reserved word @code{time} causes timing statistics
648 to be printed for the pipeline once it finishes.
649 The statistics currently consist of elapsed (wall-clock) time and
650 user and system time consumed by the command's execution.
651 The @option{-p} option changes the output format to that specified
652 by @sc{posix}.
653 The @env{TIMEFORMAT} variable may be set to a format string that
654 specifies how the timing information should be displayed.
655 @xref{Bash Variables}, for a description of the available formats.
656 The use of @code{time} as a reserved word permits the timing of
657 shell builtins, shell functions, and pipelines. An external
658 @code{time} command cannot time these easily.
659
660 If the pipeline is not executed asynchronously (@pxref{Lists}), the
661 shell waits for all commands in the pipeline to complete.
662
663 Each command in a pipeline is executed in its own subshell
664 (@pxref{Command Execution Environment}). The exit
665 status of a pipeline is the exit status of the last command in the
666 pipeline. If the reserved word @samp{!} precedes the pipeline, the
667 exit status is the logical negation of the exit status of the last command.
668
669 @node Lists
670 @subsection Lists of Commands
671 @cindex commands, lists
672
673 A @code{list} is a sequence of one or more pipelines separated by one
674 of the operators @samp{;}, @samp{&}, @samp{&&}, or @samp{||},
675 and optionally terminated by one of @samp{;}, @samp{&}, or a
676 @code{newline}.
677
678 Of these list operators, @samp{&&} and @samp{||}
679 have equal precedence, followed by @samp{;} and @samp{&},
680 which have equal precedence.
681
682 If a command is terminated by the control operator @samp{&},
683 the shell executes the command asynchronously in a subshell.
684 This is known as executing the command in the @var{background}.
685 The shell does not wait for the command to finish, and the return
686 status is 0 (true).
687 When job control is not active (@pxref{Job Control}),
688 the standard input for asynchronous commands, in the absence of any
689 explicit redirections, is redirected from @code{/dev/null}.
690
691 Commands separated by a @samp{;} are executed sequentially; the shell
692 waits for each command to terminate in turn. The return status is the
693 exit status of the last command executed.
694
695 The control operators @samp{&&} and @samp{||}
696 denote @sc{and} lists and @sc{or} lists, respectively.
697 An @sc{and} list has the form
698 @example
699 @var{command1} && @var{command2}
700 @end example
701
702 @noindent
703 @var{command2} is executed if, and only if, @var{command1}
704 returns an exit status of zero.
705
706 An @sc{or} list has the form
707 @example
708 @var{command1} || @var{command2}
709 @end example
710
711 @noindent
712 @var{command2} is executed if, and only if, @var{command1}
713 returns a non-zero exit status.
714
715 The return status of
716 @sc{and} and @sc{or} lists is the exit status of the last command
717 executed in the list.
718
719 @node Looping Constructs
720 @subsection Looping Constructs
721 @cindex commands, looping
722
723 Bash supports the following looping constructs.
724
725 Note that wherever a @samp{;} appears in the description of a
726 command's syntax, it may be replaced with one or more newlines.
727
728 @table @code
729 @item until
730 @rwindex until
731 @rwindex do
732 @rwindex done
733 The syntax of the @code{until} command is:
734 @example
735 until @var{test-commands}; do @var{consequent-commands}; done
736 @end example
737 Execute @var{consequent-commands} as long as
738 @var{test-commands} has an exit status which is not zero.
739 The return status is the exit status of the last command executed
740 in @var{consequent-commands}, or zero if none was executed.
741
742 @item while
743 @rwindex while
744 The syntax of the @code{while} command is:
745 @example
746 while @var{test-commands}; do @var{consequent-commands}; done
747 @end example
748
749 Execute @var{consequent-commands} as long as
750 @var{test-commands} has an exit status of zero.
751 The return status is the exit status of the last command executed
752 in @var{consequent-commands}, or zero if none was executed.
753
754 @item for
755 @rwindex for
756 The syntax of the @code{for} command is:
757
758 @example
759 for @var{name} [in @var{words} @dots{}]; do @var{commands}; done
760 @end example
761 Expand @var{words}, and execute @var{commands} once for each member
762 in the resultant list, with @var{name} bound to the current member.
763 If @samp{in @var{words}} is not present, the @code{for} command
764 executes the @var{commands} once for each positional parameter that is
765 set, as if @samp{in "$@@"} had been specified
766 (@pxref{Special Parameters}).
767 The return status is the exit status of the last command that executes.
768 If there are no items in the expansion of @var{words}, no commands are
769 executed, and the return status is zero.
770
771 An alternate form of the @code{for} command is also supported:
772
773 @example
774 for (( @var{expr1} ; @var{expr2} ; @var{expr3} )) ; do @var{commands} ; done
775 @end example
776 First, the arithmetic expression @var{expr1} is evaluated according
777 to the rules described below (@pxref{Shell Arithmetic}).
778 The arithmetic expression @var{expr2} is then evaluated repeatedly
779 until it evaluates to zero.
780 Each time @var{expr2} evaluates to a non-zero value, @var{commands} are
781 executed and the arithmetic expression @var{expr3} is evaluated.
782 If any expression is omitted, it behaves as if it evaluates to 1.
783 The return value is the exit status of the last command in @var{list}
784 that is executed, or false if any of the expressions is invalid.
785
786 @end table
787
788 The @code{break} and @code{continue} builtins (@pxref{Bourne Shell Builtins})
789 may be used to control loop execution.
790
791 @node Conditional Constructs
792 @subsection Conditional Constructs
793 @cindex commands, conditional
794
795 @table @code
796 @item if
797 @rwindex if
798 @rwindex then
799 @rwindex else
800 @rwindex elif
801 @rwindex fi
802 The syntax of the @code{if} command is:
803
804 @example
805 if @var{test-commands}; then
806 @var{consequent-commands};
807 [elif @var{more-test-commands}; then
808 @var{more-consequents};]
809 [else @var{alternate-consequents};]
810 fi
811 @end example
812
813 The @var{test-commands} list is executed, and if its return status is zero,
814 the @var{consequent-commands} list is executed.
815 If @var{test-commands} returns a non-zero status, each @code{elif} list
816 is executed in turn, and if its exit status is zero,
817 the corresponding @var{more-consequents} is executed and the
818 command completes.
819 If @samp{else @var{alternate-consequents}} is present, and
820 the final command in the final @code{if} or @code{elif} clause
821 has a non-zero exit status, then @var{alternate-consequents} is executed.
822 The return status is the exit status of the last command executed, or
823 zero if no condition tested true.
824
825 @item case
826 @rwindex case
827 @rwindex in
828 @rwindex esac
829 The syntax of the @code{case} command is:
830
831 @example
832 @code{case @var{word} in [ [(] @var{pattern} [| @var{pattern}]@dots{}) @var{command-list} ;;]@dots{} esac}
833 @end example
834
835 @code{case} will selectively execute the @var{command-list} corresponding to
836 the first @var{pattern} that matches @var{word}.
837 The @samp{|} is used to separate multiple patterns, and the @samp{)}
838 operator terminates a pattern list.
839 A list of patterns and an associated command-list is known
840 as a @var{clause}. Each clause must be terminated with @samp{;;}.
841 The @var{word} undergoes tilde expansion, parameter expansion, command
842 substitution, arithmetic expansion, and quote removal before matching is
843 attempted. Each @var{pattern} undergoes tilde expansion, parameter
844 expansion, command substitution, and arithmetic expansion.
845
846 There may be an arbitrary number of @code{case} clauses, each terminated
847 by a @samp{;;}. The first pattern that matches determines the
848 command-list that is executed.
849
850 Here is an example using @code{case} in a script that could be used to
851 describe one interesting feature of an animal:
852
853 @example
854 echo -n "Enter the name of an animal: "
855 read ANIMAL
856 echo -n "The $ANIMAL has "
857 case $ANIMAL in
858 horse | dog | cat) echo -n "four";;
859 man | kangaroo ) echo -n "two";;
860 *) echo -n "an unknown number of";;
861 esac
862 echo " legs."
863 @end example
864
865 @noindent
866 The return status is zero if no @var{pattern} is matched. Otherwise, the
867 return status is the exit status of the @var{command-list} executed.
868
869 @item select
870 @rwindex select
871
872 The @code{select} construct allows the easy generation of menus.
873 It has almost the same syntax as the @code{for} command:
874
875 @example
876 select @var{name} [in @var{words} @dots{}]; do @var{commands}; done
877 @end example
878
879 The list of words following @code{in} is expanded, generating a list
880 of items. The set of expanded words is printed on the standard
881 error output stream, each preceded by a number. If the
882 @samp{in @var{words}} is omitted, the positional parameters are printed,
883 as if @samp{in "$@@"} had been specifed.
884 The @env{PS3} prompt is then displayed and a line is read from the
885 standard input.
886 If the line consists of a number corresponding to one of the displayed
887 words, then the value of @var{name} is set to that word.
888 If the line is empty, the words and prompt are displayed again.
889 If @code{EOF} is read, the @code{select} command completes.
890 Any other value read causes @var{name} to be set to null.
891 The line read is saved in the variable @env{REPLY}.
892
893 The @var{commands} are executed after each selection until a
894 @code{break} or @code{return} command is executed, at which
895 point the @code{select} command completes.
896
897 Here is an example that allows the user to pick a filename from the
898 current directory, and displays the name and index of the file
899 selected.
900
901 @example
902 select fname in *;
903 do
904 echo you picked $fname \($REPLY\)
905 break;
906 done
907 @end example
908
909 @item ((@dots{}))
910 @example
911 (( @var{expression} ))
912 @end example
913
914 The arithmetic @var{expression} is evaluated according to the rules
915 described below (@pxref{Shell Arithmetic}).
916 If the value of the expression is non-zero, the return status is 0;
917 otherwise the return status is 1. This is exactly equivalent to
918 @example
919 let "@var{expression}"
920 @end example
921 @noindent
922 @xref{Bash Builtins}, for a full description of the @code{let} builtin.
923
924 @item [[@dots{}]]
925 @rwindex [[
926 @rwindex ]]
927 @example
928 [[ @var{expression} ]]
929 @end example
930
931 Return a status of 0 or 1 depending on the evaluation of
932 the conditional expression @var{expression}.
933 Expressions are composed of the primaries described below in
934 @ref{Bash Conditional Expressions}.
935 Word splitting and filename expansion are not performed on the words
936 between the @samp{[[} and @samp{]]}; tilde expansion, parameter and
937 variable expansion, arithmetic expansion, command substitution, process
938 substitution, and quote removal are performed.
939
940 When the @samp{==} and @samp{!=} operators are used, the string to the
941 right of the operator is considered a pattern and matched according
942 to the rules described below in @ref{Pattern Matching}.
943 The return value is 0 if the string matches or does not match
944 the pattern, respectively, and 1 otherwise.
945 Any part of the pattern may be quoted to force it to be matched as a
946 string.
947
948 Expressions may be combined using the following operators, listed
949 in decreasing order of precedence:
950
951 @table @code
952 @item ( @var{expression} )
953 Returns the value of @var{expression}.
954 This may be used to override the normal precedence of operators.
955
956 @item ! @var{expression}
957 True if @var{expression} is false.
958
959 @item @var{expression1} && @var{expression2}
960 True if both @var{expression1} and @var{expression2} are true.
961
962 @item @var{expression1} || @var{expression2}
963 True if either @var{expression1} or @var{expression2} is true.
964 @end table
965 @noindent
966 The @code{&&} and @code{||} commands do not execute @var{expression2} if the
967 value of @var{expression1} is sufficient to determine the return
968 value of the entire conditional expression.
969
970 @end table
971
972 @node Command Grouping
973 @subsection Grouping Commands
974 @cindex commands, grouping
975
976 Bash provides two ways to group a list of commands to be executed
977 as a unit. When commands are grouped, redirections may be applied
978 to the entire command list. For example, the output of all the
979 commands in the list may be redirected to a single stream.
980
981 @table @code
982 @item ()
983 @example
984 ( @var{list} )
985 @end example
986
987 Placing a list of commands between parentheses causes a subshell
988 to be created, and each of the commands in @var{list} to be executed
989 in that subshell. Since the @var{list} is executed in a subshell,
990 variable assignments do not remain in effect after the subshell completes.
991
992 @item @{@}
993 @rwindex @{
994 @rwindex @}
995 @example
996 @{ @var{list}; @}
997 @end example
998
999 Placing a list of commands between curly braces causes the list to
1000 be executed in the current shell context. No subshell is created.
1001 The semicolon (or newline) following @var{list} is required.
1002 @end table
1003
1004 In addition to the creation of a subshell, there is a subtle difference
1005 between these two constructs due to historical reasons. The braces
1006 are @code{reserved words}, so they must be separated from the @var{list}
1007 by @code{blank}s. The parentheses are @code{operators}, and are
1008 recognized as separate tokens by the shell even if they are not separated
1009 from the @var{list} by whitespace.
1010
1011 The exit status of both of these constructs is the exit status of
1012 @var{list}.
1013
1014 @node Shell Functions
1015 @section Shell Functions
1016 @cindex shell function
1017 @cindex functions, shell
1018
1019 Shell functions are a way to group commands for later execution
1020 using a single name for the group. They are executed just like
1021 a "regular" command.
1022 When the name of a shell function is used as a simple command name,
1023 the list of commands associated with that function name is executed.
1024 Shell functions are executed in the current
1025 shell context; no new process is created to interpret them.
1026
1027 Functions are declared using this syntax:
1028 @rwindex function
1029 @example
1030 [ @code{function} ] @var{name} () @{ @var{command-list}; @}
1031 @end example
1032
1033 This defines a shell function named @var{name}. The reserved
1034 word @code{function} is optional.
1035 If the @code{function} reserved
1036 word is supplied, the parentheses are optional.
1037 The @var{body} of the function is the @var{command-list} between @{ and @}.
1038 This list is executed whenever @var{name} is specified as the
1039 name of a command. The exit status of a function is
1040 the exit status of the last command executed in the body.
1041
1042 Note that for historical reasons, the curly braces that surround
1043 the body of the function must be separated from the body by
1044 @code{blank}s or newlines.
1045 This is because the braces are reserved words and are only recognized
1046 as such when they are separated by whitespace.
1047 Also, the @var{command-list} must be terminated with a semicolon
1048 or a newline.
1049
1050 When a function is executed, the arguments to the
1051 function become the positional parameters
1052 during its execution (@pxref{Positional Parameters}).
1053 The special parameter @samp{#} that expands to the number of
1054 positional parameters is updated to reflect the change.
1055 Positional parameter @code{0} is unchanged.
1056 The @env{FUNCNAME} variable is set to the name of the function
1057 while the function is executing.
1058
1059 If the builtin command @code{return}
1060 is executed in a function, the function completes and
1061 execution resumes with the next command after the function
1062 call. When a function completes, the values of the
1063 positional parameters and the special parameter @samp{#}
1064 are restored to the values they had prior to the function's
1065 execution. If a numeric argument is given to @code{return},
1066 that is the function's return status; otherwise the functions's
1067 return status is the exit status of the last command executed
1068 before the @code{return}.
1069
1070 Variables local to the function may be declared with the
1071 @code{local} builtin. These variables are visible only to
1072 the function and the commands it invokes.
1073
1074 Functions may be recursive. No limit is placed on the number of
1075 recursive calls.
1076
1077 @node Shell Parameters
1078 @section Shell Parameters
1079 @cindex parameters
1080 @cindex variable, shell
1081 @cindex shell variable
1082
1083 @menu
1084 * Positional Parameters:: The shell's command-line arguments.
1085 * Special Parameters:: Parameters with special meanings.
1086 @end menu
1087
1088 A @var{parameter} is an entity that stores values.
1089 It can be a @code{name}, a number, or one of the special characters
1090 listed below.
1091 For the shell's purposes, a @var{variable} is a parameter denoted by a
1092 @code{name}.
1093
1094 A parameter is set if it has been assigned a value. The null string is
1095 a valid value. Once a variable is set, it may be unset only by using
1096 the @code{unset} builtin command.
1097
1098 A variable may be assigned to by a statement of the form
1099 @example
1100 @var{name}=[@var{value}]
1101 @end example
1102 @noindent
1103 If @var{value}
1104 is not given, the variable is assigned the null string. All
1105 @var{value}s undergo tilde expansion, parameter and variable expansion,
1106 command substitution, arithmetic expansion, and quote
1107 removal (detailed below). If the variable has its @code{integer}
1108 attribute set (see the description of the @code{declare} builtin in
1109 @ref{Bash Builtins}), then @var{value}
1110 is subject to arithmetic expansion even if the @code{$((@dots{}))}
1111 expansion is not used (@pxref{Arithmetic Expansion}).
1112 Word splitting is not performed, with the exception
1113 of @code{"$@@"} as explained below.
1114 Filename expansion is not performed.
1115
1116 @node Positional Parameters
1117 @subsection Positional Parameters
1118 @cindex parameters, positional
1119
1120 A @var{positional parameter} is a parameter denoted by one or more
1121 digits, other than the single digit @code{0}. Positional parameters are
1122 assigned from the shell's arguments when it is invoked,
1123 and may be reassigned using the @code{set} builtin command.
1124 Positional parameter @code{N} may be referenced as @code{$@{N@}}, or
1125 as @code{$N} when @code{N} consists of a single digit.
1126 Positional parameters may not be assigned to with assignment statements.
1127 The @code{set} and @code{shift} builtins are used to set and
1128 unset them (@pxref{Shell Builtin Commands}).
1129 The positional parameters are
1130 temporarily replaced when a shell function is executed
1131 (@pxref{Shell Functions}).
1132
1133 When a positional parameter consisting of more than a single
1134 digit is expanded, it must be enclosed in braces.
1135
1136 @node Special Parameters
1137 @subsection Special Parameters
1138 @cindex parameters, special
1139
1140 The shell treats several parameters specially. These parameters may
1141 only be referenced; assignment to them is not allowed.
1142
1143 @vtable @code
1144
1145 @item *
1146 Expands to the positional parameters, starting from one. When the
1147 expansion occurs within double quotes, it expands to a single word
1148 with the value of each parameter separated by the first character
1149 of the @env{IFS}
1150 special variable. That is, @code{"$*"} is equivalent
1151 to @code{"$1@var{c}$2@var{c}@dots{}"}, where @var{c}
1152 is the first character of the value of the @code{IFS}
1153 variable.
1154 If @env{IFS} is unset, the parameters are separated by spaces.
1155 If @env{IFS} is null, the parameters are joined without intervening
1156 separators.
1157
1158
1159 @item @@
1160 Expands to the positional parameters, starting from one. When the
1161 expansion occurs within double quotes, each parameter expands to a
1162 separate word. That is, @code{"$@@"} is equivalent to
1163 @code{"$1" "$2" @dots{}}.
1164 When there are no positional parameters, @code{"$@@"} and
1165 @code{$@@}
1166 expand to nothing (i.e., they are removed).
1167
1168 @item #
1169 Expands to the number of positional parameters in decimal.
1170
1171 @item ?
1172 Expands to the exit status of the most recently executed foreground
1173 pipeline.
1174
1175 @item -
1176 (A hyphen.) Expands to the current option flags as specified upon
1177 invocation, by the @code{set}
1178 builtin command, or those set by the shell itself
1179 (such as the @option{-i} option).
1180
1181 @item $
1182 Expands to the process @sc{id} of the shell. In a @code{()} subshell, it
1183 expands to the process @sc{id} of the invoking shell, not the subshell.
1184
1185 @item !
1186 Expands to the process @sc{id} of the most recently executed background
1187 (asynchronous) command.
1188
1189 @item 0
1190 Expands to the name of the shell or shell script. This is set at
1191 shell initialization. If Bash is invoked with a file of commands
1192 (@pxref{Shell Scripts}), @code{$0} is set to the name of that file.
1193 If Bash is started with the @option{-c} option (@pxref{Invoking Bash}),
1194 then @code{$0} is set to the first argument after the string to be
1195 executed, if one is present. Otherwise, it is set
1196 to the filename used to invoke Bash, as given by argument zero.
1197
1198 @item _
1199 (An underscore.)
1200 At shell startup, set to the absolute filename of the shell or shell
1201 script being executed as passed in the argument list.
1202 Subsequently, expands to the last argument to the previous command,
1203 after expansion.
1204 Also set to the full pathname of each command executed and placed in
1205 the environment exported to that command.
1206 When checking mail, this parameter holds the name of the mail file.
1207 @end vtable
1208
1209 @node Shell Expansions
1210 @section Shell Expansions
1211 @cindex expansion
1212
1213 Expansion is performed on the command line after it has been split into
1214 @code{token}s. There are seven kinds of expansion performed:
1215 @itemize @bullet
1216 @item brace expansion
1217 @item tilde expansion
1218 @item parameter and variable expansion
1219 @item command substitution
1220 @item arithmetic expansion
1221 @item word splitting
1222 @item filename expansion
1223 @end itemize
1224
1225 @menu
1226 * Brace Expansion:: Expansion of expressions within braces.
1227 * Tilde Expansion:: Expansion of the ~ character.
1228 * Shell Parameter Expansion:: How Bash expands variables to their values.
1229 * Command Substitution:: Using the output of a command as an argument.
1230 * Arithmetic Expansion:: How to use arithmetic in shell expansions.
1231 * Process Substitution:: A way to write and read to and from a
1232 command.
1233 * Word Splitting:: How the results of expansion are split into separate
1234 arguments.
1235 * Filename Expansion:: A shorthand for specifying filenames matching patterns.
1236 * Quote Removal:: How and when quote characters are removed from
1237 words.
1238 @end menu
1239
1240 The order of expansions is: brace expansion, tilde expansion,
1241 parameter, variable, and arithmetic expansion and
1242 command substitution
1243 (done in a left-to-right fashion), word splitting, and filename
1244 expansion.
1245
1246 On systems that can support it, there is an additional expansion
1247 available: @var{process substitution}. This is performed at the
1248 same time as parameter, variable, and arithmetic expansion and
1249 command substitution.
1250
1251 Only brace expansion, word splitting, and filename expansion
1252 can change the number of words of the expansion; other expansions
1253 expand a single word to a single word.
1254 The only exceptions to this are the expansions of
1255 @code{"$@@"} (@pxref{Special Parameters}) and @code{"$@{@var{name}[@@]@}"}
1256 (@pxref{Arrays}).
1257
1258 After all expansions, @code{quote removal} (@pxref{Quote Removal})
1259 is performed.
1260
1261 @node Brace Expansion
1262 @subsection Brace Expansion
1263 @cindex brace expansion
1264 @cindex expansion, brace
1265
1266 Brace expansion is a mechanism by which arbitrary strings may be generated.
1267 This mechanism is similar to
1268 @var{filename expansion} (@pxref{Filename Expansion}),
1269 but the file names generated need not exist.
1270 Patterns to be brace expanded take the form of an optional @var{preamble},
1271 followed by a series of comma-separated strings between a pair of braces,
1272 followed by an optional @var{postscript}.
1273 The preamble is prefixed to each string contained within the braces, and
1274 the postscript is then appended to each resulting string, expanding left
1275 to right.
1276
1277 Brace expansions may be nested.
1278 The results of each expanded string are not sorted; left to right order
1279 is preserved.
1280 For example,
1281 @example
1282 bash$ echo a@{d,c,b@}e
1283 ade ace abe
1284 @end example
1285
1286 Brace expansion is performed before any other expansions,
1287 and any characters special to other expansions are preserved
1288 in the result. It is strictly textual. Bash
1289 does not apply any syntactic interpretation to the context of the
1290 expansion or the text between the braces.
1291 To avoid conflicts with parameter expansion, the string @samp{$@{}
1292 is not considered eligible for brace expansion.
1293
1294 A correctly-formed brace expansion must contain unquoted opening
1295 and closing braces, and at least one unquoted comma.
1296 Any incorrectly formed brace expansion is left unchanged.
1297
1298 This construct is typically used as shorthand when the common
1299 prefix of the strings to be generated is longer than in the
1300 above example:
1301 @example
1302 mkdir /usr/local/src/bash/@{old,new,dist,bugs@}
1303 @end example
1304 or
1305 @example
1306 chown root /usr/@{ucb/@{ex,edit@},lib/@{ex?.?*,how_ex@}@}
1307 @end example
1308
1309 @node Tilde Expansion
1310 @subsection Tilde Expansion
1311 @cindex tilde expansion
1312 @cindex expansion, tilde
1313
1314 If a word begins with an unquoted tilde character (@samp{~}), all of the
1315 characters up to the first unquoted slash (or all characters,
1316 if there is no unquoted slash) are considered a @var{tilde-prefix}.
1317 If none of the characters in the tilde-prefix are quoted, the
1318 characters in the tilde-prefix following the tilde are treated as a
1319 possible @var{login name}.
1320 If this login name is the null string, the tilde is replaced with the
1321 value of the @env{HOME} shell variable.
1322 If @env{HOME} is unset, the home directory of the user executing the
1323 shell is substituted instead.
1324 Otherwise, the tilde-prefix is replaced with the home directory
1325 associated with the specified login name.
1326
1327 If the tilde-prefix is @samp{~+}, the value of
1328 the shell variable @env{PWD} replaces the tilde-prefix.
1329 If the tilde-prefix is @samp{~-}, the value of the shell variable
1330 @env{OLDPWD}, if it is set, is substituted.
1331
1332 If the characters following the tilde in the tilde-prefix consist of a
1333 number @var{N}, optionally prefixed by a @samp{+} or a @samp{-},
1334 the tilde-prefix is replaced with the
1335 corresponding element from the directory stack, as it would be displayed
1336 by the @code{dirs} builtin invoked with the characters following tilde
1337 in the tilde-prefix as an argument (@pxref{The Directory Stack}).
1338 If the tilde-prefix, sans the tilde, consists of a number without a
1339 leading @samp{+} or @samp{-}, @samp{+} is assumed.
1340
1341 If the login name is invalid, or the tilde expansion fails, the word is
1342 left unchanged.
1343
1344 Each variable assignment is checked for unquoted tilde-prefixes immediately
1345 following a @samp{:} or @samp{=}.
1346 In these cases, tilde expansion is also performed.
1347 Consequently, one may use file names with tildes in assignments to
1348 @env{PATH}, @env{MAILPATH}, and @env{CDPATH},
1349 and the shell assigns the expanded value.
1350
1351 The following table shows how Bash treats unquoted tilde-prefixes:
1352
1353 @table @code
1354 @item ~
1355 The value of @code{$HOME}
1356 @item ~/foo
1357 @file{$HOME/foo}
1358
1359 @item ~fred/foo
1360 The subdirectory @code{foo} of the home directory of the user
1361 @code{fred}
1362
1363 @item ~+/foo
1364 @file{$PWD/foo}
1365
1366 @item ~-/foo
1367 @file{$@{OLDPWD-'~-'@}/foo}
1368
1369 @item ~@var{N}
1370 The string that would be displayed by @samp{dirs +@var{N}}
1371
1372 @item ~+@var{N}
1373 The string that would be displayed by @samp{dirs +@var{N}}
1374
1375 @item ~-@var{N}
1376 The string that would be displayed by @samp{dirs -@var{N}}
1377
1378 @end table
1379
1380 @node Shell Parameter Expansion
1381 @subsection Shell Parameter Expansion
1382 @cindex parameter expansion
1383 @cindex expansion, parameter
1384
1385 The @samp{$} character introduces parameter expansion,
1386 command substitution, or arithmetic expansion. The parameter name
1387 or symbol to be expanded may be enclosed in braces, which
1388 are optional but serve to protect the variable to be expanded from
1389 characters immediately following it which could be
1390 interpreted as part of the name.
1391
1392 When braces are used, the matching ending brace is the first @samp{@}}
1393 not escaped by a backslash or within a quoted string, and not within an
1394 embedded arithmetic expansion, command substitution, or parameter
1395 expansion.
1396
1397 The basic form of parameter expansion is $@{@var{parameter}@}.
1398 The value of @var{parameter} is substituted. The braces are required
1399 when @var{parameter}
1400 is a positional parameter with more than one digit,
1401 or when @var{parameter}
1402 is followed by a character that is not to be
1403 interpreted as part of its name.
1404
1405 If the first character of @var{parameter} is an exclamation point,
1406 a level of variable indirection is introduced.
1407 Bash uses the value of the variable formed from the rest of
1408 @var{parameter} as the name of the variable; this variable is then
1409 expanded and that value is used in the rest of the substitution, rather
1410 than the value of @var{parameter} itself.
1411 This is known as @code{indirect expansion}.
1412 The exception to this is the expansion of $@{!@var{prefix*@}}
1413 described below.
1414
1415 In each of the cases below, @var{word} is subject to tilde expansion,
1416 parameter expansion, command substitution, and arithmetic expansion.
1417
1418 When not performing substring expansion, Bash tests for a parameter
1419 that is unset or null; omitting the colon results in a test only for a
1420 parameter that is unset. Put another way, if the colon is included,
1421 the operator tests for both existence and that the value is not null;
1422 if the colon is omitted, the operator tests only for existence.
1423
1424 @table @code
1425
1426 @item $@{@var{parameter}:@minus{}@var{word}@}
1427 If @var{parameter} is unset or null, the expansion of
1428 @var{word} is substituted. Otherwise, the value of
1429 @var{parameter} is substituted.
1430
1431 @item $@{@var{parameter}:=@var{word}@}
1432 If @var{parameter}
1433 is unset or null, the expansion of @var{word}
1434 is assigned to @var{parameter}.
1435 The value of @var{parameter}
1436 is then substituted. Positional parameters and special parameters may
1437 not be assigned to in this way.
1438
1439 @item $@{@var{parameter}:?@var{word}@}
1440 If @var{parameter}
1441 is null or unset, the expansion of @var{word} (or a message
1442 to that effect if @var{word}
1443 is not present) is written to the standard error and the shell, if it
1444 is not interactive, exits. Otherwise, the value of @var{parameter} is
1445 substituted.
1446
1447 @item $@{@var{parameter}:+@var{word}@}
1448 If @var{parameter}
1449 is null or unset, nothing is substituted, otherwise the expansion of
1450 @var{word} is substituted.
1451
1452 @item $@{@var{parameter}:@var{offset}@}
1453 @itemx $@{@var{parameter}:@var{offset}:@var{length}@}
1454 Expands to up to @var{length} characters of @var{parameter}
1455 starting at the character specified by @var{offset}.
1456 If @var{length} is omitted, expands to the substring of
1457 @var{parameter} starting at the character specified by @var{offset}.
1458 @var{length} and @var{offset} are arithmetic expressions
1459 (@pxref{Shell Arithmetic}).
1460 This is referred to as Substring Expansion.
1461
1462 @var{length} must evaluate to a number greater than or equal to zero.
1463 If @var{offset} evaluates to a number less than zero, the value
1464 is used as an offset from the end of the value of @var{parameter}.
1465 If @var{parameter} is @samp{@@}, the result is @var{length} positional
1466 parameters beginning at @var{offset}.
1467 If @var{parameter} is an array name indexed by @samp{@@} or @samp{*},
1468 the result is the @var{length}
1469 members of the array beginning with @code{$@{@var{parameter}[@var{offset}]@}}.
1470 Substring indexing is zero-based unless the positional parameters
1471 are used, in which case the indexing starts at 1.
1472
1473 @item $@{!@var{prefix}*@}
1474 Expands to the names of variables whose names begin with @var{prefix},
1475 separated by the first character of the @env{IFS} special variable.
1476
1477 @item $@{#@var{parameter}@}
1478 The length in characters of the expanded value of @var{parameter} is
1479 substituted.
1480 If @var{parameter} is @samp{*} or @samp{@@}, the value substituted
1481 is the number of positional parameters.
1482 If @var{parameter} is an array name subscripted by @samp{*} or @samp{@@},
1483 the value substituted is the number of elements in the array.
1484
1485 @item $@{@var{parameter}#@var{word}@}
1486 @itemx $@{@var{parameter}##@var{word}@}
1487 The @var{word}
1488 is expanded to produce a pattern just as in filename
1489 expansion (@pxref{Filename Expansion}). If the pattern matches
1490 the beginning of the expanded value of @var{parameter},
1491 then the result of the expansion is the expanded value of @var{parameter}
1492 with the shortest matching pattern (the @samp{#} case) or the
1493 longest matching pattern (the @samp{##} case) deleted.
1494 If @var{parameter} is @samp{@@} or @samp{*},
1495 the pattern removal operation is applied to each positional
1496 parameter in turn, and the expansion is the resultant list.
1497 If @var{parameter} is an array variable subscripted with
1498 @samp{@@} or @samp{*},
1499 the pattern removal operation is applied to each member of the
1500 array in turn, and the expansion is the resultant list.
1501
1502 @item $@{@var{parameter}%@var{word}@}
1503 @itemx $@{@var{parameter}%%@var{word}@}
1504 The @var{word} is expanded to produce a pattern just as in
1505 filename expansion.
1506 If the pattern matches a trailing portion of the expanded value of
1507 @var{parameter}, then the result of the expansion is the value of
1508 @var{parameter} with the shortest matching pattern (the @samp{%} case)
1509 or the longest matching pattern (the @samp{%%} case) deleted.
1510 If @var{parameter} is @samp{@@} or @samp{*},
1511 the pattern removal operation is applied to each positional
1512 parameter in turn, and the expansion is the resultant list.
1513 If @var{parameter}
1514 is an array variable subscripted with @samp{@@} or @samp{*},
1515 the pattern removal operation is applied to each member of the
1516 array in turn, and the expansion is the resultant list.
1517
1518 @item $@{@var{parameter}/@var{pattern}/@var{string}@}
1519 @itemx $@{@var{parameter}//@var{pattern}/@var{string}@}
1520
1521 The @var{pattern} is expanded to produce a pattern just as in
1522 filename expansion.
1523 @var{Parameter} is expanded and the longest match of @var{pattern}
1524 against its value is replaced with @var{string}.
1525 In the first form, only the first match is replaced.
1526 The second form causes all matches of @var{pattern} to be
1527 replaced with @var{string}.
1528 If @var{pattern} begins with @samp{#}, it must match at the beginning
1529 of the expanded value of @var{parameter}.
1530 If @var{pattern} begins with @samp{%}, it must match at the end
1531 of the expanded value of @var{parameter}.
1532 If @var{string} is null, matches of @var{pattern} are deleted
1533 and the @code{/} following @var{pattern} may be omitted.
1534 If @var{parameter} is @samp{@@} or @samp{*},
1535 the substitution operation is applied to each positional
1536 parameter in turn, and the expansion is the resultant list.
1537 If @var{parameter}
1538 is an array variable subscripted with @samp{@@} or @samp{*},
1539 the substitution operation is applied to each member of the
1540 array in turn, and the expansion is the resultant list.
1541
1542 @end table
1543
1544 @node Command Substitution
1545 @subsection Command Substitution
1546 @cindex command substitution
1547
1548 Command substitution allows the output of a command to replace
1549 the command itself.
1550 Command substitution occurs when a command is enclosed as follows:
1551 @example
1552 $(@var{command})
1553 @end example
1554 @noindent
1555 or
1556 @example
1557 `@var{command}`
1558 @end example
1559
1560 @noindent
1561 Bash performs the expansion by executing @var{command} and
1562 replacing the command substitution with the standard output of the
1563 command, with any trailing newlines deleted.
1564 Embedded newlines are not deleted, but they may be removed during
1565 word splitting.
1566 The command substitution @code{$(cat @var{file})} can be
1567 replaced by the equivalent but faster @code{$(< @var{file})}.
1568
1569 When the old-style backquote form of substitution is used,
1570 backslash retains its literal meaning except when followed by
1571 @samp{$}, @samp{`}, or @samp{\}.
1572 The first backquote not preceded by a backslash terminates the
1573 command substitution.
1574 When using the @code{$(@var{command})} form, all characters between
1575 the parentheses make up the command; none are treated specially.
1576
1577 Command substitutions may be nested. To nest when using the backquoted
1578 form, escape the inner backquotes with backslashes.
1579
1580 If the substitution appears within double quotes, word splitting and
1581 filename expansion are not performed on the results.
1582
1583 @node Arithmetic Expansion
1584 @subsection Arithmetic Expansion
1585 @cindex expansion, arithmetic
1586 @cindex arithmetic expansion
1587
1588 Arithmetic expansion allows the evaluation of an arithmetic expression
1589 and the substitution of the result. The format for arithmetic expansion is:
1590
1591 @example
1592 $(( @var{expression} ))
1593 @end example
1594
1595 The expression is treated as if it were within double quotes, but
1596 a double quote inside the parentheses is not treated specially.
1597 All tokens in the expression undergo parameter expansion, command
1598 substitution, and quote removal.
1599 Arithmetic substitutions may be nested.
1600
1601 The evaluation is performed according to the rules listed below
1602 (@pxref{Shell Arithmetic}).
1603 If the expression is invalid, Bash prints a message indicating
1604 failure to the standard error and no substitution occurs.
1605
1606 @node Process Substitution
1607 @subsection Process Substitution
1608 @cindex process substitution
1609
1610 Process substitution is supported on systems that support named
1611 pipes (@sc{fifo}s) or the @file{/dev/fd} method of naming open files.
1612 It takes the form of
1613 @example
1614 <(@var{list})
1615 @end example
1616 @noindent
1617 or
1618 @example
1619 >(@var{list})
1620 @end example
1621 @noindent
1622 The process @var{list} is run with its input or output connected to a
1623 @sc{fifo} or some file in @file{/dev/fd}. The name of this file is
1624 passed as an argument to the current command as the result of the
1625 expansion. If the @code{>(@var{list})} form is used, writing to
1626 the file will provide input for @var{list}. If the
1627 @code{<(@var{list})} form is used, the file passed as an
1628 argument should be read to obtain the output of @var{list}.
1629 Note that no space may appear between the @code{<} or @code{>}
1630 and the left parenthesis, otherwise the construct would be interpreted
1631 as a redirection.
1632
1633 When available, process substitution is performed simultaneously with
1634 parameter and variable expansion, command substitution, and arithmetic
1635 expansion.
1636
1637 @node Word Splitting
1638 @subsection Word Splitting
1639 @cindex word splitting
1640
1641 The shell scans the results of parameter expansion, command substitution,
1642 and arithmetic expansion that did not occur within double quotes for
1643 word splitting.
1644
1645 The shell treats each character of @env{$IFS}
1646 as a delimiter, and splits the results of the other
1647 expansions into words on these characters. If
1648 @env{IFS} is unset, or its value is exactly @code{<space><tab><newline>},
1649 the default, then any sequence of @env{IFS}
1650 characters serves to delimit words. If @env{IFS}
1651 has a value other than the default, then sequences of
1652 the whitespace characters @code{space} and @code{tab}
1653 are ignored at the beginning and end of the
1654 word, as long as the whitespace character is in the
1655 value of @env{IFS} (an @env{IFS} whitespace character).
1656 Any character in @env{IFS} that is not @env{IFS}
1657 whitespace, along with any adjacent @env{IFS}
1658 whitespace characters, delimits a field. A sequence of @env{IFS}
1659 whitespace characters is also treated as a delimiter.
1660 If the value of @env{IFS} is null, no word splitting occurs.
1661
1662 Explicit null arguments (@code{""} or @code{''}) are retained.
1663 Unquoted implicit null arguments, resulting from the expansion of
1664 parameters that have no values, are removed.
1665 If a parameter with no value is expanded within double quotes, a
1666 null argument results and is retained.
1667
1668 Note that if no expansion occurs, no splitting
1669 is performed.
1670
1671 @node Filename Expansion
1672 @subsection Filename Expansion
1673 @menu
1674 * Pattern Matching:: How the shell matches patterns.
1675 @end menu
1676 @cindex expansion, filename
1677 @cindex expansion, pathname
1678 @cindex filename expansion
1679 @cindex pathname expansion
1680
1681 After word splitting, unless the @option{-f} option has been set
1682 (@pxref{The Set Builtin}), Bash scans each word for the characters
1683 @samp{*}, @samp{?}, and @samp{[}.
1684 If one of these characters appears, then the word is
1685 regarded as a @var{pattern},
1686 and replaced with an alphabetically sorted list of
1687 file names matching the pattern. If no matching file names are found,
1688 and the shell option @code{nullglob} is disabled, the word is left
1689 unchanged.
1690 If the @code{nullglob} option is set, and no matches are found, the word
1691 is removed.
1692 If the shell option @code{nocaseglob} is enabled, the match is performed
1693 without regard to the case of alphabetic characters.
1694
1695 When a pattern is used for filename generation, the character @samp{.}
1696 at the start of a filename or immediately following a slash
1697 must be matched explicitly, unless the shell option @code{dotglob} is set.
1698 When matching a file name, the slash character must always be
1699 matched explicitly.
1700 In other cases, the @samp{.} character is not treated specially.
1701
1702 See the description of @code{shopt} in @ref{Bash Builtins},
1703 for a description of the @code{nocaseglob}, @code{nullglob},
1704 and @code{dotglob} options.
1705
1706 The @env{GLOBIGNORE}
1707 shell variable may be used to restrict the set of filenames matching a
1708 pattern. If @env{GLOBIGNORE}
1709 is set, each matching filename that also matches one of the patterns in
1710 @env{GLOBIGNORE} is removed from the list of matches. The filenames
1711 @file{.} and @file{..}
1712 are always ignored, even when @env{GLOBIGNORE}
1713 is set. However, setting @env{GLOBIGNORE} has the effect of
1714 enabling the @code{dotglob}
1715 shell option, so all other filenames beginning with a
1716 @samp{.} will match.
1717 To get the old behavior of ignoring filenames beginning with a
1718 @samp{.}, make @samp{.*} one of the patterns in @env{GLOBIGNORE}.
1719 The @code{dotglob} option is disabled when @env{GLOBIGNORE}
1720 is unset.
1721
1722 @node Pattern Matching
1723 @subsubsection Pattern Matching
1724 @cindex pattern matching
1725 @cindex matching, pattern
1726
1727 Any character that appears in a pattern, other than the special pattern
1728 characters described below, matches itself. The @sc{nul} character may not
1729 occur in a pattern. The special pattern characters must be quoted if
1730 they are to be matched literally.
1731
1732 The special pattern characters have the following meanings:
1733 @table @code
1734 @item *
1735 Matches any string, including the null string.
1736 @item ?
1737 Matches any single character.
1738 @item [@dots{}]
1739 Matches any one of the enclosed characters. A pair of characters
1740 separated by a hyphen denotes a @var{range expression};
1741 any character that sorts between those two characters, inclusive,
1742 using the current locale's collating sequence and character set,
1743 is matched. If the first character following the
1744 @samp{[} is a @samp{!} or a @samp{^}
1745 then any character not enclosed is matched. A @samp{@minus{}}
1746 may be matched by including it as the first or last character
1747 in the set. A @samp{]} may be matched by including it as the first
1748 character in the set.
1749 The sorting order of characters in range expressions is determined by
1750 the current locale and the value of the @env{LC_COLLATE} shell variable,
1751 if set.
1752
1753 For example, in the default C locale, @samp{[a-dx-z]} is equivalent to
1754 @samp{[abcdxyz]}. Many locales sort characters in dictionary order, and in
1755 these locales @samp{[a-dx-z]} is typically not equivalent to @samp{[abcdxyz]};
1756 it might be equivalent to @samp{[aBbCcDdxXyYz]}, for example. To obtain
1757 the traditional interpretation of ranges in bracket expressions, you can
1758 force the use of the C locale by setting the @env{LC_COLLATE} or
1759 @env{LC_ALL} environment variable to the value @samp{C}.
1760
1761 Within @samp{[} and @samp{]}, @var{character classes} can be specified
1762 using the syntax
1763 @code{[:}@var{class}@code{:]}, where @var{class} is one of the
1764 following classes defined in the @sc{posix} 1003.2 standard:
1765 @example
1766 alnum alpha ascii blank cntrl digit graph lower
1767 print punct space upper xdigit
1768 @end example
1769 @noindent
1770 A character class matches any character belonging to that class.
1771
1772 Within @samp{[} and @samp{]}, an @var{equivalence class} can be
1773 specified using the syntax @code{[=}@var{c}@code{=]}, which
1774 matches all characters with the same collation weight (as defined
1775 by the current locale) as the character @var{c}.
1776
1777 Within @samp{[} and @samp{]}, the syntax @code{[.}@var{symbol}@code{.]}
1778 matches the collating symbol @var{symbol}.
1779 @end table
1780
1781 If the @code{extglob} shell option is enabled using the @code{shopt}
1782 builtin, several extended pattern matching operators are recognized.
1783 In the following description, a @var{pattern-list} is a list of one
1784 or more patterns separated by a @samp{|}.
1785 Composite patterns may be formed using one or more of the following
1786 sub-patterns:
1787
1788 @table @code
1789 @item ?(@var{pattern-list})
1790 Matches zero or one occurrence of the given patterns.
1791
1792 @item *(@var{pattern-list})
1793 Matches zero or more occurrences of the given patterns.
1794
1795 @item +(@var{pattern-list})
1796 Matches one or more occurrences of the given patterns.
1797
1798 @item @@(@var{pattern-list})
1799 Matches exactly one of the given patterns.
1800
1801 @item !(@var{pattern-list})
1802 Matches anything except one of the given patterns.
1803 @end table
1804
1805 @node Quote Removal
1806 @subsection Quote Removal
1807
1808 After the preceding expansions, all unquoted occurrences of the
1809 characters @samp{\}, @samp{'}, and @samp{"} that did not
1810 result from one of the above expansions are removed.
1811
1812 @node Redirections
1813 @section Redirections
1814 @cindex redirection
1815
1816 Before a command is executed, its input and output
1817 may be @var{redirected}
1818 using a special notation interpreted by the shell.
1819 Redirection may also be used to open and close files for the
1820 current shell execution environment. The following redirection
1821 operators may precede or appear anywhere within a
1822 simple command or may follow a command.
1823 Redirections are processed in the order they appear, from
1824 left to right.
1825
1826 In the following descriptions, if the file descriptor number is
1827 omitted, and the first character of the redirection operator is
1828 @samp{<}, the redirection refers to the standard input (file
1829 descriptor 0). If the first character of the redirection operator
1830 is @samp{>}, the redirection refers to the standard output (file
1831 descriptor 1).
1832
1833 The word following the redirection operator in the following
1834 descriptions, unless otherwise noted, is subjected to brace expansion,
1835 tilde expansion, parameter expansion, command substitution, arithmetic
1836 expansion, quote removal, filename expansion, and word splitting.
1837 If it expands to more than one word, Bash reports an error.
1838
1839 Note that the order of redirections is significant. For example,
1840 the command
1841 @example
1842 ls > @var{dirlist} 2>&1
1843 @end example
1844 @noindent
1845 directs both standard output (file descriptor 1) and standard error
1846 (file descriptor 2) to the file @var{dirlist}, while the command
1847 @example
1848 ls 2>&1 > @var{dirlist}
1849 @end example
1850 @noindent
1851 directs only the standard output to file @var{dirlist},
1852 because the standard error was duplicated as standard output
1853 before the standard output was redirected to @var{dirlist}.
1854
1855 Bash handles several filenames specially when they are used in
1856 redirections, as described in the following table:
1857
1858 @table @code
1859 @item /dev/fd/@var{fd}
1860 If @var{fd} is a valid integer, file descriptor @var{fd} is duplicated.
1861
1862 @item /dev/stdin
1863 File descriptor 0 is duplicated.
1864
1865 @item /dev/stdout
1866 File descriptor 1 is duplicated.
1867
1868 @item /dev/stderr
1869 File descriptor 2 is duplicated.
1870
1871 @item /dev/tcp/@var{host}/@var{port}
1872 If @var{host} is a valid hostname or Internet address, and @var{port}
1873 is an integer port number, Bash attempts to open a TCP connection
1874 to the corresponding socket.
1875
1876 @item /dev/udp/@var{host}/@var{port}
1877 If @var{host} is a valid hostname or Internet address, and @var{port}
1878 is an integer port number, Bash attempts to open a UDP connection
1879 to the corresponding socket.
1880
1881 @end table
1882
1883 A failure to open or create a file causes the redirection to fail.
1884
1885 @subsection Redirecting Input
1886 Redirection of input causes the file whose name results from
1887 the expansion of @var{word}
1888 to be opened for reading on file descriptor @code{n},
1889 or the standard input (file descriptor 0) if @code{n}
1890 is not specified.
1891
1892 The general format for redirecting input is:
1893 @example
1894 [n]<@var{word}
1895 @end example
1896
1897 @subsection Redirecting Output
1898 Redirection of output causes the file whose name results from
1899 the expansion of @var{word}
1900 to be opened for writing on file descriptor @code{n},
1901 or the standard output (file descriptor 1) if @code{n}
1902 is not specified. If the file does not exist it is created;
1903 if it does exist it is truncated to zero size.
1904
1905 The general format for redirecting output is:
1906 @example
1907 [n]>[|]@var{word}
1908 @end example
1909
1910 If the redirection operator is @samp{>}, and the @code{noclobber}
1911 option to the @code{set} builtin has been enabled, the redirection
1912 will fail if the file whose name results from the expansion of
1913 @var{word} exists and is a regular file.
1914 If the redirection operator is @samp{>|}, or the redirection operator is
1915 @samp{>} and the @code{noclobber} option is not enabled, the redirection
1916 is attempted even if the file named by @var{word} exists.
1917
1918 @subsection Appending Redirected Output
1919 Redirection of output in this fashion
1920 causes the file whose name results from
1921 the expansion of @var{word}
1922 to be opened for appending on file descriptor @code{n},
1923 or the standard output (file descriptor 1) if @code{n}
1924 is not specified. If the file does not exist it is created.
1925
1926 The general format for appending output is:
1927 @example
1928 [n]>>@var{word}
1929 @end example
1930
1931 @subsection Redirecting Standard Output and Standard Error
1932 Bash allows both the
1933 standard output (file descriptor 1) and
1934 the standard error output (file descriptor 2)
1935 to be redirected to the file whose name is the
1936 expansion of @var{word} with this construct.
1937
1938 There are two formats for redirecting standard output and
1939 standard error:
1940 @example
1941 &>@var{word}
1942 @end example
1943 @noindent
1944 and
1945 @example
1946 >&@var{word}
1947 @end example
1948 @noindent
1949 Of the two forms, the first is preferred.
1950 This is semantically equivalent to
1951 @example
1952 >@var{word} 2>&1
1953 @end example
1954
1955 @subsection Here Documents
1956 This type of redirection instructs the shell to read input from the
1957 current source until a line containing only @var{word}
1958 (with no trailing blanks) is seen. All of
1959 the lines read up to that point are then used as the standard
1960 input for a command.
1961
1962 The format of here-documents is as follows:
1963 @example
1964 <<[@minus{}]@var{word}
1965 @var{here-document}
1966 @var{delimiter}
1967 @end example
1968
1969 No parameter expansion, command substitution, arithmetic expansion,
1970 or filename expansion is performed on
1971 @var{word}. If any characters in @var{word} are quoted, the
1972 @var{delimiter} is the result of quote removal on @var{word},
1973 and the lines in the here-document are not expanded.
1974 If @var{word} is unquoted,
1975 all lines of the here-document are subjected to parameter expansion,
1976 command substitution, and arithmetic expansion. In the latter
1977 case, the character sequence @code{\newline} is ignored, and @samp{\}
1978 must be used to quote the characters
1979 @samp{\}, @samp{$}, and @samp{`}.
1980
1981 If the redirection operator is @samp{<<-},
1982 then all leading tab characters are stripped from input lines and the
1983 line containing @var{delimiter}.
1984 This allows here-documents within shell scripts to be indented in a
1985 natural fashion.
1986
1987 @subsection Duplicating File Descriptors
1988 The redirection operator
1989 @example
1990 [n]<&@var{word}
1991 @end example
1992 @noindent
1993 is used to duplicate input file descriptors.
1994 If @var{word}
1995 expands to one or more digits, the file descriptor denoted by @code{n}
1996 is made to be a copy of that file descriptor.
1997 If the digits in @var{word} do not specify a file descriptor open for
1998 input, a redirection error occurs.
1999 If @var{word}
2000 evaluates to @samp{-}, file descriptor @code{n} is closed. If
2001 @code{n} is not specified, the standard input (file descriptor 0) is used.
2002
2003 The operator
2004 @example
2005 [n]>&@var{word}
2006 @end example
2007 @noindent
2008 is used similarly to duplicate output file descriptors. If
2009 @code{n}
2010 is not specified, the standard output (file descriptor 1) is used.
2011 If the digits in @var{word} do not specify a file descriptor open for
2012 output, a redirection error occurs.
2013 As a special case, if @code{n} is omitted, and @var{word} does not
2014 expand to one or more digits, the standard output and standard
2015 error are redirected as described previously.
2016
2017 @subsection Opening File Descriptors for Reading and Writing
2018 The redirection operator
2019 @example
2020 [n]<>@var{word}
2021 @end example
2022 @noindent
2023 causes the file whose name is the expansion of @var{word}
2024 to be opened for both reading and writing on file descriptor
2025 @code{n}, or on file descriptor 0 if @code{n}
2026 is not specified. If the file does not exist, it is created.
2027
2028 @node Executing Commands
2029 @section Executing Commands
2030
2031 @menu
2032 * Simple Command Expansion:: How Bash expands simple commands before
2033 executing them.
2034
2035 * Command Search and Execution:: How Bash finds commands and runs them.
2036
2037 * Command Execution Environment:: The environment in which Bash
2038 executes commands that are not
2039 shell builtins.
2040
2041 * Environment:: The environment given to a command.
2042
2043 * Exit Status:: The status returned by commands and how Bash
2044 interprets it.
2045
2046 * Signals:: What happens when Bash or a command it runs
2047 receives a signal.
2048
2049 @end menu
2050
2051 @node Simple Command Expansion
2052 @subsection Simple Command Expansion
2053 @cindex command expansion
2054
2055 When a simple command is executed, the shell performs the following
2056 expansions, assignments, and redirections, from left to right.
2057
2058 @enumerate
2059 @item
2060 The words that the parser has marked as variable assignments (those
2061 preceding the command name) and redirections are saved for later
2062 processing.
2063
2064 @item
2065 The words that are not variable assignments or redirections are
2066 expanded (@pxref{Shell Expansions}).
2067 If any words remain after expansion, the first word
2068 is taken to be the name of the command and the remaining words are
2069 the arguments.
2070
2071 @item
2072 Redirections are performed as described above (@pxref{Redirections}).
2073
2074 @item
2075 The text after the @samp{=} in each variable assignment undergoes tilde
2076 expansion, parameter expansion, command substitution, arithmetic expansion,
2077 and quote removal before being assigned to the variable.
2078 @end enumerate
2079
2080 If no command name results, the variable assignments affect the current
2081 shell environment. Otherwise, the variables are added to the environment
2082 of the executed command and do not affect the current shell environment.
2083 If any of the assignments attempts to assign a value to a readonly variable,
2084 an error occurs, and the command exits with a non-zero status.
2085
2086 If no command name results, redirections are performed, but do not
2087 affect the current shell environment. A redirection error causes the
2088 command to exit with a non-zero status.
2089
2090 If there is a command name left after expansion, execution proceeds as
2091 described below. Otherwise, the command exits. If one of the expansions
2092 contained a command substitution, the exit status of the command is
2093 the exit status of the last command substitution performed. If there
2094 were no command substitutions, the command exits with a status of zero.
2095
2096 @node Command Search and Execution
2097 @subsection Command Search and Execution
2098 @cindex command execution
2099 @cindex command search
2100
2101 After a command has been split into words, if it results in a
2102 simple command and an optional list of arguments, the following
2103 actions are taken.
2104
2105 @enumerate
2106 @item
2107 If the command name contains no slashes, the shell attempts to
2108 locate it. If there exists a shell function by that name, that
2109 function is invoked as described in @ref{Shell Functions}.
2110
2111 @item
2112 If the name does not match a function, the shell searches for
2113 it in the list of shell builtins. If a match is found, that
2114 builtin is invoked.
2115
2116 @item
2117 If the name is neither a shell function nor a builtin,
2118 and contains no slashes, Bash searches each element of
2119 @env{$PATH} for a directory containing an executable file
2120 by that name. Bash uses a hash table to remember the full
2121 pathnames of executable files to avoid multiple @env{PATH} searches
2122 (see the description of @code{hash} in @ref{Bourne Shell Builtins}).
2123 A full search of the directories in @env{$PATH}
2124 is performed only if the command is not found in the hash table.
2125 If the search is unsuccessful, the shell prints an error
2126 message and returns an exit status of 127.
2127
2128 @item
2129 If the search is successful, or if the command name contains
2130 one or more slashes, the shell executes the named program in
2131 a separate execution environment.
2132 Argument 0 is set to the name given, and the remaining arguments
2133 to the command are set to the arguments supplied, if any.
2134
2135 @item
2136 If this execution fails because the file is not in executable
2137 format, and the file is not a directory, it is assumed to be a
2138 @var{shell script} and the shell executes it as described in
2139 @ref{Shell Scripts}.
2140
2141 @item
2142 If the command was not begun asynchronously, the shell waits for
2143 the command to complete and collects its exit status.
2144
2145 @end enumerate
2146
2147 @node Command Execution Environment
2148 @subsection Command Execution Environment
2149 @cindex execution environment
2150
2151 The shell has an @var{execution environment}, which consists of the
2152 following:
2153
2154 @itemize @bullet
2155 @item
2156 open files inherited by the shell at invocation, as modified by
2157 redirections supplied to the @code{exec} builtin
2158
2159 @item
2160 the current working directory as set by @code{cd}, @code{pushd}, or
2161 @code{popd}, or inherited by the shell at invocation
2162
2163 @item
2164 the file creation mode mask as set by @code{umask} or inherited from
2165 the shell's parent
2166
2167 @item
2168 current traps set by @code{trap}
2169
2170 @item
2171 shell parameters that are set by variable assignment or with @code{set}
2172 or inherited from the shell's parent in the environment
2173
2174 @item
2175 shell functions defined during execution or inherited from the shell's
2176 parent in the environment
2177
2178 @item
2179 options enabled at invocation (either by default or with command-line
2180 arguments) or by @code{set}
2181
2182 @item
2183 options enabled by @code{shopt}
2184
2185 @item
2186 shell aliases defined with @code{alias} (@pxref{Aliases})
2187
2188 @item
2189 various process @sc{id}s, including those of background jobs
2190 (@pxref{Lists}), the value of @code{$$}, and the value of
2191 @env{$PPID}
2192
2193 @end itemize
2194
2195 When a simple command other than a builtin or shell function
2196 is to be executed, it
2197 is invoked in a separate execution environment that consists of
2198 the following. Unless otherwise noted, the values are inherited
2199 from the shell.
2200
2201 @itemize @bullet
2202 @item
2203 the shell's open files, plus any modifications and additions specified
2204 by redirections to the command
2205
2206 @item
2207 the current working directory
2208
2209 @item
2210 the file creation mode mask
2211
2212 @item
2213 shell variables marked for export, along with variables exported for
2214 the command, passed in the environment (@pxref{Environment})
2215
2216 @item
2217 traps caught by the shell are reset to the values inherited from the
2218 shell's parent, and traps ignored by the shell are ignored
2219
2220 @end itemize
2221
2222 A command invoked in this separate environment cannot affect the
2223 shell's execution environment.
2224
2225 Command substitution and asynchronous commands are invoked in a
2226 subshell environment that is a duplicate of the shell environment,
2227 except that traps caught by the shell are reset to the values
2228 that the shell inherited from its parent at invocation. Builtin
2229 commands that are invoked as part of a pipeline are also executed
2230 in a subshell environment. Changes made to the subshell environment
2231 cannot affect the shell's execution environment.
2232
2233 @node Environment
2234 @subsection Environment
2235 @cindex environment
2236
2237 When a program is invoked it is given an array of strings
2238 called the @var{environment}.
2239 This is a list of name-value pairs, of the form @code{name=value}.
2240
2241 Bash provides several ways to manipulate the environment.
2242 On invocation, the shell scans its own environment and
2243 creates a parameter for each name found, automatically marking
2244 it for @var{export}
2245 to child processes. Executed commands inherit the environment.
2246 The @code{export} and @samp{declare -x}
2247 commands allow parameters and functions to be added to and
2248 deleted from the environment. If the value of a parameter
2249 in the environment is modified, the new value becomes part
2250 of the environment, replacing the old. The environment
2251 inherited by any executed command consists of the shell's
2252 initial environment, whose values may be modified in the shell,
2253 less any pairs removed by the @code{unset} and @samp{export -n}
2254 commands, plus any additions via the @code{export} and
2255 @samp{declare -x} commands.
2256
2257 The environment for any simple command
2258 or function may be augmented temporarily by prefixing it with
2259 parameter assignments, as described in @ref{Shell Parameters}.
2260 These assignment statements affect only the environment seen
2261 by that command.
2262
2263 If the @option{-k} option is set (@pxref{The Set Builtin}), then all
2264 parameter assignments are placed in the environment for a command,
2265 not just those that precede the command name.
2266
2267 When Bash invokes an external command, the variable @samp{$_}
2268 is set to the full path name of the command and passed to that
2269 command in its environment.
2270
2271 @node Exit Status
2272 @subsection Exit Status
2273 @cindex exit status
2274
2275 For the shell's purposes, a command which exits with a
2276 zero exit status has succeeded.
2277 A non-zero exit status indicates failure.
2278 This seemingly counter-intuitive scheme is used so there
2279 is one well-defined way to indicate success and a variety of
2280 ways to indicate various failure modes.
2281 When a command terminates on a fatal signal whose number is @var{N},
2282 Bash uses the value 128+@var{N} as the exit status.
2283
2284 If a command is not found, the child process created to
2285 execute it returns a status of 127. If a command is found
2286 but is not executable, the return status is 126.
2287
2288 If a command fails because of an error during expansion or redirection,
2289 the exit status is greater than zero.
2290
2291 The exit status is used by the Bash conditional commands
2292 (@pxref{Conditional Constructs}) and some of the list
2293 constructs (@pxref{Lists}).
2294
2295 All of the Bash builtins return an exit status of zero if they succeed
2296 and a non-zero status on failure, so they may be used by the
2297 conditional and list constructs.
2298 All builtins return an exit status of 2 to indicate incorrect usage.
2299
2300 @node Signals
2301 @subsection Signals
2302 @cindex signal handling
2303
2304 When Bash is interactive, in the absence of any traps, it ignores
2305 @code{SIGTERM} (so that @samp{kill 0} does not kill an interactive shell),
2306 and @code{SIGINT}
2307 is caught and handled (so that the @code{wait} builtin is interruptible).
2308 When Bash receives a @code{SIGINT}, it breaks out of any executing loops.
2309 In all cases, Bash ignores @code{SIGQUIT}.
2310 If job control is in effect (@pxref{Job Control}), Bash
2311 ignores @code{SIGTTIN}, @code{SIGTTOU}, and @code{SIGTSTP}.
2312
2313 Commands started by Bash have signal handlers set to the
2314 values inherited by the shell from its parent.
2315 When job control is not in effect, asynchronous commands
2316 ignore @code{SIGINT} and @code{SIGQUIT} as well.
2317 Commands run as a result of
2318 command substitution ignore the keyboard-generated job control signals
2319 @code{SIGTTIN}, @code{SIGTTOU}, and @code{SIGTSTP}.
2320
2321 The shell exits by default upon receipt of a @code{SIGHUP}.
2322 Before exiting, it resends the @code{SIGHUP} to all jobs, running
2323 or stopped.
2324 Stopped jobs are sent @code{SIGCONT} to ensure that they receive
2325 the @code{SIGHUP}.
2326 To prevent the shell from sending the @code{SIGHUP} signal to a
2327 particular job, it should be removed
2328 from the jobs table with the @code{disown}
2329 builtin (@pxref{Job Control Builtins}) or marked
2330 to not receive @code{SIGHUP} using @code{disown -h}.
2331
2332 If the @code{huponexit} shell option has been set with @code{shopt}
2333 (@pxref{Bash Builtins}), Bash sends a @code{SIGHUP} to all jobs when
2334 an interactive login shell exits.
2335
2336 When Bash receives a signal for which a trap has been set while waiting
2337 for a command to complete, the trap will not be executed until the
2338 command completes.
2339 When Bash is waiting for an asynchronous
2340 command via the @code{wait} builtin, the reception of a signal for
2341 which a trap has been set will cause the @code{wait} builtin to return
2342 immediately with an exit status greater than 128, immediately after
2343 which the trap is executed.
2344
2345 @node Shell Scripts
2346 @section Shell Scripts
2347 @cindex shell script
2348
2349 A shell script is a text file containing shell commands. When such
2350 a file is used as the first non-option argument when invoking Bash,
2351 and neither the @option{-c} nor @option{-s} option is supplied
2352 (@pxref{Invoking Bash}),
2353 Bash reads and executes commands from the file, then exits. This
2354 mode of operation creates a non-interactive shell. When Bash runs
2355 a shell script, it sets the special parameter @code{0} to the name
2356 of the file, rather than the name of the shell, and the positional
2357 parameters are set to the remaining arguments, if any are given.
2358 If no additional arguments are supplied, the positional parameters
2359 are unset.
2360
2361 A shell script may be made executable by using the @code{chmod} command
2362 to turn on the execute bit. When Bash finds such a file while
2363 searching the @env{$PATH} for a command, it spawns a subshell to
2364 execute it. In other words, executing
2365 @example
2366 filename @var{arguments}
2367 @end example
2368 @noindent
2369 is equivalent to executing
2370 @example
2371 bash filename @var{arguments}
2372 @end example
2373
2374 @noindent
2375 if @code{filename} is an executable shell script.
2376 This subshell reinitializes itself, so that the effect is as if a
2377 new shell had been invoked to interpret the script, with the
2378 exception that the locations of commands remembered by the parent
2379 (see the description of @code{hash} in @ref{Bourne Shell Builtins})
2380 are retained by the child.
2381
2382 Most versions of Unix make this a part of the operating system's command
2383 execution mechanism. If the first line of a script begins with
2384 the two characters @samp{#!}, the remainder of the line specifies
2385 an interpreter for the program.
2386 Thus, you can specify Bash, @code{awk}, Perl, or some other
2387 interpreter and write the rest of the script file in that language.
2388
2389 The arguments to the interpreter
2390 consist of a single optional argument following the interpreter
2391 name on the first line of the script file, followed by the name of
2392 the script file, followed by the rest of the arguments. Bash
2393 will perform this action on operating systems that do not handle it
2394 themselves. Note that some older versions of Unix limit the interpreter
2395 name and argument to a maximum of 32 characters.
2396
2397 Bash scripts often begin with @code{#! /bin/bash} (assuming that
2398 Bash has been installed in @file{/bin}), since this ensures that
2399 Bash will be used to interpret the script, even if it is executed
2400 under another shell.
2401
2402 @node Shell Builtin Commands
2403 @chapter Shell Builtin Commands
2404
2405 @menu
2406 * Bourne Shell Builtins:: Builtin commands inherited from the Bourne
2407 Shell.
2408 * Bash Builtins:: Table of builtins specific to Bash.
2409 * The Set Builtin:: This builtin is so overloaded it
2410 deserves its own section.
2411 * Special Builtins:: Builtin commands classified specially by
2412 POSIX.2.
2413 @end menu
2414
2415 Builtin commands are contained within the shell itself.
2416 When the name of a builtin command is used as the first word of
2417 a simple command (@pxref{Simple Commands}), the shell executes
2418 the command directly, without invoking another program.
2419 Builtin commands are necessary to implement functionality impossible
2420 or inconvenient to obtain with separate utilities.
2421
2422 This section briefly the builtins which Bash inherits from
2423 the Bourne Shell, as well as the builtin commands which are unique
2424 to or have been extended in Bash.
2425
2426 Several builtin commands are described in other chapters: builtin
2427 commands which provide the Bash interface to the job control
2428 facilities (@pxref{Job Control Builtins}), the directory stack
2429 (@pxref{Directory Stack Builtins}), the command history
2430 (@pxref{Bash History Builtins}), and the programmable completion
2431 facilities (@pxref{Programmable Completion Builtins}).
2432
2433 Many of the builtins have been extended by @sc{posix} or Bash.
2434
2435 @node Bourne Shell Builtins
2436 @section Bourne Shell Builtins
2437
2438 The following shell builtin commands are inherited from the Bourne Shell.
2439 These commands are implemented as specified by the @sc{posix} 1003.2 standard.
2440
2441 @table @code
2442 @item : @r{(a colon)}
2443 @btindex :
2444 @example
2445 : [@var{arguments}]
2446 @end example
2447 Do nothing beyond expanding @var{arguments} and performing redirections.
2448 The return status is zero.
2449
2450 @item . @r{(a period)}
2451 @btindex .
2452 @example
2453 . @var{filename} [@var{arguments}]
2454 @end example
2455 Read and execute commands from the @var{filename} argument in the
2456 current shell context. If @var{filename} does not contain a slash,
2457 the @env{PATH} variable is used to find @var{filename}.
2458 When Bash is not in @sc{posix} mode, the current directory is searched
2459 if @var{filename} is not found in @env{$PATH}.
2460 If any @var{arguments} are supplied, they become the positional
2461 parameters when @var{filename} is executed. Otherwise the positional
2462 parameters are unchanged.
2463 The return status is the exit status of the last command executed, or
2464 zero if no commands are executed. If @var{filename} is not found, or
2465 cannot be read, the return status is non-zero.
2466 This builtin is equivalent to @code{source}.
2467
2468 @item break
2469 @btindex break
2470 @example
2471 break [@var{n}]
2472 @end example
2473 Exit from a @code{for}, @code{while}, @code{until}, or @code{select} loop.
2474 If @var{n} is supplied, the @var{n}th enclosing loop is exited.
2475 @var{n} must be greater than or equal to 1.
2476 The return status is zero unless @var{n} is not greater than or equal to 1.
2477
2478 @item cd
2479 @btindex cd
2480 @example
2481 cd [-LP] [@var{directory}]
2482 @end example
2483 Change the current working directory to @var{directory}. If @var{directory}
2484 is not given, the value of the @env{HOME} shell variable is used. If the
2485 shell variable @env{CDPATH} exists, it is used as a search path. If
2486 @var{directory} begins with a slash, @env{CDPATH} is not used.
2487 The @option{-P} option means
2488 to not follow symbolic links; symbolic links are followed by default
2489 or with the @option{-L} option.
2490 If @var{directory} is @samp{-}, it is equivalent to @env{$OLDPWD}.
2491 The return status is zero if the directory is successfully changed,
2492 non-zero otherwise.
2493
2494 @item continue
2495 @btindex continue
2496 @example
2497 continue [@var{n}]
2498 @end example
2499 Resume the next iteration of an enclosing @code{for}, @code{while},
2500 @code{until}, or @code{select} loop.
2501 If @var{n} is supplied, the execution of the @var{n}th enclosing loop
2502 is resumed.
2503 @var{n} must be greater than or equal to 1.
2504 The return status is zero unless @var{n} is not greater than or equal to 1.
2505
2506 @item eval
2507 @btindex eval
2508 @example
2509 eval [@var{arguments}]
2510 @end example
2511 The arguments are concatenated together into a single command, which is
2512 then read and executed, and its exit status returned as the exit status
2513 of @code{eval}.
2514 If there are no arguments or only empty arguments, the return status is
2515 zero.
2516
2517 @item exec
2518 @btindex exec
2519 @example
2520 exec [-cl] [-a @var{name}] [@var{command} [@var{arguments}]]
2521 @end example
2522 If @var{command}
2523 is supplied, it replaces the shell without creating a new process.
2524 If the @option{-l} option is supplied, the shell places a dash at the
2525 beginning of the zeroth arg passed to @var{command}.
2526 This is what the @code{login} program does.
2527 The @option{-c} option causes @var{command} to be executed with an empty
2528 environment.
2529 If @option{-a} is supplied, the shell passes @var{name} as the zeroth
2530 argument to @var{command}.
2531 If no @var{command} is specified, redirections may be used to affect
2532 the current shell environment. If there are no redirection errors, the
2533 return status is zero; otherwise the return status is non-zero.
2534
2535 @item exit
2536 @btindex exit
2537 @example
2538 exit [@var{n}]
2539 @end example
2540 Exit the shell, returning a status of @var{n} to the shell's parent.
2541 If @var{n} is omitted, the exit status is that of the last command executed.
2542 Any trap on @code{EXIT} is executed before the shell terminates.
2543
2544 @item export
2545 @btindex export
2546 @example
2547 export [-fn] [-p] [@var{name}[=@var{value}]]
2548 @end example
2549 Mark each @var{name} to be passed to child processes
2550 in the environment. If the @option{-f} option is supplied, the @var{name}s
2551 refer to shell functions; otherwise the names refer to shell variables.
2552 The @option{-n} option means to no longer mark each @var{name} for export.
2553 If no @var{names} are supplied, or if the @option{-p} option is given, a
2554 list of exported names is displayed.
2555 The @option{-p} option displays output in a form that may be reused as input.
2556 The return status is zero unless an invalid option is supplied, one of
2557 the names is not a valid shell variable name, or @option{-f} is supplied
2558 with a name that is not a shell function.
2559
2560 @item getopts
2561 @btindex getopts
2562 @example
2563 getopts @var{optstring} @var{name} [@var{args}]
2564 @end example
2565 @code{getopts} is used by shell scripts to parse positional parameters.
2566 @var{optstring} contains the option characters to be recognized; if a
2567 character is followed by a colon, the option is expected to have an
2568 argument, which should be separated from it by white space.
2569 The colon (@samp{:}) and question mark (@samp{?}) may not be
2570 used as option characters.
2571 Each time it is invoked, @code{getopts}
2572 places the next option in the shell variable @var{name}, initializing
2573 @var{name} if it does not exist,
2574 and the index of the next argument to be processed into the
2575 variable @env{OPTIND}.
2576 @env{OPTIND} is initialized to 1 each time the shell or a shell script
2577 is invoked.
2578 When an option requires an argument,
2579 @code{getopts} places that argument into the variable @env{OPTARG}.
2580 The shell does not reset @env{OPTIND} automatically; it must be manually
2581 reset between multiple calls to @code{getopts} within the same shell
2582 invocation if a new set of parameters is to be used.
2583
2584 When the end of options is encountered, @code{getopts} exits with a
2585 return value greater than zero.
2586 @env{OPTIND} is set to the index of the first non-option argument,
2587 and @code{name} is set to @samp{?}.
2588
2589 @code{getopts}
2590 normally parses the positional parameters, but if more arguments are
2591 given in @var{args}, @code{getopts} parses those instead.
2592
2593 @code{getopts} can report errors in two ways. If the first character of
2594 @var{optstring} is a colon, @var{silent}
2595 error reporting is used. In normal operation diagnostic messages
2596 are printed when invalid options or missing option arguments are
2597 encountered.
2598 If the variable @env{OPTERR}
2599 is set to 0, no error messages will be displayed, even if the first
2600 character of @code{optstring} is not a colon.
2601
2602 If an invalid option is seen,
2603 @code{getopts} places @samp{?} into @var{name} and, if not silent,
2604 prints an error message and unsets @env{OPTARG}.
2605 If @code{getopts} is silent, the option character found is placed in
2606 @env{OPTARG} and no diagnostic message is printed.
2607
2608 If a required argument is not found, and @code{getopts}
2609 is not silent, a question mark (@samp{?}) is placed in @var{name},
2610 @code{OPTARG} is unset, and a diagnostic message is printed.
2611 If @code{getopts} is silent, then a colon (@samp{:}) is placed in
2612 @var{name} and @env{OPTARG} is set to the option character found.
2613
2614 @item hash
2615 @btindex hash
2616 @example
2617 hash [-r] [-p @var{filename}] [@var{name}]
2618 @end example
2619 Remember the full pathnames of commands specified as @var{name} arguments,
2620 so they need not be searched for on subsequent invocations.
2621 The commands are found by searching through the directories listed in
2622 @env{$PATH}.
2623 The @option{-p} option inhibits the path search, and @var{filename} is
2624 used as the location of @var{name}.
2625 The @option{-r} option causes the shell to forget all remembered locations.
2626 If no arguments are given, information about remembered commands is printed.
2627 The return status is zero unless a @var{name} is not found or an invalid
2628 option is supplied.
2629
2630 @item pwd
2631 @btindex pwd
2632 @example
2633 pwd [-LP]
2634 @end example
2635 Print the absolute pathname of the current working directory.
2636 If the @option{-P} option is supplied, the pathname printed will not
2637 contain symbolic links.
2638 If the @option{-L} option is supplied, the pathname printed may contain
2639 symbolic links.
2640 The return status is zero unless an error is encountered while
2641 determining the name of the current directory or an invalid option
2642 is supplied.
2643
2644 @item readonly
2645 @btindex readonly
2646 @example
2647 readonly [-apf] [@var{name}] @dots{}
2648 @end example
2649 Mark each @var{name} as readonly.
2650 The values of these names may not be changed by subsequent assignment.
2651 If the @option{-f} option is supplied, each @var{name} refers to a shell
2652 function.
2653 The @option{-a} option means each @var{name} refers to an array variable.
2654 If no @var{name} arguments are given, or if the @option{-p}
2655 option is supplied, a list of all readonly names is printed.
2656 The @option{-p} option causes output to be displayed in a format that
2657 may be reused as input.
2658 The return status is zero unless an invalid option is supplied, one of
2659 the @var{name} arguments is not a valid shell variable or function name,
2660 or the @option{-f} option is supplied with a name that is not a shell function.
2661
2662 @item return
2663 @btindex return
2664 @example
2665 return [@var{n}]
2666 @end example
2667 Cause a shell function to exit with the return value @var{n}.
2668 If @var{n} is not supplied, the return value is the exit status of the
2669 last command executed in the function.
2670 This may also be used to terminate execution of a script being executed
2671 with the @code{.} (or @code{source}) builtin, returning either @var{n} or
2672 the exit status of the last command executed within the script as the exit
2673 status of the script.
2674 The return status is false if @code{return} is used outside a function
2675 and not during the execution of a script by @code{.} or @code{source}.
2676
2677 @item shift
2678 @btindex shift
2679 @example
2680 shift [@var{n}]
2681 @end example
2682 Shift the positional parameters to the left by @var{n}.
2683 The positional parameters from @var{n}+1 @dots{} @code{$#} are
2684 renamed to @code{$1} @dots{} @code{$#}-@var{n}+1.
2685 Parameters represented by the numbers @code{$#} to @var{n}+1 are unset.
2686 @var{n} must be a non-negative number less than or equal to @code{$#}.
2687 If @var{n} is zero or greater than @code{$#}, the positional parameters
2688 are not changed.
2689 If @var{n} is not supplied, it is assumed to be 1.
2690 The return status is zero unless @var{n} is greater than @code{$#} or
2691 less than zero, non-zero otherwise.
2692
2693 @item test
2694 @itemx [
2695 @btindex test
2696 @btindex [
2697 Evaluate a conditional expression @var{expr}.
2698 Each operator and operand must be a separate argument.
2699 Expressions are composed of the primaries described below in
2700 @ref{Bash Conditional Expressions}.
2701
2702 When the @code{[} form is used, the last argument to the command must
2703 be a @code{]}.
2704
2705 Expressions may be combined using the following operators, listed in
2706 decreasing order of precedence.
2707
2708 @table @code
2709 @item ! @var{expr}
2710 True if @var{expr} is false.
2711
2712 @item ( @var{expr} )
2713 Returns the value of @var{expr}.
2714 This may be used to override the normal precedence of operators.
2715
2716 @item @var{expr1} -a @var{expr2}
2717 True if both @var{expr1} and @var{expr2} are true.
2718
2719 @item @var{expr1} -o @var{expr2}
2720 True if either @var{expr1} or @var{expr2} is true.
2721 @end table
2722
2723 The @code{test} and @code{[} builtins evaluate conditional
2724 expressions using a set of rules based on the number of arguments.
2725
2726 @table @asis
2727 @item 0 arguments
2728 The expression is false.
2729
2730 @item 1 argument
2731 The expression is true if and only if the argument is not null.
2732
2733 @item 2 arguments
2734 If the first argument is @samp{!}, the expression is true if and
2735 only if the second argument is null.
2736 If the first argument is one of the unary conditional operators
2737 (@pxref{Bash Conditional Expressions}), the expression
2738 is true if the unary test is true.
2739 If the first argument is not a valid unary operator, the expression is
2740 false.
2741
2742 @item 3 arguments
2743 If the second argument is one of the binary conditional
2744 operators (@pxref{Bash Conditional Expressions}), the
2745 result of the expression is the result of the binary test using the
2746 first and third arguments as operands.
2747 If the first argument is @samp{!}, the value is the negation of
2748 the two-argument test using the second and third arguments.
2749 If the first argument is exactly @samp{(} and the third argument is
2750 exactly @samp{)}, the result is the one-argument test of the second
2751 argument.
2752 Otherwise, the expression is false.
2753 The @samp{-a} and @samp{-o} operators are considered binary operators
2754 in this case.
2755
2756 @item 4 arguments
2757 If the first argument is @samp{!}, the result is the negation of
2758 the three-argument expression composed of the remaining arguments.
2759 Otherwise, the expression is parsed and evaluated according to
2760 precedence using the rules listed above.
2761
2762 @item 5 or more arguments
2763 The expression is parsed and evaluated according to precedence
2764 using the rules listed above.
2765 @end table
2766
2767 @item times
2768 @btindex times
2769 @example
2770 times
2771 @end example
2772 Print out the user and system times used by the shell and its children.
2773 The return status is zero.
2774
2775 @item trap
2776 @btindex trap
2777 @example
2778 trap [-lp] [@var{arg}] [@var{sigspec} @dots{}]
2779 @end example
2780 The commands in @var{arg} are to be read and executed when the
2781 shell receives signal @var{sigspec}. If @var{arg} is absent or
2782 equal to @samp{-}, all specified signals are reset to the values
2783 they had when the shell was started.
2784 If @var{arg} is the null string, then the signal specified by
2785 each @var{sigspec} is ignored by the shell and commands it invokes.
2786 If @var{arg} is not present and @option{-p} has been supplied,
2787 the shell displays the trap commands associated with each @var{sigspec}.
2788 If no arguments are supplied, or
2789 only @option{-p} is given, @code{trap} prints the list of commands
2790 associated with each signal number in a form that may be reused as
2791 shell input.
2792 Each @var{sigspec} is either a signal name such as @code{SIGINT} (with
2793 or without the @code{SIG} prefix) or a signal number.
2794 If a @var{sigspec}
2795 is @code{0} or @code{EXIT}, @var{arg} is executed when the shell exits.
2796 If a @var{sigspec} is @code{DEBUG}, the command @var{arg} is executed
2797 after every simple command.
2798 The @option{-l} option causes the shell to print a list of signal names
2799 and their corresponding numbers.
2800
2801 Signals ignored upon entry to the shell cannot be trapped or reset.
2802 Trapped signals are reset to their original values in a child
2803 process when it is created.
2804
2805 The return status is zero unless a @var{sigspec} does not specify a
2806 valid signal.
2807
2808 @item umask
2809 @btindex umask
2810 @example
2811 umask [-p] [-S] [@var{mode}]
2812 @end example
2813 Set the shell process's file creation mask to @var{mode}. If
2814 @var{mode} begins with a digit, it is interpreted as an octal number;
2815 if not, it is interpreted as a symbolic mode mask similar
2816 to that accepted by the @code{chmod} command. If @var{mode} is
2817 omitted, the current value of the mask is printed. If the @option{-S}
2818 option is supplied without a @var{mode} argument, the mask is printed
2819 in a symbolic format.
2820 If the @option{-p} option is supplied, and @var{mode}
2821 is omitted, the output is in a form that may be reused as input.
2822 The return status is zero if the mode is successfully changed or if
2823 no @var{mode} argument is supplied, and non-zero otherwise.
2824
2825 Note that when the mode is interpreted as an octal number, each number
2826 of the umask is subtracted from @code{7}. Thus, a umask of @code{022}
2827 results in permissions of @code{755}.
2828
2829 @item unset
2830 @btindex unset
2831 @example
2832 unset [-fv] [@var{name}]
2833 @end example
2834 Each variable or function @var{name} is removed.
2835 If no options are supplied, or the @option{-v} option is given, each
2836 @var{name} refers to a shell variable.
2837 If the @option{-f} option is given, the @var{name}s refer to shell
2838 functions, and the function definition is removed.
2839 Readonly variables and functions may not be unset.
2840 The return status is zero unless a @var{name} does not exist or is
2841 readonly.
2842 @end table
2843
2844 @node Bash Builtins
2845 @section Bash Builtin Commands
2846
2847 This section describes builtin commands which are unique to
2848 or have been extended in Bash.
2849 Some of these commands are specified in the @sc{posix} 1003.2 standard.
2850
2851 @table @code
2852
2853 @item alias
2854 @btindex alias
2855 @example
2856 alias [@code{-p}] [@var{name}[=@var{value}] @dots{}]
2857 @end example
2858
2859 Without arguments or with the @option{-p} option, @code{alias} prints
2860 the list of aliases on the standard output in a form that allows
2861 them to be reused as input.
2862 If arguments are supplied, an alias is defined for each @var{name}
2863 whose @var{value} is given. If no @var{value} is given, the name
2864 and value of the alias is printed.
2865 Aliases are described in @ref{Aliases}.
2866
2867 @item bind
2868 @btindex bind
2869 @example
2870 bind [-m @var{keymap}] [-lpsvPSV]
2871 bind [-m @var{keymap}] [-q @var{function}] [-u @var{function}] [-r @var{keyseq}]
2872 bind [-m @var{keymap}] -f @var{filename}
2873 bind [-m @var{keymap}] -x @var{keyseq:shell-command}
2874 bind [-m @var{keymap}] @var{keyseq:function-name}
2875 @end example
2876
2877 Display current Readline (@pxref{Command Line Editing})
2878 key and function bindings, or
2879 bind a key sequence to a Readline function or macro. The
2880 binding syntax accepted is identical to that of
2881 a Readline initialization file (@pxref{Readline Init File}),
2882 but each binding must be passed as a separate argument: e.g.,
2883 @samp{"\C-x\C-r":re-read-init-file}.
2884 Options, if supplied, have the following meanings:
2885
2886 @table @code
2887 @item -m @var{keymap}
2888 Use @var{keymap} as the keymap to be affected by
2889 the subsequent bindings. Acceptable @var{keymap}
2890 names are
2891 @code{emacs},
2892 @code{emacs-standard},
2893 @code{emacs-meta},
2894 @code{emacs-ctlx},
2895 @code{vi},
2896 @code{vi-move},
2897 @code{vi-command}, and
2898 @code{vi-insert}.
2899 @code{vi} is equivalent to @code{vi-command};
2900 @code{emacs} is equivalent to @code{emacs-standard}.
2901
2902 @item -l
2903 List the names of all Readline functions.
2904
2905 @item -p
2906 Display Readline function names and bindings in such a way that they
2907 can be used as input or in a Readline initialization file.
2908
2909 @item -P
2910 List current Readline function names and bindings.
2911
2912 @item -v
2913 Display Readline variable names and values in such a way that they
2914 can be used as input or in a Readline initialization file.
2915
2916 @item -V
2917 List current Readline variable names and values.
2918
2919 @item -s
2920 Display Readline key sequences bound to macros and the strings they output
2921 in such a way that they can be used as input or in a Readline
2922 initialization file.
2923
2924 @item -S
2925 Display Readline key sequences bound to macros and the strings they output.
2926
2927 @item -f @var{filename}
2928 Read key bindings from @var{filename}.
2929
2930 @item -q @var{function}
2931 Query about which keys invoke the named @var{function}.
2932
2933 @item -u @var{function}
2934 Unbind all keys bound to the named @var{function}.
2935
2936 @item -r @var{keyseq}
2937 Remove any current binding for @var{keyseq}.
2938
2939 @item -x @var{keyseq:shell-command}
2940 Cause @var{shell-command} to be executed whenever @var{keyseq} is
2941 entered.
2942
2943 @end table
2944
2945 @noindent
2946 The return status is zero unless an invalid option is supplied or an
2947 error occurs.
2948
2949 @item builtin
2950 @btindex builtin
2951 @example
2952 builtin [@var{shell-builtin} [@var{args}]]
2953 @end example
2954 Run a shell builtin, passing it @var{args}, and return its exit status.
2955 This is useful when defining a shell function with the same
2956 name as a shell builtin, retaining the functionality of the builtin within
2957 the function.
2958 The return status is non-zero if @var{shell-builtin} is not a shell
2959 builtin command.
2960
2961 @item command
2962 @btindex command
2963 @example
2964 command [-pVv] @var{command} [@var{arguments} @dots{}]
2965 @end example
2966 Runs @var{command} with @var{arguments} ignoring any shell function
2967 named @var{command}.
2968 Only shell builtin commands or commands found by searching the
2969 @env{PATH} are executed.
2970 If there is a shell function named @code{ls}, running @samp{command ls}
2971 within the function will execute the external command @code{ls}
2972 instead of calling the function recursively.
2973 The @option{-p} option means to use a default value for @env{PATH}
2974 that is guaranteed to find all of the standard utilities.
2975 The return status in this case is 127 if @var{command} cannot be
2976 found or an error occurred, and the exit status of @var{command}
2977 otherwise.
2978
2979 If either the @option{-V} or @option{-v} option is supplied, a
2980 description of @var{command} is printed. The @option{-v} option
2981 causes a single word indicating the command or file name used to
2982 invoke @var{command} to be displayed; the @option{-V} option produces
2983 a more verbose description. In this case, the return status is
2984 zero if @var{command} is found, and non-zero if not.
2985
2986 @item declare
2987 @btindex declare
2988 @example
2989 declare [-afFrxi] [-p] [@var{name}[=@var{value}]]
2990 @end example
2991
2992 Declare variables and give them attributes. If no @var{name}s
2993 are given, then display the values of variables instead.
2994
2995 The @option{-p} option will display the attributes and values of each
2996 @var{name}. When @option{-p} is used, additional options are ignored.
2997 The @option{-F} option inhibits the display of function definitions;
2998 only the function name and attributes are printed. @option{-F} implies
2999 @option{-f}. The following options can be used to restrict output
3000 to variables with the specified attributes or to give variables
3001 attributes:
3002
3003 @table @code
3004 @item -a
3005 Each @var{name} is an array variable (@pxref{Arrays}).
3006
3007 @item -f
3008 Use function names only.
3009
3010 @item -i
3011 The variable is to be treated as
3012 an integer; arithmetic evaluation (@pxref{Shell Arithmetic}) is
3013 performed when the variable is assigned a value.
3014
3015 @item -r
3016 Make @var{name}s readonly. These names cannot then be assigned values
3017 by subsequent assignment statements or unset.
3018
3019 @item -x
3020 Mark each @var{name} for export to subsequent commands via
3021 the environment.
3022 @end table
3023
3024 Using @samp{+} instead of @samp{-} turns off the attribute instead.
3025 When used in a function, @code{declare} makes each @var{name} local,
3026 as with the @code{local} command.
3027
3028 The return status is zero unless an invalid option is encountered,
3029 an attempt is made to define a function using @samp{-f foo=bar},
3030 an attempt is made to assign a value to a readonly variable,
3031 an attempt is made to assign a value to an array variable without
3032 using the compound assignment syntax (@pxref{Arrays}),
3033 one of the @var{names} is not a valid shell variable name,
3034 an attempt is made to turn off readonly status for a readonly variable,
3035 an attempt is made to turn off array status for an array variable,
3036 or an attempt is made to display a non-existent function with @option{-f}.
3037
3038 @item echo
3039 @btindex echo
3040 @example
3041 echo [-neE] [@var{arg} @dots{}]
3042 @end example
3043 Output the @var{arg}s, separated by spaces, terminated with a
3044 newline.
3045 The return status is always 0.
3046 If @option{-n} is specified, the trailing newline is suppressed.
3047 If the @option{-e} option is given, interpretation of the following
3048 backslash-escaped characters is enabled.
3049 The @option{-E} option disables the interpretation of these escape characters,
3050 even on systems where they are interpreted by default.
3051 The @code{xpg_echo} shell option may be used to
3052 dynamically determine whether or not @code{echo} expands these
3053 escape characters by default.
3054 @code{echo} interprets the following escape sequences:
3055 @table @code
3056 @item \a
3057 alert (bell)
3058 @item \b
3059 backspace
3060 @item \c
3061 suppress trailing newline
3062 @item \e
3063 escape
3064 @item \f
3065 form feed
3066 @item \n
3067 new line
3068 @item \r
3069 carriage return
3070 @item \t
3071 horizontal tab
3072 @item \v
3073 vertical tab
3074 @item \\
3075 backslash
3076 @item \@var{nnn}
3077 the character whose @code{ASCII} code is the octal value @var{nnn}
3078 (one to three digits)
3079 @item \x@var{nnn}
3080 the character whose @code{ASCII} code is the hexadecimal value @var{nnn}
3081 (one to three digits)
3082 @end table
3083
3084 @item enable
3085 @btindex enable
3086 @example
3087 enable [-n] [-p] [-f @var{filename}] [-ads] [@var{name} @dots{}]
3088 @end example
3089 Enable and disable builtin shell commands.
3090 Disabling a builtin allows a disk command which has the same name
3091 as a shell builtin to be executed without specifying a full pathname,
3092 even though the shell normally searches for builtins before disk commands.
3093 If @option{-n} is used, the @var{name}s become disabled. Otherwise
3094 @var{name}s are enabled. For example, to use the @code{test} binary
3095 found via @env{$PATH} instead of the shell builtin version, type
3096 @samp{enable -n test}.
3097
3098 If the @option{-p} option is supplied, or no @var{name} arguments appear,
3099 a list of shell builtins is printed. With no other arguments, the list
3100 consists of all enabled shell builtins.
3101 The @option{-a} option means to list
3102 each builtin with an indication of whether or not it is enabled.
3103
3104 The @option{-f} option means to load the new builtin command @var{name}
3105 from shared object @var{filename}, on systems that support dynamic loading.
3106 The @option{-d} option will delete a builtin loaded with @option{-f}.
3107
3108 If there are no options, a list of the shell builtins is displayed.
3109 The @option{-s} option restricts @code{enable} to the @sc{posix} special
3110 builtins. If @option{-s} is used with @option{-f}, the new builtin becomes
3111 a special builtin (@pxref{Special Builtins}).
3112
3113 The return status is zero unless a @var{name} is not a shell builtin
3114 or there is an error loading a new builtin from a shared object.
3115
3116 @item help
3117 @btindex help
3118 @example
3119 help [-s] [@var{pattern}]
3120 @end example
3121 Display helpful information about builtin commands.
3122 If @var{pattern} is specified, @code{help} gives detailed help
3123 on all commands matching @var{pattern}, otherwise a list of
3124 the builtins is printed.
3125 The @option{-s} option restricts the information displayed to a short
3126 usage synopsis.
3127 The return status is zero unless no command matches @var{pattern}.
3128
3129 @item let
3130 @btindex let
3131 @example
3132 let @var{expression} [@var{expression}]
3133 @end example
3134 The @code{let} builtin allows arithmetic to be performed on shell
3135 variables. Each @var{expression} is evaluated according to the
3136 rules given below in @ref{Shell Arithmetic}. If the
3137 last @var{expression} evaluates to 0, @code{let} returns 1;
3138 otherwise 0 is returned.
3139
3140 @item local
3141 @btindex local
3142 @example
3143 local [@var{option}] @var{name}[=@var{value}]
3144 @end example
3145 For each argument, a local variable named @var{name} is created,
3146 and assigned @var{value}.
3147 The @var{option} can be any of the options accepted by @code{declare}.
3148 @code{local} can only be used within a function; it makes the variable
3149 @var{name} have a visible scope restricted to that function and its
3150 children. The return status is zero unless @code{local} is used outside
3151 a function, an invalid @var{name} is supplied, or @var{name} is a
3152 readonly variable.
3153
3154 @item logout
3155 @btindex logout
3156 @example
3157 logout [@var{n}]
3158 @end example
3159 Exit a login shell, returning a status of @var{n} to the shell's
3160 parent.
3161
3162 @item printf
3163 @btindex printf
3164 @example
3165 @code{printf} @var{format} [@var{arguments}]
3166 @end example
3167 Write the formatted @var{arguments} to the standard output under the
3168 control of the @var{format}.
3169 The @var{format} is a character string which contains three types of objects:
3170 plain characters, which are simply copied to standard output, character
3171 escape sequences, which are converted and copied to the standard output, and
3172 format specifications, each of which causes printing of the next successive
3173 @var{argument}.
3174 In addition to the standard @code{printf(1)} formats, @samp{%b} causes
3175 @code{printf} to expand backslash escape sequences in the corresponding
3176 @var{argument}, and @samp{%q} causes @code{printf} to output the
3177 corresponding @var{argument} in a format that can be reused as shell input.
3178
3179 The @var{format} is reused as necessary to consume all of the @var{arguments}.
3180 If the @var{format} requires more @var{arguments} than are supplied, the
3181 extra format specifications behave as if a zero value or null string, as
3182 appropriate, had been supplied. The return value is zero on success,
3183 non-zero on failure.
3184
3185 @item read
3186 @btindex read
3187 @example
3188 read [-ers] [-a @var{aname}] [-p @var{prompt}] [-t @var{timeout}] [-n @var{nchars}] [-d @var{delim}] [@var{name} @dots{}]
3189 @end example
3190 One line is read from the standard input, and the first word
3191 is assigned to the first @var{name}, the second word to the second @var{name},
3192 and so on, with leftover words and their intervening separators assigned
3193 to the last @var{name}.
3194 If there are fewer words read from the standard input than names,
3195 the remaining names are assigned empty values.
3196 The characters in the value of the @env{IFS} variable
3197 are used to split the line into words.
3198 The backslash character @samp{\} may be used to remove any special
3199 meaning for the next character read and for line continuation.
3200 If no names are supplied, the line read is assigned to the
3201 variable @env{REPLY}.
3202 The return code is zero, unless end-of-file is encountered or @code{read}
3203 times out.
3204 Options, if supplied, have the following meanings:
3205
3206 @table @code
3207 @item -a @var{aname}
3208 The words are assigned to sequential indices of the array variable
3209 @var{aname}, starting at 0.
3210 All elements are removed from @var{aname} before the assignment.
3211 Other @var{name} arguments are ignored.
3212
3213 @item -d @var{delim}
3214 The first character of @var{delim} is used to terminate the input line,
3215 rather than newline.
3216
3217 @item -e
3218 Readline (@pxref{Command Line Editing}) is used to obtain the line.
3219
3220 @item -n @var{nchars}
3221 @code{read} returns after reading @var{nchars} characters rather than
3222 waiting for a complete line of input.
3223
3224 @item -p @var{prompt}
3225 Display @var{prompt}, without a trailing newline, before attempting
3226 to read any input.
3227 The prompt is displayed only if input is coming from a terminal.
3228
3229 @item -r
3230 If this option is given, backslash does not act as an escape character.
3231 The backslash is considered to be part of the line.
3232 In particular, a backslash-newline pair may not be used as a line
3233 continuation.
3234
3235 @item -s
3236 Silent mode. If input is coming from a terminal, characters are
3237 not echoed.
3238
3239 @item -t @var{timeout}
3240 Cause @code{read} to time out and return failure if a complete line of
3241 input is not read within @var{timeout} seconds.
3242 This option has no effect if @code{read} is not reading input from the
3243 terminal or a pipe.
3244
3245 @end table
3246
3247 @item shopt
3248 @btindex shopt
3249 @example
3250 shopt [-pqsu] [-o] [@var{optname} @dots{}]
3251 @end example
3252 Toggle the values of variables controlling optional shell behavior.
3253 With no options, or with the @option{-p} option, a list of all settable
3254 options is displayed, with an indication of whether or not each is set.
3255 The @option{-p} option causes output to be displayed in a form that
3256 may be reused as input.
3257 Other options have the following meanings:
3258
3259 @table @code
3260 @item -s
3261 Enable (set) each @var{optname}.
3262
3263 @item -u
3264 Disable (unset) each @var{optname}.
3265
3266 @item -q
3267 Suppresses normal output; the return status
3268 indicates whether the @var{optname} is set or unset.
3269 If multiple @var{optname} arguments are given with @option{-q},
3270 the return status is zero if all @var{optnames} are enabled;
3271 non-zero otherwise.
3272
3273 @item -o
3274 Restricts the values of
3275 @var{optname} to be those defined for the @option{-o} option to the
3276 @code{set} builtin (@pxref{The Set Builtin}).
3277 @end table
3278
3279 If either @option{-s} or @option{-u}
3280 is used with no @var{optname} arguments, the display is limited to
3281 those options which are set or unset, respectively.
3282
3283 Unless otherwise noted, the @code{shopt} options are disabled (off)
3284 by default.
3285
3286 The return status when listing options is zero if all @var{optnames}
3287 are enabled, non-zero otherwise. When setting or unsetting options,
3288 the return status is zero unless an @var{optname} is not a valid shell
3289 option.
3290
3291 The list of @code{shopt} options is:
3292 @table @code
3293 @item cdable_vars
3294 If this is set, an argument to the @code{cd}
3295 builtin command that
3296 is not a directory is assumed to be the name of a variable whose
3297 value is the directory to change to.
3298
3299 @item cdspell
3300 If set, minor errors in the spelling of a directory component in a
3301 @code{cd} command will be corrected.
3302 The errors checked for are transposed characters,
3303 a missing character, and a character too many.
3304 If a correction is found, the corrected path is printed,
3305 and the command proceeds.
3306 This option is only used by interactive shells.
3307
3308 @item checkhash
3309 If this is set, Bash checks that a command found in the hash
3310 table exists before trying to execute it. If a hashed command no
3311 longer exists, a normal path search is performed.
3312
3313 @item checkwinsize
3314 If set, Bash checks the window size after each command
3315 and, if necessary, updates the values of
3316 @env{LINES} and @env{COLUMNS}.
3317
3318 @item cmdhist
3319 If set, Bash
3320 attempts to save all lines of a multiple-line
3321 command in the same history entry. This allows
3322 easy re-editing of multi-line commands.
3323
3324 @item dotglob
3325 If set, Bash includes filenames beginning with a `.' in
3326 the results of filename expansion.
3327
3328 @item execfail
3329 If this is set, a non-interactive shell will not exit if
3330 it cannot execute the file specified as an argument to the @code{exec}
3331 builtin command. An interactive shell does not exit if @code{exec}
3332 fails.
3333
3334 @item expand_aliases
3335 If set, aliases are expanded as described below under Aliases,
3336 @ref{Aliases}.
3337 This option is enabled by default for interactive shells.
3338
3339 @item extglob
3340 If set, the extended pattern matching features described above
3341 (@pxref{Pattern Matching}) are enabled.
3342
3343 @item histappend
3344 If set, the history list is appended to the file named by the value
3345 of the @env{HISTFILE}
3346 variable when the shell exits, rather than overwriting the file.
3347
3348 @item histreedit
3349 If set, and Readline
3350 is being used, a user is given the opportunity to re-edit a
3351 failed history substitution.
3352
3353 @item histverify
3354 If set, and Readline
3355 is being used, the results of history substitution are not immediately
3356 passed to the shell parser. Instead, the resulting line is loaded into
3357 the Readline editing buffer, allowing further modification.
3358
3359 @item hostcomplete
3360 If set, and Readline is being used, Bash will attempt to perform
3361 hostname completion when a word containing a @samp{@@} is being
3362 completed (@pxref{Commands For Completion}). This option is enabled
3363 by default.
3364
3365 @item huponexit
3366 If set, Bash will send @code{SIGHUP} to all jobs when an interactive
3367 login shell exits (@pxref{Signals}).
3368
3369 @item interactive_comments
3370 Allow a word beginning with @samp{#}
3371 to cause that word and all remaining characters on that
3372 line to be ignored in an interactive shell.
3373 This option is enabled by default.
3374
3375 @item lithist
3376 If enabled, and the @code{cmdhist}
3377 option is enabled, multi-line commands are saved to the history with
3378 embedded newlines rather than using semicolon separators where possible.
3379
3380 @item mailwarn
3381 If set, and a file that Bash is checking for mail has been
3382 accessed since the last time it was checked, the message
3383 @code{"The mail in @var{mailfile} has been read"} is displayed.
3384
3385 @item no_empty_cmd_completion
3386 If set, and Readline is being used, Bash will not attempt to search
3387 the @env{PATH} for possible completions when completion is attempted
3388 on an empty line.
3389
3390 @item nocaseglob
3391 If set, Bash matches filenames in a case-insensitive fashion when
3392 performing filename expansion.
3393
3394 @item nullglob
3395 If set, Bash allows filename patterns which match no
3396 files to expand to a null string, rather than themselves.
3397
3398 @item progcomp
3399 If set, the programmable completion facilities
3400 (@pxref{Programmable Completion}) are enabled.
3401 This option is enabled by default.
3402
3403 @item promptvars
3404 If set, prompt strings undergo variable and parameter expansion after
3405 being expanded (@pxref{Printing a Prompt}).
3406 This option is enabled by default.
3407
3408 @item restricted_shell
3409 The shell sets this option if it is started in restricted mode
3410 (@pxref{The Restricted Shell}).
3411 The value may not be changed.
3412 This is not reset when the startup files are executed, allowing
3413 the startup files to discover whether or not a shell is restricted.
3414
3415 @item shift_verbose
3416 If this is set, the @code{shift}
3417 builtin prints an error message when the shift count exceeds the
3418 number of positional parameters.
3419
3420 @item sourcepath
3421 If set, the @code{source} builtin uses the value of @env{PATH}
3422 to find the directory containing the file supplied as an argument.
3423 This option is enabled by default.
3424
3425 @item xpg_echo
3426 If set, the @code{echo} builtin expands backslash-escape sequences
3427 by default.
3428
3429 @end table
3430
3431 @noindent
3432 The return status when listing options is zero if all @var{optnames}
3433 are enabled, non-zero otherwise.
3434 When setting or unsetting options, the return status is zero unless an
3435 @var{optname} is not a valid shell option.
3436
3437 @item source
3438 @btindex source
3439 @example
3440 source @var{filename}
3441 @end example
3442 A synonym for @code{.} (@pxref{Bourne Shell Builtins}).
3443
3444 @item type
3445 @btindex type
3446 @example
3447 type [-atp] [@var{name} @dots{}]
3448 @end example
3449 For each @var{name}, indicate how it would be interpreted if used as a
3450 command name.
3451
3452 If the @option{-t} option is used, @code{type} prints a single word
3453 which is one of @samp{alias}, @samp{function}, @samp{builtin},
3454 @samp{file} or @samp{keyword},
3455 if @var{name} is an alias, shell function, shell builtin,
3456 disk file, or shell reserved word, respectively.
3457 If the @var{name} is not found, then nothing is printed, and
3458 @code{type} returns a failure status.
3459
3460 If the @option{-p} option is used, @code{type} either returns the name
3461 of the disk file that would be executed, or nothing if @option{-t}
3462 would not return @samp{file}.
3463
3464 If the @option{-a} option is used, @code{type} returns all of the places
3465 that contain an executable named @var{file}.
3466 This includes aliases and functions, if and only if the @option{-p} option
3467 is not also used.
3468
3469 The return status is zero if any of the @var{names} are found, non-zero
3470 if none are found.
3471
3472 @item typeset
3473 @btindex typeset
3474 @example
3475 typeset [-afFrxi] [-p] [@var{name}[=@var{value}]]
3476 @end example
3477 The @code{typeset} command is supplied for compatibility with the Korn
3478 shell; however, it has been deprecated in favor of the @code{declare}
3479 builtin command.
3480
3481 @item ulimit
3482 @btindex ulimit
3483 @example
3484 ulimit [-acdflmnpstuvSH] [@var{limit}]
3485 @end example
3486 @code{ulimit} provides control over the resources available to processes
3487 started by the shell, on systems that allow such control. If an
3488 option is given, it is interpreted as follows:
3489 @table @code
3490 @item -S
3491 Change and report the soft limit associated with a resource.
3492
3493 @item -H
3494 Change and report the hard limit associated with a resource.
3495
3496 @item -a
3497 All current limits are reported.
3498
3499 @item -c
3500 The maximum size of core files created.
3501
3502 @item -d
3503 The maximum size of a process's data segment.
3504
3505 @item -f
3506 The maximum size of files created by the shell.
3507
3508 @item -l
3509 The maximum size that may be locked into memory.
3510
3511 @item -m
3512 The maximum resident set size.
3513
3514 @item -n
3515 The maximum number of open file descriptors.
3516
3517 @item -p
3518 The pipe buffer size.
3519
3520 @item -s
3521 The maximum stack size.
3522
3523 @item -t
3524 The maximum amount of cpu time in seconds.
3525
3526 @item -u
3527 The maximum number of processes available to a single user.
3528
3529 @item -v
3530 The maximum amount of virtual memory available to the process.
3531
3532 @end table
3533
3534 If @var{limit} is given, it is the new value of the specified resource.
3535 Otherwise, the current value of the soft limit for the specified resource
3536 is printed, unless the @option{-H} option is supplied.
3537 When setting new limits, if neither @option{-H} nor @option{-S} is supplied,
3538 both the hard and soft limits are set.
3539 If no option is given, then @option{-f} is assumed. Values are in 1024-byte
3540 increments, except for @option{-t}, which is in seconds, @option{-p},
3541 which is in units of 512-byte blocks, and @option{-n} and @option{-u}, which
3542 are unscaled values.
3543
3544 The return status is zero unless an invalid option is supplied, a
3545 non-numeric argument other than @code{unlimited} is supplied as a
3546 @var{limit}, or an error occurs while setting a new limit.
3547
3548 @item unalias
3549 @btindex unalias
3550 @example
3551 unalias [-a] [@var{name} @dots{} ]
3552 @end example
3553
3554 Remove each @var{name} from the list of aliases. If @option{-a} is
3555 supplied, all aliases are removed.
3556 Aliases are described in @ref{Aliases}.
3557
3558 @end table
3559
3560 @node The Set Builtin
3561 @section The Set Builtin
3562
3563 This builtin is so complicated that it deserves its own section.
3564
3565 @table @code
3566 @item set
3567 @btindex set
3568 @example
3569 set [--abefhkmnptuvxBCHP] [-o @var{option}] [@var{argument} @dots{}]
3570 @end example
3571
3572 If no options or arguments are supplied, @code{set} displays the names
3573 and values of all shell variables and functions, sorted according to the
3574 current locale, in a format that may be reused as input.
3575
3576 When options are supplied, they set or unset shell attributes.
3577 Options, if specified, have the following meanings:
3578
3579 @table @code
3580 @item -a
3581 Mark variables and function which are modified or created for export
3582 to the environment of subsequent commands.
3583
3584 @item -b
3585 Cause the status of terminated background jobs to be reported
3586 immediately, rather than before printing the next primary prompt.
3587
3588 @item -e
3589 Exit immediately if a simple command (@pxref{Simple Commands}) exits
3590 with a non-zero status, unless the command that fails is part of an
3591 @code{until} or @code{while} loop, part of an @code{if} statement,
3592 part of a @code{&&} or @code{||} list, or if the command's return
3593 status is being inverted using @code{!}.
3594
3595 @item -f
3596 Disable file name generation (globbing).
3597
3598 @item -h
3599 Locate and remember (hash) commands as they are looked up for execution.
3600 This option is enabled by default.
3601
3602 @item -k
3603 All arguments in the form of assignment statements are placed
3604 in the environment for a command, not just those that precede
3605 the command name.
3606
3607 @item -m
3608 Job control is enabled (@pxref{Job Control}).
3609
3610 @item -n
3611 Read commands but do not execute them; this may be used to check a
3612 script for syntax errors.
3613 This option is ignored by interactive shells.
3614
3615 @item -o @var{option-name}
3616
3617 Set the option corresponding to @var{option-name}:
3618
3619 @table @code
3620 @item allexport
3621 Same as @code{-a}.
3622
3623 @item braceexpand
3624 Same as @code{-B}.
3625
3626 @item emacs
3627 Use an @code{emacs}-style line editing interface (@pxref{Command Line Editing}).
3628
3629 @item errexit
3630 Same as @code{-e}.
3631
3632 @item hashall
3633 Same as @code{-h}.
3634
3635 @item histexpand
3636 Same as @code{-H}.
3637
3638 @item history
3639 Enable command history, as described in @ref{Bash History Facilities}.
3640 This option is on by default in interactive shells.
3641
3642 @item ignoreeof
3643 An interactive shell will not exit upon reading EOF.
3644
3645 @item keyword
3646 Same as @code{-k}.
3647
3648 @item monitor
3649 Same as @code{-m}.
3650
3651 @item noclobber
3652 Same as @code{-C}.
3653
3654 @item noexec
3655 Same as @code{-n}.
3656
3657 @item noglob
3658 Same as @code{-f}.
3659
3660 @item notify
3661 Same as @code{-b}.
3662
3663 @item nounset
3664 Same as @code{-u}.
3665
3666 @item onecmd
3667 Same as @code{-t}.
3668
3669 @item physical
3670 Same as @code{-P}.
3671
3672 @item posix
3673 Change the behavior of Bash where the default operation differs
3674 from the @sc{posix} 1003.2 standard to match the standard
3675 (@pxref{Bash POSIX Mode}).
3676 This is intended to make Bash behave as a strict superset of that
3677 standard.
3678
3679 @item privileged
3680 Same as @code{-p}.
3681
3682 @item verbose
3683 Same as @code{-v}.
3684
3685 @item vi
3686 Use a @code{vi}-style line editing interface.
3687
3688 @item xtrace
3689 Same as @code{-x}.
3690 @end table
3691
3692 @item -p
3693 Turn on privileged mode.
3694 In this mode, the @env{$BASH_ENV} and @env{$ENV} files are not
3695 processed, shell functions are not inherited from the environment,
3696 and the @env{SHELLOPTS} variable, if it appears in the environment,
3697 is ignored.
3698 If the shell is started with the effective user (group) id not equal to the
3699 real user (group) id, and the @code{-p} option is not supplied, these actions
3700 are taken and the effective user id is set to the real user id.
3701 If the @code{-p} option is supplied at startup, the effective user id is
3702 not reset.
3703 Turning this option off causes the effective user
3704 and group ids to be set to the real user and group ids.
3705
3706 @item -t
3707 Exit after reading and executing one command.
3708
3709 @item -u
3710 Treat unset variables as an error when performing parameter expansion.
3711 An error message will be written to the standard error, and a non-interactive
3712 shell will exit.
3713
3714 @item -v
3715 Print shell input lines as they are read.
3716
3717 @item -x
3718 Print a trace of simple commands and their arguments after they are
3719 expanded and before they are executed.
3720
3721 @item -B
3722 The shell will perform brace expansion (@pxref{Brace Expansion}).
3723 This option is on by default.
3724
3725 @item -C
3726 Prevent output redirection using @samp{>}, @samp{>&}, and @samp{<>}
3727 from overwriting existing files.
3728
3729 @item -H
3730 Enable @samp{!} style history substitution (@pxref{History Interaction}).
3731 This option is on by default for interactive shells.
3732
3733 @item -P
3734 If set, do not follow symbolic links when performing commands such as
3735 @code{cd} which change the current directory. The physical directory
3736 is used instead. By default, Bash follows
3737 the logical chain of directories when performing commands
3738 which change the current directory.
3739
3740 For example, if @file{/usr/sys} is a symbolic link to @file{/usr/local/sys}
3741 then:
3742 @example
3743 $ cd /usr/sys; echo $PWD
3744 /usr/sys
3745 $ cd ..; pwd
3746 /usr
3747 @end example
3748
3749 @noindent
3750 If @code{set -P} is on, then:
3751 @example
3752 $ cd /usr/sys; echo $PWD
3753 /usr/local/sys
3754 $ cd ..; pwd
3755 /usr/local
3756 @end example
3757
3758 @item --
3759 If no arguments follow this option, then the positional parameters are
3760 unset. Otherwise, the positional parameters are set to the
3761 @var{arguments}, even if some of them begin with a @samp{-}.
3762
3763 @item -
3764 Signal the end of options, cause all remaining @var{arguments}
3765 to be assigned to the positional parameters. The @option{-x}
3766 and @option{-v} options are turned off.
3767 If there are no arguments, the positional parameters remain unchanged.
3768 @end table
3769
3770 Using @samp{+} rather than @samp{-} causes these options to be
3771 turned off. The options can also be used upon invocation of the
3772 shell. The current set of options may be found in @code{$-}.
3773
3774 The remaining N @var{arguments} are positional parameters and are
3775 assigned, in order, to @code{$1}, @code{$2}, @dots{} @code{$N}.
3776 The special parameter @code{#} is set to N.
3777
3778 The return status is always zero unless an invalid option is supplied.
3779 @end table
3780
3781 @node Special Builtins
3782 @section Special Builtins
3783 @cindex special builtin
3784
3785 For historical reasons, the @sc{posix} 1003.2 standard has classified
3786 several builtin commands as @emph{special}.
3787 When Bash is executing in @sc{posix} mode, the special builtins
3788 differ from other builtin commands in three respects:
3789
3790 @enumerate
3791 @item
3792 Special builtins are found before shell functions during command lookup.
3793
3794 @item
3795 If a special builtin returns an error status, a non-interactive shell exits.
3796
3797 @item
3798 Assignment statements preceding the command stay in effect in the shell
3799 environment after the command completes.
3800 @end enumerate
3801
3802 When Bash is not executing in @sc{posix} mode, these builtins behave no
3803 differently than the rest of the Bash builtin commands.
3804 The Bash @sc{posix} mode is described in @ref{Bash POSIX Mode}.
3805
3806 These are the @sc{posix} special builtins:
3807 @example
3808 @w{break : . continue eval exec exit export readonly return set}
3809 @w{shift trap unset}
3810 @end example
3811
3812 @node Shell Variables
3813 @chapter Shell Variables
3814
3815 @menu
3816 * Bourne Shell Variables:: Variables which Bash uses in the same way
3817 as the Bourne Shell.
3818 * Bash Variables:: List of variables that exist in Bash.
3819 @end menu
3820
3821 This chapter describes the shell variables that Bash uses.
3822 Bash automatically assigns default values to a number of variables.
3823
3824 @node Bourne Shell Variables
3825 @section Bourne Shell Variables
3826
3827 Bash uses certain shell variables in the same way as the Bourne shell.
3828 In some cases, Bash assigns a default value to the variable.
3829
3830 @vtable @code
3831
3832 @item CDPATH
3833 A colon-separated list of directories used as a search path for
3834 the @code{cd} builtin command.
3835
3836 @item HOME
3837 The current user's home directory; the default for the @code{cd} builtin
3838 command.
3839 The value of this variable is also used by tilde expansion
3840 (@pxref{Tilde Expansion}).
3841
3842 @item IFS
3843 A list of characters that separate fields; used when the shell splits
3844 words as part of expansion.
3845
3846 @item MAIL
3847 If this parameter is set to a filename and the @env{MAILPATH} variable
3848 is not set, Bash informs the user of the arrival of mail in
3849 the specified file.
3850
3851 @item MAILPATH
3852 A colon-separated list of filenames which the shell periodically checks
3853 for new mail.
3854 Each list entry can specify the message that is printed when new mail
3855 arrives in the mail file by separating the file name from the message with
3856 a @samp{?}.
3857 When used in the text of the message, @code{$_} expands to the name of
3858 the current mail file.
3859
3860 @item OPTARG
3861 The value of the last option argument processed by the @code{getopts} builtin.
3862
3863 @item OPTIND
3864 The index of the last option argument processed by the @code{getopts} builtin.
3865
3866 @item PATH
3867 A colon-separated list of directories in which the shell looks for
3868 commands.
3869
3870 @item PS1
3871 The primary prompt string. The default value is @samp{\s-\v\$ }.
3872 @xref{Printing a Prompt}, for the complete list of escape
3873 sequences that are expanded before @env{PS1} is displayed.
3874
3875 @item PS2
3876 The secondary prompt string. The default value is @samp{> }.
3877
3878 @end vtable
3879
3880 @node Bash Variables
3881 @section Bash Variables
3882
3883 These variables are set or used by Bash, but other shells
3884 do not normally treat them specially.
3885
3886 A few variables used by Bash are described in different chapters:
3887 variables for controlling the job control facilities
3888 (@pxref{Job Control Variables}).
3889
3890 @vtable @code
3891
3892 @item BASH
3893 The full pathname used to execute the current instance of Bash.
3894
3895 @item BASH_ENV
3896 If this variable is set when Bash is invoked to execute a shell
3897 script, its value is expanded and used as the name of a startup file
3898 to read before executing the script. @xref{Bash Startup Files}.
3899
3900 @item BASH_VERSION
3901 The version number of the current instance of Bash.
3902
3903 @item BASH_VERSINFO
3904 A readonly array variable (@pxref{Arrays})
3905 whose members hold version information for this instance of Bash.
3906 The values assigned to the array members are as follows:
3907
3908 @table @code
3909
3910 @item BASH_VERSINFO[0]
3911 The major version number (the @var{release}).
3912
3913 @item BASH_VERSINFO[1]
3914 The minor version number (the @var{version}).
3915
3916 @item BASH_VERSINFO[2]
3917 The patch level.
3918
3919 @item BASH_VERSINFO[3]
3920 The build version.
3921
3922 @item BASH_VERSINFO[4]
3923 The release status (e.g., @var{beta1}).
3924
3925 @item BASH_VERSINFO[5]
3926 The value of @env{MACHTYPE}.
3927
3928 @end table
3929
3930 @item COMP_WORDS
3931 An array variable consisting of the individual
3932 words in the current command line.
3933 This variable is available only in shell functions invoked by the
3934 programmable completion facilities (@pxref{Programmable Completion}).
3935
3936 @item COMP_CWORD
3937 An index into @env{$@{COMP_WORDS@}} of the word containing the current
3938 cursor position.
3939 This variable is available only in shell functions invoked by the
3940 programmable completion facilities (@pxref{Programmable Completion}).
3941
3942 @item COMP_LINE
3943 The current command line.
3944 This variable is available only in shell functions and external
3945 commands invoked by the
3946 programmable completion facilities (@pxref{Programmable Completion}).
3947
3948 @item COMP_POINT
3949 The index of the current cursor position relative to the beginning of
3950 the current command.
3951 If the current cursor position is at the end of the current command,
3952 the value of this variable is equal to @code{$@{#COMP_LINE@}}.
3953 This variable is available only in shell functions and external
3954 commands invoked by the
3955 programmable completion facilities (@pxref{Programmable Completion}).
3956
3957 @item COMPREPLY
3958 An array variable from which Bash reads the possible completions
3959 generated by a shell function invoked by the programmable completion
3960 facility (@pxref{Programmable Completion}).
3961
3962 @item DIRSTACK
3963 An array variable containing the current contents of the directory stack.
3964 Directories appear in the stack in the order they are displayed by the
3965 @code{dirs} builtin.
3966 Assigning to members of this array variable may be used to modify
3967 directories already in the stack, but the @code{pushd} and @code{popd}
3968 builtins must be used to add and remove directories.
3969 Assignment to this variable will not change the current directory.
3970 If @env{DIRSTACK} is unset, it loses its special properties, even if
3971 it is subsequently reset.
3972
3973 @item EUID
3974 The numeric effective user id of the current user. This variable
3975 is readonly.
3976
3977 @item FCEDIT
3978 The editor used as a default by the @option{-e} option to the @code{fc}
3979 builtin command.
3980
3981 @item FIGNORE
3982 A colon-separated list of suffixes to ignore when performing
3983 filename completion.
3984 A file name whose suffix matches one of the entries in
3985 @env{FIGNORE}
3986 is excluded from the list of matched file names. A sample
3987 value is @samp{.o:~}
3988
3989 @item GLOBIGNORE
3990 A colon-separated list of patterns defining the set of filenames to
3991 be ignored by filename expansion.
3992 If a filename matched by a filename expansion pattern also matches one
3993 of the patterns in @env{GLOBIGNORE}, it is removed from the list
3994 of matches.
3995
3996 @item GROUPS
3997 An array variable containing the list of groups of which the current
3998 user is a member.
3999 Assignments to @env{GROUPS} have no effect and return an error status.
4000 If @env{GROUPS} is unset, it loses its special properties, even if it is
4001 subsequently reset.
4002
4003 @item histchars
4004 Up to three characters which control history expansion, quick
4005 substitution, and tokenization (@pxref{History Interaction}).
4006 The first character is the
4007 @var{history expansion} character, that is, the character which signifies the
4008 start of a history expansion, normally @samp{!}. The second character is the
4009 character which signifies `quick substitution' when seen as the first
4010 character on a line, normally @samp{^}. The optional third character is the
4011 character which indicates that the remainder of the line is a comment when
4012 found as the first character of a word, usually @samp{#}. The history
4013 comment character causes history substitution to be skipped for the
4014 remaining words on the line. It does not necessarily cause the shell
4015 parser to treat the rest of the line as a comment.
4016
4017 @item HISTCMD
4018 The history number, or index in the history list, of the current
4019 command. If @env{HISTCMD} is unset, it loses its special properties,
4020 even if it is subsequently reset.
4021
4022 @item FUNCNAME
4023 The name of any currently-executing shell function.
4024 This variable exists only when a shell function is executing.
4025 Assignments to @env{FUNCNAME} have no effect and return an error status.
4026 If @env{FUNCNAME} is unset, it loses its special properties, even if
4027 it is subsequently reset.
4028
4029 @item HISTCONTROL
4030 A value of @samp{ignorespace} means to not enter lines which
4031 begin with a space or tab into the history list.
4032 A value of @samp{ignoredups} means to not enter lines which match the last
4033 entered line.
4034 A value of @samp{ignoreboth} combines the two options.
4035 Unset, or set to any other value than those above, means to save
4036 all lines on the history list.
4037 The second and subsequent lines of a multi-line compound command are
4038 not tested, and are added to the history regardless of the value of
4039 @env{HISTCONTROL}.
4040
4041 @item HISTIGNORE
4042 A colon-separated list of patterns used to decide which command
4043 lines should be saved on the history list. Each pattern is
4044 anchored at the beginning of the line and must match the complete
4045 line (no implicit @samp{*} is appended). Each pattern is tested
4046 against the line after the checks specified by @env{HISTCONTROL}
4047 are applied. In addition to the normal shell pattern matching
4048 characters, @samp{&} matches the previous history line. @samp{&}
4049 may be escaped using a backslash; the backslash is removed
4050 before attempting a match.
4051 The second and subsequent lines of a multi-line compound command are
4052 not tested, and are added to the history regardless of the value of
4053 @env{HISTIGNORE}.
4054
4055 @env{HISTIGNORE} subsumes the function of @env{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}.
4060
4061 @item HISTFILE
4062 The name of the file to which the command history is saved. The
4063 default value is @file{~/.bash_history}.
4064
4065 @item HISTSIZE
4066 The maximum number of commands to remember on the history list.
4067 The default value is 500.
4068
4069 @item HISTFILESIZE
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.
4073 The history file is also truncated to this size after
4074 writing it when an interactive shell exits.
4075 The default value is 500.
4076
4077 @item HOSTFILE
4078 Contains the name of a file in the same format as @file{/etc/hosts} that
4079 should be read when the shell needs to complete a hostname.
4080 The list of possible hostname completions may be changed while the shell
4081 is running;
4082 the next time hostname completion is attempted after the
4083 value is changed, Bash adds the contents of the new file to the
4084 existing list.
4085 If @env{HOSTFILE} is set, but has no value, Bash attempts to read
4086 @file{/etc/hosts} to obtain the list of possible hostname completions.
4087 When @env{HOSTFILE} is unset, the hostname list is cleared.
4088
4089 @item HOSTNAME
4090 The name of the current host.
4091
4092 @item HOSTTYPE
4093 A string describing the machine Bash is running on.
4094
4095 @item IGNOREEOF
4096 Controls the action of the shell on receipt of an @code{EOF} character
4097 as the sole input. If set, the value denotes the number
4098 of consecutive @code{EOF} characters that can be read as the
4099 first character on an input line
4100 before the shell will exit. If the variable exists but does not
4101 have a numeric value (or has no value) then the default is 10.
4102 If the variable does not exist, then @code{EOF} signifies the end of
4103 input to the shell. This is only in effect for interactive shells.
4104
4105 @item INPUTRC
4106 The name of the Readline initialization file, overriding the default
4107 of @file{~/.inputrc}.
4108
4109 @item LANG
4110 Used to determine the locale category for any category not specifically
4111 selected with a variable starting with @code{LC_}.
4112
4113 @item LC_ALL
4114 This variable overrides the value of @env{LANG} and any other
4115 @code{LC_} variable specifying a locale category.
4116
4117 @item LC_COLLATE
4118 This variable determines the collation order used when sorting the
4119 results of filename expansion, and
4120 determines the behavior of range expressions, equivalence classes,
4121 and collating sequences within filename expansion and pattern matching
4122 (@pxref{Filename Expansion}).
4123
4124 @item LC_CTYPE
4125 This variable determines the interpretation of characters and the
4126 behavior of character classes within filename expansion and pattern
4127 matching (@pxref{Filename Expansion}).
4128
4129 @item LC_MESSAGES
4130 This variable determines the locale used to translate double-quoted
4131 strings preceded by a @samp{$} (@pxref{Locale Translation}).
4132
4133 @item LC_NUMERIC
4134 This variable determines the locale category used for number formatting.
4135
4136 @item LINES
4137 Used by the @code{select} builtin command to determine the column length
4138 for printing selection lists. Automatically set upon receipt of a
4139 @code{SIGWINCH}.
4140
4141 @item COLUMNS
4142 Used by the @code{select} builtin command to determine the terminal width
4143 when printing selection lists. Automatically set upon receipt of a
4144 @code{SIGWINCH}.
4145
4146 @item LINENO
4147 The line number in the script or shell function currently executing.
4148
4149 @item MACHTYPE
4150 A string that fully describes the system type on which Bash
4151 is executing, in the standard @sc{gnu} @var{cpu-company-system} format.
4152
4153 @item MAILCHECK
4154 How often (in seconds) that the shell should check for mail in the
4155 files specified in the @env{MAILPATH} or @env{MAIL} variables.
4156 The default is 60 seconds. When it is time to check
4157 for mail, the shell does so before displaying the primary prompt.
4158 If this variable is unset, or set to a value that is not a number
4159 greater than or equal to zero, the shell disables mail checking.
4160
4161 @item OLDPWD
4162 The previous working directory as set by the @code{cd} builtin.
4163
4164 @item OPTERR
4165 If set to the value 1, Bash displays error messages
4166 generated by the @code{getopts} builtin command.
4167
4168 @item OSTYPE
4169 A string describing the operating system Bash is running on.
4170
4171 @item PIPESTATUS
4172 An array variable (@pxref{Arrays})
4173 containing a list of exit status values from the processes
4174 in the most-recently-executed foreground pipeline (which may
4175 contain only a single command).
4176
4177 @item PPID
4178 The process @sc{id} of the shell's parent process. This variable
4179 is readonly.
4180
4181 @item PROMPT_COMMAND
4182 If set, the value is interpreted as a command to execute
4183 before the printing of each primary prompt (@env{$PS1}).
4184
4185 @item PS3
4186 The value of this variable is used as the prompt for the
4187 @code{select} command. If this variable is not set, the
4188 @code{select} command prompts with @samp{#? }
4189
4190 @item PS4
4191 The value is the prompt printed before the command line is echoed
4192 when the @option{-x} option is set (@pxref{The Set Builtin}).
4193 The first character of @env{PS4} is replicated multiple times, as
4194 necessary, to indicate multiple levels of indirection.
4195 The default is @samp{+ }.
4196
4197 @item PWD
4198 The current working directory as set by the @code{cd} builtin.
4199
4200 @item RANDOM
4201 Each time this parameter is referenced, a random integer
4202 between 0 and 32767 is generated. Assigning a value to this
4203 variable seeds the random number generator.
4204
4205 @item REPLY
4206 The default variable for the @code{read} builtin.
4207
4208 @item SECONDS
4209 This variable expands to the number of seconds since the
4210 shell was started. Assignment to this variable resets
4211 the count to the value assigned, and the expanded value
4212 becomes the value assigned plus the number of seconds
4213 since the assignment.
4214
4215 @item SHELLOPTS
4216 A colon-separated list of enabled shell options. Each word in
4217 the list is a valid argument for the @option{-o} option to the
4218 @code{set} builtin command (@pxref{The Set Builtin}).
4219 The options appearing in @env{SHELLOPTS} are those reported
4220 as @samp{on} by @samp{set -o}.
4221 If this variable is in the environment when Bash
4222 starts up, each shell option in the list will be enabled before
4223 reading any startup files. This variable is readonly.
4224
4225 @item SHLVL
4226 Incremented by one each time a new instance of Bash is started. This is
4227 intended to be a count of how deeply your Bash shells are nested.
4228
4229 @item TIMEFORMAT
4230 The value of this parameter is used as a format string specifying
4231 how the timing information for pipelines prefixed with the @code{time}
4232 reserved word should be displayed.
4233 The @samp{%} character introduces an
4234 escape sequence that is expanded to a time value or other
4235 information.
4236 The escape sequences and their meanings are as
4237 follows; the braces denote optional portions.
4238
4239 @table @code
4240
4241 @item %%
4242 A literal @samp{%}.
4243
4244 @item %[@var{p}][l]R
4245 The elapsed time in seconds.
4246
4247 @item %[@var{p}][l]U
4248 The number of CPU seconds spent in user mode.
4249
4250 @item %[@var{p}][l]S
4251 The number of CPU seconds spent in system mode.
4252
4253 @item %P
4254 The CPU percentage, computed as (%U + %S) / %R.
4255 @end table
4256
4257 The optional @var{p} is a digit specifying the precision, the number of
4258 fractional digits after a decimal point.
4259 A value of 0 causes no decimal point or fraction to be output.
4260 At most three places after the decimal point may be specified; values
4261 of @var{p} greater than 3 are changed to 3.
4262 If @var{p} is not specified, the value 3 is used.
4263
4264 The optional @code{l} specifies a longer format, including minutes, of
4265 the form @var{MM}m@var{SS}.@var{FF}s.
4266 The value of @var{p} determines whether or not the fraction is included.
4267
4268 If this variable is not set, Bash acts as if it had the value
4269 @example
4270 @code{$'\nreal\t%3lR\nuser\t%3lU\nsys\t%3lS'}
4271 @end example
4272 If the value is null, no timing information is displayed.
4273 A trailing newline is added when the format string is displayed.
4274
4275 @item TMOUT
4276 If set to a value greater than zero, the value is interpreted as
4277 the number of seconds to wait for input after issuing the primary
4278 prompt when the shell is interactive.
4279 Bash terminates after that number of seconds if input does
4280 not arrive.
4281
4282 @item UID
4283 The numeric real user id of the current user. This variable is readonly.
4284
4285 @end vtable
4286
4287 @node Bash Features
4288 @chapter Bash Features
4289
4290 This section describes features unique to Bash.
4291
4292 @menu
4293 * Invoking Bash:: Command line options that you can give
4294 to Bash.
4295 * Bash Startup Files:: When and how Bash executes scripts.
4296 * Interactive Shells:: What an interactive shell is.
4297 * Bash Conditional Expressions:: Primitives used in composing expressions for
4298 the @code{test} builtin.
4299 * Shell Arithmetic:: Arithmetic on shell variables.
4300 * Aliases:: Substituting one command for another.
4301 * Arrays:: Array Variables.
4302 * The Directory Stack:: History of visited directories.
4303 * Printing a Prompt:: Controlling the PS1 string.
4304 * The Restricted Shell:: A more controlled mode of shell execution.
4305 * Bash POSIX Mode:: Making Bash behave more closely to what
4306 the POSIX standard specifies.
4307 @end menu
4308
4309 @node Invoking Bash
4310 @section Invoking Bash
4311
4312 @example
4313 bash [long-opt] [-ir] [-abefhkmnptuvxdBCDHP] [-o @var{option}] [@var{argument} @dots{}]
4314 bash [long-opt] [-abefhkmnptuvxdBCDHP] [-o @var{option}] -c @var{string} [@var{argument} @dots{}]
4315 bash [long-opt] -s [-abefhkmnptuvxdBCDHP] [-o @var{option}] [@var{argument} @dots{}]
4316 @end example
4317
4318 In addition to the single-character shell command-line options
4319 (@pxref{The Set Builtin}), there are several multi-character
4320 options that you can use. These options must appear on the command
4321 line before the single-character options in order for them
4322 to be recognized.
4323
4324 @table @code
4325 @item --dump-po-strings
4326 A list of all double-quoted strings preceded by @samp{$}
4327 is printed on the standard ouput
4328 in the @sc{gnu} @code{gettext} PO (portable object) file format.
4329 Equivalent to @option{-D} except for the output format.
4330
4331 @item --dump-strings
4332 Equivalent to @option{-D}.
4333
4334 @item --help
4335 Display a usage message on standard output and exit sucessfully.
4336
4337 @item --init-file @var{filename}
4338 @itemx --rcfile @var{filename}
4339 Execute commands from @var{filename} (instead of @file{~/.bashrc})
4340 in an interactive shell.
4341
4342 @item --login
4343 Make this shell act as if it had been directly invoked by login.
4344 When the shell is interactive, this is equivalent to starting a
4345 login shell with @samp{exec -l bash}.
4346 When the shell is not interactive, the login shell startup files will
4347 be executed.
4348 @samp{exec bash --login}
4349 will replace the current shell with a Bash login shell.
4350 @xref{Bash Startup Files}, for a description of the special behavior
4351 of a login shell.
4352
4353 @item --noediting
4354 Do not use the @sc{gnu} Readline library (@pxref{Command Line Editing})
4355 to read command lines when the shell is interactive.
4356
4357 @item --noprofile
4358 Don't load the system-wide startup file @file{/etc/profile}
4359 or any of the personal initialization files
4360 @file{~/.bash_profile}, @file{~/.bash_login}, or @file{~/.profile}
4361 when Bash is invoked as a login shell.
4362
4363 @item --norc
4364 Don't read the @file{~/.bashrc} initialization file in an
4365 interactive shell. This is on by default if the shell is
4366 invoked as @code{sh}.
4367
4368 @item --posix
4369 Change the behavior of Bash where the default operation differs
4370 from the @sc{posix} 1003.2 standard to match the standard. This
4371 is intended to make Bash behave as a strict superset of that
4372 standard. @xref{Bash POSIX Mode}, for a description of the Bash
4373 @sc{posix} mode.
4374
4375 @item --restricted
4376 Make the shell a restricted shell (@pxref{The Restricted Shell}).
4377
4378 @item --verbose
4379 Equivalent to @option{-v}. Print shell input lines as they're read.
4380
4381 @item --version
4382 Show version information for this instance of
4383 Bash on the standard output and exit successfully.
4384
4385 @end table
4386
4387 There are several single-character options that may be supplied at
4388 invocation which are not available with the @code{set} builtin.
4389
4390 @table @code
4391 @item -c @var{string}
4392 Read and execute commands from @var{string} after processing the
4393 options, then exit. Any remaining arguments are assigned to the
4394 positional parameters, starting with @code{$0}.
4395
4396 @item -i
4397 Force the shell to run interactively. Interactive shells are
4398 described in @ref{Interactive Shells}.
4399
4400 @item -r
4401 Make the shell a restricted shell (@pxref{The Restricted Shell}).
4402
4403 @item -s
4404 If this option is present, or if no arguments remain after option
4405 processing, then commands are read from the standard input.
4406 This option allows the positional parameters to be set
4407 when invoking an interactive shell.
4408
4409 @item -D
4410 A list of all double-quoted strings preceded by @samp{$}
4411 is printed on the standard ouput.
4412 These are the strings that
4413 are subject to language translation when the current locale
4414 is not @code{C} or @code{POSIX} (@pxref{Locale Translation}).
4415 This implies the @option{-n} option; no commands will be executed.
4416
4417 @item --
4418 A @code{--} signals the end of options and disables further option
4419 processing.
4420 Any arguments after the @code{--} are treated as filenames and arguments.
4421
4422 @end table
4423
4424 @cindex interactive shell
4425 An @emph{interactive} shell is one started without non-option arguments,
4426 unless @option{-s} is specified,
4427 without specifying the @option{-c} option, and whose input and output are both
4428 connected to terminals (as determined by @code{isatty(3)}), or one
4429 started with the @option{-i} option. @xref{Interactive Shells}, for more
4430 information.
4431
4432 If arguments remain after option processing, and neither the
4433 @option{-c} nor the @option{-s}
4434 option has been supplied, the first argument is assumed to
4435 be the name of a file containing shell commands (@pxref{Shell Scripts}).
4436 When Bash is invoked in this fashion, @code{$0}
4437 is set to the name of the file, and the positional parameters
4438 are set to the remaining arguments.
4439 Bash reads and executes commands from this file, then exits.
4440 Bash's exit status is the exit status of the last command executed
4441 in the script. If no commands are executed, the exit status is 0.
4442
4443 @node Bash Startup Files
4444 @section Bash Startup Files
4445 @cindex startup files
4446
4447 This section describs how Bash executes its startup files.
4448 If any of the files exist but cannot be read, Bash reports an error.
4449 Tildes are expanded in file names as described above under
4450 Tilde Expansion (@pxref{Tilde Expansion}).
4451
4452 Interactive shells are described in @ref{Interactive Shells}.
4453
4454 @subsubheading Invoked as an interactive login shell, or with @option{--login}
4455
4456 When Bash is invoked as an interactive login shell, or as a
4457 non-interactive shell with the @option{--login} option, it first reads and
4458 executes commands from the file @file{/etc/profile}, if that file exists.
4459 After reading that file, it looks for @file{~/.bash_profile},
4460 @file{~/.bash_login}, and @file{~/.profile}, in that order, and reads
4461 and executes commands from the first one that exists and is readable.
4462 The @option{--noprofile} option may be used when the shell is started to
4463 inhibit this behavior.
4464
4465 When a login shell exits, Bash reads and executes commands from
4466 the file @file{~/.bash_logout}, if it exists.
4467
4468 @subsubheading Invoked as an interactive non-login shell
4469
4470 When an interactive shell that is not a login shell is started, Bash
4471 reads and executes commands from @file{~/.bashrc}, if that file exists.
4472 This may be inhibited by using the @option{--norc} option.
4473 The @option{--rcfile @var{file}} option will force Bash to read and
4474 execute commands from @var{file} instead of @file{~/.bashrc}.
4475
4476 So, typically, your @file{~/.bash_profile} contains the line
4477 @example
4478 @code{if [ -f ~/.bashrc ]; then . ~/.bashrc; fi}
4479 @end example
4480 @noindent
4481 after (or before) any login-specific initializations.
4482
4483 @subsubheading Invoked non-interactively
4484
4485 When Bash is started non-interactively, to run a shell script,
4486 for example, it looks for the variable @env{BASH_ENV} in the environment,
4487 expands its value if it appears there, and uses the expanded value as
4488 the name of a file to read and execute. Bash behaves as if the
4489 following command were executed:
4490 @example
4491 @code{if [ -n "$BASH_ENV" ]; then . "$BASH_ENV"; fi}
4492 @end example
4493 @noindent
4494 but the value of the @env{PATH} variable is not used to search for the
4495 file name.
4496
4497 As noted above, if a non-interactive shell is invoked with the
4498 @option{--login} option, Bash attempts to read and execute commands from the
4499 login shell startup files.
4500
4501 @subsubheading Invoked with name @code{sh}
4502
4503 If Bash is invoked with the name @code{sh}, it tries to mimic the
4504 startup behavior of historical versions of @code{sh} as closely as
4505 possible, while conforming to the @sc{posix} standard as well.
4506
4507 When invoked as an interactive login shell, or as a non-interactive
4508 shell with the @option{--login} option, it first attempts to read
4509 and execute commands from @file{/etc/profile} and @file{~/.profile}, in
4510 that order.
4511 The @option{--noprofile} option may be used to inhibit this behavior.
4512 When invoked as an interactive shell with the name @code{sh}, Bash
4513 looks for the variable @env{ENV}, expands its value if it is defined,
4514 and uses the expanded value as the name of a file to read and execute.
4515 Since a shell invoked as @code{sh} does not attempt to read and execute
4516 commands from any other startup files, the @option{--rcfile} option has
4517 no effect.
4518 A non-interactive shell invoked with the name @code{sh} does not attempt
4519 to read any other startup files.
4520
4521 When invoked as @code{sh}, Bash enters @sc{posix} mode after
4522 the startup files are read.
4523
4524 @subsubheading Invoked in @sc{posix} mode
4525
4526 When Bash is started in @sc{posix} mode, as with the
4527 @option{--posix} command line option, it follows the @sc{posix} standard
4528 for startup files.
4529 In this mode, interactive shells expand the @env{ENV} variable
4530 and commands are read and executed from the file whose name is the
4531 expanded value.
4532 No other startup files are read.
4533
4534 @subsubheading Invoked by remote shell daemon
4535
4536 Bash attempts to determine when it is being run by the remote shell
4537 daemon, usually @code{rshd}. If Bash determines it is being run by
4538 rshd, it reads and executes commands from @file{~/.bashrc}, if that
4539 file exists and is readable.
4540 It will not do this if invoked as @code{sh}.
4541 The @option{--norc} option may be used to inhibit this behavior, and the
4542 @option{--rcfile} option may be used to force another file to be read, but
4543 @code{rshd} does not generally invoke the shell with those options or
4544 allow them to be specified.
4545
4546 @subsubheading Invoked with unequal effective and real @sc{uid/gid}s
4547
4548 If Bash is started with the effective user (group) id not equal to the
4549 real user (group) id, and the @code{-p} option is not supplied, no startup
4550 files are read, shell functions are not inherited from the environment,
4551 the @env{SHELLOPTS} variable, if it appears in the environment, is ignored,
4552 and the effective user id is set to the real user id.
4553 If the @code{-p} option is supplied at invocation, the startup behavior is
4554 the same, but the effective user id is not reset.
4555
4556 @node Interactive Shells
4557 @section Interactive Shells
4558 @cindex interactive shell
4559 @cindex shell, interactive
4560
4561 @menu
4562 * What is an Interactive Shell?:: What determines whether a shell is Interactive.
4563 * Is this Shell Interactive?:: How to tell if a shell is interactive.
4564 * Interactive Shell Behavior:: What changes in a interactive shell?
4565 @end menu
4566
4567 @node What is an Interactive Shell?
4568 @subsection What is an Interactive Shell?
4569
4570 An interactive shell
4571 is one started without non-option arguments, unless @option{-s} is
4572 specified, without specifiying the @option{-c} option, and
4573 whose input and output are both
4574 connected to terminals (as determined by @code{isatty(3)}),
4575 or one started with the @option{-i} option.
4576
4577 An interactive shell generally reads from and writes to a user's
4578 terminal.
4579
4580 The @option{-s} invocation option may be used to set the positional parameters
4581 when an interactive shell is started.
4582
4583 @node Is this Shell Interactive?
4584 @subsection Is this Shell Interactive?
4585
4586 To determine within a startup script whether or not Bash is
4587 running interactively,
4588 test the value of the @samp{-} special parameter.
4589 It contains @code{i} when the shell is interactive. For example:
4590
4591 @example
4592 case "$-" in
4593 *i*) echo This shell is interactive ;;
4594 *) echo This shell is not interactive ;;
4595 esac
4596 @end example
4597
4598 Alternatively, startup scripts may examine the variable
4599 @env{PS1}; it is unset in non-interactive shells, and set in
4600 interactive shells. Thus:
4601
4602 @example
4603 if [ -z "$PS1" ]; then
4604 echo This shell is not interactive
4605 else
4606 echo This shell is interactive
4607 fi
4608 @end example
4609
4610 @node Interactive Shell Behavior
4611 @subsection Interactive Shell Behavior
4612
4613 When the shell is running interactively, it changes its behavior in
4614 several ways.
4615
4616 @enumerate
4617 @item
4618 Startup files are read and executed as described in @ref{Bash Startup Files}.
4619
4620 @item
4621 Job Control (@pxref{Job Control}) is enabled by default. When job
4622 control is in effect, Bash ignores the keyboard-generated job control
4623 signals @code{SIGTTIN}, @code{SIGTTOU}, and @code{SIGTSTP}.
4624
4625 @item
4626 Bash expands and displays @env{PS1} before reading the first line
4627 of a command, and expands and displays @env{PS2} before reading the
4628 second and subsequent lines of a multi-line command.
4629
4630 @item
4631 Bash executes the value of the @env{PROMPT_COMMAND} variable as a command
4632 before printing the primary prompt, @env{$PS1}
4633 (@pxref{Bash Variables}).
4634
4635 @item
4636 Readline (@pxref{Command Line Editing}) is used to read commands from
4637 the user's terminal.
4638
4639 @item
4640 Bash inspects the value of the @code{ignoreeof} option to @code{set -o}
4641 instead of exiting immediately when it receives an @code{EOF} on its
4642 standard input when reading a command (@pxref{The Set Builtin}).
4643
4644 @item
4645 Command history (@pxref{Bash History Facilities})
4646 and history expansion (@pxref{History Interaction})
4647 are enabled by default.
4648 Bash will save the command history to the file named by @env{$HISTFILE}
4649 when an interactive shell exits.
4650
4651 @item
4652 Alias expansion (@pxref{Aliases}) is performed by default.
4653
4654 @item
4655 In the absence of any traps, Bash ignores @code{SIGTERM}
4656 (@pxref{Signals}).
4657
4658 @item
4659 In the absence of any traps, @code{SIGINT} is caught and handled
4660 ((@pxref{Signals}).
4661 @code{SIGINT} will interrupt some shell builtins.
4662
4663 @item
4664 An interactive login shell sends a @code{SIGHUP} to all jobs on exit
4665 if the @code{hupoxexit} shell option has been enabled (@pxref{Signals}).
4666
4667 @item
4668 The @option{-n} invocation option is ignored, and @samp{set -n} has
4669 no effect (@pxref{The Set Builtin}).
4670
4671 @item
4672 Bash will check for mail periodically, depending on the values of the
4673 @env{MAIL}, @env{MAILPATH}, and @env{MAILCHECK} shell variables
4674 (@pxref{Bash Variables}).
4675
4676 @item
4677 Expansion errors due to references to unbound shell variables after
4678 @samp{set -u} has been enabled will not cause the shell to exit
4679 (@pxref{The Set Builtin}).
4680
4681 @item
4682 The shell will not exit on expansion errors caused by @var{var} being unset
4683 or null in @code{$@{@var{var}:?@var{word}@}} expansions
4684 (@pxref{Shell Parameter Expansion}).
4685
4686 @item
4687 Redirection errors encountered by shell builtins will not cause the
4688 shell to exit.
4689
4690 @item
4691 When running in @sc{posix} mode, a special builtin returning an error
4692 status will not cause the shell to exit (@pxref{Bash POSIX Mode}).
4693 @item
4694 A failed @code{exec} will not cause the shell to exit
4695 (@pxref{Bourne Shell Builtins}).
4696
4697 @item
4698 Parser syntax errors will not cause the shell to exit.
4699
4700 @item
4701 Simple spelling correction for directory arguments to the @code{cd}
4702 builtin is enabled by default (see the description of the @code{cdspell}
4703 option to the @code{shopt} builtin in @ref{Bash Builtins}).
4704
4705 @item
4706 The shell will check the value of the @env{TMOUT} variable and exit
4707 if a command is not read within the specified number of seconds after
4708 printing @env{$PS1} (@pxref{Bash Variables}).
4709
4710 @end enumerate
4711
4712 @node Bash Conditional Expressions
4713 @section Bash Conditional Expressions
4714 @cindex expressions, conditional
4715
4716 Conditional expressions are used by the @code{[[} compound command
4717 and the @code{test} and @code{[} builtin commands.
4718
4719 Expressions may be unary or binary.
4720 Unary expressions are often used to examine the status of a file.
4721 There are string operators and numeric comparison operators as well.
4722 If the @var{file} argument to one of the primaries is of the form
4723 @file{/dev/fd/@var{N}}, then file descriptor @var{N} is checked.
4724 If the @var{file} argument to one of the primaries is one of
4725 @file{/dev/stdin}, @file{/dev/stdout}, or @file{/dev/stderr}, file
4726 descriptor 0, 1, or 2, respectively, is checked.
4727
4728 @table @code
4729 @item -a @var{file}
4730 True if @var{file} exists.
4731
4732 @item -b @var{file}
4733 True if @var{file} exists and is a block special file.
4734
4735 @item -c @var{file}
4736 True if @var{file} exists and is a character special file.
4737
4738 @item -d @var{file}
4739 True if @var{file} exists and is a directory.
4740
4741 @item -e @var{file}
4742 True if @var{file} exists.
4743
4744 @item -f @var{file}
4745 True if @var{file} exists and is a regular file.
4746
4747 @item -g @var{file}
4748 True if @var{file} exists and its set-group-id bit is set.
4749
4750 @item -h @var{file}
4751 True if @var{file} exists and is a symbolic link.
4752
4753 @item -k @var{file}
4754 True if @var{file} exists and its "sticky" bit is set.
4755
4756 @item -p @var{file}
4757 True if @var{file} exists and is a named pipe (FIFO).
4758
4759 @item -r @var{file}
4760 True if @var{file} exists and is readable.
4761
4762 @item -s @var{file}
4763 True if @var{file} exists and has a size greater than zero.
4764
4765 @item -t @var{fd}
4766 True if file descriptor @var{fd} is open and refers to a terminal.
4767
4768 @item -u @var{file}
4769 True if @var{file} exists and its set-user-id bit is set.
4770
4771 @item -w @var{file}
4772 True if @var{file} exists and is writable.
4773
4774 @item -x @var{file}
4775 True if @var{file} exists and is executable.
4776
4777 @item -O @var{file}
4778 True if @var{file} exists and is owned by the effective user id.
4779
4780 @item -G @var{file}
4781 True if @var{file} exists and is owned by the effective group id.
4782
4783 @item -L @var{file}
4784 True if @var{file} exists and is a symbolic link.
4785
4786 @item -S @var{file}
4787 True if @var{file} exists and is a socket.
4788
4789 @item -N @var{file}
4790 True if @var{file} exists and has been modified since it was last read.
4791
4792 @item @var{file1} -nt @var{file2}
4793 True if @var{file1} is newer (according to
4794 modification date) than @var{file2}.
4795
4796 @item @var{file1} -ot @var{file2}
4797 True if @var{file1} is older than @var{file2}.
4798
4799 @item @var{file1} -ef @var{file2}
4800 True if @var{file1} and @var{file2} have the same device and
4801 inode numbers.
4802
4803 @item -o @var{optname}
4804 True if shell option @var{optname} is enabled.
4805 The list of options appears in the description of the @option{-o}
4806 option to the @code{set} builtin (@pxref{The Set Builtin}).
4807
4808 @item -z @var{string}
4809 True if the length of @var{string} is zero.
4810
4811 @item -n @var{string}
4812 @itemx @var{string}
4813 True if the length of @var{string} is non-zero.
4814
4815 @item @var{string1} == @var{string2}
4816 True if the strings are equal.
4817 @samp{=} may be used in place of @samp{==}.
4818
4819 @item @var{string1} != @var{string2}
4820 True if the strings are not equal.
4821
4822 @item @var{string1} < @var{string2}
4823 True if @var{string1} sorts before @var{string2} lexicographically
4824 in the current locale.
4825
4826 @item @var{string1} > @var{string2}
4827 True if @var{string1} sorts after @var{string2} lexicographically
4828 in the current locale.
4829
4830 @item @var{arg1} OP @var{arg2}
4831 @code{OP} is one of
4832 @samp{-eq}, @samp{-ne}, @samp{-lt}, @samp{-le}, @samp{-gt}, or @samp{-ge}.
4833 These arithmetic binary operators return true if @var{arg1}
4834 is equal to, not equal to, less than, less than or equal to,
4835 greater than, or greater than or equal to @var{arg2},
4836 respectively. @var{Arg1} and @var{arg2}
4837 may be positive or negative integers.
4838
4839 @end table
4840
4841 @node Shell Arithmetic
4842 @section Shell Arithmetic
4843 @cindex arithmetic, shell
4844 @cindex shell arithmetic
4845 @cindex expressions, arithmetic
4846 @cindex evaluation, arithmetic
4847 @cindex arithmetic evaluation
4848
4849 The shell allows arithmetic expressions to be evaluated, as one of
4850 the shell expansions or by the @code{let} builtin.
4851
4852 Evaluation is done in long integers with no check for overflow,
4853 though division by 0 is trapped and flagged as an error.
4854 The operators and their precedence and associativity are the same
4855 as in the C language.
4856 The following list of operators is grouped into levels of
4857 equal-precedence operators.
4858 The levels are listed in order of decreasing precedence.
4859
4860 @table @code
4861
4862 @item @var{id}++ @var{id}--
4863 variable post-increment and post-decrement
4864
4865 @item ++@var{id} --@var{id}
4866 variable pre-increment and pre-decrement
4867
4868 @item - +
4869 unary minus and plus
4870
4871 @item ! ~
4872 logical and bitwise negation
4873
4874 @item **
4875 exponentiation
4876
4877 @item * / %
4878 multiplication, division, remainder
4879
4880 @item + -
4881 addition, subtraction
4882
4883 @item << >>
4884 left and right bitwise shifts
4885
4886 @item <= >= < >
4887 comparison
4888
4889 @item == !=
4890 equality and inequality
4891
4892 @item &
4893 bitwise AND
4894
4895 @item ^
4896 bitwise exclusive OR
4897
4898 @item |
4899 bitwise OR
4900
4901 @item &&
4902 logical AND
4903
4904 @item ||
4905 logical OR
4906
4907 @item expr ? expr : expr
4908 conditional evaluation
4909
4910 @item = *= /= %= += -= <<= >>= &= ^= |=
4911 assignment
4912
4913 @item expr1 , expr2
4914 comma
4915 @end table
4916
4917 Shell variables are allowed as operands; parameter expansion is
4918 performed before the expression is evaluated.
4919 Within an expression, shell variables may also be referenced by name
4920 without using the parameter expansion syntax.
4921 The value of a variable is evaluated as an arithmetic expression
4922 when it is referenced.
4923 A shell variable need not have its integer attribute turned on
4924 to be used in an expression.
4925
4926 Constants with a leading 0 are interpreted as octal numbers.
4927 A leading @samp{0x} or @samp{0X} denotes hexadecimal. Otherwise,
4928 numbers take the form [@var{base}@code{#}]@var{n}, where @var{base}
4929 is a decimal number between 2 and 64 representing the arithmetic
4930 base, and @var{n} is a number in that base. If @var{base}@code{#} is
4931 omitted, then base 10 is used.
4932 The digits greater than 9 are represented by the lowercase letters,
4933 the uppercase letters, @samp{_}, and @samp{@@}, in that order.
4934 If @var{base} is less than or equal to 36, lowercase and uppercase
4935 letters may be used interchangably to represent numbers between 10
4936 and 35.
4937
4938 Operators are evaluated in order of precedence. Sub-expressions in
4939 parentheses are evaluated first and may override the precedence
4940 rules above.
4941
4942 @node Aliases
4943 @section Aliases
4944 @cindex alias expansion
4945
4946 @var{Aliases} allow a string to be substituted for a word when it is used
4947 as the first word of a simple command.
4948 The shell maintains a list of aliases that may be set and unset with
4949 the @code{alias} and @code{unalias} builtin commands.
4950
4951 The first word of each simple command, if unquoted, is checked to see
4952 if it has an alias.
4953 If so, that word is replaced by the text of the alias.
4954 The alias name and the replacement text may contain any valid
4955 shell input, including shell metacharacters, with the exception
4956 that the alias name may not contain @samp{=}.
4957 The first word of the replacement text is tested for
4958 aliases, but a word that is identical to an alias being expanded
4959 is not expanded a second time. This means that one may alias
4960 @code{ls} to @code{"ls -F"},
4961 for instance, and Bash does not try to recursively expand the
4962 replacement text. If the last character of the alias value is a
4963 space or tab character, then the next command word following the
4964 alias is also checked for alias expansion.
4965
4966 Aliases are created and listed with the @code{alias}
4967 command, and removed with the @code{unalias} command.
4968
4969 There is no mechanism for using arguments in the replacement text,
4970 as in @code{csh}.
4971 If arguments are needed, a shell function should be used
4972 (@pxref{Shell Functions}).
4973
4974 Aliases are not expanded when the shell is not interactive,
4975 unless the @code{expand_aliases} shell option is set using
4976 @code{shopt} (@pxref{Bash Builtins}).
4977
4978 The rules concerning the definition and use of aliases are
4979 somewhat confusing. Bash
4980 always reads at least one complete line
4981 of input before executing any
4982 of the commands on that line. Aliases are expanded when a
4983 command is read, not when it is executed. Therefore, an
4984 alias definition appearing on the same line as another
4985 command does not take effect until the next line of input is read.
4986 The commands following the alias definition
4987 on that line are not affected by the new alias.
4988 This behavior is also an issue when functions are executed.
4989 Aliases are expanded when a function definition is read,
4990 not when the function is executed, because a function definition
4991 is itself a compound command. As a consequence, aliases
4992 defined in a function are not available until after that
4993 function is executed. To be safe, always put
4994 alias definitions on a separate line, and do not use @code{alias}
4995 in compound commands.
4996
4997 For almost every purpose, shell functions are preferred over aliases.
4998
4999 @node Arrays
5000 @section Arrays
5001 @cindex arrays
5002
5003 Bash provides one-dimensional array variables. Any variable may be used as
5004 an array; the @code{declare} builtin will explicitly declare an array.
5005 There is no maximum
5006 limit on the size of an array, nor any requirement that members
5007 be indexed or assigned contiguously. Arrays are zero-based.
5008
5009 An array is created automatically if any variable is assigned to using
5010 the syntax
5011 @example
5012 name[@var{subscript}]=@var{value}
5013 @end example
5014
5015 @noindent
5016 The @var{subscript}
5017 is treated as an arithmetic expression that must evaluate to a number
5018 greater than or equal to zero. To explicitly declare an array, use
5019 @example
5020 declare -a @var{name}
5021 @end example
5022 @noindent
5023 The syntax
5024 @example
5025 declare -a @var{name}[@var{subscript}]
5026 @end example
5027 @noindent
5028 is also accepted; the @var{subscript} is ignored. Attributes may be
5029 specified for an array variable using the @code{declare} and
5030 @code{readonly} builtins. Each attribute applies to all members of
5031 an array.
5032
5033 Arrays are assigned to using compound assignments of the form
5034 @example
5035 name=(value@var{1} @dots{} value@var{n})
5036 @end example
5037 @noindent
5038 where each
5039 @var{value} is of the form @code{[[@var{subscript}]=]}@var{string}. If
5040 the optional subscript is supplied, that index is assigned to;
5041 otherwise the index of the element assigned is the last index assigned
5042 to by the statement plus one. Indexing starts at zero.
5043 This syntax is also accepted by the @code{declare}
5044 builtin. Individual array elements may be assigned to using the
5045 @code{name[}@var{subscript}@code{]=}@var{value} syntax introduced above.
5046
5047 Any element of an array may be referenced using
5048 @code{$@{name[}@var{subscript}@code{]@}}.
5049 The braces are required to avoid
5050 conflicts with the shell's filename expansion operators. If the
5051 @var{subscript} is @samp{@@} or @samp{*}, the word expands to all members
5052 of the array @var{name}. These subscripts differ only when the word
5053 appears within double quotes. If the word is double-quoted,
5054 @code{$@{name[*]@}} expands to a single word with
5055 the value of each array member separated by the first character of the
5056 @env{IFS} variable, and @code{$@{name[@@]@}} expands each element of
5057 @var{name} to a separate word. When there are no array members,
5058 @code{$@{name[@@]@}} expands to nothing. This is analogous to the
5059 expansion of the special parameters @samp{@@} and @samp{*}.
5060 @code{$@{#name[}@var{subscript}@code{]@}} expands to the length of
5061 @code{$@{name[}@var{subscript}@code{]@}}.
5062 If @var{subscript} is @samp{@@} or
5063 @samp{*}, the expansion is the number of elements in the array.
5064 Referencing an array variable without a subscript is equivalent to
5065 referencing element zero.
5066
5067 The @code{unset} builtin is used to destroy arrays.
5068 @code{unset} @var{name[subscript]}
5069 destroys the array element at index @var{subscript}.
5070 @code{unset} @var{name}, where @var{name} is an array, removes the
5071 entire array. A subscript of @samp{*} or @samp{@@} also removes the
5072 entire array.
5073
5074 The @code{declare}, @code{local}, and @code{readonly}
5075 builtins each accept a @option{-a}
5076 option to specify an array. The @code{read}
5077 builtin accepts a @option{-a}
5078 option to assign a list of words read from the standard input
5079 to an array, and can read values from the standard input into
5080 individual array elements. The @code{set} and @code{declare}
5081 builtins display array values in a way that allows them to be
5082 reused as input.
5083
5084 @node The Directory Stack
5085 @section The Directory Stack
5086 @cindex directory stack
5087
5088 @menu
5089 * Directory Stack Builtins:: Bash builtin commands to manipulate
5090 the directory stack.
5091 @end menu
5092
5093 The directory stack is a list of recently-visited directories. The
5094 @code{pushd} builtin adds directories to the stack as it changes
5095 the current directory, and the @code{popd} builtin removes specified
5096 directories from the stack and changes the current directory to
5097 the directory removed. The @code{dirs} builtin displays the contents
5098 of the directory stack.
5099
5100 The contents of the directory stack are also visible
5101 as the value of the @env{DIRSTACK} shell variable.
5102
5103 @node Directory Stack Builtins
5104 @subsection Directory Stack Builtins
5105
5106 @table @code
5107
5108 @item dirs
5109 @btindex dirs
5110 @example
5111 dirs [+@var{N} | -@var{N}] [-clpv]
5112 @end example
5113 Display the list of currently remembered directories. Directories
5114 are added to the list with the @code{pushd} command; the
5115 @code{popd} command removes directories from the list.
5116 @table @code
5117 @item +@var{N}
5118 Displays the @var{N}th directory (counting from the left of the
5119 list printed by @code{dirs} when invoked without options), starting
5120 with zero.
5121 @item -@var{N}
5122 Displays the @var{N}th directory (counting from the right of the
5123 list printed by @code{dirs} when invoked without options), starting
5124 with zero.
5125 @item -c
5126 Clears the directory stack by deleting all of the elements.
5127 @item -l
5128 Produces a longer listing; the default listing format uses a
5129 tilde to denote the home directory.
5130 @item -p
5131 Causes @code{dirs} to print the directory stack with one entry per
5132 line.
5133 @item -v
5134 Causes @code{dirs} to print the directory stack with one entry per
5135 line, prefixing each entry with its index in the stack.
5136 @end table
5137
5138 @item popd
5139 @btindex popd
5140 @example
5141 popd [+@var{N} | -@var{N}] [-n]
5142 @end example
5143
5144 Remove the top entry from the directory stack, and @code{cd}
5145 to the new top directory.
5146 When no arguments are given, @code{popd}
5147 removes the top directory from the stack and
5148 performs a @code{cd} to the new top directory. The
5149 elements are numbered from 0 starting at the first directory listed with
5150 @code{dirs}; i.e., @code{popd} is equivalent to @code{popd +0}.
5151 @table @code
5152 @item +@var{N}
5153 Removes the @var{N}th directory (counting from the left of the
5154 list printed by @code{dirs}), starting with zero.
5155 @item -@var{N}
5156 Removes the @var{N}th directory (counting from the right of the
5157 list printed by @code{dirs}), starting with zero.
5158 @item -n
5159 Suppresses the normal change of directory when removing directories
5160 from the stack, so that only the stack is manipulated.
5161 @end table
5162
5163 @btindex pushd
5164 @item pushd
5165 @example
5166 pushd [@var{dir} | @var{+N} | @var{-N}] [-n]
5167 @end example
5168
5169 Save the current directory on the top of the directory stack
5170 and then @code{cd} to @var{dir}.
5171 With no arguments, @code{pushd} exchanges the top two directories.
5172
5173 @table @code
5174 @item +@var{N}
5175 Brings the @var{N}th directory (counting from the left of the
5176 list printed by @code{dirs}, starting with zero) to the top of
5177 the list by rotating the stack.
5178 @item -@var{N}
5179 Brings the @var{N}th directory (counting from the right of the
5180 list printed by @code{dirs}, starting with zero) to the top of
5181 the list by rotating the stack.
5182 @item -n
5183 Suppresses the normal change of directory when adding directories
5184 to the stack, so that only the stack is manipulated.
5185 @item @var{dir}
5186 Makes the current working directory be the top of the stack, and then
5187 executes the equivalent of `@code{cd} @var{dir}'.
5188 @code{cd}s to @var{dir}.
5189 @end table
5190
5191 @end table
5192
5193 @node Printing a Prompt
5194 @section Controlling the Prompt
5195 @cindex prompting
5196
5197 The value of the variable @env{PROMPT_COMMAND} is examined just before
5198 Bash prints each primary prompt. If @env{PROMPT_COMMAND} is set and
5199 has a non-null value, then the
5200 value is executed just as if it had been typed on the command line.
5201
5202 In addition, the following table describes the special characters which
5203 can appear in the prompt variables:
5204
5205 @table @code
5206 @item \a
5207 A bell character.
5208 @item \d
5209 The date, in "Weekday Month Date" format (e.g., "Tue May 26").
5210 @item \e
5211 An escape character.
5212 @item \h
5213 The hostname, up to the first `.'.
5214 @item \H
5215 The hostname.
5216 @item \j
5217 The number of jobs currently managed by the shell.
5218 @item \l
5219 The basename of the shell's terminal device name.
5220 @item \n
5221 A newline.
5222 @item \r
5223 A carriage return.
5224 @item \s
5225 The name of the shell, the basename of @code{$0} (the portion
5226 following the final slash).
5227 @item \t
5228 The time, in 24-hour HH:MM:SS format.
5229 @item \T
5230 The time, in 12-hour HH:MM:SS format.
5231 @item \@@
5232 The time, in 12-hour am/pm format.
5233 @item \u
5234 The username of the current user.
5235 @item \v
5236 The version of Bash (e.g., 2.00)
5237 @item \V
5238 The release of Bash, version + patchlevel (e.g., 2.00.0)
5239 @item \w
5240 The current working directory.
5241 @item \W
5242 The basename of @env{$PWD}.
5243 @item \!
5244 The history number of this command.
5245 @item \#
5246 The command number of this command.
5247 @item \$
5248 If the effective uid is 0, @code{#}, otherwise @code{$}.
5249 @item \@var{nnn}
5250 The character whose ASCII code is the octal value @var{nnn}.
5251 @item \\
5252 A backslash.
5253 @item \[
5254 Begin a sequence of non-printing characters. This could be used to
5255 embed a terminal control sequence into the prompt.
5256 @item \]
5257 End a sequence of non-printing characters.
5258 @end table
5259
5260 The command number and the history number are usually different:
5261 the history number of a command is its position in the history
5262 list, which may include commands restored from the history file
5263 (@pxref{Bash History Facilities}), while the command number is
5264 the position in the sequence of commands executed during the current
5265 shell session.
5266
5267 After the string is decoded, it is expanded via
5268 parameter expansion, command substitution, arithmetic
5269 expansion, and quote removal, subject to the value of the
5270 @code{promptvars} shell option (@pxref{Bash Builtins}).
5271
5272 @node The Restricted Shell
5273 @section The Restricted Shell
5274 @cindex restricted shell
5275
5276 If Bash is started with the name @code{rbash}, or the
5277 @option{--restricted}
5278 option is supplied at invocation, the shell becomes restricted.
5279 A restricted shell is used to
5280 set up an environment more controlled than the standard shell.
5281 A restricted shell behaves identically to @code{bash}
5282 with the exception that the following are disallowed:
5283 @itemize @bullet
5284 @item
5285 Changing directories with the @code{cd} builtin.
5286 @item
5287 Setting or unsetting the values of the @env{SHELL}, @env{PATH},
5288 @env{ENV}, or @env{BASH_ENV} variables.
5289 @item
5290 Specifying command names containing slashes.
5291 @item
5292 Specifying a filename containing a slash as an argument to the @code{.}
5293 builtin command.
5294 @item
5295 Specifying a filename containing a slash as an argument to the @option{-p}
5296 option to the @code{hash} builtin command.
5297 @item
5298 Importing function definitions from the shell environment at startup.
5299 @item
5300 Parsing the value of @env{SHELLOPTS} from the shell environment at startup.
5301 @item
5302 Redirecting output using the @samp{>}, @samp{>|}, @samp{<>}, @samp{>&},
5303 @samp{&>}, and @samp{>>} redirection operators.
5304 @item
5305 Using the @code{exec} builtin to replace the shell with another command.
5306 @item
5307 Adding or deleting builtin commands with the
5308 @option{-f} and @option{-d} options to the @code{enable} builtin.
5309 @item
5310 Specifying the @option{-p} option to the @code{command} builtin.
5311 @item
5312 Turning off restricted mode with @samp{set +r} or @samp{set +o restricted}.
5313 @end itemize
5314
5315 @node Bash POSIX Mode
5316 @section Bash POSIX Mode
5317 @cindex POSIX Mode
5318
5319 Starting Bash with the @option{--posix} command-line option or executing
5320 @samp{set -o posix} while Bash is running will cause Bash to conform more
5321 closely to the @sc{posix} 1003.2 standard by changing the behavior to
5322 match that specified by @sc{posix} in areas where the Bash default differs.
5323
5324 The following list is what's changed when `@sc{posix} mode' is in effect:
5325
5326 @enumerate
5327 @item
5328 When a command in the hash table no longer exists, Bash will re-search
5329 @env{$PATH} to find the new location. This is also available with
5330 @samp{shopt -s checkhash}.
5331
5332 @item
5333 The message printed by the job control code and builtins when a job
5334 exits with a non-zero status is `Done(status)'.
5335
5336 @item
5337 The message printed by the job control code and builtins when a job
5338 is stopped is `Stopped(@var{signame})', where @var{signame} is, for
5339 example, @code{SIGTSTP}.
5340
5341 @item
5342 Reserved words may not be aliased.
5343
5344 @item
5345 The @sc{posix} 1003.2 @env{PS1} and @env{PS2} expansions of @samp{!} to
5346 the history number and @samp{!!} to @samp{!} are enabled,
5347 and parameter expansion is performed on the values of @env{PS1} and
5348 @env{PS2} regardless of the setting of the @code{promptvars} option.
5349
5350 @item
5351 Interactive comments are enabled by default. (Bash has them on by
5352 default anyway.)
5353
5354 @item
5355 The @sc{posix} 1003.2 startup files are executed (@env{$ENV}) rather than
5356 the normal Bash files.
5357
5358 @item
5359 Tilde expansion is only performed on assignments preceding a command
5360 name, rather than on all assignment statements on the line.
5361
5362 @item
5363 The default history file is @file{~/.sh_history} (this is the
5364 default value of @env{$HISTFILE}).
5365
5366 @item
5367 The output of @samp{kill -l} prints all the signal names on a single line,
5368 separated by spaces.
5369
5370 @item
5371 Non-interactive shells exit if @var{filename} in @code{.} @var{filename}
5372 is not found.
5373
5374 @item
5375 Non-interactive shells exit if a syntax error in an arithmetic expansion
5376 results in an invalid expression.
5377
5378 @item
5379 Redirection operators do not perform filename expansion on the word
5380 in the redirection unless the shell is interactive.
5381
5382 @item
5383 Redirection operators do not perform word splitting on the word in the
5384 redirection.
5385
5386 @item
5387 Function names must be valid shell @code{name}s. That is, they may not
5388 contain characters other than letters, digits, and underscores, and
5389 may not start with a digit. Declaring a function with an invalid name
5390 causes a fatal syntax error in non-interactive shells.
5391
5392 @item
5393 @sc{posix} 1003.2 `special' builtins are found before shell functions
5394 during command lookup.
5395
5396 @item
5397 If a @sc{posix} 1003.2 special builtin returns an error status, a
5398 non-interactive shell exits. The fatal errors are those listed in
5399 the POSIX.2 standard, and include things like passing incorrect options,
5400 redirection errors, variable assignment errors for assignments preceding
5401 the command name, and so on.
5402
5403 @item
5404 If the @code{cd} builtin finds a directory to change to
5405 using @env{$CDPATH}, the
5406 value it assigns to the @env{PWD} variable does not contain any
5407 symbolic links, as if @samp{cd -P} had been executed.
5408
5409 @item
5410 If @env{CDPATH} is set, the @code{cd} builtin will not implicitly
5411 append the current directory to it. This means that @code{cd} will
5412 fail if no valid directory name can be constructed from
5413 any of the entries in @env{$CDPATH}, even if the a directory with
5414 the same name as the name given as an argument to @code{cd} exists
5415 in the current directory.
5416
5417 @item
5418 A non-interactive shell exits with an error status if a variable
5419 assignment error occurs when no command name follows the assignment
5420 statements.
5421 A variable assignment error occurs, for example, when trying to assign
5422 a value to a readonly variable.
5423
5424 @item
5425 A non-interactive shell exits with an error status if the iteration
5426 variable in a @code{for} statement or the selection variable in a
5427 @code{select} statement is a readonly variable.
5428
5429 @item
5430 Process substitution is not available.
5431
5432 @item
5433 Assignment statements preceding @sc{posix} 1003.2 special builtins
5434 persist in the shell environment after the builtin completes.
5435
5436 @item
5437 Assignment statements preceding shell function calls persist in the
5438 shell environment after the function returns, as if a @sc{posix}
5439 special builtin command had been executed.
5440
5441 @item
5442 The @code{export} and @code{readonly} builtin commands display their
5443 output in the format required by @sc{posix} 1003.2.
5444
5445 @item
5446 The @code{trap} builtin displays signal names without the leading
5447 @code{SIG}.
5448
5449 @item
5450 The @code{.} and @code{source} builtins do not search the current directory
5451 for the filename argument if it is not found by searching @env{PATH}.
5452
5453 @item
5454 Subshells spawned to execute command substitutions inherit the value of
5455 the @option{-e} option from the parent shell. When not in @sc{posix} mode,
5456 Bash clears the @option{-e} option in such subshells.
5457
5458 @item
5459 Alias expansion is always enabled, even in non-interactive shells.
5460
5461 @item
5462 When the @code{set} builtin is invoked without options, it does not display
5463 shell function names and definitions.
5464
5465 @end enumerate
5466
5467 There is other @sc{posix} 1003.2 behavior that Bash does not implement.
5468 Specifically:
5469
5470 @enumerate
5471 @item
5472 Assignment statements affect the execution environment of all
5473 builtins, not just special ones.
5474
5475 @item
5476 When a subshell is created to execute a shell script with execute permission,
5477 but without a leading @samp{#!}, Bash sets @code{$0} to the full pathname of
5478 the script as found by searching @code{$PATH}, rather than the command as
5479 typed by the user.
5480
5481 @item
5482 When using @samp{.} to source a shell script found in @code{$PATH}, bash
5483 checks execute permission bits rather than read permission bits, just as
5484 if it were searching for a command.
5485
5486 @end enumerate
5487
5488 @node Job Control
5489 @chapter Job Control
5490
5491 This chapter discusses what job control is, how it works, and how
5492 Bash allows you to access its facilities.
5493
5494 @menu
5495 * Job Control Basics:: How job control works.
5496 * Job Control Builtins:: Bash builtin commands used to interact
5497 with job control.
5498 * Job Control Variables:: Variables Bash uses to customize job
5499 control.
5500 @end menu
5501
5502 @node Job Control Basics
5503 @section Job Control Basics
5504 @cindex job control
5505 @cindex foreground
5506 @cindex background
5507 @cindex suspending jobs
5508
5509 Job control
5510 refers to the ability to selectively stop (suspend)
5511 the execution of processes and continue (resume)
5512 their execution at a later point. A user typically employs
5513 this facility via an interactive interface supplied jointly
5514 by the system's terminal driver and Bash.
5515
5516 The shell associates a @var{job} with each pipeline. It keeps a
5517 table of currently executing jobs, which may be listed with the
5518 @code{jobs} command. When Bash starts a job
5519 asynchronously, it prints a line that looks
5520 like:
5521 @example
5522 [1] 25647
5523 @end example
5524 @noindent
5525 indicating that this job is job number 1 and that the process @sc{id}
5526 of the last process in the pipeline associated with this job is
5527 25647. All of the processes in a single pipeline are members of
5528 the same job. Bash uses the @var{job} abstraction as the
5529 basis for job control.
5530
5531 To facilitate the implementation of the user interface to job
5532 control, the operating system maintains the notion of a current terminal
5533 process group @sc{id}. Members of this process group (processes whose
5534 process group @sc{id} is equal to the current terminal process group
5535 @sc{id}) receive keyboard-generated signals such as @code{SIGINT}.
5536 These processes are said to be in the foreground. Background
5537 processes are those whose process group @sc{id} differs from the
5538 terminal's; such processes are immune to keyboard-generated
5539 signals. Only foreground processes are allowed to read from or
5540 write to the terminal. Background processes which attempt to
5541 read from (write to) the terminal are sent a @code{SIGTTIN}
5542 (@code{SIGTTOU}) signal by the terminal driver, which, unless
5543 caught, suspends the process.
5544
5545 If the operating system on which Bash is running supports
5546 job control, Bash contains facilities to use it. Typing the
5547 @var{suspend} character (typically @samp{^Z}, Control-Z) while a
5548 process is running causes that process to be stopped and returns
5549 control to Bash. Typing the @var{delayed suspend} character
5550 (typically @samp{^Y}, Control-Y) causes the process to be stopped
5551 when it attempts to read input from the terminal, and control to
5552 be returned to Bash. The user then manipulates the state of
5553 this job, using the @code{bg} command to continue it in the
5554 background, the @code{fg} command to continue it in the
5555 foreground, or the @code{kill} command to kill it. A @samp{^Z}
5556 takes effect immediately, and has the additional side effect of
5557 causing pending output and typeahead to be discarded.
5558
5559 There are a number of ways to refer to a job in the shell. The
5560 character @samp{%} introduces a job name.
5561
5562 Job number @code{n} may be referred to as @samp{%n}.
5563 The symbols @samp{%%} and
5564 @samp{%+} refer to the shell's notion of the current job, which
5565 is the last job stopped while it was in the foreground or started
5566 in the background. The
5567 previous job may be referenced using @samp{%-}. In output
5568 pertaining to jobs (e.g., the output of the @code{jobs} command),
5569 the current job is always flagged with a @samp{+}, and the
5570 previous job with a @samp{-}.
5571
5572 A job may also be referred to
5573 using a prefix of the name used to start it, or using a substring
5574 that appears in its command line. For example, @samp{%ce} refers
5575 to a stopped @code{ce} job. Using @samp{%?ce}, on the
5576 other hand, refers to any job containing the string @samp{ce} in
5577 its command line. If the prefix or substring matches more than one job,
5578 Bash reports an error.
5579
5580 Simply naming a job can be used to bring it into the foreground:
5581 @samp{%1} is a synonym for @samp{fg %1}, bringing job 1 from the
5582 background into the foreground. Similarly, @samp{%1 &} resumes
5583 job 1 in the background, equivalent to @samp{bg %1}
5584
5585 The shell learns immediately whenever a job changes state.
5586 Normally, Bash waits until it is about to print a prompt
5587 before reporting changes in a job's status so as to not interrupt
5588 any other output. If the
5589 the @option{-b} option to the @code{set} builtin is enabled,
5590 Bash reports such changes immediately (@pxref{The Set Builtin}).
5591
5592 If an attempt to exit Bash is while jobs are stopped, the
5593 shell prints a message warning that there are stopped jobs.
5594 The @code{jobs} command may then be used to inspect their status.
5595 If a second attempt to exit is made without an intervening command,
5596 Bash does not print another warning, and the stopped jobs are terminated.
5597
5598 @node Job Control Builtins
5599 @section Job Control Builtins
5600
5601 @table @code
5602
5603 @item bg
5604 @btindex bg
5605 @example
5606 bg [@var{jobspec}]
5607 @end example
5608 Resume the suspended job @var{jobspec} in the background, as if it
5609 had been started with @samp{&}.
5610 If @var{jobspec} is not supplied, the current job is used.
5611 The return status is zero unless it is run when job control is not
5612 enabled, or, when run with job control enabled, if @var{jobspec} was
5613 not found or @var{jobspec} specifies a job that was started without
5614 job control.
5615
5616 @item fg
5617 @btindex fg
5618 @example
5619 fg [@var{jobspec}]
5620 @end example
5621 Resume the job @var{jobspec} in the foreground and make it the current job.
5622 If @var{jobspec} is not supplied, the current job is used.
5623 The return status is that of the command placed into the foreground,
5624 or non-zero if run when job control is disabled or, when run with
5625 job control enabled, @var{jobspec} does not specify a valid job or
5626 @var{jobspec} specifies a job that was started without job control.
5627
5628 @item jobs
5629 @btindex jobs
5630 @example
5631 jobs [-lnprs] [@var{jobspec}]
5632 jobs -x @var{command} [@var{arguments}]
5633 @end example
5634
5635 The first form lists the active jobs. The options have the
5636 following meanings:
5637
5638 @table @code
5639 @item -l
5640 List process @sc{id}s in addition to the normal information.
5641
5642 @item -n
5643 Display information only about jobs that have changed status since
5644 the user was last notified of their status.
5645
5646 @item -p
5647 List only the process @sc{id} of the job's process group leader.
5648
5649 @item -r
5650 Restrict output to running jobs.
5651
5652 @item -s
5653 Restrict output to stopped jobs.
5654 @end table
5655
5656 If @var{jobspec} is given,
5657 output is restricted to information about that job.
5658 If @var{jobspec} is not supplied, the status of all jobs is
5659 listed.
5660
5661 If the @option{-x} option is supplied, @code{jobs} replaces any
5662 @var{jobspec} found in @var{command} or @var{arguments} with the
5663 corresponding process group @sc{id}, and executes @var{command},
5664 passing it @var{argument}s, returning its exit status.
5665
5666 @item kill
5667 @btindex kill
5668 @example
5669 kill [-s @var{sigspec}] [-n @var{signum}] [-@var{sigspec}] @var{jobspec} or @var{pid}
5670 kill -l [@var{exit_status}]
5671 @end example
5672 Send a signal specified by @var{sigspec} or @var{signum} to the process
5673 named by job specification @var{jobspec} or process @sc{id} @var{pid}.
5674 @var{sigspec} is either a signal name such as @code{SIGINT} (with or without
5675 the @code{SIG} prefix) or a signal number; @var{signum} is a signal number.
5676 If @var{sigspec} and @var{signum} are not present, @code{SIGTERM} is used.
5677 The @option{-l} option lists the signal names.
5678 If any arguments are supplied when @option{-l} is given, the names of the
5679 signals corresponding to the arguments are listed, and the return status
5680 is zero.
5681 @var{exit_status} is a number specifying a signal number or the exit
5682 status of a process terminated by a signal.
5683 The return status is zero if at least one signal was successfully sent,
5684 or non-zero if an error occurs or an invalid option is encountered.
5685
5686 @item wait
5687 @btindex wait
5688 @example
5689 wait [@var{jobspec} or @var{pid}]
5690 @end example
5691 Wait until the child process specified by process @sc{id} @var{pid} or job
5692 specification @var{jobspec} exits and return the exit status of the last
5693 command waited for.
5694 If a job spec is given, all processes in the job are waited for.
5695 If no arguments are given, all currently active child processes are
5696 waited for, and the return status is zero.
5697 If neither @var{jobspec} nor @var{pid} specifies an active child process
5698 of the shell, the return status is 127.
5699
5700 @item disown
5701 @btindex disown
5702 @example
5703 disown [-ar] [-h] [@var{jobspec} @dots{}]
5704 @end example
5705 Without options, each @var{jobspec} is removed from the table of
5706 active jobs.
5707 If the @option{-h} option is given, the job is not removed from the table,
5708 but is marked so that @code{SIGHUP} is not sent to the job if the shell
5709 receives a @code{SIGHUP}.
5710 If @var{jobspec} is not present, and neither the @option{-a} nor @option{-r}
5711 option is supplied, the current job is used.
5712 If no @var{jobspec} is supplied, the @option{-a} option means to remove or
5713 mark all jobs; the @option{-r} option without a @var{jobspec}
5714 argument restricts operation to running jobs.
5715
5716 @item suspend
5717 @btindex suspend
5718 @example
5719 suspend [-f]
5720 @end example
5721 Suspend the execution of this shell until it receives a
5722 @code{SIGCONT} signal. The @option{-f} option means to suspend
5723 even if the shell is a login shell.
5724
5725 @end table
5726
5727 When job control is not active, the @code{kill} and @code{wait}
5728 builtins do not accept @var{jobspec} arguments. They must be
5729 supplied process @sc{id}s.
5730
5731 @node Job Control Variables
5732 @section Job Control Variables
5733
5734 @vtable @code
5735
5736 @item auto_resume
5737 This variable controls how the shell interacts with the user and
5738 job control. If this variable exists then single word simple
5739 commands without redirections are treated as candidates for resumption
5740 of an existing job. There is no ambiguity allowed; if there is
5741 more than one job beginning with the string typed, then
5742 the most recently accessed job will be selected.
5743 The name of a stopped job, in this context, is the command line
5744 used to start it. If this variable is set to the value @samp{exact},
5745 the string supplied must match the name of a stopped job exactly;
5746 if set to @samp{substring},
5747 the string supplied needs to match a substring of the name of a
5748 stopped job. The @samp{substring} value provides functionality
5749 analogous to the @samp{%?} job @sc{id} (@pxref{Job Control Basics}).
5750 If set to any other value, the supplied string must
5751 be a prefix of a stopped job's name; this provides functionality
5752 analogous to the @samp{%} job @sc{id}.
5753
5754 @end vtable
5755
5756 @set readline-appendix
5757 @set history-appendix
5758 @cindex Readline, how to use
5759 @include rluser.texinfo
5760 @cindex History, how to use
5761 @include hsuser.texinfo
5762 @clear readline-appendix
5763 @clear history-appendix
5764
5765 @node Installing Bash
5766 @chapter Installing Bash
5767
5768 This chapter provides basic instructions for installing Bash on
5769 the various supported platforms. The distribution supports the
5770 @sc{gnu} operating systems, nearly every version of Unix, and several
5771 non-Unix systems such as BeOS and Interix.
5772 Other independent ports exist for
5773 @sc{ms-dos}, @sc{os/2}, Windows @sc{95/98}, and Windows @sc{nt}.
5774
5775 @menu
5776 * Basic Installation:: Installation instructions.
5777
5778 * Compilers and Options:: How to set special options for various
5779 systems.
5780
5781 * Compiling For Multiple Architectures:: How to compile Bash for more
5782 than one kind of system from
5783 the same source tree.
5784
5785 * Installation Names:: How to set the various paths used by the installation.
5786
5787 * Specifying the System Type:: How to configure Bash for a particular system.
5788
5789 * Sharing Defaults:: How to share default configuration values among GNU
5790 programs.
5791
5792 * Operation Controls:: Options recognized by the configuration program.
5793
5794 * Optional Features:: How to enable and disable optional features when
5795 building Bash.
5796 @end menu
5797
5798 @node Basic Installation
5799 @section Basic Installation
5800 @cindex installation
5801 @cindex configuration
5802 @cindex Bash installation
5803 @cindex Bash configuration
5804
5805 These are installation instructions for Bash.
5806
5807 The simplest way to compile Bash is:
5808
5809 @enumerate
5810 @item
5811 @code{cd} to the directory containing the source code and type
5812 @samp{./configure} to configure Bash for your system. If you're
5813 using @code{csh} on an old version of System V, you might need to
5814 type @samp{sh ./configure} instead to prevent @code{csh} from trying
5815 to execute @code{configure} itself.
5816
5817 Running @code{configure} takes some time.
5818 While running, it prints messages telling which features it is
5819 checking for.
5820
5821 @item
5822 Type @samp{make} to compile Bash and build the @code{bashbug} bug
5823 reporting script.
5824
5825 @item
5826 Optionally, type @samp{make tests} to run the Bash test suite.
5827
5828 @item
5829 Type @samp{make install} to install @code{bash} and @code{bashbug}.
5830 This will also install the manual pages and Info file.
5831
5832 @end enumerate
5833
5834 The @code{configure} shell script attempts to guess correct
5835 values for various system-dependent variables used during
5836 compilation. It uses those values to create a @file{Makefile} in
5837 each directory of the package (the top directory, the
5838 @file{builtins}, @file{doc}, and @file{support} directories,
5839 each directory under @file{lib}, and several others). It also creates a
5840 @file{config.h} file containing system-dependent definitions.
5841 Finally, it creates a shell script named @code{config.status} that you
5842 can run in the future to recreate the current configuration, a
5843 file @file{config.cache} that saves the results of its tests to
5844 speed up reconfiguring, and a file @file{config.log} containing
5845 compiler output (useful mainly for debugging @code{configure}).
5846 If at some point
5847 @file{config.cache} contains results you don't want to keep, you
5848 may remove or edit it.
5849
5850 To find out more about the options and arguments that the
5851 @code{configure} script understands, type
5852
5853 @example
5854 bash-2.04$ ./configure --help
5855 @end example
5856
5857 @noindent
5858 at the Bash prompt in your Bash source directory.
5859
5860 If you need to do unusual things to compile Bash, please
5861 try to figure out how @code{configure} could check whether or not
5862 to do them, and mail diffs or instructions to
5863 @email{bash-maintainers@@gnu.org} so they can be
5864 considered for the next release.
5865
5866 The file @file{configure.in} is used to create @code{configure}
5867 by a program called Autoconf. You only need
5868 @file{configure.in} if you want to change it or regenerate
5869 @code{configure} using a newer version of Autoconf. If
5870 you do this, make sure you are using Autoconf version 2.10 or
5871 newer.
5872
5873 If you need to change @file{configure.in} or regenerate
5874 @code{configure}, you will need to create two files:
5875 @file{_distribution} and @file{_patchlevel}. @file{_distribution}
5876 should contain the major and minor version numbers of the Bash
5877 distribution, for example @samp{2.01}. @file{_patchlevel} should
5878 contain the patch level of the Bash distribution, @samp{0} for
5879 example. The script @file{support/mkconffiles} has been provided
5880 to automate the creation of these files.
5881
5882 You can remove the program binaries and object files from the
5883 source code directory by typing @samp{make clean}. To also remove the
5884 files that @code{configure} created (so you can compile Bash for
5885 a different kind of computer), type @samp{make distclean}.
5886
5887 @node Compilers and Options
5888 @section Compilers and Options
5889
5890 Some systems require unusual options for compilation or linking
5891 that the @code{configure} script does not know about. You can
5892 give @code{configure} initial values for variables by setting
5893 them in the environment. Using a Bourne-compatible shell, you
5894 can do that on the command line like this:
5895
5896 @example
5897 CC=c89 CFLAGS=-O2 LIBS=-lposix ./configure
5898 @end example
5899
5900 On systems that have the @code{env} program, you can do it like this:
5901
5902 @example
5903 env CPPFLAGS=-I/usr/local/include LDFLAGS=-s ./configure
5904 @end example
5905
5906 The configuration process uses GCC to build Bash if it
5907 is available.
5908
5909 @node Compiling For Multiple Architectures
5910 @section Compiling For Multiple Architectures
5911
5912 You can compile Bash for more than one kind of computer at the
5913 same time, by placing the object files for each architecture in their
5914 own directory. To do this, you must use a version of @code{make} that
5915 supports the @code{VPATH} variable, such as GNU @code{make}.
5916 @code{cd} to the
5917 directory where you want the object files and executables to go and run
5918 the @code{configure} script from the source directory. You may need to
5919 supply the @option{--srcdir=PATH} argument to tell @code{configure} where the
5920 source files are. @code{configure} automatically checks for the
5921 source code in the directory that @code{configure} is in and in `..'.
5922
5923 If you have to use a @code{make} that does not supports the @code{VPATH}
5924 variable, you can compile Bash for one architecture at a
5925 time in the source code directory. After you have installed
5926 Bash for one architecture, use @samp{make distclean} before
5927 reconfiguring for another architecture.
5928
5929 Alternatively, if your system supports symbolic links, you can use the
5930 @file{support/mkclone} script to create a build tree which has
5931 symbolic links back to each file in the source directory. Here's an
5932 example that creates a build directory in the current directory from a
5933 source directory @file{/usr/gnu/src/bash-2.0}:
5934
5935 @example
5936 bash /usr/gnu/src/bash-2.0/support/mkclone -s /usr/gnu/src/bash-2.0 .
5937 @end example
5938
5939 @noindent
5940 The @code{mkclone} script requires Bash, so you must have already built
5941 Bash for at least one architecture before you can create build
5942 directories for other architectures.
5943
5944 @node Installation Names
5945 @section Installation Names
5946
5947 By default, @samp{make install} will install into
5948 @file{/usr/local/bin}, @file{/usr/local/man}, etc. You can
5949 specify an installation prefix other than @file{/usr/local} by
5950 giving @code{configure} the option @option{--prefix=@var{PATH}}.
5951
5952 You can specify separate installation prefixes for
5953 architecture-specific files and architecture-independent files.
5954 If you give @code{configure} the option
5955 @option{--exec-prefix=@var{PATH}}, @samp{make install} will use
5956 @var{PATH} as the prefix for installing programs and libraries.
5957 Documentation and other data files will still use the regular prefix.
5958
5959 @node Specifying the System Type
5960 @section Specifying the System Type
5961
5962 There may be some features @code{configure} can not figure out
5963 automatically, but needs to determine by the type of host Bash
5964 will run on. Usually @code{configure} can figure that
5965 out, but if it prints a message saying it can not guess the host
5966 type, give it the @option{--host=TYPE} option. @samp{TYPE} can
5967 either be a short name for the system type, such as @samp{sun4},
5968 or a canonical name with three fields: @samp{CPU-COMPANY-SYSTEM}
5969 (e.g., @samp{sparc-sun-sunos4.1.2}).
5970
5971 See the file @file{support/config.sub} for the possible
5972 values of each field.
5973
5974 @node Sharing Defaults
5975 @section Sharing Defaults
5976
5977 If you want to set default values for @code{configure} scripts to
5978 share, you can create a site shell script called
5979 @code{config.site} that gives default values for variables like
5980 @code{CC}, @code{cache_file}, and @code{prefix}. @code{configure}
5981 looks for @file{PREFIX/share/config.site} if it exists, then
5982 @file{PREFIX/etc/config.site} if it exists. Or, you can set the
5983 @code{CONFIG_SITE} environment variable to the location of the site
5984 script. A warning: the Bash @code{configure} looks for a site script,
5985 but not all @code{configure} scripts do.
5986
5987 @node Operation Controls
5988 @section Operation Controls
5989
5990 @code{configure} recognizes the following options to control how it
5991 operates.
5992
5993 @table @code
5994
5995 @item --cache-file=@var{file}
5996 Use and save the results of the tests in
5997 @var{file} instead of @file{./config.cache}. Set @var{file} to
5998 @file{/dev/null} to disable caching, for debugging
5999 @code{configure}.
6000
6001 @item --help
6002 Print a summary of the options to @code{configure}, and exit.
6003
6004 @item --quiet
6005 @itemx --silent
6006 @itemx -q
6007 Do not print messages saying which checks are being made.
6008
6009 @item --srcdir=@var{dir}
6010 Look for the Bash source code in directory @var{dir}. Usually
6011 @code{configure} can determine that directory automatically.
6012
6013 @item --version
6014 Print the version of Autoconf used to generate the @code{configure}
6015 script, and exit.
6016 @end table
6017
6018 @code{configure} also accepts some other, not widely used, boilerplate
6019 options. @samp{configure --help} prints the complete list.
6020
6021 @node Optional Features
6022 @section Optional Features
6023
6024 The Bash @code{configure} has a number of @option{--enable-@var{feature}}
6025 options, where @var{feature} indicates an optional part of Bash.
6026 There are also several @option{--with-@var{package}} options,
6027 where @var{package} is something like @samp{bash-malloc} or @samp{purify}.
6028 To turn off the default use of a package, use
6029 @option{--without-@var{package}}. To configure Bash without a feature
6030 that is enabled by default, use @option{--disable-@var{feature}}.
6031
6032 Here is a complete list of the @option{--enable-} and
6033 @option{--with-} options that the Bash @code{configure} recognizes.
6034
6035 @table @code
6036 @item --with-afs
6037 Define if you are using the Andrew File System from Transarc.
6038
6039 @item --with-bash-malloc
6040 Use the Bash version of
6041 @code{malloc} in @file{lib/malloc/malloc.c}. This is not the same
6042 @code{malloc} that appears in @sc{gnu} libc, but an older version
6043 derived from the 4.2 @sc{bsd} @code{malloc}. This @code{malloc} is
6044 very fast, but wastes some space on each allocation.
6045 This option is enabled by default.
6046 The @file{NOTES} file contains a list of systems for
6047 which this should be turned off, and @code{configure} disables this
6048 option automatically for a number of systems.
6049
6050 @item --with-curses
6051 Use the curses library instead of the termcap library. This should
6052 be supplied if your system has an inadequate or incomplete termcap
6053 database.
6054
6055 @item --with-glibc-malloc
6056 Use the @sc{gnu} libc version of @code{malloc} in
6057 @file{lib/malloc/gmalloc.c}. This is not the version of @code{malloc}
6058 that appears in glibc version 2, but a modified version of the
6059 @code{malloc} from glibc version 1. This is somewhat slower than the
6060 default @code{malloc}, but wastes less space on a per-allocation
6061 basis, and will return memory to the operating system under
6062 certain circumstances.
6063
6064 @item --with-gnu-malloc
6065 A synonym for @code{--with-bash-malloc}.
6066
6067 @item --with-installed-readline
6068 Define this to make Bash link with a locally-installed version of Readline
6069 rather than the version in @file{lib/readline}. This works only with
6070 Readline 4.1 and later versions.
6071
6072 @item --with-purify
6073 Define this to use the Purify memory allocation checker from Rational
6074 Software.
6075
6076 @item --enable-minimal-config
6077 This produces a shell with minimal features, close to the historical
6078 Bourne shell.
6079 @end table
6080
6081 There are several @option{--enable-} options that alter how Bash is
6082 compiled and linked, rather than changing run-time features.
6083
6084 @table @code
6085 @item --enable-profiling
6086 This builds a Bash binary that produces profiling information to be
6087 processed by @code{gprof} each time it is executed.
6088
6089 @item --enable-static-link
6090 This causes Bash to be linked statically, if @code{gcc} is being used.
6091 This could be used to build a version to use as root's shell.
6092 @end table
6093
6094 The @samp{minimal-config} option can be used to disable all of
6095 the following options, but it is processed first, so individual
6096 options may be enabled using @samp{enable-@var{feature}}.
6097
6098 All of the following options except for @samp{disabled-builtins} and
6099 @samp{xpg-echo-default} are
6100 enabled by default, unless the operating system does not provide the
6101 necessary support.
6102
6103 @table @code
6104 @item --enable-alias
6105 Allow alias expansion and include the @code{alias} and @code{unalias}
6106 builtins (@pxref{Aliases}).
6107
6108 @item --enable-arith-for-command
6109 Include support for the alternate form of the @code{for} command
6110 that behaves like the C language @code{for} statement
6111 (@pxref{Looping Constructs}).
6112
6113 @item --enable-array-variables
6114 Include support for one-dimensional array shell variables
6115 (@pxref{Arrays}).
6116
6117 @item --enable-bang-history
6118 Include support for @code{csh}-like history substitution
6119 (@pxref{History Interaction}).
6120
6121 @item --enable-brace-expansion
6122 Include @code{csh}-like brace expansion
6123 ( @code{b@{a,b@}c} @expansion{} @code{bac bbc} ).
6124 See @ref{Brace Expansion}, for a complete description.
6125
6126 @item --enable-command-timing
6127 Include support for recognizing @code{time} as a reserved word and for
6128 displaying timing statistics for the pipeline following @code{time}
6129 (@pxref{Pipelines}).
6130 This allows pipelines as well as shell builtins and functions to be timed.
6131
6132 @item --enable-cond-command
6133 Include support for the @code{[[} conditional command
6134 (@pxref{Conditional Constructs}).
6135
6136 @item --enable-directory-stack
6137 Include support for a @code{csh}-like directory stack and the
6138 @code{pushd}, @code{popd}, and @code{dirs} builtins
6139 (@pxref{The Directory Stack}).
6140
6141 @item --enable-disabled-builtins
6142 Allow builtin commands to be invoked via @samp{builtin xxx}
6143 even after @code{xxx} has been disabled using @samp{enable -n xxx}.
6144 See @ref{Bash Builtins}, for details of the @code{builtin} and
6145 @code{enable} builtin commands.
6146
6147 @item --enable-dparen-arithmetic
6148 Include support for the @code{((@dots{}))} command
6149 (@pxref{Conditional Constructs}).
6150
6151 @item --enable-extended-glob
6152 Include support for the extended pattern matching features described
6153 above under @ref{Pattern Matching}.
6154
6155 @item --enable-help-builtin
6156 Include the @code{help} builtin, which displays help on shell builtins and
6157 variables (@pxref{Bash Builtins}).
6158
6159 @item --enable-history
6160 Include command history and the @code{fc} and @code{history}
6161 builtin commands (@pxref{Bash History Facilities}).
6162
6163 @item --enable-job-control
6164 This enables the job control features (@pxref{Job Control}),
6165 if the operating system supports them.
6166
6167 @item --enable-net-redirections
6168 This enables the special handling of filenames of the form
6169 @code{/dev/tcp/@var{host}/@var{port}} and
6170 @code{/dev/udp/@var{host}/@var{port}}
6171 when used in redirections (@pxref{Redirections}).
6172
6173 @item --enable-process-substitution
6174 This enables process substitution (@pxref{Process Substitution}) if
6175 the operating system provides the necessary support.
6176
6177 @item --enable-prompt-string-decoding
6178 Turn on the interpretation of a number of backslash-escaped characters
6179 in the @env{$PS1}, @env{$PS2}, @env{$PS3}, and @env{$PS4} prompt
6180 strings. See @ref{Printing a Prompt}, for a complete list of prompt
6181 string escape sequences.
6182
6183 @item --enable-progcomp
6184 Enable the programmable completion facilities
6185 (@pxref{Programmable Completion}).
6186 If Readline is not enabled, this option has no effect.
6187
6188 @item --enable-readline
6189 Include support for command-line editing and history with the Bash
6190 version of the Readline library (@pxref{Command Line Editing}).
6191
6192 @item --enable-restricted
6193 Include support for a @dfn{restricted shell}. If this is enabled, Bash,
6194 when called as @code{rbash}, enters a restricted mode. See
6195 @ref{The Restricted Shell}, for a description of restricted mode.
6196
6197 @item --enable-select
6198 Include the @code{select} builtin, which allows the generation of simple
6199 menus (@pxref{Conditional Constructs}).
6200
6201 @item --enable-usg-echo-default
6202 A synonym for @code{--enable-xpg-echo-default}.
6203
6204 @item --enable-xpg-echo-default
6205 Make the @code{echo} builtin expand backslash-escaped characters by default,
6206 without requiring the @option{-e} option.
6207 This sets the default value of the @code{xpg_echo} shell option to @code{on},
6208 which makes the Bash @code{echo} behave more like the version specified in
6209 the Single Unix Specification, version 2.
6210 @xref{Bash Builtins}, for a description of the escape sequences that
6211 @code{echo} recognizes.
6212
6213 @end table
6214
6215 The file @file{config-top.h} contains C Preprocessor
6216 @samp{#define} statements for options which are not settable from
6217 @code{configure}.
6218 Some of these are not meant to be changed; beware of the consequences if
6219 you do.
6220 Read the comments associated with each definition for more
6221 information about its effect.
6222
6223 @node Reporting Bugs
6224 @appendix Reporting Bugs
6225
6226 Please report all bugs you find in Bash.
6227 But first, you should
6228 make sure that it really is a bug, and that it appears in the latest
6229 version of Bash that you have.
6230
6231 Once you have determined that a bug actually exists, use the
6232 @code{bashbug} command to submit a bug report.
6233 If you have a fix, you are encouraged to mail that as well!
6234 Suggestions and `philosophical' bug reports may be mailed
6235 to @email{bug-bash@@gnu.org} or posted to the Usenet
6236 newsgroup @code{gnu.bash.bug}.
6237
6238 All bug reports should include:
6239 @itemize @bullet
6240 @item
6241 The version number of Bash.
6242 @item
6243 The hardware and operating system.
6244 @item
6245 The compiler used to compile Bash.
6246 @item
6247 A description of the bug behaviour.
6248 @item
6249 A short script or `recipe' which exercises the bug and may be used
6250 to reproduce it.
6251 @end itemize
6252
6253 @noindent
6254 @code{bashbug} inserts the first three items automatically into
6255 the template it provides for filing a bug report.
6256
6257 Please send all reports concerning this manual to
6258 @email{chet@@po.CWRU.Edu}.
6259
6260 @node Major Differences From The Bourne Shell
6261 @appendix Major Differences From The Bourne Shell
6262
6263 Bash implements essentially the same grammar, parameter and
6264 variable expansion, redirection, and quoting as the Bourne Shell.
6265 Bash uses the @sc{posix} 1003.2 standard as the specification of
6266 how these features are to be implemented. There are some
6267 differences between the traditional Bourne shell and Bash; this
6268 section quickly details the differences of significance. A
6269 number of these differences are explained in greater depth in
6270 previous sections.
6271 This section uses the version of @code{sh} included in SVR4.2 as
6272 the baseline reference.
6273
6274 @itemize @bullet
6275
6276 @item
6277 Bash is @sc{posix}-conformant, even where the @sc{posix} specification
6278 differs from traditional @code{sh} behavior (@pxref{Bash POSIX Mode}).
6279
6280 @item
6281 Bash has multi-character invocation options (@pxref{Invoking Bash}).
6282
6283 @item
6284 Bash has command-line editing (@pxref{Command Line Editing}) and
6285 the @code{bind} builtin.
6286
6287 @item
6288 Bash provides a programmable word completion mechanism
6289 (@pxref{Programmable Completion}), and two builtin commands,
6290 @code{complete} and @code{compgen}, to manipulate it.
6291
6292 @item
6293 Bash has command history (@pxref{Bash History Facilities}) and the
6294 @code{history} and @code{fc} builtins to manipulate it.
6295
6296 @item
6297 Bash implements @code{csh}-like history expansion
6298 (@pxref{History Interaction}).
6299
6300 @item
6301 Bash has one-dimensional array variables (@pxref{Arrays}), and the
6302 appropriate variable expansions and assignment syntax to use them.
6303 Several of the Bash builtins take options to act on arrays.
6304 Bash provides a number of built-in array variables.
6305
6306 @item
6307 The @code{$'@dots{}'} quoting syntax, which expands ANSI-C
6308 backslash-escaped characters in the text between the single quotes,
6309 is supported (@pxref{ANSI-C Quoting}).
6310
6311 @item
6312 Bash supports the @code{$"@dots{}"} quoting syntax to do
6313 locale-specific translation of the characters between the double
6314 quotes. The @option{-D}, @option{--dump-strings}, and @option{--dump-po-strings}
6315 invocation options list the translatable strings found in a script
6316 (@pxref{Locale Translation}).
6317
6318 @item
6319 Bash implements the @code{!} keyword to negate the return value of
6320 a pipeline (@pxref{Pipelines}).
6321 Very useful when an @code{if} statement needs to act only if a test fails.
6322
6323 @item
6324 Bash has the @code{time} reserved word and command timing (@pxref{Pipelines}).
6325 The display of the timing statistics may be controlled with the
6326 @env{TIMEFORMAT} variable.
6327
6328 @item
6329 Bash implements the @code{for (( @var{expr1} ; @var{expr2} ; @var{expr3} ))}
6330 arithmetic for command, similar to the C language (@pxref{Looping Constructs}).
6331
6332 @item
6333 Bash includes the @code{select} compound command, which allows the
6334 generation of simple menus (@pxref{Conditional Constructs}).
6335
6336 @item
6337 Bash includes the @code{[[} compound command, which makes conditional
6338 testing part of the shell grammar (@pxref{Conditional Constructs}).
6339
6340 @item
6341 Bash includes brace expansion (@pxref{Brace Expansion}) and tilde
6342 expansion (@pxref{Tilde Expansion}).
6343
6344 @item
6345 Bash implements command aliases and the @code{alias} and @code{unalias}
6346 builtins (@pxref{Aliases}).
6347
6348 @item
6349 Bash provides shell arithmetic, the @code{((} compound command
6350 (@pxref{Conditional Constructs}),
6351 and arithmetic expansion (@pxref{Shell Arithmetic}).
6352
6353 @item
6354 Variables present in the shell's initial environment are automatically
6355 exported to child processes. The Bourne shell does not normally do
6356 this unless the variables are explicitly marked using the @code{export}
6357 command.
6358
6359 @item
6360 Bash includes the @sc{posix} pattern removal @samp{%}, @samp{#}, @samp{%%}
6361 and @samp{##} expansions to remove leading or trailing substrings from
6362 variable values (@pxref{Shell Parameter Expansion}).
6363
6364 @item
6365 The expansion @code{$@{#xx@}}, which returns the length of @code{$@{xx@}},
6366 is supported (@pxref{Shell Parameter Expansion}).
6367
6368 @item
6369 The expansion @code{$@{var:}@var{offset}@code{[:}@var{length}@code{]@}},
6370 which expands to the substring of @code{var}'s value of length
6371 @var{length}, beginning at @var{offset}, is present
6372 (@pxref{Shell Parameter Expansion}).
6373
6374 @item
6375 The expansion
6376 @code{$@{var/[/]}@var{pattern}@code{[/}@var{replacement}@code{]@}},
6377 which matches @var{pattern} and replaces it with @var{replacement} in
6378 the value of @code{var}, is available (@pxref{Shell Parameter Expansion}).
6379
6380 @item
6381 The expansion @code{$@{!@var{prefix@}*}} expansion, which expands to
6382 the names of all shell variables whose names begin with @var{prefix},
6383 is available (@pxref{Shell Parameter Expansion}).
6384
6385 @item
6386 Bash has @var{indirect} variable expansion using @code{$@{!word@}}
6387 (@pxref{Shell Parameter Expansion}).
6388
6389 @item
6390 Bash can expand positional parameters beyond @code{$9} using
6391 @code{$@{@var{num}@}}.
6392
6393 @item
6394 The @sc{posix} @code{$()} form of command substitution
6395 is implemented (@pxref{Command Substitution}),
6396 and preferred to the Bourne shell's @code{``} (which
6397 is also implemented for backwards compatibility).
6398
6399 @item
6400 Bash has process substitution (@pxref{Process Substitution}).
6401
6402 @item
6403 Bash automatically assigns variables that provide information about the
6404 current user (@env{UID}, @env{EUID}, and @env{GROUPS}), the current host
6405 (@env{HOSTTYPE}, @env{OSTYPE}, @env{MACHTYPE}, and @env{HOSTNAME}),
6406 and the instance of Bash that is running (@env{BASH},
6407 @env{BASH_VERSION}, and @env{BASH_VERSINFO}). @xref{Bash Variables},
6408 for details.
6409
6410 @item
6411 The @env{IFS} variable is used to split only the results of expansion,
6412 not all words (@pxref{Word Splitting}).
6413 This closes a longstanding shell security hole.
6414
6415 @item
6416 Bash implements the full set of @sc{posix} 1003.2 filename expansion operators,
6417 including @var{character classes}, @var{equivalence classes}, and
6418 @var{collating symbols} (@pxref{Filename Expansion}).
6419
6420 @item
6421 Bash implements extended pattern matching features when the @code{extglob}
6422 shell option is enabled (@pxref{Pattern Matching}).
6423
6424 @item
6425 It is possible to have a variable and a function with the same name;
6426 @code{sh} does not separate the two name spaces.
6427
6428 @item
6429 Bash functions are permitted to have local variables using the
6430 @code{local} builtin, and thus useful recursive functions may be written
6431 (@pxref{Bash Builtins}).
6432
6433 @item
6434 Variable assignments preceding commands affect only that command, even
6435 builtins and functions (@pxref{Environment}).
6436 In @code{sh}, all variable assignments
6437 preceding commands are global unless the command is executed from the
6438 file system.
6439
6440 @item
6441 Bash performs filename expansion on filenames specified as operands
6442 to input and output redirection operators (@pxref{Redirections}).
6443
6444 @item
6445 Bash contains the @samp{<>} redirection operator, allowing a file to be
6446 opened for both reading and writing, and the @samp{&>} redirection
6447 operator, for directing standard output and standard error to the same
6448 file (@pxref{Redirections}).
6449
6450 @item
6451 Bash treats a number of filenames specially when they are
6452 used in redirection operators (@pxref{Redirections}).
6453
6454 @item
6455 Bash can open network connections to arbitrary machines and services
6456 with the redirection operators (@pxref{Redirections}).
6457
6458 @item
6459 The @code{noclobber} option is available to avoid overwriting existing
6460 files with output redirection (@pxref{The Set Builtin}).
6461 The @samp{>|} redirection operator may be used to override @code{noclobber}.
6462
6463 @item
6464 The Bash @code{cd} and @code{pwd} builtins (@pxref{Bourne Shell Builtins})
6465 each take @option{-L} and @option{-P} options to switch between logical and
6466 physical modes.
6467
6468 @item
6469 Bash allows a function to override a builtin with the same name, and provides
6470 access to that builtin's functionality within the function via the
6471 @code{builtin} and @code{command} builtins (@pxref{Bash Builtins}).
6472
6473 @item
6474 The @code{command} builtin allows selective disabling of functions
6475 when command lookup is performed (@pxref{Bash Builtins}).
6476
6477 @item
6478 Individual builtins may be enabled or disabled using the @code{enable}
6479 builtin (@pxref{Bash Builtins}).
6480
6481 @item
6482 The Bash @code{exec} builtin takes additional options that allow users
6483 to control the contents of the environment passed to the executed
6484 command, and what the zeroth argument to the command is to be
6485 (@pxref{Bourne Shell Builtins}).
6486
6487 @item
6488 Shell functions may be exported to children via the environment
6489 using @code{export -f} (@pxref{Shell Functions}).
6490
6491 @item
6492 The Bash @code{export}, @code{readonly}, and @code{declare} builtins can
6493 take a @option{-f} option to act on shell functions, a @option{-p} option to
6494 display variables with various attributes set in a format that can be
6495 used as shell input, a @option{-n} option to remove various variable
6496 attributes, and @samp{name=value} arguments to set variable attributes
6497 and values simultaneously.
6498
6499 @item
6500 The Bash @code{hash} builtin allows a name to be associated with
6501 an arbitrary filename, even when that filename cannot be found by
6502 searching the @env{$PATH}, using @samp{hash -p}
6503 (@pxref{Bourne Shell Builtins}).
6504
6505 @item
6506 Bash includes a @code{help} builtin for quick reference to shell
6507 facilities (@pxref{Bash Builtins}).
6508
6509 @item
6510 The @code{printf} builtin is available to display formatted output
6511 (@pxref{Bash Builtins}).
6512
6513 @item
6514 The Bash @code{read} builtin (@pxref{Bash Builtins})
6515 will read a line ending in @samp{\} with
6516 the @option{-r} option, and will use the @env{REPLY} variable as a
6517 default if no non-option arguments are supplied.
6518 The Bash @code{read} builtin
6519 also accepts a prompt string with the @option{-p} option and will use
6520 Readline to obtain the line when given the @option{-e} option.
6521 The @code{read} builtin also has additional options to control input:
6522 the @option{-s} option will turn off echoing of input characters as
6523 they are read, the @option{-t} option will allow @code{read} to time out
6524 if input does not arrive within a specified number of seconds, the
6525 @option{-n} option will allow reading only a specified number of
6526 characters rather than a full line, and the @option{-d} option will read
6527 until a particular character rather than newline.
6528
6529 @item
6530 The @code{return} builtin may be used to abort execution of scripts
6531 executed with the @code{.} or @code{source} builtins
6532 (@pxref{Bourne Shell Builtins}).
6533
6534 @item
6535 Bash includes the @code{shopt} builtin, for finer control of shell
6536 optional capabilities (@pxref{Bash Builtins}).
6537
6538 @item
6539 Bash has much more optional behavior controllable with the @code{set}
6540 builtin (@pxref{The Set Builtin}).
6541
6542 @item
6543 The @code{test} builtin (@pxref{Bourne Shell Builtins})
6544 is slightly different, as it implements the @sc{posix} algorithm,
6545 which specifies the behavior based on the number of arguments.
6546
6547 @item
6548 The @code{trap} builtin (@pxref{Bourne Shell Builtins})
6549 allows a @code{DEBUG} pseudo-signal specification,
6550 similar to @code{EXIT}. Commands specified with a @code{DEBUG} trap are
6551 executed after every simple command. The @code{DEBUG} trap is not
6552 inherited by shell functions.
6553
6554 @item
6555 The Bash @code{type} builtin is more extensive and gives more information
6556 about the names it finds (@pxref{Bash Builtins}).
6557
6558 @item
6559 The Bash @code{umask} builtin permits a @option{-p} option to cause
6560 the output to be displayed in the form of a @code{umask} command
6561 that may be reused as input (@pxref{Bourne Shell Builtins}).
6562
6563 @item
6564 Bash implements a @code{csh}-like directory stack, and provides the
6565 @code{pushd}, @code{popd}, and @code{dirs} builtins to manipulate it
6566 (@pxref{The Directory Stack}).
6567 Bash also makes the directory stack visible as the value of the
6568 @env{DIRSTACK} shell variable.
6569
6570 @item
6571 Bash interprets special backslash-escaped characters in the prompt
6572 strings when interactive (@pxref{Printing a Prompt}).
6573
6574 @item
6575 The Bash restricted mode is more useful (@pxref{The Restricted Shell});
6576 the SVR4.2 shell restricted mode is too limited.
6577
6578 @item
6579 The @code{disown} builtin can remove a job from the internal shell
6580 job table (@pxref{Job Control Builtins}) or suppress the sending
6581 of @code{SIGHUP} to a job when the shell exits as the result of a
6582 @code{SIGHUP}.
6583
6584 @item
6585 The SVR4.2 shell has two privilege-related builtins
6586 (@code{mldmode} and @code{priv}) not present in Bash.
6587
6588 @item
6589 Bash does not have the @code{stop} or @code{newgrp} builtins.
6590
6591 @item
6592 Bash does not use the @env{SHACCT} variable or perform shell accounting.
6593
6594 @item
6595 The SVR4.2 @code{sh} uses a @env{TIMEOUT} variable like Bash uses
6596 @env{TMOUT}.
6597
6598 @end itemize
6599
6600 @noindent
6601 More features unique to Bash may be found in @ref{Bash Features}.
6602
6603
6604 @appendixsec Implementation Differences From The SVR4.2 Shell
6605
6606 Since Bash is a completely new implementation, it does not suffer from
6607 many of the limitations of the SVR4.2 shell. For instance:
6608
6609 @itemize @bullet
6610
6611 @item
6612 Bash does not fork a subshell when redirecting into or out of
6613 a shell control structure such as an @code{if} or @code{while}
6614 statement.
6615
6616 @item
6617 Bash does not allow unbalanced quotes. The SVR4.2 shell will silently
6618 insert a needed closing quote at @code{EOF} under certain circumstances.
6619 This can be the cause of some hard-to-find errors.
6620
6621 @item
6622 The SVR4.2 shell uses a baroque memory management scheme based on
6623 trapping @code{SIGSEGV}. If the shell is started from a process with
6624 @code{SIGSEGV} blocked (e.g., by using the @code{system()} C library
6625 function call), it misbehaves badly.
6626
6627 @item
6628 In a questionable attempt at security, the SVR4.2 shell,
6629 when invoked without the @option{-p} option, will alter its real
6630 and effective @sc{uid} and @sc{gid} if they are less than some
6631 magic threshold value, commonly 100.
6632 This can lead to unexpected results.
6633
6634 @item
6635 The SVR4.2 shell does not allow users to trap @code{SIGSEGV},
6636 @code{SIGALRM}, or @code{SIGCHLD}.
6637
6638 @item
6639 The SVR4.2 shell does not allow the @env{IFS}, @env{MAILCHECK},
6640 @env{PATH}, @env{PS1}, or @env{PS2} variables to be unset.
6641
6642 @item
6643 The SVR4.2 shell treats @samp{^} as the undocumented equivalent of
6644 @samp{|}.
6645
6646 @item
6647 Bash allows multiple option arguments when it is invoked (@code{-x -v});
6648 the SVR4.2 shell allows only one option argument (@code{-xv}). In
6649 fact, some versions of the shell dump core if the second argument begins
6650 with a @samp{-}.
6651
6652 @item
6653 The SVR4.2 shell exits a script if any builtin fails; Bash exits
6654 a script only if one of the @sc{posix} 1003.2 special builtins fails, and
6655 only for certain failures, as enumerated in the @sc{posix} 1003.2 standard.
6656
6657 @item
6658 The SVR4.2 shell behaves differently when invoked as @code{jsh}
6659 (it turns on job control).
6660 @end itemize
6661
6662 @node Builtin Index
6663 @unnumbered Index of Shell Builtin Commands
6664 @printindex bt
6665
6666 @node Reserved Word Index
6667 @unnumbered Index of Shell Reserved Words
6668 @printindex rw
6669
6670 @node Variable Index
6671 @unnumbered Parameter and Variable Index
6672 @printindex vr
6673
6674 @node Function Index
6675 @unnumbered Function Index
6676 @printindex fn
6677
6678 @node Concept Index
6679 @unnumbered Concept Index
6680 @printindex cp
6681
6682 @contents
6683 @bye