← Back to branch summary

~ubuntu-branches/ubuntu/trusty/bash/trusty-security

« back to all changes in this revision

Viewing changes to .pc/exec-redirections-doc.diff/doc/bashref.texi

  • Committer: Package Import Robot
  • Author(s): Matthias Klose
  • Date: 2014-03-03 22:52:05 UTC
  • mfrom: (1.3.5) (2.2.6 experimental)
  • Revision ID: package-import@ubuntu.com-20140303225205-87ltrt5kspeq0g1b
Tags: 4.3-1ubuntu1
* Merge with Debian; remaining changes:
  - skel.bashrc:
    - Run lesspipe.
    - Enable ls aliases.
    - Set options in ll alias to -alF.
    - Define an alert alias.
    - Enabled colored grep aliases.
  - etc.bash.bashrc:
    - Add sudo hint.

Show diffs side-by-side

added added

removed removed

Lines of Context:
.pc/exec-redirections-doc.diff/doc/bashref.texi
 
1
\input texinfo.tex @c -*- texinfo -*-
 
2
@c %**start of header
 
3
@setfilename bashref.info
 
4
@settitle Bash Reference Manual
 
5
 
 
6
@include version.texi
 
7
@c %**end of header
 
8
 
 
9
@copying
 
10
This text is a brief description of the features that are present in
 
11
the Bash shell (version @value{VERSION}, @value{UPDATED}).
 
12
 
 
13
This is Edition @value{EDITION}, last updated @value{UPDATED},
 
14
of @cite{The GNU Bash Reference Manual},
 
15
for @code{Bash}, Version @value{VERSION}.
 
16
 
 
17
Copyright @copyright{} 1988--2014 Free Software Foundation, Inc.
 
18
 
 
19
@quotation
 
20
Permission is granted to copy, distribute and/or modify this document
 
21
under the terms of the GNU Free Documentation License, Version 1.3 or
 
22
any later version published by the Free Software Foundation; with no
 
23
Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
 
24
A copy of the license is included in the section entitled
 
25
``GNU Free Documentation License''.
 
26
@end quotation
 
27
@end copying
 
28
 
 
29
@defcodeindex bt
 
30
@defcodeindex rw
 
31
@set BashFeatures
 
32
 
 
33
@dircategory Basics
 
34
@direntry
 
35
* Bash: (bash).                     The GNU Bourne-Again SHell.
 
36
@end direntry
 
37
 
 
38
@finalout
 
39
 
 
40
@titlepage
 
41
@title Bash Reference Manual
 
42
@subtitle Reference Documentation for Bash
 
43
@subtitle Edition @value{EDITION}, for @code{Bash} Version @value{VERSION}.
 
44
@subtitle @value{UPDATED-MONTH}
 
45
@author Chet Ramey, Case Western Reserve University
 
46
@author Brian Fox, Free Software Foundation
 
47
 
 
48
@page
 
49
@vskip 0pt plus 1filll
 
50
@insertcopying
 
51
 
 
52
@end titlepage
 
53
 
 
54
@contents
 
55
 
 
56
@ifnottex
 
57
@node Top, Introduction, (dir), (dir)
 
58
@top Bash Features
 
59
 
 
60
This text is a brief description of the features that are present in
 
61
the Bash shell (version @value{VERSION}, @value{UPDATED}).
 
62
The Bash home page is @url{http://www.gnu.org/software/bash/}.
 
63
 
 
64
This is Edition @value{EDITION}, last updated @value{UPDATED},
 
65
of @cite{The GNU Bash Reference Manual},
 
66
for @code{Bash}, Version @value{VERSION}.
 
67
 
 
68
Bash contains features that appear in other popular shells, and some
 
69
features that only appear in Bash.  Some of the shells that Bash has
 
70
borrowed concepts from are the Bourne Shell (@file{sh}), the Korn Shell
 
71
(@file{ksh}), and the C-shell (@file{csh} and its successor,
 
72
@file{tcsh}).  The following menu breaks the features up into
 
73
categories, noting which features were inspired by other shells and
 
74
which are specific to Bash.
 
75
 
 
76
This manual is meant as a brief introduction to features found in
 
77
Bash.  The Bash manual page should be used as the definitive
 
78
reference on shell behavior.
 
79
 
 
80
@menu
 
81
* Introduction::                An introduction to the shell.
 
82
* Definitions::                 Some definitions used in the rest of this
 
83
                                manual.
 
84
* Basic Shell Features::        The shell "building blocks".
 
85
* Shell Builtin Commands::      Commands that are a part of the shell.
 
86
* Shell Variables::             Variables used or set by Bash.
 
87
* Bash Features::               Features found only in Bash.
 
88
* Job Control::                 What job control is and how Bash allows you
 
89
                                to use it.
 
90
* Command Line Editing::        Chapter describing the command line
 
91
                                editing features.
 
92
* Using History Interactively:: Command History Expansion
 
93
* Installing Bash::             How to build and install Bash on your system.
 
94
* Reporting Bugs::              How to report bugs in Bash.
 
95
* Major Differences From The Bourne Shell::     A terse list of the differences
 
96
                                                between Bash and historical
 
97
                                                versions of /bin/sh.
 
98
* GNU Free Documentation License::      Copying and sharing this documentation.
 
99
* Indexes::                     Various indexes for this manual.
 
100
@end menu
 
101
@end ifnottex
 
102
 
 
103
@node Introduction
 
104
@chapter Introduction
 
105
@menu
 
106
* What is Bash?::               A short description of Bash.
 
107
* What is a shell?::            A brief introduction to shells.
 
108
@end menu
 
109
 
 
110
@node What is Bash?
 
111
@section What is Bash?
 
112
 
 
113
Bash is the shell, or command language interpreter,
 
114
for the @sc{gnu} operating system.
 
115
The name is an acronym for the @samp{Bourne-Again SHell},
 
116
a pun on Stephen Bourne, the author of the direct ancestor of
 
117
the current Unix shell @code{sh}, 
 
118
which appeared in the Seventh Edition Bell Labs Research version
 
119
of Unix.
 
120
 
 
121
Bash is largely compatible with @code{sh} and incorporates useful
 
122
features from the Korn shell @code{ksh} and the C shell @code{csh}.
 
123
It is intended to be a conformant implementation of the @sc{ieee}
 
124
@sc{posix} Shell and Tools portion of the @sc{ieee} @sc{posix}
 
125
specification (@sc{ieee} Standard 1003.1).
 
126
It offers functional improvements over @code{sh} for both interactive and
 
127
programming use.
 
128
 
 
129
While the @sc{gnu} operating system provides other shells, including
 
130
a version of @code{csh}, Bash is the default shell.
 
131
Like other @sc{gnu} software, Bash is quite portable.  It currently runs
 
132
on nearly every version of Unix and a few other operating systems @minus{}
 
133
independently-supported ports exist for @sc{ms-dos}, @sc{os/2},
 
134
and Windows platforms.
 
135
 
 
136
@node What is a shell?
 
137
@section What is a shell?
 
138
 
 
139
At its base, a shell is simply a macro processor that executes
 
140
commands.  The term macro processor means functionality where text
 
141
and symbols are expanded to create larger expressions.
 
142
 
 
143
A Unix shell is both a command interpreter and a programming
 
144
language.  As a command interpreter, the shell provides the user
 
145
interface to the rich set of @sc{gnu} utilities.  The programming
 
146
language features allow these utilities to be combined.
 
147
Files containing commands can be created, and become
 
148
commands themselves.  These new commands have the same status as
 
149
system commands in directories such as @file{/bin}, allowing users
 
150
or groups to establish custom environments to automate their common
 
151
tasks.
 
152
 
 
153
Shells may be used interactively or non-interactively.  In
 
154
interactive mode, they accept input typed from the keyboard.
 
155
When executing non-interactively, shells execute commands read
 
156
from a file.
 
157
 
 
158
A shell allows execution of @sc{gnu} commands, both synchronously and
 
159
asynchronously.
 
160
The shell waits for synchronous commands to complete before accepting
 
161
more input; asynchronous commands continue to execute in parallel
 
162
with the shell while it reads and executes additional commands.
 
163
The @dfn{redirection} constructs permit
 
164
fine-grained control of the input and output of those commands.
 
165
Moreover, the shell allows control over the contents of commands'
 
166
environments.
 
167
 
 
168
Shells also provide a small set of built-in
 
169
commands (@dfn{builtins}) implementing functionality impossible
 
170
or inconvenient to obtain via separate utilities.
 
171
For example, @code{cd}, @code{break}, @code{continue}, and
 
172
@code{exec} cannot be implemented outside of the shell because
 
173
they directly manipulate the shell itself.
 
174
The @code{history}, @code{getopts}, @code{kill}, or @code{pwd}
 
175
builtins, among others, could be implemented in separate utilities,
 
176
but they are more convenient to use as builtin commands.
 
177
All of the shell builtins are described in
 
178
subsequent sections.
 
179
 
 
180
While executing commands is essential, most of the power (and
 
181
complexity) of shells is due to their embedded programming
 
182
languages.  Like any high-level language, the shell provides
 
183
variables, flow control constructs, quoting, and functions. 
 
184
 
 
185
Shells offer features geared specifically for
 
186
interactive use rather than to augment the programming language. 
 
187
These interactive features include job control, command line
 
188
editing, command history and aliases.  Each of these features is
 
189
described in this manual.
 
190
 
 
191
@node Definitions
 
192
@chapter Definitions
 
193
These definitions are used throughout the remainder of this manual.
 
194
 
 
195
@table @code
 
196
 
 
197
@item POSIX
 
198
@cindex POSIX
 
199
A family of open system standards based on Unix.  Bash
 
200
is primarily concerned with the Shell and Utilities portion of the
 
201
@sc{posix} 1003.1 standard. 
 
202
 
 
203
@item blank
 
204
A space or tab character.
 
205
 
 
206
@item builtin
 
207
@cindex builtin
 
208
A command that is implemented internally by the shell itself, rather
 
209
than by an executable program somewhere in the file system.
 
210
 
 
211
@item control operator
 
212
@cindex control operator
 
213
A @code{token} that performs a control function.  It is a @code{newline}
 
214
or one of the following:
 
215
@samp{||}, @samp{&&}, @samp{&}, @samp{;}, @samp{;;},
 
216
@samp{|}, @samp{|&}, @samp{(}, or @samp{)}.
 
217
 
 
218
@item exit status
 
219
@cindex exit status
 
220
The value returned by a command to its caller.  The value is restricted
 
221
to eight bits, so the maximum value is 255.
 
222
 
 
223
@item field
 
224
@cindex field
 
225
A unit of text that is the result of one of the shell expansions.  After
 
226
expansion, when executing a command, the resulting fields are used as
 
227
the command name and arguments.
 
228
 
 
229
@item filename
 
230
@cindex filename
 
231
A string of characters used to identify a file.
 
232
 
 
233
@item job
 
234
@cindex job
 
235
A set of processes comprising a pipeline, and any processes descended
 
236
from it, that are all in the same process group.
 
237
 
 
238
@item job control
 
239
@cindex job control
 
240
A mechanism by which users can selectively stop (suspend) and restart
 
241
(resume) execution of processes.
 
242
 
 
243
@item metacharacter
 
244
@cindex metacharacter
 
245
A character that, when unquoted, separates words.  A metacharacter is
 
246
a @code{blank} or one of the following characters:
 
247
@samp{|}, @samp{&}, @samp{;}, @samp{(}, @samp{)}, @samp{<}, or
 
248
@samp{>}.
 
249
 
 
250
@item name
 
251
@cindex name
 
252
@cindex identifier
 
253
A @code{word} consisting solely of letters, numbers, and underscores,
 
254
and beginning with a letter or underscore.  @code{Name}s are used as
 
255
shell variable and function names.
 
256
Also referred to as an @code{identifier}.
 
257
 
 
258
@item operator
 
259
@cindex operator, shell
 
260
A @code{control operator} or a @code{redirection operator}.
 
261
@xref{Redirections}, for a list of redirection operators.
 
262
Operators contain at least one unquoted @code{metacharacter}.
 
263
 
 
264
@item process group
 
265
@cindex process group
 
266
A collection of related processes each having the same process
 
267
group @sc{id}.
 
268
 
 
269
@item process group ID
 
270
@cindex process group ID
 
271
A unique identifier that represents a @code{process group}
 
272
during its lifetime.
 
273
 
 
274
@item reserved word
 
275
@cindex reserved word
 
276
A @code{word} that has a special meaning to the shell.  Most reserved
 
277
words introduce shell flow control constructs, such as @code{for} and
 
278
@code{while}.
 
279
 
 
280
@item return status
 
281
@cindex return status
 
282
A synonym for @code{exit status}.
 
283
 
 
284
@item signal
 
285
@cindex signal
 
286
A mechanism by which a process may be notified by the kernel
 
287
of an event occurring in the system.
 
288
 
 
289
@item special builtin
 
290
@cindex special builtin
 
291
A shell builtin command that has been classified as special by the
 
292
@sc{posix} standard.
 
293
 
 
294
@item token
 
295
@cindex token
 
296
A sequence of characters considered a single unit by the shell.
 
297
It is either a @code{word} or an @code{operator}.
 
298
 
 
299
@item word
 
300
@cindex word
 
301
A sequence of characters treated as a unit by the shell.
 
302
Words may not include unquoted @code{metacharacters}.
 
303
@end table
 
304
 
 
305
@node Basic Shell Features
 
306
@chapter Basic Shell Features
 
307
@cindex Bourne shell
 
308
 
 
309
Bash is an acronym for @samp{Bourne-Again SHell}.
 
310
The Bourne shell is
 
311
the traditional Unix shell originally written by Stephen Bourne.
 
312
All of the Bourne shell builtin commands are available in Bash,
 
313
The rules for evaluation and quoting are taken from the @sc{posix}
 
314
specification for the `standard' Unix shell.
 
315
 
 
316
This chapter briefly summarizes the shell's `building blocks':
 
317
commands, control structures, shell functions, shell @i{parameters},
 
318
shell expansions,
 
319
@i{redirections}, which are a way to direct input and output from
 
320
and to named files, and how the shell executes commands.
 
321
 
 
322
@menu
 
323
* Shell Syntax::                What your input means to the shell.
 
324
* Shell Commands::              The types of commands you can use.
 
325
* Shell Functions::             Grouping commands by name.
 
326
* Shell Parameters::            How the shell stores values.
 
327
* Shell Expansions::            How Bash expands parameters and the various
 
328
                                expansions available.
 
329
* Redirections::                A way to control where input and output go.
 
330
* Executing Commands::          What happens when you run a command.
 
331
* Shell Scripts::               Executing files of shell commands.
 
332
@end menu
 
333
 
 
334
@node Shell Syntax
 
335
@section Shell Syntax
 
336
@menu
 
337
* Shell Operation::     The basic operation of the shell.
 
338
* Quoting::             How to remove the special meaning from characters.
 
339
* Comments::            How to specify comments.
 
340
@end menu
 
341
 
 
342
When the shell reads input, it proceeds through a
 
343
sequence of operations.  If the input indicates the beginning of a
 
344
comment, the shell ignores the comment symbol (@samp{#}), and the rest
 
345
of that line.
 
346
                                
 
347
Otherwise, roughly speaking,  the shell reads its input and
 
348
divides the input into words and operators, employing the quoting rules
 
349
to select which meanings to assign various words and characters.
 
350
 
 
351
The shell then parses these tokens into commands and other constructs,
 
352
removes the special meaning of certain words or characters, expands
 
353
others, redirects input and output as needed, executes the specified
 
354
command, waits for the command's exit status, and makes that exit status
 
355
available for further inspection or processing.
 
356
 
 
357
@node Shell Operation
 
358
@subsection Shell Operation
 
359
 
 
360
The following is a brief description of the shell's operation when it
 
361
reads and executes a command.  Basically, the shell does the
 
362
following:
 
363
 
 
364
@enumerate
 
365
@item
 
366
Reads its input from a file (@pxref{Shell Scripts}), from a string
 
367
supplied as an argument to the @option{-c} invocation option
 
368
(@pxref{Invoking Bash}), or from the user's terminal.
 
369
 
 
370
@item
 
371
Breaks the input into words and operators, obeying the quoting rules
 
372
described in @ref{Quoting}.  These tokens are separated by
 
373
@code{metacharacters}.  Alias expansion is performed by this step
 
374
(@pxref{Aliases}).
 
375
 
 
376
@item
 
377
Parses the tokens into simple and compound commands
 
378
(@pxref{Shell Commands}).
 
379
 
 
380
@item
 
381
Performs the various shell expansions (@pxref{Shell Expansions}), breaking
 
382
the expanded tokens into lists of filenames (@pxref{Filename Expansion})
 
383
and commands and arguments.
 
384
 
 
385
@item
 
386
Performs any necessary redirections (@pxref{Redirections}) and removes
 
387
the redirection operators and their operands from the argument list.
 
388
 
 
389
@item
 
390
Executes the command (@pxref{Executing Commands}).
 
391
 
 
392
@item
 
393
Optionally waits for the command to complete and collects its exit
 
394
status (@pxref{Exit Status}).
 
395
 
 
396
@end enumerate
 
397
 
 
398
@node Quoting
 
399
@subsection Quoting
 
400
@cindex quoting
 
401
@menu
 
402
* Escape Character::    How to remove the special meaning from a single
 
403
                        character.
 
404
* Single Quotes::       How to inhibit all interpretation of a sequence
 
405
                        of characters.
 
406
* Double Quotes::       How to suppress most of the interpretation of a
 
407
                        sequence of characters.
 
408
* ANSI-C Quoting::      How to expand ANSI-C sequences in quoted strings.
 
409
* Locale Translation::  How to translate strings into different languages.
 
410
@end menu
 
411
 
 
412
Quoting is used to remove the special meaning of certain
 
413
characters or words to the shell.  Quoting can be used to
 
414
disable special treatment for special characters, to prevent
 
415
reserved words from being recognized as such, and to prevent
 
416
parameter expansion.
 
417
 
 
418
Each of the shell metacharacters (@pxref{Definitions})
 
419
has special meaning to the shell and must be quoted if it is to
 
420
represent itself.
 
421
When the command history expansion facilities are being used
 
422
(@pxref{History Interaction}), the
 
423
@var{history expansion} character, usually @samp{!}, must be quoted
 
424
to prevent history expansion.  @xref{Bash History Facilities}, for
 
425
more details concerning history expansion.
 
426
 
 
427
There are three quoting mechanisms: the
 
428
@var{escape character}, single quotes, and double quotes.
 
429
 
 
430
@node Escape Character
 
431
@subsubsection Escape Character
 
432
A non-quoted backslash @samp{\} is the Bash escape character.
 
433
It preserves the literal value of the next character that follows,
 
434
with the exception of @code{newline}.  If a @code{\newline} pair
 
435
appears, and the backslash itself is not quoted, the @code{\newline}
 
436
is treated as a line continuation (that is, it is removed from
 
437
the input stream and effectively ignored).
 
438
 
 
439
@node Single Quotes
 
440
@subsubsection Single Quotes
 
441
 
 
442
Enclosing characters in single quotes (@samp{'}) preserves the literal value
 
443
of each character within the quotes.  A single quote may not occur
 
444
between single quotes, even when preceded by a backslash.
 
445
 
 
446
@node Double Quotes
 
447
@subsubsection Double Quotes
 
448
 
 
449
Enclosing characters in double quotes (@samp{"}) preserves the literal value
 
450
of all characters within the quotes, with the exception of
 
451
@samp{$}, @samp{`}, @samp{\},
 
452
and, when history expansion is enabled, @samp{!}.
 
453
The characters @samp{$} and @samp{`}
 
454
retain their special meaning within double quotes (@pxref{Shell Expansions}).
 
455
The backslash retains its special meaning only when followed by one of
 
456
the following characters:
 
457
@samp{$}, @samp{`}, @samp{"}, @samp{\}, or @code{newline}.
 
458
Within double quotes, backslashes that are followed by one of these
 
459
characters are removed.  Backslashes preceding characters without a
 
460
special meaning are left unmodified.
 
461
A double quote may be quoted within double quotes by preceding it with
 
462
a backslash.
 
463
If enabled, history expansion will be performed unless an @samp{!}
 
464
appearing in double quotes is escaped using a backslash.
 
465
The backslash preceding the @samp{!} is not removed.
 
466
 
 
467
The special parameters @samp{*} and @samp{@@} have special meaning
 
468
when in double quotes (@pxref{Shell Parameter Expansion}).
 
469
 
 
470
@node ANSI-C Quoting
 
471
@subsubsection ANSI-C Quoting
 
472
@cindex quoting, ANSI
 
473
 
 
474
Words of the form @code{$'@var{string}'} are treated specially.  The
 
475
word expands to @var{string}, with backslash-escaped characters replaced
 
476
as specified by the ANSI C standard.  Backslash escape sequences, if
 
477
present, are decoded as follows:
 
478
 
 
479
@table @code
 
480
@item \a
 
481
alert (bell)
 
482
@item \b
 
483
backspace
 
484
@item \e
 
485
@itemx \E
 
486
an escape character (not ANSI C)
 
487
@item \f
 
488
form feed
 
489
@item \n
 
490
newline
 
491
@item \r
 
492
carriage return
 
493
@item \t
 
494
horizontal tab
 
495
@item \v
 
496
vertical tab
 
497
@item \\
 
498
backslash
 
499
@item \'
 
500
single quote
 
501
@item \"
 
502
double quote
 
503
@item \@var{nnn}
 
504
the eight-bit character whose value is the octal value @var{nnn}
 
505
(one to three digits)
 
506
@item \x@var{HH}
 
507
the eight-bit character whose value is the hexadecimal value @var{HH}
 
508
(one or two hex digits)
 
509
@item \u@var{HHHH}
 
510
the Unicode (ISO/IEC 10646) character whose value is the hexadecimal value
 
511
@var{HHHH} (one to four hex digits)
 
512
@item \U@var{HHHHHHHH}
 
513
the Unicode (ISO/IEC 10646) character whose value is the hexadecimal value
 
514
@var{HHHHHHHH} (one to eight hex digits)
 
515
@item \c@var{x}
 
516
a control-@var{x} character
 
517
@end table
 
518
 
 
519
@noindent
 
520
The expanded result is single-quoted, as if the dollar sign had not
 
521
been present.
 
522
 
 
523
@node Locale Translation
 
524
@subsubsection Locale-Specific Translation
 
525
@cindex localization
 
526
@cindex internationalization
 
527
@cindex native languages
 
528
@cindex translation, native languages
 
529
 
 
530
A double-quoted string preceded by a dollar sign (@samp{$}) will cause
 
531
the string to be translated according to the current locale.
 
532
If the current locale is @code{C} or @code{POSIX}, the dollar sign
 
533
is ignored.
 
534
If the string is translated and replaced, the replacement is
 
535
double-quoted.
 
536
 
 
537
@vindex LC_MESSAGES
 
538
@vindex TEXTDOMAIN
 
539
@vindex TEXTDOMAINDIR
 
540
Some systems use the message catalog selected by the @env{LC_MESSAGES}
 
541
shell variable.  Others create the name of the message catalog from the
 
542
value of the @env{TEXTDOMAIN} shell variable, possibly adding a
 
543
suffix of @samp{.mo}.  If you use the @env{TEXTDOMAIN} variable, you
 
544
may need to set the @env{TEXTDOMAINDIR} variable to the location of
 
545
the message catalog files.  Still others use both variables in this
 
546
fashion:
 
547
@env{TEXTDOMAINDIR}/@env{LC_MESSAGES}/LC_MESSAGES/@env{TEXTDOMAIN}.mo.
 
548
 
 
549
@node Comments
 
550
@subsection Comments
 
551
@cindex comments, shell
 
552
 
 
553
In a non-interactive shell, or an interactive shell in which the
 
554
@code{interactive_comments} option to the @code{shopt}
 
555
builtin is enabled (@pxref{The Shopt Builtin}),
 
556
a word beginning with @samp{#}
 
557
causes that word and all remaining characters on that line to
 
558
be ignored.  An interactive shell without the @code{interactive_comments}
 
559
option enabled does not allow comments.  The @code{interactive_comments}
 
560
option is on by default in interactive shells.
 
561
@xref{Interactive Shells}, for a description of what makes
 
562
a shell interactive.
 
563
 
 
564
@node Shell Commands
 
565
@section Shell Commands
 
566
@cindex commands, shell
 
567
 
 
568
A simple shell command such as @code{echo a b c} consists of the command
 
569
itself followed by arguments, separated by spaces.
 
570
 
 
571
More complex shell commands are composed of simple commands arranged together
 
572
in a variety of ways: in a pipeline in which the output of one command
 
573
becomes the input of a second, in a loop or conditional construct, or in
 
574
some other grouping.
 
575
 
 
576
@menu
 
577
* Simple Commands::             The most common type of command.
 
578
* Pipelines::                   Connecting the input and output of several
 
579
                                commands.
 
580
* Lists::                       How to execute commands sequentially.
 
581
* Compound Commands::           Shell commands for control flow.
 
582
* Coprocesses::                 Two-way communication between commands.
 
583
* GNU Parallel::                Running commands in parallel.
 
584
@end menu
 
585
 
 
586
@node Simple Commands
 
587
@subsection Simple Commands
 
588
@cindex commands, simple
 
589
 
 
590
A simple command is the kind of command encountered most often.
 
591
It's just a sequence of words separated by @code{blank}s, terminated
 
592
by one of the shell's control operators (@pxref{Definitions}).  The
 
593
first word generally specifies a command to be executed, with the
 
594
rest of the words being that command's arguments.
 
595
 
 
596
The return status (@pxref{Exit Status}) of a simple command is
 
597
its exit status as provided
 
598
by the @sc{posix} 1003.1 @code{waitpid} function, or 128+@var{n} if
 
599
the command was terminated by signal @var{n}.
 
600
 
 
601
@node Pipelines
 
602
@subsection Pipelines
 
603
@cindex pipeline
 
604
@cindex commands, pipelines
 
605
 
 
606
A @code{pipeline} is a sequence of simple commands separated by one of
 
607
the control operators @samp{|} or @samp{|&}.
 
608
 
 
609
@rwindex time
 
610
@rwindex !
 
611
@cindex command timing
 
612
The format for a pipeline is
 
613
@example
 
614
[time [-p]] [!] @var{command1} [ | or |& @var{command2} ] @dots{}
 
615
@end example
 
616
 
 
617
@noindent
 
618
The output of each command in the pipeline is connected via a pipe
 
619
to the input of the next command.
 
620
That is, each command reads the previous command's output.  This
 
621
connection is performed before any redirections specified by the
 
622
command.
 
623
 
 
624
If @samp{|&} is used, @var{command1}'s standard error, in addition to
 
625
its standard output, is connected to
 
626
@var{command2}'s standard input through the pipe;
 
627
it is shorthand for @code{2>&1 |}.
 
628
This implicit redirection of the standard error to the standard output is
 
629
performed after any redirections specified by the command.
 
630
 
 
631
The reserved word @code{time} causes timing statistics
 
632
to be printed for the pipeline once it finishes.
 
633
The statistics currently consist of elapsed (wall-clock) time and
 
634
user and system time consumed by the command's execution.
 
635
The @option{-p} option changes the output format to that specified
 
636
by @sc{posix}.
 
637
When the shell is in @sc{posix} mode (@pxref{Bash POSIX Mode}),
 
638
it does not recognize @code{time} as a reserved word if the next
 
639
token begins with a @samp{-}.
 
640
The @env{TIMEFORMAT} variable may be set to a format string that
 
641
specifies how the timing information should be displayed.
 
642
@xref{Bash Variables}, for a description of the available formats.
 
643
The use of @code{time} as a reserved word permits the timing of
 
644
shell builtins, shell functions, and pipelines.  An external
 
645
@code{time} command cannot time these easily.
 
646
 
 
647
When the shell is in @sc{posix} mode (@pxref{Bash POSIX Mode}), @code{time}
 
648
may be followed by a newline.  In this case, the shell displays the
 
649
total user and system time consumed by the shell and its children.
 
650
The @env{TIMEFORMAT} variable may be used to specify the format of
 
651
the time information.
 
652
 
 
653
If the pipeline is not executed asynchronously (@pxref{Lists}), the
 
654
shell waits for all commands in the pipeline to complete.
 
655
 
 
656
Each command in a pipeline is executed in its own subshell
 
657
(@pxref{Command Execution Environment}).  The exit
 
658
status of a pipeline is the exit status of the last command in the
 
659
pipeline, unless the @code{pipefail} option is enabled
 
660
(@pxref{The Set Builtin}).
 
661
If @code{pipefail} is enabled, the pipeline's return status is the
 
662
value of the last (rightmost) command to exit with a non-zero status,
 
663
or zero if all commands exit successfully.
 
664
If the reserved word @samp{!} precedes the pipeline, the
 
665
exit status is the logical negation of the exit status as described
 
666
above.
 
667
The shell waits for all commands in the pipeline to terminate before
 
668
returning a value.
 
669
 
 
670
@node Lists
 
671
@subsection Lists of Commands
 
672
@cindex commands, lists
 
673
 
 
674
A @code{list} is a sequence of one or more pipelines separated by one
 
675
of the operators @samp{;}, @samp{&}, @samp{&&}, or @samp{||},
 
676
and optionally terminated by one of @samp{;}, @samp{&}, or a
 
677
@code{newline}.
 
678
 
 
679
Of these list operators, @samp{&&} and @samp{||}
 
680
have equal precedence, followed by @samp{;} and @samp{&},
 
681
which have equal precedence.
 
682
 
 
683
A sequence of one or more newlines may appear in a @code{list}
 
684
to delimit commands, equivalent to a semicolon.
 
685
 
 
686
If a command is terminated by the control operator @samp{&},
 
687
the shell executes the command asynchronously in a subshell.
 
688
This is known as executing the command in the @var{background}.
 
689
The shell does not wait for the command to finish, and the return
 
690
status is 0 (true).
 
691
When job control is not active (@pxref{Job Control}),
 
692
the standard input for asynchronous commands, in the absence of any
 
693
explicit redirections, is redirected from @code{/dev/null}.
 
694
 
 
695
Commands separated by a @samp{;} are executed sequentially; the shell
 
696
waits for each command to terminate in turn.  The return status is the
 
697
exit status of the last command executed.
 
698
 
 
699
@sc{and} and @sc{or} lists are sequences of one or more pipelines
 
700
separated by the control operators @samp{&&} and @samp{||},
 
701
respectively.  @sc{and} and @sc{or} lists are executed with left
 
702
associativity.
 
703
 
 
704
An @sc{and} list has the form
 
705
@example
 
706
@var{command1} && @var{command2}
 
707
@end example
 
708
 
 
709
@noindent
 
710
@var{command2} is executed if, and only if, @var{command1}
 
711
returns an exit status of zero.
 
712
 
 
713
An @sc{or} list has the form
 
714
@example
 
715
@var{command1} || @var{command2}
 
716
@end example
 
717
 
 
718
@noindent
 
719
@var{command2} is executed if, and only if, @var{command1}
 
720
returns a non-zero exit status.
 
721
 
 
722
The return status of
 
723
@sc{and} and @sc{or} lists is the exit status of the last command
 
724
executed in the list.
 
725
 
 
726
@node Compound Commands
 
727
@subsection Compound Commands
 
728
@cindex commands, compound
 
729
 
 
730
@menu
 
731
* Looping Constructs::          Shell commands for iterative action.
 
732
* Conditional Constructs::      Shell commands for conditional execution.
 
733
* Command Grouping::            Ways to group commands.
 
734
@end menu
 
735
 
 
736
Compound commands are the shell programming constructs.
 
737
Each construct begins with a reserved word or control operator and is
 
738
terminated by a corresponding reserved word or operator.
 
739
Any redirections (@pxref{Redirections}) associated with a compound command
 
740
apply to all commands within that compound command unless explicitly overridden.
 
741
 
 
742
In most cases a list of commands in a compound command's description may be
 
743
separated from the rest of the command by one or more newlines, and may be
 
744
followed by a newline in place of a semicolon.
 
745
 
 
746
Bash provides looping constructs, conditional commands, and mechanisms
 
747
to group commands and execute them as a unit.
 
748
 
 
749
@node Looping Constructs
 
750
@subsubsection Looping Constructs
 
751
@cindex commands, looping
 
752
 
 
753
Bash supports the following looping constructs.
 
754
 
 
755
Note that wherever a @samp{;} appears in the description of a
 
756
command's syntax, it may be replaced with one or more newlines.
 
757
 
 
758
@table @code
 
759
@item until
 
760
@rwindex until
 
761
@rwindex do
 
762
@rwindex done
 
763
The syntax of the @code{until} command is:
 
764
 
 
765
@example
 
766
until @var{test-commands}; do @var{consequent-commands}; done
 
767
@end example
 
768
 
 
769
Execute @var{consequent-commands} as long as
 
770
@var{test-commands} has an exit status which is not zero.
 
771
The return status is the exit status of the last command executed
 
772
in @var{consequent-commands}, or zero if none was executed.
 
773
 
 
774
@item while
 
775
@rwindex while
 
776
The syntax of the @code{while} command is:
 
777
 
 
778
@example
 
779
while @var{test-commands}; do @var{consequent-commands}; done
 
780
@end example
 
781
 
 
782
Execute @var{consequent-commands} as long as
 
783
@var{test-commands} has an exit status of zero.
 
784
The return status is the exit status of the last command executed
 
785
in @var{consequent-commands}, or zero if none was executed.
 
786
 
 
787
@item for
 
788
@rwindex for
 
789
The syntax of the @code{for} command is:
 
790
 
 
791
@example
 
792
for @var{name} [ [in [@var{words} @dots{}] ] ; ] do @var{commands}; done
 
793
@end example
 
794
 
 
795
Expand @var{words}, and execute @var{commands} once for each member
 
796
in the resultant list, with @var{name} bound to the current member.
 
797
If @samp{in @var{words}} is not present, the @code{for} command
 
798
executes the @var{commands} once for each positional parameter that is
 
799
set, as if @samp{in "$@@"} had been specified
 
800
(@pxref{Special Parameters}).
 
801
The return status is the exit status of the last command that executes.
 
802
If there are no items in the expansion of @var{words}, no commands are
 
803
executed, and the return status is zero.
 
804
 
 
805
An alternate form of the @code{for} command is also supported:
 
806
 
 
807
@example
 
808
for (( @var{expr1} ; @var{expr2} ; @var{expr3} )) ; do @var{commands} ; done
 
809
@end example
 
810
 
 
811
First, the arithmetic expression @var{expr1} is evaluated according
 
812
to the rules described below (@pxref{Shell Arithmetic}).
 
813
The arithmetic expression @var{expr2} is then evaluated repeatedly
 
814
until it evaluates to zero.   
 
815
Each time @var{expr2} evaluates to a non-zero value, @var{commands} are
 
816
executed and the arithmetic expression @var{expr3} is evaluated.       
 
817
If any expression is omitted, it behaves as if it evaluates to 1.
 
818
The return value is the exit status of the last command in @var{commands}
 
819
that is executed, or false if any of the expressions is invalid.
 
820
@end table
 
821
 
 
822
The @code{break} and @code{continue} builtins (@pxref{Bourne Shell Builtins})
 
823
may be used to control loop execution.
 
824
 
 
825
@node Conditional Constructs
 
826
@subsubsection Conditional Constructs
 
827
@cindex commands, conditional
 
828
 
 
829
@table @code
 
830
@item if
 
831
@rwindex if
 
832
@rwindex then
 
833
@rwindex else
 
834
@rwindex elif
 
835
@rwindex fi
 
836
The syntax of the @code{if} command is:
 
837
 
 
838
@example
 
839
if @var{test-commands}; then
 
840
  @var{consequent-commands};
 
841
[elif @var{more-test-commands}; then
 
842
  @var{more-consequents};]
 
843
[else @var{alternate-consequents};]
 
844
fi
 
845
@end example
 
846
 
 
847
The @var{test-commands} list is executed, and if its return status is zero,
 
848
the @var{consequent-commands} list is executed.
 
849
If @var{test-commands} returns a non-zero status, each @code{elif} list
 
850
is executed in turn, and if its exit status is zero,
 
851
the corresponding @var{more-consequents} is executed and the   
 
852
command completes.
 
853
If @samp{else @var{alternate-consequents}} is present, and
 
854
the final command in the final @code{if} or @code{elif} clause
 
855
has a non-zero exit status, then @var{alternate-consequents} is executed.
 
856
The return status is the exit status of the last command executed, or
 
857
zero if no condition tested true.
 
858
 
 
859
@item case
 
860
@rwindex case
 
861
@rwindex in
 
862
@rwindex esac
 
863
The syntax of the @code{case} command is:
 
864
 
 
865
@example
 
866
case @var{word} in [ [(] @var{pattern} [| @var{pattern}]@dots{}) @var{command-list} ;;]@dots{} esac
 
867
@end example
 
868
 
 
869
@code{case} will selectively execute the @var{command-list} corresponding to
 
870
the first @var{pattern} that matches @var{word}.
 
871
If the shell option @code{nocasematch}
 
872
(see the description of @code{shopt} in @ref{The Shopt Builtin})
 
873
is enabled, the match is performed without regard to the case
 
874
of alphabetic characters.
 
875
The @samp{|} is used to separate multiple patterns, and the @samp{)}
 
876
operator terminates a pattern list.
 
877
A list of patterns and an associated command-list is known
 
878
as a @var{clause}.
 
879
 
 
880
Each clause must be terminated with @samp{;;}, @samp{;&}, or @samp{;;&}.
 
881
The @var{word} undergoes tilde expansion, parameter expansion, command
 
882
substitution, arithmetic expansion, and quote removal before matching is
 
883
attempted.  Each @var{pattern} undergoes tilde expansion, parameter
 
884
expansion, command substitution, and arithmetic expansion.
 
885
 
 
886
There may be an arbitrary number of @code{case} clauses, each terminated
 
887
by a @samp{;;}, @samp{;&}, or @samp{;;&}.
 
888
The first pattern that matches determines the
 
889
command-list that is executed.
 
890
It's a common idiom to use @samp{*} as the final pattern to define the
 
891
default case, since that pattern will always match.
 
892
 
 
893
Here is an example using @code{case} in a script that could be used to
 
894
describe one interesting feature of an animal:
 
895
 
 
896
@example
 
897
echo -n "Enter the name of an animal: "
 
898
read ANIMAL
 
899
echo -n "The $ANIMAL has "
 
900
case $ANIMAL in
 
901
  horse | dog | cat) echo -n "four";;
 
902
  man | kangaroo ) echo -n "two";;
 
903
  *) echo -n "an unknown number of";;
 
904
esac
 
905
echo " legs."
 
906
@end example
 
907
 
 
908
@noindent
 
909
 
 
910
If the @samp{;;} operator is used, no subsequent matches are attempted after
 
911
the first pattern match.
 
912
Using @samp{;&}  in place of @samp{;;} causes execution to continue with
 
913
the @var{command-list} associated with the next clause, if any.
 
914
Using @samp{;;&} in place of @samp{;;} causes the shell to test the patterns
 
915
in the next clause, if any, and execute any associated @var{command-list}
 
916
on a successful match.
 
917
 
 
918
The return status is zero if no @var{pattern} is matched.  Otherwise, the
 
919
return status is the exit status of the @var{command-list} executed.
 
920
 
 
921
@item select
 
922
@rwindex select
 
923
 
 
924
The @code{select} construct allows the easy generation of menus.
 
925
It has almost the same syntax as the @code{for} command:
 
926
 
 
927
@example
 
928
select @var{name} [in @var{words} @dots{}]; do @var{commands}; done
 
929
@end example
 
930
 
 
931
The list of words following @code{in} is expanded, generating a list
 
932
of items.  The set of expanded words is printed on the standard
 
933
error output stream, each preceded by a number.  If the
 
934
@samp{in @var{words}} is omitted, the positional parameters are printed,
 
935
as if @samp{in "$@@"} had been specified.
 
936
The @env{PS3} prompt is then displayed and a line is read from the
 
937
standard input.
 
938
If the line consists of a number corresponding to one of the displayed
 
939
words, then the value of @var{name} is set to that word.
 
940
If the line is empty, the words and prompt are displayed again.
 
941
If @code{EOF} is read, the @code{select} command completes.
 
942
Any other value read causes @var{name} to be set to null.
 
943
The line read is saved in the variable @env{REPLY}.
 
944
 
 
945
The @var{commands} are executed after each selection until a
 
946
@code{break} command is executed, at which
 
947
point the @code{select} command completes.
 
948
 
 
949
Here is an example that allows the user to pick a filename from the
 
950
current directory, and displays the name and index of the file
 
951
selected.
 
952
 
 
953
@example
 
954
select fname in *;
 
955
do
 
956
        echo you picked $fname \($REPLY\)
 
957
        break;
 
958
done
 
959
@end example
 
960
 
 
961
@item ((@dots{}))
 
962
@example
 
963
(( @var{expression} ))
 
964
@end example
 
965
 
 
966
The arithmetic @var{expression} is evaluated according to the rules
 
967
described below (@pxref{Shell Arithmetic}).
 
968
If the value of the expression is non-zero, the return status is 0;
 
969
otherwise the return status is 1.  This is exactly equivalent to
 
970
@example
 
971
let "@var{expression}"
 
972
@end example
 
973
@noindent
 
974
@xref{Bash Builtins}, for a full description of the @code{let} builtin.
 
975
 
 
976
@item [[@dots{}]]
 
977
@rwindex [[
 
978
@rwindex ]]
 
979
@example
 
980
[[ @var{expression} ]]
 
981
@end example
 
982
 
 
983
Return a status of 0 or 1 depending on the evaluation of
 
984
the conditional expression @var{expression}.
 
985
Expressions are composed of the primaries described below in
 
986
@ref{Bash Conditional Expressions}.
 
987
Word splitting and filename expansion are not performed on the words
 
988
between the @code{[[} and @code{]]}; tilde expansion, parameter and
 
989
variable expansion, arithmetic expansion, command substitution, process
 
990
substitution, and quote removal are performed.
 
991
Conditional operators such as @samp{-f} must be unquoted to be recognized
 
992
as primaries.
 
993
 
 
994
When used with @code{[[}, the @samp{<} and @samp{>} operators sort
 
995
lexicographically using the current locale.
 
996
 
 
997
When the @samp{==} and @samp{!=} operators are used, the string to the
 
998
right of the operator is considered a pattern and matched according
 
999
to the rules described below in @ref{Pattern Matching},
 
1000
as if the @code{extglob} shell option were enabled.
 
1001
The @samp{=} operator is identical to @samp{==}.
 
1002
If the shell option @code{nocasematch}
 
1003
(see the description of @code{shopt} in @ref{The Shopt Builtin})
 
1004
is enabled, the match is performed without regard to the case
 
1005
of alphabetic characters.
 
1006
The return value is 0 if the string matches (@samp{==}) or does not
 
1007
match (@samp{!=})the pattern, and 1 otherwise.
 
1008
Any part of the pattern may be quoted to force the quoted portion
 
1009
to be matched as a string.
 
1010
 
 
1011
An additional binary operator, @samp{=~}, is available, with the same
 
1012
precedence as @samp{==} and @samp{!=}.
 
1013
When it is used, the string to the right of the operator is considered
 
1014
an extended regular expression and matched accordingly (as in @i{regex}3)).  
 
1015
The return value is 0 if the string matches
 
1016
the pattern, and 1 otherwise.
 
1017
If the regular expression is syntactically incorrect, the conditional
 
1018
expression's return value is 2.
 
1019
If the shell option @code{nocasematch}
 
1020
(see the description of @code{shopt} in @ref{The Shopt Builtin})
 
1021
is enabled, the match is performed without regard to the case
 
1022
of alphabetic characters.
 
1023
Any part of the pattern may be quoted to force the quoted portion
 
1024
to be matched as a string.
 
1025
Bracket expressions in regular expressions must be treated carefully,
 
1026
since normal quoting characters lose their meanings between brackets.
 
1027
If the pattern is stored in a shell variable, quoting the variable
 
1028
expansion forces the entire pattern to be matched as a string.
 
1029
Substrings matched by parenthesized subexpressions within the regular
 
1030
expression are saved in the array variable @code{BASH_REMATCH}.
 
1031
The element of @code{BASH_REMATCH} with index 0 is the portion of the string
 
1032
matching the entire regular expression.
 
1033
The element of @code{BASH_REMATCH} with index @var{n} is the portion of the
 
1034
string matching the @var{n}th parenthesized subexpression.
 
1035
 
 
1036
For example, the following will match a line
 
1037
(stored in the shell variable @var{line})
 
1038
if there is a sequence of characters in the value consisting of
 
1039
any number, including zero, of 
 
1040
space characters, zero or one instances of @samp{a}, then a @samp{b}:
 
1041
@example
 
1042
[[ $line =~ [[:space:]]*(a)?b ]]
 
1043
@end example
 
1044
 
 
1045
@noindent
 
1046
That means values like @samp{aab} and @samp{  aaaaaab} will match, as
 
1047
will a line containing a @samp{b} anywhere in its value.
 
1048
 
 
1049
Storing the regular expression in a shell variable is often a useful
 
1050
way to avoid problems with quoting characters that are special to the
 
1051
shell.
 
1052
It is sometimes difficult to specify a regular expression literally
 
1053
without using quotes, or to keep track of the quoting used by regular
 
1054
expressions while paying attention to the shell's quote removal.
 
1055
Using a shell variable to store the pattern decreases these problems.
 
1056
For example, the following is equivalent to the above:
 
1057
@example
 
1058
pattern='[[:space:]]*(a)?b'
 
1059
[[ $line =~ $pattern ]]
 
1060
@end example
 
1061
 
 
1062
@noindent
 
1063
If you want to match a character that's special to the regular expression
 
1064
grammar, it has to be quoted to remove its special meaning.
 
1065
This means that in the pattern @samp{xxx.txt}, the @samp{.} matches any
 
1066
character in the string (its usual regular expression meaning), but in the
 
1067
pattern @samp{"xxx.txt"} it can only match a literal @samp{.}.
 
1068
Shell programmers should take special care with backslashes, since backslashes
 
1069
are used both by the shell and regular expressions to remove the special
 
1070
meaning from the following character.
 
1071
The following two sets of commands are @emph{not} equivalent:
 
1072
@example
 
1073
pattern='\.'
 
1074
 
 
1075
[[ . =~ $pattern ]]
 
1076
[[ . =~ \. ]]
 
1077
 
 
1078
[[ . =~ "$pattern" ]]
 
1079
[[ . =~ '\.' ]]
 
1080
@end example
 
1081
 
 
1082
@noindent
 
1083
The first two matches will succeed, but the second two will not, because
 
1084
in the second two the backslash will be part of the pattern to be matched.
 
1085
In the first two examples, the backslash removes the special meaning from
 
1086
@samp{.}, so the literal @samp{.} matches.
 
1087
If the string in the first examples were anything other than @samp{.}, say
 
1088
@samp{a}, the pattern would not match, because the quoted @samp{.} in the
 
1089
pattern loses its special meaning of matching any single character.
 
1090
 
 
1091
Expressions may be combined using the following operators, listed
 
1092
in decreasing order of precedence:
 
1093
 
 
1094
@table @code
 
1095
@item ( @var{expression} )
 
1096
Returns the value of @var{expression}.
 
1097
This may be used to override the normal precedence of operators.
 
1098
 
 
1099
@item ! @var{expression}
 
1100
True if @var{expression} is false.
 
1101
 
 
1102
@item @var{expression1} && @var{expression2}
 
1103
True if both @var{expression1} and @var{expression2} are true.
 
1104
 
 
1105
@item @var{expression1} || @var{expression2}
 
1106
True if either @var{expression1} or @var{expression2} is true.
 
1107
@end table
 
1108
 
 
1109
@noindent
 
1110
The @code{&&} and @code{||} operators do not evaluate @var{expression2} if the
 
1111
value of @var{expression1} is sufficient to determine the return
 
1112
value of the entire conditional expression.
 
1113
@end table
 
1114
 
 
1115
@node Command Grouping
 
1116
@subsubsection Grouping Commands
 
1117
@cindex commands, grouping
 
1118
 
 
1119
Bash provides two ways to group a list of commands to be executed
 
1120
as a unit.  When commands are grouped, redirections may be applied
 
1121
to the entire command list.  For example, the output of all the
 
1122
commands in the list may be redirected to a single stream.
 
1123
 
 
1124
@table @code
 
1125
@item ()
 
1126
@example
 
1127
( @var{list} )
 
1128
@end example
 
1129
 
 
1130
Placing a list of commands between parentheses causes a subshell
 
1131
environment to be created (@pxref{Command Execution Environment}), and each
 
1132
of the commands in @var{list} to be executed in that subshell.  Since the
 
1133
@var{list} is executed in a subshell, variable assignments do not remain in
 
1134
effect after the subshell completes. 
 
1135
 
 
1136
@item @{@}
 
1137
@rwindex @{
 
1138
@rwindex @}
 
1139
@example
 
1140
@{ @var{list}; @}
 
1141
@end example
 
1142
 
 
1143
Placing a list of commands between curly braces causes the list to
 
1144
be executed in the current shell context.  No subshell is created.
 
1145
The semicolon (or newline) following @var{list} is required.
 
1146
@end table
 
1147
 
 
1148
In addition to the creation of a subshell, there is a subtle difference
 
1149
between these two constructs due to historical reasons.  The braces
 
1150
are @code{reserved words}, so they must be separated from the @var{list}
 
1151
by @code{blank}s or other shell metacharacters.
 
1152
The parentheses are @code{operators}, and are
 
1153
recognized as separate tokens by the shell even if they are not separated
 
1154
from the @var{list} by whitespace.
 
1155
 
 
1156
The exit status of both of these constructs is the exit status of
 
1157
@var{list}.
 
1158
 
 
1159
@node Coprocesses
 
1160
@subsection Coprocesses
 
1161
@cindex coprocess
 
1162
 
 
1163
A @code{coprocess} is a shell command preceded by the @code{coproc}
 
1164
reserved word.
 
1165
A coprocess is executed asynchronously in a subshell, as if the command
 
1166
had been terminated with the @samp{&} control operator, with a two-way pipe
 
1167
established between the executing shell and the coprocess.
 
1168
 
 
1169
The format for a coprocess is:
 
1170
@example
 
1171
coproc [@var{NAME}] @var{command} [@var{redirections}]
 
1172
@end example
 
1173
 
 
1174
@noindent
 
1175
This creates a coprocess named @var{NAME}.
 
1176
If @var{NAME} is not supplied, the default name is @var{COPROC}.
 
1177
@var{NAME} must not be supplied if @var{command} is a simple
 
1178
command (@pxref{Simple Commands}); otherwise, it is interpreted as
 
1179
the first word of the simple command.
 
1180
 
 
1181
When the coprocess is executed, the shell creates an array variable
 
1182
(@pxref{Arrays})
 
1183
named @env{NAME} in the context of the executing shell.
 
1184
The standard output of @var{command}
 
1185
is connected via a pipe to a file descriptor in the executing shell,
 
1186
and that file descriptor is assigned to @env{NAME}[0].
 
1187
The standard input of @var{command}
 
1188
is connected via a pipe to a file descriptor in the executing shell,
 
1189
and that file descriptor is assigned to @env{NAME}[1].
 
1190
This pipe is established before any redirections specified by the
 
1191
command (@pxref{Redirections}).
 
1192
The file descriptors can be utilized as arguments to shell commands
 
1193
and redirections using standard word expansions.
 
1194
The file descriptors are not available in subshells.
 
1195
 
 
1196
The process ID of the shell spawned to execute the coprocess is
 
1197
available as the value of the variable @env{NAME}_PID.
 
1198
The @code{wait}
 
1199
builtin command may be used to wait for the coprocess to terminate.
 
1200
 
 
1201
Since the coprocess is created as an asynchronous command,
 
1202
the @code{coproc} command always returns success.
 
1203
The return status of a coprocess is the exit status of @var{command}.
 
1204
 
 
1205
@node GNU Parallel
 
1206
@subsection GNU Parallel
 
1207
 
 
1208
There are ways to run commands in parallel that are not built into Bash.
 
1209
GNU Parallel is a tool to do just that.
 
1210
 
 
1211
GNU Parallel, as its name suggests, can be used to build and run commands
 
1212
in parallel.  You may run the same command with different arguments, whether
 
1213
they are filenames, usernames, hostnames, or lines read from files.  GNU
 
1214
Parallel provides shorthand references to many of the most common operations
 
1215
(input lines, various portions of the input line, different ways to specify
 
1216
the input source, and so on).  Parallel can replace @code{xargs} or feed
 
1217
commands from its input sources to several different instances of Bash.
 
1218
 
 
1219
For a complete description, refer to the GNU Parallel documentation.  A few
 
1220
examples should provide a brief introduction to its use.
 
1221
 
 
1222
For example, it is easy to replace @code{xargs} to gzip all html files in the
 
1223
current directory and its subdirectories:
 
1224
@example
 
1225
find . -type f -name '*.html' -print | parallel gzip
 
1226
@end example
 
1227
@noindent
 
1228
If you need to protect special characters such as newlines in file names,
 
1229
use find's @option{-print0} option and parallel's @option{-0} option.
 
1230
 
 
1231
You can use Parallel to move files from the current directory when the
 
1232
number of files is too large to process with one @code{mv} invocation:
 
1233
@example
 
1234
ls | parallel mv @{@} destdir
 
1235
@end example
 
1236
 
 
1237
As you can see, the @{@} is replaced with each line read from standard input.
 
1238
While using @code{ls} will work in most instances, it is not sufficient to
 
1239
deal with all filenames.
 
1240
If you need to accommodate special characters in filenames, you can use
 
1241
 
 
1242
@example
 
1243
find . -depth 1 \! -name '.*' -print0 | parallel -0 mv @{@} destdir
 
1244
@end example
 
1245
 
 
1246
@noindent
 
1247
as alluded to above.
 
1248
 
 
1249
This will run as many @code{mv} commands as there are files in the current
 
1250
directory.
 
1251
You can emulate a parallel @code{xargs} by adding the @option{-X} option:
 
1252
@example
 
1253
find . -depth 1 \! -name '.*' -print0 | parallel -0 -X mv @{@} destdir
 
1254
@end example
 
1255
 
 
1256
GNU Parallel can replace certain common idioms that operate on lines read
 
1257
from a file (in this case, filenames listed one per line):
 
1258
@example
 
1259
        while IFS= read -r x; do
 
1260
                do-something1 "$x" "config-$x"
 
1261
                do-something2 < "$x"
 
1262
        done < file | process-output
 
1263
@end example
 
1264
 
 
1265
@noindent
 
1266
with a more compact syntax reminiscent of lambdas:
 
1267
@example
 
1268
cat list | parallel "do-something1 @{@} config-@{@} ; do-something2 < @{@}" | process-output
 
1269
@end example
 
1270
 
 
1271
Parallel provides a built-in mechanism to remove filename extensions, which
 
1272
lends itself to batch file transformations or renaming:
 
1273
@example
 
1274
ls *.gz | parallel -j+0 "zcat @{@} | bzip2 >@{.@}.bz2 && rm @{@}"
 
1275
@end example
 
1276
@noindent
 
1277
This will recompress all files in the current directory with names ending
 
1278
in .gz using bzip2, running one job per CPU (-j+0) in parallel.
 
1279
(We use @code{ls} for brevity here; using @code{find} as above is more
 
1280
robust in the face of filenames containing unexpected characters.)
 
1281
Parallel can take arguments from the command line; the above can also be
 
1282
written as
 
1283
 
 
1284
@example
 
1285
parallel "zcat @{@} | bzip2 >@{.@}.bz2 && rm @{@}" ::: *.gz
 
1286
@end example
 
1287
 
 
1288
If a command generates output, you may want to preserve the input order in
 
1289
the output.  For instance, the following command
 
1290
@example
 
1291
@{ echo foss.org.my ; echo debian.org; echo freenetproject.org; @} | parallel traceroute
 
1292
@end example
 
1293
@noindent
 
1294
will display as output the traceroute invocation that finishes first.
 
1295
Adding the @option{-k} option 
 
1296
@example
 
1297
@{ echo foss.org.my ; echo debian.org; echo freenetproject.org; @} | parallel -k traceroute
 
1298
@end example
 
1299
@noindent
 
1300
will ensure that the output of @code{traceroute foss.org.my} is displayed first.
 
1301
 
 
1302
Finally, Parallel can be used to run a sequence of shell commands in parallel,
 
1303
similar to @samp{cat file | bash}.
 
1304
It is not uncommon to take a list of filenames, create a series of shell
 
1305
commands to operate on them, and feed that list of commnds to a shell.
 
1306
Parallel can speed this up.  Assuming that @file{file} contains a list of
 
1307
shell commands, one per line,
 
1308
 
 
1309
@example
 
1310
parallel -j 10 < file
 
1311
@end example
 
1312
 
 
1313
@noindent
 
1314
will evaluate the commands using the shell (since no explicit command is
 
1315
supplied as an argument), in blocks of ten shell jobs at a time.
 
1316
 
 
1317
@node Shell Functions
 
1318
@section Shell Functions
 
1319
@cindex shell function
 
1320
@cindex functions, shell
 
1321
 
 
1322
Shell functions are a way to group commands for later execution
 
1323
using a single name for the group.  They are executed just like
 
1324
a "regular" command.
 
1325
When the name of a shell function is used as a simple command name,
 
1326
the list of commands associated with that function name is executed.
 
1327
Shell functions are executed in the current
 
1328
shell context; no new process is created to interpret them.
 
1329
 
 
1330
Functions are declared using this syntax:
 
1331
@rwindex function
 
1332
@example
 
1333
@var{name} () @var{compound-command} [ @var{redirections} ]
 
1334
@end example
 
1335
 
 
1336
or
 
1337
 
 
1338
@example
 
1339
function @var{name} [()] @var{compound-command} [ @var{redirections} ]
 
1340
@end example
 
1341
 
 
1342
This defines a shell function named @var{name}.  The reserved
 
1343
word @code{function} is optional.
 
1344
If the @code{function} reserved
 
1345
word is supplied, the parentheses are optional.
 
1346
The @var{body} of the function is the compound command
 
1347
@var{compound-command} (@pxref{Compound Commands}).
 
1348
That command is usually a @var{list} enclosed between @{ and @}, but
 
1349
may be any compound command listed above.
 
1350
@var{compound-command} is executed whenever @var{name} is specified as the
 
1351
name of a command.
 
1352
When the shell is in @sc{posix} mode (@pxref{Bash POSIX Mode}),
 
1353
@var{name} may not be the same as one of the special builtins
 
1354
(@pxref{Special Builtins}).
 
1355
Any redirections (@pxref{Redirections}) associated with the shell function
 
1356
are performed when the function is executed.
 
1357
 
 
1358
A function definition may be deleted using the @option{-f} option to the
 
1359
@code{unset} builtin (@pxref{Bourne Shell Builtins}).
 
1360
 
 
1361
The exit status of a function definition is zero unless a syntax error
 
1362
occurs or a readonly function with the same name already exists.
 
1363
When executed, the exit status of a function is the exit status of the
 
1364
last command executed in the body.
 
1365
 
 
1366
Note that for historical reasons, in the most common usage the curly braces
 
1367
that surround the body of the function must be separated from the body by
 
1368
@code{blank}s or newlines.
 
1369
This is because the braces are reserved words and are only recognized
 
1370
as such when they are separated from the command list
 
1371
by whitespace or another shell metacharacter.
 
1372
Also, when using the braces, the @var{list} must be terminated by a semicolon,
 
1373
a @samp{&}, or a newline.
 
1374
 
 
1375
When a function is executed, the arguments to the
 
1376
function become the positional parameters
 
1377
during its execution (@pxref{Positional Parameters}).
 
1378
The special parameter @samp{#} that expands to the number of
 
1379
positional parameters is updated to reflect the change.
 
1380
Special parameter @code{0} is unchanged.
 
1381
The first element of the @env{FUNCNAME} variable is set to the
 
1382
name of the function while the function is executing.
 
1383
 
 
1384
All other aspects of the shell execution
 
1385
environment are identical between a function and its caller
 
1386
with these exceptions:
 
1387
the @env{DEBUG} and @env{RETURN} traps
 
1388
are not inherited unless the function has been given the
 
1389
@code{trace} attribute using the @code{declare} builtin or
 
1390
the @code{-o functrace} option has been enabled with
 
1391
the @code{set} builtin,
 
1392
(in which case all functions inherit the @env{DEBUG} and @env{RETURN} traps),
 
1393
and the @env{ERR} trap is not inherited unless the @code{-o errtrace}
 
1394
shell option has been enabled.
 
1395
@xref{Bourne Shell Builtins}, for the description of the
 
1396
@code{trap} builtin.
 
1397
 
 
1398
The @env{FUNCNEST} variable, if set to a numeric value greater
 
1399
than 0, defines a maximum function nesting level.  Function
 
1400
invocations that exceed the limit cause the entire command to
 
1401
abort.
 
1402
 
 
1403
If the builtin command @code{return}
 
1404
is executed in a function, the function completes and
 
1405
execution resumes with the next command after the function
 
1406
call.
 
1407
Any command associated with the @code{RETURN} trap is executed
 
1408
before execution resumes.
 
1409
When a function completes, the values of the
 
1410
positional parameters and the special parameter @samp{#}
 
1411
are restored to the values they had prior to the function's
 
1412
execution.  If a numeric argument is given to @code{return},
 
1413
that is the function's return status; otherwise the function's
 
1414
return status is the exit status of the last command executed
 
1415
before the @code{return}.
 
1416
 
 
1417
Variables local to the function may be declared with the
 
1418
@code{local} builtin.  These variables are visible only to
 
1419
the function and the commands it invokes.
 
1420
 
 
1421
Function names and definitions may be listed with the
 
1422
@option{-f} option to the @code{declare} (@code{typeset})
 
1423
builtin command (@pxref{Bash Builtins}).
 
1424
The @option{-F} option to @code{declare} or @code{typeset}
 
1425
will list the function names only
 
1426
(and optionally the source file and line number, if the @code{extdebug}
 
1427
shell option is enabled).
 
1428
Functions may be exported so that subshells
 
1429
automatically have them defined with the
 
1430
@option{-f} option to the @code{export} builtin
 
1431
(@pxref{Bourne Shell Builtins}).
 
1432
Note that shell functions and variables with the same name may result
 
1433
in multiple identically-named entries in the environment passed to the
 
1434
shell's children.
 
1435
Care should be taken in cases where this may cause a problem.
 
1436
 
 
1437
Functions may be recursive.
 
1438
The @code{FUNCNEST} variable may be used to limit the depth of the
 
1439
function call stack and restrict the number of function invocations.
 
1440
By default, no limit is placed on the number of recursive  calls.
 
1441
 
 
1442
@node Shell Parameters
 
1443
@section Shell Parameters
 
1444
@cindex parameters
 
1445
@cindex variable, shell
 
1446
@cindex shell variable
 
1447
 
 
1448
@menu
 
1449
* Positional Parameters::       The shell's command-line arguments.
 
1450
* Special Parameters::          Parameters denoted by special characters.
 
1451
@end menu
 
1452
 
 
1453
A @var{parameter} is an entity that stores values.
 
1454
It can be a @code{name}, a number, or one of the special characters
 
1455
listed below.
 
1456
A @var{variable} is a parameter denoted by a @code{name}.
 
1457
A variable has a @var{value} and zero or more @var{attributes}.
 
1458
Attributes are assigned using the @code{declare} builtin command
 
1459
(see the description of the @code{declare} builtin in @ref{Bash Builtins}).
 
1460
 
 
1461
A parameter is set if it has been assigned a value.  The null string is
 
1462
a valid value.  Once a variable is set, it may be unset only by using
 
1463
the @code{unset} builtin command.
 
1464
 
 
1465
A variable may be assigned to by a statement of the form
 
1466
@example
 
1467
@var{name}=[@var{value}]
 
1468
@end example
 
1469
@noindent
 
1470
If @var{value}
 
1471
is not given, the variable is assigned the null string.  All
 
1472
@var{value}s undergo tilde expansion, parameter and variable expansion,
 
1473
command substitution, arithmetic expansion, and quote
 
1474
removal (detailed below).  If the variable has its @code{integer}
 
1475
attribute set, then @var{value} 
 
1476
is evaluated as an arithmetic expression even if the @code{$((@dots{}))}
 
1477
expansion is not used (@pxref{Arithmetic Expansion}).
 
1478
Word splitting is not performed, with the exception
 
1479
of @code{"$@@"} as explained below.
 
1480
Filename expansion is not performed.
 
1481
Assignment statements may also appear as arguments to the
 
1482
@code{alias}, 
 
1483
@code{declare}, @code{typeset}, @code{export}, @code{readonly},
 
1484
and @code{local} builtin commands.
 
1485
When in @sc{posix} mode (@pxref{Bash POSIX Mode}), these builtins may appear
 
1486
in a command after one or more instances of the @code{command} builtin
 
1487
and retain these assignment statement properties.
 
1488
 
 
1489
In the context where an assignment statement is assigning a value  
 
1490
to a shell variable or array index (@pxref{Arrays}), the @samp{+=}
 
1491
operator can be used to   
 
1492
append to or add to the variable's previous value.
 
1493
When @samp{+=} is applied to a variable for which the @var{integer} attribute
 
1494
has been set, @var{value} is evaluated as an arithmetic expression and
 
1495
added to the variable's current value, which is also evaluated.
 
1496
When @samp{+=} is applied to an array variable using compound assignment
 
1497
(@pxref{Arrays}), the
 
1498
variable's value is not unset (as it is when using @samp{=}), and new
 
1499
values are appended to the array beginning at one greater than the array's
 
1500
maximum index (for indexed arrays),  or added as additional key-value pairs
 
1501
in an associative array.
 
1502
When applied to a string-valued variable, @var{value} is expanded and
 
1503
appended to the variable's value.
 
1504
 
 
1505
A variable can be assigned the @var{nameref} attribute using the
 
1506
@option{-n} option to the \fBdeclare\fP or \fBlocal\fP builtin commands
 
1507
(@pxref{Bash Builtins})
 
1508
to create a @var{nameref}, or a reference to another variable.
 
1509
This allows variables to be manipulated indirectly.
 
1510
Whenever the nameref variable is referenced or assigned to, the operation
 
1511
is actually performed on the variable specified by the nameref variable's
 
1512
value.
 
1513
A nameref is commonly used within shell functions to refer to a variable
 
1514
whose name is passed as an argument to the function.
 
1515
For instance, if a variable name is passed to a shell function as its first
 
1516
argument, running
 
1517
@example
 
1518
declare -n ref=$1
 
1519
@end example
 
1520
@noindent
 
1521
inside the function creates a nameref variable @var{ref} whose value is
 
1522
the variable name passed as the first argument.
 
1523
References and assignments to @var{ref} are treated as references and
 
1524
assignments to the variable whose name was passed as @code{$1}.
 
1525
 
 
1526
If the control variable in a @code{for} loop has the nameref attribute,
 
1527
the list of words can be a list of shell variables, and a name reference
 
1528
will be established for each word in the list, in turn, when the loop is
 
1529
executed.
 
1530
Array variables cannot be given the @option{-n} attribute.
 
1531
However, nameref variables can reference array variables and subscripted
 
1532
array variables.
 
1533
Namerefs can be unset using the @option{-n} option to the @code{unset} builtin
 
1534
(@pxref{Bourne Shell Builtins}).
 
1535
Otherwise, if @code{unset} is executed with the name of a nameref variable
 
1536
as an argument, the variable referenced by the nameref variable will be unset.
 
1537
 
 
1538
@node Positional Parameters
 
1539
@subsection Positional Parameters
 
1540
@cindex parameters, positional
 
1541
 
 
1542
A @var{positional parameter} is a parameter denoted by one or more
 
1543
digits, other than the single digit @code{0}.  Positional parameters are
 
1544
assigned from the shell's arguments when it is invoked,
 
1545
and may be reassigned using the @code{set} builtin command.
 
1546
Positional parameter @code{N} may be referenced as @code{$@{N@}}, or
 
1547
as @code{$N} when @code{N} consists of a single digit.
 
1548
Positional parameters may not be assigned to with assignment statements.
 
1549
The @code{set} and @code{shift} builtins are used to set and
 
1550
unset them (@pxref{Shell Builtin Commands}).
 
1551
The positional parameters are
 
1552
temporarily replaced when a shell function is executed
 
1553
(@pxref{Shell Functions}).
 
1554
 
 
1555
When a positional parameter consisting of more than a single
 
1556
digit is expanded, it must be enclosed in braces.
 
1557
 
 
1558
@node Special Parameters
 
1559
@subsection Special Parameters
 
1560
@cindex parameters, special
 
1561
 
 
1562
The shell treats several parameters specially.  These parameters may
 
1563
only be referenced; assignment to them is not allowed.
 
1564
 
 
1565
@vtable @code
 
1566
 
 
1567
@item *
 
1568
@vindex $*
 
1569
($*) Expands to the positional parameters, starting from one.
 
1570
When the expansion is not within double quotes, each positional parameter
 
1571
expands to a separate word.
 
1572
In contexts where it is performed, those words
 
1573
are subject to further word splitting and pathname expansion.
 
1574
When the expansion occurs within double quotes, it expands to a single word
 
1575
with the value of each parameter separated by the first character
 
1576
of the @env{IFS}
 
1577
special variable.  That is, @code{"$*"} is equivalent
 
1578
to @code{"$1@var{c}$2@var{c}@dots{}"}, where @var{c}
 
1579
is the first character of the value of the @code{IFS}
 
1580
variable.
 
1581
If @env{IFS} is unset, the parameters are separated by spaces.
 
1582
If @env{IFS} is null, the parameters are joined without intervening
 
1583
separators.
 
1584
 
 
1585
@item @@
 
1586
@vindex $@@
 
1587
($@@) Expands to the positional parameters, starting from one.  When the
 
1588
expansion occurs within double quotes, each parameter expands to a
 
1589
separate word.  That is, @code{"$@@"} is equivalent to
 
1590
@code{"$1" "$2" @dots{}}.
 
1591
If the double-quoted expansion occurs within a word, the expansion of
 
1592
the first parameter is joined with the beginning part of the original
 
1593
word, and the expansion of the last parameter is joined with the last
 
1594
part of the original word.
 
1595
When there are no positional parameters, @code{"$@@"} and
 
1596
@code{$@@}
 
1597
expand to nothing (i.e., they are removed).
 
1598
 
 
1599
@item #
 
1600
@vindex $#
 
1601
($#) Expands to the number of positional parameters in decimal.
 
1602
 
 
1603
@item ?
 
1604
@vindex $?
 
1605
($?) Expands to the exit status of the most recently executed foreground
 
1606
pipeline.
 
1607
 
 
1608
@item -
 
1609
@vindex $-
 
1610
($-, a hyphen.)  Expands to the current option flags as specified upon
 
1611
invocation, by the @code{set}
 
1612
builtin command, or those set by the shell itself
 
1613
(such as the @option{-i} option).
 
1614
 
 
1615
@item $
 
1616
@vindex $$
 
1617
($$) Expands to the process @sc{id} of the shell.  In a @code{()} subshell, it
 
1618
expands to the process @sc{id} of the invoking shell, not the subshell.
 
1619
 
 
1620
@item !
 
1621
@vindex $!
 
1622
($!) Expands to the process @sc{id} of the job most recently placed into the
 
1623
background, whether executed as an asynchronous command or using
 
1624
the @code{bg} builtin (@pxref{Job Control Builtins}).
 
1625
 
 
1626
@item 0
 
1627
@vindex $0
 
1628
($0) Expands to the name of the shell or shell script.  This is set at
 
1629
shell initialization.  If Bash is invoked with a file of commands
 
1630
(@pxref{Shell Scripts}), @code{$0} is set to the name of that file.
 
1631
If Bash is started with the @option{-c} option (@pxref{Invoking Bash}),
 
1632
then @code{$0} is set to the first argument after the string to be
 
1633
executed, if one is present.  Otherwise, it is set
 
1634
to the filename used to invoke Bash, as given by argument zero.
 
1635
 
 
1636
@item _
 
1637
@vindex $_
 
1638
($_, an underscore.)
 
1639
At shell startup, set to the absolute pathname used to invoke the
 
1640
shell or shell script being executed as passed in the environment
 
1641
or argument list.
 
1642
Subsequently, expands to the last argument to the previous command,
 
1643
after expansion.   
 
1644
Also set to the full pathname used to invoke each command executed
 
1645
and placed in the environment exported to that command.
 
1646
When checking mail, this parameter holds the name of the mail file.
 
1647
@end vtable
 
1648
 
 
1649
@node Shell Expansions
 
1650
@section Shell Expansions
 
1651
@cindex expansion
 
1652
 
 
1653
Expansion is performed on the command line after it has been split into
 
1654
@code{token}s.  There are seven kinds of expansion performed:
 
1655
 
 
1656
@itemize @bullet
 
1657
@item brace expansion
 
1658
@item tilde expansion
 
1659
@item parameter and variable expansion
 
1660
@item command substitution
 
1661
@item arithmetic expansion
 
1662
@item word splitting
 
1663
@item filename expansion
 
1664
@end itemize
 
1665
 
 
1666
@menu
 
1667
* Brace Expansion::             Expansion of expressions within braces.
 
1668
* Tilde Expansion::             Expansion of the ~ character.
 
1669
* Shell Parameter Expansion::   How Bash expands variables to their values.
 
1670
* Command Substitution::        Using the output of a command as an argument.
 
1671
* Arithmetic Expansion::        How to use arithmetic in shell expansions.
 
1672
* Process Substitution::        A way to write and read to and from a
 
1673
                                command.
 
1674
* Word Splitting::      How the results of expansion are split into separate
 
1675
                        arguments.
 
1676
* Filename Expansion::  A shorthand for specifying filenames matching patterns.
 
1677
* Quote Removal::       How and when quote characters are removed from
 
1678
                        words.
 
1679
@end menu
 
1680
 
 
1681
The order of expansions is:
 
1682
brace expansion;
 
1683
tilde expansion, parameter and variable expansion, arithmetic expansion,
 
1684
and command substitution (done in a left-to-right fashion);
 
1685
word splitting;
 
1686
and filename expansion.
 
1687
 
 
1688
On systems that can support it, there is an additional expansion
 
1689
available: @var{process substitution}.
 
1690
This is performed at the
 
1691
same time as tilde, parameter, variable, and arithmetic expansion and
 
1692
command substitution.
 
1693
 
 
1694
Only brace expansion, word splitting, and filename expansion
 
1695
can change the number of words of the expansion; other expansions
 
1696
expand a single word to a single word.
 
1697
The only exceptions to this are the expansions of
 
1698
@code{"$@@"} (@pxref{Special Parameters}) and @code{"$@{@var{name}[@@]@}"}
 
1699
(@pxref{Arrays}).
 
1700
 
 
1701
After all expansions, @code{quote removal} (@pxref{Quote Removal})
 
1702
is performed.
 
1703
 
 
1704
@node Brace Expansion
 
1705
@subsection Brace Expansion
 
1706
@cindex brace expansion
 
1707
@cindex expansion, brace
 
1708
 
 
1709
Brace expansion is a mechanism by which arbitrary strings may be generated.
 
1710
This mechanism is similar to
 
1711
@var{filename expansion} (@pxref{Filename Expansion}),
 
1712
but the filenames generated need not exist.
 
1713
Patterns to be brace expanded take the form of an optional @var{preamble},
 
1714
followed by either a series of comma-separated strings or a sequence expression
 
1715
between a pair of braces,
 
1716
followed by an optional @var{postscript}.
 
1717
The preamble is prefixed to each string contained within the braces, and
 
1718
the postscript is then appended to each resulting string, expanding left
 
1719
to right.
 
1720
 
 
1721
Brace expansions may be nested.
 
1722
The results of each expanded string are not sorted; left to right order
 
1723
is preserved.
 
1724
For example,
 
1725
@example
 
1726
bash$ echo a@{d,c,b@}e
 
1727
ade ace abe
 
1728
@end example
 
1729
 
 
1730
A sequence expression takes the form @code{@{@var{x}..@var{y}[..@var{incr}]@}},
 
1731
where @var{x} and @var{y} are either integers or single characters,
 
1732
and @var{incr}, an optional increment, is an integer.
 
1733
When integers are supplied, the expression expands to each number between
 
1734
@var{x} and @var{y}, inclusive.
 
1735
Supplied integers may be prefixed with @samp{0} to force each term to have the
 
1736
same width.
 
1737
When either @var{x} or @var{y} begins with a zero, the shell
 
1738
attempts to force all generated terms to contain the same number of digits,
 
1739
zero-padding where necessary.
 
1740
When characters are supplied, the expression expands to each character
 
1741
lexicographically between @var{x} and @var{y}, inclusive,
 
1742
using the default C locale.
 
1743
Note that both @var{x} and @var{y} must be of the same type.
 
1744
When the increment is supplied, it is used as the difference between
 
1745
each term.  The default increment is 1 or -1 as appropriate.
 
1746
 
 
1747
Brace expansion is performed before any other expansions,
 
1748
and any characters special to other expansions are preserved
 
1749
in the result.  It is strictly textual.  Bash
 
1750
does not apply any syntactic interpretation to the context of the
 
1751
expansion or the text between the braces.
 
1752
To avoid conflicts with parameter expansion, the string @samp{$@{}
 
1753
is not considered eligible for brace expansion.
 
1754
 
 
1755
A correctly-formed brace expansion must contain unquoted opening
 
1756
and closing braces, and at least one unquoted comma or a valid
 
1757
sequence expression.
 
1758
Any incorrectly formed brace expansion is left unchanged.
 
1759
 
 
1760
A @{ or @samp{,} may be quoted with a backslash to prevent its
 
1761
being considered part of a brace expression.
 
1762
To avoid conflicts with parameter expansion, the string @samp{$@{}
 
1763
is not considered eligible for brace expansion.
 
1764
 
 
1765
This construct is typically used as shorthand when the common
 
1766
prefix of the strings to be generated is longer than in the
 
1767
above example:
 
1768
@example
 
1769
mkdir /usr/local/src/bash/@{old,new,dist,bugs@}
 
1770
@end example
 
1771
or
 
1772
@example
 
1773
chown root /usr/@{ucb/@{ex,edit@},lib/@{ex?.?*,how_ex@}@}
 
1774
@end example
 
1775
 
 
1776
@node Tilde Expansion
 
1777
@subsection Tilde Expansion
 
1778
@cindex tilde expansion
 
1779
@cindex expansion, tilde
 
1780
 
 
1781
If a word begins with an unquoted tilde character (@samp{~}), all of the
 
1782
characters up to the first unquoted slash (or all characters,
 
1783
if there is no unquoted slash) are considered a @var{tilde-prefix}.
 
1784
If none of the characters in the tilde-prefix are quoted, the
 
1785
characters in the tilde-prefix following the tilde are treated as a
 
1786
possible @var{login name}.
 
1787
If this login name is the null string, the tilde is replaced with the
 
1788
value of the @env{HOME} shell variable.
 
1789
If @env{HOME} is unset, the home directory of the user executing the
 
1790
shell is substituted instead.
 
1791
Otherwise, the tilde-prefix is replaced with the home directory
 
1792
associated with the specified login name.
 
1793
 
 
1794
If the tilde-prefix is @samp{~+}, the value of
 
1795
the shell variable @env{PWD} replaces the tilde-prefix.
 
1796
If the tilde-prefix is @samp{~-}, the value of the shell variable
 
1797
@env{OLDPWD}, if it is set, is substituted.
 
1798
 
 
1799
If the characters following the tilde in the tilde-prefix consist of a
 
1800
number @var{N}, optionally prefixed by a @samp{+} or a @samp{-},
 
1801
the tilde-prefix is replaced with the
 
1802
corresponding element from the directory stack, as it would be displayed
 
1803
by the @code{dirs} builtin invoked with the characters following tilde
 
1804
in the tilde-prefix as an argument (@pxref{The Directory Stack}).
 
1805
If the tilde-prefix, sans the tilde, consists of a number without a
 
1806
leading @samp{+} or @samp{-}, @samp{+} is assumed.
 
1807
 
 
1808
If the login name is invalid, or the tilde expansion fails, the word is
 
1809
left unchanged.
 
1810
 
 
1811
Each variable assignment is checked for unquoted tilde-prefixes immediately
 
1812
following a @samp{:} or the first @samp{=}.
 
1813
In these cases, tilde expansion is also performed.
 
1814
Consequently, one may use filenames with tildes in assignments to
 
1815
@env{PATH}, @env{MAILPATH}, and @env{CDPATH},
 
1816
and the shell assigns the expanded value.
 
1817
 
 
1818
The following table shows how Bash treats unquoted tilde-prefixes:
 
1819
 
 
1820
@table @code
 
1821
@item ~
 
1822
The value of @code{$HOME}
 
1823
@item ~/foo
 
1824
@file{$HOME/foo}
 
1825
 
 
1826
@item ~fred/foo
 
1827
The subdirectory @code{foo} of the home directory of the user
 
1828
@code{fred}
 
1829
 
 
1830
@item ~+/foo
 
1831
@file{$PWD/foo}
 
1832
 
 
1833
@item ~-/foo
 
1834
@file{$@{OLDPWD-'~-'@}/foo}
 
1835
 
 
1836
@item ~@var{N}
 
1837
The string that would be displayed by @samp{dirs +@var{N}}
 
1838
 
 
1839
@item ~+@var{N}
 
1840
The string that would be displayed by @samp{dirs +@var{N}}
 
1841
 
 
1842
@item ~-@var{N}
 
1843
The string that would be displayed by @samp{dirs -@var{N}}
 
1844
@end table
 
1845
 
 
1846
@node Shell Parameter Expansion
 
1847
@subsection Shell Parameter Expansion
 
1848
@cindex parameter expansion
 
1849
@cindex expansion, parameter
 
1850
 
 
1851
The @samp{$} character introduces parameter expansion,
 
1852
command substitution, or arithmetic expansion.  The parameter name
 
1853
or symbol to be expanded may be enclosed in braces, which
 
1854
are optional but serve to protect the variable to be expanded from
 
1855
characters immediately following it which could be
 
1856
interpreted as part of the name.
 
1857
 
 
1858
When braces are used, the matching ending brace is the first @samp{@}}
 
1859
not escaped by a backslash or within a quoted string, and not within an
 
1860
embedded arithmetic expansion, command substitution, or parameter
 
1861
expansion.
 
1862
 
 
1863
The basic form of parameter expansion is $@{@var{parameter}@}.
 
1864
The value of @var{parameter} is substituted.
 
1865
The @var{parameter} is a shell parameter as described above
 
1866
(@pxref{Shell Parameters}) or an array reference (@pxref{Arrays}).
 
1867
The braces are required when @var{parameter}
 
1868
is a positional parameter with more than one digit,
 
1869
or when @var{parameter} is followed by a character that is not to be
 
1870
interpreted as part of its name.
 
1871
 
 
1872
If the first character of @var{parameter} is an exclamation point (!),
 
1873
it introduces a level of variable indirection.
 
1874
Bash uses the value of the variable formed from the rest of
 
1875
@var{parameter} as the name of the variable; this variable is then
 
1876
expanded and that value is used in the rest of the substitution, rather
 
1877
than the value of @var{parameter} itself.
 
1878
This is known as @code{indirect expansion}.
 
1879
The exceptions to this are the expansions of $@{!@var{prefix}*@}
 
1880
and $@{!@var{name}[@@]@}
 
1881
described below.
 
1882
The exclamation point must immediately follow the left brace in order to
 
1883
introduce indirection.
 
1884
 
 
1885
In each of the cases below, @var{word} is subject to tilde expansion,
 
1886
parameter expansion, command substitution, and arithmetic expansion.
 
1887
 
 
1888
When not performing substring expansion, using the form described
 
1889
below (e.g., @samp{:-}), Bash tests for a parameter that is unset or null.
 
1890
Omitting the colon results in a test only for a parameter that is unset.
 
1891
Put another way, if the colon is included,
 
1892
the operator tests for both @var{parameter}'s existence and that its value
 
1893
is not null; if the colon is omitted, the operator tests only for existence.
 
1894
 
 
1895
@table @code
 
1896
 
 
1897
@item $@{@var{parameter}:@minus{}@var{word}@}
 
1898
If @var{parameter} is unset or null, the expansion of
 
1899
@var{word} is substituted.  Otherwise, the value of
 
1900
@var{parameter} is substituted.
 
1901
 
 
1902
@item $@{@var{parameter}:=@var{word}@}
 
1903
If @var{parameter}
 
1904
is unset or null, the expansion of @var{word}
 
1905
is assigned to @var{parameter}.
 
1906
The value of @var{parameter} is then substituted. 
 
1907
Positional parameters and special parameters may not be assigned to
 
1908
in this way.
 
1909
 
 
1910
@item $@{@var{parameter}:?@var{word}@}
 
1911
If @var{parameter}
 
1912
is null or unset, the expansion of @var{word} (or a message
 
1913
to that effect if @var{word}
 
1914
is not present) is written to the standard error and the shell, if it
 
1915
is not interactive, exits.  Otherwise, the value of @var{parameter} is
 
1916
substituted.
 
1917
 
 
1918
@item $@{@var{parameter}:+@var{word}@}
 
1919
If @var{parameter}
 
1920
is null or unset, nothing is substituted, otherwise the expansion of
 
1921
@var{word} is substituted.
 
1922
 
 
1923
@item $@{@var{parameter}:@var{offset}@}
 
1924
@itemx $@{@var{parameter}:@var{offset}:@var{length}@}
 
1925
This is referred to as Substring Expansion.
 
1926
It expands to up to @var{length} characters of the value of @var{parameter}
 
1927
starting at the character specified by @var{offset}.
 
1928
If @var{parameter} is @samp{@@}, an indexed array subscripted by
 
1929
@samp{@@} or @samp{*}, or an associative array name, the results differ as
 
1930
described below.
 
1931
If @var{length} is omitted, it expands to the substring of the value of
 
1932
@var{parameter} starting at the character specified by @var{offset}
 
1933
and extending to the end of the value.
 
1934
@var{length} and @var{offset} are arithmetic expressions
 
1935
(@pxref{Shell Arithmetic}).
 
1936
 
 
1937
If @var{offset} evaluates to a number less than zero, the value
 
1938
is used as an offset in characters
 
1939
from the end of the value of @var{parameter}.
 
1940
If @var{length} evaluates to a number less than zero,
 
1941
it is interpreted as an offset in characters
 
1942
from the end of the value of @var{parameter} rather than
 
1943
a number of characters, and the expansion is the characters between
 
1944
@var{offset} and that result.
 
1945
Note that a negative offset must be separated from the colon by at least
 
1946
one space to avoid being confused with the @samp{:-} expansion.
 
1947
 
 
1948
Here are some examples illustrating substring expansion on parameters and
 
1949
subscripted arrays:
 
1950
 
 
1951
@verbatim
 
1952
$ string=01234567890abcdefgh
 
1953
$ echo ${string:7}
 
1954
7890abcdefgh
 
1955
$ echo ${string:7:0}
 
1956
 
 
1957
$ echo ${string:7:2}
 
1958
78
 
1959
$ echo ${string:7:-2}
 
1960
7890abcdef
 
1961
$ echo ${string: -7}
 
1962
bcdefgh
 
1963
$ echo ${string: -7:0}
 
1964
 
 
1965
$ echo ${string: -7:2}
 
1966
bc
 
1967
$ echo ${string: -7:-2}
 
1968
bcdef
 
1969
$ set -- 01234567890abcdefgh
 
1970
$ echo ${1:7}
 
1971
7890abcdefgh
 
1972
$ echo ${1:7:0}
 
1973
 
 
1974
$ echo ${1:7:2}
 
1975
78
 
1976
$ echo ${1:7:-2}
 
1977
7890abcdef
 
1978
$ echo ${1: -7}
 
1979
bcdefgh
 
1980
$ echo ${1: -7:0}
 
1981
 
 
1982
$ echo ${1: -7:2}
 
1983
bc
 
1984
$ echo ${1: -7:-2}
 
1985
bcdef
 
1986
$ array[0]=01234567890abcdefgh
 
1987
$ echo ${array[0]:7}
 
1988
7890abcdefgh
 
1989
$ echo ${array[0]:7:0}
 
1990
 
 
1991
$ echo ${array[0]:7:2}
 
1992
78
 
1993
$ echo ${array[0]:7:-2}
 
1994
7890abcdef
 
1995
$ echo ${array[0]: -7}
 
1996
bcdefgh
 
1997
$ echo ${array[0]: -7:0}
 
1998
 
 
1999
$ echo ${array[0]: -7:2}
 
2000
bc
 
2001
$ echo ${array[0]: -7:-2}
 
2002
bcdef
 
2003
@end verbatim
 
2004
 
 
2005
If @var{parameter} is @samp{@@}, the result is @var{length} positional
 
2006
parameters beginning at @var{offset}.
 
2007
A negative @var{offset} is taken relative to one greater than the greatest
 
2008
positional parameter, so an offset of -1 evaluates to the last positional
 
2009
parameter.
 
2010
It is an expansion error if @var{length} evaluates to a number less than zero.
 
2011
 
 
2012
The following examples illustrate substring expansion using positional
 
2013
parameters:
 
2014
 
 
2015
@verbatim
 
2016
$ set -- 1 2 3 4 5 6 7 8 9 0 a b c d e f g h
 
2017
$ echo ${@:7}
 
2018
7 8 9 0 a b c d e f g h
 
2019
$ echo ${@:7:0}
 
2020
 
 
2021
$ echo ${@:7:2}
 
2022
7 8
 
2023
$ echo ${@:7:-2}
 
2024
bash: -2: substring expression < 0
 
2025
$ echo ${@: -7:2}
 
2026
b c
 
2027
$ echo ${@:0}
 
2028
./bash 1 2 3 4 5 6 7 8 9 0 a b c d e f g h
 
2029
$ echo ${@:0:2}
 
2030
./bash 1
 
2031
$ echo ${@: -7:0}
 
2032
 
 
2033
@end verbatim
 
2034
 
 
2035
If @var{parameter} is an indexed array name subscripted
 
2036
by @samp{@@} or @samp{*}, the result is the @var{length}
 
2037
members of the array beginning with @code{$@{@var{parameter}[@var{offset}]@}}.
 
2038
A negative @var{offset} is taken relative to one greater than the maximum
 
2039
index of the specified array.
 
2040
It is an expansion error if @var{length} evaluates to a number less than zero.
 
2041
 
 
2042
These examples show how you can use substring expansion with indexed
 
2043
arrays:
 
2044
 
 
2045
@verbatim
 
2046
$ array=(0 1 2 3 4 5 6 7 8 9 0 a b c d e f g h)
 
2047
$ echo ${array[@]:7}
 
2048
7 8 9 0 a b c d e f g h
 
2049
$ echo ${array[@]:7:2}
 
2050
7 8
 
2051
$ echo ${array[@]: -7:2}
 
2052
b c
 
2053
$ echo ${array[@]: -7:-2}
 
2054
bash: -2: substring expression < 0
 
2055
$ echo ${array[@]:0}
 
2056
0 1 2 3 4 5 6 7 8 9 0 a b c d e f g h
 
2057
$ echo ${array[@]:0:2}
 
2058
0 1
 
2059
$ echo ${array[@]: -7:0}
 
2060
 
 
2061
@end verbatim
 
2062
 
 
2063
Substring expansion applied to an associative array produces undefined
 
2064
results.
 
2065
 
 
2066
Substring indexing is zero-based unless the positional parameters
 
2067
are used, in which case the indexing starts at 1 by default.
 
2068
If @var{offset} is 0, and the positional parameters are used, @code{$@@} is
 
2069
prefixed to the list.
 
2070
 
 
2071
@item $@{!@var{prefix}*@}
 
2072
@itemx $@{!@var{prefix}@@@}
 
2073
Expands to the names of variables whose names begin with @var{prefix},
 
2074
separated by the first character of the @env{IFS} special variable.
 
2075
When @samp{@@} is used and the expansion appears within double quotes, each
 
2076
variable name expands to a separate word.
 
2077
 
 
2078
@item $@{!@var{name}[@@]@}
 
2079
@itemx $@{!@var{name}[*]@}
 
2080
If @var{name} is an array variable, expands to the list of array indices
 
2081
(keys) assigned in @var{name}.
 
2082
If @var{name} is not an array, expands to 0 if @var{name} is set and null
 
2083
otherwise.
 
2084
When @samp{@@} is used and the expansion appears within double quotes, each
 
2085
key expands to a separate word.
 
2086
 
 
2087
@item $@{#@var{parameter}@}
 
2088
The length in characters of the expanded value of @var{parameter} is
 
2089
substituted.
 
2090
If @var{parameter} is @samp{*} or @samp{@@}, the value substituted
 
2091
is the number of positional parameters.
 
2092
If @var{parameter} is an array name subscripted by @samp{*} or @samp{@@}, 
 
2093
the value substituted is the number of elements in the array.
 
2094
If @var{parameter}
 
2095
is an indexed array name subscripted by a negative number, that number is
 
2096
interpreted as relative to one greater than the maximum index of
 
2097
@var{parameter}, so negative indices count back from the end of the
 
2098
array, and an index of -1 references the last element.
 
2099
 
 
2100
@item $@{@var{parameter}#@var{word}@}
 
2101
@itemx $@{@var{parameter}##@var{word}@}
 
2102
The @var{word}
 
2103
is expanded to produce a pattern just as in filename
 
2104
expansion (@pxref{Filename Expansion}).  If the pattern matches
 
2105
the beginning of the expanded value of @var{parameter},
 
2106
then the result of the expansion is the expanded value of @var{parameter}
 
2107
with the shortest matching pattern (the @samp{#} case) or the
 
2108
longest matching pattern (the @samp{##} case) deleted.
 
2109
If @var{parameter} is @samp{@@} or @samp{*},
 
2110
the pattern removal operation is applied to each positional
 
2111
parameter in turn, and the expansion is the resultant list.
 
2112
If @var{parameter} is an array variable subscripted with
 
2113
@samp{@@} or @samp{*},
 
2114
the pattern removal operation is applied to each member of the
 
2115
array in turn, and the expansion is the resultant list.
 
2116
 
 
2117
@item $@{@var{parameter}%@var{word}@}
 
2118
@itemx $@{@var{parameter}%%@var{word}@}
 
2119
The @var{word} is expanded to produce a pattern just as in
 
2120
filename expansion.
 
2121
If the pattern matches a trailing portion of the expanded value of
 
2122
@var{parameter}, then the result of the expansion is the value of
 
2123
@var{parameter} with the shortest matching pattern (the @samp{%} case)
 
2124
or the longest matching pattern (the @samp{%%} case) deleted.
 
2125
If @var{parameter} is @samp{@@} or @samp{*},
 
2126
the pattern removal operation is applied to each positional
 
2127
parameter in turn, and the expansion is the resultant list.
 
2128
If @var{parameter}
 
2129
is an array variable subscripted with @samp{@@} or @samp{*},
 
2130
the pattern removal operation is applied to each member of the
 
2131
array in turn, and the expansion is the resultant list.
 
2132
 
 
2133
@item $@{@var{parameter}/@var{pattern}/@var{string}@} 
 
2134
 
 
2135
The @var{pattern} is expanded to produce a pattern just as in
 
2136
filename expansion.
 
2137
@var{Parameter} is expanded and the longest match of @var{pattern}
 
2138
against its value is replaced with @var{string}.
 
2139
If @var{pattern} begins with @samp{/}, all matches of @var{pattern} are
 
2140
replaced with @var{string}.  Normally only the first match is replaced.
 
2141
If @var{pattern} begins with @samp{#}, it must match at the beginning
 
2142
of the expanded value of @var{parameter}.
 
2143
If @var{pattern} begins with @samp{%}, it must match at the end
 
2144
of the expanded value of @var{parameter}.
 
2145
If @var{string} is null, matches of @var{pattern} are deleted
 
2146
and the @code{/} following @var{pattern} may be omitted.
 
2147
If @var{parameter} is @samp{@@} or @samp{*},
 
2148
the substitution operation is applied to each positional
 
2149
parameter in turn, and the expansion is the resultant list.
 
2150
If @var{parameter}
 
2151
is an array variable subscripted with @samp{@@} or @samp{*},
 
2152
the substitution operation is applied to each member of the
 
2153
array in turn, and the expansion is the resultant list.
 
2154
 
 
2155
@item $@{@var{parameter}^@var{pattern}@}
 
2156
@itemx $@{@var{parameter}^^@var{pattern}@}
 
2157
@itemx $@{@var{parameter},@var{pattern}@}
 
2158
@itemx $@{@var{parameter},,@var{pattern}@}
 
2159
This expansion modifies the case of alphabetic characters in @var{parameter}.
 
2160
The @var{pattern} is expanded to produce a pattern just as in
 
2161
filename expansion.
 
2162
Each character in the expanded value of @var{parameter} is tested against
 
2163
@var{pattern}, and, if it matches the pattern, its case is converted.
 
2164
The pattern should not attempt to match more than one character.
 
2165
The @samp{^} operator converts lowercase letters matching @var{pattern}
 
2166
to uppercase; the @samp{,} operator converts matching uppercase letters
 
2167
to lowercase.
 
2168
The @samp{^^} and @samp{,,} expansions convert each matched character in the
 
2169
expanded value; the @samp{^} and @samp{,} expansions match and convert only
 
2170
the first character in the expanded value.
 
2171
If @var{pattern} is omitted, it is treated like a @samp{?}, which matches
 
2172
every character.
 
2173
If @var{parameter} is @samp{@@} or @samp{*},
 
2174
the case modification operation is applied to each positional
 
2175
parameter in turn, and the expansion is the resultant list.
 
2176
If @var{parameter}
 
2177
is an array variable subscripted with @samp{@@} or @samp{*},
 
2178
the case modification operation is applied to each member of the
 
2179
array in turn, and the expansion is the resultant list.
 
2180
@end table
 
2181
 
 
2182
@node Command Substitution
 
2183
@subsection Command Substitution
 
2184
@cindex command substitution
 
2185
 
 
2186
Command substitution allows the output of a command to replace
 
2187
the command itself.
 
2188
Command substitution occurs when a command is enclosed as follows:
 
2189
@example
 
2190
$(@var{command})
 
2191
@end example
 
2192
@noindent
 
2193
or
 
2194
@example
 
2195
`@var{command}`
 
2196
@end example
 
2197
 
 
2198
@noindent
 
2199
Bash performs the expansion by executing @var{command} and
 
2200
replacing the command substitution with the standard output of the
 
2201
command, with any trailing newlines deleted.
 
2202
Embedded newlines are not deleted, but they may be removed during
 
2203
word splitting.
 
2204
The command substitution @code{$(cat @var{file})} can be
 
2205
replaced by the equivalent but faster @code{$(< @var{file})}.
 
2206
 
 
2207
When the old-style backquote form of substitution is used,
 
2208
backslash retains its literal meaning except when followed by
 
2209
@samp{$}, @samp{`}, or @samp{\}. 
 
2210
The first backquote not preceded by a backslash terminates the
 
2211
command substitution.
 
2212
When using the @code{$(@var{command})} form, all characters between
 
2213
the parentheses make up the command; none are treated specially.
 
2214
 
 
2215
Command substitutions may be nested.  To nest when using the backquoted
 
2216
form, escape the inner backquotes with backslashes.
 
2217
 
 
2218
If the substitution appears within double quotes, word splitting and
 
2219
filename expansion are not performed on the results.
 
2220
 
 
2221
@node Arithmetic Expansion
 
2222
@subsection Arithmetic Expansion
 
2223
@cindex expansion, arithmetic
 
2224
@cindex arithmetic expansion
 
2225
 
 
2226
Arithmetic expansion allows the evaluation of an arithmetic expression
 
2227
and the substitution of the result.  The format for arithmetic expansion is:
 
2228
 
 
2229
@example
 
2230
$(( @var{expression} ))
 
2231
@end example
 
2232
 
 
2233
The expression is treated as if it were within double quotes, but
 
2234
a double quote inside the parentheses is not treated specially.
 
2235
All tokens in the expression undergo parameter and variable expansion,
 
2236
command substitution, and quote removal.
 
2237
The result is treated as the arithmetic expression to be evaluated.
 
2238
Arithmetic expansions may be nested. 
 
2239
 
 
2240
The evaluation is performed according to the rules listed below
 
2241
(@pxref{Shell Arithmetic}).
 
2242
If the expression is invalid, Bash prints a message indicating
 
2243
failure to the standard error and no substitution occurs.
 
2244
 
 
2245
@node Process Substitution
 
2246
@subsection Process Substitution
 
2247
@cindex process substitution
 
2248
 
 
2249
Process substitution is supported on systems that support named
 
2250
pipes (@sc{fifo}s) or the @file{/dev/fd} method of naming open files.
 
2251
It takes the form of 
 
2252
@example
 
2253
<(@var{list})
 
2254
@end example
 
2255
@noindent
 
2256
or
 
2257
@example
 
2258
>(@var{list})
 
2259
@end example
 
2260
@noindent
 
2261
The process @var{list} is run with its input or output connected to a
 
2262
@sc{fifo} or some file in @file{/dev/fd}.  The name of this file is
 
2263
passed as an argument to the current command as the result of the
 
2264
expansion.  If the @code{>(@var{list})} form is used, writing to
 
2265
the file will provide input for @var{list}.  If the
 
2266
@code{<(@var{list})} form is used, the file passed as an
 
2267
argument should be read to obtain the output of @var{list}.
 
2268
Note that no space may appear between the @code{<} or @code{>}
 
2269
and the left parenthesis, otherwise the construct would be interpreted
 
2270
as a redirection.
 
2271
 
 
2272
When available, process substitution is performed simultaneously with
 
2273
parameter and variable expansion, command substitution, and arithmetic
 
2274
expansion.
 
2275
 
 
2276
@node Word Splitting
 
2277
@subsection Word Splitting
 
2278
@cindex word splitting
 
2279
 
 
2280
The shell scans the results of parameter expansion, command substitution,
 
2281
and arithmetic expansion that did not occur within double quotes for
 
2282
word splitting.
 
2283
 
 
2284
The shell treats each character of @env{$IFS} as a delimiter, and splits
 
2285
the results of the other expansions into words using these characters
 
2286
as field terminators.
 
2287
If @env{IFS} is unset, or its value is exactly @code{<space><tab><newline>},
 
2288
the default, then sequences of
 
2289
@code{ <space>}, @code{<tab>}, and @code{<newline>}
 
2290
at the beginning and end of the results of the previous
 
2291
expansions are ignored, and any sequence of @env{IFS}
 
2292
characters not at the beginning or end serves to delimit words.
 
2293
If @env{IFS} has a value other than the default, then sequences of
 
2294
the whitespace characters @code{space} and @code{tab}
 
2295
are ignored at the beginning and end of the
 
2296
word, as long as the whitespace character is in the
 
2297
value of @env{IFS} (an @env{IFS} whitespace character).
 
2298
Any character in @env{IFS} that is not @env{IFS}
 
2299
whitespace, along with any adjacent @env{IFS}
 
2300
whitespace characters, delimits a field.  A sequence of @env{IFS}
 
2301
whitespace characters is also treated as a delimiter.
 
2302
If the value of @env{IFS} is null, no word splitting occurs.
 
2303
 
 
2304
Explicit null arguments (@code{""} or @code{''}) are retained.
 
2305
Unquoted implicit null arguments, resulting from the expansion of
 
2306
parameters that have no values, are removed.
 
2307
If a parameter with no value is expanded within double quotes, a
 
2308
null argument results and is retained.
 
2309
 
 
2310
Note that if no expansion occurs, no splitting
 
2311
is performed.
 
2312
 
 
2313
@node Filename Expansion
 
2314
@subsection Filename Expansion
 
2315
@menu
 
2316
* Pattern Matching::    How the shell matches patterns.
 
2317
@end menu
 
2318
@cindex expansion, filename
 
2319
@cindex expansion, pathname
 
2320
@cindex filename expansion
 
2321
@cindex pathname expansion
 
2322
 
 
2323
After word splitting, unless the @option{-f} option has been set
 
2324
(@pxref{The Set Builtin}), Bash scans each word for the characters
 
2325
@samp{*}, @samp{?}, and @samp{[}.
 
2326
If one of these characters appears, then the word is
 
2327
regarded as a @var{pattern},
 
2328
and replaced with an alphabetically sorted list of
 
2329
filenames matching the pattern (@pxref{Pattern Matching}).
 
2330
If no matching filenames are found,
 
2331
and the shell option @code{nullglob} is disabled, the word is left
 
2332
unchanged.
 
2333
If the @code{nullglob} option is set, and no matches are found, the word
 
2334
is removed.
 
2335
If the @code{failglob} shell option is set, and no matches are found,
 
2336
an error message is printed and the command is not executed.
 
2337
If the shell option @code{nocaseglob} is enabled, the match is performed
 
2338
without regard to the case of alphabetic characters.
 
2339
 
 
2340
When a pattern is used for filename expansion, the character @samp{.}
 
2341
at the start of a filename or immediately following a slash
 
2342
must be matched explicitly, unless the shell option @code{dotglob} is set.
 
2343
When matching a filename, the slash character must always be
 
2344
matched explicitly.
 
2345
In other cases, the @samp{.} character is not treated specially.
 
2346
 
 
2347
See the description of @code{shopt} in @ref{The Shopt Builtin},
 
2348
for a description of the @code{nocaseglob}, @code{nullglob},
 
2349
@code{failglob}, and @code{dotglob} options.
 
2350
 
 
2351
The @env{GLOBIGNORE}
 
2352
shell variable may be used to restrict the set of filenames matching a
 
2353
pattern.  If @env{GLOBIGNORE}
 
2354
is set, each matching filename that also matches one of the patterns in
 
2355
@env{GLOBIGNORE} is removed from the list of matches.  The filenames
 
2356
@file{.} and @file{..}
 
2357
are always ignored when @env{GLOBIGNORE}
 
2358
is set and not null.
 
2359
However, setting @env{GLOBIGNORE} to a non-null value has the effect of
 
2360
enabling the @code{dotglob}
 
2361
shell option, so all other filenames beginning with a
 
2362
@samp{.} will match.
 
2363
To get the old behavior of ignoring filenames beginning with a
 
2364
@samp{.}, make @samp{.*} one of the patterns in @env{GLOBIGNORE}.
 
2365
The @code{dotglob} option is disabled when @env{GLOBIGNORE}
 
2366
is unset.
 
2367
 
 
2368
@node Pattern Matching
 
2369
@subsubsection Pattern Matching
 
2370
@cindex pattern matching
 
2371
@cindex matching, pattern
 
2372
 
 
2373
Any character that appears in a pattern, other than the special pattern
 
2374
characters described below, matches itself.
 
2375
The @sc{nul} character may not occur in a pattern.
 
2376
A backslash escapes the following character; the
 
2377
escaping backslash is discarded when matching.
 
2378
The special pattern characters must be quoted if they are to be matched
 
2379
literally.
 
2380
 
 
2381
The special pattern characters have the following meanings:
 
2382
@table @code
 
2383
@item *
 
2384
Matches any string, including the null string.
 
2385
When the @code{globstar} shell option is enabled, and @samp{*} is used in
 
2386
a filename expansion context, two adjacent @samp{*}s used as a single
 
2387
pattern will match all files and zero or more directories and
 
2388
subdirectories.
 
2389
If followed by a @samp{/}, two adjacent @samp{*}s will match only
 
2390
directories and subdirectories.
 
2391
@item ?
 
2392
Matches any single character.
 
2393
@item [@dots{}]
 
2394
Matches any one of the enclosed characters.  A pair of characters
 
2395
separated by a hyphen denotes a @var{range expression};
 
2396
any character that falls between those two characters, inclusive,
 
2397
using the current locale's collating sequence and character set,
 
2398
is matched.  If the first character following the
 
2399
@samp{[} is a @samp{!}  or a @samp{^}
 
2400
then any character not enclosed is matched.  A @samp{@minus{}}
 
2401
may be matched by including it as the first or last character
 
2402
in the set.  A @samp{]} may be matched by including it as the first
 
2403
character in the set.
 
2404
The sorting order of characters in range expressions is determined by
 
2405
the current locale and the values of the
 
2406
@env{LC_COLLATE} and @env{LC_ALL} shell variables, if set.
 
2407
 
 
2408
For example, in the default C locale, @samp{[a-dx-z]} is equivalent to
 
2409
@samp{[abcdxyz]}.  Many locales sort characters in dictionary order, and in
 
2410
these locales @samp{[a-dx-z]} is typically not equivalent to @samp{[abcdxyz]};
 
2411
it might be equivalent to @samp{[aBbCcDdxXyYz]}, for example.  To obtain
 
2412
the traditional interpretation of ranges in bracket expressions, you can
 
2413
force the use of the C locale by setting the @env{LC_COLLATE} or
 
2414
@env{LC_ALL} environment variable to the value @samp{C}, or enable the
 
2415
@code{globasciiranges} shell option.
 
2416
 
 
2417
Within @samp{[} and @samp{]}, @var{character classes} can be specified
 
2418
using the syntax
 
2419
@code{[:}@var{class}@code{:]}, where @var{class} is one of the
 
2420
following classes defined in the @sc{posix} standard:
 
2421
@example
 
2422
alnum   alpha   ascii   blank   cntrl   digit   graph   lower
 
2423
print   punct   space   upper   word    xdigit
 
2424
@end example
 
2425
@noindent
 
2426
A character class matches any character belonging to that class.
 
2427
The @code{word} character class matches letters, digits, and the character
 
2428
@samp{_}.
 
2429
 
 
2430
Within @samp{[} and @samp{]}, an @var{equivalence class} can be
 
2431
specified using the syntax @code{[=}@var{c}@code{=]}, which
 
2432
matches all characters with the same collation weight (as defined
 
2433
by the current locale) as the character @var{c}.
 
2434
 
 
2435
Within @samp{[} and @samp{]}, the syntax @code{[.}@var{symbol}@code{.]}
 
2436
matches the collating symbol @var{symbol}.
 
2437
@end table
 
2438
 
 
2439
If the @code{extglob} shell option is enabled using the @code{shopt}
 
2440
builtin, several extended pattern matching operators are recognized.
 
2441
In the following description, a @var{pattern-list} is a list of one
 
2442
or more patterns separated by a @samp{|}.
 
2443
Composite patterns may be formed using one or more of the following
 
2444
sub-patterns:
 
2445
 
 
2446
@table @code
 
2447
@item ?(@var{pattern-list})
 
2448
Matches zero or one occurrence of the given patterns.
 
2449
 
 
2450
@item *(@var{pattern-list})
 
2451
Matches zero or more occurrences of the given patterns.
 
2452
 
 
2453
@item +(@var{pattern-list})
 
2454
Matches one or more occurrences of the given patterns.
 
2455
 
 
2456
@item @@(@var{pattern-list})
 
2457
Matches one of the given patterns.
 
2458
 
 
2459
@item !(@var{pattern-list})
 
2460
Matches anything except one of the given patterns.
 
2461
@end table
 
2462
 
 
2463
@node Quote Removal
 
2464
@subsection Quote Removal
 
2465
 
 
2466
After the preceding expansions, all unquoted occurrences of the
 
2467
characters @samp{\}, @samp{'}, and @samp{"} that did not
 
2468
result from one of the above expansions are removed.
 
2469
 
 
2470
@node Redirections
 
2471
@section Redirections
 
2472
@cindex redirection
 
2473
 
 
2474
Before a command is executed, its input and output
 
2475
may be @var{redirected}
 
2476
using a special notation interpreted by the shell.
 
2477
Redirection allows commands' file handles to be
 
2478
duplicated, opened, closed,
 
2479
made to refer to different files,
 
2480
and can change the files the command reads from and writes to.
 
2481
Redirection may also be used to modify file handles in the
 
2482
current shell execution environment.  The following redirection
 
2483
operators may precede or appear anywhere within a
 
2484
simple command or may follow a command.
 
2485
Redirections are processed in the order they appear, from
 
2486
left to right.
 
2487
 
 
2488
Each redirection that may be preceded by a file descriptor number
 
2489
may instead be preceded by a word of the form @{@var{varname}@}.
 
2490
In this case, for each redirection operator except
 
2491
>&- and <&-, the shell will allocate a file descriptor greater
 
2492
than 10 and assign it to @{@var{varname}@}.  If >&- or <&- is preceded
 
2493
by @{@var{varname}@}, the value of @var{varname} defines the file
 
2494
descriptor to close.
 
2495
 
 
2496
In the following descriptions, if the file descriptor number is
 
2497
omitted, and the first character of the redirection operator is
 
2498
@samp{<}, the redirection refers to the standard input (file
 
2499
descriptor 0).  If the first character of the redirection operator
 
2500
is @samp{>}, the redirection refers to the standard output (file
 
2501
descriptor 1).
 
2502
 
 
2503
The word following the redirection operator in the following
 
2504
descriptions, unless otherwise noted, is subjected to brace expansion,
 
2505
tilde expansion, parameter expansion, command substitution, arithmetic
 
2506
expansion, quote removal, filename expansion, and word splitting.
 
2507
If it expands to more than one word, Bash reports an error.
 
2508
 
 
2509
Note that the order of redirections is significant.  For example,
 
2510
the command
 
2511
@example
 
2512
ls > @var{dirlist} 2>&1
 
2513
@end example
 
2514
@noindent
 
2515
directs both standard output (file descriptor 1) and standard error
 
2516
(file descriptor 2) to the file @var{dirlist}, while the command
 
2517
@example
 
2518
ls 2>&1 > @var{dirlist}
 
2519
@end example
 
2520
@noindent
 
2521
directs only the standard output to file @var{dirlist},
 
2522
because the standard error was made a copy of the standard output
 
2523
before the standard output was redirected to @var{dirlist}.
 
2524
 
 
2525
Bash handles several filenames specially when they are used in
 
2526
redirections, as described in the following table:
 
2527
 
 
2528
@table @code
 
2529
@item /dev/fd/@var{fd}
 
2530
If @var{fd} is a valid integer, file descriptor @var{fd} is duplicated.
 
2531
 
 
2532
@item /dev/stdin
 
2533
File descriptor 0 is duplicated.
 
2534
 
 
2535
@item /dev/stdout
 
2536
File descriptor 1 is duplicated.
 
2537
 
 
2538
@item /dev/stderr
 
2539
File descriptor 2 is duplicated.
 
2540
 
 
2541
@item /dev/tcp/@var{host}/@var{port}
 
2542
If @var{host} is a valid hostname or Internet address, and @var{port}
 
2543
is an integer port number or service name, Bash attempts to open
 
2544
the corresponding TCP socket.
 
2545
 
 
2546
@item /dev/udp/@var{host}/@var{port}
 
2547
If @var{host} is a valid hostname or Internet address, and @var{port}
 
2548
is an integer port number or service name, Bash attempts to open 
 
2549
the corresponding UDP socket.
 
2550
@end table
 
2551
 
 
2552
A failure to open or create a file causes the redirection to fail.
 
2553
 
 
2554
Redirections using file descriptors greater than 9 should be used with
 
2555
care, as they may conflict with file descriptors the shell uses
 
2556
internally.
 
2557
 
 
2558
@subsection Redirecting Input
 
2559
Redirection of input causes the file whose name results from
 
2560
the expansion of @var{word}
 
2561
to be opened for reading on file descriptor @code{n},
 
2562
or the standard input (file descriptor 0) if @code{n}
 
2563
is not specified.
 
2564
 
 
2565
The general format for redirecting input is:
 
2566
@example
 
2567
[@var{n}]<@var{word}
 
2568
@end example
 
2569
 
 
2570
@subsection Redirecting Output
 
2571
Redirection of output causes the file whose name results from
 
2572
the expansion of @var{word}
 
2573
to be opened for writing on file descriptor @var{n},
 
2574
or the standard output (file descriptor 1) if @var{n}
 
2575
is not specified.  If the file does not exist it is created;
 
2576
if it does exist it is truncated to zero size.
 
2577
 
 
2578
The general format for redirecting output is:
 
2579
@example
 
2580
[@var{n}]>[|]@var{word}
 
2581
@end example
 
2582
 
 
2583
If the redirection operator is @samp{>}, and the @code{noclobber}
 
2584
option to the @code{set} builtin has been enabled, the redirection
 
2585
will fail if the file whose name results from the expansion of
 
2586
@var{word} exists and is a regular file.
 
2587
If the redirection operator is @samp{>|}, or the redirection operator is
 
2588
@samp{>} and the @code{noclobber} option is not enabled, the redirection
 
2589
is attempted even if the file named by @var{word} exists.
 
2590
 
 
2591
@subsection Appending Redirected Output
 
2592
Redirection of output in this fashion
 
2593
causes the file whose name results from
 
2594
the expansion of @var{word}
 
2595
to be opened for appending on file descriptor @var{n},
 
2596
or the standard output (file descriptor 1) if @var{n}
 
2597
is not specified.  If the file does not exist it is created.
 
2598
 
 
2599
The general format for appending output is:
 
2600
@example
 
2601
[@var{n}]>>@var{word}
 
2602
@end example
 
2603
 
 
2604
@subsection Redirecting Standard Output and Standard Error
 
2605
This construct allows both the
 
2606
standard output (file descriptor 1) and
 
2607
the standard error output (file descriptor 2)
 
2608
to be redirected to the file whose name is the
 
2609
expansion of @var{word}.
 
2610
 
 
2611
There are two formats for redirecting standard output and
 
2612
standard error:
 
2613
@example
 
2614
&>@var{word}
 
2615
@end example
 
2616
@noindent
 
2617
and
 
2618
@example
 
2619
>&@var{word}
 
2620
@end example
 
2621
@noindent
 
2622
Of the two forms, the first is preferred.
 
2623
This is semantically equivalent to
 
2624
@example
 
2625
>@var{word} 2>&1
 
2626
@end example
 
2627
When using the second form, @var{word} may not expand to a number or
 
2628
@samp{-}.  If it does, other redirection operators apply
 
2629
(see Duplicating File Descriptors below) for compatibility reasons.
 
2630
 
 
2631
@subsection Appending Standard Output and Standard Error
 
2632
This construct allows both the
 
2633
standard output (file descriptor 1) and
 
2634
the standard error output (file descriptor 2)
 
2635
to be appended to the file whose name is the
 
2636
expansion of @var{word}.
 
2637
 
 
2638
The format for appending standard output and standard error is:
 
2639
@example
 
2640
&>>@var{word}
 
2641
@end example
 
2642
@noindent
 
2643
This is semantically equivalent to
 
2644
@example
 
2645
>>@var{word} 2>&1
 
2646
@end example
 
2647
(see Duplicating File Descriptors below).
 
2648
 
 
2649
@subsection Here Documents
 
2650
This type of redirection instructs the shell to read input from the
 
2651
current source until a line containing only @var{word}
 
2652
(with no trailing blanks) is seen.  All of
 
2653
the lines read up to that point are then used as the standard
 
2654
input for a command.
 
2655
 
 
2656
The format of here-documents is:
 
2657
@example
 
2658
<<[@minus{}]@var{word}
 
2659
        @var{here-document}
 
2660
@var{delimiter}
 
2661
@end example
 
2662
 
 
2663
No parameter and variable expansion, command substitution,
 
2664
arithmetic expansion, or filename expansion is performed on
 
2665
@var{word}.  If any characters in @var{word} are quoted, the
 
2666
@var{delimiter} is the result of quote removal on @var{word},
 
2667
and the lines in the here-document are not expanded.
 
2668
If @var{word} is unquoted,
 
2669
all lines of the here-document are subjected to
 
2670
parameter expansion, command substitution, and arithmetic expansion,
 
2671
the character sequence @code{\newline} is ignored, and @samp{\}
 
2672
must be used to quote the characters
 
2673
@samp{\}, @samp{$}, and @samp{`}.
 
2674
 
 
2675
If the redirection operator is @samp{<<-},
 
2676
then all leading tab characters are stripped from input lines and the
 
2677
line containing @var{delimiter}.
 
2678
This allows here-documents within shell scripts to be indented in a
 
2679
natural fashion.
 
2680
 
 
2681
@subsection Here Strings
 
2682
A variant of here documents, the format is:
 
2683
@example
 
2684
<<< @var{word}
 
2685
@end example
 
2686
 
 
2687
The @var{word} undergoes
 
2688
brace expansion, tilde expansion, parameter and variable expansion,
 
2689
command substitution, arithmetic expansion, and quote removal.
 
2690
Pathname expansion and word splitting are not performed.
 
2691
The result is supplied as a single string to the command on its
 
2692
standard input.
 
2693
 
 
2694
@subsection Duplicating File Descriptors
 
2695
The redirection operator
 
2696
@example
 
2697
[@var{n}]<&@var{word}
 
2698
@end example
 
2699
@noindent
 
2700
is used to duplicate input file descriptors.
 
2701
If @var{word}
 
2702
expands to one or more digits, the file descriptor denoted by @var{n}
 
2703
is made to be a copy of that file descriptor.
 
2704
If the digits in @var{word} do not specify a file descriptor open for
 
2705
input, a redirection error occurs.
 
2706
If @var{word}
 
2707
evaluates to @samp{-}, file descriptor @var{n} is closed.
 
2708
If @var{n} is not specified, the standard input (file descriptor 0) is used.
 
2709
 
 
2710
The operator
 
2711
@example
 
2712
[@var{n}]>&@var{word}
 
2713
@end example
 
2714
@noindent
 
2715
is used similarly to duplicate output file descriptors.  If
 
2716
@var{n} is not specified, the standard output (file descriptor 1) is used.
 
2717
If the digits in @var{word} do not specify a file descriptor open for
 
2718
output, a redirection error occurs.
 
2719
If @var{word}
 
2720
evaluates to @samp{-}, file descriptor @var{n} is closed.
 
2721
As a special case, if @var{n} is omitted, and @var{word} does not
 
2722
expand to one or more digits or @samp{-}, the standard output and standard
 
2723
error are redirected as described previously.
 
2724
 
 
2725
@subsection Moving File Descriptors
 
2726
The redirection operator
 
2727
@example
 
2728
[@var{n}]<&@var{digit}-
 
2729
@end example
 
2730
@noindent
 
2731
moves the file descriptor @var{digit} to file descriptor @var{n},
 
2732
or the standard input (file descriptor 0) if @var{n} is not specified.
 
2733
@var{digit} is closed after being duplicated to @var{n}.
 
2734
 
 
2735
Similarly, the redirection operator
 
2736
@example
 
2737
[@var{n}]>&@var{digit}-
 
2738
@end example
 
2739
@noindent
 
2740
moves the file descriptor @var{digit} to file descriptor @var{n},
 
2741
or the standard output (file descriptor 1) if @var{n} is not specified.
 
2742
 
 
2743
@subsection Opening File Descriptors for Reading and Writing
 
2744
The redirection operator
 
2745
@example
 
2746
[@var{n}]<>@var{word}
 
2747
@end example
 
2748
@noindent
 
2749
causes the file whose name is the expansion of @var{word}
 
2750
to be opened for both reading and writing on file descriptor
 
2751
@var{n}, or on file descriptor 0 if @var{n}
 
2752
is not specified.  If the file does not exist, it is created.
 
2753
 
 
2754
@node Executing Commands
 
2755
@section Executing Commands
 
2756
 
 
2757
@menu
 
2758
* Simple Command Expansion::    How Bash expands simple commands before
 
2759
                                executing them.
 
2760
* Command Search and Execution::        How Bash finds commands and runs them.
 
2761
* Command Execution Environment::       The environment in which Bash
 
2762
                                        executes commands that are not
 
2763
                                        shell builtins.
 
2764
* Environment::         The environment given to a command.
 
2765
* Exit Status::         The status returned by commands and how Bash
 
2766
                        interprets it.
 
2767
* Signals::             What happens when Bash or a command it runs
 
2768
                        receives a signal.
 
2769
@end menu
 
2770
 
 
2771
@node Simple Command Expansion
 
2772
@subsection Simple Command Expansion
 
2773
@cindex command expansion
 
2774
 
 
2775
When a simple command is executed, the shell performs the following
 
2776
expansions, assignments, and redirections, from left to right.
 
2777
 
 
2778
@enumerate
 
2779
@item
 
2780
The words that the parser has marked as variable assignments (those
 
2781
preceding the command name) and redirections are saved for later
 
2782
processing.
 
2783
 
 
2784
@item
 
2785
The words that are not variable assignments or redirections are
 
2786
expanded (@pxref{Shell Expansions}).
 
2787
If any words remain after expansion, the first word
 
2788
is taken to be the name of the command and the remaining words are
 
2789
the arguments.
 
2790
 
 
2791
@item
 
2792
Redirections are performed as described above (@pxref{Redirections}).
 
2793
 
 
2794
@item
 
2795
The text after the @samp{=} in each variable assignment undergoes tilde
 
2796
expansion, parameter expansion, command substitution, arithmetic expansion,
 
2797
and quote removal before being assigned to the variable.
 
2798
@end enumerate
 
2799
 
 
2800
If no command name results, the variable assignments affect the current
 
2801
shell environment.  Otherwise, the variables are added to the environment
 
2802
of the executed command and do not affect the current shell environment.
 
2803
If any of the assignments attempts to assign a value to a readonly variable,
 
2804
an error occurs, and the command exits with a non-zero status.
 
2805
 
 
2806
If no command name results, redirections are performed, but do not
 
2807
affect the current shell environment.  A redirection error causes the
 
2808
command to exit with a non-zero status.
 
2809
 
 
2810
If there is a command name left after expansion, execution proceeds as
 
2811
described below.  Otherwise, the command exits.  If one of the expansions
 
2812
contained a command substitution, the exit status of the command is
 
2813
the exit status of the last command substitution performed.  If there
 
2814
were no command substitutions, the command exits with a status of zero.
 
2815
 
 
2816
@node Command Search and Execution
 
2817
@subsection Command Search and Execution
 
2818
@cindex command execution
 
2819
@cindex command search
 
2820
 
 
2821
After a command has been split into words, if it results in a
 
2822
simple command and an optional list of arguments, the following
 
2823
actions are taken.
 
2824
 
 
2825
@enumerate
 
2826
@item
 
2827
If the command name contains no slashes, the shell attempts to
 
2828
locate it.  If there exists a shell function by that name, that
 
2829
function is invoked as described in @ref{Shell Functions}.
 
2830
 
 
2831
@item
 
2832
If the name does not match a function, the shell searches for
 
2833
it in the list of shell builtins.  If a match is found, that
 
2834
builtin is invoked.
 
2835
 
 
2836
@item
 
2837
If the name is neither a shell function nor a builtin,
 
2838
and contains no slashes, Bash searches each element of
 
2839
@env{$PATH} for a directory containing an executable file
 
2840
by that name.  Bash uses a hash table to remember the full
 
2841
pathnames of executable files to avoid multiple @env{PATH} searches
 
2842
(see the description of @code{hash} in @ref{Bourne Shell Builtins}).
 
2843
A full search of the directories in @env{$PATH}
 
2844
is performed only if the command is not found in the hash table.
 
2845
If the search is unsuccessful, the shell searches for a defined shell
 
2846
function named @code{command_not_found_handle}.
 
2847
If that function exists, it is invoked with the original command and
 
2848
the original command's arguments as its arguments, and the function's
 
2849
exit status becomes the exit status of the shell.
 
2850
If that function is not defined, the shell prints an error
 
2851
message and returns an exit status of 127.
 
2852
 
 
2853
@item
 
2854
If the search is successful, or if the command name contains
 
2855
one or more slashes, the shell executes the named program in
 
2856
a separate execution environment.
 
2857
Argument 0 is set to the name given, and the remaining arguments
 
2858
to the command are set to the arguments supplied, if any.
 
2859
 
 
2860
@item
 
2861
If this execution fails because the file is not in executable
 
2862
format, and the file is not a directory, it is assumed to be a
 
2863
@var{shell script} and the shell executes it as described in
 
2864
@ref{Shell Scripts}.
 
2865
 
 
2866
@item
 
2867
If the command was not begun asynchronously, the shell waits for
 
2868
the command to complete and collects its exit status.
 
2869
 
 
2870
@end enumerate
 
2871
 
 
2872
@node Command Execution Environment
 
2873
@subsection Command Execution Environment
 
2874
@cindex execution environment
 
2875
 
 
2876
The shell has an @var{execution environment}, which consists of the
 
2877
following:
 
2878
 
 
2879
@itemize @bullet
 
2880
@item
 
2881
open files inherited by the shell at invocation, as modified by
 
2882
redirections supplied to the @code{exec} builtin
 
2883
 
 
2884
@item
 
2885
the current working directory as set by @code{cd}, @code{pushd}, or
 
2886
@code{popd}, or inherited by the shell at invocation
 
2887
 
 
2888
@item
 
2889
the file creation mode mask as set by @code{umask} or inherited from
 
2890
the shell's parent
 
2891
 
 
2892
@item
 
2893
current traps set by @code{trap}
 
2894
 
 
2895
@item
 
2896
shell parameters that are set by variable assignment or with @code{set}
 
2897
or inherited from the shell's parent in the environment
 
2898
 
 
2899
@item
 
2900
shell functions defined during execution or inherited from the shell's
 
2901
parent in the environment
 
2902
 
 
2903
@item
 
2904
options enabled at invocation (either by default or with command-line
 
2905
arguments) or by @code{set}
 
2906
 
 
2907
@item
 
2908
options enabled by @code{shopt} (@pxref{The Shopt Builtin})
 
2909
 
 
2910
@item
 
2911
shell aliases defined with @code{alias} (@pxref{Aliases})
 
2912
 
 
2913
@item
 
2914
various process @sc{id}s, including those of background jobs
 
2915
(@pxref{Lists}), the value of @code{$$}, and the value of
 
2916
@env{$PPID}
 
2917
 
 
2918
@end itemize
 
2919
 
 
2920
When a simple command other than a builtin or shell function
 
2921
is to be executed, it
 
2922
is invoked in a separate execution environment that consists of
 
2923
the following.  Unless otherwise noted, the values are inherited
 
2924
from the shell.
 
2925
 
 
2926
@itemize @bullet
 
2927
@item
 
2928
the shell's open files, plus any modifications and additions specified
 
2929
by redirections to the command
 
2930
 
 
2931
@item
 
2932
the current working directory
 
2933
 
 
2934
@item
 
2935
the file creation mode mask
 
2936
 
 
2937
@item
 
2938
shell variables and functions marked for export, along with variables
 
2939
exported for the command, passed in the environment (@pxref{Environment})
 
2940
 
 
2941
@item
 
2942
traps caught by the shell are reset to the values inherited from the
 
2943
shell's parent, and traps ignored by the shell are ignored
 
2944
 
 
2945
@end itemize
 
2946
 
 
2947
A command invoked in this separate environment cannot affect the
 
2948
shell's execution environment. 
 
2949
 
 
2950
Command substitution, commands grouped with parentheses,
 
2951
and asynchronous commands are invoked in a
 
2952
subshell environment that is a duplicate of the shell environment,
 
2953
except that traps caught by the shell are reset to the values
 
2954
that the shell inherited from its parent at invocation.  Builtin
 
2955
commands that are invoked as part of a pipeline are also executed
 
2956
in a subshell environment.  Changes made to the subshell environment
 
2957
cannot affect the shell's execution environment.
 
2958
 
 
2959
Subshells spawned to execute command substitutions inherit the value of
 
2960
the @option{-e} option from the parent shell.  When not in @sc{posix} mode,
 
2961
Bash clears the @option{-e} option in such subshells.
 
2962
 
 
2963
If a command is followed by a @samp{&} and job control is not active, the
 
2964
default standard input for the command is the empty file @file{/dev/null}.
 
2965
Otherwise, the invoked command inherits the file descriptors of the calling
 
2966
shell as modified by redirections.
 
2967
 
 
2968
@node Environment
 
2969
@subsection Environment
 
2970
@cindex environment
 
2971
 
 
2972
When a program is invoked it is given an array of strings
 
2973
called the @var{environment}.
 
2974
This is a list of name-value pairs, of the form @code{name=value}.
 
2975
 
 
2976
Bash provides several ways to manipulate the environment.
 
2977
On invocation, the shell scans its own environment and
 
2978
creates a parameter for each name found, automatically marking
 
2979
it for @var{export}
 
2980
to child processes.  Executed commands inherit the environment.
 
2981
The @code{export} and @samp{declare -x}
 
2982
commands allow parameters and functions to be added to and
 
2983
deleted from the environment.  If the value of a parameter
 
2984
in the environment is modified, the new value becomes part
 
2985
of the environment, replacing the old.  The environment
 
2986
inherited by any executed command consists of the shell's
 
2987
initial environment, whose values may be modified in the shell,
 
2988
less any pairs removed by the @code{unset} and @samp{export -n}
 
2989
commands, plus any additions via the @code{export} and
 
2990
@samp{declare -x} commands.
 
2991
 
 
2992
The environment for any simple command
 
2993
or function may be augmented temporarily by prefixing it with
 
2994
parameter assignments, as described in @ref{Shell Parameters}.
 
2995
These assignment statements affect only the environment seen
 
2996
by that command.
 
2997
 
 
2998
If the @option{-k} option is set (@pxref{The Set Builtin}), then all
 
2999
parameter assignments are placed in the environment for a command,
 
3000
not just those that precede the command name.
 
3001
 
 
3002
When Bash invokes an external command, the variable @samp{$_}
 
3003
is set to the full pathname of the command and passed to that
 
3004
command in its environment.
 
3005
 
 
3006
@node Exit Status
 
3007
@subsection Exit Status
 
3008
@cindex exit status
 
3009
 
 
3010
The exit status of an executed command is the value returned by the
 
3011
@var{waitpid} system call or equivalent function.  Exit statuses    
 
3012
fall between 0 and 255, though, as explained below, the shell may
 
3013
use values above 125 specially.  Exit statuses from shell builtins and
 
3014
compound commands are also limited to this range.  Under certain
 
3015
circumstances, the shell will use special values to indicate specific
 
3016
failure modes.
 
3017
 
 
3018
For the shell's purposes, a command which exits with a
 
3019
zero exit status has succeeded.
 
3020
A non-zero exit status indicates failure.
 
3021
This seemingly counter-intuitive scheme is used so there
 
3022
is one well-defined way to indicate success and a variety of
 
3023
ways to indicate various failure modes.
 
3024
When a command terminates on a fatal signal whose number is @var{N},
 
3025
Bash uses the value 128+@var{N} as the exit status.
 
3026
 
 
3027
If a command is not found, the child process created to
 
3028
execute it returns a status of 127.  If a command is found  
 
3029
but is not executable, the return status is 126.
 
3030
 
 
3031
If a command fails because of an error during expansion or redirection,
 
3032
the exit status is greater than zero.
 
3033
 
 
3034
The exit status is used by the Bash conditional commands
 
3035
(@pxref{Conditional Constructs}) and some of the list
 
3036
constructs (@pxref{Lists}).
 
3037
 
 
3038
All of the Bash builtins return an exit status of zero if they succeed
 
3039
and a non-zero status on failure, so they may be used by the
 
3040
conditional and list constructs.
 
3041
All builtins return an exit status of 2 to indicate incorrect usage.
 
3042
 
 
3043
@node Signals
 
3044
@subsection Signals
 
3045
@cindex signal handling
 
3046
 
 
3047
When Bash is interactive, in the absence of any traps, it ignores
 
3048
@code{SIGTERM} (so that @samp{kill 0} does not kill an interactive shell),
 
3049
and @code{SIGINT}
 
3050
is caught and handled (so that the @code{wait} builtin is interruptible).
 
3051
When Bash receives a @code{SIGINT}, it breaks out of any executing loops.
 
3052
In all cases, Bash ignores @code{SIGQUIT}.
 
3053
If job control is in effect (@pxref{Job Control}), Bash
 
3054
ignores @code{SIGTTIN}, @code{SIGTTOU}, and @code{SIGTSTP}.
 
3055
 
 
3056
Non-builtin commands started by Bash have signal handlers set to the
 
3057
values inherited by the shell from its parent.
 
3058
When job control is not in effect, asynchronous commands
 
3059
ignore @code{SIGINT} and @code{SIGQUIT} in addition to these inherited
 
3060
handlers.
 
3061
Commands run as a result of
 
3062
command substitution ignore the keyboard-generated job control signals
 
3063
@code{SIGTTIN}, @code{SIGTTOU}, and @code{SIGTSTP}.
 
3064
 
 
3065
The shell exits by default upon receipt of a @code{SIGHUP}.
 
3066
Before exiting, an interactive shell resends the @code{SIGHUP} to
 
3067
all jobs, running or stopped.
 
3068
Stopped jobs are sent @code{SIGCONT} to ensure that they receive
 
3069
the @code{SIGHUP}.
 
3070
To prevent the shell from sending the @code{SIGHUP} signal to a
 
3071
particular job, it should be removed
 
3072
from the jobs table with the @code{disown}
 
3073
builtin (@pxref{Job Control Builtins}) or marked
 
3074
to not receive @code{SIGHUP} using @code{disown -h}.
 
3075
 
 
3076
If the  @code{huponexit} shell option has been set with @code{shopt}
 
3077
(@pxref{The Shopt Builtin}), Bash sends a @code{SIGHUP} to all jobs when
 
3078
an interactive login shell exits.
 
3079
 
 
3080
If Bash is waiting for a command to complete and receives a signal
 
3081
for which a trap has been set, the trap will not be executed until
 
3082
the command completes. 
 
3083
When Bash is waiting for an asynchronous
 
3084
command via the @code{wait} builtin, the reception of a signal for
 
3085
which a trap has been set will cause the @code{wait} builtin to return
 
3086
immediately with an exit status greater than 128, immediately after
 
3087
which the trap is executed.
 
3088
 
 
3089
@node Shell Scripts
 
3090
@section Shell Scripts
 
3091
@cindex shell script
 
3092
 
 
3093
A shell script is a text file containing shell commands.  When such
 
3094
a file is used as the first non-option argument when invoking Bash,
 
3095
and neither the @option{-c} nor @option{-s} option is supplied
 
3096
(@pxref{Invoking Bash}), 
 
3097
Bash reads and executes commands from the file, then exits.  This
 
3098
mode of operation creates a non-interactive shell.  The shell first
 
3099
searches for the file in the current directory, and looks in the
 
3100
directories in @env{$PATH} if not found there.
 
3101
 
 
3102
When Bash runs
 
3103
a shell script, it sets the special parameter @code{0} to the name
 
3104
of the file, rather than the name of the shell, and the positional
 
3105
parameters are set to the remaining arguments, if any are given.
 
3106
If no additional arguments are supplied, the positional parameters
 
3107
are unset.
 
3108
 
 
3109
A shell script may be made executable by using the @code{chmod} command
 
3110
to turn on the execute bit.  When Bash finds such a file while
 
3111
searching the @env{$PATH} for a command, it spawns a subshell to
 
3112
execute it.  In other words, executing
 
3113
@example
 
3114
filename @var{arguments}
 
3115
@end example
 
3116
@noindent
 
3117
is equivalent to executing
 
3118
@example
 
3119
bash filename @var{arguments}
 
3120
@end example
 
3121
 
 
3122
@noindent
 
3123
if @code{filename} is an executable shell script.
 
3124
This subshell reinitializes itself, so that the effect is as if a
 
3125
new shell had been invoked to interpret the script, with the
 
3126
exception that the locations of commands remembered by the parent
 
3127
(see the description of @code{hash} in @ref{Bourne Shell Builtins})
 
3128
are retained by the child.
 
3129
 
 
3130
Most versions of Unix make this a part of the operating system's command
 
3131
execution mechanism.  If the first line of a script begins with
 
3132
the two characters @samp{#!}, the remainder of the line specifies
 
3133
an interpreter for the program.
 
3134
Thus, you can specify Bash, @code{awk}, Perl, or some other
 
3135
interpreter and write the rest of the script file in that language.
 
3136
 
 
3137
The arguments to the interpreter
 
3138
consist of a single optional argument following the interpreter
 
3139
name on the first line of the script file, followed by the name of
 
3140
the script file, followed by the rest of the arguments.  Bash
 
3141
will perform this action on operating systems that do not handle it
 
3142
themselves.  Note that some older versions of Unix limit the interpreter
 
3143
name and argument to a maximum of 32 characters.
 
3144
 
 
3145
Bash scripts often begin with @code{#! /bin/bash} (assuming that
 
3146
Bash has been installed in @file{/bin}), since this ensures that
 
3147
Bash will be used to interpret the script, even if it is executed
 
3148
under another shell.
 
3149
 
 
3150
@node Shell Builtin Commands
 
3151
@chapter Shell Builtin Commands
 
3152
 
 
3153
@menu
 
3154
* Bourne Shell Builtins::       Builtin commands inherited from the Bourne
 
3155
                                Shell.
 
3156
* Bash Builtins::               Table of builtins specific to Bash.
 
3157
* Modifying Shell Behavior::    Builtins to modify shell attributes and
 
3158
                                optional behavior.
 
3159
* Special Builtins::            Builtin commands classified specially by
 
3160
                                POSIX.
 
3161
@end menu
 
3162
 
 
3163
Builtin commands are contained within the shell itself.
 
3164
When the name of a builtin command is used as the first word of
 
3165
a simple command (@pxref{Simple Commands}), the shell executes
 
3166
the command directly, without invoking another program.
 
3167
Builtin commands are necessary to implement functionality impossible
 
3168
or inconvenient to obtain with separate utilities.
 
3169
 
 
3170
This section briefly describes the builtins which Bash inherits from
 
3171
the Bourne Shell, as well as the builtin commands which are unique
 
3172
to or have been extended in Bash.
 
3173
 
 
3174
Several builtin commands are described in other chapters:  builtin
 
3175
commands which provide the Bash interface to the job control
 
3176
facilities (@pxref{Job Control Builtins}), the directory stack
 
3177
(@pxref{Directory Stack Builtins}), the command history
 
3178
(@pxref{Bash History Builtins}), and the programmable completion
 
3179
facilities (@pxref{Programmable Completion Builtins}).
 
3180
 
 
3181
Many of the builtins have been extended by @sc{posix} or Bash.
 
3182
 
 
3183
Unless otherwise noted, each builtin command documented as accepting
 
3184
options preceded by @samp{-} accepts @samp{--}
 
3185
to signify the end of the options.
 
3186
The @code{:}, @code{true}, @code{false}, and @code{test}
 
3187
builtins do not accept options and do not treat @samp{--} specially.
 
3188
The @code{exit}, @code{logout}, @code{break}, @code{continue}, @code{let},
 
3189
and @code{shift} builtins accept and process arguments beginning
 
3190
with @samp{-} without requiring @samp{--}.
 
3191
Other builtins that accept arguments but are not specified as accepting
 
3192
options interpret arguments beginning with @samp{-} as invalid options and
 
3193
require @samp{--} to prevent this interpretation.
 
3194
 
 
3195
@node Bourne Shell Builtins
 
3196
@section Bourne Shell Builtins
 
3197
 
 
3198
The following shell builtin commands are inherited from the Bourne Shell.
 
3199
These commands are implemented as specified by the @sc{posix} standard.
 
3200
 
 
3201
@table @code
 
3202
@item :    @r{(a colon)}
 
3203
@btindex :
 
3204
@example
 
3205
: [@var{arguments}]
 
3206
@end example
 
3207
 
 
3208
Do nothing beyond expanding @var{arguments} and performing redirections.
 
3209
The return status is zero.
 
3210
 
 
3211
@item .    @r{(a period)}
 
3212
@btindex .
 
3213
@example
 
3214
. @var{filename} [@var{arguments}]
 
3215
@end example
 
3216
 
 
3217
Read and execute commands from the @var{filename} argument in the
 
3218
current shell context.  If @var{filename} does not contain a slash,
 
3219
the @env{PATH} variable is used to find @var{filename}.
 
3220
When Bash is not in @sc{posix} mode, the current directory is searched
 
3221
if @var{filename} is not found in @env{$PATH}.
 
3222
If any @var{arguments} are supplied, they become the positional
 
3223
parameters when @var{filename} is executed.  Otherwise the positional
 
3224
parameters are unchanged.
 
3225
The return status is the exit status of the last command executed, or
 
3226
zero if no commands are executed.  If @var{filename} is not found, or
 
3227
cannot be read, the return status is non-zero.
 
3228
This builtin is equivalent to @code{source}.
 
3229
 
 
3230
@item break
 
3231
@btindex break
 
3232
@example
 
3233
break [@var{n}]
 
3234
@end example
 
3235
 
 
3236
Exit from a @code{for}, @code{while}, @code{until}, or @code{select} loop.
 
3237
If @var{n} is supplied, the @var{n}th enclosing loop is exited.
 
3238
@var{n} must be greater than or equal to 1.
 
3239
The return status is zero unless @var{n} is not greater than or equal to 1.
 
3240
 
 
3241
@item cd
 
3242
@btindex cd
 
3243
@example
 
3244
cd [-L|[-P [-e]] [-@@] [@var{directory}]
 
3245
@end example
 
3246
 
 
3247
Change the current working directory to @var{directory}.
 
3248
If @var{directory} is not supplied, the value of the @env{HOME}
 
3249
shell variable is used.
 
3250
Any additional arguments following @var{directory} are ignored.
 
3251
If the shell variable
 
3252
@env{CDPATH} exists, it is used as a search path:
 
3253
each directory name in @env{CDPATH} is searched for
 
3254
@var{directory}, with alternative directory names in @env{CDPATH}
 
3255
separated by a colon (@samp{:}).
 
3256
If @var{directory} begins with a slash, @env{CDPATH} is not used.
 
3257
 
 
3258
The @option{-P} option means to not follow symbolic links: symbolic links
 
3259
are resolved while @code{cd} is traversing @var{directory} and before
 
3260
processing an instance of @samp{..} in @var{directory}.
 
3261
 
 
3262
By default, or when the @option{-L} option is supplied, symbolic links
 
3263
in @var{directory} are resolved after @code{cd} processes an instance
 
3264
of @samp{..} in @var{directory}.
 
3265
 
 
3266
If @samp{..} appears in @var{directory}, it is processed by removing the
 
3267
immediately preceding pathname component, back to a slash or the beginning
 
3268
of @var{directory}.
 
3269
 
 
3270
If the @option{-e} option is supplied with @option{-P}
 
3271
and the current working directory cannot be successfully determined
 
3272
after a successful directory change, @code{cd} will return an unsuccessful
 
3273
status.
 
3274
 
 
3275
On systems that support it, the @option{-@@} option presents the extended
 
3276
attributes associated with a file as a directory.              
 
3277
 
 
3278
If @var{directory} is @samp{-}, it is converted to @env{$OLDPWD}
 
3279
before the directory change is attempted.
 
3280
 
 
3281
If a non-empty directory name from @env{CDPATH} is used, or if
 
3282
@samp{-} is the first argument, and the directory change is
 
3283
successful, the absolute pathname of the new working directory is
 
3284
written to the standard output.
 
3285
 
 
3286
The return status is zero if the directory is successfully changed,
 
3287
non-zero otherwise.
 
3288
 
 
3289
@item continue
 
3290
@btindex continue
 
3291
@example
 
3292
continue [@var{n}]
 
3293
@end example
 
3294
 
 
3295
Resume the next iteration of an enclosing @code{for}, @code{while},
 
3296
@code{until}, or @code{select} loop.
 
3297
If @var{n} is supplied, the execution of the @var{n}th enclosing loop
 
3298
is resumed.
 
3299
@var{n} must be greater than or equal to 1.
 
3300
The return status is zero unless @var{n} is not greater than or equal to 1.
 
3301
 
 
3302
@item eval
 
3303
@btindex eval
 
3304
@example
 
3305
eval [@var{arguments}]
 
3306
@end example
 
3307
 
 
3308
The arguments are concatenated together into a single command, which is
 
3309
then read and executed, and its exit status returned as the exit status
 
3310
of @code{eval}.
 
3311
If there are no arguments or only empty arguments, the return status is
 
3312
zero.
 
3313
 
 
3314
@item exec
 
3315
@btindex exec
 
3316
@example
 
3317
exec [-cl] [-a @var{name}] [@var{command} [@var{arguments}]]
 
3318
@end example
 
3319
 
 
3320
If @var{command}
 
3321
is supplied, it replaces the shell without creating a new process.
 
3322
If the @option{-l} option is supplied, the shell places a dash at the
 
3323
beginning of the zeroth argument passed to @var{command}.
 
3324
This is what the @code{login} program does.
 
3325
The @option{-c} option causes @var{command} to be executed with an empty
 
3326
environment.
 
3327
If @option{-a} is supplied, the shell passes @var{name} as the zeroth
 
3328
argument to @var{command}.
 
3329
If @var{command}
 
3330
cannot be executed for some reason, a non-interactive shell exits,
 
3331
unless the @code{execfail} shell option
 
3332
is enabled.  In that case, it returns failure.
 
3333
An interactive shell returns failure if the file cannot be executed.
 
3334
If no @var{command} is specified, redirections may be used to affect
 
3335
the current shell environment.  If there are no redirection errors, the
 
3336
return status is zero; otherwise the return status is non-zero.
 
3337
 
 
3338
@item exit
 
3339
@btindex exit
 
3340
@example
 
3341
exit [@var{n}]
 
3342
@end example
 
3343
 
 
3344
Exit the shell, returning a status of @var{n} to the shell's parent.
 
3345
If @var{n} is omitted, the exit status is that of the last command executed.
 
3346
Any trap on @code{EXIT} is executed before the shell terminates.
 
3347
 
 
3348
@item export
 
3349
@btindex export
 
3350
@example
 
3351
export [-fn] [-p] [@var{name}[=@var{value}]]
 
3352
@end example
 
3353
 
 
3354
Mark each @var{name} to be passed to child processes
 
3355
in the environment.  If the @option{-f} option is supplied, the @var{name}s
 
3356
refer to shell functions; otherwise the names refer to shell variables.
 
3357
The @option{-n} option means to no longer mark each @var{name} for export.
 
3358
If no @var{names} are supplied, or if the @option{-p} option is given, a
 
3359
list of names of all exported variables is displayed.
 
3360
The @option{-p} option displays output in a form that may be reused as input.
 
3361
If a variable name is followed by =@var{value}, the value of
 
3362
the variable is set to @var{value}.
 
3363
 
 
3364
The return status is zero unless an invalid option is supplied, one of
 
3365
the names is not a valid shell variable name, or @option{-f} is supplied
 
3366
with a name that is not a shell function.
 
3367
 
 
3368
@item getopts
 
3369
@btindex getopts
 
3370
@example
 
3371
getopts @var{optstring} @var{name} [@var{args}]
 
3372
@end example
 
3373
 
 
3374
@code{getopts} is used by shell scripts to parse positional parameters.
 
3375
@var{optstring} contains the option characters to be recognized; if a
 
3376
character is followed by a colon, the option is expected to have an
 
3377
argument, which should be separated from it by whitespace.
 
3378
The colon (@samp{:}) and question mark (@samp{?}) may not be
 
3379
used as option characters.
 
3380
Each time it is invoked, @code{getopts}
 
3381
places the next option in the shell variable @var{name}, initializing
 
3382
@var{name} if it does not exist,
 
3383
and the index of the next argument to be processed into the
 
3384
variable @env{OPTIND}.
 
3385
@env{OPTIND} is initialized to 1 each time the shell or a shell script
 
3386
is invoked.
 
3387
When an option requires an argument,
 
3388
@code{getopts} places that argument into the variable @env{OPTARG}.
 
3389
The shell does not reset @env{OPTIND} automatically; it must be manually
 
3390
reset between multiple calls to @code{getopts} within the same shell
 
3391
invocation if a new set of parameters is to be used.
 
3392
 
 
3393
When the end of options is encountered, @code{getopts} exits with a
 
3394
return value greater than zero.
 
3395
@env{OPTIND} is set to the index of the first non-option argument,
 
3396
and @var{name} is set to @samp{?}.
 
3397
 
 
3398
@code{getopts}
 
3399
normally parses the positional parameters, but if more arguments are
 
3400
given in @var{args}, @code{getopts} parses those instead.
 
3401
 
 
3402
@code{getopts} can report errors in two ways.  If the first character of
 
3403
@var{optstring} is a colon, @var{silent}
 
3404
error reporting is used.  In normal operation, diagnostic messages
 
3405
are printed when invalid options or missing option arguments are
 
3406
encountered.
 
3407
If the variable @env{OPTERR}
 
3408
is set to 0, no error messages will be displayed, even if the first
 
3409
character of @code{optstring} is not a colon.
 
3410
 
 
3411
If an invalid option is seen,
 
3412
@code{getopts} places @samp{?} into @var{name} and, if not silent,
 
3413
prints an error message and unsets @env{OPTARG}.
 
3414
If @code{getopts} is silent, the option character found is placed in
 
3415
@env{OPTARG} and no diagnostic message is printed.
 
3416
 
 
3417
If a required argument is not found, and @code{getopts}
 
3418
is not silent, a question mark (@samp{?}) is placed in @var{name},
 
3419
@code{OPTARG} is unset, and a diagnostic message is printed.
 
3420
If @code{getopts} is silent, then a colon (@samp{:}) is placed in
 
3421
@var{name} and @env{OPTARG} is set to the option character found.
 
3422
 
 
3423
@item hash
 
3424
@btindex hash
 
3425
@example
 
3426
hash [-r] [-p @var{filename}] [-dt] [@var{name}]
 
3427
@end example
 
3428
 
 
3429
Each time @code{hash} is invoked, it remembers the full pathnames of the
 
3430
commands specified as @var{name} arguments,
 
3431
so they need not be searched for on subsequent invocations.
 
3432
The commands are found by searching through the directories listed in
 
3433
@env{$PATH}.
 
3434
Any previously-remembered pathname is discarded.
 
3435
The @option{-p} option inhibits the path search, and @var{filename} is
 
3436
used as the location of @var{name}.
 
3437
The @option{-r} option causes the shell to forget all remembered locations.
 
3438
The @option{-d} option causes the shell to forget the remembered location
 
3439
of each @var{name}.
 
3440
If the @option{-t} option is supplied, the full pathname to which each
 
3441
@var{name} corresponds is printed.  If multiple @var{name} arguments are
 
3442
supplied with @option{-t} the @var{name} is printed before the hashed
 
3443
full pathname.
 
3444
The @option{-l} option causes output to be displayed in a format
 
3445
that may be reused as input.
 
3446
If no arguments are given, or if only @option{-l} is supplied,
 
3447
information about remembered commands is printed.
 
3448
The return status is zero unless a @var{name} is not found or an invalid
 
3449
option is supplied.
 
3450
 
 
3451
@item pwd
 
3452
@btindex pwd
 
3453
@example
 
3454
pwd [-LP]
 
3455
@end example
 
3456
 
 
3457
Print the absolute pathname of the current working directory.
 
3458
If the @option{-P} option is supplied, the pathname printed will not
 
3459
contain symbolic links.
 
3460
If the @option{-L} option is supplied, the pathname printed may contain
 
3461
symbolic links.
 
3462
The return status is zero unless an error is encountered while
 
3463
determining the name of the current directory or an invalid option
 
3464
is supplied.
 
3465
 
 
3466
@item readonly
 
3467
@btindex readonly
 
3468
@example
 
3469
readonly [-aAf] [-p] [@var{name}[=@var{value}]] @dots{}
 
3470
@end example
 
3471
 
 
3472
Mark each @var{name} as readonly.
 
3473
The values of these names may not be changed by subsequent assignment.
 
3474
If the @option{-f} option is supplied, each @var{name} refers to a shell
 
3475
function.
 
3476
The @option{-a} option means each @var{name} refers to an indexed
 
3477
array variable; the @option{-A} option means each @var{name} refers
 
3478
to an associative array variable.
 
3479
If both options are supplied, @option{-A} takes precedence.
 
3480
If no @var{name} arguments are given, or if the @option{-p}
 
3481
option is supplied, a list of all readonly names is printed.
 
3482
The other options may be used to restrict the output to a subset of
 
3483
the set of readonly names.
 
3484
The @option{-p} option causes output to be displayed in a format that
 
3485
may be reused as input.
 
3486
If a variable name is followed by =@var{value}, the value of
 
3487
the variable is set to @var{value}.
 
3488
The return status is zero unless an invalid option is supplied, one of
 
3489
the @var{name} arguments is not a valid shell variable or function name,
 
3490
or the @option{-f} option is supplied with a name that is not a shell function.
 
3491
 
 
3492
@item return
 
3493
@btindex return
 
3494
@example
 
3495
return [@var{n}]
 
3496
@end example
 
3497
 
 
3498
Cause a shell function to stop executing and return the value @var{n}
 
3499
to its caller.
 
3500
If @var{n} is not supplied, the return value is the exit status of the
 
3501
last command executed in the function.
 
3502
@code{return} may also be used to terminate execution of a script
 
3503
being executed with the @code{.} (@code{source}) builtin,
 
3504
returning either @var{n} or
 
3505
the exit status of the last command executed within the script as the exit
 
3506
status of the script.
 
3507
If @var{n} is supplied, the return value is its least significant
 
3508
8 bits.
 
3509
Any command associated with the @code{RETURN} trap is executed
 
3510
before execution resumes after the function or script.
 
3511
The return status is non-zero if @code{return} is supplied a non-numeric
 
3512
argument or is used outside a function
 
3513
and not during the execution of a script by @code{.} or @code{source}.
 
3514
 
 
3515
@item shift
 
3516
@btindex shift
 
3517
@example
 
3518
shift [@var{n}]
 
3519
@end example
 
3520
 
 
3521
Shift the positional parameters to the left by @var{n}.
 
3522
The positional parameters from @var{n}+1 @dots{} @code{$#} are
 
3523
renamed to @code{$1} @dots{} @code{$#}-@var{n}.
 
3524
Parameters represented by the numbers @code{$#} to @code{$#}-@var{n}+1
 
3525
are unset.
 
3526
@var{n} must be a non-negative number less than or equal to @code{$#}.
 
3527
If @var{n} is zero or greater than @code{$#}, the positional parameters
 
3528
are not changed.
 
3529
If @var{n} is not supplied, it is assumed to be 1.
 
3530
The return status is zero unless @var{n} is greater than @code{$#} or
 
3531
less than zero, non-zero otherwise.
 
3532
 
 
3533
@item test
 
3534
@itemx [
 
3535
@btindex test
 
3536
@btindex [
 
3537
@example
 
3538
test @var{expr}
 
3539
@end example
 
3540
 
 
3541
Evaluate a conditional express
 
3542
ion @var{expr} and return a status of 0
 
3543
(true) or 1 (false).
 
3544
Each operator and operand must be a separate argument.
 
3545
Expressions are composed of the primaries described below in
 
3546
@ref{Bash Conditional Expressions}.
 
3547
@code{test} does not accept any options, nor does it accept and ignore
 
3548
an argument of @option{--} as signifying the end of options.
 
3549
 
 
3550
When the @code{[} form is used, the last argument to the command must
 
3551
be a @code{]}.
 
3552
 
 
3553
Expressions may be combined using the following operators, listed in
 
3554
decreasing order of precedence.
 
3555
The evaluation depends on the number of arguments; see below.
 
3556
Operator precedence is used when there are five or more arguments.
 
3557
 
 
3558
@table @code
 
3559
@item ! @var{expr}
 
3560
True if @var{expr} is false.
 
3561
 
 
3562
@item ( @var{expr} )
 
3563
Returns the value of @var{expr}.
 
3564
This may be used to override the normal precedence of operators.
 
3565
 
 
3566
@item @var{expr1} -a @var{expr2}
 
3567
True if both @var{expr1} and @var{expr2} are true.
 
3568
 
 
3569
@item @var{expr1} -o @var{expr2}
 
3570
True if either @var{expr1} or @var{expr2} is true.
 
3571
@end table
 
3572
 
 
3573
The @code{test} and @code{[} builtins evaluate conditional
 
3574
expressions using a set of rules based on the number of arguments.
 
3575
 
 
3576
@table @asis
 
3577
@item 0 arguments
 
3578
The expression is false.
 
3579
 
 
3580
@item 1 argument
 
3581
The expression is true if and only if the argument is not null.
 
3582
 
 
3583
@item 2 arguments
 
3584
If the first argument is @samp{!}, the expression is true if and
 
3585
only if the second argument is null.
 
3586
If the first argument is one of the unary conditional operators
 
3587
(@pxref{Bash Conditional Expressions}), the expression
 
3588
is true if the unary test is true.
 
3589
If the first argument is not a valid unary operator, the expression is
 
3590
false.
 
3591
 
 
3592
@item 3 arguments
 
3593
The following conditions are applied in the order listed.
 
3594
If the second argument is one of the binary conditional
 
3595
operators (@pxref{Bash Conditional Expressions}), the
 
3596
result of the expression is the result of the binary test using the
 
3597
first and third arguments as operands.
 
3598
The @samp{-a} and @samp{-o} operators are considered binary operators
 
3599
when there are three arguments.
 
3600
If the first argument is @samp{!}, the value is the negation of
 
3601
the two-argument test using the second and third arguments.
 
3602
If the first argument is exactly @samp{(} and the third argument is
 
3603
exactly @samp{)}, the result is the one-argument test of the second
 
3604
argument.
 
3605
Otherwise, the expression is false.
 
3606
 
 
3607
@item 4 arguments
 
3608
If the first argument is @samp{!}, the result is the negation of
 
3609
the three-argument expression composed of the remaining arguments.
 
3610
Otherwise, the expression is parsed and evaluated according to 
 
3611
precedence using the rules listed above.
 
3612
 
 
3613
@item 5 or more arguments
 
3614
The expression is parsed and evaluated according to precedence
 
3615
using the rules listed above.
 
3616
@end table
 
3617
 
 
3618
When used with @code{test} or @samp{[}, the @samp{<} and @samp{>}
 
3619
operators sort lexicographically using ASCII ordering.
 
3620
 
 
3621
@item times
 
3622
@btindex times
 
3623
@example
 
3624
times
 
3625
@end example
 
3626
 
 
3627
Print out the user and system times used by the shell and its children.
 
3628
The return status is zero.
 
3629
 
 
3630
@item trap
 
3631
@btindex trap
 
3632
@example
 
3633
trap [-lp] [@var{arg}] [@var{sigspec} @dots{}]
 
3634
@end example
 
3635
 
 
3636
The commands in @var{arg} are to be read and executed when the
 
3637
shell receives signal @var{sigspec}.  If @var{arg} is absent (and
 
3638
there is a single @var{sigspec}) or
 
3639
equal to @samp{-}, each specified signal's disposition is reset
 
3640
to the value it had when the shell was started.
 
3641
If @var{arg} is the null string, then the signal specified by
 
3642
each @var{sigspec} is ignored by the shell and commands it invokes.
 
3643
If @var{arg} is not present and @option{-p} has been supplied,
 
3644
the shell displays the trap commands associated with each @var{sigspec}.
 
3645
If no arguments are supplied, or
 
3646
only @option{-p} is given, @code{trap} prints the list of commands
 
3647
associated with each signal number in a form that may be reused as
 
3648
shell input.
 
3649
The @option{-l} option causes the shell to print a list of signal names
 
3650
and their corresponding numbers.
 
3651
Each @var{sigspec} is either a signal name or a signal number.
 
3652
Signal names are case insensitive and the @code{SIG} prefix is optional.
 
3653
 
 
3654
If a @var{sigspec}
 
3655
is @code{0} or @code{EXIT}, @var{arg} is executed when the shell exits.
 
3656
If a @var{sigspec} is @code{DEBUG}, the command @var{arg} is executed
 
3657
before every simple command, @code{for} command, @code{case} command,
 
3658
@code{select} command, every arithmetic @code{for} command, and before
 
3659
the first command executes in a shell function.
 
3660
Refer to the description of the @code{extdebug} option to the
 
3661
@code{shopt} builtin (@pxref{The Shopt Builtin}) for details of its
 
3662
effect on the @code{DEBUG} trap.
 
3663
If a @var{sigspec} is @code{RETURN}, the command @var{arg} is executed
 
3664
each time a shell function or a script executed with the @code{.} or
 
3665
@code{source} builtins finishes executing.
 
3666
 
 
3667
If a @var{sigspec} is @code{ERR}, the command @var{arg} 
 
3668
is executed whenever
 
3669
a pipeline (which may consist of a single simple
 
3670
command), a list, or a compound command returns a 
 
3671
non-zero exit status,
 
3672
subject to the following conditions.
 
3673
The @code{ERR} trap is not executed if the failed command is part of the
 
3674
command list immediately following an @code{until} or @code{while} keyword,
 
3675
part of the test following the @code{if} or @code{elif} reserved words,
 
3676
part of a command executed in a @code{&&} or @code{||} list
 
3677
except the command following the final @code{&&} or @code{||},
 
3678
any command in a pipeline but the last,
 
3679
or if the command's return
 
3680
status is being inverted using @code{!}.
 
3681
These are the same conditions obeyed by the @code{errexit} (@option{-e})
 
3682
option.
 
3683
 
 
3684
Signals ignored upon entry to the shell cannot be trapped or reset.
 
3685
Trapped signals that are not being ignored are reset to their original
 
3686
values in a subshell or subshell environment when one is created.
 
3687
 
 
3688
The return status is zero unless a @var{sigspec} does not specify a
 
3689
valid signal.
 
3690
 
 
3691
@item umask
 
3692
@btindex umask
 
3693
@example
 
3694
umask [-p] [-S] [@var{mode}]
 
3695
@end example
 
3696
 
 
3697
Set the shell process's file creation mask to @var{mode}.  If
 
3698
@var{mode} begins with a digit, it is interpreted as an octal number;
 
3699
if not, it is interpreted as a symbolic mode mask similar
 
3700
to that accepted by the @code{chmod} command.  If @var{mode} is
 
3701
omitted, the current value of the mask is printed.  If the @option{-S}
 
3702
option is supplied without a @var{mode} argument, the mask is printed
 
3703
in a symbolic format.
 
3704
If the  @option{-p} option is supplied, and @var{mode}
 
3705
is omitted, the output is in a form that may be reused as input.
 
3706
The return status is zero if the mode is successfully changed or if
 
3707
no @var{mode} argument is supplied, and non-zero otherwise.
 
3708
 
 
3709
Note that when the mode is interpreted as an octal number, each number
 
3710
of the umask is subtracted from @code{7}.  Thus, a umask of @code{022}
 
3711
results in permissions of @code{755}.
 
3712
 
 
3713
@item unset
 
3714
@btindex unset
 
3715
@example
 
3716
unset [-fnv] [@var{name}]
 
3717
@end example
 
3718
 
 
3719
Remove each variable or function @var{name}.
 
3720
If the @option{-v} option is given, each
 
3721
@var{name} refers to a shell variable and that variable is remvoved.
 
3722
If the @option{-f} option is given, the @var{name}s refer to shell
 
3723
functions, and the function definition is removed.
 
3724
If the @option{-n} option is supplied, and @var{name} is a variable with
 
3725
the @var{nameref} attribute, @var{name} will be unset rather than the
 
3726
variable it references.
 
3727
@option{-n} has no effect if the @option{-f} option is supplied.
 
3728
If no options are supplied, each @var{name} refers to a variable; if
 
3729
there is no variable by that name, any function with that name is
 
3730
unset.
 
3731
Readonly variables and functions may not be unset.
 
3732
The return status is zero unless a @var{name} is readonly.
 
3733
@end table
 
3734
 
 
3735
@node Bash Builtins
 
3736
@section Bash Builtin Commands
 
3737
 
 
3738
This section describes builtin commands which are unique to
 
3739
or have been extended in Bash.
 
3740
Some of these commands are specified in the @sc{posix} standard.
 
3741
 
 
3742
@table @code
 
3743
 
 
3744
@item alias
 
3745
@btindex alias
 
3746
@example
 
3747
alias [-p] [@var{name}[=@var{value}] @dots{}]
 
3748
@end example
 
3749
 
 
3750
Without arguments or with the @option{-p} option, @code{alias} prints
 
3751
the list of aliases on the standard output in a form that allows
 
3752
them to be reused as input.
 
3753
If arguments are supplied, an alias is defined for each @var{name}
 
3754
whose @var{value} is given.  If no @var{value} is given, the name
 
3755
and value of the alias is printed.
 
3756
Aliases are described in @ref{Aliases}.
 
3757
 
 
3758
@item bind
 
3759
@btindex bind
 
3760
@example
 
3761
bind [-m @var{keymap}] [-lpsvPSVX]
 
3762
bind [-m @var{keymap}] [-q @var{function}] [-u @var{function}] [-r @var{keyseq}]
 
3763
bind [-m @var{keymap}] -f @var{filename}
 
3764
bind [-m @var{keymap}] -x @var{keyseq:shell-command}
 
3765
bind [-m @var{keymap}] @var{keyseq:function-name}
 
3766
bind @var{readline-command}
 
3767
@end example
 
3768
 
 
3769
Display current Readline (@pxref{Command Line Editing})
 
3770
key and function bindings,
 
3771
bind a key sequence to a Readline function or macro,
 
3772
or set a Readline variable.
 
3773
Each non-option argument is a command as it would appear in a
 
3774
Readline initialization file (@pxref{Readline Init File}),
 
3775
but each binding or command must be passed as a separate argument;  e.g.,
 
3776
@samp{"\C-x\C-r":re-read-init-file}.
 
3777
 
 
3778
Options, if supplied, have the following meanings:
 
3779
 
 
3780
@table @code
 
3781
@item -m @var{keymap}
 
3782
Use @var{keymap} as the keymap to be affected by
 
3783
the subsequent bindings.  Acceptable @var{keymap}
 
3784
names are
 
3785
@code{emacs},
 
3786
@code{emacs-standard},
 
3787
@code{emacs-meta},
 
3788
@code{emacs-ctlx},
 
3789
@code{vi},
 
3790
@code{vi-move},
 
3791
@code{vi-command}, and
 
3792
@code{vi-insert}.
 
3793
@code{vi} is equivalent to @code{vi-command};
 
3794
@code{emacs} is equivalent to @code{emacs-standard}.
 
3795
 
 
3796
@item -l
 
3797
List the names of all Readline functions.
 
3798
 
 
3799
@item -p
 
3800
Display Readline function names and bindings in such a way that they
 
3801
can be used as input or in a Readline initialization file.
 
3802
 
 
3803
@item -P
 
3804
List current Readline function names and bindings.
 
3805
 
 
3806
@item -v
 
3807
Display Readline variable names and values in such a way that they
 
3808
can be used as input or in a Readline initialization file.
 
3809
 
 
3810
@item -V
 
3811
List current Readline variable names and values.
 
3812
 
 
3813
@item -s
 
3814
Display Readline key sequences bound to macros and the strings they output
 
3815
in such a way that they can be used as input or in a Readline
 
3816
initialization file.
 
3817
 
 
3818
@item -S
 
3819
Display Readline key sequences bound to macros and the strings they output.
 
3820
 
 
3821
@item -f @var{filename}
 
3822
Read key bindings from @var{filename}.
 
3823
 
 
3824
@item -q @var{function}
 
3825
Query about which keys invoke the named @var{function}.
 
3826
 
 
3827
@item -u @var{function}
 
3828
Unbind all keys bound to the named @var{function}.
 
3829
 
 
3830
@item -r @var{keyseq}
 
3831
Remove any current binding for @var{keyseq}.
 
3832
 
 
3833
@item -x @var{keyseq:shell-command}
 
3834
Cause @var{shell-command} to be executed whenever @var{keyseq} is
 
3835
entered.
 
3836
When @var{shell-command} is executed, the shell sets the
 
3837
@code{READLINE_LINE} variable to the contents of the Readline line
 
3838
buffer and the @code{READLINE_POINT} variable to the current location
 
3839
of the insertion point.
 
3840
If the executed command changes the value of @code{READLINE_LINE} or
 
3841
@code{READLINE_POINT}, those new values will be reflected in the
 
3842
editing state.
 
3843
 
 
3844
@item -X
 
3845
List all key sequences bound to shell commands and the associated commands
 
3846
in a format that can be reused as input.
 
3847
@end table
 
3848
 
 
3849
@noindent
 
3850
The return status is zero unless an invalid option is supplied or an
 
3851
error occurs.
 
3852
 
 
3853
@item builtin
 
3854
@btindex builtin
 
3855
@example
 
3856
builtin [@var{shell-builtin} [@var{args}]]
 
3857
@end example
 
3858
 
 
3859
Run a shell builtin, passing it @var{args}, and return its exit status.
 
3860
This is useful when defining a shell function with the same
 
3861
name as a shell builtin, retaining the functionality of the builtin within
 
3862
the function.
 
3863
The return status is non-zero if @var{shell-builtin} is not a shell
 
3864
builtin command.
 
3865
 
 
3866
@item caller
 
3867
@btindex caller
 
3868
@example
 
3869
caller [@var{expr}]
 
3870
@end example
 
3871
 
 
3872
Returns the context of any active subroutine call (a shell function or
 
3873
a script executed with the @code{.} or @code{source} builtins).
 
3874
 
 
3875
Without @var{expr}, @code{caller} displays the line number and source
 
3876
filename of the current subroutine call.
 
3877
If a non-negative integer is supplied as @var{expr}, @code{caller} 
 
3878
displays the line number, subroutine name, and source file corresponding
 
3879
to that position in the current execution call stack.  This extra
 
3880
information may be used, for example, to print a stack trace.  The
 
3881
current frame is frame 0.
 
3882
 
 
3883
The return value is 0 unless the shell is not executing a subroutine
 
3884
call or @var{expr} does not correspond to a valid position in the
 
3885
call stack.
 
3886
 
 
3887
@item command
 
3888
@btindex command
 
3889
@example
 
3890
command [-pVv] @var{command} [@var{arguments} @dots{}]
 
3891
@end example
 
3892
 
 
3893
Runs @var{command} with @var{arguments} ignoring any shell function
 
3894
named @var{command}.
 
3895
Only shell builtin commands or commands found by searching the
 
3896
@env{PATH} are executed.
 
3897
If there is a shell function named @code{ls}, running @samp{command ls}
 
3898
within the function will execute the external command @code{ls}
 
3899
instead of calling the function recursively.
 
3900
The @option{-p} option means to use a default value for @env{PATH}
 
3901
that is guaranteed to find all of the standard utilities.
 
3902
The return status in this case is 127 if @var{command} cannot be
 
3903
found or an error occurred, and the exit status of @var{command}
 
3904
otherwise.
 
3905
 
 
3906
If either the @option{-V} or @option{-v} option is supplied, a
 
3907
description of @var{command} is printed.  The @option{-v} option
 
3908
causes a single word indicating the command or file name used to
 
3909
invoke @var{command} to be displayed; the @option{-V} option produces
 
3910
a more verbose description.  In this case, the return status is
 
3911
zero if @var{command} is found, and non-zero if not.
 
3912
 
 
3913
@item declare
 
3914
@btindex declare
 
3915
@example
 
3916
declare [-aAfFgilnrtux] [-p] [@var{name}[=@var{value}] @dots{}]
 
3917
@end example
 
3918
 
 
3919
Declare variables and give them attributes.  If no @var{name}s
 
3920
are given, then display the values of variables instead. 
 
3921
 
 
3922
The @option{-p} option will display the attributes and values of each
 
3923
@var{name}.
 
3924
When @option{-p} is used with @var{name} arguments, additional options,
 
3925
other than @option{-f} and @option{-F}, are ignored.
 
3926
 
 
3927
When @option{-p} is supplied without @var{name} arguments, @code{declare}
 
3928
will display the attributes and values of all variables having the
 
3929
attributes specified by the additional options.
 
3930
If no other options are supplied with @option{-p}, @code{declare} will
 
3931
display the attributes and values of all shell variables.  The @option{-f}
 
3932
option will restrict the display to shell functions.
 
3933
 
 
3934
The @option{-F} option inhibits the display of function definitions;
 
3935
only the function name and attributes are printed.
 
3936
If the @code{extdebug} shell option is enabled using @code{shopt}
 
3937
(@pxref{The Shopt Builtin}), the source file name and line number where
 
3938
the function is defined are displayed as well.
 
3939
@option{-F} implies @option{-f}.
 
3940
 
 
3941
The @option{-g} option forces variables to be created or modified at
 
3942
the global scope, even when @code{declare} is executed in a shell function.
 
3943
It is ignored in all other cases.
 
3944
 
 
3945
The following options can be used to restrict output to variables with
 
3946
the specified attributes or to give variables attributes:
 
3947
 
 
3948
@table @code
 
3949
@item -a
 
3950
Each @var{name} is an indexed array variable (@pxref{Arrays}).
 
3951
 
 
3952
@item -A
 
3953
Each @var{name} is an associative array variable (@pxref{Arrays}).
 
3954
 
 
3955
@item -f
 
3956
Use function names only.
 
3957
 
 
3958
@item -i
 
3959
The variable is to be treated as
 
3960
an integer; arithmetic evaluation (@pxref{Shell Arithmetic}) is
 
3961
performed when the variable is assigned a value.
 
3962
 
 
3963
@item -l
 
3964
When the variable is assigned a value, all upper-case characters are
 
3965
converted to lower-case.
 
3966
The upper-case attribute is disabled.
 
3967
 
 
3968
@item -n
 
3969
Give each @var{name} the @var{nameref} attribute, making
 
3970
it a name reference to another variable.
 
3971
That other variable is defined by the value of @var{name}.
 
3972
All references and assignments to @var{name}, except for changing the
 
3973
@option{-n} attribute itself, are performed on the variable referenced by
 
3974
@var{name}'s value.
 
3975
The @option{-n} attribute cannot be applied to array variables.
 
3976
 
 
3977
@item -r
 
3978
Make @var{name}s readonly.  These names cannot then be assigned values
 
3979
by subsequent assignment statements or unset.
 
3980
 
 
3981
@item -t
 
3982
Give each @var{name} the @code{trace} attribute.
 
3983
Traced functions inherit the @code{DEBUG} and @code{RETURN} traps from
 
3984
the calling shell.
 
3985
The trace attribute has no special meaning for variables.
 
3986
 
 
3987
@item -u
 
3988
When the variable is assigned a value, all lower-case characters are
 
3989
converted to upper-case.
 
3990
The lower-case attribute is disabled.
 
3991
 
 
3992
@item -x
 
3993
Mark each @var{name} for export to subsequent commands via
 
3994
the environment.
 
3995
@end table
 
3996
 
 
3997
Using @samp{+} instead of @samp{-} turns off the attribute instead,
 
3998
with the exceptions that @samp{+a}
 
3999
may not be used to destroy an array variable and @samp{+r} will not
 
4000
remove the readonly attribute.
 
4001
When used in a function, @code{declare} makes each @var{name} local,
 
4002
as with the @code{local} command, unless the @option{-g} option is used.
 
4003
If a variable name is followed by =@var{value}, the value of the variable
 
4004
is set to @var{value}.
 
4005
 
 
4006
When using @option{-a} or @option{-A} and the compound assignment syntax to 
 
4007
create array variables, additional attributes do not take effect until
 
4008
subsequent assignments.
 
4009
 
 
4010
The return status is zero unless an invalid option is encountered,
 
4011
an attempt is made to define a function using @samp{-f foo=bar},
 
4012
an attempt is made to assign a value to a readonly variable,
 
4013
an attempt is made to assign a value to an array variable without
 
4014
using the compound assignment syntax (@pxref{Arrays}),
 
4015
one of the @var{names} is not a valid shell variable name,
 
4016
an attempt is made to turn off readonly status for a readonly variable,
 
4017
an attempt is made to turn off array status for an array variable,
 
4018
or an attempt is made to display a non-existent function with @option{-f}.
 
4019
 
 
4020
@item echo
 
4021
@btindex echo
 
4022
@example
 
4023
echo [-neE] [@var{arg} @dots{}]
 
4024
@end example
 
4025
 
 
4026
Output the @var{arg}s, separated by spaces, terminated with a
 
4027
newline.
 
4028
The return status is 0 unless a write error occurs.
 
4029
If @option{-n} is specified, the trailing newline is suppressed.
 
4030
If the @option{-e} option is given, interpretation of the following
 
4031
backslash-escaped characters is enabled.
 
4032
The @option{-E} option disables the interpretation of these escape characters,
 
4033
even on systems where they are interpreted by default.
 
4034
The @code{xpg_echo} shell option may be used to
 
4035
dynamically determine whether or not @code{echo} expands these
 
4036
escape characters by default.
 
4037
@code{echo} does not interpret @option{--} to mean the end of options.
 
4038
 
 
4039
@code{echo} interprets the following escape sequences:
 
4040
@table @code
 
4041
@item \a
 
4042
alert (bell)
 
4043
@item \b
 
4044
backspace
 
4045
@item \c
 
4046
suppress further output
 
4047
@item \e
 
4048
@itemx \E
 
4049
escape
 
4050
@item \f
 
4051
form feed
 
4052
@item \n
 
4053
new line
 
4054
@item \r
 
4055
carriage return
 
4056
@item \t 
 
4057
horizontal tab
 
4058
@item \v
 
4059
vertical tab
 
4060
@item \\
 
4061
backslash
 
4062
@item \0@var{nnn}
 
4063
the eight-bit character whose value is the octal value @var{nnn}
 
4064
(zero to three octal digits)
 
4065
@item \x@var{HH}
 
4066
the eight-bit character whose value is the hexadecimal value @var{HH}
 
4067
(one or two hex digits)
 
4068
@item \u@var{HHHH}
 
4069
the Unicode (ISO/IEC 10646) character whose value is the hexadecimal value
 
4070
@var{HHHH} (one to four hex digits)
 
4071
@item \U@var{HHHHHHHH}
 
4072
the Unicode (ISO/IEC 10646) character whose value is the hexadecimal value
 
4073
@var{HHHHHHHH} (one to eight hex digits)
 
4074
@end table
 
4075
 
 
4076
@item enable
 
4077
@btindex enable
 
4078
@example
 
4079
enable [-a] [-dnps] [-f @var{filename}] [@var{name} @dots{}]
 
4080
@end example
 
4081
 
 
4082
Enable and disable builtin shell commands.
 
4083
Disabling a builtin allows a disk command which has the same name
 
4084
as a shell builtin to be executed without specifying a full pathname,
 
4085
even though the shell normally searches for builtins before disk commands.
 
4086
If @option{-n} is used, the @var{name}s become disabled.  Otherwise
 
4087
@var{name}s are enabled.  For example, to use the @code{test} binary
 
4088
found via @env{$PATH} instead of the shell builtin version, type
 
4089
@samp{enable -n test}.
 
4090
 
 
4091
If the @option{-p} option is supplied, or no @var{name} arguments appear,
 
4092
a list of shell builtins is printed.  With no other arguments, the list
 
4093
consists of all enabled shell builtins.
 
4094
The @option{-a} option means to list
 
4095
each builtin with an indication of whether or not it is enabled. 
 
4096
 
 
4097
The @option{-f} option means to load the new builtin command @var{name}
 
4098
from shared object @var{filename}, on systems that support dynamic loading.
 
4099
The @option{-d} option will delete a builtin loaded with @option{-f}.
 
4100
 
 
4101
If there are no options, a list of the shell builtins is displayed.
 
4102
The @option{-s} option restricts @code{enable} to the @sc{posix} special
 
4103
builtins.  If @option{-s} is used with @option{-f}, the new builtin becomes
 
4104
a special builtin (@pxref{Special Builtins}).
 
4105
 
 
4106
The return status is zero unless a @var{name} is not a shell builtin
 
4107
or there is an error loading a new builtin from a shared object.
 
4108
 
 
4109
@item help
 
4110
@btindex help
 
4111
@example
 
4112
help [-dms] [@var{pattern}]
 
4113
@end example
 
4114
 
 
4115
Display helpful information about builtin commands.
 
4116
If @var{pattern} is specified, @code{help} gives detailed help
 
4117
on all commands matching @var{pattern}, otherwise a list of
 
4118
the builtins is printed.
 
4119
 
 
4120
Options, if supplied, have the following meanings:
 
4121
 
 
4122
@table @code
 
4123
@item -d
 
4124
Display a short description of each @var{pattern}
 
4125
@item -m
 
4126
Display the description of each @var{pattern} in a manpage-like format
 
4127
@item -s
 
4128
Display only a short usage synopsis for each @var{pattern}
 
4129
@end table
 
4130
 
 
4131
The return status is zero unless no command matches @var{pattern}.
 
4132
 
 
4133
@item let
 
4134
@btindex let
 
4135
@example
 
4136
let @var{expression} [@var{expression} @dots{}]
 
4137
@end example
 
4138
 
 
4139
The @code{let} builtin allows arithmetic to be performed on shell
 
4140
variables.  Each @var{expression} is evaluated according to the
 
4141
rules given below in @ref{Shell Arithmetic}.  If the
 
4142
last @var{expression} evaluates to 0, @code{let} returns 1;
 
4143
otherwise 0 is returned.
 
4144
 
 
4145
@item local
 
4146
@btindex local
 
4147
@example
 
4148
local [@var{option}] @var{name}[=@var{value}] @dots{}
 
4149
@end example
 
4150
 
 
4151
For each argument, a local variable named @var{name} is created,
 
4152
and assigned @var{value}.
 
4153
The @var{option} can be any of the options accepted by @code{declare}.
 
4154
@code{local} can only be used within a function; it makes the variable
 
4155
@var{name} have a visible scope restricted to that function and its
 
4156
children.  The return status is zero unless @code{local} is used outside
 
4157
a function, an invalid @var{name} is supplied, or @var{name} is a
 
4158
readonly variable.
 
4159
 
 
4160
@item logout
 
4161
@btindex logout
 
4162
@example
 
4163
logout [@var{n}]
 
4164
@end example
 
4165
 
 
4166
Exit a login shell, returning a status of @var{n} to the shell's
 
4167
parent.
 
4168
 
 
4169
@item mapfile
 
4170
@btindex mapfile
 
4171
@example
 
4172
mapfile [-n @var{count}] [-O @var{origin}] [-s @var{count}] [-t] [-u @var{fd}]
 
4173
    [-C @var{callback}] [-c @var{quantum}] [@var{array}]
 
4174
@end example
 
4175
 
 
4176
Read lines from the standard input into the indexed array variable @var{array},
 
4177
or from file descriptor @var{fd}
 
4178
if the @option{-u} option is supplied.
 
4179
The variable @code{MAPFILE} is the default @var{array}.
 
4180
Options, if supplied, have the following meanings:
 
4181
 
 
4182
@table @code
 
4183
 
 
4184
@item -n
 
4185
Copy at most @var{count} lines.  If @var{count} is 0, all lines are copied.
 
4186
@item -O
 
4187
Begin assigning to @var{array} at index @var{origin}.
 
4188
The default index is 0.
 
4189
@item -s
 
4190
Discard the first @var{count} lines read.
 
4191
@item -t
 
4192
Remove a trailing newline from each line read.
 
4193
@item -u
 
4194
Read lines from file descriptor @var{fd} instead of the standard input.
 
4195
@item -C
 
4196
Evaluate @var{callback} each time @var{quantum}P lines are read.
 
4197
The @option{-c} option specifies @var{quantum}.
 
4198
@item -c
 
4199
Specify the number of lines read between each call to @var{callback}.
 
4200
@end table
 
4201
 
 
4202
If @option{-C} is specified without @option{-c}, 
 
4203
the default quantum is 5000.
 
4204
When @var{callback}  is evaluated, it is supplied the index of the next
 
4205
array element to be assigned and the line to be assigned to that element
 
4206
as additional arguments.
 
4207
@var{callback} is evaluated after the line is read but before the 
 
4208
array element is assigned.
 
4209
 
 
4210
If not supplied with an explicit origin, @code{mapfile} will clear @var{array}
 
4211
before assigning to it.
 
4212
 
 
4213
@code{mapfile} returns successfully unless an invalid option or option
 
4214
argument is supplied, @var{array} is invalid or unassignable, or @var{array}
 
4215
is not an indexed array.
 
4216
 
 
4217
@item printf
 
4218
@btindex printf
 
4219
@example
 
4220
printf [-v @var{var}] @var{format} [@var{arguments}]
 
4221
@end example
 
4222
 
 
4223
Write the formatted @var{arguments} to the standard output under the
 
4224
control of the @var{format}.
 
4225
The @option{-v} option causes the output to be assigned to the variable
 
4226
@var{var} rather than being printed to the standard output.
 
4227
 
 
4228
The @var{format} is a character string which contains three types of objects:
 
4229
plain characters, which are simply copied to standard output, character
 
4230
escape sequences, which are converted and copied to the standard output, and
 
4231
format specifications, each of which causes printing of the next successive
 
4232
@var{argument}.
 
4233
In addition to the standard @code{printf(1)} formats, @code{printf}
 
4234
interprets the following extensions:
 
4235
 
 
4236
@table @code
 
4237
@item %b
 
4238
Causes @code{printf} to expand backslash escape sequences in the
 
4239
corresponding @var{argument},
 
4240
except that @samp{\c} terminates output, backslashes in
 
4241
@samp{\'}, @samp{\"}, and @samp{\?} are not removed, and octal escapes
 
4242
beginning with @samp{\0} may contain up to four digits.
 
4243
@item %q
 
4244
Causes @code{printf} to output the
 
4245
corresponding @var{argument} in a format that can be reused as shell input.
 
4246
@item %(@var{datefmt})T
 
4247
Causes @code{printf} to output the date-time string resulting from using
 
4248
@var{datefmt} as a format string for @code{strftime}(3).
 
4249
The corresponding @var{argument} is an integer representing the number of
 
4250
seconds since the epoch.
 
4251
Two special argument values may be used: -1 represents the current
 
4252
time, and -2 represents the time the shell was invoked.
 
4253
If no argument is specified, conversion behaves as if -1 had been given.
 
4254
This is an exception to the usual @code{printf} behavior.
 
4255
@end table
 
4256
 
 
4257
@noindent
 
4258
Arguments to non-string format specifiers are treated as C language constants,
 
4259
except that a leading plus or minus sign is allowed, and if the leading
 
4260
character is a single or double quote, the value is the ASCII value of
 
4261
the following character.
 
4262
 
 
4263
The @var{format} is reused as necessary to consume all of the @var{arguments}.
 
4264
If the @var{format} requires more @var{arguments} than are supplied, the
 
4265
extra format specifications behave as if a zero value or null string, as
 
4266
appropriate, had been supplied.  The return value is zero on success,
 
4267
non-zero on failure.
 
4268
 
 
4269
@item read
 
4270
@btindex read
 
4271
@example
 
4272
read [-ers] [-a @var{aname}] [-d @var{delim}] [-i @var{text}] [-n @var{nchars}]
 
4273
    [-N @var{nchars}] [-p @var{prompt}] [-t @var{timeout}] [-u @var{fd}] [@var{name} @dots{}]
 
4274
@end example
 
4275
 
 
4276
One line is read from the standard input, or from the file descriptor
 
4277
@var{fd} supplied as an argument to the @option{-u} option, and the first word
 
4278
is assigned to the first @var{name}, the second word to the second @var{name},
 
4279
and so on, with leftover words and their intervening separators assigned
 
4280
to the last @var{name}.
 
4281
If there are fewer words read from the input stream than names,
 
4282
the remaining names are assigned empty values.
 
4283
The characters in the value of the @env{IFS} variable
 
4284
are used to split the line into words using the same rules the shell
 
4285
uses for expansion (described above in @ref{Word Splitting}).
 
4286
The backslash character @samp{\} may be used to remove any special
 
4287
meaning for the next character read and for line continuation.
 
4288
If no names are supplied, the line read is assigned to the
 
4289
variable @env{REPLY}.
 
4290
The return code is zero, unless end-of-file is encountered, @code{read}
 
4291
times out (in which case the return code is greater than 128),
 
4292
a variable assignment error (such as assigning to a readonly variable) occurs,
 
4293
or an invalid file descriptor is supplied as the argument to @option{-u}.
 
4294
 
 
4295
Options, if supplied, have the following meanings:
 
4296
 
 
4297
@table @code
 
4298
@item -a @var{aname}
 
4299
The words are assigned to sequential indices of the array variable
 
4300
@var{aname}, starting at 0.
 
4301
All elements are removed from @var{aname} before the assignment.
 
4302
Other @var{name} arguments are ignored.
 
4303
 
 
4304
@item -d @var{delim}
 
4305
The first character of @var{delim} is used to terminate the input line,
 
4306
rather than newline.
 
4307
 
 
4308
@item -e
 
4309
Readline (@pxref{Command Line Editing}) is used to obtain the line.
 
4310
Readline uses the current (or default, if line editing was not previously
 
4311
active) editing settings.
 
4312
 
 
4313
@item -i @var{text}
 
4314
If Readline is being used to read the line, @var{text} is placed into
 
4315
the editing buffer before editing begins.
 
4316
 
 
4317
@item -n @var{nchars}
 
4318
@code{read} returns after reading @var{nchars} characters rather than
 
4319
waiting for a complete line of input, but honor a delimiter if fewer
 
4320
than @var{nchars} characters are read before the delimiter.
 
4321
 
 
4322
@item -N @var{nchars}
 
4323
@code{read} returns after reading exactly @var{nchars} characters rather
 
4324
than waiting for a complete line of input, unless EOF is encountered or
 
4325
@code{read} times out.
 
4326
Delimiter characters encountered in the input are
 
4327
not treated specially and do not cause @code{read} to return until
 
4328
@var{nchars} characters are read.
 
4329
 
 
4330
@item -p @var{prompt}
 
4331
Display @var{prompt}, without a trailing newline, before attempting
 
4332
to read any input.
 
4333
The prompt is displayed only if input is coming from a terminal.
 
4334
 
 
4335
@item -r
 
4336
If this option is given, backslash does not act as an escape character.
 
4337
The backslash is considered to be part of the line.
 
4338
In particular, a backslash-newline pair may not be used as a line
 
4339
continuation.
 
4340
 
 
4341
@item -s
 
4342
Silent mode.  If input is coming from a terminal, characters are
 
4343
not echoed.
 
4344
 
 
4345
@item -t @var{timeout}
 
4346
Cause @code{read} to time out and return failure if a complete line of
 
4347
input (or a specified number of characters)
 
4348
is not read within @var{timeout} seconds.
 
4349
@var{timeout}  may be a decimal number with a fractional portion following
 
4350
the decimal point.
 
4351
This option is only effective if @code{read} is reading input from a
 
4352
terminal, pipe, or other special file; it has no effect when reading
 
4353
from regular files.
 
4354
If @code{read} times out, @code{read} saves any partial input read into
 
4355
the specified variable @var{name}.
 
4356
If @var{timeout} is 0, @code{read} returns immediately, without trying to
 
4357
read and data.  The exit status is 0 if input is available on
 
4358
the specified file descriptor, non-zero otherwise.
 
4359
The exit status is greater than 128 if the timeout is exceeded.
 
4360
 
 
4361
@item -u @var{fd}
 
4362
Read input from file descriptor @var{fd}.
 
4363
@end table
 
4364
 
 
4365
@item readarray
 
4366
@btindex readarray
 
4367
@example
 
4368
readarray [-n @var{count}] [-O @var{origin}] [-s @var{count}] [-t] [-u @var{fd}]
 
4369
    [-C @var{callback}] [-c @var{quantum}] [@var{array}]
 
4370
@end example
 
4371
 
 
4372
Read lines from the standard input into the indexed array variable @var{array},
 
4373
or from file descriptor @var{fd}
 
4374
if the @option{-u} option is supplied.
 
4375
 
 
4376
A synonym for @code{mapfile}.
 
4377
 
 
4378
@item source
 
4379
@btindex source
 
4380
@example
 
4381
source @var{filename}
 
4382
@end example
 
4383
 
 
4384
A synonym for @code{.} (@pxref{Bourne Shell Builtins}).
 
4385
 
 
4386
@item type
 
4387
@btindex type
 
4388
@example
 
4389
type [-afptP] [@var{name} @dots{}]
 
4390
@end example
 
4391
 
 
4392
For each @var{name}, indicate how it would be interpreted if used as a
 
4393
command name.
 
4394
 
 
4395
If the @option{-t} option is used, @code{type} prints a single word
 
4396
which is one of @samp{alias}, @samp{function}, @samp{builtin},
 
4397
@samp{file} or @samp{keyword},
 
4398
if @var{name} is an alias, shell function, shell builtin,
 
4399
disk file, or shell reserved word, respectively.
 
4400
If the @var{name} is not found, then nothing is printed, and
 
4401
@code{type} returns a failure status.
 
4402
 
 
4403
If the @option{-p} option is used, @code{type} either returns the name
 
4404
of the disk file that would be executed, or nothing if @option{-t}
 
4405
would not return @samp{file}.
 
4406
 
 
4407
The @option{-P} option forces a path search for each @var{name}, even if
 
4408
@option{-t} would not return @samp{file}.
 
4409
 
 
4410
If a command is hashed, @option{-p} and @option{-P} print the hashed value,
 
4411
which is not necessarily the file that appears first in @code{$PATH}.
 
4412
 
 
4413
If the @option{-a} option is used, @code{type} returns all of the places
 
4414
that contain an executable named @var{file}.
 
4415
This includes aliases and functions, if and only if the @option{-p} option
 
4416
is not also used.
 
4417
 
 
4418
If the @option{-f} option is used, @code{type} does not attempt to find
 
4419
shell functions, as with the @code{command} builtin.
 
4420
 
 
4421
The return status is zero if all of the @var{names} are found, non-zero
 
4422
if any are not found.
 
4423
 
 
4424
@item typeset
 
4425
@btindex typeset
 
4426
@example
 
4427
typeset [-afFgrxilnrtux] [-p] [@var{name}[=@var{value}] @dots{}]
 
4428
@end example
 
4429
 
 
4430
The @code{typeset} command is supplied for compatibility with the Korn
 
4431
shell.
 
4432
It is a synonym for the @code{declare} builtin command.
 
4433
 
 
4434
@item ulimit
 
4435
@btindex ulimit
 
4436
@example
 
4437
ulimit [-abcdefilmnpqrstuvxHST] [@var{limit}]
 
4438
@end example
 
4439
 
 
4440
@code{ulimit} provides control over the resources available to processes
 
4441
started by the shell, on systems that allow such control.  If an
 
4442
option is given, it is interpreted as follows:
 
4443
 
 
4444
@table @code
 
4445
@item -S
 
4446
Change and report the soft limit associated with a resource.
 
4447
 
 
4448
@item -H
 
4449
Change and report the hard limit associated with a resource.
 
4450
 
 
4451
@item -a
 
4452
All current limits are reported.
 
4453
 
 
4454
@item -b
 
4455
The maximum socket buffer size.
 
4456
 
 
4457
@item -c
 
4458
The maximum size of core files created.
 
4459
 
 
4460
@item -d
 
4461
The maximum size of a process's data segment.
 
4462
 
 
4463
@item -e
 
4464
The maximum scheduling priority ("nice").
 
4465
 
 
4466
@item -f
 
4467
The maximum size of files written by the shell and its children.
 
4468
 
 
4469
@item -i
 
4470
The maximum number of pending signals.
 
4471
 
 
4472
@item -l
 
4473
The maximum size that may be locked into memory.
 
4474
 
 
4475
@item -m
 
4476
The maximum resident set size (many systems do not honor this limit).
 
4477
 
 
4478
@item -n
 
4479
The maximum number of open file descriptors (most systems do not
 
4480
allow this value to be set).
 
4481
 
 
4482
@item -p
 
4483
The pipe buffer size.
 
4484
 
 
4485
@item -q
 
4486
The maximum number of bytes in POSIX message queues.
 
4487
 
 
4488
@item -r
 
4489
The maximum real-time scheduling priority.
 
4490
 
 
4491
@item -s
 
4492
The maximum stack size.
 
4493
 
 
4494
@item -t
 
4495
The maximum amount of cpu time in seconds.
 
4496
 
 
4497
@item -u
 
4498
The maximum number of processes available to a single user.
 
4499
 
 
4500
@item -v
 
4501
The maximum amount of virtual memory available to the shell, and, on
 
4502
some systems, to its children.
 
4503
 
 
4504
@item -x
 
4505
The maximum number of file locks.
 
4506
 
 
4507
@item -T
 
4508
The maximum number of threads.
 
4509
@end table
 
4510
 
 
4511
If @var{limit} is given, and the @option{-a} option is not used,
 
4512
@var{limit} is the new value of the specified resource.
 
4513
The special @var{limit} values @code{hard}, @code{soft}, and
 
4514
@code{unlimited} stand for the current hard limit, the current soft limit,
 
4515
and no limit, respectively.
 
4516
A hard limit cannot be increased by a non-root user once it is set;
 
4517
a soft limit may be increased up to the value of the hard limit.
 
4518
Otherwise, the current value of the soft limit for the specified resource
 
4519
is printed, unless the @option{-H} option is supplied.
 
4520
When setting new limits, if neither @option{-H} nor @option{-S} is supplied,
 
4521
both the hard and soft limits are set.
 
4522
If no option is given, then @option{-f} is assumed.  Values are in 1024-byte
 
4523
increments, except for @option{-t}, which is in seconds; @option{-p},
 
4524
which is in units of 512-byte blocks; and @option{-T}, @option{-b},
 
4525
@option{-n} and @option{-u}, which are unscaled values.
 
4526
 
 
4527
The return status is zero unless an invalid option or argument is supplied,
 
4528
or an error occurs while setting a new limit.
 
4529
 
 
4530
@item unalias
 
4531
@btindex unalias
 
4532
@example
 
4533
unalias [-a] [@var{name} @dots{} ]
 
4534
@end example
 
4535
 
 
4536
Remove each @var{name} from the list of aliases.  If @option{-a} is
 
4537
supplied, all aliases are removed.
 
4538
Aliases are described in @ref{Aliases}.
 
4539
@end table
 
4540
 
 
4541
@node Modifying Shell Behavior
 
4542
@section Modifying Shell Behavior
 
4543
 
 
4544
@menu
 
4545
* The Set Builtin::             Change the values of shell attributes and
 
4546
                                positional parameters.
 
4547
* The Shopt Builtin::           Modify shell optional behavior.
 
4548
@end menu
 
4549
 
 
4550
@node The Set Builtin
 
4551
@subsection The Set Builtin
 
4552
 
 
4553
This builtin is so complicated that it deserves its own section.  @code{set}
 
4554
allows you to change the values of shell options and set the positional
 
4555
parameters, or to display the names and values of shell variables.
 
4556
 
 
4557
@table @code
 
4558
@item set
 
4559
@btindex set
 
4560
@example
 
4561
set [--abefhkmnptuvxBCEHPT] [-o @var{option-name}] [@var{argument} @dots{}]
 
4562
set [+abefhkmnptuvxBCEHPT] [+o @var{option-name}] [@var{argument} @dots{}]
 
4563
@end example
 
4564
 
 
4565
If no options or arguments are supplied, @code{set} displays the names
 
4566
and values of all shell variables and functions, sorted according to the
 
4567
current locale, in a format that may be reused as input
 
4568
for setting or resetting the currently-set variables.
 
4569
Read-only variables cannot be reset.
 
4570
In @sc{posix} mode, only shell variables are listed.
 
4571
 
 
4572
When options are supplied, they set or unset shell attributes.
 
4573
Options, if specified, have the following meanings:
 
4574
 
 
4575
@table @code
 
4576
@item -a
 
4577
Mark variables and function which are modified or created for export
 
4578
to the environment of subsequent commands.
 
4579
 
 
4580
@item -b
 
4581
Cause the status of terminated background jobs to be reported
 
4582
immediately, rather than before printing the next primary prompt.
 
4583
 
 
4584
@item -e
 
4585
Exit immediately if
 
4586
a pipeline (@pxref{Pipelines}), which may consist of a single simple command
 
4587
(@pxref{Simple Commands}),
 
4588
a list (@pxref{Lists}),
 
4589
or a compound command (@pxref{Compound Commands})
 
4590
returns a non-zero status.
 
4591
The shell does not exit if the command that fails is part of the
 
4592
command list immediately following a @code{while} or @code{until} keyword,
 
4593
part of the test in an @code{if} statement,
 
4594
part of any command executed in a @code{&&} or @code{||} list except
 
4595
the command following the final @code{&&} or @code{||},
 
4596
any command in a pipeline but the last,
 
4597
or if the command's return status is being inverted with @code{!}.
 
4598
If a compound command other than a subshell
 
4599
returns a non-zero status because a command failed
 
4600
while @option{-e} was being ignored, the shell does not exit.
 
4601
A trap on @code{ERR}, if set, is executed before the shell exits.
 
4602
 
 
4603
This option applies to the shell environment and each subshell environment
 
4604
separately (@pxref{Command Execution Environment}), and may cause
 
4605
subshells to exit before executing all the commands in the subshell.
 
4606
 
 
4607
If a compound command or shell function executes in a context where
 
4608
@option{-e} is being ignored,
 
4609
none of the commands executed within the compound command or function body
 
4610
will be affected by the @option{-e} setting, even if @option{-e} is set
 
4611
and a command returns a failure status.
 
4612
If a compound command or shell function sets @option{-e} while executing in
 
4613
a context where @option{-e} is ignored, that setting will not have any
 
4614
effect until the compound command or the command containing the function
 
4615
call completes.
 
4616
 
 
4617
@item -f
 
4618
Disable filename expansion (globbing).
 
4619
 
 
4620
@item -h
 
4621
Locate and remember (hash) commands as they are looked up for execution.
 
4622
This option is enabled by default.
 
4623
 
 
4624
@item -k
 
4625
All arguments in the form of assignment statements are placed
 
4626
in the environment for a command, not just those that precede
 
4627
the command name.
 
4628
 
 
4629
@item -m
 
4630
Job control is enabled (@pxref{Job Control}).
 
4631
All processes run in a separate process group.
 
4632
When a background job completes, the shell prints a line
 
4633
containing its exit status.
 
4634
 
 
4635
@item -n
 
4636
Read commands but do not execute them; this may be used to check a
 
4637
script for syntax errors.
 
4638
This option is ignored by interactive shells.
 
4639
 
 
4640
@item -o @var{option-name}
 
4641
 
 
4642
Set the option corresponding to @var{option-name}:
 
4643
 
 
4644
@table @code
 
4645
@item allexport
 
4646
Same as @code{-a}.
 
4647
 
 
4648
@item braceexpand
 
4649
Same as @code{-B}.
 
4650
 
 
4651
@item emacs
 
4652
Use an @code{emacs}-style line editing interface (@pxref{Command Line Editing}).
 
4653
This also affects the editing interface used for @code{read -e}.
 
4654
 
 
4655
@item errexit
 
4656
Same as @code{-e}.
 
4657
 
 
4658
@item errtrace
 
4659
Same as @code{-E}.
 
4660
 
 
4661
@item functrace
 
4662
Same as @code{-T}.
 
4663
 
 
4664
@item hashall
 
4665
Same as @code{-h}.
 
4666
 
 
4667
@item histexpand
 
4668
Same as @code{-H}.
 
4669
 
 
4670
@item history
 
4671
Enable command history, as described in @ref{Bash History Facilities}.
 
4672
This option is on by default in interactive shells.
 
4673
 
 
4674
@item ignoreeof
 
4675
An interactive shell will not exit upon reading EOF.
 
4676
 
 
4677
@item keyword
 
4678
Same as @code{-k}.
 
4679
 
 
4680
@item monitor
 
4681
Same as @code{-m}.
 
4682
 
 
4683
@item noclobber
 
4684
Same as @code{-C}.
 
4685
 
 
4686
@item noexec
 
4687
Same as @code{-n}.
 
4688
 
 
4689
@item noglob
 
4690
Same as @code{-f}.
 
4691
 
 
4692
@item nolog
 
4693
Currently ignored.
 
4694
 
 
4695
@item notify
 
4696
Same as @code{-b}.
 
4697
 
 
4698
@item nounset
 
4699
Same as @code{-u}.
 
4700
 
 
4701
@item onecmd
 
4702
Same as @code{-t}.
 
4703
 
 
4704
@item physical
 
4705
Same as @code{-P}.
 
4706
 
 
4707
@item pipefail
 
4708
If set, the return value of a pipeline is the value of the last
 
4709
(rightmost) command to exit with a non-zero status, or zero if all
 
4710
commands in the pipeline exit successfully.
 
4711
This option is disabled by default.
 
4712
 
 
4713
@item posix
 
4714
Change the behavior of Bash where the default operation differs
 
4715
from the @sc{posix} standard to match the standard
 
4716
(@pxref{Bash POSIX Mode}).
 
4717
This is intended to make Bash behave as a strict superset of that
 
4718
standard.
 
4719
 
 
4720
@item privileged
 
4721
Same as @code{-p}.
 
4722
 
 
4723
@item verbose
 
4724
Same as @code{-v}.
 
4725
 
 
4726
@item vi
 
4727
Use a @code{vi}-style line editing interface.
 
4728
This also affects the editing interface used for @code{read -e}.
 
4729
 
 
4730
@item xtrace
 
4731
Same as @code{-x}.
 
4732
@end table
 
4733
 
 
4734
@item -p
 
4735
Turn on privileged mode.
 
4736
In this mode, the @env{$BASH_ENV} and @env{$ENV} files are not
 
4737
processed, shell functions are not inherited from the environment,
 
4738
and the @env{SHELLOPTS}, @env{BASHOPTS}, @env{CDPATH} and @env{GLOBIGNORE}
 
4739
variables, if they appear in the environment, are ignored.
 
4740
If the shell is started with the effective user (group) id not equal to the
 
4741
real user (group) id, and the @option{-p} option is not supplied, these actions
 
4742
are taken and the effective user id is set to the real user id.
 
4743
If the @option{-p} option is supplied at startup, the effective user id is
 
4744
not reset.
 
4745
Turning this option off causes the effective user
 
4746
and group ids to be set to the real user and group ids.
 
4747
 
 
4748
@item -t
 
4749
Exit after reading and executing one command.
 
4750
 
 
4751
@item -u
 
4752
Treat unset variables and parameters other than the special parameters
 
4753
@samp{@@} or @samp{*} as an error when performing parameter expansion.
 
4754
An error message will be written to the standard error, and a non-interactive
 
4755
shell will exit.
 
4756
 
 
4757
@item -v
 
4758
Print shell input lines as they are read.
 
4759
 
 
4760
@item -x
 
4761
Print a trace of simple commands, @code{for} commands, @code{case}
 
4762
commands, @code{select} commands, and arithmetic @code{for} commands
 
4763
and their arguments or associated word lists after they are
 
4764
expanded and before they are executed.  The value of the @env{PS4}
 
4765
variable is expanded and the resultant value is printed before
 
4766
the command and its expanded arguments.
 
4767
 
 
4768
@item -B
 
4769
The shell will perform brace expansion (@pxref{Brace Expansion}).
 
4770
This option is on by default.
 
4771
 
 
4772
@item -C
 
4773
Prevent output redirection using @samp{>}, @samp{>&}, and @samp{<>}
 
4774
from overwriting existing files.
 
4775
 
 
4776
@item -E
 
4777
If set, any trap on @code{ERR} is inherited by shell functions, command
 
4778
substitutions, and commands executed in a subshell environment.
 
4779
The @code{ERR} trap is normally not inherited in such cases.
 
4780
 
 
4781
@item -H
 
4782
Enable @samp{!} style history substitution (@pxref{History Interaction}).
 
4783
This option is on by default for interactive shells.
 
4784
 
 
4785
@item -P
 
4786
If set, do not resolve symbolic links when performing commands such as
 
4787
@code{cd} which change the current directory.  The physical directory
 
4788
is used instead.  By default, Bash follows
 
4789
the logical chain of directories when performing commands
 
4790
which change the current directory.
 
4791
 
 
4792
For example, if @file{/usr/sys} is a symbolic link to @file{/usr/local/sys}
 
4793
then:
 
4794
@example
 
4795
$ cd /usr/sys; echo $PWD
 
4796
/usr/sys
 
4797
$ cd ..; pwd
 
4798
/usr
 
4799
@end example
 
4800
 
 
4801
@noindent
 
4802
If @code{set -P} is on, then:
 
4803
@example
 
4804
$ cd /usr/sys; echo $PWD
 
4805
/usr/local/sys
 
4806
$ cd ..; pwd
 
4807
/usr/local
 
4808
@end example
 
4809
 
 
4810
@item -T
 
4811
If set, any trap on @code{DEBUG} and @code{RETURN} are inherited by
 
4812
shell functions, command substitutions, and commands executed
 
4813
in a subshell environment.
 
4814
The @code{DEBUG} and @code{RETURN} traps are normally not inherited
 
4815
in such cases.
 
4816
 
 
4817
@item --
 
4818
If no arguments follow this option, then the positional parameters are
 
4819
unset.  Otherwise, the positional parameters are set to the
 
4820
@var{arguments}, even if some of them begin with a @samp{-}.
 
4821
 
 
4822
@item -
 
4823
Signal the end of options, cause all remaining @var{arguments}
 
4824
to be assigned to the positional parameters.  The @option{-x}
 
4825
and @option{-v}  options are turned off.
 
4826
If there are no arguments, the positional parameters remain unchanged.
 
4827
@end table
 
4828
 
 
4829
Using @samp{+} rather than @samp{-} causes these options to be
 
4830
turned off.  The options can also be used upon invocation of the
 
4831
shell.  The current set of options may be found in @code{$-}.
 
4832
 
 
4833
The remaining N @var{arguments} are positional parameters and are
 
4834
assigned, in order, to @code{$1}, @code{$2}, @dots{}  @code{$N}.
 
4835
The special parameter @code{#} is set to N.
 
4836
 
 
4837
The return status is always zero unless an invalid option is supplied.
 
4838
@end table
 
4839
 
 
4840
@node The Shopt Builtin
 
4841
@subsection The Shopt Builtin
 
4842
 
 
4843
This builtin allows you to change additional shell optional behavior.
 
4844
 
 
4845
@table @code
 
4846
 
 
4847
@item shopt
 
4848
@btindex shopt
 
4849
@example
 
4850
shopt [-pqsu] [-o] [@var{optname} @dots{}]
 
4851
@end example
 
4852
 
 
4853
Toggle the values of settings controlling optional shell behavior.
 
4854
The settings can be either those listed below, or, if the
 
4855
@option{-o} option is used, those available with the @option{-o}
 
4856
option to the @code{set} builtin command (@pxref{The Set Builtin}).
 
4857
With no options, or with the @option{-p} option, a list of all settable
 
4858
options is displayed, with an indication of whether or not each is set.
 
4859
The @option{-p} option causes output to be displayed in a form that
 
4860
may be reused as input.
 
4861
Other options have the following meanings:
 
4862
 
 
4863
@table @code
 
4864
@item -s
 
4865
Enable (set) each @var{optname}.
 
4866
 
 
4867
@item -u
 
4868
Disable (unset) each @var{optname}.
 
4869
 
 
4870
@item -q
 
4871
Suppresses normal output; the return status
 
4872
indicates whether the @var{optname} is set or unset.
 
4873
If multiple @var{optname} arguments are given with @option{-q},
 
4874
the return status is zero if all @var{optnames} are enabled;
 
4875
non-zero otherwise.
 
4876
 
 
4877
@item -o
 
4878
Restricts the values of
 
4879
@var{optname} to be those defined for the @option{-o} option to the
 
4880
@code{set} builtin (@pxref{The Set Builtin}).
 
4881
@end table
 
4882
 
 
4883
If either @option{-s} or @option{-u}
 
4884
is used with no @var{optname} arguments, @code{shopt} shows only
 
4885
those options which are set or unset, respectively.
 
4886
 
 
4887
Unless otherwise noted, the @code{shopt} options are disabled (off)
 
4888
by default.
 
4889
 
 
4890
The return status when listing options is zero if all @var{optnames}
 
4891
are enabled, non-zero otherwise.  When setting or unsetting options,
 
4892
the return status is zero unless an @var{optname} is not a valid shell
 
4893
option.
 
4894
 
 
4895
The list of @code{shopt} options is:
 
4896
@table @code
 
4897
 
 
4898
@item autocd
 
4899
If set, a command name that is the name of a directory is executed as if
 
4900
it were the argument to the @code{cd} command.
 
4901
This option is only used by interactive shells.
 
4902
 
 
4903
@item cdable_vars
 
4904
If this is set, an argument to the @code{cd} builtin command that
 
4905
is not a directory is assumed to be the name of a variable whose
 
4906
value is the directory to change to.
 
4907
 
 
4908
@item cdspell
 
4909
If set, minor errors in the spelling of a directory component in a
 
4910
@code{cd} command will be corrected.
 
4911
The errors checked for are transposed characters,
 
4912
a missing character, and a character too many.
 
4913
If a correction is found, the corrected path is printed,
 
4914
and the command proceeds.
 
4915
This option is only used by interactive shells.
 
4916
 
 
4917
@item checkhash
 
4918
If this is set, Bash checks that a command found in the hash
 
4919
table exists before trying to execute it.  If a hashed command no
 
4920
longer exists, a normal path search is performed.
 
4921
 
 
4922
@item checkjobs
 
4923
If set, Bash lists the status of any stopped and running jobs before
 
4924
exiting an interactive shell.  If any jobs are running, this causes
 
4925
the exit to be deferred until a second exit is attempted without an
 
4926
intervening command (@pxref{Job Control}).
 
4927
The shell always postpones exiting if any jobs are stopped.
 
4928
 
 
4929
@item checkwinsize
 
4930
If set, Bash checks the window size after each command
 
4931
 and, if necessary, updates the values of    
 
4932
@env{LINES} and @env{COLUMNS}.
 
4933
 
 
4934
@item cmdhist
 
4935
If set, Bash
 
4936
attempts to save all lines of a multiple-line
 
4937
command in the same history entry.  This allows
 
4938
easy re-editing of multi-line commands.
 
4939
 
 
4940
@item compat31
 
4941
If set, Bash
 
4942
changes its behavior to that of version 3.1 with respect to quoted
 
4943
arguments to the conditional command's @samp{=~} operator
 
4944
and with respect to locale-specific
 
4945
string comparison when using the @code{[[}
 
4946
conditional command's @samp{<} and @samp{>} operators.
 
4947
Bash versions prior to bash-4.1 use ASCII collation and strcmp(3);
 
4948
bash-4.1 and later use the current locale's collation sequence and strcoll(3).
 
4949
 
 
4950
@item compat32
 
4951
If set, Bash
 
4952
changes its behavior to that of version 3.2 with respect to locale-specific
 
4953
string comparison when using the @code{[[}
 
4954
conditional command's @samp{<} and @samp{>} operators (see previous item).
 
4955
 
 
4956
@item compat40
 
4957
If set, Bash
 
4958
changes its behavior to that of version 4.0 with respect to locale-specific
 
4959
string comparison when using the @code{[[}
 
4960
conditional command's @samp{<} and @samp{>} operators (see description
 
4961
of @code{compat31})
 
4962
and the effect of interrupting a command list.
 
4963
Bash versions 4.0 and later interrupt the list as if the shell received the
 
4964
interrupt; previous versions continue with the next command in the list.
 
4965
 
 
4966
@item compat41
 
4967
If set, Bash, when in @sc{posix} mode, treats a single quote in a double-quoted
 
4968
parameter expansion as a special character.  The single quotes must match
 
4969
(an even number) and the characters between the single quotes are considered
 
4970
quoted.  This is the behavior of @sc{posix} mode through version 4.1.
 
4971
The default Bash behavior remains as in previous versions.
 
4972
 
 
4973
@item compat42
 
4974
If set, Bash
 
4975
does not process the replacement string in the pattern substitution word
 
4976
expansion using quote removal.
 
4977
 
 
4978
@item complete_fullquote
 
4979
If set, Bash
 
4980
quotes all shell metacharacters in filenames and directory names when
 
4981
performing completion.
 
4982
If not set, Bash
 
4983
removes metacharacters such as the dollar sign from the set of
 
4984
characters that will be quoted in completed filenames
 
4985
when these metacharacters appear in shell variable references in words to be
 
4986
completed.
 
4987
This means that dollar signs in variable names that expand to directories
 
4988
will not be quoted;
 
4989
however, any dollar signs appearing in filenames will not be quoted, either.
 
4990
This is active only when bash is using backslashes to quote completed
 
4991
filenames.
 
4992
This variable is set by default, which is the default Bash behavior in
 
4993
versions through 4.2.
 
4994
 
 
4995
@item direxpand
 
4996
If set, Bash
 
4997
replaces directory names with the results of word expansion when performing
 
4998
filename completion.  This changes the contents of the readline editing
 
4999
buffer.
 
5000
If not set, Bash attempts to preserve what the user typed.
 
5001
 
 
5002
@item dirspell
 
5003
If set, Bash
 
5004
attempts spelling correction on directory names during word completion 
 
5005
if the directory name initially supplied does not exist.
 
5006
 
 
5007
@item dotglob
 
5008
If set, Bash includes filenames beginning with a `.' in
 
5009
the results of filename expansion.
 
5010
 
 
5011
@item execfail
 
5012
If this is set, a non-interactive shell will not exit if
 
5013
it cannot execute the file specified as an argument to the @code{exec}
 
5014
builtin command.  An interactive shell does not exit if @code{exec}
 
5015
fails.
 
5016
 
 
5017
@item expand_aliases
 
5018
If set, aliases are expanded as described below under Aliases,
 
5019
@ref{Aliases}.
 
5020
This option is enabled by default for interactive shells.
 
5021
 
 
5022
@item extdebug
 
5023
If set, behavior intended for use by debuggers is enabled:
 
5024
 
 
5025
@enumerate
 
5026
@item
 
5027
The @option{-F} option to the @code{declare} builtin (@pxref{Bash Builtins})
 
5028
displays the source file name and line number corresponding to each function
 
5029
name supplied as an argument.
 
5030
 
 
5031
@item
 
5032
If the command run by the @code{DEBUG} trap returns a non-zero value, the
 
5033
next command is skipped and not executed.
 
5034
 
 
5035
@item
 
5036
If the command run by the @code{DEBUG} trap returns a value of 2, and the
 
5037
shell is executing in a subroutine (a shell function or a shell script
 
5038
executed by the @code{.} or @code{source} builtins), a call to
 
5039
@code{return} is simulated.
 
5040
 
 
5041
@item
 
5042
@code{BASH_ARGC} and @code{BASH_ARGV} are updated as described in their
 
5043
descriptions (@pxref{Bash Variables}).
 
5044
 
 
5045
@item
 
5046
Function tracing is enabled:  command substitution, shell functions, and
 
5047
subshells invoked with @code{( @var{command} )} inherit the
 
5048
@code{DEBUG} and @code{RETURN} traps.
 
5049
 
 
5050
@item
 
5051
Error tracing is enabled:  command substitution, shell functions, and
 
5052
subshells invoked with @code{( @var{command} )} inherit the
 
5053
@code{ERR} trap.
 
5054
@end enumerate
 
5055
 
 
5056
@item extglob
 
5057
If set, the extended pattern matching features described above
 
5058
(@pxref{Pattern Matching}) are enabled.
 
5059
 
 
5060
@item extquote
 
5061
If set, @code{$'@var{string}'} and @code{$"@var{string}"} quoting is  
 
5062
performed within @code{$@{@var{parameter}@}} expansions                     
 
5063
enclosed in double quotes.  This option is enabled by default. 
 
5064
 
 
5065
@item failglob
 
5066
If set, patterns which fail to match filenames during filename expansion
 
5067
result in an expansion error.
 
5068
 
 
5069
@item force_fignore
 
5070
If set, the suffixes specified by the @env{FIGNORE} shell variable
 
5071
cause words to be ignored when performing word completion even if
 
5072
the ignored words are the only possible completions.
 
5073
@xref{Bash Variables}, for a description of @env{FIGNORE}.
 
5074
This option is enabled by default.
 
5075
 
 
5076
@item globasciiranges
 
5077
If set, range expressions used in pattern matching bracket expressions
 
5078
(@pxref{Pattern Matching})
 
5079
behave as if in the traditional C locale when performing
 
5080
comparisons.  That is, the current locale's collating sequence
 
5081
is not taken into account, so
 
5082
@samp{b} will not collate between @samp{A} and @samp{B},
 
5083
and upper-case and lower-case ASCII characters will collate together.   
 
5084
 
 
5085
@item globstar
 
5086
If set, the pattern @samp{**} used in a filename expansion context will
 
5087
match all files and zero or more directories and subdirectories.
 
5088
If the pattern is followed by a @samp{/}, only directories and
 
5089
subdirectories match.
 
5090
 
 
5091
@item gnu_errfmt
 
5092
If set, shell error messages are written in the standard @sc{gnu} error
 
5093
message format.
 
5094
 
 
5095
@item histappend
 
5096
If set, the history list is appended to the file named by the value
 
5097
of the @env{HISTFILE}
 
5098
variable when the shell exits, rather than overwriting the file.
 
5099
 
 
5100
@item histreedit
 
5101
If set, and Readline
 
5102
is being used, a user is given the opportunity to re-edit a
 
5103
failed history substitution.
 
5104
 
 
5105
@item histverify
 
5106
If set, and Readline
 
5107
is being used, the results of history substitution are not immediately
 
5108
passed to the shell parser.  Instead, the resulting line is loaded into
 
5109
the Readline editing buffer, allowing further modification.
 
5110
 
 
5111
@item hostcomplete
 
5112
If set, and Readline is being used, Bash will attempt to perform
 
5113
hostname completion when a word containing a @samp{@@} is being
 
5114
completed (@pxref{Commands For Completion}).  This option is enabled
 
5115
by default.
 
5116
 
 
5117
@item huponexit
 
5118
If set, Bash will send @code{SIGHUP} to all jobs when an interactive
 
5119
login shell exits (@pxref{Signals}).
 
5120
 
 
5121
@item interactive_comments
 
5122
Allow a word beginning with @samp{#}
 
5123
to cause that word and all remaining characters on that
 
5124
line to be ignored in an interactive shell.
 
5125
This option is enabled by default.
 
5126
 
 
5127
@item lastpipe
 
5128
If set, and job control is not active, the shell runs the last command of
 
5129
a pipeline not executed in the background in the current shell environment.
 
5130
 
 
5131
@item lithist
 
5132
If enabled, and the @code{cmdhist}
 
5133
option is enabled, multi-line commands are saved to the history with
 
5134
embedded newlines rather than using semicolon separators where possible.
 
5135
 
 
5136
@item login_shell
 
5137
The shell sets this option if it is started as a login shell
 
5138
(@pxref{Invoking Bash}).
 
5139
The value may not be changed.
 
5140
 
 
5141
@item mailwarn
 
5142
If set, and a file that Bash is checking for mail has been  
 
5143
accessed since the last time it was checked, the message
 
5144
@code{"The mail in @var{mailfile} has been read"} is displayed.
 
5145
 
 
5146
@item no_empty_cmd_completion
 
5147
If set, and Readline is being used, Bash will not attempt to search
 
5148
the @env{PATH} for possible completions when completion is attempted
 
5149
on an empty line.
 
5150
 
 
5151
@item nocaseglob
 
5152
If set, Bash matches filenames in a case-insensitive fashion when
 
5153
performing filename expansion.
 
5154
 
 
5155
@item nocasematch
 
5156
If set, Bash matches patterns in a case-insensitive fashion when
 
5157
performing matching while executing @code{case} or @code{[[}
 
5158
conditional commands.
 
5159
 
 
5160
@item nullglob
 
5161
If set, Bash allows filename patterns which match no
 
5162
files to expand to a null string, rather than themselves.
 
5163
 
 
5164
@item progcomp
 
5165
If set, the programmable completion facilities
 
5166
(@pxref{Programmable Completion}) are enabled.
 
5167
This option is enabled by default.
 
5168
 
 
5169
@item promptvars
 
5170
If set, prompt strings undergo
 
5171
parameter expansion, command substitution, arithmetic
 
5172
expansion, and quote removal after being expanded
 
5173
as described below (@pxref{Controlling the Prompt}).
 
5174
This option is enabled by default.
 
5175
 
 
5176
@item restricted_shell
 
5177
The shell sets this option if it is started in restricted mode
 
5178
(@pxref{The Restricted Shell}).
 
5179
The value may not be changed.
 
5180
This is not reset when the startup files are executed, allowing
 
5181
the startup files to discover whether or not a shell is restricted.
 
5182
 
 
5183
@item shift_verbose
 
5184
If this is set, the @code{shift}
 
5185
builtin prints an error message when the shift count exceeds the
 
5186
number of positional parameters.
 
5187
 
 
5188
@item sourcepath
 
5189
If set, the @code{source} builtin uses the value of @env{PATH}
 
5190
to find the directory containing the file supplied as an argument.
 
5191
This option is enabled by default.
 
5192
 
 
5193
@item xpg_echo
 
5194
If set, the @code{echo} builtin expands backslash-escape sequences
 
5195
by default.
 
5196
 
 
5197
@end table
 
5198
 
 
5199
@noindent
 
5200
The return status when listing options is zero if all @var{optnames}
 
5201
are enabled, non-zero otherwise.
 
5202
When setting or unsetting options, the return status is zero unless an
 
5203
@var{optname} is not a valid shell option.
 
5204
@end table
 
5205
 
 
5206
@node Special Builtins
 
5207
@section Special Builtins
 
5208
@cindex special builtin
 
5209
 
 
5210
For historical reasons, the @sc{posix} standard has classified
 
5211
several builtin commands as @emph{special}.
 
5212
When Bash is executing in @sc{posix} mode, the special builtins
 
5213
differ from other builtin commands in three respects:
 
5214
 
 
5215
@enumerate
 
5216
@item
 
5217
Special builtins are found before shell functions during command lookup.
 
5218
 
 
5219
@item
 
5220
If a special builtin returns an error status, a non-interactive shell exits.
 
5221
 
 
5222
@item
 
5223
Assignment statements preceding the command stay in effect in the shell
 
5224
environment after the command completes.
 
5225
@end enumerate
 
5226
 
 
5227
When Bash is not executing in @sc{posix} mode, these builtins behave no
 
5228
differently than the rest of the Bash builtin commands.
 
5229
The Bash @sc{posix} mode is described in @ref{Bash POSIX Mode}. 
 
5230
 
 
5231
These are the @sc{posix} special builtins:
 
5232
@example
 
5233
@w{break : . continue eval exec exit export readonly return set}
 
5234
@w{shift trap unset}
 
5235
@end example
 
5236
 
 
5237
@node Shell Variables
 
5238
@chapter Shell Variables
 
5239
 
 
5240
@menu
 
5241
* Bourne Shell Variables::      Variables which Bash uses in the same way
 
5242
                                as the Bourne Shell.
 
5243
* Bash Variables::              List of variables that exist in Bash.
 
5244
@end menu
 
5245
 
 
5246
This chapter describes the shell variables that Bash uses.
 
5247
Bash automatically assigns default values to a number of variables.
 
5248
 
 
5249
@node Bourne Shell Variables
 
5250
@section Bourne Shell Variables
 
5251
 
 
5252
Bash uses certain shell variables in the same way as the Bourne shell.
 
5253
In some cases, Bash assigns a default value to the variable.
 
5254
 
 
5255
@vtable @code
 
5256
 
 
5257
@item CDPATH
 
5258
A colon-separated list of directories used as a search path for
 
5259
the @code{cd} builtin command.
 
5260
 
 
5261
@item HOME
 
5262
The current user's home directory; the default for the @code{cd} builtin
 
5263
command.
 
5264
The value of this variable is also used by tilde expansion
 
5265
(@pxref{Tilde Expansion}).
 
5266
 
 
5267
@item IFS
 
5268
A list of characters that separate fields; used when the shell splits
 
5269
words as part of expansion.
 
5270
 
 
5271
@item MAIL
 
5272
If this parameter is set to a filename or directory name
 
5273
and the @env{MAILPATH} variable
 
5274
is not set, Bash informs the user of the arrival of mail in
 
5275
the specified file or Maildir-format directory.
 
5276
 
 
5277
@item MAILPATH
 
5278
A colon-separated list of filenames which the shell periodically checks
 
5279
for new mail.
 
5280
Each list entry can specify the message that is printed when new mail
 
5281
arrives in the mail file by separating the filename from the message with
 
5282
a @samp{?}.
 
5283
When used in the text of the message, @code{$_} expands to the name of
 
5284
the current mail file.
 
5285
 
 
5286
@item OPTARG
 
5287
The value of the last option argument processed by the @code{getopts} builtin.
 
5288
 
 
5289
@item OPTIND
 
5290
The index of the last option argument processed by the @code{getopts} builtin.
 
5291
 
 
5292
@item PATH
 
5293
A colon-separated list of directories in which the shell looks for
 
5294
commands.
 
5295
A zero-length (null) directory name in the value of @code{PATH} indicates the
 
5296
current directory.
 
5297
A null directory name may appear as two adjacent colons, or as an initial
 
5298
or trailing colon.
 
5299
 
 
5300
 
 
5301
@item PS1
 
5302
The primary prompt string.  The default value is @samp{\s-\v\$ }.
 
5303
@xref{Controlling the Prompt}, for the complete list of escape
 
5304
sequences that are expanded before @env{PS1} is displayed.
 
5305
 
 
5306
@item PS2
 
5307
The secondary prompt string.  The default value is @samp{> }.
 
5308
 
 
5309
@end vtable
 
5310
 
 
5311
@node Bash Variables
 
5312
@section Bash Variables
 
5313
 
 
5314
These variables are set or used by Bash, but other shells
 
5315
do not normally treat them specially.
 
5316
 
 
5317
A few variables used by Bash are described in different chapters:
 
5318
variables for controlling the job control facilities
 
5319
(@pxref{Job Control Variables}).
 
5320
 
 
5321
@vtable @code
 
5322
 
 
5323
@item BASH
 
5324
The full pathname used to execute the current instance of Bash.
 
5325
 
 
5326
@item BASHOPTS
 
5327
A colon-separated list of enabled shell options.  Each word in
 
5328
the list is a valid argument for the @option{-s} option to the
 
5329
@code{shopt} builtin command (@pxref{The Shopt Builtin}).
 
5330
The options appearing in @env{BASHOPTS} are those reported
 
5331
as @samp{on} by @samp{shopt}.
 
5332
If this variable is in the environment when Bash
 
5333
starts up, each shell option in the list will be enabled before
 
5334
reading any startup files.  This variable is readonly.
 
5335
 
 
5336
@item BASHPID
 
5337
Expands to the process ID of the current Bash process.
 
5338
This differs from @code{$$} under certain circumstances, such as subshells
 
5339
that do not require Bash to be re-initialized.
 
5340
 
 
5341
@item BASH_ALIASES
 
5342
An associative array variable whose members correspond to the internal
 
5343
list of aliases as maintained by the @code{alias} builtin.
 
5344
(@pxref{Bourne Shell Builtins}).
 
5345
Elements added to this array appear in the alias list; unsetting array
 
5346
elements cause aliases to be removed from the alias list.
 
5347
 
 
5348
@item BASH_ARGC
 
5349
An array variable whose values are the number of parameters in each
 
5350
frame of the current bash execution call stack.  The number of
 
5351
parameters to the current subroutine (shell function or script executed
 
5352
with @code{.} or @code{source}) is at the top of the stack.  When a
 
5353
subroutine is executed, the number of parameters passed is pushed onto
 
5354
@code{BASH_ARGC}.
 
5355
The shell sets @code{BASH_ARGC} only when in extended debugging mode
 
5356
(see @ref{The Shopt Builtin}
 
5357
for a description of the @code{extdebug} option to the @code{shopt}
 
5358
builtin).
 
5359
 
 
5360
@item BASH_ARGV
 
5361
An array variable containing all of the parameters in the current bash
 
5362
execution call stack.  The final parameter of the last subroutine call
 
5363
is at the top of the stack; the first parameter of the initial call is
 
5364
at the bottom.  When a subroutine is executed, the parameters supplied
 
5365
are pushed onto @code{BASH_ARGV}.
 
5366
The shell sets @code{BASH_ARGV} only when in extended debugging mode
 
5367
(see @ref{The Shopt Builtin}
 
5368
for a description of the @code{extdebug} option to the @code{shopt}
 
5369
builtin).
 
5370
 
 
5371
@item BASH_CMDS
 
5372
An associative array variable whose members correspond to the internal
 
5373
hash table of commands as maintained by the @code{hash} builtin
 
5374
(@pxref{Bourne Shell Builtins}).
 
5375
Elements added to this array appear in the hash table; unsetting array
 
5376
elements cause commands to be removed from the hash table.
 
5377
 
 
5378
@item BASH_COMMAND
 
5379
The command currently being executed or about to be executed, unless the
 
5380
shell is executing a command as the result of a trap,
 
5381
in which case it is the command executing at the time of the trap.
 
5382
 
 
5383
@item BASH_COMPAT
 
5384
The value is used to set the shell's compatibility level.
 
5385
@xref{The Shopt Builtin}, for a description of the various compatibility
 
5386
levels and their effects.
 
5387
The value may be a decimal number (e.g., 4.2) or an integer (e.g., 42)
 
5388
corresponding to the desired compatibility level.
 
5389
If @code{BASH_COMPAT} is unset or set to the empty string, the compatibility
 
5390
level is set to the default for the current version.
 
5391
If @code{BASH_COMPAT} is set to a value that is not one of the valid
 
5392
compatibility levels, the shell prints an error message and sets the
 
5393
compatibility level to the default for the current version.
 
5394
The valid compatibility levels correspond to the compatibility options
 
5395
accepted by the @code{shopt} builtin described above (for example,
 
5396
@var{compat42} means that 4.2 and 42 are valid values).
 
5397
The current version is also a valid value.
 
5398
 
 
5399
@item BASH_ENV
 
5400
If this variable is set when Bash is invoked to execute a shell
 
5401
script, its value is expanded and used as the name of a startup file
 
5402
to read before executing the script.  @xref{Bash Startup Files}.
 
5403
 
 
5404
@item BASH_EXECUTION_STRING
 
5405
The command argument to the @option{-c} invocation option.
 
5406
 
 
5407
@item BASH_LINENO
 
5408
An array variable whose members are the line numbers in source files
 
5409
where each corresponding member of @var{FUNCNAME} was invoked.
 
5410
@code{$@{BASH_LINENO[$i]@}} is the line number in the source file
 
5411
(@code{$@{BASH_SOURCE[$i+1]@}}) where
 
5412
@code{$@{FUNCNAME[$i]@}} was called (or @code{$@{BASH_LINENO[$i-1]@}} if
 
5413
referenced within another shell function). 
 
5414
Use @code{LINENO} to obtain the current line number.
 
5415
 
 
5416
@item BASH_REMATCH
 
5417
An array variable whose members are assigned by the @samp{=~} binary
 
5418
operator to the @code{[[} conditional command
 
5419
(@pxref{Conditional Constructs}).
 
5420
The element with index 0 is the portion of the string
 
5421
matching the entire regular expression.
 
5422
The element with index @var{n} is the portion of the
 
5423
string matching the @var{n}th parenthesized subexpression.
 
5424
This variable is read-only.
 
5425
 
 
5426
@item BASH_SOURCE
 
5427
An array variable whose members are the source filenames where the
 
5428
corresponding shell function names in the @code{FUNCNAME} array
 
5429
variable are defined.
 
5430
The shell function @code{$@{FUNCNAME[$i]@}} is defined in the file
 
5431
@code{$@{BASH_SOURCE[$i]@}} and called from @code{$@{BASH_SOURCE[$i+1]@}}
 
5432
 
 
5433
@item BASH_SUBSHELL
 
5434
Incremented by one within each subshell or subshell environment when
 
5435
the shell begins executing in that environment.
 
5436
The initial value is 0.
 
5437
 
 
5438
@item BASH_VERSINFO
 
5439
A readonly array variable (@pxref{Arrays})
 
5440
whose members hold version information for this instance of Bash.
 
5441
The values assigned to the array members are as follows:
 
5442
 
 
5443
@table @code
 
5444
 
 
5445
@item BASH_VERSINFO[0]
 
5446
The major version number (the @var{release}).
 
5447
 
 
5448
@item BASH_VERSINFO[1]
 
5449
The minor version number (the @var{version}).
 
5450
 
 
5451
@item BASH_VERSINFO[2]
 
5452
The patch level.
 
5453
 
 
5454
@item BASH_VERSINFO[3]
 
5455
The build version.
 
5456
 
 
5457
@item BASH_VERSINFO[4]
 
5458
The release status (e.g., @var{beta1}).
 
5459
 
 
5460
@item BASH_VERSINFO[5]
 
5461
The value of @env{MACHTYPE}.
 
5462
@end table
 
5463
 
 
5464
@item BASH_VERSION
 
5465
The version number of the current instance of Bash.
 
5466
 
 
5467
@item BASH_XTRACEFD
 
5468
If set to an integer corresponding to a valid file descriptor, Bash
 
5469
will write the trace output generated when @samp{set -x}
 
5470
is enabled to that file descriptor.
 
5471
This allows tracing output to be separated from diagnostic and error
 
5472
messages.
 
5473
The file descriptor is closed when @code{BASH_XTRACEFD} is unset or assigned
 
5474
a new value.
 
5475
Unsetting @code{BASH_XTRACEFD} or assigning it the empty string causes the
 
5476
trace output to be sent to the standard error.
 
5477
Note that setting @code{BASH_XTRACEFD} to 2 (the standard error file
 
5478
descriptor) and then unsetting it will result in the standard error
 
5479
being closed.
 
5480
 
 
5481
@item CHILD_MAX
 
5482
Set the number of exited child status values for the shell to remember.
 
5483
Bash will not allow this value to be decreased below a @sc{posix}-mandated
 
5484
minimum, and there is a maximum value (currently 8192) that this may
 
5485
not exceed.
 
5486
The minimum value is system-dependent.
 
5487
 
 
5488
@item COLUMNS
 
5489
Used by the @code{select} command to determine the terminal width
 
5490
when printing selection lists.
 
5491
Automatically set if the @code{checkwinsize} option is enabled
 
5492
(@pxref{The Shopt Builtin}), or in an interactive shell upon receipt of a
 
5493
@code{SIGWINCH}.
 
5494
 
 
5495
@item COMP_CWORD
 
5496
An index into @env{$@{COMP_WORDS@}} of the word containing the current
 
5497
cursor position.
 
5498
This variable is available only in shell functions invoked by the
 
5499
programmable completion facilities (@pxref{Programmable Completion}).
 
5500
 
 
5501
@item COMP_LINE
 
5502
The current command line.
 
5503
This variable is available only in shell functions and external
 
5504
commands invoked by the
 
5505
programmable completion facilities (@pxref{Programmable Completion}).
 
5506
 
 
5507
@item COMP_POINT
 
5508
The index of the current cursor position relative to the beginning of
 
5509
the current command.
 
5510
If the current cursor position is at the end of the current command,
 
5511
the value of this variable is equal to @code{$@{#COMP_LINE@}}.
 
5512
This variable is available only in shell functions and external
 
5513
commands invoked by the
 
5514
programmable completion facilities (@pxref{Programmable Completion}).
 
5515
 
 
5516
@item COMP_TYPE
 
5517
Set to an integer value corresponding to the type of completion attempted
 
5518
that caused a completion function to be called:
 
5519
@var{TAB}, for normal completion,
 
5520
@samp{?}, for listing completions after successive tabs,
 
5521
@samp{!}, for listing alternatives on partial word completion,
 
5522
@samp{@@}, to list completions if the word is not unmodified,
 
5523
or
 
5524
@samp{%}, for menu completion.
 
5525
This variable is available only in shell functions and external
 
5526
commands invoked by the
 
5527
programmable completion facilities (@pxref{Programmable Completion}).
 
5528
 
 
5529
@item COMP_KEY
 
5530
The key (or final key of a key sequence) used to invoke the current
 
5531
completion function.
 
5532
 
 
5533
@item COMP_WORDBREAKS
 
5534
The set of characters that the Readline library treats as word
 
5535
separators when performing word completion.
 
5536
If @code{COMP_WORDBREAKS} is unset, it loses its special properties,
 
5537
even if it is subsequently reset.
 
5538
 
 
5539
@item COMP_WORDS
 
5540
An array variable consisting of the individual
 
5541
words in the current command line.
 
5542
The line is split into words as Readline would split it, using
 
5543
@code{COMP_WORDBREAKS} as described above.
 
5544
This variable is available only in shell functions invoked by the
 
5545
programmable completion facilities (@pxref{Programmable Completion}).
 
5546
 
 
5547
@item COMPREPLY
 
5548
An array variable from which Bash reads the possible completions
 
5549
generated by a shell function invoked by the programmable completion
 
5550
facility (@pxref{Programmable Completion}).
 
5551
Each array element contains one possible completion.
 
5552
 
 
5553
@item COPROC
 
5554
An array variable created to hold the file descriptors
 
5555
for output from and input to an unnamed coprocess (@pxref{Coprocesses}).
 
5556
 
 
5557
@item DIRSTACK
 
5558
An array variable containing the current contents of the directory stack.
 
5559
Directories appear in the stack in the order they are displayed by the
 
5560
@code{dirs} builtin.
 
5561
Assigning to members of this array variable may be used to modify
 
5562
directories already in the stack, but the @code{pushd} and @code{popd}
 
5563
builtins must be used to add and remove directories.
 
5564
Assignment to this variable will not change the current directory.
 
5565
If @env{DIRSTACK} is unset, it loses its special properties, even if
 
5566
it is subsequently reset.
 
5567
 
 
5568
@item EMACS
 
5569
If Bash finds this variable in the environment when the shell
 
5570
starts with value @samp{t}, it assumes that the shell is running in an
 
5571
Emacs shell buffer and disables line editing.
 
5572
 
 
5573
@item ENV
 
5574
Similar to @code{BASH_ENV}; used when the shell is invoked in
 
5575
@sc{posix} Mode (@pxref{Bash POSIX Mode}).
 
5576
 
 
5577
@item EUID
 
5578
The numeric effective user id of the current user.  This variable
 
5579
is readonly.
 
5580
 
 
5581
@item FCEDIT
 
5582
The editor used as a default by the @option{-e} option to the @code{fc}
 
5583
builtin command.
 
5584
 
 
5585
@item FIGNORE
 
5586
A colon-separated list of suffixes to ignore when performing
 
5587
filename completion.
 
5588
A filename whose suffix matches one of the entries in 
 
5589
@env{FIGNORE}
 
5590
is excluded from the list of matched filenames.  A sample
 
5591
value is @samp{.o:~}
 
5592
 
 
5593
@item FUNCNAME
 
5594
An array variable containing the names of all shell functions
 
5595
currently in the execution call stack.
 
5596
The element with index 0 is the name of any currently-executing
 
5597
shell function.
 
5598
The bottom-most element (the one with the highest index)
 
5599
is @code{"main"}.
 
5600
This variable exists only when a shell function is executing.
 
5601
Assignments to @env{FUNCNAME} have no effect and return an error status.
 
5602
If @env{FUNCNAME} is unset, it loses its special properties, even if
 
5603
it is subsequently reset.
 
5604
 
 
5605
This variable can be used with @code{BASH_LINENO} and @code{BASH_SOURCE}.
 
5606
Each element of @code{FUNCNAME} has corresponding elements in
 
5607
@code{BASH_LINENO} and @code{BASH_SOURCE} to describe the call stack.
 
5608
For instance, @code{$@{FUNCNAME[$i]@}} was called from the file
 
5609
@code{$@{BASH_SOURCE[$i+1]@}} at line number @code{$@{BASH_LINENO[$i]@}}.
 
5610
The @code{caller} builtin displays the current call stack using this
 
5611
information.
 
5612
 
 
5613
@item FUNCNEST
 
5614
If set to a numeric value greater than 0, defines a maximum function
 
5615
nesting level.  Function invocations that exceed this nesting level
 
5616
will cause the current command to abort.
 
5617
 
 
5618
@item GLOBIGNORE
 
5619
A colon-separated list of patterns defining the set of filenames to
 
5620
be ignored by filename expansion.
 
5621
If a filename matched by a filename expansion pattern also matches one
 
5622
of the patterns in @env{GLOBIGNORE}, it is removed from the list
 
5623
of matches.
 
5624
 
 
5625
@item GROUPS
 
5626
An array variable containing the list of groups of which the current    
 
5627
user is a member.
 
5628
Assignments to @env{GROUPS} have no effect and return an error status.
 
5629
If @env{GROUPS} is unset, it loses its special properties, even if it is
 
5630
subsequently reset.
 
5631
 
 
5632
@item histchars
 
5633
Up to three characters which control history expansion, quick
 
5634
substitution, and tokenization (@pxref{History Interaction}).
 
5635
The first character is the
 
5636
@var{history expansion} character, that is, the character which signifies the
 
5637
start of a history expansion, normally @samp{!}.  The second character is the
 
5638
character which signifies `quick substitution' when seen as the first
 
5639
character on a line, normally @samp{^}.  The optional third character is the
 
5640
character which indicates that the remainder of the line is a comment when
 
5641
found as the first character of a word, usually @samp{#}.  The history
 
5642
comment character causes history substitution to be skipped for the
 
5643
remaining words on the line.  It does not necessarily cause the shell
 
5644
parser to treat the rest of the line as a comment.
 
5645
 
 
5646
@item HISTCMD
 
5647
The history number, or index in the history list, of the current
 
5648
command.  If @env{HISTCMD} is unset, it loses its special properties,
 
5649
even if it is subsequently reset.
 
5650
 
 
5651
@item HISTCONTROL
 
5652
A colon-separated list of values controlling how commands are saved on
 
5653
the history list.
 
5654
If the list of values includes @samp{ignorespace}, lines which begin
 
5655
with a space character are not saved in the history list.
 
5656
A value of @samp{ignoredups} causes lines which match the previous
 
5657
history entry to not be saved.
 
5658
A value of @samp{ignoreboth} is shorthand for
 
5659
@samp{ignorespace} and @samp{ignoredups}.
 
5660
A value of @samp{erasedups} causes all previous lines matching the
 
5661
current line to be removed from the history list before that line
 
5662
is saved.
 
5663
Any value not in the above list is ignored.
 
5664
If @env{HISTCONTROL} is unset, or does not include a valid value, 
 
5665
all lines read by the shell parser are saved on the history list, 
 
5666
subject to the value of @env{HISTIGNORE}.
 
5667
The second and subsequent lines of a multi-line compound command are
 
5668
not tested, and are added to the history regardless of the value of
 
5669
@env{HISTCONTROL}.
 
5670
 
 
5671
@item HISTFILE
 
5672
The name of the file to which the command history is saved.  The
 
5673
default value is @file{~/.bash_history}.
 
5674
 
 
5675
@item HISTFILESIZE
 
5676
The maximum number of lines contained in the history file.
 
5677
When this variable is assigned a value, the history file is truncated,
 
5678
if necessary, to contain no more than that number of lines
 
5679
by removing the oldest entries.
 
5680
The history file is also truncated to this size after
 
5681
writing it when a shell exits.
 
5682
If the value is 0, the history file is truncated to zero size.
 
5683
Non-numeric values and numeric values less than zero inhibit truncation.
 
5684
The shell sets the default value to the value of @env{HISTSIZE}
 
5685
after reading any startup files.
 
5686
 
 
5687
@item HISTIGNORE
 
5688
A colon-separated list of patterns used to decide which command
 
5689
lines should be saved on the history list.  Each pattern is
 
5690
anchored at the beginning of the line and must match the complete
 
5691
line (no implicit @samp{*} is appended).  Each pattern is tested
 
5692
against the line after the checks specified by @env{HISTCONTROL}
 
5693
are applied.  In addition to the normal shell pattern matching
 
5694
characters, @samp{&} matches the previous history line.  @samp{&}
 
5695
may be escaped using a backslash; the backslash is removed
 
5696
before attempting a match. 
 
5697
The second and subsequent lines of a multi-line compound command are
 
5698
not tested, and are added to the history regardless of the value of
 
5699
@env{HISTIGNORE}.
 
5700
 
 
5701
@env{HISTIGNORE} subsumes the function of @env{HISTCONTROL}.  A
 
5702
pattern of @samp{&} is identical to @code{ignoredups}, and a
 
5703
pattern of @samp{[ ]*} is identical to @code{ignorespace}. 
 
5704
Combining these two patterns, separating them with a colon,
 
5705
provides the functionality of @code{ignoreboth}. 
 
5706
 
 
5707
@item HISTSIZE
 
5708
The maximum number of commands to remember on the history list.
 
5709
If the value is 0, commands are not saved in the history list.
 
5710
Numeric values less than zero result in every command being saved
 
5711
on the history list (there is no limit).
 
5712
The shell sets the default value to 500 after reading any startup files.
 
5713
 
 
5714
@item HISTTIMEFORMAT
 
5715
If this variable is set and not null, its value is used as a format string
 
5716
for @var{strftime} to print the time stamp associated with each history
 
5717
entry displayed by the @code{history} builtin.
 
5718
If this variable is set, time stamps are written to the history file so
 
5719
they may be preserved across shell sessions.
 
5720
This uses the history comment character to distinguish timestamps from
 
5721
other history lines.
 
5722
 
 
5723
@item HOSTFILE
 
5724
Contains the name of a file in the same format as @file{/etc/hosts} that
 
5725
should be read when the shell needs to complete a hostname.
 
5726
The list of possible hostname completions may be changed while the shell
 
5727
is running;
 
5728
the next time hostname completion is attempted after the
 
5729
value is changed, Bash adds the contents of the new file to the
 
5730
existing list.
 
5731
If @env{HOSTFILE} is set, but has no value, or does not name a readable file,
 
5732
Bash attempts to read 
 
5733
@file{/etc/hosts} to obtain the list of possible hostname completions.
 
5734
When @env{HOSTFILE} is unset, the hostname list is cleared.
 
5735
 
 
5736
@item HOSTNAME
 
5737
The name of the current host.
 
5738
 
 
5739
@item HOSTTYPE
 
5740
A string describing the machine Bash is running on.
 
5741
 
 
5742
@item IGNOREEOF
 
5743
Controls the action of the shell on receipt of an @code{EOF} character
 
5744
as the sole input.  If set, the value denotes the number
 
5745
of consecutive @code{EOF} characters that can be read as the
 
5746
first character on an input line
 
5747
before the shell will exit.  If the variable exists but does not
 
5748
have a numeric value (or has no value) then the default is 10.
 
5749
If the variable does not exist, then @code{EOF} signifies the end of 
 
5750
input to the shell.  This is only in effect for interactive shells.
 
5751
 
 
5752
@item INPUTRC
 
5753
The name of the Readline initialization file, overriding the default
 
5754
of @file{~/.inputrc}.
 
5755
 
 
5756
@item LANG  
 
5757
Used to determine the locale category for any category not specifically
 
5758
selected with a variable starting with @code{LC_}.
 
5759
 
 
5760
@item LC_ALL
 
5761
This variable overrides the value of @env{LANG} and any other
 
5762
@code{LC_} variable specifying a locale category.
 
5763
 
 
5764
@item LC_COLLATE
 
5765
This variable determines the collation order used when sorting the
 
5766
results of filename expansion, and
 
5767
determines the behavior of range expressions, equivalence classes,
 
5768
and collating sequences within filename expansion and pattern matching
 
5769
(@pxref{Filename Expansion}).
 
5770
 
 
5771
@item LC_CTYPE
 
5772
This variable determines the interpretation of characters and the
 
5773
behavior of character classes within filename expansion and pattern
 
5774
matching (@pxref{Filename Expansion}).
 
5775
 
 
5776
@item LC_MESSAGES
 
5777
This variable determines the locale used to translate double-quoted
 
5778
strings preceded by a @samp{$} (@pxref{Locale Translation}).
 
5779
 
 
5780
@item LC_NUMERIC
 
5781
This variable determines the locale category used for number formatting.
 
5782
 
 
5783
@item LINENO
 
5784
The line number in the script or shell function currently executing.
 
5785
 
 
5786
@item LINES
 
5787
Used by the @code{select} command to determine the column length
 
5788
for printing selection lists.
 
5789
Automatically set if the @code{checkwinsize} option is enabled
 
5790
(@pxref{The Shopt Builtin}), or in an interactive shell upon receipt of a
 
5791
@code{SIGWINCH}.
 
5792
 
 
5793
@item MACHTYPE
 
5794
A string that fully describes the system type on which Bash
 
5795
is executing, in the standard @sc{gnu} @var{cpu-company-system} format.
 
5796
 
 
5797
@item MAILCHECK
 
5798
How often (in seconds) that the shell should check for mail in the
 
5799
files specified in the @env{MAILPATH} or @env{MAIL} variables.
 
5800
The default is 60 seconds.  When it is time to check
 
5801
for mail, the shell does so before displaying the primary prompt.
 
5802
If this variable is unset, or set to a value that is not a number
 
5803
greater than or equal to zero, the shell disables mail checking.
 
5804
 
 
5805
@item MAPFILE
 
5806
An array variable created to hold the text read by the
 
5807
@code{mapfile} builtin when no variable name is supplied.
 
5808
 
 
5809
@item OLDPWD
 
5810
The previous working directory as set by the @code{cd} builtin.
 
5811
 
 
5812
@item OPTERR
 
5813
If set to the value 1, Bash displays error messages
 
5814
generated by the @code{getopts} builtin command.
 
5815
 
 
5816
@item OSTYPE
 
5817
A string describing the operating system Bash is running on.
 
5818
 
 
5819
@item PIPESTATUS
 
5820
An array variable (@pxref{Arrays})
 
5821
containing a list of exit status values from the processes
 
5822
in the most-recently-executed foreground pipeline (which may
 
5823
contain only a single command).
 
5824
 
 
5825
@item POSIXLY_CORRECT
 
5826
If this variable is in the environment when Bash starts, the shell
 
5827
enters @sc{posix} mode (@pxref{Bash POSIX Mode}) before reading the
 
5828
startup files, as if the @option{--posix} invocation option had been supplied.
 
5829
If it is set while the shell is running, Bash enables @sc{posix} mode,
 
5830
as if the command
 
5831
@example
 
5832
@code{set -o posix}
 
5833
@end example
 
5834
@noindent
 
5835
had been executed.  
 
5836
 
 
5837
@item PPID
 
5838
The process @sc{id} of the shell's parent process.  This variable
 
5839
is readonly.
 
5840
 
 
5841
@item PROMPT_COMMAND
 
5842
If set, the value is interpreted as a command to execute
 
5843
before the printing of each primary prompt (@env{$PS1}).
 
5844
 
 
5845
@item PROMPT_DIRTRIM
 
5846
If set to a number greater than zero, the value is used as the number of
 
5847
trailing directory components to retain when expanding the @code{\w} and
 
5848
@code{\W} prompt string escapes (@pxref{Controlling the Prompt}).
 
5849
Characters removed are replaced with an ellipsis.
 
5850
 
 
5851
@item PS3
 
5852
The value of this variable is used as the prompt for the
 
5853
@code{select} command.  If this variable is not set, the
 
5854
@code{select} command prompts with @samp{#? }
 
5855
 
 
5856
@item PS4
 
5857
The value is the prompt printed before the command line is echoed
 
5858
when the @option{-x} option is set (@pxref{The Set Builtin}).
 
5859
The first character of @env{PS4} is replicated multiple times, as
 
5860
necessary, to indicate multiple levels of indirection.
 
5861
The default is @samp{+ }.
 
5862
 
 
5863
@item PWD
 
5864
The current working directory as set by the @code{cd} builtin.
 
5865
 
 
5866
@item RANDOM
 
5867
Each time this parameter is referenced, a random integer
 
5868
between 0 and 32767 is generated.  Assigning a value to this
 
5869
variable seeds the random number generator.
 
5870
 
 
5871
@item READLINE_LINE
 
5872
The contents of the Readline line buffer, for use
 
5873
with @samp{bind -x} (@pxref{Bash Builtins}).
 
5874
 
 
5875
@item READLINE_POINT
 
5876
The position of the insertion point in the Readline line buffer, for use
 
5877
with @samp{bind -x} (@pxref{Bash Builtins}).
 
5878
 
 
5879
@item REPLY
 
5880
The default variable for the @code{read} builtin.
 
5881
 
 
5882
@item SECONDS
 
5883
This variable expands to the number of seconds since the
 
5884
shell was started.  Assignment to this variable resets
 
5885
the count to the value assigned, and the expanded value
 
5886
becomes the value assigned plus the number of seconds
 
5887
since the assignment.
 
5888
 
 
5889
@item SHELL
 
5890
The full pathname to the shell is kept in this environment variable.
 
5891
If it is not set when the shell starts,
 
5892
Bash assigns to it the full pathname of the current user's login shell.
 
5893
 
 
5894
@item SHELLOPTS
 
5895
A colon-separated list of enabled shell options.  Each word in
 
5896
the list is a valid argument for the @option{-o} option to the
 
5897
@code{set} builtin command (@pxref{The Set Builtin}).
 
5898
The options appearing in @env{SHELLOPTS} are those reported
 
5899
as @samp{on} by @samp{set -o}.
 
5900
If this variable is in the environment when Bash
 
5901
starts up, each shell option in the list will be enabled before
 
5902
reading any startup files.  This variable is readonly.
 
5903
 
 
5904
@item SHLVL
 
5905
Incremented by one each time a new instance of Bash is started.  This is
 
5906
intended to be a count of how deeply your Bash shells are nested.
 
5907
 
 
5908
@item TIMEFORMAT
 
5909
The value of this parameter is used as a format string specifying
 
5910
how the timing information for pipelines prefixed with the @code{time}
 
5911
reserved word should be displayed.
 
5912
The @samp{%} character introduces an
 
5913
escape sequence that is expanded to a time value or other
 
5914
information.
 
5915
The escape sequences and their meanings are as
 
5916
follows; the braces denote optional portions. 
 
5917
 
 
5918
@table @code
 
5919
 
 
5920
@item %%
 
5921
A literal @samp{%}.
 
5922
 
 
5923
@item %[@var{p}][l]R
 
5924
The elapsed time in seconds. 
 
5925
 
 
5926
@item %[@var{p}][l]U
 
5927
The number of CPU seconds spent in user mode. 
 
5928
 
 
5929
@item %[@var{p}][l]S
 
5930
The number of CPU seconds spent in system mode. 
 
5931
 
 
5932
@item %P
 
5933
The CPU percentage, computed as (%U + %S) / %R. 
 
5934
@end table
 
5935
 
 
5936
The optional @var{p} is a digit specifying the precision, the number of
 
5937
fractional digits after a decimal point.
 
5938
A value of 0 causes no decimal point or fraction to be output.
 
5939
At most three places after the decimal point may be specified; values
 
5940
of @var{p} greater than 3 are changed to 3.
 
5941
If @var{p} is not specified, the value 3 is used. 
 
5942
 
 
5943
The optional @code{l} specifies a longer format, including minutes, of
 
5944
the form @var{MM}m@var{SS}.@var{FF}s.
 
5945
The value of @var{p} determines whether or not the fraction is included. 
 
5946
 
 
5947
If this variable is not set, Bash acts as if it had the value
 
5948
@example
 
5949
@code{$'\nreal\t%3lR\nuser\t%3lU\nsys\t%3lS'}
 
5950
@end example
 
5951
If the value is null, no timing information is displayed.
 
5952
A trailing newline is added when the format string is displayed.
 
5953
 
 
5954
@item TMOUT
 
5955
If set to a value greater than zero, @code{TMOUT} is treated as the
 
5956
default timeout for the @code{read} builtin (@pxref{Bash Builtins}).
 
5957
The @code{select} command (@pxref{Conditional Constructs}) terminates
 
5958
if input does not arrive after @code{TMOUT} seconds when input is coming
 
5959
from a terminal.
 
5960
 
 
5961
In an interactive shell, the value is interpreted as
 
5962
the number of seconds to wait for a line of input after issuing
 
5963
the primary prompt.
 
5964
Bash
 
5965
terminates after waiting for that number of seconds if a complete
 
5966
line of input does not arrive.
 
5967
 
 
5968
@item TMPDIR
 
5969
If set, Bash uses its value as the name of a directory in which
 
5970
Bash creates temporary files for the shell's use.
 
5971
 
 
5972
@item UID
 
5973
The numeric real user id of the current user.  This variable is readonly.
 
5974
 
 
5975
@end vtable
 
5976
 
 
5977
@node Bash Features
 
5978
@chapter Bash Features
 
5979
 
 
5980
This chapter describes features unique to Bash.
 
5981
 
 
5982
@menu
 
5983
* Invoking Bash::               Command line options that you can give
 
5984
                                to Bash.
 
5985
* Bash Startup Files::          When and how Bash executes scripts.
 
5986
* Interactive Shells::          What an interactive shell is.
 
5987
* Bash Conditional Expressions::        Primitives used in composing expressions for
 
5988
                                the @code{test} builtin.
 
5989
* Shell Arithmetic::            Arithmetic on shell variables.
 
5990
* Aliases::                     Substituting one command for another.
 
5991
* Arrays::                      Array Variables.
 
5992
* The Directory Stack::         History of visited directories.
 
5993
* Controlling the Prompt::      Customizing the various prompt strings.
 
5994
* The Restricted Shell::        A more controlled mode of shell execution.
 
5995
* Bash POSIX Mode::             Making Bash behave more closely to what
 
5996
                                the POSIX standard specifies.
 
5997
@end menu
 
5998
 
 
5999
@node Invoking Bash
 
6000
@section Invoking Bash
 
6001
 
 
6002
@example
 
6003
bash [long-opt] [-ir] [-abefhkmnptuvxdBCDHP] [-o @var{option}] [-O @var{shopt_option}] [@var{argument} @dots{}]
 
6004
bash [long-opt] [-abefhkmnptuvxdBCDHP] [-o @var{option}] [-O @var{shopt_option}] -c @var{string} [@var{argument} @dots{}]
 
6005
bash [long-opt] -s [-abefhkmnptuvxdBCDHP] [-o @var{option}] [-O @var{shopt_option}] [@var{argument} @dots{}]
 
6006
@end example
 
6007
 
 
6008
All of the single-character options used with the @code{set} builtin
 
6009
(@pxref{The Set Builtin}) can be used as options when the shell is invoked.
 
6010
In addition, there are several multi-character
 
6011
options that you can use.  These options must appear on the command
 
6012
line before the single-character options to be recognized. 
 
6013
 
 
6014
@table @code
 
6015
@item --debugger
 
6016
Arrange for the debugger profile to be executed before the shell
 
6017
starts.  Turns on extended debugging mode (see @ref{The Shopt Builtin}
 
6018
for a description of the @code{extdebug} option to the @code{shopt}
 
6019
builtin).
 
6020
 
 
6021
@item --dump-po-strings
 
6022
A list of all double-quoted strings preceded by @samp{$}
 
6023
is printed on the standard output
 
6024
in the @sc{gnu} @code{gettext} PO (portable object) file format.
 
6025
Equivalent to @option{-D} except for the output format.
 
6026
 
 
6027
@item --dump-strings
 
6028
Equivalent to @option{-D}.
 
6029
 
 
6030
@item --help
 
6031
Display a usage message on standard output and exit successfully.
 
6032
 
 
6033
@item --init-file @var{filename}
 
6034
@itemx --rcfile @var{filename}
 
6035
Execute commands from @var{filename} (instead of @file{~/.bashrc})
 
6036
in an interactive shell.
 
6037
 
 
6038
@item --login
 
6039
Equivalent to @option{-l}.
 
6040
 
 
6041
@item --noediting
 
6042
Do not use the @sc{gnu} Readline library (@pxref{Command Line Editing})
 
6043
to read  command lines when the shell is interactive.
 
6044
 
 
6045
@item --noprofile
 
6046
Don't load the system-wide startup file @file{/etc/profile}
 
6047
or any of the personal initialization files
 
6048
@file{~/.bash_profile}, @file{~/.bash_login}, or @file{~/.profile}
 
6049
when Bash is invoked as a login shell.
 
6050
 
 
6051
@item --norc
 
6052
Don't read the @file{~/.bashrc} initialization file in an
 
6053
interactive shell.  This is on by default if the shell is
 
6054
invoked as @code{sh}.
 
6055
 
 
6056
@item --posix
 
6057
Change the behavior of Bash where the default operation differs
 
6058
from the @sc{posix} standard to match the standard.  This
 
6059
is intended to make Bash behave as a strict superset of that
 
6060
standard.  @xref{Bash POSIX Mode}, for a description of the Bash
 
6061
@sc{posix} mode.
 
6062
 
 
6063
@item --restricted
 
6064
Make the shell a restricted shell (@pxref{The Restricted Shell}).
 
6065
 
 
6066
@item --verbose
 
6067
Equivalent to @option{-v}.  Print shell input lines as they're read.
 
6068
 
 
6069
@item --version
 
6070
Show version information for this instance of
 
6071
Bash on the standard output and exit successfully.
 
6072
@end table
 
6073
 
 
6074
There are several single-character options that may be supplied at
 
6075
invocation which are not available with the @code{set} builtin.
 
6076
 
 
6077
@table @code
 
6078
@item -c
 
6079
Read and execute commands from the first non-option @var{argument}
 
6080
after processing the options, then exit. 
 
6081
Any remaining arguments are assigned to the
 
6082
positional parameters, starting with @code{$0}.
 
6083
 
 
6084
@item -i
 
6085
Force the shell to run interactively.  Interactive shells are
 
6086
described in @ref{Interactive Shells}.
 
6087
 
 
6088
@item -l
 
6089
Make this shell act as if it had been directly invoked by login.
 
6090
When the shell is interactive, this is equivalent to starting a
 
6091
login shell with @samp{exec -l bash}.
 
6092
When the shell is not interactive, the login shell startup files will
 
6093
be executed.
 
6094
@samp{exec bash -l} or @samp{exec bash --login}
 
6095
will replace the current shell with a Bash login shell.
 
6096
@xref{Bash Startup Files}, for a description of the special behavior
 
6097
of a login shell.
 
6098
 
 
6099
@item -r
 
6100
Make the shell a restricted shell (@pxref{The Restricted Shell}).
 
6101
 
 
6102
@item -s
 
6103
If this option is present, or if no arguments remain after option
 
6104
processing, then commands are read from the standard input.
 
6105
This option allows the positional parameters to be set
 
6106
when invoking an interactive shell.
 
6107
 
 
6108
@item -D
 
6109
A list of all double-quoted strings preceded by @samp{$}
 
6110
is printed on the standard output.
 
6111
These are the strings that
 
6112
are subject to language translation when the current locale
 
6113
is not @code{C} or @code{POSIX} (@pxref{Locale Translation}).
 
6114
This implies the @option{-n} option; no commands will be executed.
 
6115
 
 
6116
@item [-+]O [@var{shopt_option}]
 
6117
@var{shopt_option} is one of the shell options accepted by the
 
6118
@code{shopt} builtin (@pxref{The Shopt Builtin}).
 
6119
If @var{shopt_option} is present, @option{-O} sets the value of that option;
 
6120
@option{+O} unsets it.  
 
6121
If @var{shopt_option} is not supplied, the names and values of the shell
 
6122
options accepted by @code{shopt} are printed on the standard output.
 
6123
If the invocation option is @option{+O}, the output is displayed in a format
 
6124
that may be reused as input.
 
6125
 
 
6126
@item --
 
6127
A @code{--} signals the end of options and disables further option
 
6128
processing.
 
6129
Any arguments after the @code{--} are treated as filenames and arguments.
 
6130
@end table
 
6131
 
 
6132
@cindex login shell
 
6133
A @emph{login} shell is one whose first character of argument zero is
 
6134
@samp{-}, or one invoked with the @option{--login} option.
 
6135
 
 
6136
@cindex interactive shell
 
6137
An @emph{interactive} shell is one started without non-option arguments,
 
6138
unless @option{-s} is specified,
 
6139
without specifying the @option{-c} option, and whose input and output are both
 
6140
connected to terminals (as determined by @code{isatty(3)}), or one
 
6141
started with the @option{-i} option.  @xref{Interactive Shells}, for more
 
6142
information.
 
6143
 
 
6144
If arguments remain after option processing, and neither the
 
6145
@option{-c} nor the @option{-s}
 
6146
option has been supplied, the first argument is assumed to
 
6147
be the name of a file containing shell commands (@pxref{Shell Scripts}).
 
6148
When Bash is invoked in this fashion, @code{$0}
 
6149
is set to the name of the file, and the positional parameters
 
6150
are set to the remaining arguments.
 
6151
Bash reads and executes commands from this file, then exits.   
 
6152
Bash's exit status is the exit status of the last command executed
 
6153
in the script.  If no commands are executed, the exit status is 0.
 
6154
 
 
6155
@node Bash Startup Files
 
6156
@section Bash Startup Files
 
6157
@cindex startup files
 
6158
 
 
6159
This section describes how Bash executes its startup files.
 
6160
If any of the files exist but cannot be read, Bash reports an error.
 
6161
Tildes are expanded in filenames as described above under
 
6162
Tilde Expansion (@pxref{Tilde Expansion}).
 
6163
 
 
6164
Interactive shells are described in @ref{Interactive Shells}.
 
6165
 
 
6166
@subsubheading Invoked as an interactive login shell, or with @option{--login}
 
6167
 
 
6168
When Bash is invoked as an interactive login shell, or as a
 
6169
non-interactive shell with the @option{--login} option, it first reads and
 
6170
executes commands from the file @file{/etc/profile}, if that file exists.
 
6171
After reading that file, it looks for @file{~/.bash_profile},
 
6172
@file{~/.bash_login}, and @file{~/.profile}, in that order, and reads
 
6173
and executes commands from the first one that exists and is readable.
 
6174
The @option{--noprofile} option may be used when the shell is started to
 
6175
inhibit this behavior.
 
6176
 
 
6177
When a login shell exits, Bash reads and executes commands from
 
6178
the file @file{~/.bash_logout}, if it exists.
 
6179
 
 
6180
@subsubheading Invoked as an interactive non-login shell
 
6181
 
 
6182
When an interactive shell that is not a login shell is started, Bash
 
6183
reads and executes commands from @file{~/.bashrc}, if that file exists.
 
6184
This may be inhibited by using the @option{--norc} option.
 
6185
The @option{--rcfile @var{file}} option will force Bash to read and
 
6186
execute commands from @var{file} instead of @file{~/.bashrc}.
 
6187
 
 
6188
So, typically, your @file{~/.bash_profile} contains the line
 
6189
@example
 
6190
@code{if [ -f ~/.bashrc ]; then . ~/.bashrc; fi}
 
6191
@end example
 
6192
@noindent
 
6193
after (or before) any login-specific initializations.
 
6194
 
 
6195
@subsubheading Invoked non-interactively
 
6196
 
 
6197
When Bash is started non-interactively, to run a shell script,
 
6198
for example, it looks for the variable @env{BASH_ENV} in the environment,
 
6199
expands its value if it appears there, and uses the expanded value as
 
6200
the name of a file to read and execute.  Bash behaves as if the
 
6201
following command were executed:
 
6202
@example
 
6203
@code{if [ -n "$BASH_ENV" ]; then . "$BASH_ENV"; fi}
 
6204
@end example
 
6205
@noindent
 
6206
but the value of the @env{PATH} variable is not used to search for the
 
6207
filename.
 
6208
 
 
6209
As noted above, if a non-interactive shell is invoked with the
 
6210
@option{--login} option, Bash attempts to read and execute commands from the
 
6211
login shell startup files. 
 
6212
 
 
6213
@subsubheading Invoked with name @code{sh}
 
6214
 
 
6215
If Bash is invoked with the name @code{sh}, it tries to mimic the
 
6216
startup behavior of historical versions of @code{sh} as closely as
 
6217
possible, while conforming to the @sc{posix} standard as well.
 
6218
 
 
6219
When invoked as an interactive login shell, or as a non-interactive
 
6220
shell with the @option{--login} option, it first attempts to read
 
6221
and execute commands from @file{/etc/profile} and @file{~/.profile}, in
 
6222
that order.
 
6223
The @option{--noprofile} option may be used to inhibit this behavior.
 
6224
When invoked as an interactive shell with the name @code{sh}, Bash
 
6225
looks for the variable @env{ENV}, expands its value if it is defined,
 
6226
and uses the expanded value as the name of a file to read and execute.
 
6227
Since a shell invoked as @code{sh} does not attempt to read and execute
 
6228
commands from any other startup files, the @option{--rcfile} option has
 
6229
no effect.
 
6230
A non-interactive shell invoked with the name @code{sh} does not attempt
 
6231
to read any other startup files.
 
6232
 
 
6233
When invoked as @code{sh}, Bash enters @sc{posix} mode after
 
6234
the startup files are read.
 
6235
 
 
6236
@subsubheading Invoked in @sc{posix} mode
 
6237
 
 
6238
When Bash is started in @sc{posix} mode, as with the
 
6239
@option{--posix} command line option, it follows the @sc{posix} standard
 
6240
for startup files.
 
6241
In this mode, interactive shells expand the @env{ENV} variable
 
6242
and commands are read and executed from the file whose name is the
 
6243
expanded value.
 
6244
No other startup files are read.
 
6245
 
 
6246
@subsubheading Invoked by remote shell daemon
 
6247
 
 
6248
Bash attempts to determine when it is being run with its standard input
 
6249
connected to a network connection, as when executed by the remote shell
 
6250
daemon, usually @code{rshd}, or the secure shell daemon @code{sshd}.
 
6251
If Bash determines it is being run in
 
6252
this fashion, it reads and executes commands from @file{~/.bashrc}, if that
 
6253
file exists and is readable.
 
6254
It will not do this if invoked as @code{sh}.
 
6255
The @option{--norc} option may be used to inhibit this behavior, and the
 
6256
@option{--rcfile} option may be used to force another file to be read, but
 
6257
neither @code{rshd} nor @code{sshd} generally invoke the shell with those
 
6258
options or allow them to be specified.
 
6259
 
 
6260
@subsubheading Invoked with unequal effective and real @sc{uid/gid}s
 
6261
 
 
6262
If Bash is started with the effective user (group) id not equal to the
 
6263
real user (group) id, and the @option{-p} option is not supplied, no startup
 
6264
files are read, shell functions are not inherited from the environment,
 
6265
the @env{SHELLOPTS}, @env{BASHOPTS}, @env{CDPATH}, and @env{GLOBIGNORE}
 
6266
variables, if they appear in the environment, are ignored, and the effective
 
6267
user id is set to the real user id.
 
6268
If the @option{-p} option is supplied at invocation, the startup behavior is
 
6269
the same, but the effective user id is not reset.
 
6270
 
 
6271
@node Interactive Shells
 
6272
@section Interactive Shells
 
6273
@cindex interactive shell
 
6274
@cindex shell, interactive
 
6275
 
 
6276
@menu
 
6277
* What is an Interactive Shell?::       What determines whether a shell is Interactive.
 
6278
* Is this Shell Interactive?::  How to tell if a shell is interactive.
 
6279
* Interactive Shell Behavior::  What changes in a interactive shell?
 
6280
@end menu
 
6281
 
 
6282
@node What is an Interactive Shell?
 
6283
@subsection What is an Interactive Shell?
 
6284
 
 
6285
An interactive shell
 
6286
is one started without non-option arguments, unless @option{-s} is
 
6287
specified, without specifying the @option{-c} option, and
 
6288
whose input and error output are both
 
6289
connected to terminals (as determined by @code{isatty(3)}),
 
6290
or one started with the @option{-i} option.
 
6291
 
 
6292
An interactive shell generally reads from and writes to a user's
 
6293
terminal.
 
6294
 
 
6295
The @option{-s} invocation option may be used to set the positional parameters
 
6296
when an interactive shell is started.
 
6297
 
 
6298
@node Is this Shell Interactive?
 
6299
@subsection Is this Shell Interactive?
 
6300
 
 
6301
To determine within a startup script whether or not Bash is
 
6302
running interactively,
 
6303
test the value of the @samp{-} special parameter.
 
6304
It contains @code{i} when the shell is interactive.  For example:
 
6305
 
 
6306
@example
 
6307
case "$-" in
 
6308
*i*)    echo This shell is interactive ;;
 
6309
*)      echo This shell is not interactive ;;
 
6310
esac
 
6311
@end example
 
6312
 
 
6313
Alternatively, startup scripts may examine the variable
 
6314
@env{PS1}; it is unset in non-interactive shells, and set in
 
6315
interactive shells.  Thus:
 
6316
 
 
6317
@example
 
6318
if [ -z "$PS1" ]; then
 
6319
        echo This shell is not interactive
 
6320
else
 
6321
        echo This shell is interactive
 
6322
fi
 
6323
@end example
 
6324
 
 
6325
@node Interactive Shell Behavior
 
6326
@subsection Interactive Shell Behavior
 
6327
 
 
6328
When the shell is running interactively, it changes its behavior in
 
6329
several ways.
 
6330
 
 
6331
@enumerate
 
6332
@item
 
6333
Startup files are read and executed as described in @ref{Bash Startup Files}.
 
6334
 
 
6335
@item
 
6336
Job Control (@pxref{Job Control}) is enabled by default.  When job
 
6337
control is in effect, Bash ignores the keyboard-generated job control
 
6338
signals @code{SIGTTIN}, @code{SIGTTOU}, and @code{SIGTSTP}.
 
6339
 
 
6340
@item
 
6341
Bash expands and displays @env{PS1} before reading the first line
 
6342
of a command, and expands and displays @env{PS2} before reading the
 
6343
second and subsequent lines of a multi-line command.
 
6344
 
 
6345
@item
 
6346
Bash executes the value of the @env{PROMPT_COMMAND} variable as a command
 
6347
before printing the primary prompt, @env{$PS1}
 
6348
(@pxref{Bash Variables}).
 
6349
 
 
6350
@item
 
6351
Readline (@pxref{Command Line Editing}) is used to read commands from
 
6352
the user's terminal.
 
6353
 
 
6354
@item
 
6355
Bash inspects the value of the @code{ignoreeof} option to @code{set -o}
 
6356
instead of exiting immediately when it receives an @code{EOF} on its
 
6357
standard input when reading a command (@pxref{The Set Builtin}).
 
6358
 
 
6359
@item
 
6360
Command history (@pxref{Bash History Facilities})
 
6361
and history expansion (@pxref{History Interaction})
 
6362
are enabled by default.
 
6363
Bash will save the command history to the file named by @env{$HISTFILE}
 
6364
when a shell with history enabled exits.
 
6365
 
 
6366
@item
 
6367
Alias expansion (@pxref{Aliases}) is performed by default.
 
6368
 
 
6369
@item
 
6370
In the absence of any traps, Bash ignores @code{SIGTERM}
 
6371
(@pxref{Signals}).
 
6372
 
 
6373
@item
 
6374
In the absence of any traps, @code{SIGINT} is caught and handled
 
6375
((@pxref{Signals}).
 
6376
@code{SIGINT} will interrupt some shell builtins.
 
6377
 
 
6378
@item
 
6379
An interactive login shell sends a @code{SIGHUP} to all jobs on exit
 
6380
if the @code{huponexit} shell option has been enabled (@pxref{Signals}).
 
6381
 
 
6382
@item
 
6383
The @option{-n} invocation option is ignored, and @samp{set -n} has
 
6384
no effect (@pxref{The Set Builtin}).
 
6385
 
 
6386
@item
 
6387
Bash will check for mail periodically, depending on the values of the
 
6388
@env{MAIL}, @env{MAILPATH}, and @env{MAILCHECK} shell variables
 
6389
(@pxref{Bash Variables}).
 
6390
 
 
6391
@item
 
6392
Expansion errors due to references to unbound shell variables after
 
6393
@samp{set -u} has been enabled will not cause the shell to exit
 
6394
(@pxref{The Set Builtin}).
 
6395
 
 
6396
@item
 
6397
The shell will not exit on expansion errors caused by @var{var} being unset
 
6398
or null in @code{$@{@var{var}:?@var{word}@}} expansions
 
6399
(@pxref{Shell Parameter Expansion}).
 
6400
 
 
6401
@item
 
6402
Redirection errors encountered by shell builtins will not cause the
 
6403
shell to exit.
 
6404
 
 
6405
@item
 
6406
When running in @sc{posix} mode, a special builtin returning an error
 
6407
status will not cause the shell to exit (@pxref{Bash POSIX Mode}).
 
6408
 
 
6409
@item
 
6410
A failed @code{exec} will not cause the shell to exit
 
6411
(@pxref{Bourne Shell Builtins}).
 
6412
 
 
6413
@item
 
6414
Parser syntax errors will not cause the shell to exit.
 
6415
 
 
6416
@item
 
6417
Simple spelling correction for directory arguments to the @code{cd}
 
6418
builtin is enabled by default (see the description of the @code{cdspell}
 
6419
option to the @code{shopt} builtin in @ref{The Shopt Builtin}).
 
6420
 
 
6421
@item
 
6422
The shell will check the value of the @env{TMOUT} variable and exit
 
6423
if a command is not read within the specified number of seconds after
 
6424
printing @env{$PS1} (@pxref{Bash Variables}).
 
6425
 
 
6426
@end enumerate
 
6427
 
 
6428
@node Bash Conditional Expressions
 
6429
@section Bash Conditional Expressions
 
6430
@cindex expressions, conditional
 
6431
 
 
6432
Conditional expressions are used by the @code{[[} compound command
 
6433
and the @code{test} and @code{[} builtin commands.
 
6434
 
 
6435
Expressions may be unary or binary.
 
6436
Unary expressions are often used to examine the status of a file.
 
6437
There are string operators and numeric comparison operators as well.
 
6438
If the @var{file} argument to one of the primaries is of the form
 
6439
@file{/dev/fd/@var{N}}, then file descriptor @var{N} is checked.
 
6440
If the @var{file} argument to one of the primaries is one of
 
6441
@file{/dev/stdin}, @file{/dev/stdout}, or @file{/dev/stderr}, file
 
6442
descriptor 0, 1, or 2, respectively, is checked.
 
6443
 
 
6444
When used with @code{[[}, the @samp{<} and @samp{>} operators sort
 
6445
lexicographically using the current locale.
 
6446
The @code{test} command uses ASCII ordering.
 
6447
 
 
6448
Unless otherwise specified, primaries that operate on files follow symbolic
 
6449
links and operate on the target of the link, rather than the link itself.
 
6450
 
 
6451
See the description of the @code{test} builtin command (section
 
6452
@pxref{Bash Builtins} below) for the handling of parameters
 
6453
(i.e. missing parameters).
 
6454
 
 
6455
@table @code
 
6456
@item -a @var{file}
 
6457
True if @var{file} exists.
 
6458
 
 
6459
@item -b @var{file}
 
6460
True if @var{file} exists and is a block special file.
 
6461
 
 
6462
@item -c @var{file}
 
6463
True if @var{file} exists and is a character special file.
 
6464
 
 
6465
@item -d @var{file}
 
6466
True if @var{file} exists and is a directory.
 
6467
 
 
6468
@item -e @var{file}
 
6469
True if @var{file} exists.
 
6470
 
 
6471
@item -f @var{file}
 
6472
True if @var{file} exists and is a regular file.
 
6473
 
 
6474
@item -g @var{file}
 
6475
True if @var{file} exists and its set-group-id bit is set.
 
6476
 
 
6477
@item -h @var{file}
 
6478
True if @var{file} exists and is a symbolic link.
 
6479
 
 
6480
@item -k @var{file}
 
6481
True if @var{file} exists and its "sticky" bit is set.
 
6482
 
 
6483
@item -p @var{file}
 
6484
True if @var{file} exists and is a named pipe (FIFO).
 
6485
 
 
6486
@item -r @var{file}
 
6487
True if @var{file} exists and is readable.
 
6488
 
 
6489
@item -s @var{file}
 
6490
True if @var{file} exists and has a size greater than zero.
 
6491
 
 
6492
@item -t @var{fd}
 
6493
True if file descriptor @var{fd} is open and refers to a terminal.
 
6494
 
 
6495
@item -u @var{file}
 
6496
True if @var{file} exists and its set-user-id bit is set.
 
6497
 
 
6498
@item -w @var{file}
 
6499
True if @var{file} exists and is writable.
 
6500
 
 
6501
@item -x @var{file}
 
6502
True if @var{file} exists and is executable.
 
6503
 
 
6504
@item -G @var{file}
 
6505
True if @var{file} exists and is owned by the effective group id.
 
6506
 
 
6507
@item -L @var{file}
 
6508
True if @var{file} exists and is a symbolic link.
 
6509
 
 
6510
@item -N @var{file}
 
6511
True if @var{file} exists and has been modified since it was last read.
 
6512
 
 
6513
@item -O @var{file}
 
6514
True if @var{file} exists and is owned by the effective user id.
 
6515
 
 
6516
@item -S @var{file}
 
6517
True if @var{file} exists and is a socket.
 
6518
 
 
6519
@item @var{file1} -ef @var{file2}
 
6520
True if @var{file1} and @var{file2} refer to the same device and
 
6521
inode numbers.
 
6522
 
 
6523
@item @var{file1} -nt @var{file2}
 
6524
True if @var{file1} is newer (according to modification date)
 
6525
than @var{file2}, or if @var{file1} exists and @var{file2} does not.
 
6526
 
 
6527
@item @var{file1} -ot @var{file2}
 
6528
True if @var{file1} is older than @var{file2},
 
6529
or if @var{file2} exists and @var{file1} does not.
 
6530
 
 
6531
@item -o @var{optname}
 
6532
True if the shell option @var{optname} is enabled.
 
6533
The list of options appears in the description of the @option{-o}
 
6534
option to the @code{set} builtin (@pxref{The Set Builtin}).
 
6535
 
 
6536
@item -v @var{varname}
 
6537
True if the shell variable @var{varname} is set (has been assigned a value).
 
6538
 
 
6539
@item -R @var{varname}
 
6540
True if the shell variable @var{varname} is set and is a name reference.
 
6541
 
 
6542
@item -z @var{string}
 
6543
True if the length of @var{string} is zero.
 
6544
 
 
6545
@item -n @var{string}
 
6546
@itemx @var{string}
 
6547
True if the length of @var{string} is non-zero.
 
6548
 
 
6549
@item @var{string1} == @var{string2}
 
6550
@itemx @var{string1} = @var{string2}
 
6551
True if the strings are equal.
 
6552
When used with the @code{[[} command, this performs pattern matching as
 
6553
described above (@pxref{Conditional Constructs}).
 
6554
 
 
6555
@samp{=} should be used with the @code{test} command for @sc{posix} conformance.
 
6556
 
 
6557
@item @var{string1} != @var{string2}
 
6558
True if the strings are not equal.
 
6559
 
 
6560
@item @var{string1} < @var{string2}
 
6561
True if @var{string1} sorts before @var{string2} lexicographically.
 
6562
 
 
6563
@item @var{string1} > @var{string2}
 
6564
True if @var{string1} sorts after @var{string2} lexicographically.
 
6565
 
 
6566
@item @var{arg1} OP @var{arg2}
 
6567
@code{OP} is one of 
 
6568
@samp{-eq}, @samp{-ne}, @samp{-lt}, @samp{-le}, @samp{-gt}, or @samp{-ge}.
 
6569
These arithmetic binary operators return true if @var{arg1}
 
6570
is equal to, not equal to, less than, less than or equal to,
 
6571
greater than, or greater than or equal to @var{arg2},
 
6572
respectively.  @var{Arg1} and @var{arg2}
 
6573
may be positive or negative integers.
 
6574
@end table
 
6575
 
 
6576
@node Shell Arithmetic
 
6577
@section Shell Arithmetic
 
6578
@cindex arithmetic, shell
 
6579
@cindex shell arithmetic
 
6580
@cindex expressions, arithmetic
 
6581
@cindex evaluation, arithmetic
 
6582
@cindex arithmetic evaluation
 
6583
 
 
6584
The shell allows arithmetic expressions to be evaluated, as one of
 
6585
the shell expansions or by the @code{let} and the @option{-i} option
 
6586
to the @code{declare} builtins.
 
6587
 
 
6588
Evaluation is done in fixed-width integers with no check for overflow,
 
6589
though division by 0 is trapped and flagged as an error.
 
6590
The operators and their precedence, associativity, and values
 
6591
are the same as in the C language.
 
6592
The following list of operators is grouped into levels of
 
6593
equal-precedence operators.
 
6594
The levels are listed in order of decreasing precedence. 
 
6595
 
 
6596
@table @code
 
6597
 
 
6598
@item @var{id}++ @var{id}--
 
6599
variable post-increment and post-decrement 
 
6600
 
 
6601
@item ++@var{id} --@var{id}
 
6602
variable pre-increment and pre-decrement
 
6603
 
 
6604
@item - +
 
6605
unary minus and plus
 
6606
 
 
6607
@item ! ~
 
6608
logical and bitwise negation
 
6609
 
 
6610
@item **
 
6611
exponentiation
 
6612
 
 
6613
@item * / %
 
6614
multiplication, division, remainder
 
6615
 
 
6616
@item + -
 
6617
addition, subtraction
 
6618
 
 
6619
@item << >>
 
6620
left and right bitwise shifts
 
6621
 
 
6622
@item <= >= < >
 
6623
comparison
 
6624
 
 
6625
@item == !=
 
6626
equality and inequality
 
6627
 
 
6628
@item &
 
6629
bitwise AND
 
6630
 
 
6631
@item ^
 
6632
bitwise exclusive OR
 
6633
 
 
6634
@item |
 
6635
bitwise OR
 
6636
 
 
6637
@item &&
 
6638
logical AND
 
6639
 
 
6640
@item ||
 
6641
logical OR
 
6642
 
 
6643
@item expr ? expr : expr
 
6644
conditional operator
 
6645
 
 
6646
@item = *= /= %= += -= <<= >>= &= ^= |=
 
6647
assignment
 
6648
 
 
6649
@item expr1 , expr2
 
6650
comma
 
6651
@end table
 
6652
 
 
6653
Shell variables are allowed as operands; parameter expansion is
 
6654
performed before the expression is evaluated. 
 
6655
Within an expression, shell variables may also be referenced by name
 
6656
without using the parameter expansion syntax.
 
6657
A shell variable that is null or unset evaluates to 0 when referenced
 
6658
by name without using the parameter expansion syntax.
 
6659
The value of a variable is evaluated as an arithmetic expression
 
6660
when it is referenced, or when a variable which has been given the  
 
6661
@var{integer} attribute using @samp{declare -i} is assigned a value.
 
6662
A null value evaluates to 0.
 
6663
A shell variable need not have its @var{integer} attribute turned on
 
6664
to be used in an expression.
 
6665
 
 
6666
Constants with a leading 0 are interpreted as octal numbers.
 
6667
A leading @samp{0x} or @samp{0X} denotes hexadecimal.  Otherwise,
 
6668
numbers take the form [@var{base}@code{#}]@var{n}, where the optional @var{base}
 
6669
is a decimal number between 2 and 64 representing the arithmetic
 
6670
base, and @var{n} is a number in that base.
 
6671
If @var{base}@code{#} is omitted, then base 10 is used.
 
6672
When specifying @var{n},
 
6673
he digits greater than 9 are represented by the lowercase letters,
 
6674
the uppercase letters, @samp{@@}, and @samp{_}, in that order.
 
6675
If @var{base} is less than or equal to 36, lowercase and uppercase
 
6676
letters may be used interchangeably to represent numbers between 10
 
6677
and 35.
 
6678
 
 
6679
Operators are evaluated in order of precedence.  Sub-expressions in
 
6680
parentheses are evaluated first and may override the precedence
 
6681
rules above.
 
6682
 
 
6683
@node Aliases
 
6684
@section Aliases
 
6685
@cindex alias expansion
 
6686
 
 
6687
@var{Aliases} allow a string to be substituted for a word when it is used
 
6688
as the first word of a simple command.
 
6689
The shell maintains a list of aliases that may be set and unset with
 
6690
the @code{alias} and @code{unalias} builtin commands.
 
6691
 
 
6692
The first word of each simple command, if unquoted, is checked to see
 
6693
if it has an alias.
 
6694
If so, that word is replaced by the text of the alias.
 
6695
The characters @samp{/}, @samp{$}, @samp{`}, @samp{=} and any of the
 
6696
shell metacharacters or quoting characters listed above may not appear
 
6697
in an alias name.
 
6698
The replacement text may contain any valid
 
6699
shell input, including shell metacharacters.
 
6700
The first word of the replacement text is tested for
 
6701
aliases, but a word that is identical to an alias being expanded
 
6702
is not expanded a second time.
 
6703
This means that one may alias @code{ls} to @code{"ls -F"},
 
6704
for instance, and Bash does not try to recursively expand the
 
6705
replacement text.
 
6706
If the last character of the alias value is a
 
6707
@var{blank}, then the next command word following the
 
6708
alias is also checked for alias expansion.
 
6709
 
 
6710
Aliases are created and listed with the @code{alias}
 
6711
command, and removed with the @code{unalias} command.
 
6712
 
 
6713
There is no mechanism for using arguments in the replacement text,
 
6714
as in @code{csh}.
 
6715
If arguments are needed, a shell function should be used
 
6716
(@pxref{Shell Functions}).
 
6717
 
 
6718
Aliases are not expanded when the shell is not interactive,
 
6719
unless the @code{expand_aliases} shell option is set using
 
6720
@code{shopt} (@pxref{The Shopt Builtin}).
 
6721
 
 
6722
The rules concerning the definition and use of aliases are
 
6723
somewhat confusing.  Bash
 
6724
always reads at least one complete line
 
6725
of input before executing any
 
6726
of the commands on that line.  Aliases are expanded when a
 
6727
command is read, not when it is executed.  Therefore, an
 
6728
alias definition appearing on the same line as another
 
6729
command does not take effect until the next line of input is read.
 
6730
The commands following the alias definition
 
6731
on that line are not affected by the new alias.
 
6732
This behavior is also an issue when functions are executed.
 
6733
Aliases are expanded when a function definition is read,
 
6734
not when the function is executed, because a function definition
 
6735
is itself a compound command.  As a consequence, aliases
 
6736
defined in a function are not available until after that
 
6737
function is executed.  To be safe, always put
 
6738
alias definitions on a separate line, and do not use @code{alias}
 
6739
in compound commands.
 
6740
 
 
6741
For almost every purpose, shell functions are preferred over aliases.
 
6742
 
 
6743
@node Arrays
 
6744
@section Arrays
 
6745
@cindex arrays
 
6746
 
 
6747
Bash provides one-dimensional indexed and associative array variables.
 
6748
Any variable may be used as an indexed array;
 
6749
the @code{declare} builtin will explicitly declare an array.
 
6750
There is no maximum
 
6751
limit on the size of an array, nor any requirement that members
 
6752
be indexed or assigned contiguously.
 
6753
Indexed arrays are referenced using integers (including arithmetic
 
6754
expressions (@pxref{Shell Arithmetic})) and are zero-based;
 
6755
associative arrays use arbitrary strings.
 
6756
Unless otherwise noted, indexed array indices must be non-negative integers.
 
6757
 
 
6758
An indexed array is created automatically if any variable is assigned to
 
6759
using the syntax
 
6760
@example
 
6761
@var{name}[@var{subscript}]=@var{value}
 
6762
@end example
 
6763
 
 
6764
@noindent
 
6765
The @var{subscript}
 
6766
is treated as an arithmetic expression that must evaluate to a number.
 
6767
To explicitly declare an array, use
 
6768
@example
 
6769
declare -a @var{name}
 
6770
@end example
 
6771
@noindent
 
6772
The syntax
 
6773
@example
 
6774
declare -a @var{name}[@var{subscript}]
 
6775
@end example
 
6776
@noindent
 
6777
is also accepted; the @var{subscript} is ignored.
 
6778
 
 
6779
@noindent
 
6780
Associative arrays are created using
 
6781
@example
 
6782
declare -A @var{name}.
 
6783
@end example
 
6784
 
 
6785
Attributes may be
 
6786
specified for an array variable using the @code{declare} and
 
6787
@code{readonly} builtins.  Each attribute applies to all members of
 
6788
an array.
 
6789
 
 
6790
Arrays are assigned to using compound assignments of the form
 
6791
@example
 
6792
@var{name}=(@var{value1} @var{value2} @dots{} )
 
6793
@end example
 
6794
@noindent
 
6795
where each
 
6796
@var{value} is of the form @code{[@var{subscript}]=}@var{string}.
 
6797
Indexed array assignments do not require anything but @var{string}.
 
6798
When assigning to indexed arrays, if
 
6799
the optional subscript is supplied, that index is assigned to;
 
6800
otherwise the index of the element assigned is the last index assigned
 
6801
to by the statement plus one.  Indexing starts at zero.
 
6802
 
 
6803
When assigning to an associative array, the subscript is required.
 
6804
 
 
6805
This syntax is also accepted by the @code{declare}
 
6806
builtin.  Individual array elements may be assigned to using the
 
6807
@code{@var{name}[@var{subscript}]=@var{value}} syntax introduced above.
 
6808
 
 
6809
When assigning to an indexed array, if @var{name}
 
6810
is subscripted by a negative number, that number is
 
6811
interpreted as relative to one greater than the maximum index of
 
6812
@var{name}, so negative indices count back from the end of the
 
6813
array, and an index of -1 references the last element.
 
6814
 
 
6815
Any element of an array may be referenced using
 
6816
@code{$@{@var{name}[@var{subscript}]@}}.
 
6817
The braces are required to avoid
 
6818
conflicts with the shell's filename expansion operators.  If the
 
6819
@var{subscript} is @samp{@@} or @samp{*}, the word expands to all members
 
6820
of the array @var{name}.  These subscripts differ only when the word
 
6821
appears within double quotes.
 
6822
If the word is double-quoted,
 
6823
@code{$@{@var{name}[*]@}} expands to a single word with
 
6824
the value of each array member separated by the first character of the
 
6825
@env{IFS} variable, and @code{$@{@var{name}[@@]@}} expands each element of
 
6826
@var{name} to a separate word.  When there are no array members,
 
6827
@code{$@{@var{name}[@@]@}} expands to nothing.
 
6828
If the double-quoted expansion occurs within a word, the expansion of
 
6829
the first parameter is joined with the beginning part of the original
 
6830
word, and the expansion of the last parameter is joined with the last
 
6831
part of the original word.
 
6832
This is analogous to the
 
6833
expansion of the special parameters @samp{@@} and @samp{*}. 
 
6834
@code{$@{#@var{name}[@var{subscript}]@}} expands to the length of
 
6835
@code{$@{@var{name}[@var{subscript}]@}}.
 
6836
If @var{subscript} is @samp{@@} or
 
6837
@samp{*}, the expansion is the number of elements in the array. 
 
6838
Referencing an array variable without a subscript is equivalent to
 
6839
referencing with a subscript of 0. 
 
6840
If the @var{subscript}
 
6841
used to reference an element of an indexed array
 
6842
evaluates to a number less than zero, it is 
 
6843
interpreted as relative to one greater than the maximum index of the array,
 
6844
so negative indices count back from the end of the array,
 
6845
and an index of -1 refers to the last element.
 
6846
 
 
6847
An array variable is considered set if a subscript has been assigned a
 
6848
value.  The null string is a valid value.
 
6849
 
 
6850
It is possible to obtain the keys (indices) of an array as well as the values.
 
6851
$@{!@var{name}[@@]@} and $@{!@var{name}[*]@} expand to the indices
 
6852
assigned in array variable @var{name}.
 
6853
The treatment when in double quotes is similar to the expansion of the
 
6854
special parameters @samp{@@} and @samp{*} within double quotes.
 
6855
 
 
6856
The @code{unset} builtin is used to destroy arrays.
 
6857
@code{unset @var{name}[@var{subscript}]}
 
6858
destroys the array element at index @var{subscript}.
 
6859
Negative subscripts to indexed arrays are interpreted as described above.
 
6860
Care must be taken to avoid unwanted side effects caused by filename
 
6861
expansion.
 
6862
@code{unset @var{name}}, where @var{name} is an array, removes the
 
6863
entire array.  A subscript of @samp{*} or @samp{@@} also removes the
 
6864
entire array.
 
6865
 
 
6866
The @code{declare}, @code{local}, and @code{readonly}
 
6867
builtins each accept a @option{-a} option to specify an indexed
 
6868
array and a @option{-A} option to specify an associative array.
 
6869
If both options are supplied, @option{-A} takes precedence.
 
6870
The @code{read} builtin accepts a @option{-a}
 
6871
option to assign a list of words read from the standard input
 
6872
to an array, and can read values from the standard input into
 
6873
individual array elements.  The @code{set} and @code{declare}
 
6874
builtins display array values in a way that allows them to be
 
6875
reused as input.
 
6876
 
 
6877
@node The Directory Stack
 
6878
@section The Directory Stack
 
6879
@cindex directory stack
 
6880
 
 
6881
@menu
 
6882
* Directory Stack Builtins::            Bash builtin commands to manipulate
 
6883
                                        the directory stack.
 
6884
@end menu
 
6885
 
 
6886
The directory stack is a list of recently-visited directories.  The
 
6887
@code{pushd} builtin adds directories to the stack as it changes
 
6888
the current directory, and the @code{popd} builtin removes specified
 
6889
directories from the stack and changes the current directory to
 
6890
the directory removed.  The @code{dirs} builtin displays the contents
 
6891
of the directory stack.
 
6892
 
 
6893
The contents of the directory stack are also visible
 
6894
as the value of the @env{DIRSTACK} shell variable.
 
6895
 
 
6896
@node Directory Stack Builtins
 
6897
@subsection Directory Stack Builtins
 
6898
 
 
6899
@table @code
 
6900
 
 
6901
@item dirs
 
6902
@btindex dirs
 
6903
@example
 
6904
dirs [-clpv] [+@var{N} | -@var{N}]
 
6905
@end example
 
6906
 
 
6907
Display the list of currently remembered directories.  Directories
 
6908
are added to the list with the @code{pushd} command; the
 
6909
@code{popd} command removes directories from the list.
 
6910
 
 
6911
@table @code
 
6912
@item -c
 
6913
Clears the directory stack by deleting all of the elements.
 
6914
@item -l
 
6915
Produces a listing using full pathnames;
 
6916
the default listing format uses a tilde to denote the home directory.
 
6917
@item -p
 
6918
Causes @code{dirs} to print the directory stack with one entry per
 
6919
line.
 
6920
@item -v
 
6921
Causes @code{dirs} to print the directory stack with one entry per
 
6922
line, prefixing each entry with its index in the stack.
 
6923
@item +@var{N}
 
6924
Displays the @var{N}th directory (counting from the left of the
 
6925
list printed by @code{dirs} when invoked without options), starting
 
6926
with zero.
 
6927
@item -@var{N}
 
6928
Displays the @var{N}th directory (counting from the right of the
 
6929
list printed by @code{dirs} when invoked without options), starting
 
6930
with zero.
 
6931
@end table
 
6932
 
 
6933
@item popd
 
6934
@btindex popd
 
6935
@example
 
6936
popd [-n] [+@var{N} | -@var{N}]
 
6937
@end example
 
6938
 
 
6939
Remove the top entry from the directory stack, and @code{cd}
 
6940
to the new top directory.
 
6941
When no arguments are given, @code{popd}
 
6942
removes the top directory from the stack and
 
6943
performs a @code{cd} to the new top directory.  The
 
6944
elements are numbered from 0 starting at the first directory listed with
 
6945
@code{dirs}; that is, @code{popd} is equivalent to @code{popd +0}.
 
6946
 
 
6947
@table @code
 
6948
@item -n
 
6949
Suppresses the normal change of directory when removing directories
 
6950
from the stack, so that only the stack is manipulated.
 
6951
@item +@var{N}
 
6952
Removes the @var{N}th directory (counting from the left of the
 
6953
list printed by @code{dirs}), starting with zero.
 
6954
@item -@var{N}
 
6955
Removes the @var{N}th directory (counting from the right of the
 
6956
list printed by @code{dirs}), starting with zero.
 
6957
@end table
 
6958
 
 
6959
@btindex pushd
 
6960
@item pushd
 
6961
@example
 
6962
pushd [-n] [@var{+N} | @var{-N} | @var{dir}]
 
6963
@end example
 
6964
 
 
6965
Save the current directory on the top of the directory stack
 
6966
and then @code{cd} to @var{dir}.
 
6967
With no arguments, @code{pushd} exchanges the top two directories.
 
6968
 
 
6969
@table @code
 
6970
@item -n
 
6971
Suppresses the normal change of directory when adding directories
 
6972
to the stack, so that only the stack is manipulated.
 
6973
@item +@var{N}
 
6974
Brings the @var{N}th directory (counting from the left of the
 
6975
list printed by @code{dirs}, starting with zero) to the top of
 
6976
the list by rotating the stack.
 
6977
@item -@var{N}
 
6978
Brings the @var{N}th directory (counting from the right of the
 
6979
list printed by @code{dirs}, starting with zero) to the top of
 
6980
the list by rotating the stack.
 
6981
@item @var{dir}
 
6982
Makes the current working directory be the top of the stack, making
 
6983
it the new current directory as if it had been supplied as an argument
 
6984
to the @code{cd} builtin.
 
6985
@end table
 
6986
@end table
 
6987
 
 
6988
@node Controlling the Prompt
 
6989
@section Controlling the Prompt
 
6990
@cindex prompting
 
6991
 
 
6992
The value of the variable @env{PROMPT_COMMAND} is examined just before
 
6993
Bash prints each primary prompt.  If @env{PROMPT_COMMAND} is set and
 
6994
has a non-null value, then the
 
6995
value is executed just as if it had been typed on the command line.
 
6996
 
 
6997
In addition, the following table describes the special characters which
 
6998
can appear in the prompt variables @env{PS1} to @env{PS4}:
 
6999
 
 
7000
@table @code
 
7001
@item \a
 
7002
A bell character.
 
7003
@item \d
 
7004
The date, in "Weekday Month Date" format (e.g., "Tue May 26").
 
7005
@item \D@{@var{format}@}
 
7006
The @var{format} is passed to @code{strftime}(3) and the result is inserted
 
7007
into the prompt string; an empty @var{format} results in a locale-specific
 
7008
time representation.  The braces are required.
 
7009
@item \e
 
7010
An escape character.
 
7011
@item \h
 
7012
The hostname, up to the first `.'.
 
7013
@item \H
 
7014
The hostname.
 
7015
@item \j
 
7016
The number of jobs currently managed by the shell.
 
7017
@item \l
 
7018
The basename of the shell's terminal device name.
 
7019
@item \n
 
7020
A newline.
 
7021
@item \r
 
7022
A carriage return.
 
7023
@item \s
 
7024
The name of the shell, the basename of @code{$0} (the portion
 
7025
following the final slash).
 
7026
@item \t
 
7027
The time, in 24-hour HH:MM:SS format.
 
7028
@item \T
 
7029
The time, in 12-hour HH:MM:SS format.
 
7030
@item \@@
 
7031
The time, in 12-hour am/pm format.
 
7032
@item \A
 
7033
The time, in 24-hour HH:MM format.
 
7034
@item \u
 
7035
The username of the current user.
 
7036
@item \v
 
7037
The version of Bash (e.g., 2.00)          
 
7038
@item \V
 
7039
The release of Bash, version + patchlevel (e.g., 2.00.0)
 
7040
@item \w
 
7041
The current working directory, with @env{$HOME} abbreviated with a tilde
 
7042
(uses the @env{$PROMPT_DIRTRIM} variable).
 
7043
@item \W
 
7044
The basename of @env{$PWD}, with @env{$HOME} abbreviated with a tilde.
 
7045
@item \!
 
7046
The history number of this command.
 
7047
@item \#
 
7048
The command number of this command.
 
7049
@item \$
 
7050
If the effective uid is 0, @code{#}, otherwise @code{$}.
 
7051
@item \@var{nnn}
 
7052
The character whose ASCII code is the octal value @var{nnn}.
 
7053
@item \\
 
7054
A backslash.
 
7055
@item \[
 
7056
Begin a sequence of non-printing characters.  This could be used to
 
7057
embed a terminal control sequence into the prompt.
 
7058
@item \]
 
7059
End a sequence of non-printing characters.
 
7060
@end table
 
7061
 
 
7062
The command number and the history number are usually different:
 
7063
the history number of a command is its position in the history
 
7064
list, which may include commands restored from the history file
 
7065
(@pxref{Bash History Facilities}), while the command number is
 
7066
the position in the sequence of commands executed during the current
 
7067
shell session.
 
7068
 
 
7069
After the string is decoded, it is expanded via
 
7070
parameter expansion, command substitution, arithmetic
 
7071
expansion, and quote removal, subject to the value of the
 
7072
@code{promptvars} shell option (@pxref{Bash Builtins}).
 
7073
 
 
7074
@node The Restricted Shell
 
7075
@section The Restricted Shell
 
7076
@cindex restricted shell
 
7077
 
 
7078
If Bash is started with the name @code{rbash}, or the
 
7079
@option{--restricted}
 
7080
or
 
7081
@option{-r}
 
7082
option is supplied at invocation, the shell becomes restricted.
 
7083
A restricted shell is used to
 
7084
set up an environment more controlled than the standard shell.
 
7085
A restricted shell behaves identically to @code{bash}
 
7086
with the exception that the following are disallowed or not performed:
 
7087
 
 
7088
@itemize @bullet
 
7089
@item
 
7090
Changing directories with the @code{cd} builtin.
 
7091
@item
 
7092
Setting or unsetting the values of the @env{SHELL}, @env{PATH},
 
7093
@env{ENV}, or @env{BASH_ENV} variables.
 
7094
@item
 
7095
Specifying command names containing slashes.
 
7096
@item
 
7097
Specifying a filename containing a slash as an argument to the @code{.}
 
7098
builtin command.
 
7099
@item
 
7100
Specifying a filename containing a slash as an argument to the @option{-p}
 
7101
option to the @code{hash} builtin command.
 
7102
@item
 
7103
Importing function definitions from the shell environment at startup.
 
7104
@item
 
7105
Parsing the value of @env{SHELLOPTS} from the shell environment at startup.
 
7106
@item
 
7107
Redirecting output using the @samp{>}, @samp{>|}, @samp{<>}, @samp{>&},
 
7108
@samp{&>}, and @samp{>>} redirection operators.
 
7109
@item
 
7110
Using the @code{exec} builtin to replace the shell with another command.
 
7111
@item
 
7112
Adding or deleting builtin commands with the
 
7113
@option{-f} and @option{-d} options to the @code{enable} builtin.
 
7114
@item
 
7115
Using the @code{enable} builtin command to enable disabled shell builtins.
 
7116
@item
 
7117
Specifying the @option{-p} option to the @code{command} builtin.
 
7118
@item
 
7119
Turning off restricted mode with @samp{set +r} or @samp{set +o restricted}.
 
7120
@end itemize
 
7121
 
 
7122
These restrictions are enforced after any startup files are read.
 
7123
 
 
7124
When a command that is found to be a shell script is executed
 
7125
(@pxref{Shell Scripts}), @code{rbash} turns off any restrictions in
 
7126
the shell spawned to execute the script.
 
7127
 
 
7128
@node Bash POSIX Mode
 
7129
@section Bash POSIX Mode
 
7130
@cindex POSIX Mode
 
7131
 
 
7132
Starting Bash with the @option{--posix} command-line option or executing
 
7133
@samp{set -o posix} while Bash is running will cause Bash to conform more
 
7134
closely to the @sc{posix} standard by changing the behavior to
 
7135
match that specified by @sc{posix} in areas where the Bash default differs.
 
7136
 
 
7137
When invoked as @code{sh}, Bash enters @sc{posix} mode after reading the
 
7138
startup files.
 
7139
 
 
7140
The following list is what's changed when `@sc{posix} mode' is in effect:
 
7141
 
 
7142
@enumerate
 
7143
@item
 
7144
When a command in the hash table no longer exists, Bash will re-search
 
7145
@env{$PATH} to find the new location.  This is also available with
 
7146
@samp{shopt -s checkhash}.
 
7147
 
 
7148
@item
 
7149
The message printed by the job control code and builtins when a job
 
7150
exits with a non-zero status is `Done(status)'.
 
7151
 
 
7152
@item
 
7153
The message printed by the job control code and builtins when a job
 
7154
is stopped is `Stopped(@var{signame})', where @var{signame} is, for
 
7155
example, @code{SIGTSTP}.
 
7156
 
 
7157
@item
 
7158
The @code{bg} builtin uses the required format to describe each job placed
 
7159
in the background, which does not include an indication of whether the job
 
7160
is the current or previous job.
 
7161
 
 
7162
@item
 
7163
Reserved words appearing in a context where reserved words are recognized
 
7164
do not undergo alias expansion.
 
7165
 
 
7166
@item
 
7167
The @sc{posix} @env{PS1} and @env{PS2} expansions of @samp{!} to
 
7168
the history number and @samp{!!} to @samp{!} are enabled,
 
7169
and parameter expansion is performed on the values of @env{PS1} and
 
7170
@env{PS2} regardless of the setting of the @code{promptvars} option.
 
7171
 
 
7172
@item
 
7173
The @sc{posix} startup files are executed (@env{$ENV}) rather than
 
7174
the normal Bash files.
 
7175
 
 
7176
@item
 
7177
Tilde expansion is only performed on assignments preceding a command
 
7178
name, rather than on all assignment statements on the line.
 
7179
 
 
7180
@item
 
7181
The @code{command} builtin does not prevent builtins that take assignment
 
7182
statements as arguments from expanding them as assignment statements;
 
7183
when not in @sc{posix} mode, assignment builtins lose their assignment
 
7184
statement expansion properties when preceded by @code{command}.
 
7185
 
 
7186
@item
 
7187
The default history file is @file{~/.sh_history} (this is the
 
7188
default value of @env{$HISTFILE}).
 
7189
 
 
7190
@item
 
7191
The output of @samp{kill -l} prints all the signal names on a single line,
 
7192
separated by spaces, without the @samp{SIG} prefix.
 
7193
 
 
7194
@item
 
7195
The @code{kill} builtin does not accept signal names with a @samp{SIG}
 
7196
prefix.
 
7197
 
 
7198
@item
 
7199
Non-interactive shells exit if @var{filename} in @code{.} @var{filename}
 
7200
is not found.
 
7201
 
 
7202
@item
 
7203
Non-interactive shells exit if a syntax error in an arithmetic expansion
 
7204
results in an invalid expression.
 
7205
 
 
7206
@item
 
7207
Non-interactive shells exit if there is a syntax error in a script read
 
7208
with the @code{.} or @code{source} builtins, or in a string processed by
 
7209
the @code{eval} builtin.
 
7210
 
 
7211
@item
 
7212
Redirection operators do not perform filename expansion on the word
 
7213
in the redirection unless the shell is interactive.
 
7214
 
 
7215
@item
 
7216
Redirection operators do not perform word splitting on the word in the
 
7217
redirection.
 
7218
 
 
7219
@item
 
7220
Function names must be valid shell @code{name}s.  That is, they may not
 
7221
contain characters other than letters, digits, and underscores, and
 
7222
may not start with a digit.  Declaring a function with an invalid name
 
7223
causes a fatal syntax error in non-interactive shells.
 
7224
 
 
7225
@item
 
7226
Function names may not be the same as one of the @sc{posix} special
 
7227
builtins.
 
7228
 
 
7229
@item
 
7230
@sc{posix} special builtins are found before shell functions
 
7231
during command lookup.
 
7232
 
 
7233
@item
 
7234
The @code{time} reserved word may be used by itself as a command.  When
 
7235
used in this way, it displays timing statistics for the shell and its
 
7236
completed children.  The @env{TIMEFORMAT} variable controls the format
 
7237
of the timing information.
 
7238
 
 
7239
@item
 
7240
When parsing and expanding a $@{@dots{}@} expansion that appears within
 
7241
double quotes, single quotes are no longer special and cannot be used to
 
7242
quote a closing brace or other special character, unless the operator is
 
7243
one of those defined to perform pattern removal.  In this case, they do
 
7244
not have to appear as matched pairs.
 
7245
 
 
7246
@item
 
7247
The parser does not recognize @code{time} as a reserved word if the next
 
7248
token begins with a @samp{-}.
 
7249
 
 
7250
@item
 
7251
If a @sc{posix} special builtin returns an error status, a
 
7252
non-interactive shell exits.  The fatal errors are those listed in
 
7253
the @sc{posix} standard, and include things like passing incorrect options,
 
7254
redirection errors, variable assignment errors for assignments preceding
 
7255
the command name, and so on.
 
7256
 
 
7257
@item
 
7258
A non-interactive shell exits with an error status if a variable
 
7259
assignment error occurs when no command name follows the assignment
 
7260
statements.
 
7261
A variable assignment error occurs, for example, when trying to assign
 
7262
a value to a readonly variable.
 
7263
 
 
7264
@item
 
7265
A non-interactive shell exits with an error status if a variable
 
7266
assignment error occurs in an assignment statement preceding a special
 
7267
builtin, but not with any other simple command.
 
7268
 
 
7269
@item
 
7270
A non-interactive shell exits with an error status if the iteration
 
7271
variable in a @code{for} statement or the selection variable in a
 
7272
@code{select} statement is a readonly variable.
 
7273
 
 
7274
@item
 
7275
Process substitution is not available.
 
7276
 
 
7277
@item
 
7278
While variable indirection is available, it may not be applied to the
 
7279
@samp{#} and @samp{?} special parameters.
 
7280
 
 
7281
@item
 
7282
Assignment statements preceding @sc{posix} special builtins
 
7283
persist in the shell environment after the builtin completes.
 
7284
 
 
7285
@item
 
7286
Assignment statements preceding shell function calls persist in the
 
7287
shell environment after the function returns, as if a @sc{posix}
 
7288
special builtin command had been executed.
 
7289
 
 
7290
@item
 
7291
The @code{export} and @code{readonly} builtin commands display their
 
7292
output in the format required by @sc{posix}.
 
7293
 
 
7294
@item
 
7295
The @code{trap} builtin displays signal names without the leading
 
7296
@code{SIG}.
 
7297
 
 
7298
@item
 
7299
The @code{trap} builtin doesn't check the first argument for a possible
 
7300
signal specification and revert the signal handling to the original
 
7301
disposition if it is, unless that argument consists solely of digits and
 
7302
is a valid signal number.  If users want to reset the handler for a given
 
7303
signal to the original disposition, they should use @samp{-} as the
 
7304
first argument.
 
7305
 
 
7306
@item
 
7307
The @code{.} and @code{source} builtins do not search the current directory
 
7308
for the filename argument if it is not found by searching @env{PATH}.
 
7309
 
 
7310
@item
 
7311
Subshells spawned to execute command substitutions inherit the value of
 
7312
the @option{-e} option from the parent shell.  When not in @sc{posix} mode,
 
7313
Bash clears the @option{-e} option in such subshells.
 
7314
 
 
7315
@item
 
7316
Alias expansion is always enabled, even in non-interactive shells.
 
7317
 
 
7318
@item
 
7319
When the @code{alias} builtin displays alias definitions, it does not
 
7320
display them with a leading @samp{alias } unless the @option{-p} option
 
7321
is supplied.
 
7322
 
 
7323
@item
 
7324
When the @code{set} builtin is invoked without options, it does not display
 
7325
shell function names and definitions.
 
7326
 
 
7327
@item
 
7328
When the @code{set} builtin is invoked without options, it displays
 
7329
variable values without quotes, unless they contain shell metacharacters,
 
7330
even if the result contains nonprinting characters.
 
7331
 
 
7332
@item
 
7333
When the @code{cd} builtin is invoked in @var{logical} mode, and the pathname
 
7334
constructed from @code{$PWD} and the directory name supplied as an argument
 
7335
does not refer to an existing directory, @code{cd} will fail instead of
 
7336
falling back to @var{physical} mode.
 
7337
 
 
7338
@item
 
7339
The @code{pwd} builtin verifies that the value it prints is the same as the
 
7340
current directory, even if it is not asked to check the file system with the
 
7341
@option{-P} option.
 
7342
 
 
7343
@item
 
7344
When listing the history, the @code{fc} builtin does not include an
 
7345
indication of whether or not a history entry has been modified.
 
7346
 
 
7347
@item
 
7348
The default editor used by @code{fc} is @code{ed}.
 
7349
 
 
7350
@item
 
7351
The @code{type} and @code{command} builtins will not report a non-executable
 
7352
file as having been found, though the shell will attempt to execute such a
 
7353
file if it is the only so-named file found in @code{$PATH}.
 
7354
 
 
7355
@item
 
7356
The @code{vi} editing mode will invoke the @code{vi} editor directly when
 
7357
the @samp{v} command is run, instead of checking @code{$VISUAL} and
 
7358
@code{$EDITOR}.
 
7359
 
 
7360
@item
 
7361
When the @code{xpg_echo} option is enabled, Bash does not attempt to interpret
 
7362
any arguments to @code{echo} as options.  Each argument is displayed, after
 
7363
escape characters are converted.
 
7364
 
 
7365
@item
 
7366
The @code{ulimit} builtin uses a block size of 512 bytes for the @option{-c}
 
7367
and @option{-f} options.
 
7368
 
 
7369
@item
 
7370
The arrival of @code{SIGCHLD}  when a trap is set on @code{SIGCHLD} does
 
7371
not interrupt the @code{wait} builtin and cause it to return immediately.
 
7372
The trap command is run once for each child that exits.
 
7373
 
 
7374
@item
 
7375
The @code{read} builtin may be interrupted by a signal for which a trap
 
7376
has been set.
 
7377
If Bash receives a trapped signal while executing @code{read}, the trap
 
7378
handler executes and @code{read} returns an exit status greater than 128.
 
7379
 
 
7380
@end enumerate
 
7381
 
 
7382
There is other @sc{posix} behavior that Bash does not implement by
 
7383
default even when in @sc{posix} mode.
 
7384
Specifically:
 
7385
 
 
7386
@enumerate
 
7387
 
 
7388
@item
 
7389
The @code{fc} builtin checks @code{$EDITOR} as a program to edit history
 
7390
entries if @code{FCEDIT} is unset, rather than defaulting directly to
 
7391
@code{ed}.  @code{fc} uses @code{ed} if @code{EDITOR} is unset.
 
7392
 
 
7393
@item
 
7394
As noted above, Bash requires the @code{xpg_echo} option to be enabled for
 
7395
the @code{echo} builtin to be fully conformant.
 
7396
 
 
7397
@end enumerate
 
7398
 
 
7399
Bash can be configured to be @sc{posix}-conformant by default, by specifying
 
7400
the @option{--enable-strict-posix-default} to @code{configure} when building
 
7401
(@pxref{Optional Features}).
 
7402
 
 
7403
@node Job Control
 
7404
@chapter Job Control
 
7405
 
 
7406
This chapter discusses what job control is, how it works, and how
 
7407
Bash allows you to access its facilities.
 
7408
 
 
7409
@menu
 
7410
* Job Control Basics::          How job control works.
 
7411
* Job Control Builtins::        Bash builtin commands used to interact
 
7412
                                with job control.
 
7413
* Job Control Variables::       Variables Bash uses to customize job
 
7414
                                control.
 
7415
@end menu
 
7416
 
 
7417
@node Job Control Basics
 
7418
@section Job Control Basics
 
7419
@cindex job control
 
7420
@cindex foreground
 
7421
@cindex background
 
7422
@cindex suspending jobs
 
7423
 
 
7424
Job control
 
7425
refers to the ability to selectively stop (suspend)
 
7426
the execution of processes and continue (resume)
 
7427
their execution at a later point.  A user typically employs
 
7428
this facility via an interactive interface supplied jointly
 
7429
by the operating system kernel's terminal driver and Bash.
 
7430
 
 
7431
The shell associates a @var{job} with each pipeline.  It keeps a
 
7432
table of currently executing jobs, which may be listed with the
 
7433
@code{jobs} command.  When Bash starts a job
 
7434
asynchronously, it prints a line that looks
 
7435
like:
 
7436
@example
 
7437
[1] 25647
 
7438
@end example
 
7439
@noindent
 
7440
indicating that this job is job number 1 and that the process @sc{id}
 
7441
of the last process in the pipeline associated with this job is
 
7442
25647.  All of the processes in a single pipeline are members of
 
7443
the same job.  Bash uses the @var{job} abstraction as the
 
7444
basis for job control. 
 
7445
 
 
7446
To facilitate the implementation of the user interface to job
 
7447
control, the operating system maintains the notion of a current terminal
 
7448
process group @sc{id}.  Members of this process group (processes whose
 
7449
process group @sc{id} is equal to the current terminal process group
 
7450
@sc{id}) receive keyboard-generated signals such as @code{SIGINT}. 
 
7451
These processes are said to be in the foreground.  Background
 
7452
processes are those whose process group @sc{id} differs from the
 
7453
terminal's; such processes are immune to keyboard-generated
 
7454
signals.  Only foreground processes are allowed to read from or, if
 
7455
the user so specifies with @code{stty tostop}, write to the terminal.
 
7456
Background processes which attempt to
 
7457
read from (write to when @code{stty tostop} is in effect) the
 
7458
terminal are sent a @code{SIGTTIN} (@code{SIGTTOU})
 
7459
signal by the kernel's terminal driver,
 
7460
which, unless caught, suspends the process. 
 
7461
 
 
7462
If the operating system on which Bash is running supports
 
7463
job control, Bash contains facilities to use it.  Typing the
 
7464
@var{suspend} character (typically @samp{^Z}, Control-Z) while a
 
7465
process is running causes that process to be stopped and returns
 
7466
control to Bash.  Typing the @var{delayed suspend} character
 
7467
(typically @samp{^Y}, Control-Y) causes the process to be stopped
 
7468
when it attempts to read input from the terminal, and control to
 
7469
be returned to Bash.  The user then manipulates the state of
 
7470
this job, using the @code{bg} command to continue it in the
 
7471
background, the @code{fg} command to continue it in the
 
7472
foreground, or the @code{kill} command to kill it.  A @samp{^Z}
 
7473
takes effect immediately, and has the additional side effect of
 
7474
causing pending output and typeahead to be discarded. 
 
7475
 
 
7476
There are a number of ways to refer to a job in the shell.  The
 
7477
character @samp{%} introduces a job specification (@var{jobspec}).
 
7478
 
 
7479
Job number @code{n} may be referred to as @samp{%n}.
 
7480
The symbols @samp{%%} and  @samp{%+} refer to the shell's notion of the
 
7481
current job, which is the last job stopped while it was in the foreground
 
7482
or started in the background.
 
7483
A single @samp{%} (with no accompanying job specification) also refers
 
7484
to the current job.
 
7485
The previous job may be referenced using @samp{%-}.
 
7486
If there is only a single job, @samp{%+} and @samp{%-} can both be used
 
7487
to refer to that job.
 
7488
In output pertaining to jobs (e.g., the output of the @code{jobs}
 
7489
command), the current job is always flagged with a @samp{+}, and the
 
7490
previous job with a @samp{-}. 
 
7491
 
 
7492
A job may also be referred to
 
7493
using a prefix of the name used to start it, or using a substring
 
7494
that appears in its command line.  For example, @samp{%ce} refers
 
7495
to a stopped @code{ce} job.  Using @samp{%?ce}, on the
 
7496
other hand, refers to any job containing the string @samp{ce} in
 
7497
its command line.  If the prefix or substring matches more than one job,
 
7498
Bash reports an error.
 
7499
 
 
7500
Simply naming a job can be used to bring it into the foreground:
 
7501
@samp{%1} is a synonym for @samp{fg %1}, bringing job 1 from the
 
7502
background into the foreground.  Similarly, @samp{%1 &} resumes
 
7503
job 1 in the background, equivalent to @samp{bg %1}
 
7504
 
 
7505
The shell learns immediately whenever a job changes state. 
 
7506
Normally, Bash waits until it is about to print a prompt
 
7507
before reporting changes in a job's status so as to not interrupt
 
7508
any other output.
 
7509
If the @option{-b} option to the @code{set} builtin is enabled,
 
7510
Bash reports such changes immediately (@pxref{The Set Builtin}).
 
7511
Any trap on @code{SIGCHLD} is executed for each child process
 
7512
that exits.
 
7513
 
 
7514
If an attempt to exit Bash is made while jobs are stopped, (or running, if
 
7515
the @code{checkjobs} option is enabled -- see @ref{The Shopt Builtin}), the
 
7516
shell prints a warning message, and if the @code{checkjobs} option is
 
7517
enabled, lists the jobs and their statuses.
 
7518
The @code{jobs} command may then be used to inspect their status.
 
7519
If a second attempt to exit is made without an intervening command,
 
7520
Bash does not print another warning, and any stopped jobs are terminated.
 
7521
 
 
7522
@node Job Control Builtins
 
7523
@section Job Control Builtins
 
7524
 
 
7525
@table @code
 
7526
 
 
7527
@item bg
 
7528
@btindex bg
 
7529
@example
 
7530
bg [@var{jobspec} @dots{}]
 
7531
@end example
 
7532
 
 
7533
Resume each suspended job @var{jobspec} in the background, as if it
 
7534
had been started with @samp{&}.
 
7535
If @var{jobspec} is not supplied, the current job is used.
 
7536
The return status is zero unless it is run when job control is not
 
7537
enabled, or, when run with job control enabled, any
 
7538
@var{jobspec} was not found or specifies a job
 
7539
that was started without job control.
 
7540
 
 
7541
@item fg
 
7542
@btindex fg
 
7543
@example
 
7544
fg [@var{jobspec}]
 
7545
@end example
 
7546
 
 
7547
Resume the job @var{jobspec} in the foreground and make it the current job.
 
7548
If @var{jobspec} is not supplied, the current job is used.
 
7549
The return status is that of the command placed into the foreground,
 
7550
or non-zero if run when job control is disabled or, when run with
 
7551
job control enabled, @var{jobspec} does not specify a valid job or
 
7552
@var{jobspec} specifies a job that was started without job control.
 
7553
 
 
7554
@item jobs
 
7555
@btindex jobs
 
7556
@example
 
7557
jobs [-lnprs] [@var{jobspec}]
 
7558
jobs -x @var{command} [@var{arguments}]
 
7559
@end example
 
7560
 
 
7561
The first form lists the active jobs.  The options have the
 
7562
following meanings:
 
7563
 
 
7564
@table @code
 
7565
@item -l
 
7566
List process @sc{id}s in addition to the normal information.
 
7567
 
 
7568
@item -n
 
7569
Display information only about jobs that have changed status since
 
7570
the user was last notified of their status.
 
7571
 
 
7572
@item -p
 
7573
List only the process @sc{id} of the job's process group leader.
 
7574
 
 
7575
@item -r
 
7576
Display only running jobs.
 
7577
 
 
7578
@item -s
 
7579
Display only stopped jobs.
 
7580
@end table
 
7581
 
 
7582
If @var{jobspec} is given,
 
7583
output is restricted to information about that job. 
 
7584
If @var{jobspec} is not supplied, the status of all jobs is
 
7585
listed.
 
7586
 
 
7587
If the @option{-x} option is supplied, @code{jobs} replaces any
 
7588
@var{jobspec} found in @var{command} or @var{arguments} with the
 
7589
corresponding process group @sc{id}, and executes @var{command},
 
7590
passing it @var{argument}s, returning its exit status. 
 
7591
 
 
7592
@item kill
 
7593
@btindex kill
 
7594
@example
 
7595
kill [-s @var{sigspec}] [-n @var{signum}] [-@var{sigspec}] @var{jobspec} or @var{pid}
 
7596
kill -l [@var{exit_status}]
 
7597
@end example
 
7598
 
 
7599
Send a signal specified by @var{sigspec} or @var{signum} to the process
 
7600
named by job specification @var{jobspec} or process @sc{id} @var{pid}.
 
7601
@var{sigspec} is either a case-insensitive signal name such as
 
7602
@code{SIGINT} (with or without the @code{SIG} prefix)
 
7603
or a signal number; @var{signum} is a signal number.
 
7604
If @var{sigspec} and @var{signum} are not present, @code{SIGTERM} is used.
 
7605
The @option{-l} option lists the signal names.
 
7606
If any arguments are supplied when @option{-l} is given, the names of the
 
7607
signals corresponding to the arguments are listed, and the return status
 
7608
is zero.
 
7609
@var{exit_status} is a number specifying a signal number or the exit
 
7610
status of a process terminated by a signal.
 
7611
The return status is zero if at least one signal was successfully sent,
 
7612
or non-zero if an error occurs or an invalid option is encountered.
 
7613
 
 
7614
@item wait
 
7615
@btindex wait
 
7616
@example
 
7617
wait [-n] [@var{jobspec} or @var{pid} @dots{}]
 
7618
@end example
 
7619
 
 
7620
Wait until the child process specified by each process @sc{id} @var{pid}
 
7621
or job specification @var{jobspec} exits and return the exit status of the
 
7622
last command waited for.
 
7623
If a job spec is given, all processes in the job are waited for.
 
7624
If no arguments are given, all currently active child processes are
 
7625
waited for, and the return status is zero.
 
7626
If the @option{-n} option is supplied, @code{wait} waits for any job to
 
7627
terminate and returns its exit status.
 
7628
If neither @var{jobspec} nor @var{pid} specifies an active child process
 
7629
of the shell, the return status is 127.
 
7630
 
 
7631
@item disown
 
7632
@btindex disown
 
7633
@example
 
7634
disown [-ar] [-h] [@var{jobspec} @dots{}]
 
7635
@end example
 
7636
 
 
7637
Without options, remove each @var{jobspec} from the table of
 
7638
active jobs.
 
7639
If the @option{-h} option is given, the job is not removed from the table,
 
7640
but is marked so that @code{SIGHUP} is not sent to the job if the shell
 
7641
receives a @code{SIGHUP}.
 
7642
If @var{jobspec} is not present, and neither the @option{-a} nor the
 
7643
@option{-r} option is supplied, the current job is used.
 
7644
If no @var{jobspec} is supplied, the @option{-a} option means to remove or
 
7645
mark all jobs; the @option{-r} option without a @var{jobspec}
 
7646
argument restricts operation to running jobs.
 
7647
 
 
7648
@item suspend
 
7649
@btindex suspend
 
7650
@example
 
7651
suspend [-f]
 
7652
@end example
 
7653
 
 
7654
Suspend the execution of this shell until it receives a
 
7655
@code{SIGCONT} signal.
 
7656
A login shell cannot be suspended; the @option{-f}
 
7657
option can be used to override this and force the suspension.
 
7658
@end table
 
7659
 
 
7660
When job control is not active, the @code{kill} and @code{wait}
 
7661
builtins do not accept @var{jobspec} arguments.  They must be
 
7662
supplied process @sc{id}s.
 
7663
 
 
7664
@node Job Control Variables
 
7665
@section Job Control Variables
 
7666
 
 
7667
@vtable @code
 
7668
 
 
7669
@item auto_resume
 
7670
This variable controls how the shell interacts with the user and
 
7671
job control.  If this variable exists then single word simple
 
7672
commands without redirections are treated as candidates for resumption
 
7673
of an existing job.  There is no ambiguity allowed; if there is
 
7674
more than one job beginning with the string typed, then
 
7675
the most recently accessed job will be selected.
 
7676
The name of a stopped job, in this context, is the command line
 
7677
used to start it.  If this variable is set to the value @samp{exact},
 
7678
the string supplied must match the name of a stopped job exactly;
 
7679
if set to @samp{substring},
 
7680
the string supplied needs to match a substring of the name of a
 
7681
stopped job.  The @samp{substring} value provides functionality
 
7682
analogous to the @samp{%?} job @sc{id} (@pxref{Job Control Basics}).
 
7683
If set to any other value, the supplied string must
 
7684
be a prefix of a stopped job's name; this provides functionality
 
7685
analogous to the @samp{%} job @sc{id}.
 
7686
 
 
7687
@end vtable
 
7688
 
 
7689
@set readline-appendix
 
7690
@set history-appendix
 
7691
@cindex Readline, how to use
 
7692
@include rluser.texi
 
7693
@cindex History, how to use
 
7694
@include hsuser.texi
 
7695
@clear readline-appendix
 
7696
@clear history-appendix
 
7697
 
 
7698
@node Installing Bash
 
7699
@chapter Installing Bash
 
7700
 
 
7701
This chapter provides basic instructions for installing Bash on
 
7702
the various supported platforms.  The distribution supports the
 
7703
@sc{gnu} operating systems, nearly every version of Unix, and several
 
7704
non-Unix systems such as BeOS and Interix.
 
7705
Other independent ports exist for
 
7706
@sc{ms-dos}, @sc{os/2}, and Windows platforms.
 
7707
 
 
7708
@menu
 
7709
* Basic Installation::  Installation instructions.
 
7710
* Compilers and Options::       How to set special options for various
 
7711
                                systems.
 
7712
* Compiling For Multiple Architectures::        How to compile Bash for more
 
7713
                                                than one kind of system from
 
7714
                                                the same source tree.
 
7715
* Installation Names::  How to set the various paths used by the installation.
 
7716
* Specifying the System Type::  How to configure Bash for a particular system.
 
7717
* Sharing Defaults::    How to share default configuration values among GNU
 
7718
                        programs.
 
7719
* Operation Controls::  Options recognized by the configuration program.
 
7720
* Optional Features::   How to enable and disable optional features when
 
7721
                        building Bash.
 
7722
@end menu
 
7723
 
 
7724
@node Basic Installation
 
7725
@section Basic Installation
 
7726
@cindex installation
 
7727
@cindex configuration
 
7728
@cindex Bash installation
 
7729
@cindex Bash configuration
 
7730
 
 
7731
These are installation instructions for Bash.
 
7732
 
 
7733
The simplest way to compile Bash is:
 
7734
 
 
7735
@enumerate
 
7736
@item
 
7737
@code{cd} to the directory containing the source code and type
 
7738
@samp{./configure} to configure Bash for your system.  If you're
 
7739
using @code{csh} on an old version of System V, you might need to
 
7740
type @samp{sh ./configure} instead to prevent @code{csh} from trying
 
7741
to execute @code{configure} itself.
 
7742
 
 
7743
Running @code{configure} takes some time.
 
7744
While running, it prints messages telling which features it is
 
7745
checking for.
 
7746
 
 
7747
@item
 
7748
Type @samp{make} to compile Bash and build the @code{bashbug} bug
 
7749
reporting script.
 
7750
 
 
7751
@item
 
7752
Optionally, type @samp{make tests} to run the Bash test suite.
 
7753
 
 
7754
@item
 
7755
Type @samp{make install} to install @code{bash} and @code{bashbug}.
 
7756
This will also install the manual pages and Info file.
 
7757
 
 
7758
@end enumerate
 
7759
 
 
7760
The @code{configure} shell script attempts to guess correct
 
7761
values for various system-dependent variables used during
 
7762
compilation.  It uses those values to create a @file{Makefile} in
 
7763
each directory of the package (the top directory, the
 
7764
@file{builtins}, @file{doc}, and @file{support} directories,
 
7765
each directory under @file{lib}, and several others).  It also creates a
 
7766
@file{config.h} file containing system-dependent definitions. 
 
7767
Finally, it creates a shell script named @code{config.status} that you
 
7768
can run in the future to recreate the current configuration, a
 
7769
file @file{config.cache} that saves the results of its tests to
 
7770
speed up reconfiguring, and a file @file{config.log} containing
 
7771
compiler output (useful mainly for debugging @code{configure}). 
 
7772
If at some point
 
7773
@file{config.cache} contains results you don't want to keep, you
 
7774
may remove or edit it. 
 
7775
 
 
7776
To find out more about the options and arguments that the
 
7777
@code{configure} script understands, type 
 
7778
 
 
7779
@example
 
7780
bash-2.04$ ./configure --help
 
7781
@end example
 
7782
 
 
7783
@noindent
 
7784
at the Bash prompt in your Bash source directory.
 
7785
 
 
7786
If you need to do unusual things to compile Bash, please
 
7787
try to figure out how @code{configure} could check whether or not
 
7788
to do them, and mail diffs or instructions to
 
7789
@email{bash-maintainers@@gnu.org} so they can be
 
7790
considered for the next release.
 
7791
 
 
7792
The file @file{configure.ac} is used to create @code{configure}
 
7793
by a program called Autoconf.  You only need
 
7794
@file{configure.ac} if you want to change it or regenerate
 
7795
@code{configure} using a newer version of Autoconf.  If
 
7796
you do this, make sure you are using Autoconf version 2.50 or
 
7797
newer.
 
7798
 
 
7799
You can remove the program binaries and object files from the
 
7800
source code directory by typing @samp{make clean}.  To also remove the
 
7801
files that @code{configure} created (so you can compile Bash for
 
7802
a different kind of computer), type @samp{make distclean}.
 
7803
 
 
7804
@node Compilers and Options
 
7805
@section Compilers and Options
 
7806
 
 
7807
Some systems require unusual options for compilation or linking
 
7808
that the @code{configure} script does not know about.  You can
 
7809
give @code{configure} initial values for variables by setting
 
7810
them in the environment.  Using a Bourne-compatible shell, you
 
7811
can do that on the command line like this:
 
7812
 
 
7813
@example
 
7814
CC=c89 CFLAGS=-O2 LIBS=-lposix ./configure
 
7815
@end example
 
7816
 
 
7817
On systems that have the @code{env} program, you can do it like this:
 
7818
 
 
7819
@example
 
7820
env CPPFLAGS=-I/usr/local/include LDFLAGS=-s ./configure
 
7821
@end example
 
7822
 
 
7823
The configuration process uses GCC to build Bash if it
 
7824
is available.
 
7825
 
 
7826
@node Compiling For Multiple Architectures
 
7827
@section Compiling For Multiple Architectures
 
7828
 
 
7829
You can compile Bash for more than one kind of computer at the
 
7830
same time, by placing the object files for each architecture in their
 
7831
own directory.  To do this, you must use a version of @code{make} that
 
7832
supports the @code{VPATH} variable, such as GNU @code{make}.
 
7833
@code{cd} to the
 
7834
directory where you want the object files and executables to go and run
 
7835
the @code{configure} script from the source directory.  You may need to
 
7836
supply the @option{--srcdir=PATH} argument to tell @code{configure} where the
 
7837
source files are.  @code{configure} automatically checks for the
 
7838
source code in the directory that @code{configure} is in and in `..'.
 
7839
 
 
7840
If you have to use a @code{make} that does not supports the @code{VPATH}
 
7841
variable, you can compile Bash for one architecture at a
 
7842
time in the source code directory.  After you have installed
 
7843
Bash for one architecture, use @samp{make distclean} before
 
7844
reconfiguring for another architecture.
 
7845
 
 
7846
Alternatively, if your system supports symbolic links, you can use the
 
7847
@file{support/mkclone} script to create a build tree which has
 
7848
symbolic links back to each file in the source directory.  Here's an
 
7849
example that creates a build directory in the current directory from a
 
7850
source directory @file{/usr/gnu/src/bash-2.0}:
 
7851
 
 
7852
@example
 
7853
bash /usr/gnu/src/bash-2.0/support/mkclone -s /usr/gnu/src/bash-2.0 .
 
7854
@end example
 
7855
 
 
7856
@noindent
 
7857
The @code{mkclone} script requires Bash, so you must have already built
 
7858
Bash for at least one architecture before you can create build
 
7859
directories for other architectures.
 
7860
 
 
7861
@node Installation Names
 
7862
@section Installation Names
 
7863
 
 
7864
By default, @samp{make install} will install into
 
7865
@file{/usr/local/bin}, @file{/usr/local/man}, etc.  You can
 
7866
specify an installation prefix other than @file{/usr/local} by
 
7867
giving @code{configure} the option @option{--prefix=@var{PATH}},
 
7868
or by specifying a value for the @code{DESTDIR} @samp{make}
 
7869
variable when running @samp{make install}.
 
7870
 
 
7871
You can specify separate installation prefixes for
 
7872
architecture-specific files and architecture-independent files. 
 
7873
If you give @code{configure} the option
 
7874
@option{--exec-prefix=@var{PATH}}, @samp{make install} will use
 
7875
@var{PATH} as the prefix for installing programs and libraries.
 
7876
Documentation and other data files will still use the regular prefix. 
 
7877
 
 
7878
@node Specifying the System Type
 
7879
@section Specifying the System Type
 
7880
 
 
7881
There may be some features @code{configure} can not figure out
 
7882
automatically, but need to determine by the type of host Bash
 
7883
will run on.  Usually @code{configure} can figure that
 
7884
out, but if it prints a message saying it can not guess the host
 
7885
type, give it the @option{--host=TYPE} option.  @samp{TYPE} can
 
7886
either be a short name for the system type, such as @samp{sun4},
 
7887
or a canonical name with three fields: @samp{CPU-COMPANY-SYSTEM}
 
7888
(e.g., @samp{i386-unknown-freebsd4.2}).
 
7889
 
 
7890
See the file @file{support/config.sub} for the possible
 
7891
values of each field. 
 
7892
 
 
7893
@node Sharing Defaults
 
7894
@section Sharing Defaults
 
7895
 
 
7896
If you want to set default values for @code{configure} scripts to
 
7897
share, you can create a site shell script called
 
7898
@code{config.site} that gives default values for variables like
 
7899
@code{CC}, @code{cache_file}, and @code{prefix}.  @code{configure}
 
7900
looks for @file{PREFIX/share/config.site} if it exists, then
 
7901
@file{PREFIX/etc/config.site} if it exists.  Or, you can set the
 
7902
@code{CONFIG_SITE} environment variable to the location of the site
 
7903
script.  A warning: the Bash @code{configure} looks for a site script,
 
7904
but not all @code{configure} scripts do.
 
7905
 
 
7906
@node Operation Controls
 
7907
@section Operation Controls
 
7908
 
 
7909
@code{configure} recognizes the following options to control how it
 
7910
operates.
 
7911
 
 
7912
@table @code
 
7913
 
 
7914
@item --cache-file=@var{file}
 
7915
Use and save the results of the tests in
 
7916
@var{file} instead of @file{./config.cache}.  Set @var{file} to
 
7917
@file{/dev/null} to disable caching, for debugging
 
7918
@code{configure}. 
 
7919
 
 
7920
@item --help
 
7921
Print a summary of the options to @code{configure}, and exit.
 
7922
 
 
7923
@item --quiet
 
7924
@itemx --silent
 
7925
@itemx -q
 
7926
Do not print messages saying which checks are being made.
 
7927
 
 
7928
@item --srcdir=@var{dir}
 
7929
Look for the Bash source code in directory @var{dir}.  Usually
 
7930
@code{configure} can determine that directory automatically.
 
7931
 
 
7932
@item --version
 
7933
Print the version of Autoconf used to generate the @code{configure}
 
7934
script, and exit.
 
7935
@end table
 
7936
 
 
7937
@code{configure} also accepts some other, not widely used, boilerplate
 
7938
options.  @samp{configure --help} prints the complete list.
 
7939
 
 
7940
@node Optional Features
 
7941
@section Optional Features
 
7942
 
 
7943
The Bash @code{configure} has a number of @option{--enable-@var{feature}}
 
7944
options, where @var{feature} indicates an optional part of Bash.
 
7945
There are also several @option{--with-@var{package}} options,
 
7946
where @var{package} is something like @samp{bash-malloc} or @samp{purify}.
 
7947
To turn off the default use of a package, use
 
7948
@option{--without-@var{package}}.  To configure Bash without a feature
 
7949
that is enabled by default, use @option{--disable-@var{feature}}.
 
7950
 
 
7951
Here is a complete list of the @option{--enable-} and
 
7952
@option{--with-} options that the Bash @code{configure} recognizes. 
 
7953
 
 
7954
@table @code
 
7955
@item --with-afs
 
7956
Define if you are using the Andrew File System from Transarc.
 
7957
 
 
7958
@item --with-bash-malloc
 
7959
Use the Bash version of
 
7960
@code{malloc} in the directory @file{lib/malloc}.  This is not the same
 
7961
@code{malloc} that appears in @sc{gnu} libc, but an older version
 
7962
originally derived from the 4.2 @sc{bsd} @code{malloc}.  This @code{malloc}
 
7963
is very fast, but wastes some space on each allocation.
 
7964
This option is enabled by default.
 
7965
The @file{NOTES} file contains a list of systems for
 
7966
which this should be turned off, and @code{configure} disables this
 
7967
option automatically for a number of systems.
 
7968
 
 
7969
@item --with-curses
 
7970
Use the curses library instead of the termcap library.  This should
 
7971
be supplied if your system has an inadequate or incomplete termcap
 
7972
database.
 
7973
 
 
7974
@item --with-gnu-malloc
 
7975
A synonym for @code{--with-bash-malloc}.
 
7976
 
 
7977
@item --with-installed-readline[=@var{PREFIX}]
 
7978
Define this to make Bash link with a locally-installed version of Readline
 
7979
rather than the version in @file{lib/readline}.  This works only with
 
7980
Readline 5.0 and later versions.  If @var{PREFIX} is @code{yes} or not
 
7981
supplied, @code{configure} uses the values of the make variables
 
7982
@code{includedir} and @code{libdir}, which are subdirectories of @code{prefix}
 
7983
by default, to find the installed version of Readline if it is not in
 
7984
the standard system include and library directories.
 
7985
If @var{PREFIX} is @code{no}, Bash links with the version in
 
7986
@file{lib/readline}.
 
7987
If @var{PREFIX} is set to any other value, @code{configure} treats it as
 
7988
a directory pathname and looks for
 
7989
the installed version of Readline in subdirectories of that directory
 
7990
(include files in @var{PREFIX}/@code{include} and the library in
 
7991
@var{PREFIX}/@code{lib}).
 
7992
 
 
7993
@item --with-purify
 
7994
Define this to use the Purify memory allocation checker from Rational
 
7995
Software.
 
7996
 
 
7997
@item --enable-minimal-config
 
7998
This produces a shell with minimal features, close to the historical
 
7999
Bourne shell.
 
8000
@end table
 
8001
 
 
8002
There are several @option{--enable-} options that alter how Bash is
 
8003
compiled and linked, rather than changing run-time features.
 
8004
 
 
8005
@table @code
 
8006
@item --enable-largefile
 
8007
Enable support for @uref{http://www.sas.com/standards/large_file/x_open.20Mar96.html,
 
8008
large files} if the operating system requires special compiler options
 
8009
to build programs which can access large files.  This is enabled by
 
8010
default, if the operating system provides large file support.
 
8011
 
 
8012
@item --enable-profiling
 
8013
This builds a Bash binary that produces profiling information to be
 
8014
processed by @code{gprof} each time it is executed.
 
8015
 
 
8016
@item --enable-static-link
 
8017
This causes Bash to be linked statically, if @code{gcc} is being used.
 
8018
This could be used to build a version to use as root's shell.
 
8019
@end table
 
8020
 
 
8021
The @samp{minimal-config} option can be used to disable all of
 
8022
the following options, but it is processed first, so individual
 
8023
options may be enabled using @samp{enable-@var{feature}}. 
 
8024
 
 
8025
All of the following options except for @samp{disabled-builtins},
 
8026
@samp{directpand-default}, and
 
8027
@samp{xpg-echo-default} are
 
8028
enabled by default, unless the operating system does not provide the
 
8029
necessary support.
 
8030
 
 
8031
@table @code
 
8032
@item --enable-alias
 
8033
Allow alias expansion and include the @code{alias} and @code{unalias}
 
8034
builtins (@pxref{Aliases}).
 
8035
 
 
8036
@item --enable-arith-for-command
 
8037
Include support for the alternate form of the @code{for} command
 
8038
that behaves like the C language @code{for} statement
 
8039
(@pxref{Looping Constructs}).
 
8040
 
 
8041
@item --enable-array-variables
 
8042
Include support for one-dimensional array shell variables
 
8043
(@pxref{Arrays}).
 
8044
 
 
8045
@item --enable-bang-history
 
8046
Include support for @code{csh}-like history substitution
 
8047
(@pxref{History Interaction}).
 
8048
 
 
8049
@item --enable-brace-expansion
 
8050
Include @code{csh}-like brace expansion
 
8051
( @code{b@{a,b@}c} @expansion{} @code{bac bbc} ).
 
8052
See @ref{Brace Expansion}, for a complete description.
 
8053
 
 
8054
@item --enable-casemod-attributes
 
8055
Include support for case-modifying attributes in the @code{declare} builtin
 
8056
and assignment statements.  Variables with the @var{uppercase} attribute,
 
8057
for example, will have their values converted to uppercase upon assignment.
 
8058
 
 
8059
@item --enable-casemod-expansion
 
8060
Include support for case-modifying word expansions.
 
8061
 
 
8062
@item --enable-command-timing
 
8063
Include support for recognizing @code{time} as a reserved word and for
 
8064
displaying timing statistics for the pipeline following @code{time}
 
8065
(@pxref{Pipelines}).
 
8066
This allows pipelines as well as shell builtins and functions to be timed.
 
8067
 
 
8068
@item --enable-cond-command
 
8069
Include support for the @code{[[} conditional command.
 
8070
(@pxref{Conditional Constructs}).
 
8071
 
 
8072
@item --enable-cond-regexp
 
8073
Include support for matching @sc{posix} regular expressions using the
 
8074
@samp{=~} binary operator in the @code{[[} conditional command.
 
8075
(@pxref{Conditional Constructs}).
 
8076
 
 
8077
@item --enable-coprocesses
 
8078
Include support for coprocesses and the @code{coproc} reserved word
 
8079
(@pxref{Pipelines}).
 
8080
 
 
8081
@item --enable-debugger
 
8082
Include support for the bash debugger (distributed separately).
 
8083
 
 
8084
@item --enable-direxpand-default
 
8085
Cause the @code{direxpand} shell option (@pxref{The Shopt Builtin})
 
8086
to be enabled by default when the shell starts.
 
8087
It is normally disabled by default.
 
8088
 
 
8089
@item --enable-directory-stack
 
8090
Include support for a @code{csh}-like directory stack and the
 
8091
@code{pushd}, @code{popd}, and @code{dirs} builtins
 
8092
(@pxref{The Directory Stack}).
 
8093
 
 
8094
@item --enable-disabled-builtins
 
8095
Allow builtin commands to be invoked via @samp{builtin xxx}
 
8096
even after @code{xxx} has been disabled using @samp{enable -n xxx}.
 
8097
See @ref{Bash Builtins}, for details of the @code{builtin} and
 
8098
@code{enable} builtin commands.
 
8099
 
 
8100
@item --enable-dparen-arithmetic
 
8101
Include support for the @code{((@dots{}))} command
 
8102
(@pxref{Conditional Constructs}).
 
8103
 
 
8104
@item --enable-extended-glob
 
8105
Include support for the extended pattern matching features described
 
8106
above under @ref{Pattern Matching}.
 
8107
 
 
8108
@item --enable-extended-glob-default
 
8109
Set the default value of the @var{extglob} shell option described
 
8110
above under @ref{The Shopt Builtin} to be enabled.
 
8111
 
 
8112
@item --enable-glob-asciirange-default
 
8113
Set the default value of the @var{globasciiranges} shell option described
 
8114
above under @ref{The Shopt Builtin} to be enabled.
 
8115
This controls the behavior of character ranges when used in pattern matching
 
8116
bracket expressions.
 
8117
 
 
8118
@item --enable-help-builtin
 
8119
Include the @code{help} builtin, which displays help on shell builtins and
 
8120
variables (@pxref{Bash Builtins}).
 
8121
 
 
8122
@item --enable-history
 
8123
Include command history and the @code{fc} and @code{history}
 
8124
builtin commands (@pxref{Bash History Facilities}).
 
8125
 
 
8126
@item --enable-job-control
 
8127
This enables the job control features (@pxref{Job Control}),
 
8128
if the operating system supports them.
 
8129
 
 
8130
@item --enable-multibyte
 
8131
This enables support for multibyte characters if the operating
 
8132
system provides the necessary support.
 
8133
 
 
8134
@item --enable-net-redirections
 
8135
This enables the special handling of filenames of the form
 
8136
@code{/dev/tcp/@var{host}/@var{port}} and
 
8137
@code{/dev/udp/@var{host}/@var{port}}
 
8138
when used in redirections (@pxref{Redirections}).
 
8139
 
 
8140
@item --enable-process-substitution
 
8141
This enables process substitution (@pxref{Process Substitution}) if
 
8142
the operating system provides the necessary support.
 
8143
 
 
8144
@item --enable-progcomp
 
8145
Enable the programmable completion facilities
 
8146
(@pxref{Programmable Completion}).
 
8147
If Readline is not enabled, this option has no effect.
 
8148
 
 
8149
@item --enable-prompt-string-decoding
 
8150
Turn on the interpretation of a number of backslash-escaped characters
 
8151
in the @env{$PS1}, @env{$PS2}, @env{$PS3}, and @env{$PS4} prompt
 
8152
strings.  See @ref{Controlling the Prompt}, for a complete list of prompt
 
8153
string escape sequences.
 
8154
 
 
8155
@item --enable-readline
 
8156
Include support for command-line editing and history with the Bash
 
8157
version of the Readline library (@pxref{Command Line Editing}).
 
8158
 
 
8159
@item --enable-restricted
 
8160
Include support for a @dfn{restricted shell}.  If this is enabled, Bash,
 
8161
when called as @code{rbash}, enters a restricted mode.  See
 
8162
@ref{The Restricted Shell}, for a description of restricted mode.
 
8163
 
 
8164
@item --enable-select
 
8165
Include the @code{select} compound command, which allows the generation of
 
8166
simple menus (@pxref{Conditional Constructs}).
 
8167
 
 
8168
@item --enable-separate-helpfiles
 
8169
Use external files for the documentation displayed by the @code{help} builtin
 
8170
instead of storing the text internally.
 
8171
 
 
8172
@item --enable-single-help-strings
 
8173
Store the text displayed by the @code{help} builtin as a single string for
 
8174
each help topic.  This aids in translating the text to different languages.
 
8175
You may need to disable this if your compiler cannot handle very long string
 
8176
literals.
 
8177
 
 
8178
@item --enable-strict-posix-default
 
8179
Make Bash @sc{posix}-conformant by default (@pxref{Bash POSIX Mode}).
 
8180
 
 
8181
@item --enable-usg-echo-default
 
8182
A synonym for @code{--enable-xpg-echo-default}.
 
8183
 
 
8184
@item --enable-xpg-echo-default
 
8185
Make the @code{echo} builtin expand backslash-escaped characters by default,
 
8186
without requiring the @option{-e} option.
 
8187
This sets the default value of the @code{xpg_echo} shell option to @code{on},
 
8188
which makes the Bash @code{echo} behave more like the version specified in
 
8189
the Single Unix Specification, version 3.
 
8190
@xref{Bash Builtins}, for a description of the escape sequences that
 
8191
@code{echo} recognizes.
 
8192
@end table
 
8193
 
 
8194
The file @file{config-top.h} contains C Preprocessor
 
8195
@samp{#define} statements for options which are not settable from
 
8196
@code{configure}.
 
8197
Some of these are not meant to be changed; beware of the consequences if
 
8198
you do.
 
8199
Read the comments associated with each definition for more
 
8200
information about its effect.
 
8201
 
 
8202
@node Reporting Bugs
 
8203
@appendix Reporting Bugs
 
8204
 
 
8205
Please report all bugs you find in Bash.
 
8206
But first, you should
 
8207
make sure that it really is a bug, and that it appears in the latest
 
8208
version of Bash.
 
8209
The latest version of Bash is always available for FTP from
 
8210
@uref{ftp://ftp.gnu.org/pub/gnu/bash/}.
 
8211
 
 
8212
Once you have determined that a bug actually exists, use the
 
8213
@code{bashbug} command to submit a bug report.
 
8214
If you have a fix, you are encouraged to mail that as well!
 
8215
Suggestions and `philosophical' bug reports may be mailed
 
8216
to @email{bug-bash@@gnu.org} or posted to the Usenet
 
8217
newsgroup @code{gnu.bash.bug}.
 
8218
 
 
8219
All bug reports should include:
 
8220
@itemize @bullet
 
8221
@item
 
8222
The version number of Bash.
 
8223
@item
 
8224
The hardware and operating system.
 
8225
@item
 
8226
The compiler used to compile Bash.
 
8227
@item
 
8228
A description of the bug behaviour.
 
8229
@item
 
8230
A short script or `recipe' which exercises the bug and may be used
 
8231
to reproduce it.
 
8232
@end itemize
 
8233
 
 
8234
@noindent
 
8235
@code{bashbug} inserts the first three items automatically into
 
8236
the template it provides for filing a bug report.
 
8237
 
 
8238
Please send all reports concerning this manual to
 
8239
@email{bug-bash@@gnu.org}.
 
8240
 
 
8241
@node Major Differences From The Bourne Shell
 
8242
@appendix Major Differences From The Bourne Shell
 
8243
 
 
8244
Bash implements essentially the same grammar, parameter and
 
8245
variable expansion, redirection, and quoting as the Bourne Shell. 
 
8246
Bash uses the @sc{posix} standard as the specification of
 
8247
how these features are to be implemented.  There are some
 
8248
differences between the traditional Bourne shell and Bash; this
 
8249
section quickly details the differences of significance.  A
 
8250
number of these differences are explained in greater depth in
 
8251
previous sections.
 
8252
This section uses the version of @code{sh} included in SVR4.2 (the
 
8253
last version of the historical Bourne shell) as the baseline reference.
 
8254
 
 
8255
@itemize @bullet
 
8256
 
 
8257
@item
 
8258
Bash is @sc{posix}-conformant, even where the @sc{posix} specification
 
8259
differs from traditional @code{sh} behavior (@pxref{Bash POSIX Mode}).
 
8260
 
 
8261
@item
 
8262
Bash has multi-character invocation options (@pxref{Invoking Bash}).
 
8263
 
 
8264
@item
 
8265
Bash has command-line editing (@pxref{Command Line Editing}) and
 
8266
the @code{bind} builtin.
 
8267
 
 
8268
@item
 
8269
Bash provides a programmable word completion mechanism
 
8270
(@pxref{Programmable Completion}), and builtin commands
 
8271
@code{complete}, @code{compgen}, and @code{compopt}, to
 
8272
manipulate it.
 
8273
 
 
8274
@item
 
8275
Bash has command history (@pxref{Bash History Facilities}) and the
 
8276
@code{history} and @code{fc} builtins to manipulate it.
 
8277
The Bash history list maintains timestamp information and uses the
 
8278
value of the @code{HISTTIMEFORMAT} variable to display it.
 
8279
 
 
8280
@item
 
8281
Bash implements @code{csh}-like history expansion
 
8282
(@pxref{History Interaction}).
 
8283
 
 
8284
@item
 
8285
Bash has one-dimensional array variables (@pxref{Arrays}), and the
 
8286
appropriate variable expansions and assignment syntax to use them.
 
8287
Several of the Bash builtins take options to act on arrays.
 
8288
Bash provides a number of built-in array variables.
 
8289
 
 
8290
@item
 
8291
The @code{$'@dots{}'} quoting syntax, which expands ANSI-C
 
8292
backslash-escaped characters in the text between the single quotes,
 
8293
is supported (@pxref{ANSI-C Quoting}).
 
8294
 
 
8295
@item
 
8296
Bash supports the @code{$"@dots{}"} quoting syntax to do
 
8297
locale-specific translation of the characters between the double
 
8298
quotes.  The @option{-D}, @option{--dump-strings}, and @option{--dump-po-strings}
 
8299
invocation options list the translatable strings found in a script
 
8300
(@pxref{Locale Translation}).
 
8301
 
 
8302
@item
 
8303
Bash implements the @code{!} keyword to negate the return value of
 
8304
a pipeline (@pxref{Pipelines}).
 
8305
Very useful when an @code{if} statement needs to act only if a test fails.
 
8306
The Bash @samp{-o pipefail} option to @code{set} will cause a pipeline to
 
8307
return a failure status if any command fails.
 
8308
 
 
8309
@item
 
8310
Bash has the @code{time} reserved word and command timing (@pxref{Pipelines}).
 
8311
The display of the timing statistics may be controlled with the
 
8312
@env{TIMEFORMAT} variable.
 
8313
 
 
8314
@item
 
8315
Bash implements the @code{for (( @var{expr1} ; @var{expr2} ; @var{expr3} ))}
 
8316
arithmetic for command, similar to the C language (@pxref{Looping Constructs}).
 
8317
 
 
8318
@item
 
8319
Bash includes the @code{select} compound command, which allows the
 
8320
generation of simple menus (@pxref{Conditional Constructs}).
 
8321
 
 
8322
@item
 
8323
Bash includes the @code{[[} compound command, which makes conditional
 
8324
testing part of the shell grammar (@pxref{Conditional Constructs}), including
 
8325
optional regular expression matching.
 
8326
 
 
8327
@item
 
8328
Bash provides optional case-insensitive matching for the @code{case} and
 
8329
@code{[[} constructs.
 
8330
 
 
8331
@item
 
8332
Bash includes brace expansion (@pxref{Brace Expansion}) and tilde
 
8333
expansion (@pxref{Tilde Expansion}).
 
8334
 
 
8335
@item
 
8336
Bash implements command aliases and the @code{alias} and @code{unalias}
 
8337
builtins (@pxref{Aliases}).
 
8338
 
 
8339
@item
 
8340
Bash provides shell arithmetic, the @code{((} compound command
 
8341
(@pxref{Conditional Constructs}),
 
8342
and arithmetic expansion (@pxref{Shell Arithmetic}).
 
8343
 
 
8344
@item
 
8345
Variables present in the shell's initial environment are automatically
 
8346
exported to child processes.  The Bourne shell does not normally do
 
8347
this unless the variables are explicitly marked using the @code{export}
 
8348
command.
 
8349
 
 
8350
@item
 
8351
Bash supports the @samp{+=} assignment operator, which appends to the value
 
8352
of the variable named on the left hand side.
 
8353
 
 
8354
@item
 
8355
Bash includes the @sc{posix} pattern removal @samp{%}, @samp{#}, @samp{%%}
 
8356
and @samp{##} expansions to remove leading or trailing substrings from
 
8357
variable values (@pxref{Shell Parameter Expansion}).
 
8358
 
 
8359
@item
 
8360
The expansion @code{$@{#xx@}}, which returns the length of @code{$@{xx@}},
 
8361
is supported (@pxref{Shell Parameter Expansion}).
 
8362
 
 
8363
@item
 
8364
The expansion @code{$@{var:}@var{offset}@code{[:}@var{length}@code{]@}},
 
8365
which expands to the substring of @code{var}'s value of length
 
8366
@var{length}, beginning at @var{offset}, is present
 
8367
(@pxref{Shell Parameter Expansion}).
 
8368
 
 
8369
@item
 
8370
The expansion
 
8371
@code{$@{var/[/]}@var{pattern}@code{[/}@var{replacement}@code{]@}},
 
8372
which matches @var{pattern} and replaces it with @var{replacement} in
 
8373
the value of @code{var}, is available (@pxref{Shell Parameter Expansion}).
 
8374
 
 
8375
@item
 
8376
The expansion @code{$@{!@var{prefix}*@}} expansion, which expands to
 
8377
the names of all shell variables whose names begin with @var{prefix},
 
8378
is available (@pxref{Shell Parameter Expansion}).
 
8379
 
 
8380
@item
 
8381
Bash has @var{indirect} variable expansion using @code{$@{!word@}}
 
8382
(@pxref{Shell Parameter Expansion}).
 
8383
 
 
8384
@item
 
8385
Bash can expand positional parameters beyond @code{$9} using
 
8386
@code{$@{@var{num}@}}.
 
8387
 
 
8388
@item
 
8389
The @sc{posix} @code{$()} form of command substitution
 
8390
is implemented (@pxref{Command Substitution}),
 
8391
and preferred to the Bourne shell's @code{``} (which
 
8392
is also implemented for backwards compatibility).
 
8393
 
 
8394
@item
 
8395
Bash has process substitution (@pxref{Process Substitution}).
 
8396
 
 
8397
@item
 
8398
Bash automatically assigns variables that provide information about the
 
8399
current user (@env{UID}, @env{EUID}, and @env{GROUPS}), the current host
 
8400
(@env{HOSTTYPE}, @env{OSTYPE}, @env{MACHTYPE}, and @env{HOSTNAME}),
 
8401
and the instance of Bash that is running (@env{BASH},
 
8402
@env{BASH_VERSION}, and @env{BASH_VERSINFO}).  @xref{Bash Variables},
 
8403
for details.
 
8404
 
 
8405
@item
 
8406
The @env{IFS} variable is used to split only the results of expansion,
 
8407
not all words (@pxref{Word Splitting}).
 
8408
This closes a longstanding shell security hole.
 
8409
 
 
8410
@item
 
8411
The filename expansion bracket expression code uses @samp{!} and @samp{^}
 
8412
to negate the set of characters between the brackets.
 
8413
The Bourne shell uses only @samp{!}.
 
8414
 
 
8415
@item
 
8416
Bash implements the full set of @sc{posix} filename expansion operators,
 
8417
including @var{character classes}, @var{equivalence classes}, and
 
8418
@var{collating symbols} (@pxref{Filename Expansion}).
 
8419
 
 
8420
@item
 
8421
Bash implements extended pattern matching features when the @code{extglob}
 
8422
shell option is enabled (@pxref{Pattern Matching}).
 
8423
 
 
8424
@item
 
8425
It is possible to have a variable and a function with the same name;
 
8426
@code{sh} does not separate the two name spaces.
 
8427
 
 
8428
@item
 
8429
Bash functions are permitted to have local variables using the
 
8430
@code{local} builtin, and thus useful recursive functions may be written
 
8431
(@pxref{Bash Builtins}).
 
8432
 
 
8433
@item
 
8434
Variable assignments preceding commands affect only that command, even
 
8435
builtins and functions (@pxref{Environment}).
 
8436
In @code{sh}, all variable assignments 
 
8437
preceding commands are global unless the command is executed from the
 
8438
file system.
 
8439
 
 
8440
@item
 
8441
Bash performs filename expansion on filenames specified as operands
 
8442
to input and output redirection operators (@pxref{Redirections}).
 
8443
 
 
8444
@item
 
8445
Bash contains the @samp{<>} redirection operator, allowing a file to be
 
8446
opened for both reading and writing, and the @samp{&>} redirection
 
8447
operator, for directing standard output and standard error to the same
 
8448
file (@pxref{Redirections}).
 
8449
 
 
8450
@item
 
8451
Bash includes the @samp{<<<} redirection operator, allowing a string to
 
8452
be used as the standard input to a command.
 
8453
 
 
8454
@item
 
8455
Bash implements the @samp{[n]<&@var{word}} and @samp{[n]>&@var{word}}
 
8456
redirection operators, which move one file descriptor to another.
 
8457
 
 
8458
@item
 
8459
Bash treats a number of filenames specially when they are
 
8460
used in redirection operators (@pxref{Redirections}).
 
8461
 
 
8462
@item
 
8463
Bash can open network connections to arbitrary machines and services
 
8464
with the redirection operators (@pxref{Redirections}).
 
8465
 
 
8466
@item
 
8467
The @code{noclobber} option is available to avoid overwriting existing
 
8468
files with output redirection (@pxref{The Set Builtin}).
 
8469
The @samp{>|} redirection operator may be used to override @code{noclobber}.
 
8470
 
 
8471
@item
 
8472
The Bash @code{cd} and @code{pwd} builtins (@pxref{Bourne Shell Builtins})
 
8473
each take @option{-L} and @option{-P} options to switch between logical and
 
8474
physical modes.
 
8475
 
 
8476
@item
 
8477
Bash allows a function to override a builtin with the same name, and provides
 
8478
access to that builtin's functionality within the function via the
 
8479
@code{builtin} and @code{command} builtins (@pxref{Bash Builtins}).
 
8480
 
 
8481
@item
 
8482
The @code{command} builtin allows selective disabling of functions
 
8483
when command lookup is performed (@pxref{Bash Builtins}).
 
8484
 
 
8485
@item
 
8486
Individual builtins may be enabled or disabled using the @code{enable}
 
8487
builtin (@pxref{Bash Builtins}).
 
8488
 
 
8489
@item
 
8490
The Bash @code{exec} builtin takes additional options that allow users
 
8491
to control the contents of the environment passed to the executed
 
8492
command, and what the zeroth argument to the command is to be
 
8493
(@pxref{Bourne Shell Builtins}).
 
8494
 
 
8495
@item
 
8496
Shell functions may be exported to children via the environment
 
8497
using @code{export -f} (@pxref{Shell Functions}).
 
8498
 
 
8499
@item
 
8500
The Bash @code{export}, @code{readonly}, and @code{declare} builtins can
 
8501
take a @option{-f} option to act on shell functions, a @option{-p} option to
 
8502
display variables with various attributes set in a format that can be
 
8503
used as shell input, a @option{-n} option to remove various variable
 
8504
attributes, and @samp{name=value} arguments to set variable attributes
 
8505
and values simultaneously.
 
8506
 
 
8507
@item
 
8508
The Bash @code{hash} builtin allows a name to be associated with
 
8509
an arbitrary filename, even when that filename cannot be found by
 
8510
searching the @env{$PATH}, using @samp{hash -p}
 
8511
(@pxref{Bourne Shell Builtins}).
 
8512
 
 
8513
@item
 
8514
Bash includes a @code{help} builtin for quick reference to shell
 
8515
facilities (@pxref{Bash Builtins}).
 
8516
 
 
8517
@item
 
8518
The @code{printf} builtin is available to display formatted output
 
8519
(@pxref{Bash Builtins}).
 
8520
 
 
8521
@item
 
8522
The Bash @code{read} builtin (@pxref{Bash Builtins})
 
8523
will read a line ending in @samp{\} with
 
8524
the @option{-r} option, and will use the @env{REPLY} variable as a
 
8525
default if no non-option arguments are supplied.
 
8526
The Bash @code{read} builtin
 
8527
also accepts a prompt string with the @option{-p} option and will use
 
8528
Readline to obtain the line when given the @option{-e} option.
 
8529
The @code{read} builtin also has additional options to control input:
 
8530
the @option{-s} option will turn off echoing of input characters as
 
8531
they are read, the @option{-t} option will allow @code{read} to time out
 
8532
if input does not arrive within a specified number of seconds, the
 
8533
@option{-n} option will allow reading only a specified number of
 
8534
characters rather than a full line, and the @option{-d} option will read
 
8535
until a particular character rather than newline.
 
8536
 
 
8537
@item
 
8538
The @code{return} builtin may be used to abort execution of scripts
 
8539
executed with the @code{.} or @code{source} builtins
 
8540
(@pxref{Bourne Shell Builtins}).
 
8541
 
 
8542
@item
 
8543
Bash includes the @code{shopt} builtin, for finer control of shell
 
8544
optional capabilities (@pxref{The Shopt Builtin}), and allows these options
 
8545
to be set and unset at shell invocation (@pxref{Invoking Bash}).
 
8546
 
 
8547
@item
 
8548
Bash has much more optional behavior controllable with the @code{set}
 
8549
builtin (@pxref{The Set Builtin}).
 
8550
 
 
8551
@item
 
8552
The @samp{-x} (@option{xtrace}) option displays commands other than
 
8553
simple commands when performing an execution trace
 
8554
(@pxref{The Set Builtin}).
 
8555
 
 
8556
@item
 
8557
The @code{test} builtin (@pxref{Bourne Shell Builtins})
 
8558
is slightly different, as it implements the @sc{posix} algorithm,
 
8559
which specifies the behavior based on the number of arguments.
 
8560
 
 
8561
@item
 
8562
Bash includes the @code{caller} builtin, which displays the context of
 
8563
any active subroutine call (a shell function or a script executed with
 
8564
the @code{.} or @code{source} builtins).  This supports the bash
 
8565
debugger.
 
8566
 
 
8567
@item
 
8568
The @code{trap} builtin (@pxref{Bourne Shell Builtins}) allows a
 
8569
@code{DEBUG} pseudo-signal specification, similar to @code{EXIT}.
 
8570
Commands specified with a @code{DEBUG} trap are executed before every
 
8571
simple command, @code{for} command, @code{case} command,
 
8572
@code{select} command, every arithmetic @code{for} command, and before
 
8573
the first command executes in a shell function.
 
8574
The @code{DEBUG} trap is not inherited by shell functions unless the
 
8575
function has been given the @code{trace} attribute or the
 
8576
@code{functrace} option has been enabled using the @code{shopt} builtin.
 
8577
The @code{extdebug} shell option has additional effects on the
 
8578
@code{DEBUG} trap.
 
8579
 
 
8580
The @code{trap} builtin (@pxref{Bourne Shell Builtins}) allows an
 
8581
@code{ERR} pseudo-signal specification, similar to @code{EXIT} and @code{DEBUG}.
 
8582
Commands specified with an @code{ERR} trap are executed after a simple
 
8583
command fails, with a few exceptions.
 
8584
The @code{ERR} trap is not inherited by shell functions unless the
 
8585
@code{-o errtrace} option to the @code{set} builtin is enabled.
 
8586
 
 
8587
The @code{trap} builtin (@pxref{Bourne Shell Builtins}) allows a
 
8588
@code{RETURN} pseudo-signal specification, similar to
 
8589
@code{EXIT} and @code{DEBUG}.
 
8590
Commands specified with an @code{RETURN} trap are executed before
 
8591
execution resumes after a shell function or a shell script executed with
 
8592
@code{.} or @code{source} returns.
 
8593
The @code{RETURN} trap is not inherited by shell functions unless the
 
8594
function has been given the @code{trace} attribute or the
 
8595
@code{functrace} option has been enabled using the @code{shopt} builtin.
 
8596
 
 
8597
@item
 
8598
The Bash @code{type} builtin is more extensive and gives more information
 
8599
about the names it finds (@pxref{Bash Builtins}).
 
8600
 
 
8601
@item
 
8602
The Bash @code{umask} builtin permits a @option{-p} option to cause
 
8603
the output to be displayed in the form of a @code{umask} command
 
8604
that may be reused as input (@pxref{Bourne Shell Builtins}).
 
8605
 
 
8606
@item
 
8607
Bash implements a @code{csh}-like directory stack, and provides the
 
8608
@code{pushd}, @code{popd}, and @code{dirs} builtins to manipulate it
 
8609
(@pxref{The Directory Stack}).
 
8610
Bash also makes the directory stack visible as the value of the
 
8611
@env{DIRSTACK} shell variable.
 
8612
 
 
8613
@item
 
8614
Bash interprets special backslash-escaped characters in the prompt
 
8615
strings when interactive (@pxref{Controlling the Prompt}).
 
8616
 
 
8617
@item
 
8618
The Bash restricted mode is more useful (@pxref{The Restricted Shell});
 
8619
the SVR4.2 shell restricted mode is too limited.
 
8620
 
 
8621
@item
 
8622
The @code{disown} builtin can remove a job from the internal shell
 
8623
job table (@pxref{Job Control Builtins}) or suppress the sending
 
8624
of @code{SIGHUP} to a job when the shell exits as the result of a
 
8625
@code{SIGHUP}.
 
8626
 
 
8627
@item
 
8628
Bash includes a number of features to support a separate debugger for
 
8629
shell scripts.
 
8630
 
 
8631
@item
 
8632
The SVR4.2 shell has two privilege-related builtins
 
8633
(@code{mldmode} and @code{priv}) not present in Bash.
 
8634
 
 
8635
@item
 
8636
Bash does not have the @code{stop} or @code{newgrp} builtins.
 
8637
 
 
8638
@item
 
8639
Bash does not use the @env{SHACCT} variable or perform shell accounting.
 
8640
 
 
8641
@item
 
8642
The SVR4.2 @code{sh} uses a @env{TIMEOUT} variable like Bash uses
 
8643
@env{TMOUT}.
 
8644
 
 
8645
@end itemize
 
8646
 
 
8647
@noindent
 
8648
More features unique to Bash may be found in @ref{Bash Features}.
 
8649
 
 
8650
 
 
8651
@appendixsec Implementation Differences From The SVR4.2 Shell
 
8652
 
 
8653
Since Bash is a completely new implementation, it does not suffer from
 
8654
many of the limitations of the SVR4.2 shell.  For instance:
 
8655
 
 
8656
@itemize @bullet
 
8657
 
 
8658
@item
 
8659
Bash does not fork a subshell when redirecting into or out of
 
8660
a shell control structure such as  an @code{if} or @code{while}
 
8661
statement.
 
8662
 
 
8663
@item
 
8664
Bash does not allow unbalanced quotes.  The SVR4.2 shell will silently
 
8665
insert a needed closing quote at @code{EOF} under certain circumstances.
 
8666
This can be the cause of some hard-to-find errors.
 
8667
 
 
8668
@item
 
8669
The SVR4.2 shell uses a baroque memory management scheme based on
 
8670
trapping @code{SIGSEGV}.  If the shell is started from a process with
 
8671
@code{SIGSEGV} blocked (e.g., by using the @code{system()} C library
 
8672
function call), it misbehaves badly.
 
8673
 
 
8674
@item
 
8675
In a questionable attempt at security, the SVR4.2 shell,
 
8676
when invoked without the @option{-p} option, will alter its real
 
8677
and effective @sc{uid} and @sc{gid} if they are less than some
 
8678
magic threshold value, commonly 100.
 
8679
This can lead to unexpected results.
 
8680
 
 
8681
@item
 
8682
The SVR4.2 shell does not allow users to trap @code{SIGSEGV},
 
8683
@code{SIGALRM}, or @code{SIGCHLD}.
 
8684
 
 
8685
@item
 
8686
The SVR4.2 shell does not allow the @env{IFS}, @env{MAILCHECK},
 
8687
@env{PATH}, @env{PS1}, or @env{PS2} variables to be unset.
 
8688
 
 
8689
@item
 
8690
The SVR4.2 shell treats @samp{^} as the undocumented equivalent of
 
8691
@samp{|}.
 
8692
 
 
8693
@item
 
8694
Bash allows multiple option arguments when it is invoked (@code{-x -v});
 
8695
the SVR4.2 shell allows only one option argument (@code{-xv}).  In
 
8696
fact, some versions of the shell dump core if the second argument begins
 
8697
with a @samp{-}.
 
8698
 
 
8699
@item
 
8700
The SVR4.2 shell exits a script if any builtin fails; Bash exits
 
8701
a script only if one of the @sc{posix} special builtins fails, and
 
8702
only for certain failures, as enumerated in the @sc{posix} standard.
 
8703
 
 
8704
@item 
 
8705
The SVR4.2 shell behaves differently when invoked as @code{jsh}
 
8706
(it turns on job control).
 
8707
@end itemize
 
8708
 
 
8709
@node GNU Free Documentation License
 
8710
@appendix GNU Free Documentation License
 
8711
 
 
8712
@include fdl.texi
 
8713
 
 
8714
@node Indexes
 
8715
@appendix Indexes
 
8716
 
 
8717
@menu
 
8718
* Builtin Index::               Index of Bash builtin commands.
 
8719
* Reserved Word Index::         Index of Bash reserved words.
 
8720
* Variable Index::              Quick reference helps you find the
 
8721
                                variable you want.
 
8722
* Function Index::              Index of bindable Readline functions.
 
8723
* Concept Index::               General index for concepts described in
 
8724
                                this manual.
 
8725
@end menu
 
8726
 
 
8727
@node Builtin Index
 
8728
@appendixsec Index of Shell Builtin Commands
 
8729
@printindex bt
 
8730
 
 
8731
@node Reserved Word Index
 
8732
@appendixsec Index of Shell Reserved Words
 
8733
@printindex rw
 
8734
 
 
8735
@node Variable Index
 
8736
@appendixsec Parameter and Variable Index
 
8737
@printindex vr
 
8738
 
 
8739
@node Function Index
 
8740
@appendixsec Function Index
 
8741
@printindex fn
 
8742
 
 
8743
@node Concept Index
 
8744
@appendixsec Concept Index
 
8745
@printindex cp
 
8746
 
 
8747
@bye