RCvc4yBC

1Bash Features
21 Introduction
3  1.1 What is Bash?
4  1.2 What is a shell?
52 Definitions
63 Basic Shell Features
7  3.1 Shell Syntax
8    3.1.1 Shell Operation
9    3.1.2 Quoting
10      3.1.2.1 Escape Character
11      3.1.2.2 Single Quotes
12      3.1.2.3 Double Quotes
13      3.1.2.4 ANSI-C Quoting
14      3.1.2.5 Locale-Specific Translation
15    3.1.3 Comments
16  3.2 Shell Commands
17    3.2.1 Simple Commands
18    3.2.2 Pipelines
19    3.2.3 Lists of Commands
20    3.2.4 Compound Commands
21      3.2.4.1 Looping Constructs
22      3.2.4.2 Conditional Constructs
23      3.2.4.3 Grouping Commands
24    3.2.5 Coprocesses
25    3.2.6 GNU Parallel
26  3.3 Shell Functions
27  3.4 Shell Parameters
28    3.4.1 Positional Parameters
29    3.4.2 Special Parameters
30  3.5 Shell Expansions
31    3.5.1 Brace Expansion
32    3.5.2 Tilde Expansion
33    3.5.3 Shell Parameter Expansion
34    3.5.4 Command Substitution
35    3.5.5 Arithmetic Expansion
36    3.5.6 Process Substitution
37    3.5.7 Word Splitting
38    3.5.8 Filename Expansion
39      3.5.8.1 Pattern Matching
40    3.5.9 Quote Removal
41  3.6 Redirections
42    3.6.1 Redirecting Input
43    3.6.2 Redirecting Output
44    3.6.3 Appending Redirected Output
45    3.6.4 Redirecting Standard Output and Standard Error
46    3.6.5 Appending Standard Output and Standard Error
47    3.6.6 Here Documents
48    3.6.7 Here Strings
49    3.6.8 Duplicating File Descriptors
50    3.6.9 Moving File Descriptors
51    3.6.10 Opening File Descriptors for Reading and Writing
52  3.7 Executing Commands
53    3.7.1 Simple Command Expansion
54    3.7.2 Command Search and Execution
55    3.7.3 Command Execution Environment
56    3.7.4 Environment
57    3.7.5 Exit Status
58    3.7.6 Signals
59  3.8 Shell Scripts
604 Shell Builtin Commands
61  4.1 Bourne Shell Builtins
62  4.2 Bash Builtin Commands
63  4.3 Modifying Shell Behavior
64    4.3.1 The Set Builtin
65    4.3.2 The Shopt Builtin
66  4.4 Special Builtins
675 Shell Variables
68  5.1 Bourne Shell Variables
69  5.2 Bash Variables
706 Bash Features
71  6.1 Invoking Bash
72  6.2 Bash Startup Files
73  6.3 Interactive Shells
74    6.3.1 What is an Interactive Shell?
75    6.3.2 Is this Shell Interactive?
76    6.3.3 Interactive Shell Behavior
77  6.4 Bash Conditional Expressions
78  6.5 Shell Arithmetic
79  6.6 Aliases
80  6.7 Arrays
81  6.8 The Directory Stack
82    6.8.1 Directory Stack Builtins
83  6.9 Controlling the Prompt
84  6.10 The Restricted Shell
85  6.11 Bash POSIX Mode
867 Job Control
87  7.1 Job Control Basics
88  7.2 Job Control Builtins
89  7.3 Job Control Variables
908 Command Line Editing
91  8.1 Introduction to Line Editing
92  8.2 Readline Interaction
93    8.2.1 Readline Bare Essentials
94    8.2.2 Readline Movement Commands
95    8.2.3 Readline Killing Commands
96    8.2.4 Readline Arguments
97    8.2.5 Searching for Commands in the History
98  8.3 Readline Init File
99    8.3.1 Readline Init File Syntax
100    8.3.2 Conditional Init Constructs
101    8.3.3 Sample Init File
102  8.4 Bindable Readline Commands
103    8.4.1 Commands For Moving
104    8.4.2 Commands For Manipulating The History
105    8.4.3 Commands For Changing Text
106    8.4.4 Killing And Yanking
107    8.4.5 Specifying Numeric Arguments
108    8.4.6 Letting Readline Type For You
109    8.4.7 Keyboard Macros
110    8.4.8 Some Miscellaneous Commands
111  8.5 Readline vi Mode
112  8.6 Programmable Completion
113  8.7 Programmable Completion Builtins
114  8.8 A Programmable Completion Example
1159 Using History Interactively
116  9.1 Bash History Facilities
117  9.2 Bash History Builtins
118  9.3 History Expansion
119    9.3.1 Event Designators
120    9.3.2 Word Designators
121    9.3.3 Modifiers
12210 Installing Bash
123  10.1 Basic Installation
124  10.2 Compilers and Options
125  10.3 Compiling For Multiple Architectures
126  10.4 Installation Names
127  10.5 Specifying the System Type
128  10.6 Sharing Defaults
129  10.7 Operation Controls
130  10.8 Optional Features
131Appendix A Reporting Bugs
132Appendix B Major Differences From The Bourne Shell
133  B.1 Implementation Differences From The SVR4.2 Shell
134Appendix C GNU Free Documentation License
135Appendix D Indexes
136  D.1 Index of Shell Builtin Commands
137  D.2 Index of Shell Reserved Words
138  D.3 Parameter and Variable Index
139  D.4 Function Index
140  D.5 Concept Index
141Bash Features
142*************
143
144This text is a brief description of the features that are present in the
145Bash shell (version 4.4, 7 September 2016).  The Bash home page is
146<http://www.gnu.org/software/bash/>.
147
148   This is Edition 4.4, last updated 7 September 2016, of 'The GNU Bash
149Reference Manual', for 'Bash', Version 4.4.
150
151   Bash contains features that appear in other popular shells, and some
152features that only appear in Bash.  Some of the shells that Bash has
153borrowed concepts from are the Bourne Shell ('sh'), the Korn Shell
154('ksh'), and the C-shell ('csh' and its successor, 'tcsh').  The
155following menu breaks the features up into categories, noting which
156features were inspired by other shells and which are specific to Bash.
157
158   This manual is meant as a brief introduction to features found in
159Bash.  The Bash manual page should be used as the definitive reference
160on shell behavior.
161
1621 Introduction
163**************
164
1651.1 What is Bash?
166=================
167
168Bash is the shell, or command language interpreter, for the GNU
169operating system.  The name is an acronym for the 'Bourne-Again SHell',
170a pun on Stephen Bourne, the author of the direct ancestor of the
171current Unix shell 'sh', which appeared in the Seventh Edition Bell Labs
172Research version of Unix.
173
174   Bash is largely compatible with 'sh' and incorporates useful features
175from the Korn shell 'ksh' and the C shell 'csh'.  It is intended to be a
176conformant implementation of the IEEE POSIX Shell and Tools portion of
177the IEEE POSIX specification (IEEE Standard 1003.1).  It offers
178functional improvements over 'sh' for both interactive and programming
179use.
180
181   While the GNU operating system provides other shells, including a
182version of 'csh', Bash is the default shell.  Like other GNU software,
183Bash is quite portable.  It currently runs on nearly every version of
184Unix and a few other operating systems - independently-supported ports
185exist for MS-DOS, OS/2, and Windows platforms.
186
1871.2 What is a shell?
188====================
189
190At its base, a shell is simply a macro processor that executes commands.
191The term macro processor means functionality where text and symbols are
192expanded to create larger expressions.
193
194   A Unix shell is both a command interpreter and a programming
195language.  As a command interpreter, the shell provides the user
196interface to the rich set of GNU utilities.  The programming language
197features allow these utilities to be combined.  Files containing
198commands can be created, and become commands themselves.  These new
199commands have the same status as system commands in directories such as
200'/bin', allowing users or groups to establish custom environments to
201automate their common tasks.
202
203   Shells may be used interactively or non-interactively.  In
204interactive mode, they accept input typed from the keyboard.  When
205executing non-interactively, shells execute commands read from a file.
206
207   A shell allows execution of GNU commands, both synchronously and
208asynchronously.  The shell waits for synchronous commands to complete
209before accepting more input; asynchronous commands continue to execute
210in parallel with the shell while it reads and executes additional
211commands.  The "redirection" constructs permit fine-grained control of
212the input and output of those commands.  Moreover, the shell allows
213control over the contents of commands' environments.
214
215   Shells also provide a small set of built-in commands ("builtins")
216implementing functionality impossible or inconvenient to obtain via
217separate utilities.  For example, 'cd', 'break', 'continue', and 'exec'
218cannot be implemented outside of the shell because they directly
219manipulate the shell itself.  The 'history', 'getopts', 'kill', or 'pwd'
220builtins, among others, could be implemented in separate utilities, but
221they are more convenient to use as builtin commands.  All of the shell
222builtins are described in subsequent sections.
223
224   While executing commands is essential, most of the power (and
225complexity) of shells is due to their embedded programming languages.
226Like any high-level language, the shell provides variables, flow control
227constructs, quoting, and functions.
228
229   Shells offer features geared specifically for interactive use rather
230than to augment the programming language.  These interactive features
231include job control, command line editing, command history and aliases.
232Each of these features is described in this manual.
233
2342 Definitions
235*************
236
237These definitions are used throughout the remainder of this manual.
238
239'POSIX'
240     A family of open system standards based on Unix.  Bash is primarily
241     concerned with the Shell and Utilities portion of the POSIX 1003.1
242     standard.
243
244'blank'
245     A space or tab character.
246
247'builtin'
248     A command that is implemented internally by the shell itself,
249     rather than by an executable program somewhere in the file system.
250
251'control operator'
252     A 'token' that performs a control function.  It is a 'newline' or
253     one of the following: '||', '&&', '&', ';', ';;', ';&', ';;&', '|',
254     '|&', '(', or ')'.
255
256'exit status'
257     The value returned by a command to its caller.  The value is
258     restricted to eight bits, so the maximum value is 255.
259
260'field'
261     A unit of text that is the result of one of the shell expansions.
262     After expansion, when executing a command, the resulting fields are
263     used as the command name and arguments.
264
265'filename'
266     A string of characters used to identify a file.
267
268'job'
269     A set of processes comprising a pipeline, and any processes
270     descended from it, that are all in the same process group.
271
272'job control'
273     A mechanism by which users can selectively stop (suspend) and
274     restart (resume) execution of processes.
275
276'metacharacter'
277     A character that, when unquoted, separates words.  A metacharacter
278     is a 'space', 'tab', 'newline', or one of the following characters:
279     '|', '&', ';', '(', ')', '<', or '>'.
280
281'name'
282     A 'word' consisting solely of letters, numbers, and underscores,
283     and beginning with a letter or underscore.  'Name's are used as
284     shell variable and function names.  Also referred to as an
285     'identifier'.
286
287'operator'
288     A 'control operator' or a 'redirection operator'.  *Note
289     Redirections::, for a list of redirection operators.  Operators
290     contain at least one unquoted 'metacharacter'.
291
292'process group'
293     A collection of related processes each having the same process
294     group ID.
295
296'process group ID'
297     A unique identifier that represents a 'process group' during its
298     lifetime.
299
300'reserved word'
301     A 'word' that has a special meaning to the shell.  Most reserved
302     words introduce shell flow control constructs, such as 'for' and
303     'while'.
304
305'return status'
306     A synonym for 'exit status'.
307
308'signal'
309     A mechanism by which a process may be notified by the kernel of an
310     event occurring in the system.
311
312'special builtin'
313     A shell builtin command that has been classified as special by the
314     POSIX standard.
315
316'token'
317     A sequence of characters considered a single unit by the shell.  It
318     is either a 'word' or an 'operator'.
319
320'word'
321     A sequence of characters treated as a unit by the shell.  Words may
322     not include unquoted 'metacharacters'.
323
3243 Basic Shell Features
325**********************
326
327Bash is an acronym for 'Bourne-Again SHell'.  The Bourne shell is the
328traditional Unix shell originally written by Stephen Bourne.  All of the
329Bourne shell builtin commands are available in Bash, The rules for
330evaluation and quoting are taken from the POSIX specification for the
331'standard' Unix shell.
332
333   This chapter briefly summarizes the shell's 'building blocks':
334commands, control structures, shell functions, shell parameters, shell
335expansions, redirections, which are a way to direct input and output
336from and to named files, and how the shell executes commands.
337
3383.1 Shell Syntax
339================
340
341When the shell reads input, it proceeds through a sequence of
342operations.  If the input indicates the beginning of a comment, the
343shell ignores the comment symbol ('#'), and the rest of that line.
344
345   Otherwise, roughly speaking, the shell reads its input and divides
346the input into words and operators, employing the quoting rules to
347select which meanings to assign various words and characters.
348
349   The shell then parses these tokens into commands and other
350constructs, removes the special meaning of certain words or characters,
351expands others, redirects input and output as needed, executes the
352specified command, waits for the command's exit status, and makes that
353exit status available for further inspection or processing.
354
3553.1.1 Shell Operation
356---------------------
357
358The following is a brief description of the shell's operation when it
359reads and executes a command.  Basically, the shell does the following:
360
361  1. Reads its input from a file (*note Shell Scripts::), from a string
362     supplied as an argument to the '-c' invocation option (*note
363     Invoking Bash::), or from the user's terminal.
364
365  2. Breaks the input into words and operators, obeying the quoting
366     rules described in *note Quoting::.  These tokens are separated by
367     'metacharacters'.  Alias expansion is performed by this step (*note
368     Aliases::).
369
370  3. Parses the tokens into simple and compound commands (*note Shell
371     Commands::).
372
373  4. Performs the various shell expansions (*note Shell Expansions::),
374     breaking the expanded tokens into lists of filenames (*note
375     Filename Expansion::) and commands and arguments.
376
377  5. Performs any necessary redirections (*note Redirections::) and
378     removes the redirection operators and their operands from the
379     argument list.
380
381  6. Executes the command (*note Executing Commands::).
382
383  7. Optionally waits for the command to complete and collects its exit
384     status (*note Exit Status::).
385
3863.1.2 Quoting
387-------------
388
389Quoting is used to remove the special meaning of certain characters or
390words to the shell.  Quoting can be used to disable special treatment
391for special characters, to prevent reserved words from being recognized
392as such, and to prevent parameter expansion.
393
394   Each of the shell metacharacters (*note Definitions::) has special
395meaning to the shell and must be quoted if it is to represent itself.
396When the command history expansion facilities are being used (*note
397History Interaction::), the HISTORY EXPANSION character, usually '!',
398must be quoted to prevent history expansion.  *Note Bash History
399Facilities::, for more details concerning history expansion.
400
401   There are three quoting mechanisms: the ESCAPE CHARACTER, single
402quotes, and double quotes.
403
4043.1.2.1 Escape Character
405........................
406
407A non-quoted backslash '\' is the Bash escape character.  It preserves
408the literal value of the next character that follows, with the exception
409of 'newline'.  If a '\newline' pair appears, and the backslash itself is
410not quoted, the '\newline' is treated as a line continuation (that is,
411it is removed from the input stream and effectively ignored).
412
4133.1.2.2 Single Quotes
414.....................
415
416Enclosing characters in single quotes (''') preserves the literal value
417of each character within the quotes.  A single quote may not occur
418between single quotes, even when preceded by a backslash.
419
4203.1.2.3 Double Quotes
421.....................
422
423Enclosing characters in double quotes ('"') preserves the literal value
424of all characters within the quotes, with the exception of '$', '`',
425'\', and, when history expansion is enabled, '!'.  When the shell is in
426POSIX mode (*note Bash POSIX Mode::), the '!' has no special meaning
427within double quotes, even when history expansion is enabled.  The
428characters '$' and '`' retain their special meaning within double quotes
429(*note Shell Expansions::).  The backslash retains its special meaning
430only when followed by one of the following characters: '$', '`', '"',
431'\', or 'newline'.  Within double quotes, backslashes that are followed
432by one of these characters are removed.  Backslashes preceding
433characters without a special meaning are left unmodified.  A double
434quote may be quoted within double quotes by preceding it with a
435backslash.  If enabled, history expansion will be performed unless an
436'!' appearing in double quotes is escaped using a backslash.  The
437backslash preceding the '!' is not removed.
438
439   The special parameters '*' and '@' have special meaning when in
440double quotes (*note Shell Parameter Expansion::).
441
4423.1.2.4 ANSI-C Quoting
443......................
444
445Words of the form '$'STRING'' are treated specially.  The word expands
446to STRING, with backslash-escaped characters replaced as specified by
447the ANSI C standard.  Backslash escape sequences, if present, are
448decoded as follows:
449
450'\a'
451     alert (bell)
452'\b'
453     backspace
454'\e'
455'\E'
456     an escape character (not ANSI C)
457'\f'
458     form feed
459'\n'
460     newline
461'\r'
462     carriage return
463'\t'
464     horizontal tab
465'\v'
466     vertical tab
467'\\'
468     backslash
469'\''
470     single quote
471'\"'
472     double quote
473'\?'
474     question mark
475'\NNN'
476     the eight-bit character whose value is the octal value NNN (one to
477     three digits)
478'\xHH'
479     the eight-bit character whose value is the hexadecimal value HH
480     (one or two hex digits)
481'\uHHHH'
482     the Unicode (ISO/IEC 10646) character whose value is the
483     hexadecimal value HHHH (one to four hex digits)
484'\UHHHHHHHH'
485     the Unicode (ISO/IEC 10646) character whose value is the
486     hexadecimal value HHHHHHHH (one to eight hex digits)
487'\cX'
488     a control-X character
489
490The expanded result is single-quoted, as if the dollar sign had not been
491present.
492
4933.1.2.5 Locale-Specific Translation
494...................................
495
496A double-quoted string preceded by a dollar sign ('$') will cause the
497string to be translated according to the current locale.  If the current
498locale is 'C' or 'POSIX', the dollar sign is ignored.  If the string is
499translated and replaced, the replacement is double-quoted.
500
501   Some systems use the message catalog selected by the 'LC_MESSAGES'
502shell variable.  Others create the name of the message catalog from the
503value of the 'TEXTDOMAIN' shell variable, possibly adding a suffix of
504'.mo'.  If you use the 'TEXTDOMAIN' variable, you may need to set the
505'TEXTDOMAINDIR' variable to the location of the message catalog files.
506Still others use both variables in this fashion:
507'TEXTDOMAINDIR'/'LC_MESSAGES'/LC_MESSAGES/'TEXTDOMAIN'.mo.
508
5093.1.3 Comments
510--------------
511
512In a non-interactive shell, or an interactive shell in which the
513'interactive_comments' option to the 'shopt' builtin is enabled (*note
514The Shopt Builtin::), a word beginning with '#' causes that word and all
515remaining characters on that line to be ignored.  An interactive shell
516without the 'interactive_comments' option enabled does not allow
517comments.  The 'interactive_comments' option is on by default in
518interactive shells.  *Note Interactive Shells::, for a description of
519what makes a shell interactive.
520
5213.2 Shell Commands
522==================
523
524A simple shell command such as 'echo a b c' consists of the command
525itself followed by arguments, separated by spaces.
526
527   More complex shell commands are composed of simple commands arranged
528together in a variety of ways: in a pipeline in which the output of one
529command becomes the input of a second, in a loop or conditional
530construct, or in some other grouping.
531
5323.2.1 Simple Commands
533---------------------
534
535A simple command is the kind of command encountered most often.  It's
536just a sequence of words separated by 'blank's, terminated by one of the
537shell's control operators (*note Definitions::).  The first word
538generally specifies a command to be executed, with the rest of the words
539being that command's arguments.
540
541   The return status (*note Exit Status::) of a simple command is its
542exit status as provided by the POSIX 1003.1 'waitpid' function, or 128+N
543if the command was terminated by signal N.
544
5453.2.2 Pipelines
546---------------
547
548A 'pipeline' is a sequence of one or more commands separated by one of
549the control operators '|' or '|&'.
550
551   The format for a pipeline is
552     [time [-p]] [!] COMMAND1 [ | or |& COMMAND2 ] ...
553
554The output of each command in the pipeline is connected via a pipe to
555the input of the next command.  That is, each command reads the previous
556command's output.  This connection is performed before any redirections
557specified by the command.
558
559   If '|&' is used, COMMAND1's standard error, in addition to its
560standard output, is connected to COMMAND2's standard input through the
561pipe; it is shorthand for '2>&1 |'.  This implicit redirection of the
562standard error to the standard output is performed after any
563redirections specified by the command.
564
565   The reserved word 'time' causes timing statistics to be printed for
566the pipeline once it finishes.  The statistics currently consist of
567elapsed (wall-clock) time and user and system time consumed by the
568command's execution.  The '-p' option changes the output format to that
569specified by POSIX.  When the shell is in POSIX mode (*note Bash POSIX
570Mode::), it does not recognize 'time' as a reserved word if the next
571token begins with a '-'.  The 'TIMEFORMAT' variable may be set to a
572format string that specifies how the timing information should be
573displayed.  *Note Bash Variables::, for a description of the available
574formats.  The use of 'time' as a reserved word permits the timing of
575shell builtins, shell functions, and pipelines.  An external 'time'
576command cannot time these easily.
577
578   When the shell is in POSIX mode (*note Bash POSIX Mode::), 'time' may
579be followed by a newline.  In this case, the shell displays the total
580user and system time consumed by the shell and its children.  The
581'TIMEFORMAT' variable may be used to specify the format of the time
582information.
583
584   If the pipeline is not executed asynchronously (*note Lists::), the
585shell waits for all commands in the pipeline to complete.
586
587   Each command in a pipeline is executed in its own subshell (*note
588Command Execution Environment::).  The exit status of a pipeline is the
589exit status of the last command in the pipeline, unless the 'pipefail'
590option is enabled (*note The Set Builtin::).  If 'pipefail' is enabled,
591the pipeline's return status is the value of the last (rightmost)
592command to exit with a non-zero status, or zero if all commands exit
593successfully.  If the reserved word '!' precedes the pipeline, the exit
594status is the logical negation of the exit status as described above.
595The shell waits for all commands in the pipeline to terminate before
596returning a value.
597
5983.2.3 Lists of Commands
599-----------------------
600
601A 'list' is a sequence of one or more pipelines separated by one of the
602operators ';', '&', '&&', or '||', and optionally terminated by one of
603';', '&', or a 'newline'.
604
605   Of these list operators, '&&' and '||' have equal precedence,
606followed by ';' and '&', which have equal precedence.
607
608   A sequence of one or more newlines may appear in a 'list' to delimit
609commands, equivalent to a semicolon.
610
611   If a command is terminated by the control operator '&', the shell
612executes the command asynchronously in a subshell.  This is known as
613executing the command in the BACKGROUND.  The shell does not wait for
614the command to finish, and the return status is 0 (true).  When job
615control is not active (*note Job Control::), the standard input for
616asynchronous commands, in the absence of any explicit redirections, is
617redirected from '/dev/null'.
618
619   Commands separated by a ';' are executed sequentially; the shell
620waits for each command to terminate in turn.  The return status is the
621exit status of the last command executed.
622
623   AND and OR lists are sequences of one or more pipelines separated by
624the control operators '&&' and '||', respectively.  AND and OR lists are
625executed with left associativity.
626
627   An AND list has the form
628     COMMAND1 && COMMAND2
629
630COMMAND2 is executed if, and only if, COMMAND1 returns an exit status of
631zero.
632
633   An OR list has the form
634     COMMAND1 || COMMAND2
635
636COMMAND2 is executed if, and only if, COMMAND1 returns a non-zero exit
637status.
638
639   The return status of AND and OR lists is the exit status of the last
640command executed in the list.
641
6423.2.4 Compound Commands
643-----------------------
644
645Compound commands are the shell programming constructs.  Each construct
646begins with a reserved word or control operator and is terminated by a
647corresponding reserved word or operator.  Any redirections (*note
648Redirections::) associated with a compound command apply to all commands
649within that compound command unless explicitly overridden.
650
651   In most cases a list of commands in a compound command's description
652may be separated from the rest of the command by one or more newlines,
653and may be followed by a newline in place of a semicolon.
654
655   Bash provides looping constructs, conditional commands, and
656mechanisms to group commands and execute them as a unit.
657
6583.2.4.1 Looping Constructs
659..........................
660
661Bash supports the following looping constructs.
662
663   Note that wherever a ';' appears in the description of a command's
664syntax, it may be replaced with one or more newlines.
665
666'until'
667     The syntax of the 'until' command is:
668
669          until TEST-COMMANDS; do CONSEQUENT-COMMANDS; done
670
671     Execute CONSEQUENT-COMMANDS as long as TEST-COMMANDS has an exit
672     status which is not zero.  The return status is the exit status of
673     the last command executed in CONSEQUENT-COMMANDS, or zero if none
674     was executed.
675
676'while'
677     The syntax of the 'while' command is:
678
679          while TEST-COMMANDS; do CONSEQUENT-COMMANDS; done
680
681     Execute CONSEQUENT-COMMANDS as long as TEST-COMMANDS has an exit
682     status of zero.  The return status is the exit status of the last
683     command executed in CONSEQUENT-COMMANDS, or zero if none was
684     executed.
685
686'for'
687     The syntax of the 'for' command is:
688
689          for NAME [ [in [WORDS ...] ] ; ] do COMMANDS; done
690
691     Expand WORDS, and execute COMMANDS once for each member in the
692     resultant list, with NAME bound to the current member.  If 'in
693     WORDS' is not present, the 'for' command executes the COMMANDS once
694     for each positional parameter that is set, as if 'in "$@"' had been
695     specified (*note Special Parameters::).  The return status is the
696     exit status of the last command that executes.  If there are no
697     items in the expansion of WORDS, no commands are executed, and the
698     return status is zero.
699
700     An alternate form of the 'for' command is also supported:
701
702          for (( EXPR1 ; EXPR2 ; EXPR3 )) ; do COMMANDS ; done
703
704     First, the arithmetic expression EXPR1 is evaluated according to
705     the rules described below (*note Shell Arithmetic::).  The
706     arithmetic expression EXPR2 is then evaluated repeatedly until it
707     evaluates to zero.  Each time EXPR2 evaluates to a non-zero value,
708     COMMANDS are executed and the arithmetic expression EXPR3 is
709     evaluated.  If any expression is omitted, it behaves as if it
710     evaluates to 1.  The return value is the exit status of the last
711     command in COMMANDS that is executed, or false if any of the
712     expressions is invalid.
713
714   The 'break' and 'continue' builtins (*note Bourne Shell Builtins::)
715may be used to control loop execution.
716
7173.2.4.2 Conditional Constructs
718..............................
719
720'if'
721     The syntax of the 'if' command is:
722
723          if TEST-COMMANDS; then
724            CONSEQUENT-COMMANDS;
725          [elif MORE-TEST-COMMANDS; then
726            MORE-CONSEQUENTS;]
727          [else ALTERNATE-CONSEQUENTS;]
728          fi
729
730     The TEST-COMMANDS list is executed, and if its return status is
731     zero, the CONSEQUENT-COMMANDS list is executed.  If TEST-COMMANDS
732     returns a non-zero status, each 'elif' list is executed in turn,
733     and if its exit status is zero, the corresponding MORE-CONSEQUENTS
734     is executed and the command completes.  If 'else
735     ALTERNATE-CONSEQUENTS' is present, and the final command in the
736     final 'if' or 'elif' clause has a non-zero exit status, then
737     ALTERNATE-CONSEQUENTS is executed.  The return status is the exit
738     status of the last command executed, or zero if no condition tested
739     true.
740
741'case'
742     The syntax of the 'case' command is:
743
744          case WORD in [ [(] PATTERN [| PATTERN]...) COMMAND-LIST ;;]... esac
745
746     'case' will selectively execute the COMMAND-LIST corresponding to
747     the first PATTERN that matches WORD.  If the 'nocasematch' shell
748     option (see the description of 'shopt' in *note The Shopt
749     Builtin::) is enabled, the match is performed without regard to the
750     case of alphabetic characters.  The '|' is used to separate
751     multiple patterns, and the ')' operator terminates a pattern list.
752     A list of patterns and an associated command-list is known as a
753     CLAUSE.
754
755     Each clause must be terminated with ';;', ';&', or ';;&'.  The WORD
756     undergoes tilde expansion, parameter expansion, command
757     substitution, arithmetic expansion, and quote removal before
758     matching is attempted.  Each PATTERN undergoes tilde expansion,
759     parameter expansion, command substitution, and arithmetic
760     expansion.
761
762     There may be an arbitrary number of 'case' clauses, each terminated
763     by a ';;', ';&', or ';;&'.  The first pattern that matches
764     determines the command-list that is executed.  It's a common idiom
765     to use '*' as the final pattern to define the default case, since
766     that pattern will always match.
767
768     Here is an example using 'case' in a script that could be used to
769     describe one interesting feature of an animal:
770
771          echo -n "Enter the name of an animal: "
772          read ANIMAL
773          echo -n "The $ANIMAL has "
774          case $ANIMAL in
775            horse | dog | cat) echo -n "four";;
776            man | kangaroo ) echo -n "two";;
777            *) echo -n "an unknown number of";;
778          esac
779          echo " legs."
780
781
782     If the ';;' operator is used, no subsequent matches are attempted
783     after the first pattern match.  Using ';&' in place of ';;' causes
784     execution to continue with the COMMAND-LIST associated with the
785     next clause, if any.  Using ';;&' in place of ';;' causes the shell
786     to test the patterns in the next clause, if any, and execute any
787     associated COMMAND-LIST on a successful match.
788
789     The return status is zero if no PATTERN is matched.  Otherwise, the
790     return status is the exit status of the COMMAND-LIST executed.
791
792'select'
793
794     The 'select' construct allows the easy generation of menus.  It has
795     almost the same syntax as the 'for' command:
796
797          select NAME [in WORDS ...]; do COMMANDS; done
798
799     The list of words following 'in' is expanded, generating a list of
800     items.  The set of expanded words is printed on the standard error
801     output stream, each preceded by a number.  If the 'in WORDS' is
802     omitted, the positional parameters are printed, as if 'in "$@"' had
803     been specified.  The 'PS3' prompt is then displayed and a line is
804     read from the standard input.  If the line consists of a number
805     corresponding to one of the displayed words, then the value of NAME
806     is set to that word.  If the line is empty, the words and prompt
807     are displayed again.  If 'EOF' is read, the 'select' command
808     completes.  Any other value read causes NAME to be set to null.
809     The line read is saved in the variable 'REPLY'.
810
811     The COMMANDS are executed after each selection until a 'break'
812     command is executed, at which point the 'select' command completes.
813
814     Here is an example that allows the user to pick a filename from the
815     current directory, and displays the name and index of the file
816     selected.
817
818          select fname in *;
819          do
820          	echo you picked $fname \($REPLY\)
821          	break;
822          done
823
824'((...))'
825          (( EXPRESSION ))
826
827     The arithmetic EXPRESSION is evaluated according to the rules
828     described below (*note Shell Arithmetic::).  If the value of the
829     expression is non-zero, the return status is 0; otherwise the
830     return status is 1.  This is exactly equivalent to
831          let "EXPRESSION"
832     *Note Bash Builtins::, for a full description of the 'let' builtin.
833
834'[[...]]'
835          [[ EXPRESSION ]]
836
837     Return a status of 0 or 1 depending on the evaluation of the
838     conditional expression EXPRESSION.  Expressions are composed of the
839     primaries described below in *note Bash Conditional Expressions::.
840     Word splitting and filename expansion are not performed on the
841     words between the '[[' and ']]'; tilde expansion, parameter and
842     variable expansion, arithmetic expansion, command substitution,
843     process substitution, and quote removal are performed.  Conditional
844     operators such as '-f' must be unquoted to be recognized as
845     primaries.
846
847     When used with '[[', the '<' and '>' operators sort
848     lexicographically using the current locale.
849
850     When the '==' and '!=' operators are used, the string to the right
851     of the operator is considered a pattern and matched according to
852     the rules described below in *note Pattern Matching::, as if the
853     'extglob' shell option were enabled.  The '=' operator is identical
854     to '=='.  If the 'nocasematch' shell option (see the description of
855     'shopt' in *note The Shopt Builtin::) is enabled, the match is
856     performed without regard to the case of alphabetic characters.  The
857     return value is 0 if the string matches ('==') or does not match
858     ('!=')the pattern, and 1 otherwise.  Any part of the pattern may be
859     quoted to force the quoted portion to be matched as a string.
860
861     An additional binary operator, '=~', is available, with the same
862     precedence as '==' and '!='.  When it is used, the string to the
863     right of the operator is considered an extended regular expression
864     and matched accordingly (as in regex3)).  The return value is 0 if
865     the string matches the pattern, and 1 otherwise.  If the regular
866     expression is syntactically incorrect, the conditional expression's
867     return value is 2.  If the 'nocasematch' shell option (see the
868     description of 'shopt' in *note The Shopt Builtin::) is enabled,
869     the match is performed without regard to the case of alphabetic
870     characters.  Any part of the pattern may be quoted to force the
871     quoted portion to be matched as a string.  Bracket expressions in
872     regular expressions must be treated carefully, since normal quoting
873     characters lose their meanings between brackets.  If the pattern is
874     stored in a shell variable, quoting the variable expansion forces
875     the entire pattern to be matched as a string.  Substrings matched
876     by parenthesized subexpressions within the regular expression are
877     saved in the array variable 'BASH_REMATCH'.  The element of
878     'BASH_REMATCH' with index 0 is the portion of the string matching
879     the entire regular expression.  The element of 'BASH_REMATCH' with
880     index N is the portion of the string matching the Nth parenthesized
881     subexpression.
882
883     For example, the following will match a line (stored in the shell
884     variable LINE) if there is a sequence of characters in the value
885     consisting of any number, including zero, of space characters, zero
886     or one instances of 'a', then a 'b':
887          [[ $line =~ [[:space:]]*(a)?b ]]
888
889     That means values like 'aab' and ' aaaaaab' will match, as will a
890     line containing a 'b' anywhere in its value.
891
892     Storing the regular expression in a shell variable is often a
893     useful way to avoid problems with quoting characters that are
894     special to the shell.  It is sometimes difficult to specify a
895     regular expression literally without using quotes, or to keep track
896     of the quoting used by regular expressions while paying attention
897     to the shell's quote removal.  Using a shell variable to store the
898     pattern decreases these problems.  For example, the following is
899     equivalent to the above:
900          pattern='[[:space:]]*(a)?b'
901          [[ $line =~ $pattern ]]
902
903     If you want to match a character that's special to the regular
904     expression grammar, it has to be quoted to remove its special
905     meaning.  This means that in the pattern 'xxx.txt', the '.' matches
906     any character in the string (its usual regular expression meaning),
907     but in the pattern '"xxx.txt"' it can only match a literal '.'.
908     Shell programmers should take special care with backslashes, since
909     backslashes are used both by the shell and regular expressions to
910     remove the special meaning from the following character.  The
911     following two sets of commands are _not_ equivalent:
912          pattern='\.'
913
914          [[ . =~ $pattern ]]
915          [[ . =~ \. ]]
916
917          [[ . =~ "$pattern" ]]
918          [[ . =~ '\.' ]]
919
920     The first two matches will succeed, but the second two will not,
921     because in the second two the backslash will be part of the pattern
922     to be matched.  In the first two examples, the backslash removes
923     the special meaning from '.', so the literal '.' matches.  If the
924     string in the first examples were anything other than '.', say 'a',
925     the pattern would not match, because the quoted '.' in the pattern
926     loses its special meaning of matching any single character.
927
928     Expressions may be combined using the following operators, listed
929     in decreasing order of precedence:
930
931     '( EXPRESSION )'
932          Returns the value of EXPRESSION.  This may be used to override
933          the normal precedence of operators.
934
935     '! EXPRESSION'
936          True if EXPRESSION is false.
937
938     'EXPRESSION1 && EXPRESSION2'
939          True if both EXPRESSION1 and EXPRESSION2 are true.
940
941     'EXPRESSION1 || EXPRESSION2'
942          True if either EXPRESSION1 or EXPRESSION2 is true.
943
944     The '&&' and '||' operators do not evaluate EXPRESSION2 if the
945     value of EXPRESSION1 is sufficient to determine the return value of
946     the entire conditional expression.
947
9483.2.4.3 Grouping Commands
949.........................
950
951Bash provides two ways to group a list of commands to be executed as a
952unit.  When commands are grouped, redirections may be applied to the
953entire command list.  For example, the output of all the commands in the
954list may be redirected to a single stream.
955
956'()'
957          ( LIST )
958
959     Placing a list of commands between parentheses causes a subshell
960     environment to be created (*note Command Execution Environment::),
961     and each of the commands in LIST to be executed in that subshell.
962     Since the LIST is executed in a subshell, variable assignments do
963     not remain in effect after the subshell completes.
964
965'{}'
966          { LIST; }
967
968     Placing a list of commands between curly braces causes the list to
969     be executed in the current shell context.  No subshell is created.
970     The semicolon (or newline) following LIST is required.
971
972   In addition to the creation of a subshell, there is a subtle
973difference between these two constructs due to historical reasons.  The
974braces are 'reserved words', so they must be separated from the LIST by
975'blank's or other shell metacharacters.  The parentheses are
976'operators', and are recognized as separate tokens by the shell even if
977they are not separated from the LIST by whitespace.
978
979   The exit status of both of these constructs is the exit status of
980LIST.
981
9823.2.5 Coprocesses
983-----------------
984
985A 'coprocess' is a shell command preceded by the 'coproc' reserved word.
986A coprocess is executed asynchronously in a subshell, as if the command
987had been terminated with the '&' control operator, with a two-way pipe
988established between the executing shell and the coprocess.
989
990   The format for a coprocess is:
991     coproc [NAME] COMMAND [REDIRECTIONS]
992
993This creates a coprocess named NAME.  If NAME is not supplied, the
994default name is COPROC.  NAME must not be supplied if COMMAND is a
995simple command (*note Simple Commands::); otherwise, it is interpreted
996as the first word of the simple command.
997
998   When the coprocess is executed, the shell creates an array variable
999(*note Arrays::) named 'NAME' in the context of the executing shell.
1000The standard output of COMMAND is connected via a pipe to a file
1001descriptor in the executing shell, and that file descriptor is assigned
1002to 'NAME'[0].  The standard input of COMMAND is connected via a pipe to
1003a file descriptor in the executing shell, and that file descriptor is
1004assigned to 'NAME'[1].  This pipe is established before any redirections
1005specified by the command (*note Redirections::).  The file descriptors
1006can be utilized as arguments to shell commands and redirections using
1007standard word expansions.  The file descriptors are not available in
1008subshells.
1009
1010   The process ID of the shell spawned to execute the coprocess is
1011available as the value of the variable 'NAME'_PID. The 'wait' builtin
1012command may be used to wait for the coprocess to terminate.
1013
1014   Since the coprocess is created as an asynchronous command, the
1015'coproc' command always returns success.  The return status of a
1016coprocess is the exit status of COMMAND.
1017
10183.2.6 GNU Parallel
1019------------------
1020
1021There are ways to run commands in parallel that are not built into Bash.
1022GNU Parallel is a tool to do just that.
1023
1024   GNU Parallel, as its name suggests, can be used to build and run
1025commands in parallel.  You may run the same command with different
1026arguments, whether they are filenames, usernames, hostnames, or lines
1027read from files.  GNU Parallel provides shorthand references to many of
1028the most common operations (input lines, various portions of the input
1029line, different ways to specify the input source, and so on).  Parallel
1030can replace 'xargs' or feed commands from its input sources to several
1031different instances of Bash.
1032
1033   For a complete description, refer to the GNU Parallel documentation.
1034A few examples should provide a brief introduction to its use.
1035
1036   For example, it is easy to replace 'xargs' to gzip all html files in
1037the current directory and its subdirectories:
1038     find . -type f -name '*.html' -print | parallel gzip
1039If you need to protect special characters such as newlines in file
1040names, use find's '-print0' option and parallel's '-0' option.
1041
1042   You can use Parallel to move files from the current directory when
1043the number of files is too large to process with one 'mv' invocation:
1044     ls | parallel mv {} destdir
1045
1046   As you can see, the {} is replaced with each line read from standard
1047input.  While using 'ls' will work in most instances, it is not
1048sufficient to deal with all filenames.  If you need to accommodate
1049special characters in filenames, you can use
1050
1051     find . -depth 1 \! -name '.*' -print0 | parallel -0 mv {} destdir
1052
1053as alluded to above.
1054
1055   This will run as many 'mv' commands as there are files in the current
1056directory.  You can emulate a parallel 'xargs' by adding the '-X'
1057option:
1058     find . -depth 1 \! -name '.*' -print0 | parallel -0 -X mv {} destdir
1059
1060   GNU Parallel can replace certain common idioms that operate on lines
1061read from a file (in this case, filenames listed one per line):
1062     	while IFS= read -r x; do
1063     		do-something1 "$x" "config-$x"
1064     		do-something2 < "$x"
1065     	done < file | process-output
1066
1067with a more compact syntax reminiscent of lambdas:
1068     cat list | parallel "do-something1 {} config-{} ; do-something2 < {}" | process-output
1069
1070   Parallel provides a built-in mechanism to remove filename extensions,
1071which lends itself to batch file transformations or renaming:
1072     ls *.gz | parallel -j+0 "zcat {} | bzip2 >{.}.bz2 && rm {}"
1073This will recompress all files in the current directory with names
1074ending in .gz using bzip2, running one job per CPU (-j+0) in parallel.
1075(We use 'ls' for brevity here; using 'find' as above is more robust in
1076the face of filenames containing unexpected characters.)  Parallel can
1077take arguments from the command line; the above can also be written as
1078
1079     parallel "zcat {} | bzip2 >{.}.bz2 && rm {}" ::: *.gz
1080
1081   If a command generates output, you may want to preserve the input
1082order in the output.  For instance, the following command
1083     { echo foss.org.my ; echo debian.org; echo freenetproject.org; } | parallel traceroute
1084will display as output the traceroute invocation that finishes first.
1085Adding the '-k' option
1086     { echo foss.org.my ; echo debian.org; echo freenetproject.org; } | parallel -k traceroute
1087will ensure that the output of 'traceroute foss.org.my' is displayed
1088first.
1089
1090   Finally, Parallel can be used to run a sequence of shell commands in
1091parallel, similar to 'cat file | bash'.  It is not uncommon to take a
1092list of filenames, create a series of shell commands to operate on them,
1093and feed that list of commnds to a shell.  Parallel can speed this up.
1094Assuming that 'file' contains a list of shell commands, one per line,
1095
1096     parallel -j 10 < file
1097
1098will evaluate the commands using the shell (since no explicit command is
1099supplied as an argument), in blocks of ten shell jobs at a time.
1100
11013.3 Shell Functions
1102===================
1103
1104Shell functions are a way to group commands for later execution using a
1105single name for the group.  They are executed just like a "regular"
1106command.  When the name of a shell function is used as a simple command
1107name, the list of commands associated with that function name is
1108executed.  Shell functions are executed in the current shell context; no
1109new process is created to interpret them.
1110
1111   Functions are declared using this syntax:
1112     NAME () COMPOUND-COMMAND [ REDIRECTIONS ]
1113
1114   or
1115
1116     function NAME [()] COMPOUND-COMMAND [ REDIRECTIONS ]
1117
1118   This defines a shell function named NAME.  The reserved word
1119'function' is optional.  If the 'function' reserved word is supplied,
1120the parentheses are optional.  The BODY of the function is the compound
1121command COMPOUND-COMMAND (*note Compound Commands::).  That command is
1122usually a LIST enclosed between { and }, but may be any compound command
1123listed above, with one exception: If the 'function' reserved word is
1124used, but the parentheses are not supplied, the braces are required.
1125COMPOUND-COMMAND is executed whenever NAME is specified as the name of a
1126command.  When the shell is in POSIX mode (*note Bash POSIX Mode::),
1127NAME may not be the same as one of the special builtins (*note Special
1128Builtins::).  Any redirections (*note Redirections::) associated with
1129the shell function are performed when the function is executed.
1130
1131   A function definition may be deleted using the '-f' option to the
1132'unset' builtin (*note Bourne Shell Builtins::).
1133
1134   The exit status of a function definition is zero unless a syntax
1135error occurs or a readonly function with the same name already exists.
1136When executed, the exit status of a function is the exit status of the
1137last command executed in the body.
1138
1139   Note that for historical reasons, in the most common usage the curly
1140braces that surround the body of the function must be separated from the
1141body by 'blank's or newlines.  This is because the braces are reserved
1142words and are only recognized as such when they are separated from the
1143command list by whitespace or another shell metacharacter.  Also, when
1144using the braces, the LIST must be terminated by a semicolon, a '&', or
1145a newline.
1146
1147   When a function is executed, the arguments to the function become the
1148positional parameters during its execution (*note Positional
1149Parameters::).  The special parameter '#' that expands to the number of
1150positional parameters is updated to reflect the change.  Special
1151parameter '0' is unchanged.  The first element of the 'FUNCNAME'
1152variable is set to the name of the function while the function is
1153executing.
1154
1155   All other aspects of the shell execution environment are identical
1156between a function and its caller with these exceptions: the 'DEBUG' and
1157'RETURN' traps are not inherited unless the function has been given the
1158'trace' attribute using the 'declare' builtin or the '-o functrace'
1159option has been enabled with the 'set' builtin, (in which case all
1160functions inherit the 'DEBUG' and 'RETURN' traps), and the 'ERR' trap is
1161not inherited unless the '-o errtrace' shell option has been enabled.
1162*Note Bourne Shell Builtins::, for the description of the 'trap'
1163builtin.
1164
1165   The 'FUNCNEST' variable, if set to a numeric value greater than 0,
1166defines a maximum function nesting level.  Function invocations that
1167exceed the limit cause the entire command to abort.
1168
1169   If the builtin command 'return' is executed in a function, the
1170function completes and execution resumes with the next command after the
1171function call.  Any command associated with the 'RETURN' trap is
1172executed before execution resumes.  When a function completes, the
1173values of the positional parameters and the special parameter '#' are
1174restored to the values they had prior to the function's execution.  If a
1175numeric argument is given to 'return', that is the function's return
1176status; otherwise the function's return status is the exit status of the
1177last command executed before the 'return'.
1178
1179   Variables local to the function may be declared with the 'local'
1180builtin.  These variables are visible only to the function and the
1181commands it invokes.
1182
1183   Function names and definitions may be listed with the '-f' option to
1184the 'declare' ('typeset') builtin command (*note Bash Builtins::).  The
1185'-F' option to 'declare' or 'typeset' will list the function names only
1186(and optionally the source file and line number, if the 'extdebug' shell
1187option is enabled).  Functions may be exported so that subshells
1188automatically have them defined with the '-f' option to the 'export'
1189builtin (*note Bourne Shell Builtins::).  Note that shell functions and
1190variables with the same name may result in multiple identically-named
1191entries in the environment passed to the shell's children.  Care should
1192be taken in cases where this may cause a problem.
1193
1194   Functions may be recursive.  The 'FUNCNEST' variable may be used to
1195limit the depth of the function call stack and restrict the number of
1196function invocations.  By default, no limit is placed on the number of
1197recursive calls.
1198
11993.4 Shell Parameters
1200====================
1201
1202A PARAMETER is an entity that stores values.  It can be a 'name', a
1203number, or one of the special characters listed below.  A VARIABLE is a
1204parameter denoted by a 'name'.  A variable has a VALUE and zero or more
1205ATTRIBUTES.  Attributes are assigned using the 'declare' builtin command
1206(see the description of the 'declare' builtin in *note Bash Builtins::).
1207
1208   A parameter is set if it has been assigned a value.  The null string
1209is a valid value.  Once a variable is set, it may be unset only by using
1210the 'unset' builtin command.
1211
1212   A variable may be assigned to by a statement of the form
1213     NAME=[VALUE]
1214If VALUE is not given, the variable is assigned the null string.  All
1215VALUEs undergo tilde expansion, parameter and variable expansion,
1216command substitution, arithmetic expansion, and quote removal (detailed
1217below).  If the variable has its 'integer' attribute set, then VALUE is
1218evaluated as an arithmetic expression even if the '$((...))' expansion
1219is not used (*note Arithmetic Expansion::).  Word splitting is not
1220performed, with the exception of '"$@"' as explained below.  Filename
1221expansion is not performed.  Assignment statements may also appear as
1222arguments to the 'alias', 'declare', 'typeset', 'export', 'readonly',
1223and 'local' builtin commands (DECLARATION commands).  When in POSIX mode
1224(*note Bash POSIX Mode::), these builtins may appear in a command after
1225one or more instances of the 'command' builtin and retain these
1226assignment statement properties.
1227
1228   In the context where an assignment statement is assigning a value to
1229a shell variable or array index (*note Arrays::), the '+=' operator can
1230be used to append to or add to the variable's previous value.  This
1231includes arguments to builtin commands such as 'declare' that accept
1232assignment statements (DECLARATION commands).  When '+=' is applied to a
1233variable for which the INTEGER attribute has been set, VALUE is
1234evaluated as an arithmetic expression and added to the variable's
1235current value, which is also evaluated.  When '+=' is applied to an
1236array variable using compound assignment (*note Arrays::), the
1237variable's value is not unset (as it is when using '='), and new values
1238are appended to the array beginning at one greater than the array's
1239maximum index (for indexed arrays), or added as additional key-value
1240pairs in an associative array.  When applied to a string-valued
1241variable, VALUE is expanded and appended to the variable's value.
1242
1243   A variable can be assigned the NAMEREF attribute using the '-n'
1244option to the 'declare' or 'local' builtin commands (*note Bash
1245Builtins::) to create a NAMEREF, or a reference to another variable.
1246This allows variables to be manipulated indirectly.  Whenever the
1247nameref variable is referenced, assigned to, unset, or has its
1248attributes modified (other than using or changing the nameref attribute
1249itself), the operation is actually performed on the variable specified
1250by the nameref variable's value.  A nameref is commonly used within
1251shell functions to refer to a variable whose name is passed as an
1252argument to the function.  For instance, if a variable name is passed to
1253a shell function as its first argument, running
1254     declare -n ref=$1
1255inside the function creates a nameref variable REF whose value is the
1256variable name passed as the first argument.  References and assignments
1257to REF, and changes to its attributes, are treated as references,
1258assignments, and attribute modifications to the variable whose name was
1259passed as '$1'.
1260
1261   If the control variable in a 'for' loop has the nameref attribute,
1262the list of words can be a list of shell variables, and a name reference
1263will be established for each word in the list, in turn, when the loop is
1264executed.  Array variables cannot be given the nameref attribute.
1265However, nameref variables can reference array variables and subscripted
1266array variables.  Namerefs can be unset using the '-n' option to the
1267'unset' builtin (*note Bourne Shell Builtins::).  Otherwise, if 'unset'
1268is executed with the name of a nameref variable as an argument, the
1269variable referenced by the nameref variable will be unset.
1270
12713.4.1 Positional Parameters
1272---------------------------
1273
1274A POSITIONAL PARAMETER is a parameter denoted by one or more digits,
1275other than the single digit '0'.  Positional parameters are assigned
1276from the shell's arguments when it is invoked, and may be reassigned
1277using the 'set' builtin command.  Positional parameter 'N' may be
1278referenced as '${N}', or as '$N' when 'N' consists of a single digit.
1279Positional parameters may not be assigned to with assignment statements.
1280The 'set' and 'shift' builtins are used to set and unset them (*note
1281Shell Builtin Commands::).  The positional parameters are temporarily
1282replaced when a shell function is executed (*note Shell Functions::).
1283
1284   When a positional parameter consisting of more than a single digit is
1285expanded, it must be enclosed in braces.
1286
12873.4.2 Special Parameters
1288------------------------
1289
1290The shell treats several parameters specially.  These parameters may
1291only be referenced; assignment to them is not allowed.
1292
1293'*'
1294     ($*) Expands to the positional parameters, starting from one.  When
1295     the expansion is not within double quotes, each positional
1296     parameter expands to a separate word.  In contexts where it is
1297     performed, those words are subject to further word splitting and
1298     pathname expansion.  When the expansion occurs within double
1299     quotes, it expands to a single word with the value of each
1300     parameter separated by the first character of the 'IFS' special
1301     variable.  That is, '"$*"' is equivalent to '"$1C$2C..."', where C
1302     is the first character of the value of the 'IFS' variable.  If
1303     'IFS' is unset, the parameters are separated by spaces.  If 'IFS'
1304     is null, the parameters are joined without intervening separators.
1305
1306'@'
1307     ($@) Expands to the positional parameters, starting from one.  When
1308     the expansion occurs within double quotes, each parameter expands
1309     to a separate word.  That is, '"$@"' is equivalent to '"$1" "$2"
1310     ...'.  If the double-quoted expansion occurs within a word, the
1311     expansion of the first parameter is joined with the beginning part
1312     of the original word, and the expansion of the last parameter is
1313     joined with the last part of the original word.  When there are no
1314     positional parameters, '"$@"' and '$@' expand to nothing (i.e.,
1315     they are removed).
1316
1317'#'
1318     ($#) Expands to the number of positional parameters in decimal.
1319
1320'?'
1321     ($?)  Expands to the exit status of the most recently executed
1322     foreground pipeline.
1323
1324'-'
1325     ($-, a hyphen.)  Expands to the current option flags as specified
1326     upon invocation, by the 'set' builtin command, or those set by the
1327     shell itself (such as the '-i' option).
1328
1329'$'
1330     ($$) Expands to the process ID of the shell.  In a '()' subshell,
1331     it expands to the process ID of the invoking shell, not the
1332     subshell.
1333
1334'!'
1335     ($!)  Expands to the process ID of the job most recently placed
1336     into the background, whether executed as an asynchronous command or
1337     using the 'bg' builtin (*note Job Control Builtins::).
1338
1339'0'
1340     ($0) Expands to the name of the shell or shell script.  This is set
1341     at shell initialization.  If Bash is invoked with a file of
1342     commands (*note Shell Scripts::), '$0' is set to the name of that
1343     file.  If Bash is started with the '-c' option (*note Invoking
1344     Bash::), then '$0' is set to the first argument after the string to
1345     be executed, if one is present.  Otherwise, it is set to the
1346     filename used to invoke Bash, as given by argument zero.
1347
1348'_'
1349     ($_, an underscore.)  At shell startup, set to the absolute
1350     pathname used to invoke the shell or shell script being executed as
1351     passed in the environment or argument list.  Subsequently, expands
1352     to the last argument to the previous command, after expansion.
1353     Also set to the full pathname used to invoke each command executed
1354     and placed in the environment exported to that command.  When
1355     checking mail, this parameter holds the name of the mail file.
1356
13573.5 Shell Expansions
1358====================
1359
1360Expansion is performed on the command line after it has been split into
1361'token's.  There are seven kinds of expansion performed:
1362
1363   * brace expansion
1364   * tilde expansion
1365   * parameter and variable expansion
1366   * command substitution
1367   * arithmetic expansion
1368   * word splitting
1369   * filename expansion
1370
1371   The order of expansions is: brace expansion; tilde expansion,
1372parameter and variable expansion, arithmetic expansion, and command
1373substitution (done in a left-to-right fashion); word splitting; and
1374filename expansion.
1375
1376   On systems that can support it, there is an additional expansion
1377available: PROCESS SUBSTITUTION.  This is performed at the same time as
1378tilde, parameter, variable, and arithmetic expansion and command
1379substitution.
1380
1381   After these expansions are performed, quote characters present in the
1382original word are removed unless they have been quoted themselves (QUOTE
1383REMOVAL).
1384
1385   Only brace expansion, word splitting, and filename expansion can
1386change the number of words of the expansion; other expansions expand a
1387single word to a single word.  The only exceptions to this are the
1388expansions of '"$@"' (*note Special Parameters::) and '"${NAME[@]}"'
1389(*note Arrays::).
1390
1391   After all expansions, 'quote removal' (*note Quote Removal::) is
1392performed.
1393
13943.5.1 Brace Expansion
1395---------------------
1396
1397Brace expansion is a mechanism by which arbitrary strings may be
1398generated.  This mechanism is similar to FILENAME EXPANSION (*note
1399Filename Expansion::), but the filenames generated need not exist.
1400Patterns to be brace expanded take the form of an optional PREAMBLE,
1401followed by either a series of comma-separated strings or a sequence
1402expression between a pair of braces, followed by an optional POSTSCRIPT.
1403The preamble is prefixed to each string contained within the braces, and
1404the postscript is then appended to each resulting string, expanding left
1405to right.
1406
1407   Brace expansions may be nested.  The results of each expanded string
1408are not sorted; left to right order is preserved.  For example,
1409     bash$ echo a{d,c,b}e
1410     ade ace abe
1411
1412   A sequence expression takes the form '{X..Y[..INCR]}', where X and Y
1413are either integers or single characters, and INCR, an optional
1414increment, is an integer.  When integers are supplied, the expression
1415expands to each number between X and Y, inclusive.  Supplied integers
1416may be prefixed with '0' to force each term to have the same width.
1417When either X or Y begins with a zero, the shell attempts to force all
1418generated terms to contain the same number of digits, zero-padding where
1419necessary.  When characters are supplied, the expression expands to each
1420character lexicographically between X and Y, inclusive, using the
1421default C locale.  Note that both X and Y must be of the same type.
1422When the increment is supplied, it is used as the difference between
1423each term.  The default increment is 1 or -1 as appropriate.
1424
1425   Brace expansion is performed before any other expansions, and any
1426characters special to other expansions are preserved in the result.  It
1427is strictly textual.  Bash does not apply any syntactic interpretation
1428to the context of the expansion or the text between the braces.  To
1429avoid conflicts with parameter expansion, the string '${' is not
1430considered eligible for brace expansion.
1431
1432   A correctly-formed brace expansion must contain unquoted opening and
1433closing braces, and at least one unquoted comma or a valid sequence
1434expression.  Any incorrectly formed brace expansion is left unchanged.
1435
1436   A { or ',' may be quoted with a backslash to prevent its being
1437considered part of a brace expression.  To avoid conflicts with
1438parameter expansion, the string '${' is not considered eligible for
1439brace expansion.
1440
1441   This construct is typically used as shorthand when the common prefix
1442of the strings to be generated is longer than in the above example:
1443     mkdir /usr/local/src/bash/{old,new,dist,bugs}
1444   or
1445     chown root /usr/{ucb/{ex,edit},lib/{ex?.?*,how_ex}}
1446
14473.5.2 Tilde Expansion
1448---------------------
1449
1450If a word begins with an unquoted tilde character ('~'), all of the
1451characters up to the first unquoted slash (or all characters, if there
1452is no unquoted slash) are considered a TILDE-PREFIX.  If none of the
1453characters in the tilde-prefix are quoted, the characters in the
1454tilde-prefix following the tilde are treated as a possible LOGIN NAME.
1455If this login name is the null string, the tilde is replaced with the
1456value of the 'HOME' shell variable.  If 'HOME' is unset, the home
1457directory of the user executing the shell is substituted instead.
1458Otherwise, the tilde-prefix is replaced with the home directory
1459associated with the specified login name.
1460
1461   If the tilde-prefix is '~+', the value of the shell variable 'PWD'
1462replaces the tilde-prefix.  If the tilde-prefix is '~-', the value of
1463the shell variable 'OLDPWD', if it is set, is substituted.
1464
1465   If the characters following the tilde in the tilde-prefix consist of
1466a number N, optionally prefixed by a '+' or a '-', the tilde-prefix is
1467replaced with the corresponding element from the directory stack, as it
1468would be displayed by the 'dirs' builtin invoked with the characters
1469following tilde in the tilde-prefix as an argument (*note The Directory
1470Stack::).  If the tilde-prefix, sans the tilde, consists of a number
1471without a leading '+' or '-', '+' is assumed.
1472
1473   If the login name is invalid, or the tilde expansion fails, the word
1474is left unchanged.
1475
1476   Each variable assignment is checked for unquoted tilde-prefixes
1477immediately following a ':' or the first '='.  In these cases, tilde
1478expansion is also performed.  Consequently, one may use filenames with
1479tildes in assignments to 'PATH', 'MAILPATH', and 'CDPATH', and the shell
1480assigns the expanded value.
1481
1482   The following table shows how Bash treats unquoted tilde-prefixes:
1483
1484'~'
1485     The value of '$HOME'
1486'~/foo'
1487     '$HOME/foo'
1488
1489'~fred/foo'
1490     The subdirectory 'foo' of the home directory of the user 'fred'
1491
1492'~+/foo'
1493     '$PWD/foo'
1494
1495'~-/foo'
1496     '${OLDPWD-'~-'}/foo'
1497
1498'~N'
1499     The string that would be displayed by 'dirs +N'
1500
1501'~+N'
1502     The string that would be displayed by 'dirs +N'
1503
1504'~-N'
1505     The string that would be displayed by 'dirs -N'
1506
15073.5.3 Shell Parameter Expansion
1508-------------------------------
1509
1510The '$' character introduces parameter expansion, command substitution,
1511or arithmetic expansion.  The parameter name or symbol to be expanded
1512may be enclosed in braces, which are optional but serve to protect the
1513variable to be expanded from characters immediately following it which
1514could be interpreted as part of the name.
1515
1516   When braces are used, the matching ending brace is the first '}' not
1517escaped by a backslash or within a quoted string, and not within an
1518embedded arithmetic expansion, command substitution, or parameter
1519expansion.
1520
1521   The basic form of parameter expansion is ${PARAMETER}.  The value of
1522PARAMETER is substituted.  The PARAMETER is a shell parameter as
1523described above (*note Shell Parameters::) or an array reference (*note
1524Arrays::).  The braces are required when PARAMETER is a positional
1525parameter with more than one digit, or when PARAMETER is followed by a
1526character that is not to be interpreted as part of its name.
1527
1528   If the first character of PARAMETER is an exclamation point (!), and
1529PARAMETER is not a NAMEREF, it introduces a level of variable
1530indirection.  Bash uses the value of the variable formed from the rest
1531of PARAMETER as the name of the variable; this variable is then expanded
1532and that value is used in the rest of the substitution, rather than the
1533value of PARAMETER itself.  This is known as 'indirect expansion'.  If
1534PARAMETER is a nameref, this expands to the name of the variable
1535referenced by PARAMETER instead of performing the complete indirect
1536expansion.  The exceptions to this are the expansions of ${!PREFIX*} and
1537${!NAME[@]} described below.  The exclamation point must immediately
1538follow the left brace in order to introduce indirection.
1539
1540   In each of the cases below, WORD is subject to tilde expansion,
1541parameter expansion, command substitution, and arithmetic expansion.
1542
1543   When not performing substring expansion, using the form described
1544below (e.g., ':-'), Bash tests for a parameter that is unset or null.
1545Omitting the colon results in a test only for a parameter that is unset.
1546Put another way, if the colon is included, the operator tests for both
1547PARAMETER's existence and that its value is not null; if the colon is
1548omitted, the operator tests only for existence.
1549
1550'${PARAMETER:-WORD}'
1551     If PARAMETER is unset or null, the expansion of WORD is
1552     substituted.  Otherwise, the value of PARAMETER is substituted.
1553
1554'${PARAMETER:=WORD}'
1555     If PARAMETER is unset or null, the expansion of WORD is assigned to
1556     PARAMETER.  The value of PARAMETER is then substituted.  Positional
1557     parameters and special parameters may not be assigned to in this
1558     way.
1559
1560'${PARAMETER:?WORD}'
1561     If PARAMETER is null or unset, the expansion of WORD (or a message
1562     to that effect if WORD is not present) is written to the standard
1563     error and the shell, if it is not interactive, exits.  Otherwise,
1564     the value of PARAMETER is substituted.
1565
1566'${PARAMETER:+WORD}'
1567     If PARAMETER is null or unset, nothing is substituted, otherwise
1568     the expansion of WORD is substituted.
1569
1570'${PARAMETER:OFFSET}'
1571'${PARAMETER:OFFSET:LENGTH}'
1572     This is referred to as Substring Expansion.  It expands to up to
1573     LENGTH characters of the value of PARAMETER starting at the
1574     character specified by OFFSET.  If PARAMETER is '@', an indexed
1575     array subscripted by '@' or '*', or an associative array name, the
1576     results differ as described below.  If LENGTH is omitted, it
1577     expands to the substring of the value of PARAMETER starting at the
1578     character specified by OFFSET and extending to the end of the
1579     value.  LENGTH and OFFSET are arithmetic expressions (*note Shell
1580     Arithmetic::).
1581
1582     If OFFSET evaluates to a number less than zero, the value is used
1583     as an offset in characters from the end of the value of PARAMETER.
1584     If LENGTH evaluates to a number less than zero, it is interpreted
1585     as an offset in characters from the end of the value of PARAMETER
1586     rather than a number of characters, and the expansion is the
1587     characters between OFFSET and that result.  Note that a negative
1588     offset must be separated from the colon by at least one space to
1589     avoid being confused with the ':-' expansion.
1590
1591     Here are some examples illustrating substring expansion on
1592     parameters and subscripted arrays:
1593
1594     $ string=01234567890abcdefgh
1595     $ echo ${string:7}
1596     7890abcdefgh
1597     $ echo ${string:7:0}
1598
1599     $ echo ${string:7:2}
1600     78
1601     $ echo ${string:7:-2}
1602     7890abcdef
1603     $ echo ${string: -7}
1604     bcdefgh
1605     $ echo ${string: -7:0}
1606
1607     $ echo ${string: -7:2}
1608     bc
1609     $ echo ${string: -7:-2}
1610     bcdef
1611     $ set -- 01234567890abcdefgh
1612     $ echo ${1:7}
1613     7890abcdefgh
1614     $ echo ${1:7:0}
1615
1616     $ echo ${1:7:2}
1617     78
1618     $ echo ${1:7:-2}
1619     7890abcdef
1620     $ echo ${1: -7}
1621     bcdefgh
1622     $ echo ${1: -7:0}
1623
1624     $ echo ${1: -7:2}
1625     bc
1626     $ echo ${1: -7:-2}
1627     bcdef
1628     $ array[0]=01234567890abcdefgh
1629     $ echo ${array[0]:7}
1630     7890abcdefgh
1631     $ echo ${array[0]:7:0}
1632
1633     $ echo ${array[0]:7:2}
1634     78
1635     $ echo ${array[0]:7:-2}
1636     7890abcdef
1637     $ echo ${array[0]: -7}
1638     bcdefgh
1639     $ echo ${array[0]: -7:0}
1640
1641     $ echo ${array[0]: -7:2}
1642     bc
1643     $ echo ${array[0]: -7:-2}
1644     bcdef
1645
1646     If PARAMETER is '@', the result is LENGTH positional parameters
1647     beginning at OFFSET.  A negative OFFSET is taken relative to one
1648     greater than the greatest positional parameter, so an offset of -1
1649     evaluates to the last positional parameter.  It is an expansion
1650     error if LENGTH evaluates to a number less than zero.
1651
1652     The following examples illustrate substring expansion using
1653     positional parameters:
1654
1655     $ set -- 1 2 3 4 5 6 7 8 9 0 a b c d e f g h
1656     $ echo ${@:7}
1657     7 8 9 0 a b c d e f g h
1658     $ echo ${@:7:0}
1659
1660     $ echo ${@:7:2}
1661     7 8
1662     $ echo ${@:7:-2}
1663     bash: -2: substring expression < 0
1664     $ echo ${@: -7:2}
1665     b c
1666     $ echo ${@:0}
1667     ./bash 1 2 3 4 5 6 7 8 9 0 a b c d e f g h
1668     $ echo ${@:0:2}
1669     ./bash 1
1670     $ echo ${@: -7:0}
1671
1672
1673     If PARAMETER is an indexed array name subscripted by '@' or '*',
1674     the result is the LENGTH members of the array beginning with
1675     '${PARAMETER[OFFSET]}'.  A negative OFFSET is taken relative to one
1676     greater than the maximum index of the specified array.  It is an
1677     expansion error if LENGTH evaluates to a number less than zero.
1678
1679     These examples show how you can use substring expansion with
1680     indexed arrays:
1681
1682     $ array=(0 1 2 3 4 5 6 7 8 9 0 a b c d e f g h)
1683     $ echo ${array[@]:7}
1684     7 8 9 0 a b c d e f g h
1685     $ echo ${array[@]:7:2}
1686     7 8
1687     $ echo ${array[@]: -7:2}
1688     b c
1689     $ echo ${array[@]: -7:-2}
1690     bash: -2: substring expression < 0
1691     $ echo ${array[@]:0}
1692     0 1 2 3 4 5 6 7 8 9 0 a b c d e f g h
1693     $ echo ${array[@]:0:2}
1694     0 1
1695     $ echo ${array[@]: -7:0}
1696
1697
1698     Substring expansion applied to an associative array produces
1699     undefined results.
1700
1701     Substring indexing is zero-based unless the positional parameters
1702     are used, in which case the indexing starts at 1 by default.  If
1703     OFFSET is 0, and the positional parameters are used, '$@' is
1704     prefixed to the list.
1705
1706'${!PREFIX*}'
1707'${!PREFIX@}'
1708     Expands to the names of variables whose names begin with PREFIX,
1709     separated by the first character of the 'IFS' special variable.
1710     When '@' is used and the expansion appears within double quotes,
1711     each variable name expands to a separate word.
1712
1713'${!NAME[@]}'
1714'${!NAME[*]}'
1715     If NAME is an array variable, expands to the list of array indices
1716     (keys) assigned in NAME.  If NAME is not an array, expands to 0 if
1717     NAME is set and null otherwise.  When '@' is used and the expansion
1718     appears within double quotes, each key expands to a separate word.
1719
1720'${#PARAMETER}'
1721     The length in characters of the expanded value of PARAMETER is
1722     substituted.  If PARAMETER is '*' or '@', the value substituted is
1723     the number of positional parameters.  If PARAMETER is an array name
1724     subscripted by '*' or '@', the value substituted is the number of
1725     elements in the array.  If PARAMETER is an indexed array name
1726     subscripted by a negative number, that number is interpreted as
1727     relative to one greater than the maximum index of PARAMETER, so
1728     negative indices count back from the end of the array, and an index
1729     of -1 references the last element.
1730
1731'${PARAMETER#WORD}'
1732'${PARAMETER##WORD}'
1733     The WORD is expanded to produce a pattern just as in filename
1734     expansion (*note Filename Expansion::).  If the pattern matches the
1735     beginning of the expanded value of PARAMETER, then the result of
1736     the expansion is the expanded value of PARAMETER with the shortest
1737     matching pattern (the '#' case) or the longest matching pattern
1738     (the '##' case) deleted.  If PARAMETER is '@' or '*', the pattern
1739     removal operation is applied to each positional parameter in turn,
1740     and the expansion is the resultant list.  If PARAMETER is an array
1741     variable subscripted with '@' or '*', the pattern removal operation
1742     is applied to each member of the array in turn, and the expansion
1743     is the resultant list.
1744
1745'${PARAMETER%WORD}'
1746'${PARAMETER%%WORD}'
1747     The WORD is expanded to produce a pattern just as in filename
1748     expansion.  If the pattern matches a trailing portion of the
1749     expanded value of PARAMETER, then the result of the expansion is
1750     the value of PARAMETER with the shortest matching pattern (the '%'
1751     case) or the longest matching pattern (the '%%' case) deleted.  If
1752     PARAMETER is '@' or '*', the pattern removal operation is applied
1753     to each positional parameter in turn, and the expansion is the
1754     resultant list.  If PARAMETER is an array variable subscripted with
1755     '@' or '*', the pattern removal operation is applied to each member
1756     of the array in turn, and the expansion is the resultant list.
1757
1758'${PARAMETER/PATTERN/STRING}'
1759
1760     The PATTERN is expanded to produce a pattern just as in filename
1761     expansion.  PARAMETER is expanded and the longest match of PATTERN
1762     against its value is replaced with STRING.  If PATTERN begins with
1763     '/', all matches of PATTERN are replaced with STRING.  Normally
1764     only the first match is replaced.  If PATTERN begins with '#', it
1765     must match at the beginning of the expanded value of PARAMETER.  If
1766     PATTERN begins with '%', it must match at the end of the expanded
1767     value of PARAMETER.  If STRING is null, matches of PATTERN are
1768     deleted and the '/' following PATTERN may be omitted.  If the
1769     'nocasematch' shell option (see the description of 'shopt' in *note
1770     The Shopt Builtin::) is enabled, the match is performed without
1771     regard to the case of alphabetic characters.  If PARAMETER is '@'
1772     or '*', the substitution operation is applied to each positional
1773     parameter in turn, and the expansion is the resultant list.  If
1774     PARAMETER is an array variable subscripted with '@' or '*', the
1775     substitution operation is applied to each member of the array in
1776     turn, and the expansion is the resultant list.
1777
1778'${PARAMETER^PATTERN}'
1779'${PARAMETER^^PATTERN}'
1780'${PARAMETER,PATTERN}'
1781'${PARAMETER,,PATTERN}'
1782     This expansion modifies the case of alphabetic characters in
1783     PARAMETER.  The PATTERN is expanded to produce a pattern just as in
1784     filename expansion.  Each character in the expanded value of
1785     PARAMETER is tested against PATTERN, and, if it matches the
1786     pattern, its case is converted.  The pattern should not attempt to
1787     match more than one character.  The '^' operator converts lowercase
1788     letters matching PATTERN to uppercase; the ',' operator converts
1789     matching uppercase letters to lowercase.  The '^^' and ',,'
1790     expansions convert each matched character in the expanded value;
1791     the '^' and ',' expansions match and convert only the first
1792     character in the expanded value.  If PATTERN is omitted, it is
1793     treated like a '?', which matches every character.  If PARAMETER is
1794     '@' or '*', the case modification operation is applied to each
1795     positional parameter in turn, and the expansion is the resultant
1796     list.  If PARAMETER is an array variable subscripted with '@' or
1797     '*', the case modification operation is applied to each member of
1798     the array in turn, and the expansion is the resultant list.
1799
1800'${PARAMETER@OPERATOR}'
1801     The expansion is either a transformation of the value of PARAMETER
1802     or information about PARAMETER itself, depending on the value of
1803     OPERATOR.  Each OPERATOR is a single letter:
1804
1805     'Q'
1806          The expansion is a string that is the value of PARAMETER
1807          quoted in a format that can be reused as input.
1808     'E'
1809          The expansion is a string that is the value of PARAMETER with
1810          backslash escape sequences expanded as with the '$'...''
1811          quoting mechansim.
1812     'P'
1813          The expansion is a string that is the result of expanding the
1814          value of PARAMETER as if it were a prompt string (*note
1815          Controlling the Prompt::).
1816     'A'
1817          The expansion is a string in the form of an assignment
1818          statement or 'declare' command that, if evaluated, will
1819          recreate PARAMETER with its attributes and value.
1820     'a'
1821          The expansion is a string consisting of flag values
1822          representing PARAMETER's attributes.
1823
1824     If PARAMETER is '@' or '*', the operation is applied to each
1825     positional parameter in turn, and the expansion is the resultant
1826     list.  If PARAMETER is an array variable subscripted with '@' or
1827     '*', the operation is applied to each member of the array in turn,
1828     and the expansion is the resultant list.
1829
1830     The result of the expansion is subject to word splitting and
1831     pathname expansion as described below.
1832
18333.5.4 Command Substitution
1834--------------------------
1835
1836Command substitution allows the output of a command to replace the
1837command itself.  Command substitution occurs when a command is enclosed
1838as follows:
1839     $(COMMAND)
1840or
1841     `COMMAND`
1842
1843Bash performs the expansion by executing COMMAND in a subshell
1844environment and replacing the command substitution with the standard
1845output of the command, with any trailing newlines deleted.  Embedded
1846newlines are not deleted, but they may be removed during word splitting.
1847The command substitution '$(cat FILE)' can be replaced by the equivalent
1848but faster '$(< FILE)'.
1849
1850   When the old-style backquote form of substitution is used, backslash
1851retains its literal meaning except when followed by '$', '`', or '\'.
1852The first backquote not preceded by a backslash terminates the command
1853substitution.  When using the '$(COMMAND)' form, all characters between
1854the parentheses make up the command; none are treated specially.
1855
1856   Command substitutions may be nested.  To nest when using the
1857backquoted form, escape the inner backquotes with backslashes.
1858
1859   If the substitution appears within double quotes, word splitting and
1860filename expansion are not performed on the results.
1861
18623.5.5 Arithmetic Expansion
1863--------------------------
1864
1865Arithmetic expansion allows the evaluation of an arithmetic expression
1866and the substitution of the result.  The format for arithmetic expansion
1867is:
1868
1869     $(( EXPRESSION ))
1870
1871   The expression is treated as if it were within double quotes, but a
1872double quote inside the parentheses is not treated specially.  All
1873tokens in the expression undergo parameter and variable expansion,
1874command substitution, and quote removal.  The result is treated as the
1875arithmetic expression to be evaluated.  Arithmetic expansions may be
1876nested.
1877
1878   The evaluation is performed according to the rules listed below
1879(*note Shell Arithmetic::).  If the expression is invalid, Bash prints a
1880message indicating failure to the standard error and no substitution
1881occurs.
1882
18833.5.6 Process Substitution
1884--------------------------
1885
1886Process substitution allows a process's input or output to be referred
1887to using a filename.  It takes the form of
1888     <(LIST)
1889or
1890     >(LIST)
1891The process LIST is run asynchronously, and its input or output appears
1892as a filename.  This filename is passed as an argument to the current
1893command as the result of the expansion.  If the '>(LIST)' form is used,
1894writing to the file will provide input for LIST.  If the '<(LIST)' form
1895is used, the file passed as an argument should be read to obtain the
1896output of LIST.  Note that no space may appear between the '<' or '>'
1897and the left parenthesis, otherwise the construct would be interpreted
1898as a redirection.  Process substitution is supported on systems that
1899support named pipes (FIFOs) or the '/dev/fd' method of naming open
1900files.
1901
1902   When available, process substitution is performed simultaneously with
1903parameter and variable expansion, command substitution, and arithmetic
1904expansion.
1905
19063.5.7 Word Splitting
1907--------------------
1908
1909The shell scans the results of parameter expansion, command
1910substitution, and arithmetic expansion that did not occur within double
1911quotes for word splitting.
1912
1913   The shell treats each character of '$IFS' as a delimiter, and splits
1914the results of the other expansions into words using these characters as
1915field terminators.  If 'IFS' is unset, or its value is exactly
1916'<space><tab><newline>', the default, then sequences of ' <space>',
1917'<tab>', and '<newline>' at the beginning and end of the results of the
1918previous expansions are ignored, and any sequence of 'IFS' characters
1919not at the beginning or end serves to delimit words.  If 'IFS' has a
1920value other than the default, then sequences of the whitespace
1921characters 'space', 'tab', and 'newline' are ignored at the beginning
1922and end of the word, as long as the whitespace character is in the value
1923of 'IFS' (an 'IFS' whitespace character).  Any character in 'IFS' that
1924is not 'IFS' whitespace, along with any adjacent 'IFS' whitespace
1925characters, delimits a field.  A sequence of 'IFS' whitespace characters
1926is also treated as a delimiter.  If the value of 'IFS' is null, no word
1927splitting occurs.
1928
1929   Explicit null arguments ('""' or '''') are retained and passed to
1930commands as empty strings.  Unquoted implicit null arguments, resulting
1931from the expansion of parameters that have no values, are removed.  If a
1932parameter with no value is expanded within double quotes, a null
1933argument results and is retained and passed to a command as an empty
1934string.  When a quoted null argument appears as part of a word whose
1935expansion is non-null, the null argument is removed.  That is, the word
1936'-d''' becomes '-d' after word splitting and null argument removal.
1937
1938   Note that if no expansion occurs, no splitting is performed.
1939
19403.5.8 Filename Expansion
1941------------------------
1942
1943After word splitting, unless the '-f' option has been set (*note The Set
1944Builtin::), Bash scans each word for the characters '*', '?', and '['.
1945If one of these characters appears, then the word is regarded as a
1946PATTERN, and replaced with an alphabetically sorted list of filenames
1947matching the pattern (*note Pattern Matching::).  If no matching
1948filenames are found, and the shell option 'nullglob' is disabled, the
1949word is left unchanged.  If the 'nullglob' option is set, and no matches
1950are found, the word is removed.  If the 'failglob' shell option is set,
1951and no matches are found, an error message is printed and the command is
1952not executed.  If the shell option 'nocaseglob' is enabled, the match is
1953performed without regard to the case of alphabetic characters.
1954
1955   When a pattern is used for filename expansion, the character '.' at
1956the start of a filename or immediately following a slash must be matched
1957explicitly, unless the shell option 'dotglob' is set.  When matching a
1958filename, the slash character must always be matched explicitly.  In
1959other cases, the '.' character is not treated specially.
1960
1961   See the description of 'shopt' in *note The Shopt Builtin::, for a
1962description of the 'nocaseglob', 'nullglob', 'failglob', and 'dotglob'
1963options.
1964
1965   The 'GLOBIGNORE' shell variable may be used to restrict the set of
1966filenames matching a pattern.  If 'GLOBIGNORE' is set, each matching
1967filename that also matches one of the patterns in 'GLOBIGNORE' is
1968removed from the list of matches.  If the 'nocaseglob' option is set,
1969the matching against the patterns in 'GLOBIGNORE' is performed without
1970regard to case.  The filenames '.' and '..' are always ignored when
1971'GLOBIGNORE' is set and not null.  However, setting 'GLOBIGNORE' to a
1972non-null value has the effect of enabling the 'dotglob' shell option, so
1973all other filenames beginning with a '.' will match.  To get the old
1974behavior of ignoring filenames beginning with a '.', make '.*' one of
1975the patterns in 'GLOBIGNORE'.  The 'dotglob' option is disabled when
1976'GLOBIGNORE' is unset.
1977
19783.5.8.1 Pattern Matching
1979........................
1980
1981Any character that appears in a pattern, other than the special pattern
1982characters described below, matches itself.  The NUL character may not
1983occur in a pattern.  A backslash escapes the following character; the
1984escaping backslash is discarded when matching.  The special pattern
1985characters must be quoted if they are to be matched literally.
1986
1987   The special pattern characters have the following meanings:
1988'*'
1989     Matches any string, including the null string.  When the 'globstar'
1990     shell option is enabled, and '*' is used in a filename expansion
1991     context, two adjacent '*'s used as a single pattern will match all
1992     files and zero or more directories and subdirectories.  If followed
1993     by a '/', two adjacent '*'s will match only directories and
1994     subdirectories.
1995'?'
1996     Matches any single character.
1997'[...]'
1998     Matches any one of the enclosed characters.  A pair of characters
1999     separated by a hyphen denotes a RANGE EXPRESSION; any character
2000     that falls between those two characters, inclusive, using the
2001     current locale's collating sequence and character set, is matched.
2002     If the first character following the '[' is a '!' or a '^' then any
2003     character not enclosed is matched.  A '-' may be matched by
2004     including it as the first or last character in the set.  A ']' may
2005     be matched by including it as the first character in the set.  The
2006     sorting order of characters in range expressions is determined by
2007     the current locale and the values of the 'LC_COLLATE' and 'LC_ALL'
2008     shell variables, if set.
2009
2010     For example, in the default C locale, '[a-dx-z]' is equivalent to
2011     '[abcdxyz]'.  Many locales sort characters in dictionary order, and
2012     in these locales '[a-dx-z]' is typically not equivalent to
2013     '[abcdxyz]'; it might be equivalent to '[aBbCcDdxXyYz]', for
2014     example.  To obtain the traditional interpretation of ranges in
2015     bracket expressions, you can force the use of the C locale by
2016     setting the 'LC_COLLATE' or 'LC_ALL' environment variable to the
2017     value 'C', or enable the 'globasciiranges' shell option.
2018
2019     Within '[' and ']', CHARACTER CLASSES can be specified using the
2020     syntax '[:'CLASS':]', where CLASS is one of the following classes
2021     defined in the POSIX standard:
2022          alnum   alpha   ascii   blank   cntrl   digit   graph   lower
2023          print   punct   space   upper   word    xdigit
2024     A character class matches any character belonging to that class.
2025     The 'word' character class matches letters, digits, and the
2026     character '_'.
2027
2028     Within '[' and ']', an EQUIVALENCE CLASS can be specified using the
2029     syntax '[='C'=]', which matches all characters with the same
2030     collation weight (as defined by the current locale) as the
2031     character C.
2032
2033     Within '[' and ']', the syntax '[.'SYMBOL'.]' matches the collating
2034     symbol SYMBOL.
2035
2036   If the 'extglob' shell option is enabled using the 'shopt' builtin,
2037several extended pattern matching operators are recognized.  In the
2038following description, a PATTERN-LIST is a list of one or more patterns
2039separated by a '|'.  Composite patterns may be formed using one or more
2040of the following sub-patterns:
2041
2042'?(PATTERN-LIST)'
2043     Matches zero or one occurrence of the given patterns.
2044
2045'*(PATTERN-LIST)'
2046     Matches zero or more occurrences of the given patterns.
2047
2048'+(PATTERN-LIST)'
2049     Matches one or more occurrences of the given patterns.
2050
2051'@(PATTERN-LIST)'
2052     Matches one of the given patterns.
2053
2054'!(PATTERN-LIST)'
2055     Matches anything except one of the given patterns.
2056
20573.5.9 Quote Removal
2058-------------------
2059
2060After the preceding expansions, all unquoted occurrences of the
2061characters '\', ''', and '"' that did not result from one of the above
2062expansions are removed.
2063
20643.6 Redirections
2065================
2066
2067Before a command is executed, its input and output may be REDIRECTED
2068using a special notation interpreted by the shell.  Redirection allows
2069commands' file handles to be duplicated, opened, closed, made to refer
2070to different files, and can change the files the command reads from and
2071writes to.  Redirection may also be used to modify file handles in the
2072current shell execution environment.  The following redirection
2073operators may precede or appear anywhere within a simple command or may
2074follow a command.  Redirections are processed in the order they appear,
2075from left to right.
2076
2077   Each redirection that may be preceded by a file descriptor number may
2078instead be preceded by a word of the form {VARNAME}.  In this case, for
2079each redirection operator except >&- and <&-, the shell will allocate a
2080file descriptor greater than 10 and assign it to {VARNAME}.  If >&- or
2081<&- is preceded by {VARNAME}, the value of VARNAME defines the file
2082descriptor to close.
2083
2084   In the following descriptions, if the file descriptor number is
2085omitted, and the first character of the redirection operator is '<', the
2086redirection refers to the standard input (file descriptor 0).  If the
2087first character of the redirection operator is '>', the redirection
2088refers to the standard output (file descriptor 1).
2089
2090   The word following the redirection operator in the following
2091descriptions, unless otherwise noted, is subjected to brace expansion,
2092tilde expansion, parameter expansion, command substitution, arithmetic
2093expansion, quote removal, filename expansion, and word splitting.  If it
2094expands to more than one word, Bash reports an error.
2095
2096   Note that the order of redirections is significant.  For example, the
2097command
2098     ls > DIRLIST 2>&1
2099directs both standard output (file descriptor 1) and standard error
2100(file descriptor 2) to the file DIRLIST, while the command
2101     ls 2>&1 > DIRLIST
2102directs only the standard output to file DIRLIST, because the standard
2103error was made a copy of the standard output before the standard output
2104was redirected to DIRLIST.
2105
2106   Bash handles several filenames specially when they are used in
2107redirections, as described in the following table.  If the operating
2108system on which Bash is running provides these special files, bash will
2109use them; otherwise it will emulate them internally with the behavior
2110described below.
2111
2112'/dev/fd/FD'
2113     If FD is a valid integer, file descriptor FD is duplicated.
2114
2115'/dev/stdin'
2116     File descriptor 0 is duplicated.
2117
2118'/dev/stdout'
2119     File descriptor 1 is duplicated.
2120
2121'/dev/stderr'
2122     File descriptor 2 is duplicated.
2123
2124'/dev/tcp/HOST/PORT'
2125     If HOST is a valid hostname or Internet address, and PORT is an
2126     integer port number or service name, Bash attempts to open the
2127     corresponding TCP socket.
2128
2129'/dev/udp/HOST/PORT'
2130     If HOST is a valid hostname or Internet address, and PORT is an
2131     integer port number or service name, Bash attempts to open the
2132     corresponding UDP socket.
2133
2134   A failure to open or create a file causes the redirection to fail.
2135
2136   Redirections using file descriptors greater than 9 should be used
2137with care, as they may conflict with file descriptors the shell uses
2138internally.
2139
21403.6.1 Redirecting Input
2141-----------------------
2142
2143Redirection of input causes the file whose name results from the
2144expansion of WORD to be opened for reading on file descriptor 'n', or
2145the standard input (file descriptor 0) if 'n' is not specified.
2146
2147   The general format for redirecting input is:
2148     [N]<WORD
2149
21503.6.2 Redirecting Output
2151------------------------
2152
2153Redirection of output causes the file whose name results from the
2154expansion of WORD to be opened for writing on file descriptor N, or the
2155standard output (file descriptor 1) if N is not specified.  If the file
2156does not exist it is created; if it does exist it is truncated to zero
2157size.
2158
2159   The general format for redirecting output is:
2160     [N]>[|]WORD
2161
2162   If the redirection operator is '>', and the 'noclobber' option to the
2163'set' builtin has been enabled, the redirection will fail if the file
2164whose name results from the expansion of WORD exists and is a regular
2165file.  If the redirection operator is '>|', or the redirection operator
2166is '>' and the 'noclobber' option is not enabled, the redirection is
2167attempted even if the file named by WORD exists.
2168
21693.6.3 Appending Redirected Output
2170---------------------------------
2171
2172Redirection of output in this fashion causes the file whose name results
2173from the expansion of WORD to be opened for appending on file descriptor
2174N, or the standard output (file descriptor 1) if N is not specified.  If
2175the file does not exist it is created.
2176
2177   The general format for appending output is:
2178     [N]>>WORD
2179
21803.6.4 Redirecting Standard Output and Standard Error
2181----------------------------------------------------
2182
2183This construct allows both the standard output (file descriptor 1) and
2184the standard error output (file descriptor 2) to be redirected to the
2185file whose name is the expansion of WORD.
2186
2187   There are two formats for redirecting standard output and standard
2188error:
2189     &>WORD
2190and
2191     >&WORD
2192Of the two forms, the first is preferred.  This is semantically
2193equivalent to
2194     >WORD 2>&1
2195   When using the second form, WORD may not expand to a number or '-'.
2196If it does, other redirection operators apply (see Duplicating File
2197Descriptors below) for compatibility reasons.
2198
21993.6.5 Appending Standard Output and Standard Error
2200--------------------------------------------------
2201
2202This construct allows both the standard output (file descriptor 1) and
2203the standard error output (file descriptor 2) to be appended to the file
2204whose name is the expansion of WORD.
2205
2206   The format for appending standard output and standard error is:
2207     &>>WORD
2208This is semantically equivalent to
2209     >>WORD 2>&1
2210   (see Duplicating File Descriptors below).
2211
22123.6.6 Here Documents
2213--------------------
2214
2215This type of redirection instructs the shell to read input from the
2216current source until a line containing only WORD (with no trailing
2217blanks) is seen.  All of the lines read up to that point are then used
2218as the standard input (or file descriptor N if N is specified) for a
2219command.
2220
2221   The format of here-documents is:
2222     [N]<<[-]WORD
2223             HERE-DOCUMENT
2224     DELIMITER
2225
2226   No parameter and variable expansion, command substitution, arithmetic
2227expansion, or filename expansion is performed on WORD.  If any part of
2228WORD is quoted, the DELIMITER is the result of quote removal on WORD,
2229and the lines in the here-document are not expanded.  If WORD is
2230unquoted, all lines of the here-document are subjected to parameter
2231expansion, command substitution, and arithmetic expansion, the character
2232sequence '\newline' is ignored, and '\' must be used to quote the
2233characters '\', '$', and '`'.
2234
2235   If the redirection operator is '<<-', then all leading tab characters
2236are stripped from input lines and the line containing DELIMITER.  This
2237allows here-documents within shell scripts to be indented in a natural
2238fashion.
2239
22403.6.7 Here Strings
2241------------------
2242
2243A variant of here documents, the format is:
2244     [N]<<< WORD
2245
2246   The WORD undergoes brace expansion, tilde expansion, parameter and
2247variable expansion, command substitution, arithmetic expansion, and
2248quote removal.  Pathname expansion and word splitting are not performed.
2249The result is supplied as a single string, with a newline appended, to
2250the command on its standard input (or file descriptor N if N is
2251specified).
2252
22533.6.8 Duplicating File Descriptors
2254----------------------------------
2255
2256The redirection operator
2257     [N]<&WORD
2258is used to duplicate input file descriptors.  If WORD expands to one or
2259more digits, the file descriptor denoted by N is made to be a copy of
2260that file descriptor.  If the digits in WORD do not specify a file
2261descriptor open for input, a redirection error occurs.  If WORD
2262evaluates to '-', file descriptor N is closed.  If N is not specified,
2263the standard input (file descriptor 0) is used.
2264
2265   The operator
2266     [N]>&WORD
2267is used similarly to duplicate output file descriptors.  If N is not
2268specified, the standard output (file descriptor 1) is used.  If the
2269digits in WORD do not specify a file descriptor open for output, a
2270redirection error occurs.  If WORD evaluates to '-', file descriptor N
2271is closed.  As a special case, if N is omitted, and WORD does not expand
2272to one or more digits or '-', the standard output and standard error are
2273redirected as described previously.
2274
22753.6.9 Moving File Descriptors
2276-----------------------------
2277
2278The redirection operator
2279     [N]<&DIGIT-
2280moves the file descriptor DIGIT to file descriptor N, or the standard
2281input (file descriptor 0) if N is not specified.  DIGIT is closed after
2282being duplicated to N.
2283
2284   Similarly, the redirection operator
2285     [N]>&DIGIT-
2286moves the file descriptor DIGIT to file descriptor N, or the standard
2287output (file descriptor 1) if N is not specified.
2288
22893.6.10 Opening File Descriptors for Reading and Writing
2290-------------------------------------------------------
2291
2292The redirection operator
2293     [N]<>WORD
2294causes the file whose name is the expansion of WORD to be opened for
2295both reading and writing on file descriptor N, or on file descriptor 0
2296if N is not specified.  If the file does not exist, it is created.
2297
22983.7 Executing Commands
2299======================
2300
23013.7.1 Simple Command Expansion
2302------------------------------
2303
2304When a simple command is executed, the shell performs the following
2305expansions, assignments, and redirections, from left to right.
2306
2307  1. The words that the parser has marked as variable assignments (those
2308     preceding the command name) and redirections are saved for later
2309     processing.
2310
2311  2. The words that are not variable assignments or redirections are
2312     expanded (*note Shell Expansions::).  If any words remain after
2313     expansion, the first word is taken to be the name of the command
2314     and the remaining words are the arguments.
2315
2316  3. Redirections are performed as described above (*note
2317     Redirections::).
2318
2319  4. The text after the '=' in each variable assignment undergoes tilde
2320     expansion, parameter expansion, command substitution, arithmetic
2321     expansion, and quote removal before being assigned to the variable.
2322
2323   If no command name results, the variable assignments affect the
2324current shell environment.  Otherwise, the variables are added to the
2325environment of the executed command and do not affect the current shell
2326environment.  If any of the assignments attempts to assign a value to a
2327readonly variable, an error occurs, and the command exits with a
2328non-zero status.
2329
2330   If no command name results, redirections are performed, but do not
2331affect the current shell environment.  A redirection error causes the
2332command to exit with a non-zero status.
2333
2334   If there is a command name left after expansion, execution proceeds
2335as described below.  Otherwise, the command exits.  If one of the
2336expansions contained a command substitution, the exit status of the
2337command is the exit status of the last command substitution performed.
2338If there were no command substitutions, the command exits with a status
2339of zero.
2340
23413.7.2 Command Search and Execution
2342----------------------------------
2343
2344After a command has been split into words, if it results in a simple
2345command and an optional list of arguments, the following actions are
2346taken.
2347
2348  1. If the command name contains no slashes, the shell attempts to
2349     locate it.  If there exists a shell function by that name, that
2350     function is invoked as described in *note Shell Functions::.
2351
2352  2. If the name does not match a function, the shell searches for it in
2353     the list of shell builtins.  If a match is found, that builtin is
2354     invoked.
2355
2356  3. If the name is neither a shell function nor a builtin, and contains
2357     no slashes, Bash searches each element of '$PATH' for a directory
2358     containing an executable file by that name.  Bash uses a hash table
2359     to remember the full pathnames of executable files to avoid
2360     multiple 'PATH' searches (see the description of 'hash' in *note
2361     Bourne Shell Builtins::).  A full search of the directories in
2362     '$PATH' is performed only if the command is not found in the hash
2363     table.  If the search is unsuccessful, the shell searches for a
2364     defined shell function named 'command_not_found_handle'.  If that
2365     function exists, it is invoked with the original command and the
2366     original command's arguments as its arguments, and the function's
2367     exit status becomes the exit status of the shell.  If that function
2368     is not defined, the shell prints an error message and returns an
2369     exit status of 127.
2370
2371  4. If the search is successful, or if the command name contains one or
2372     more slashes, the shell executes the named program in a separate
2373     execution environment.  Argument 0 is set to the name given, and
2374     the remaining arguments to the command are set to the arguments
2375     supplied, if any.
2376
2377  5. If this execution fails because the file is not in executable
2378     format, and the file is not a directory, it is assumed to be a
2379     SHELL SCRIPT and the shell executes it as described in *note Shell
2380     Scripts::.
2381
2382  6. If the command was not begun asynchronously, the shell waits for
2383     the command to complete and collects its exit status.
2384
23853.7.3 Command Execution Environment
2386-----------------------------------
2387
2388The shell has an EXECUTION ENVIRONMENT, which consists of the following:
2389
2390   * open files inherited by the shell at invocation, as modified by
2391     redirections supplied to the 'exec' builtin
2392
2393   * the current working directory as set by 'cd', 'pushd', or 'popd',
2394     or inherited by the shell at invocation
2395
2396   * the file creation mode mask as set by 'umask' or inherited from the
2397     shell's parent
2398
2399   * current traps set by 'trap'
2400
2401   * shell parameters that are set by variable assignment or with 'set'
2402     or inherited from the shell's parent in the environment
2403
2404   * shell functions defined during execution or inherited from the
2405     shell's parent in the environment
2406
2407   * options enabled at invocation (either by default or with
2408     command-line arguments) or by 'set'
2409
2410   * options enabled by 'shopt' (*note The Shopt Builtin::)
2411
2412   * shell aliases defined with 'alias' (*note Aliases::)
2413
2414   * various process IDs, including those of background jobs (*note
2415     Lists::), the value of '$$', and the value of '$PPID'
2416
2417   When a simple command other than a builtin or shell function is to be
2418executed, it is invoked in a separate execution environment that
2419consists of the following.  Unless otherwise noted, the values are
2420inherited from the shell.
2421
2422   * the shell's open files, plus any modifications and additions
2423     specified by redirections to the command
2424
2425   * the current working directory
2426
2427   * the file creation mode mask
2428
2429   * shell variables and functions marked for export, along with
2430     variables exported for the command, passed in the environment
2431     (*note Environment::)
2432
2433   * traps caught by the shell are reset to the values inherited from
2434     the shell's parent, and traps ignored by the shell are ignored
2435
2436   A command invoked in this separate environment cannot affect the
2437shell's execution environment.
2438
2439   Command substitution, commands grouped with parentheses, and
2440asynchronous commands are invoked in a subshell environment that is a
2441duplicate of the shell environment, except that traps caught by the
2442shell are reset to the values that the shell inherited from its parent
2443at invocation.  Builtin commands that are invoked as part of a pipeline
2444are also executed in a subshell environment.  Changes made to the
2445subshell environment cannot affect the shell's execution environment.
2446
2447   Subshells spawned to execute command substitutions inherit the value
2448of the '-e' option from the parent shell.  When not in POSIX mode, Bash
2449clears the '-e' option in such subshells.
2450
2451   If a command is followed by a '&' and job control is not active, the
2452default standard input for the command is the empty file '/dev/null'.
2453Otherwise, the invoked command inherits the file descriptors of the
2454calling shell as modified by redirections.
2455
24563.7.4 Environment
2457-----------------
2458
2459When a program is invoked it is given an array of strings called the
2460ENVIRONMENT.  This is a list of name-value pairs, of the form
2461'name=value'.
2462
2463   Bash provides several ways to manipulate the environment.  On
2464invocation, the shell scans its own environment and creates a parameter
2465for each name found, automatically marking it for EXPORT to child
2466processes.  Executed commands inherit the environment.  The 'export' and
2467'declare -x' commands allow parameters and functions to be added to and
2468deleted from the environment.  If the value of a parameter in the
2469environment is modified, the new value becomes part of the environment,
2470replacing the old.  The environment inherited by any executed command
2471consists of the shell's initial environment, whose values may be
2472modified in the shell, less any pairs removed by the 'unset' and 'export
2473-n' commands, plus any additions via the 'export' and 'declare -x'
2474commands.
2475
2476   The environment for any simple command or function may be augmented
2477temporarily by prefixing it with parameter assignments, as described in
2478*note Shell Parameters::.  These assignment statements affect only the
2479environment seen by that command.
2480
2481   If the '-k' option is set (*note The Set Builtin::), then all
2482parameter assignments are placed in the environment for a command, not
2483just those that precede the command name.
2484
2485   When Bash invokes an external command, the variable '$_' is set to
2486the full pathname of the command and passed to that command in its
2487environment.
2488
24893.7.5 Exit Status
2490-----------------
2491
2492The exit status of an executed command is the value returned by the
2493WAITPID system call or equivalent function.  Exit statuses fall between
24940 and 255, though, as explained below, the shell may use values above
2495125 specially.  Exit statuses from shell builtins and compound commands
2496are also limited to this range.  Under certain circumstances, the shell
2497will use special values to indicate specific failure modes.
2498
2499   For the shell's purposes, a command which exits with a zero exit
2500status has succeeded.  A non-zero exit status indicates failure.  This
2501seemingly counter-intuitive scheme is used so there is one well-defined
2502way to indicate success and a variety of ways to indicate various
2503failure modes.  When a command terminates on a fatal signal whose number
2504is N, Bash uses the value 128+N as the exit status.
2505
2506   If a command is not found, the child process created to execute it
2507returns a status of 127.  If a command is found but is not executable,
2508the return status is 126.
2509
2510   If a command fails because of an error during expansion or
2511redirection, the exit status is greater than zero.
2512
2513   The exit status is used by the Bash conditional commands (*note
2514Conditional Constructs::) and some of the list constructs (*note
2515Lists::).
2516
2517   All of the Bash builtins return an exit status of zero if they
2518succeed and a non-zero status on failure, so they may be used by the
2519conditional and list constructs.  All builtins return an exit status of
25202 to indicate incorrect usage, generally invalid options or missing
2521arguments.
2522
25233.7.6 Signals
2524-------------
2525
2526When Bash is interactive, in the absence of any traps, it ignores
2527'SIGTERM' (so that 'kill 0' does not kill an interactive shell), and
2528'SIGINT' is caught and handled (so that the 'wait' builtin is
2529interruptible).  When Bash receives a 'SIGINT', it breaks out of any
2530executing loops.  In all cases, Bash ignores 'SIGQUIT'.  If job control
2531is in effect (*note Job Control::), Bash ignores 'SIGTTIN', 'SIGTTOU',
2532and 'SIGTSTP'.
2533
2534   Non-builtin commands started by Bash have signal handlers set to the
2535values inherited by the shell from its parent.  When job control is not
2536in effect, asynchronous commands ignore 'SIGINT' and 'SIGQUIT' in
2537addition to these inherited handlers.  Commands run as a result of
2538command substitution ignore the keyboard-generated job control signals
2539'SIGTTIN', 'SIGTTOU', and 'SIGTSTP'.
2540
2541   The shell exits by default upon receipt of a 'SIGHUP'.  Before
2542exiting, an interactive shell resends the 'SIGHUP' to all jobs, running
2543or stopped.  Stopped jobs are sent 'SIGCONT' to ensure that they receive
2544the 'SIGHUP'.  To prevent the shell from sending the 'SIGHUP' signal to
2545a particular job, it should be removed from the jobs table with the
2546'disown' builtin (*note Job Control Builtins::) or marked to not receive
2547'SIGHUP' using 'disown -h'.
2548
2549   If the 'huponexit' shell option has been set with 'shopt' (*note The
2550Shopt Builtin::), Bash sends a 'SIGHUP' to all jobs when an interactive
2551login shell exits.
2552
2553   If Bash is waiting for a command to complete and receives a signal
2554for which a trap has been set, the trap will not be executed until the
2555command completes.  When Bash is waiting for an asynchronous command via
2556the 'wait' builtin, the reception of a signal for which a trap has been
2557set will cause the 'wait' builtin to return immediately with an exit
2558status greater than 128, immediately after which the trap is executed.
2559
25603.8 Shell Scripts
2561=================
2562
2563A shell script is a text file containing shell commands.  When such a
2564file is used as the first non-option argument when invoking Bash, and
2565neither the '-c' nor '-s' option is supplied (*note Invoking Bash::),
2566Bash reads and executes commands from the file, then exits.  This mode
2567of operation creates a non-interactive shell.  The shell first searches
2568for the file in the current directory, and looks in the directories in
2569'$PATH' if not found there.
2570
2571   When Bash runs a shell script, it sets the special parameter '0' to
2572the name of the file, rather than the name of the shell, and the
2573positional parameters are set to the remaining arguments, if any are
2574given.  If no additional arguments are supplied, the positional
2575parameters are unset.
2576
2577   A shell script may be made executable by using the 'chmod' command to
2578turn on the execute bit.  When Bash finds such a file while searching
2579the '$PATH' for a command, it spawns a subshell to execute it.  In other
2580words, executing
2581     filename ARGUMENTS
2582is equivalent to executing
2583     bash filename ARGUMENTS
2584
2585if 'filename' is an executable shell script.  This subshell
2586reinitializes itself, so that the effect is as if a new shell had been
2587invoked to interpret the script, with the exception that the locations
2588of commands remembered by the parent (see the description of 'hash' in
2589*note Bourne Shell Builtins::) are retained by the child.
2590
2591   Most versions of Unix make this a part of the operating system's
2592command execution mechanism.  If the first line of a script begins with
2593the two characters '#!', the remainder of the line specifies an
2594interpreter for the program.  Thus, you can specify Bash, 'awk', Perl,
2595or some other interpreter and write the rest of the script file in that
2596language.
2597
2598   The arguments to the interpreter consist of a single optional
2599argument following the interpreter name on the first line of the script
2600file, followed by the name of the script file, followed by the rest of
2601the arguments.  Bash will perform this action on operating systems that
2602do not handle it themselves.  Note that some older versions of Unix
2603limit the interpreter name and argument to a maximum of 32 characters.
2604
2605   Bash scripts often begin with '#! /bin/bash' (assuming that Bash has
2606been installed in '/bin'), since this ensures that Bash will be used to
2607interpret the script, even if it is executed under another shell.
2608
26094 Shell Builtin Commands
2610************************
2611
2612Builtin commands are contained within the shell itself.  When the name
2613of a builtin command is used as the first word of a simple command
2614(*note Simple Commands::), the shell executes the command directly,
2615without invoking another program.  Builtin commands are necessary to
2616implement functionality impossible or inconvenient to obtain with
2617separate utilities.
2618
2619   This section briefly describes the builtins which Bash inherits from
2620the Bourne Shell, as well as the builtin commands which are unique to or
2621have been extended in Bash.
2622
2623   Several builtin commands are described in other chapters: builtin
2624commands which provide the Bash interface to the job control facilities
2625(*note Job Control Builtins::), the directory stack (*note Directory
2626Stack Builtins::), the command history (*note Bash History Builtins::),
2627and the programmable completion facilities (*note Programmable
2628Completion Builtins::).
2629
2630   Many of the builtins have been extended by POSIX or Bash.
2631
2632   Unless otherwise noted, each builtin command documented as accepting
2633options preceded by '-' accepts '--' to signify the end of the options.
2634The ':', 'true', 'false', and 'test' builtins do not accept options and
2635do not treat '--' specially.  The 'exit', 'logout', 'return', 'break',
2636'continue', 'let', and 'shift' builtins accept and process arguments
2637beginning with '-' without requiring '--'.  Other builtins that accept
2638arguments but are not specified as accepting options interpret arguments
2639beginning with '-' as invalid options and require '--' to prevent this
2640interpretation.
2641
26424.1 Bourne Shell Builtins
2643=========================
2644
2645The following shell builtin commands are inherited from the Bourne
2646Shell.  These commands are implemented as specified by the POSIX
2647standard.
2648
2649': (a colon)'
2650          : [ARGUMENTS]
2651
2652     Do nothing beyond expanding ARGUMENTS and performing redirections.
2653     The return status is zero.
2654
2655'. (a period)'
2656          . FILENAME [ARGUMENTS]
2657
2658     Read and execute commands from the FILENAME argument in the current
2659     shell context.  If FILENAME does not contain a slash, the 'PATH'
2660     variable is used to find FILENAME.  When Bash is not in POSIX mode,
2661     the current directory is searched if FILENAME is not found in
2662     '$PATH'.  If any ARGUMENTS are supplied, they become the positional
2663     parameters when FILENAME is executed.  Otherwise the positional
2664     parameters are unchanged.  If the '-T' option is enabled, 'source'
2665     inherits any trap on 'DEBUG'; if it is not, any 'DEBUG' trap string
2666     is saved and restored around the call to 'source', and 'source'
2667     unsets the 'DEBUG' trap while it executes.  If '-T' is not set, and
2668     the sourced file changes the 'DEBUG' trap, the new value is
2669     retained when 'source' completes.  The return status is the exit
2670     status of the last command executed, or zero if no commands are
2671     executed.  If FILENAME is not found, or cannot be read, the return
2672     status is non-zero.  This builtin is equivalent to 'source'.
2673
2674'break'
2675          break [N]
2676
2677     Exit from a 'for', 'while', 'until', or 'select' loop.  If N is
2678     supplied, the Nth enclosing loop is exited.  N must be greater than
2679     or equal to 1.  The return status is zero unless N is not greater
2680     than or equal to 1.
2681
2682'cd'
2683          cd [-L|[-P [-e]] [-@] [DIRECTORY]
2684
2685     Change the current working directory to DIRECTORY.  If DIRECTORY is
2686     not supplied, the value of the 'HOME' shell variable is used.  Any
2687     additional arguments following DIRECTORY are ignored.  If the shell
2688     variable 'CDPATH' exists, it is used as a search path: each
2689     directory name in 'CDPATH' is searched for DIRECTORY, with
2690     alternative directory names in 'CDPATH' separated by a colon (':').
2691     If DIRECTORY begins with a slash, 'CDPATH' is not used.
2692
2693     The '-P' option means to not follow symbolic links: symbolic links
2694     are resolved while 'cd' is traversing DIRECTORY and before
2695     processing an instance of '..' in DIRECTORY.
2696
2697     By default, or when the '-L' option is supplied, symbolic links in
2698     DIRECTORY are resolved after 'cd' processes an instance of '..' in
2699     DIRECTORY.
2700
2701     If '..' appears in DIRECTORY, it is processed by removing the
2702     immediately preceding pathname component, back to a slash or the
2703     beginning of DIRECTORY.
2704
2705     If the '-e' option is supplied with '-P' and the current working
2706     directory cannot be successfully determined after a successful
2707     directory change, 'cd' will return an unsuccessful status.
2708
2709     On systems that support it, the '-@' option presents the extended
2710     attributes associated with a file as a directory.
2711
2712     If DIRECTORY is '-', it is converted to '$OLDPWD' before the
2713     directory change is attempted.
2714
2715     If a non-empty directory name from 'CDPATH' is used, or if '-' is
2716     the first argument, and the directory change is successful, the
2717     absolute pathname of the new working directory is written to the
2718     standard output.
2719
2720     The return status is zero if the directory is successfully changed,
2721     non-zero otherwise.
2722
2723'continue'
2724          continue [N]
2725
2726     Resume the next iteration of an enclosing 'for', 'while', 'until',
2727     or 'select' loop.  If N is supplied, the execution of the Nth
2728     enclosing loop is resumed.  N must be greater than or equal to 1.
2729     The return status is zero unless N is not greater than or equal to
2730     1.
2731
2732'eval'
2733          eval [ARGUMENTS]
2734
2735     The arguments are concatenated together into a single command,
2736     which is then read and executed, and its exit status returned as
2737     the exit status of 'eval'.  If there are no arguments or only empty
2738     arguments, the return status is zero.
2739
2740'exec'
2741          exec [-cl] [-a NAME] [COMMAND [ARGUMENTS]]
2742
2743     If COMMAND is supplied, it replaces the shell without creating a
2744     new process.  If the '-l' option is supplied, the shell places a
2745     dash at the beginning of the zeroth argument passed to COMMAND.
2746     This is what the 'login' program does.  The '-c' option causes
2747     COMMAND to be executed with an empty environment.  If '-a' is
2748     supplied, the shell passes NAME as the zeroth argument to COMMAND.
2749     If COMMAND cannot be executed for some reason, a non-interactive
2750     shell exits, unless the 'execfail' shell option is enabled.  In
2751     that case, it returns failure.  An interactive shell returns
2752     failure if the file cannot be executed.  If no COMMAND is
2753     specified, redirections may be used to affect the current shell
2754     environment.  If there are no redirection errors, the return status
2755     is zero; otherwise the return status is non-zero.
2756
2757'exit'
2758          exit [N]
2759
2760     Exit the shell, returning a status of N to the shell's parent.  If
2761     N is omitted, the exit status is that of the last command executed.
2762     Any trap on 'EXIT' is executed before the shell terminates.
2763
2764'export'
2765          export [-fn] [-p] [NAME[=VALUE]]
2766
2767     Mark each NAME to be passed to child processes in the environment.
2768     If the '-f' option is supplied, the NAMEs refer to shell functions;
2769     otherwise the names refer to shell variables.  The '-n' option
2770     means to no longer mark each NAME for export.  If no NAMES are
2771     supplied, or if the '-p' option is given, a list of names of all
2772     exported variables is displayed.  The '-p' option displays output
2773     in a form that may be reused as input.  If a variable name is
2774     followed by =VALUE, the value of the variable is set to VALUE.
2775
2776     The return status is zero unless an invalid option is supplied, one
2777     of the names is not a valid shell variable name, or '-f' is
2778     supplied with a name that is not a shell function.
2779
2780'getopts'
2781          getopts OPTSTRING NAME [ARGS]
2782
2783     'getopts' is used by shell scripts to parse positional parameters.
2784     OPTSTRING contains the option characters to be recognized; if a
2785     character is followed by a colon, the option is expected to have an
2786     argument, which should be separated from it by whitespace.  The
2787     colon (':') and question mark ('?') may not be used as option
2788     characters.  Each time it is invoked, 'getopts' places the next
2789     option in the shell variable NAME, initializing NAME if it does not
2790     exist, and the index of the next argument to be processed into the
2791     variable 'OPTIND'.  'OPTIND' is initialized to 1 each time the
2792     shell or a shell script is invoked.  When an option requires an
2793     argument, 'getopts' places that argument into the variable
2794     'OPTARG'.  The shell does not reset 'OPTIND' automatically; it must
2795     be manually reset between multiple calls to 'getopts' within the
2796     same shell invocation if a new set of parameters is to be used.
2797
2798     When the end of options is encountered, 'getopts' exits with a
2799     return value greater than zero.  'OPTIND' is set to the index of
2800     the first non-option argument, and NAME is set to '?'.
2801
2802     'getopts' normally parses the positional parameters, but if more
2803     arguments are given in ARGS, 'getopts' parses those instead.
2804
2805     'getopts' can report errors in two ways.  If the first character of
2806     OPTSTRING is a colon, SILENT error reporting is used.  In normal
2807     operation, diagnostic messages are printed when invalid options or
2808     missing option arguments are encountered.  If the variable 'OPTERR'
2809     is set to 0, no error messages will be displayed, even if the first
2810     character of 'optstring' is not a colon.
2811
2812     If an invalid option is seen, 'getopts' places '?' into NAME and,
2813     if not silent, prints an error message and unsets 'OPTARG'.  If
2814     'getopts' is silent, the option character found is placed in
2815     'OPTARG' and no diagnostic message is printed.
2816
2817     If a required argument is not found, and 'getopts' is not silent, a
2818     question mark ('?') is placed in NAME, 'OPTARG' is unset, and a
2819     diagnostic message is printed.  If 'getopts' is silent, then a
2820     colon (':') is placed in NAME and 'OPTARG' is set to the option
2821     character found.
2822
2823'hash'
2824          hash [-r] [-p FILENAME] [-dt] [NAME]
2825
2826     Each time 'hash' is invoked, it remembers the full pathnames of the
2827     commands specified as NAME arguments, so they need not be searched
2828     for on subsequent invocations.  The commands are found by searching
2829     through the directories listed in '$PATH'.  Any
2830     previously-remembered pathname is discarded.  The '-p' option
2831     inhibits the path search, and FILENAME is used as the location of
2832     NAME.  The '-r' option causes the shell to forget all remembered
2833     locations.  The '-d' option causes the shell to forget the
2834     remembered location of each NAME.  If the '-t' option is supplied,
2835     the full pathname to which each NAME corresponds is printed.  If
2836     multiple NAME arguments are supplied with '-t' the NAME is printed
2837     before the hashed full pathname.  The '-l' option causes output to
2838     be displayed in a format that may be reused as input.  If no
2839     arguments are given, or if only '-l' is supplied, information about
2840     remembered commands is printed.  The return status is zero unless a
2841     NAME is not found or an invalid option is supplied.
2842
2843'pwd'
2844          pwd [-LP]
2845
2846     Print the absolute pathname of the current working directory.  If
2847     the '-P' option is supplied, the pathname printed will not contain
2848     symbolic links.  If the '-L' option is supplied, the pathname
2849     printed may contain symbolic links.  The return status is zero
2850     unless an error is encountered while determining the name of the
2851     current directory or an invalid option is supplied.
2852
2853'readonly'
2854          readonly [-aAf] [-p] [NAME[=VALUE]] ...
2855
2856     Mark each NAME as readonly.  The values of these names may not be
2857     changed by subsequent assignment.  If the '-f' option is supplied,
2858     each NAME refers to a shell function.  The '-a' option means each
2859     NAME refers to an indexed array variable; the '-A' option means
2860     each NAME refers to an associative array variable.  If both options
2861     are supplied, '-A' takes precedence.  If no NAME arguments are
2862     given, or if the '-p' option is supplied, a list of all readonly
2863     names is printed.  The other options may be used to restrict the
2864     output to a subset of the set of readonly names.  The '-p' option
2865     causes output to be displayed in a format that may be reused as
2866     input.  If a variable name is followed by =VALUE, the value of the
2867     variable is set to VALUE.  The return status is zero unless an
2868     invalid option is supplied, one of the NAME arguments is not a
2869     valid shell variable or function name, or the '-f' option is
2870     supplied with a name that is not a shell function.
2871
2872'return'
2873          return [N]
2874
2875     Cause a shell function to stop executing and return the value N to
2876     its caller.  If N is not supplied, the return value is the exit
2877     status of the last command executed in the function.  If 'return'
2878     is executed by a trap handler, the last command used to determine
2879     the status is the last command executed before the trap handler.
2880     if 'return' is executed during a 'DEBUG' trap, the last command
2881     used to determine the status is the last command executed by the
2882     trap handler before 'return' was invoked.  'return' may also be
2883     used to terminate execution of a script being executed with the '.'
2884     ('source') builtin, returning either N or the exit status of the
2885     last command executed within the script as the exit status of the
2886     script.  If N is supplied, the return value is its least
2887     significant 8 bits.  Any command associated with the 'RETURN' trap
2888     is executed before execution resumes after the function or script.
2889     The return status is non-zero if 'return' is supplied a non-numeric
2890     argument or is used outside a function and not during the execution
2891     of a script by '.' or 'source'.
2892
2893'shift'
2894          shift [N]
2895
2896     Shift the positional parameters to the left by N.  The positional
2897     parameters from N+1 ... '$#' are renamed to '$1' ... '$#'-N.
2898     Parameters represented by the numbers '$#' to '$#'-N+1 are unset.
2899     N must be a non-negative number less than or equal to '$#'.  If N
2900     is zero or greater than '$#', the positional parameters are not
2901     changed.  If N is not supplied, it is assumed to be 1.  The return
2902     status is zero unless N is greater than '$#' or less than zero,
2903     non-zero otherwise.
2904
2905'test'
2906'['
2907          test EXPR
2908
2909     Evaluate a conditional expression EXPR and return a status of 0
2910     (true) or 1 (false).  Each operator and operand must be a separate
2911     argument.  Expressions are composed of the primaries described
2912     below in *note Bash Conditional Expressions::.  'test' does not
2913     accept any options, nor does it accept and ignore an argument of
2914     '--' as signifying the end of options.
2915
2916     When the '[' form is used, the last argument to the command must be
2917     a ']'.
2918
2919     Expressions may be combined using the following operators, listed
2920     in decreasing order of precedence.  The evaluation depends on the
2921     number of arguments; see below.  Operator precedence is used when
2922     there are five or more arguments.
2923
2924     '! EXPR'
2925          True if EXPR is false.
2926
2927     '( EXPR )'
2928          Returns the value of EXPR.  This may be used to override the
2929          normal precedence of operators.
2930
2931     'EXPR1 -a EXPR2'
2932          True if both EXPR1 and EXPR2 are true.
2933
2934     'EXPR1 -o EXPR2'
2935          True if either EXPR1 or EXPR2 is true.
2936
2937     The 'test' and '[' builtins evaluate conditional expressions using
2938     a set of rules based on the number of arguments.
2939
2940     0 arguments
2941          The expression is false.
2942
2943     1 argument
2944          The expression is true if and only if the argument is not
2945          null.
2946
2947     2 arguments
2948          If the first argument is '!', the expression is true if and
2949          only if the second argument is null.  If the first argument is
2950          one of the unary conditional operators (*note Bash Conditional
2951          Expressions::), the expression is true if the unary test is
2952          true.  If the first argument is not a valid unary operator,
2953          the expression is false.
2954
2955     3 arguments
2956          The following conditions are applied in the order listed.  If
2957          the second argument is one of the binary conditional operators
2958          (*note Bash Conditional Expressions::), the result of the
2959          expression is the result of the binary test using the first
2960          and third arguments as operands.  The '-a' and '-o' operators
2961          are considered binary operators when there are three
2962          arguments.  If the first argument is '!', the value is the
2963          negation of the two-argument test using the second and third
2964          arguments.  If the first argument is exactly '(' and the third
2965          argument is exactly ')', the result is the one-argument test
2966          of the second argument.  Otherwise, the expression is false.
2967
2968     4 arguments
2969          If the first argument is '!', the result is the negation of
2970          the three-argument expression composed of the remaining
2971          arguments.  Otherwise, the expression is parsed and evaluated
2972          according to precedence using the rules listed above.
2973
2974     5 or more arguments
2975          The expression is parsed and evaluated according to precedence
2976          using the rules listed above.
2977
2978     When used with 'test' or '[', the '<' and '>' operators sort
2979     lexicographically using ASCII ordering.
2980
2981'times'
2982          times
2983
2984     Print out the user and system times used by the shell and its
2985     children.  The return status is zero.
2986
2987'trap'
2988          trap [-lp] [ARG] [SIGSPEC ...]
2989
2990     The commands in ARG are to be read and executed when the shell
2991     receives signal SIGSPEC.  If ARG is absent (and there is a single
2992     SIGSPEC) or equal to '-', each specified signal's disposition is
2993     reset to the value it had when the shell was started.  If ARG is
2994     the null string, then the signal specified by each SIGSPEC is
2995     ignored by the shell and commands it invokes.  If ARG is not
2996     present and '-p' has been supplied, the shell displays the trap
2997     commands associated with each SIGSPEC.  If no arguments are
2998     supplied, or only '-p' is given, 'trap' prints the list of commands
2999     associated with each signal number in a form that may be reused as
3000     shell input.  The '-l' option causes the shell to print a list of
3001     signal names and their corresponding numbers.  Each SIGSPEC is
3002     either a signal name or a signal number.  Signal names are case
3003     insensitive and the 'SIG' prefix is optional.
3004
3005     If a SIGSPEC is '0' or 'EXIT', ARG is executed when the shell
3006     exits.  If a SIGSPEC is 'DEBUG', the command ARG is executed before
3007     every simple command, 'for' command, 'case' command, 'select'
3008     command, every arithmetic 'for' command, and before the first
3009     command executes in a shell function.  Refer to the description of
3010     the 'extdebug' option to the 'shopt' builtin (*note The Shopt
3011     Builtin::) for details of its effect on the 'DEBUG' trap.  If a
3012     SIGSPEC is 'RETURN', the command ARG is executed each time a shell
3013     function or a script executed with the '.' or 'source' builtins
3014     finishes executing.
3015
3016     If a SIGSPEC is 'ERR', the command ARG is executed whenever a
3017     pipeline (which may consist of a single simple command), a list, or
3018     a compound command returns a non-zero exit status, subject to the
3019     following conditions.  The 'ERR' trap is not executed if the failed
3020     command is part of the command list immediately following an
3021     'until' or 'while' keyword, part of the test following the 'if' or
3022     'elif' reserved words, part of a command executed in a '&&' or '||'
3023     list except the command following the final '&&' or '||', any
3024     command in a pipeline but the last, or if the command's return
3025     status is being inverted using '!'.  These are the same conditions
3026     obeyed by the 'errexit' ('-e') option.
3027
3028     Signals ignored upon entry to the shell cannot be trapped or reset.
3029     Trapped signals that are not being ignored are reset to their
3030     original values in a subshell or subshell environment when one is
3031     created.
3032
3033     The return status is zero unless a SIGSPEC does not specify a valid
3034     signal.
3035
3036'umask'
3037          umask [-p] [-S] [MODE]
3038
3039     Set the shell process's file creation mask to MODE.  If MODE begins
3040     with a digit, it is interpreted as an octal number; if not, it is
3041     interpreted as a symbolic mode mask similar to that accepted by the
3042     'chmod' command.  If MODE is omitted, the current value of the mask
3043     is printed.  If the '-S' option is supplied without a MODE
3044     argument, the mask is printed in a symbolic format.  If the '-p'
3045     option is supplied, and MODE is omitted, the output is in a form
3046     that may be reused as input.  The return status is zero if the mode
3047     is successfully changed or if no MODE argument is supplied, and
3048     non-zero otherwise.
3049
3050     Note that when the mode is interpreted as an octal number, each
3051     number of the umask is subtracted from '7'.  Thus, a umask of '022'
3052     results in permissions of '755'.
3053
3054'unset'
3055          unset [-fnv] [NAME]
3056
3057     Remove each variable or function NAME.  If the '-v' option is
3058     given, each NAME refers to a shell variable and that variable is
3059     removed.  If the '-f' option is given, the NAMEs refer to shell
3060     functions, and the function definition is removed.  If the '-n'
3061     option is supplied, and NAME is a variable with the NAMEREF
3062     attribute, NAME will be unset rather than the variable it
3063     references.  '-n' has no effect if the '-f' option is supplied.  If
3064     no options are supplied, each NAME refers to a variable; if there
3065     is no variable by that name, any function with that name is unset.
3066     Readonly variables and functions may not be unset.  The return
3067     status is zero unless a NAME is readonly.
3068
30694.2 Bash Builtin Commands
3070=========================
3071
3072This section describes builtin commands which are unique to or have been
3073extended in Bash.  Some of these commands are specified in the POSIX
3074standard.
3075
3076'alias'
3077          alias [-p] [NAME[=VALUE] ...]
3078
3079     Without arguments or with the '-p' option, 'alias' prints the list
3080     of aliases on the standard output in a form that allows them to be
3081     reused as input.  If arguments are supplied, an alias is defined
3082     for each NAME whose VALUE is given.  If no VALUE is given, the name
3083     and value of the alias is printed.  Aliases are described in *note
3084     Aliases::.
3085
3086'bind'
3087          bind [-m KEYMAP] [-lpsvPSVX]
3088          bind [-m KEYMAP] [-q FUNCTION] [-u FUNCTION] [-r KEYSEQ]
3089          bind [-m KEYMAP] -f FILENAME
3090          bind [-m KEYMAP] -x KEYSEQ:SHELL-COMMAND
3091          bind [-m KEYMAP] KEYSEQ:FUNCTION-NAME
3092          bind [-m KEYMAP] KEYSEQ:READLINE-COMMAND
3093
3094     Display current Readline (*note Command Line Editing::) key and
3095     function bindings, bind a key sequence to a Readline function or
3096     macro, or set a Readline variable.  Each non-option argument is a
3097     command as it would appear in a Readline initialization file (*note
3098     Readline Init File::), but each binding or command must be passed
3099     as a separate argument; e.g., '"\C-x\C-r":re-read-init-file'.
3100
3101     Options, if supplied, have the following meanings:
3102
3103     '-m KEYMAP'
3104          Use KEYMAP as the keymap to be affected by the subsequent
3105          bindings.  Acceptable KEYMAP names are 'emacs',
3106          'emacs-standard', 'emacs-meta', 'emacs-ctlx', 'vi', 'vi-move',
3107          'vi-command', and 'vi-insert'.  'vi' is equivalent to
3108          'vi-command' ('vi-move' is also a synonym); 'emacs' is
3109          equivalent to 'emacs-standard'.
3110
3111     '-l'
3112          List the names of all Readline functions.
3113
3114     '-p'
3115          Display Readline function names and bindings in such a way
3116          that they can be used as input or in a Readline initialization
3117          file.
3118
3119     '-P'
3120          List current Readline function names and bindings.
3121
3122     '-v'
3123          Display Readline variable names and values in such a way that
3124          they can be used as input or in a Readline initialization
3125          file.
3126
3127     '-V'
3128          List current Readline variable names and values.
3129
3130     '-s'
3131          Display Readline key sequences bound to macros and the strings
3132          they output in such a way that they can be used as input or in
3133          a Readline initialization file.
3134
3135     '-S'
3136          Display Readline key sequences bound to macros and the strings
3137          they output.
3138
3139     '-f FILENAME'
3140          Read key bindings from FILENAME.
3141
3142     '-q FUNCTION'
3143          Query about which keys invoke the named FUNCTION.
3144
3145     '-u FUNCTION'
3146          Unbind all keys bound to the named FUNCTION.
3147
3148     '-r KEYSEQ'
3149          Remove any current binding for KEYSEQ.
3150
3151     '-x KEYSEQ:SHELL-COMMAND'
3152          Cause SHELL-COMMAND to be executed whenever KEYSEQ is entered.
3153          When SHELL-COMMAND is executed, the shell sets the
3154          'READLINE_LINE' variable to the contents of the Readline line
3155          buffer and the 'READLINE_POINT' variable to the current
3156          location of the insertion point.  If the executed command
3157          changes the value of 'READLINE_LINE' or 'READLINE_POINT',
3158          those new values will be reflected in the editing state.
3159
3160     '-X'
3161          List all key sequences bound to shell commands and the
3162          associated commands in a format that can be reused as input.
3163
3164     The return status is zero unless an invalid option is supplied or
3165     an error occurs.
3166
3167'builtin'
3168          builtin [SHELL-BUILTIN [ARGS]]
3169
3170     Run a shell builtin, passing it ARGS, and return its exit status.
3171     This is useful when defining a shell function with the same name as
3172     a shell builtin, retaining the functionality of the builtin within
3173     the function.  The return status is non-zero if SHELL-BUILTIN is
3174     not a shell builtin command.
3175
3176'caller'
3177          caller [EXPR]
3178
3179     Returns the context of any active subroutine call (a shell function
3180     or a script executed with the '.' or 'source' builtins).
3181
3182     Without EXPR, 'caller' displays the line number and source filename
3183     of the current subroutine call.  If a non-negative integer is
3184     supplied as EXPR, 'caller' displays the line number, subroutine
3185     name, and source file corresponding to that position in the current
3186     execution call stack.  This extra information may be used, for
3187     example, to print a stack trace.  The current frame is frame 0.
3188
3189     The return value is 0 unless the shell is not executing a
3190     subroutine call or EXPR does not correspond to a valid position in
3191     the call stack.
3192
3193'command'
3194          command [-pVv] COMMAND [ARGUMENTS ...]
3195
3196     Runs COMMAND with ARGUMENTS ignoring any shell function named
3197     COMMAND.  Only shell builtin commands or commands found by
3198     searching the 'PATH' are executed.  If there is a shell function
3199     named 'ls', running 'command ls' within the function will execute
3200     the external command 'ls' instead of calling the function
3201     recursively.  The '-p' option means to use a default value for
3202     'PATH' that is guaranteed to find all of the standard utilities.
3203     The return status in this case is 127 if COMMAND cannot be found or
3204     an error occurred, and the exit status of COMMAND otherwise.
3205
3206     If either the '-V' or '-v' option is supplied, a description of
3207     COMMAND is printed.  The '-v' option causes a single word
3208     indicating the command or file name used to invoke COMMAND to be
3209     displayed; the '-V' option produces a more verbose description.  In
3210     this case, the return status is zero if COMMAND is found, and
3211     non-zero if not.
3212
3213'declare'
3214          declare [-aAfFgilnrtux] [-p] [NAME[=VALUE] ...]
3215
3216     Declare variables and give them attributes.  If no NAMEs are given,
3217     then display the values of variables instead.
3218
3219     The '-p' option will display the attributes and values of each
3220     NAME.  When '-p' is used with NAME arguments, additional options,
3221     other than '-f' and '-F', are ignored.
3222
3223     When '-p' is supplied without NAME arguments, 'declare' will
3224     display the attributes and values of all variables having the
3225     attributes specified by the additional options.  If no other
3226     options are supplied with '-p', 'declare' will display the
3227     attributes and values of all shell variables.  The '-f' option will
3228     restrict the display to shell functions.
3229
3230     The '-F' option inhibits the display of function definitions; only
3231     the function name and attributes are printed.  If the 'extdebug'
3232     shell option is enabled using 'shopt' (*note The Shopt Builtin::),
3233     the source file name and line number where each NAME is defined are
3234     displayed as well.  '-F' implies '-f'.
3235
3236     The '-g' option forces variables to be created or modified at the
3237     global scope, even when 'declare' is executed in a shell function.
3238     It is ignored in all other cases.
3239
3240     The following options can be used to restrict output to variables
3241     with the specified attributes or to give variables attributes:
3242
3243     '-a'
3244          Each NAME is an indexed array variable (*note Arrays::).
3245
3246     '-A'
3247          Each NAME is an associative array variable (*note Arrays::).
3248
3249     '-f'
3250          Use function names only.
3251
3252     '-i'
3253          The variable is to be treated as an integer; arithmetic
3254          evaluation (*note Shell Arithmetic::) is performed when the
3255          variable is assigned a value.
3256
3257     '-l'
3258          When the variable is assigned a value, all upper-case
3259          characters are converted to lower-case.  The upper-case
3260          attribute is disabled.
3261
3262     '-n'
3263          Give each NAME the NAMEREF attribute, making it a name
3264          reference to another variable.  That other variable is defined
3265          by the value of NAME.  All references, assignments, and
3266          attribute modifications to NAME, except for those using or
3267          changing the '-n' attribute itself, are performed on the
3268          variable referenced by NAME's value.  The nameref attribute
3269          cannot be applied to array variables.
3270
3271     '-r'
3272          Make NAMEs readonly.  These names cannot then be assigned
3273          values by subsequent assignment statements or unset.
3274
3275     '-t'
3276          Give each NAME the 'trace' attribute.  Traced functions
3277          inherit the 'DEBUG' and 'RETURN' traps from the calling shell.
3278          The trace attribute has no special meaning for variables.
3279
3280     '-u'
3281          When the variable is assigned a value, all lower-case
3282          characters are converted to upper-case.  The lower-case
3283          attribute is disabled.
3284
3285     '-x'
3286          Mark each NAME for export to subsequent commands via the
3287          environment.
3288
3289     Using '+' instead of '-' turns off the attribute instead, with the
3290     exceptions that '+a' may not be used to destroy an array variable
3291     and '+r' will not remove the readonly attribute.  When used in a
3292     function, 'declare' makes each NAME local, as with the 'local'
3293     command, unless the '-g' option is used.  If a variable name is
3294     followed by =VALUE, the value of the variable is set to VALUE.
3295
3296     When using '-a' or '-A' and the compound assignment syntax to
3297     create array variables, additional attributes do not take effect
3298     until subsequent assignments.
3299
3300     The return status is zero unless an invalid option is encountered,
3301     an attempt is made to define a function using '-f foo=bar', an
3302     attempt is made to assign a value to a readonly variable, an
3303     attempt is made to assign a value to an array variable without
3304     using the compound assignment syntax (*note Arrays::), one of the
3305     NAMES is not a valid shell variable name, an attempt is made to
3306     turn off readonly status for a readonly variable, an attempt is
3307     made to turn off array status for an array variable, or an attempt
3308     is made to display a non-existent function with '-f'.
3309
3310'echo'
3311          echo [-neE] [ARG ...]
3312
3313     Output the ARGs, separated by spaces, terminated with a newline.
3314     The return status is 0 unless a write error occurs.  If '-n' is
3315     specified, the trailing newline is suppressed.  If the '-e' option
3316     is given, interpretation of the following backslash-escaped
3317     characters is enabled.  The '-E' option disables the interpretation
3318     of these escape characters, even on systems where they are
3319     interpreted by default.  The 'xpg_echo' shell option may be used to
3320     dynamically determine whether or not 'echo' expands these escape
3321     characters by default.  'echo' does not interpret '--' to mean the
3322     end of options.
3323
3324     'echo' interprets the following escape sequences:
3325     '\a'
3326          alert (bell)
3327     '\b'
3328          backspace
3329     '\c'
3330          suppress further output
3331     '\e'
3332     '\E'
3333          escape
3334     '\f'
3335          form feed
3336     '\n'
3337          new line
3338     '\r'
3339          carriage return
3340     '\t'
3341          horizontal tab
3342     '\v'
3343          vertical tab
3344     '\\'
3345          backslash
3346     '\0NNN'
3347          the eight-bit character whose value is the octal value NNN
3348          (zero to three octal digits)
3349     '\xHH'
3350          the eight-bit character whose value is the hexadecimal value
3351          HH (one or two hex digits)
3352     '\uHHHH'
3353          the Unicode (ISO/IEC 10646) character whose value is the
3354          hexadecimal value HHHH (one to four hex digits)
3355     '\UHHHHHHHH'
3356          the Unicode (ISO/IEC 10646) character whose value is the
3357          hexadecimal value HHHHHHHH (one to eight hex digits)
3358
3359'enable'
3360          enable [-a] [-dnps] [-f FILENAME] [NAME ...]
3361
3362     Enable and disable builtin shell commands.  Disabling a builtin
3363     allows a disk command which has the same name as a shell builtin to
3364     be executed without specifying a full pathname, even though the
3365     shell normally searches for builtins before disk commands.  If '-n'
3366     is used, the NAMEs become disabled.  Otherwise NAMEs are enabled.
3367     For example, to use the 'test' binary found via '$PATH' instead of
3368     the shell builtin version, type 'enable -n test'.
3369
3370     If the '-p' option is supplied, or no NAME arguments appear, a list
3371     of shell builtins is printed.  With no other arguments, the list
3372     consists of all enabled shell builtins.  The '-a' option means to
3373     list each builtin with an indication of whether or not it is
3374     enabled.
3375
3376     The '-f' option means to load the new builtin command NAME from
3377     shared object FILENAME, on systems that support dynamic loading.
3378     The '-d' option will delete a builtin loaded with '-f'.
3379
3380     If there are no options, a list of the shell builtins is displayed.
3381     The '-s' option restricts 'enable' to the POSIX special builtins.
3382     If '-s' is used with '-f', the new builtin becomes a special
3383     builtin (*note Special Builtins::).
3384
3385     The return status is zero unless a NAME is not a shell builtin or
3386     there is an error loading a new builtin from a shared object.
3387
3388'help'
3389          help [-dms] [PATTERN]
3390
3391     Display helpful information about builtin commands.  If PATTERN is
3392     specified, 'help' gives detailed help on all commands matching
3393     PATTERN, otherwise a list of the builtins is printed.
3394
3395     Options, if supplied, have the following meanings:
3396
3397     '-d'
3398          Display a short description of each PATTERN
3399     '-m'
3400          Display the description of each PATTERN in a manpage-like
3401          format
3402     '-s'
3403          Display only a short usage synopsis for each PATTERN
3404
3405     The return status is zero unless no command matches PATTERN.
3406
3407'let'
3408          let EXPRESSION [EXPRESSION ...]
3409
3410     The 'let' builtin allows arithmetic to be performed on shell
3411     variables.  Each EXPRESSION is evaluated according to the rules
3412     given below in *note Shell Arithmetic::.  If the last EXPRESSION
3413     evaluates to 0, 'let' returns 1; otherwise 0 is returned.
3414
3415'local'
3416          local [OPTION] NAME[=VALUE] ...
3417
3418     For each argument, a local variable named NAME is created, and
3419     assigned VALUE.  The OPTION can be any of the options accepted by
3420     'declare'.  'local' can only be used within a function; it makes
3421     the variable NAME have a visible scope restricted to that function
3422     and its children.  If NAME is '-', the set of shell options is made
3423     local to the function in which 'local' is invoked: shell options
3424     changed using the 'set' builtin inside the function are restored to
3425     their original values when the function returns.  The return status
3426     is zero unless 'local' is used outside a function, an invalid NAME
3427     is supplied, or NAME is a readonly variable.
3428
3429'logout'
3430          logout [N]
3431
3432     Exit a login shell, returning a status of N to the shell's parent.
3433
3434'mapfile'
3435          mapfile [-d DELIM] [-n COUNT] [-O ORIGIN] [-s COUNT] [-t] [-u FD]
3436              [-C CALLBACK] [-c QUANTUM] [ARRAY]
3437
3438     Read lines from the standard input into the indexed array variable
3439     ARRAY, or from file descriptor FD if the '-u' option is supplied.
3440     The variable 'MAPFILE' is the default ARRAY.  Options, if supplied,
3441     have the following meanings:
3442
3443     '-d'
3444          The first character of DELIM is used to terminate each input
3445          line, rather than newline.
3446     '-n'
3447          Copy at most COUNT lines.  If COUNT is 0, all lines are
3448          copied.
3449     '-O'
3450          Begin assigning to ARRAY at index ORIGIN.  The default index
3451          is 0.
3452     '-s'
3453          Discard the first COUNT lines read.
3454     '-t'
3455          Remove a trailing DELIM (default newline) from each line read.
3456     '-u'
3457          Read lines from file descriptor FD instead of the standard
3458          input.
3459     '-C'
3460          Evaluate CALLBACK each time QUANTUMP lines are read.  The '-c'
3461          option specifies QUANTUM.
3462     '-c'
3463          Specify the number of lines read between each call to
3464          CALLBACK.
3465
3466     If '-C' is specified without '-c', the default quantum is 5000.
3467     When CALLBACK is evaluated, it is supplied the index of the next
3468     array element to be assigned and the line to be assigned to that
3469     element as additional arguments.  CALLBACK is evaluated after the
3470     line is read but before the array element is assigned.
3471
3472     If not supplied with an explicit origin, 'mapfile' will clear ARRAY
3473     before assigning to it.
3474
3475     'mapfile' returns successfully unless an invalid option or option
3476     argument is supplied, ARRAY is invalid or unassignable, or ARRAY is
3477     not an indexed array.
3478
3479'printf'
3480          printf [-v VAR] FORMAT [ARGUMENTS]
3481
3482     Write the formatted ARGUMENTS to the standard output under the
3483     control of the FORMAT.  The '-v' option causes the output to be
3484     assigned to the variable VAR rather than being printed to the
3485     standard output.
3486
3487     The FORMAT is a character string which contains three types of
3488     objects: plain characters, which are simply copied to standard
3489     output, character escape sequences, which are converted and copied
3490     to the standard output, and format specifications, each of which
3491     causes printing of the next successive ARGUMENT.  In addition to
3492     the standard 'printf(1)' formats, 'printf' interprets the following
3493     extensions:
3494
3495     '%b'
3496          Causes 'printf' to expand backslash escape sequences in the
3497          corresponding ARGUMENT in the same way as 'echo -e' (*note
3498          Bash Builtins::).
3499     '%q'
3500          Causes 'printf' to output the corresponding ARGUMENT in a
3501          format that can be reused as shell input.
3502     '%(DATEFMT)T'
3503          Causes 'printf' to output the date-time string resulting from
3504          using DATEFMT as a format string for 'strftime'(3).  The
3505          corresponding ARGUMENT is an integer representing the number
3506          of seconds since the epoch.  Two special argument values may
3507          be used: -1 represents the current time, and -2 represents the
3508          time the shell was invoked.  If no argument is specified,
3509          conversion behaves as if -1 had been given.  This is an
3510          exception to the usual 'printf' behavior.
3511
3512     Arguments to non-string format specifiers are treated as C language
3513     constants, except that a leading plus or minus sign is allowed, and
3514     if the leading character is a single or double quote, the value is
3515     the ASCII value of the following character.
3516
3517     The FORMAT is reused as necessary to consume all of the ARGUMENTS.
3518     If the FORMAT requires more ARGUMENTS than are supplied, the extra
3519     format specifications behave as if a zero value or null string, as
3520     appropriate, had been supplied.  The return value is zero on
3521     success, non-zero on failure.
3522
3523'read'
3524          read [-ers] [-a ANAME] [-d DELIM] [-i TEXT] [-n NCHARS]
3525              [-N NCHARS] [-p PROMPT] [-t TIMEOUT] [-u FD] [NAME ...]
3526
3527     One line is read from the standard input, or from the file
3528     descriptor FD supplied as an argument to the '-u' option, split
3529     into words as described above in *note Word Splitting::, and the
3530     first word is assigned to the first NAME, the second word to the
3531     second NAME, and so on.  If there are more words than names, the
3532     remaining words and their intervening delimiters are assigned to
3533     the last NAME.  If there are fewer words read from the input stream
3534     than names, the remaining names are assigned empty values.  The
3535     characters in the value of the 'IFS' variable are used to split the
3536     line into words using the same rules the shell uses for expansion
3537     (described above in *note Word Splitting::).  The backslash
3538     character '\' may be used to remove any special meaning for the
3539     next character read and for line continuation.  If no names are
3540     supplied, the line read is assigned to the variable 'REPLY'.  The
3541     exit status is zero, unless end-of-file is encountered, 'read'
3542     times out (in which case the status is greater than 128), a
3543     variable assignment error (such as assigning to a readonly
3544     variable) occurs, or an invalid file descriptor is supplied as the
3545     argument to '-u'.
3546
3547     Options, if supplied, have the following meanings:
3548
3549     '-a ANAME'
3550          The words are assigned to sequential indices of the array
3551          variable ANAME, starting at 0.  All elements are removed from
3552          ANAME before the assignment.  Other NAME arguments are
3553          ignored.
3554
3555     '-d DELIM'
3556          The first character of DELIM is used to terminate the input
3557          line, rather than newline.
3558
3559     '-e'
3560          Readline (*note Command Line Editing::) is used to obtain the
3561          line.  Readline uses the current (or default, if line editing
3562          was not previously active) editing settings.
3563
3564     '-i TEXT'
3565          If Readline is being used to read the line, TEXT is placed
3566          into the editing buffer before editing begins.
3567
3568     '-n NCHARS'
3569          'read' returns after reading NCHARS characters rather than
3570          waiting for a complete line of input, but honors a delimiter
3571          if fewer than NCHARS characters are read before the delimiter.
3572
3573     '-N NCHARS'
3574          'read' returns after reading exactly NCHARS characters rather
3575          than waiting for a complete line of input, unless EOF is
3576          encountered or 'read' times out.  Delimiter characters
3577          encountered in the input are not treated specially and do not
3578          cause 'read' to return until NCHARS characters are read.  The
3579          result is not split on the characters in 'IFS'; the intent is
3580          that the variable is assigned exactly the characters read
3581          (with the exception of backslash; see the '-r' option below).
3582
3583     '-p PROMPT'
3584          Display PROMPT, without a trailing newline, before attempting
3585          to read any input.  The prompt is displayed only if input is
3586          coming from a terminal.
3587
3588     '-r'
3589          If this option is given, backslash does not act as an escape
3590          character.  The backslash is considered to be part of the
3591          line.  In particular, a backslash-newline pair may not be used
3592          as a line continuation.
3593
3594     '-s'
3595          Silent mode.  If input is coming from a terminal, characters
3596          are not echoed.
3597
3598     '-t TIMEOUT'
3599          Cause 'read' to time out and return failure if a complete line
3600          of input (or a specified number of characters) is not read
3601          within TIMEOUT seconds.  TIMEOUT may be a decimal number with
3602          a fractional portion following the decimal point.  This option
3603          is only effective if 'read' is reading input from a terminal,
3604          pipe, or other special file; it has no effect when reading
3605          from regular files.  If 'read' times out, 'read' saves any
3606          partial input read into the specified variable NAME.  If
3607          TIMEOUT is 0, 'read' returns immediately, without trying to
3608          read and data.  The exit status is 0 if input is available on
3609          the specified file descriptor, non-zero otherwise.  The exit
3610          status is greater than 128 if the timeout is exceeded.
3611
3612     '-u FD'
3613          Read input from file descriptor FD.
3614
3615'readarray'
3616          readarray [-d DELIM] [-n COUNT] [-O ORIGIN] [-s COUNT] [-t] [-u FD]
3617              [-C CALLBACK] [-c QUANTUM] [ARRAY]
3618
3619     Read lines from the standard input into the indexed array variable
3620     ARRAY, or from file descriptor FD if the '-u' option is supplied.
3621
3622     A synonym for 'mapfile'.
3623
3624'source'
3625          source FILENAME
3626
3627     A synonym for '.' (*note Bourne Shell Builtins::).
3628
3629'type'
3630          type [-afptP] [NAME ...]
3631
3632     For each NAME, indicate how it would be interpreted if used as a
3633     command name.
3634
3635     If the '-t' option is used, 'type' prints a single word which is
3636     one of 'alias', 'function', 'builtin', 'file' or 'keyword', if NAME
3637     is an alias, shell function, shell builtin, disk file, or shell
3638     reserved word, respectively.  If the NAME is not found, then
3639     nothing is printed, and 'type' returns a failure status.
3640
3641     If the '-p' option is used, 'type' either returns the name of the
3642     disk file that would be executed, or nothing if '-t' would not
3643     return 'file'.
3644
3645     The '-P' option forces a path search for each NAME, even if '-t'
3646     would not return 'file'.
3647
3648     If a command is hashed, '-p' and '-P' print the hashed value, which
3649     is not necessarily the file that appears first in '$PATH'.
3650
3651     If the '-a' option is used, 'type' returns all of the places that
3652     contain an executable named FILE.  This includes aliases and
3653     functions, if and only if the '-p' option is not also used.
3654
3655     If the '-f' option is used, 'type' does not attempt to find shell
3656     functions, as with the 'command' builtin.
3657
3658     The return status is zero if all of the NAMES are found, non-zero
3659     if any are not found.
3660
3661'typeset'
3662          typeset [-afFgrxilnrtux] [-p] [NAME[=VALUE] ...]
3663
3664     The 'typeset' command is supplied for compatibility with the Korn
3665     shell.  It is a synonym for the 'declare' builtin command.
3666
3667'ulimit'
3668          ulimit [-HSabcdefiklmnpqrstuvxPT] [LIMIT]
3669
3670     'ulimit' provides control over the resources available to processes
3671     started by the shell, on systems that allow such control.  If an
3672     option is given, it is interpreted as follows:
3673
3674     '-S'
3675          Change and report the soft limit associated with a resource.
3676
3677     '-H'
3678          Change and report the hard limit associated with a resource.
3679
3680     '-a'
3681          All current limits are reported.
3682
3683     '-b'
3684          The maximum socket buffer size.
3685
3686     '-c'
3687          The maximum size of core files created.
3688
3689     '-d'
3690          The maximum size of a process's data segment.
3691
3692     '-e'
3693          The maximum scheduling priority ("nice").
3694
3695     '-f'
3696          The maximum size of files written by the shell and its
3697          children.
3698
3699     '-i'
3700          The maximum number of pending signals.
3701
3702     '-k'
3703          The maximum number of kqueues that may be allocated.
3704
3705     '-l'
3706          The maximum size that may be locked into memory.
3707
3708     '-m'
3709          The maximum resident set size (many systems do not honor this
3710          limit).
3711
3712     '-n'
3713          The maximum number of open file descriptors (most systems do
3714          not allow this value to be set).
3715
3716     '-p'
3717          The pipe buffer size.
3718
3719     '-q'
3720          The maximum number of bytes in POSIX message queues.
3721
3722     '-r'
3723          The maximum real-time scheduling priority.
3724
3725     '-s'
3726          The maximum stack size.
3727
3728     '-t'
3729          The maximum amount of cpu time in seconds.
3730
3731     '-u'
3732          The maximum number of processes available to a single user.
3733
3734     '-v'
3735          The maximum amount of virtual memory available to the shell,
3736          and, on some systems, to its children.
3737
3738     '-x'
3739          The maximum number of file locks.
3740
3741     '-P'
3742          The maximum number of pseudoterminals.
3743
3744     '-T'
3745          The maximum number of threads.
3746
3747     If LIMIT is given, and the '-a' option is not used, LIMIT is the
3748     new value of the specified resource.  The special LIMIT values
3749     'hard', 'soft', and 'unlimited' stand for the current hard limit,
3750     the current soft limit, and no limit, respectively.  A hard limit
3751     cannot be increased by a non-root user once it is set; a soft limit
3752     may be increased up to the value of the hard limit.  Otherwise, the
3753     current value of the soft limit for the specified resource is
3754     printed, unless the '-H' option is supplied.  When setting new
3755     limits, if neither '-H' nor '-S' is supplied, both the hard and
3756     soft limits are set.  If no option is given, then '-f' is assumed.
3757     Values are in 1024-byte increments, except for '-t', which is in
3758     seconds; '-p', which is in units of 512-byte blocks; '-P', '-T',
3759     '-b', '-k', '-n' and '-u', which are unscaled values; and, when in
3760     POSIX Mode (*note Bash POSIX Mode::), '-c' and '-f', which are in
3761     512-byte increments.
3762
3763     The return status is zero unless an invalid option or argument is
3764     supplied, or an error occurs while setting a new limit.
3765
3766'unalias'
3767          unalias [-a] [NAME ... ]
3768
3769     Remove each NAME from the list of aliases.  If '-a' is supplied,
3770     all aliases are removed.  Aliases are described in *note Aliases::.
3771
37724.3 Modifying Shell Behavior
3773============================
3774
37754.3.1 The Set Builtin
3776---------------------
3777
3778This builtin is so complicated that it deserves its own section.  'set'
3779allows you to change the values of shell options and set the positional
3780parameters, or to display the names and values of shell variables.
3781
3782'set'
3783          set [--abefhkmnptuvxBCEHPT] [-o OPTION-NAME] [ARGUMENT ...]
3784          set [+abefhkmnptuvxBCEHPT] [+o OPTION-NAME] [ARGUMENT ...]
3785
3786     If no options or arguments are supplied, 'set' displays the names
3787     and values of all shell variables and functions, sorted according
3788     to the current locale, in a format that may be reused as input for
3789     setting or resetting the currently-set variables.  Read-only
3790     variables cannot be reset.  In POSIX mode, only shell variables are
3791     listed.
3792
3793     When options are supplied, they set or unset shell attributes.
3794     Options, if specified, have the following meanings:
3795
3796     '-a'
3797          Each variable or function that is created or modified is given
3798          the export attribute and marked for export to the environment
3799          of subsequent commands.
3800
3801     '-b'
3802          Cause the status of terminated background jobs to be reported
3803          immediately, rather than before printing the next primary
3804          prompt.
3805
3806     '-e'
3807          Exit immediately if a pipeline (*note Pipelines::), which may
3808          consist of a single simple command (*note Simple Commands::),
3809          a list (*note Lists::), or a compound command (*note Compound
3810          Commands::) returns a non-zero status.  The shell does not
3811          exit if the command that fails is part of the command list
3812          immediately following a 'while' or 'until' keyword, part of
3813          the test in an 'if' statement, part of any command executed in
3814          a '&&' or '||' list except the command following the final
3815          '&&' or '||', any command in a pipeline but the last, or if
3816          the command's return status is being inverted with '!'.  If a
3817          compound command other than a subshell returns a non-zero
3818          status because a command failed while '-e' was being ignored,
3819          the shell does not exit.  A trap on 'ERR', if set, is executed
3820          before the shell exits.
3821
3822          This option applies to the shell environment and each subshell
3823          environment separately (*note Command Execution
3824          Environment::), and may cause subshells to exit before
3825          executing all the commands in the subshell.
3826
3827          If a compound command or shell function executes in a context
3828          where '-e' is being ignored, none of the commands executed
3829          within the compound command or function body will be affected
3830          by the '-e' setting, even if '-e' is set and a command returns
3831          a failure status.  If a compound command or shell function
3832          sets '-e' while executing in a context where '-e' is ignored,
3833          that setting will not have any effect until the compound
3834          command or the command containing the function call completes.
3835
3836     '-f'
3837          Disable filename expansion (globbing).
3838
3839     '-h'
3840          Locate and remember (hash) commands as they are looked up for
3841          execution.  This option is enabled by default.
3842
3843     '-k'
3844          All arguments in the form of assignment statements are placed
3845          in the environment for a command, not just those that precede
3846          the command name.
3847
3848     '-m'
3849          Job control is enabled (*note Job Control::).  All processes
3850          run in a separate process group.  When a background job
3851          completes, the shell prints a line containing its exit status.
3852
3853     '-n'
3854          Read commands but do not execute them.  This may be used to
3855          check a script for syntax errors.  This option is ignored by
3856          interactive shells.
3857
3858     '-o OPTION-NAME'
3859
3860          Set the option corresponding to OPTION-NAME:
3861
3862          'allexport'
3863               Same as '-a'.
3864
3865          'braceexpand'
3866               Same as '-B'.
3867
3868          'emacs'
3869               Use an 'emacs'-style line editing interface (*note
3870               Command Line Editing::).  This also affects the editing
3871               interface used for 'read -e'.
3872
3873          'errexit'
3874               Same as '-e'.
3875
3876          'errtrace'
3877               Same as '-E'.
3878
3879          'functrace'
3880               Same as '-T'.
3881
3882          'hashall'
3883               Same as '-h'.
3884
3885          'histexpand'
3886               Same as '-H'.
3887
3888          'history'
3889               Enable command history, as described in *note Bash
3890               History Facilities::.  This option is on by default in
3891               interactive shells.
3892
3893          'ignoreeof'
3894               An interactive shell will not exit upon reading EOF.
3895
3896          'keyword'
3897               Same as '-k'.
3898
3899          'monitor'
3900               Same as '-m'.
3901
3902          'noclobber'
3903               Same as '-C'.
3904
3905          'noexec'
3906               Same as '-n'.
3907
3908          'noglob'
3909               Same as '-f'.
3910
3911          'nolog'
3912               Currently ignored.
3913
3914          'notify'
3915               Same as '-b'.
3916
3917          'nounset'
3918               Same as '-u'.
3919
3920          'onecmd'
3921               Same as '-t'.
3922
3923          'physical'
3924               Same as '-P'.
3925
3926          'pipefail'
3927               If set, the return value of a pipeline is the value of
3928               the last (rightmost) command to exit with a non-zero
3929               status, or zero if all commands in the pipeline exit
3930               successfully.  This option is disabled by default.
3931
3932          'posix'
3933               Change the behavior of Bash where the default operation
3934               differs from the POSIX standard to match the standard
3935               (*note Bash POSIX Mode::).  This is intended to make Bash
3936               behave as a strict superset of that standard.
3937
3938          'privileged'
3939               Same as '-p'.
3940
3941          'verbose'
3942               Same as '-v'.
3943
3944          'vi'
3945               Use a 'vi'-style line editing interface.  This also
3946               affects the editing interface used for 'read -e'.
3947
3948          'xtrace'
3949               Same as '-x'.
3950
3951     '-p'
3952          Turn on privileged mode.  In this mode, the '$BASH_ENV' and
3953          '$ENV' files are not processed, shell functions are not
3954          inherited from the environment, and the 'SHELLOPTS',
3955          'BASHOPTS', 'CDPATH' and 'GLOBIGNORE' variables, if they
3956          appear in the environment, are ignored.  If the shell is
3957          started with the effective user (group) id not equal to the
3958          real user (group) id, and the '-p' option is not supplied,
3959          these actions are taken and the effective user id is set to
3960          the real user id.  If the '-p' option is supplied at startup,
3961          the effective user id is not reset.  Turning this option off
3962          causes the effective user and group ids to be set to the real
3963          user and group ids.
3964
3965     '-t'
3966          Exit after reading and executing one command.
3967
3968     '-u'
3969          Treat unset variables and parameters other than the special
3970          parameters '@' or '*' as an error when performing parameter
3971          expansion.  An error message will be written to the standard
3972          error, and a non-interactive shell will exit.
3973
3974     '-v'
3975          Print shell input lines as they are read.
3976
3977     '-x'
3978          Print a trace of simple commands, 'for' commands, 'case'
3979          commands, 'select' commands, and arithmetic 'for' commands and
3980          their arguments or associated word lists after they are
3981          expanded and before they are executed.  The value of the 'PS4'
3982          variable is expanded and the resultant value is printed before
3983          the command and its expanded arguments.
3984
3985     '-B'
3986          The shell will perform brace expansion (*note Brace
3987          Expansion::).  This option is on by default.
3988
3989     '-C'
3990          Prevent output redirection using '>', '>&', and '<>' from
3991          overwriting existing files.
3992
3993     '-E'
3994          If set, any trap on 'ERR' is inherited by shell functions,
3995          command substitutions, and commands executed in a subshell
3996          environment.  The 'ERR' trap is normally not inherited in such
3997          cases.
3998
3999     '-H'
4000          Enable '!' style history substitution (*note History
4001          Interaction::).  This option is on by default for interactive
4002          shells.
4003
4004     '-P'
4005          If set, do not resolve symbolic links when performing commands
4006          such as 'cd' which change the current directory.  The physical
4007          directory is used instead.  By default, Bash follows the
4008          logical chain of directories when performing commands which
4009          change the current directory.
4010
4011          For example, if '/usr/sys' is a symbolic link to
4012          '/usr/local/sys' then:
4013               $ cd /usr/sys; echo $PWD
4014               /usr/sys
4015               $ cd ..; pwd
4016               /usr
4017
4018          If 'set -P' is on, then:
4019               $ cd /usr/sys; echo $PWD
4020               /usr/local/sys
4021               $ cd ..; pwd
4022               /usr/local
4023
4024     '-T'
4025          If set, any trap on 'DEBUG' and 'RETURN' are inherited by
4026          shell functions, command substitutions, and commands executed
4027          in a subshell environment.  The 'DEBUG' and 'RETURN' traps are
4028          normally not inherited in such cases.
4029
4030     '--'
4031          If no arguments follow this option, then the positional
4032          parameters are unset.  Otherwise, the positional parameters
4033          are set to the ARGUMENTS, even if some of them begin with a
4034          '-'.
4035
4036     '-'
4037          Signal the end of options, cause all remaining ARGUMENTS to be
4038          assigned to the positional parameters.  The '-x' and '-v'
4039          options are turned off.  If there are no arguments, the
4040          positional parameters remain unchanged.
4041
4042     Using '+' rather than '-' causes these options to be turned off.
4043     The options can also be used upon invocation of the shell.  The
4044     current set of options may be found in '$-'.
4045
4046     The remaining N ARGUMENTS are positional parameters and are
4047     assigned, in order, to '$1', '$2', ... '$N'.  The special parameter
4048     '#' is set to N.
4049
4050     The return status is always zero unless an invalid option is
4051     supplied.
4052
40534.3.2 The Shopt Builtin
4054-----------------------
4055
4056This builtin allows you to change additional shell optional behavior.
4057
4058'shopt'
4059          shopt [-pqsu] [-o] [OPTNAME ...]
4060
4061     Toggle the values of settings controlling optional shell behavior.
4062     The settings can be either those listed below, or, if the '-o'
4063     option is used, those available with the '-o' option to the 'set'
4064     builtin command (*note The Set Builtin::).  With no options, or
4065     with the '-p' option, a list of all settable options is displayed,
4066     with an indication of whether or not each is set.  The '-p' option
4067     causes output to be displayed in a form that may be reused as
4068     input.  Other options have the following meanings:
4069
4070     '-s'
4071          Enable (set) each OPTNAME.
4072
4073     '-u'
4074          Disable (unset) each OPTNAME.
4075
4076     '-q'
4077          Suppresses normal output; the return status indicates whether
4078          the OPTNAME is set or unset.  If multiple OPTNAME arguments
4079          are given with '-q', the return status is zero if all OPTNAMES
4080          are enabled; non-zero otherwise.
4081
4082     '-o'
4083          Restricts the values of OPTNAME to be those defined for the
4084          '-o' option to the 'set' builtin (*note The Set Builtin::).
4085
4086     If either '-s' or '-u' is used with no OPTNAME arguments, 'shopt'
4087     shows only those options which are set or unset, respectively.
4088
4089     Unless otherwise noted, the 'shopt' options are disabled (off) by
4090     default.
4091
4092     The return status when listing options is zero if all OPTNAMES are
4093     enabled, non-zero otherwise.  When setting or unsetting options,
4094     the return status is zero unless an OPTNAME is not a valid shell
4095     option.
4096
4097     The list of 'shopt' options is:
4098
4099     'autocd'
4100          If set, a command name that is the name of a directory is
4101          executed as if it were the argument to the 'cd' command.  This
4102          option is only used by interactive shells.
4103
4104     'cdable_vars'
4105          If this is set, an argument to the 'cd' builtin command that
4106          is not a directory is assumed to be the name of a variable
4107          whose value is the directory to change to.
4108
4109     'cdspell'
4110          If set, minor errors in the spelling of a directory component
4111          in a 'cd' command will be corrected.  The errors checked for
4112          are transposed characters, a missing character, and a
4113          character too many.  If a correction is found, the corrected
4114          path is printed, and the command proceeds.  This option is
4115          only used by interactive shells.
4116
4117     'checkhash'
4118          If this is set, Bash checks that a command found in the hash
4119          table exists before trying to execute it.  If a hashed command
4120          no longer exists, a normal path search is performed.
4121
4122     'checkjobs'
4123          If set, Bash lists the status of any stopped and running jobs
4124          before exiting an interactive shell.  If any jobs are running,
4125          this causes the exit to be deferred until a second exit is
4126          attempted without an intervening command (*note Job
4127          Control::).  The shell always postpones exiting if any jobs
4128          are stopped.
4129
4130     'checkwinsize'
4131          If set, Bash checks the window size after each command and, if
4132          necessary, updates the values of 'LINES' and 'COLUMNS'.
4133
4134     'cmdhist'
4135          If set, Bash attempts to save all lines of a multiple-line
4136          command in the same history entry.  This allows easy
4137          re-editing of multi-line commands.
4138
4139     'compat31'
4140          If set, Bash changes its behavior to that of version 3.1 with
4141          respect to quoted arguments to the conditional command's '=~'
4142          operator and with respect to locale-specific string comparison
4143          when using the '[[' conditional command's '<' and '>'
4144          operators.  Bash versions prior to bash-4.1 use ASCII
4145          collation and strcmp(3); bash-4.1 and later use the current
4146          locale's collation sequence and strcoll(3).
4147
4148     'compat32'
4149          If set, Bash changes its behavior to that of version 3.2 with
4150          respect to locale-specific string comparison when using the
4151          '[[' conditional command's '<' and '>' operators (see previous
4152          item) and the effect of interrupting a command list.  Bash
4153          versions 3.2 and earlier continue with the next command in the
4154          list after one terminates due to an interrupt.
4155
4156     'compat40'
4157          If set, Bash changes its behavior to that of version 4.0 with
4158          respect to locale-specific string comparison when using the
4159          '[[' conditional command's '<' and '>' operators (see
4160          description of 'compat31') and the effect of interrupting a
4161          command list.  Bash versions 4.0 and later interrupt the list
4162          as if the shell received the interrupt; previous versions
4163          continue with the next command in the list.
4164
4165     'compat41'
4166          If set, Bash, when in POSIX mode, treats a single quote in a
4167          double-quoted parameter expansion as a special character.  The
4168          single quotes must match (an even number) and the characters
4169          between the single quotes are considered quoted.  This is the
4170          behavior of POSIX mode through version 4.1.  The default Bash
4171          behavior remains as in previous versions.
4172
4173     'compat42'
4174          If set, Bash does not process the replacement string in the
4175          pattern substitution word expansion using quote removal.
4176
4177     'compat43'
4178          If set, Bash does not print a warning message if an attempt is
4179          made to use a quoted compound array assignment as an argument
4180          to 'declare', makes word expansion errors non-fatal errors
4181          that cause the current command to fail (the default behavior
4182          is to make them fatal errors that cause the shell to exit),
4183          and does not reset the loop state when a shell function is
4184          executed (this allows 'break' or 'continue' in a shell
4185          function to affect loops in the caller's context).
4186
4187     'complete_fullquote'
4188          If set, Bash quotes all shell metacharacters in filenames and
4189          directory names when performing completion.  If not set, Bash
4190          removes metacharacters such as the dollar sign from the set of
4191          characters that will be quoted in completed filenames when
4192          these metacharacters appear in shell variable references in
4193          words to be completed.  This means that dollar signs in
4194          variable names that expand to directories will not be quoted;
4195          however, any dollar signs appearing in filenames will not be
4196          quoted, either.  This is active only when bash is using
4197          backslashes to quote completed filenames.  This variable is
4198          set by default, which is the default Bash behavior in versions
4199          through 4.2.
4200
4201     'direxpand'
4202          If set, Bash replaces directory names with the results of word
4203          expansion when performing filename completion.  This changes
4204          the contents of the readline editing buffer.  If not set, Bash
4205          attempts to preserve what the user typed.
4206
4207     'dirspell'
4208          If set, Bash attempts spelling correction on directory names
4209          during word completion if the directory name initially
4210          supplied does not exist.
4211
4212     'dotglob'
4213          If set, Bash includes filenames beginning with a '.'  in the
4214          results of filename expansion.
4215
4216     'execfail'
4217          If this is set, a non-interactive shell will not exit if it
4218          cannot execute the file specified as an argument to the 'exec'
4219          builtin command.  An interactive shell does not exit if 'exec'
4220          fails.
4221
4222     'expand_aliases'
4223          If set, aliases are expanded as described below under Aliases,
4224          *note Aliases::.  This option is enabled by default for
4225          interactive shells.
4226
4227     'extdebug'
4228          If set at shell invocation, arrange to execute the debugger
4229          profile before the shell starts, identical to the '--debugger'
4230          option.  If set after invocation, behavior intended for use by
4231          debuggers is enabled:
4232
4233            1. The '-F' option to the 'declare' builtin (*note Bash
4234               Builtins::) displays the source file name and line number
4235               corresponding to each function name supplied as an
4236               argument.
4237
4238            2. If the command run by the 'DEBUG' trap returns a non-zero
4239               value, the next command is skipped and not executed.
4240
4241            3. If the command run by the 'DEBUG' trap returns a value of
4242               2, and the shell is executing in a subroutine (a shell
4243               function or a shell script executed by the '.' or
4244               'source' builtins), the shell simulates a call to
4245               'return'.
4246
4247            4. 'BASH_ARGC' and 'BASH_ARGV' are updated as described in
4248               their descriptions (*note Bash Variables::).
4249
4250            5. Function tracing is enabled: command substitution, shell
4251               functions, and subshells invoked with '( COMMAND )'
4252               inherit the 'DEBUG' and 'RETURN' traps.
4253
4254            6. Error tracing is enabled: command substitution, shell
4255               functions, and subshells invoked with '( COMMAND )'
4256               inherit the 'ERR' trap.
4257
4258     'extglob'
4259          If set, the extended pattern matching features described above
4260          (*note Pattern Matching::) are enabled.
4261
4262     'extquote'
4263          If set, '$'STRING'' and '$"STRING"' quoting is performed
4264          within '${PARAMETER}' expansions enclosed in double quotes.
4265          This option is enabled by default.
4266
4267     'failglob'
4268          If set, patterns which fail to match filenames during filename
4269          expansion result in an expansion error.
4270
4271     'force_fignore'
4272          If set, the suffixes specified by the 'FIGNORE' shell variable
4273          cause words to be ignored when performing word completion even
4274          if the ignored words are the only possible completions.  *Note
4275          Bash Variables::, for a description of 'FIGNORE'.  This option
4276          is enabled by default.
4277
4278     'globasciiranges'
4279          If set, range expressions used in pattern matching bracket
4280          expressions (*note Pattern Matching::) behave as if in the
4281          traditional C locale when performing comparisons.  That is,
4282          the current locale's collating sequence is not taken into
4283          account, so 'b' will not collate between 'A' and 'B', and
4284          upper-case and lower-case ASCII characters will collate
4285          together.
4286
4287     'globstar'
4288          If set, the pattern '**' used in a filename expansion context
4289          will match all files and zero or more directories and
4290          subdirectories.  If the pattern is followed by a '/', only
4291          directories and subdirectories match.
4292
4293     'gnu_errfmt'
4294          If set, shell error messages are written in the standard GNU
4295          error message format.
4296
4297     'histappend'
4298          If set, the history list is appended to the file named by the
4299          value of the 'HISTFILE' variable when the shell exits, rather
4300          than overwriting the file.
4301
4302     'histreedit'
4303          If set, and Readline is being used, a user is given the
4304          opportunity to re-edit a failed history substitution.
4305
4306     'histverify'
4307          If set, and Readline is being used, the results of history
4308          substitution are not immediately passed to the shell parser.
4309          Instead, the resulting line is loaded into the Readline
4310          editing buffer, allowing further modification.
4311
4312     'hostcomplete'
4313          If set, and Readline is being used, Bash will attempt to
4314          perform hostname completion when a word containing a '@' is
4315          being completed (*note Commands For Completion::).  This
4316          option is enabled by default.
4317
4318     'huponexit'
4319          If set, Bash will send 'SIGHUP' to all jobs when an
4320          interactive login shell exits (*note Signals::).
4321
4322     'inherit_errexit'
4323          If set, command substitution inherits the value of the
4324          'errexit' option, instead of unsetting it in the subshell
4325          environment.  This option is enabled when POSIX mode is
4326          enabled.
4327
4328     'interactive_comments'
4329          Allow a word beginning with '#' to cause that word and all
4330          remaining characters on that line to be ignored in an
4331          interactive shell.  This option is enabled by default.
4332
4333     'lastpipe'
4334          If set, and job control is not active, the shell runs the last
4335          command of a pipeline not executed in the background in the
4336          current shell environment.
4337
4338     'lithist'
4339          If enabled, and the 'cmdhist' option is enabled, multi-line
4340          commands are saved to the history with embedded newlines
4341          rather than using semicolon separators where possible.
4342
4343     'login_shell'
4344          The shell sets this option if it is started as a login shell
4345          (*note Invoking Bash::).  The value may not be changed.
4346
4347     'mailwarn'
4348          If set, and a file that Bash is checking for mail has been
4349          accessed since the last time it was checked, the message '"The
4350          mail in MAILFILE has been read"' is displayed.
4351
4352     'no_empty_cmd_completion'
4353          If set, and Readline is being used, Bash will not attempt to
4354          search the 'PATH' for possible completions when completion is
4355          attempted on an empty line.
4356
4357     'nocaseglob'
4358          If set, Bash matches filenames in a case-insensitive fashion
4359          when performing filename expansion.
4360
4361     'nocasematch'
4362          If set, Bash matches patterns in a case-insensitive fashion
4363          when performing matching while executing 'case' or '[['
4364          conditional commands, when performing pattern substitution
4365          word expansions, or when filtering possible completions as
4366          part of programmable completion.
4367
4368     'nullglob'
4369          If set, Bash allows filename patterns which match no files to
4370          expand to a null string, rather than themselves.
4371
4372     'progcomp'
4373          If set, the programmable completion facilities (*note
4374          Programmable Completion::) are enabled.  This option is
4375          enabled by default.
4376
4377     'promptvars'
4378          If set, prompt strings undergo parameter expansion, command
4379          substitution, arithmetic expansion, and quote removal after
4380          being expanded as described below (*note Controlling the
4381          Prompt::).  This option is enabled by default.
4382
4383     'restricted_shell'
4384          The shell sets this option if it is started in restricted mode
4385          (*note The Restricted Shell::).  The value may not be changed.
4386          This is not reset when the startup files are executed,
4387          allowing the startup files to discover whether or not a shell
4388          is restricted.
4389
4390     'shift_verbose'
4391          If this is set, the 'shift' builtin prints an error message
4392          when the shift count exceeds the number of positional
4393          parameters.
4394
4395     'sourcepath'
4396          If set, the 'source' builtin uses the value of 'PATH' to find
4397          the directory containing the file supplied as an argument.
4398          This option is enabled by default.
4399
4400     'xpg_echo'
4401          If set, the 'echo' builtin expands backslash-escape sequences
4402          by default.
4403
4404     The return status when listing options is zero if all OPTNAMES are
4405     enabled, non-zero otherwise.  When setting or unsetting options,
4406     the return status is zero unless an OPTNAME is not a valid shell
4407     option.
4408
44094.4 Special Builtins
4410====================
4411
4412For historical reasons, the POSIX standard has classified several
4413builtin commands as _special_.  When Bash is executing in POSIX mode,
4414the special builtins differ from other builtin commands in three
4415respects:
4416
4417  1. Special builtins are found before shell functions during command
4418     lookup.
4419
4420  2. If a special builtin returns an error status, a non-interactive
4421     shell exits.
4422
4423  3. Assignment statements preceding the command stay in effect in the
4424     shell environment after the command completes.
4425
4426   When Bash is not executing in POSIX mode, these builtins behave no
4427differently than the rest of the Bash builtin commands.  The Bash POSIX
4428mode is described in *note Bash POSIX Mode::.
4429
4430   These are the POSIX special builtins:
4431     break : . continue eval exec exit export readonly return set
4432     shift trap unset
4433
44345 Shell Variables
4435*****************
4436
4437This chapter describes the shell variables that Bash uses.  Bash
4438automatically assigns default values to a number of variables.
4439
44405.1 Bourne Shell Variables
4441==========================
4442
4443Bash uses certain shell variables in the same way as the Bourne shell.
4444In some cases, Bash assigns a default value to the variable.
4445
4446'CDPATH'
4447     A colon-separated list of directories used as a search path for the
4448     'cd' builtin command.
4449
4450'HOME'
4451     The current user's home directory; the default for the 'cd' builtin
4452     command.  The value of this variable is also used by tilde
4453     expansion (*note Tilde Expansion::).
4454
4455'IFS'
4456     A list of characters that separate fields; used when the shell
4457     splits words as part of expansion.
4458
4459'MAIL'
4460     If this parameter is set to a filename or directory name and the
4461     'MAILPATH' variable is not set, Bash informs the user of the
4462     arrival of mail in the specified file or Maildir-format directory.
4463
4464'MAILPATH'
4465     A colon-separated list of filenames which the shell periodically
4466     checks for new mail.  Each list entry can specify the message that
4467     is printed when new mail arrives in the mail file by separating the
4468     filename from the message with a '?'.  When used in the text of the
4469     message, '$_' expands to the name of the current mail file.
4470
4471'OPTARG'
4472     The value of the last option argument processed by the 'getopts'
4473     builtin.
4474
4475'OPTIND'
4476     The index of the last option argument processed by the 'getopts'
4477     builtin.
4478
4479'PATH'
4480     A colon-separated list of directories in which the shell looks for
4481     commands.  A zero-length (null) directory name in the value of
4482     'PATH' indicates the current directory.  A null directory name may
4483     appear as two adjacent colons, or as an initial or trailing colon.
4484
4485'PS1'
4486     The primary prompt string.  The default value is '\s-\v\$ '.  *Note
4487     Controlling the Prompt::, for the complete list of escape sequences
4488     that are expanded before 'PS1' is displayed.
4489
4490'PS2'
4491     The secondary prompt string.  The default value is '> '.
4492
44935.2 Bash Variables
4494==================
4495
4496These variables are set or used by Bash, but other shells do not
4497normally treat them specially.
4498
4499   A few variables used by Bash are described in different chapters:
4500variables for controlling the job control facilities (*note Job Control
4501Variables::).
4502
4503'BASH'
4504     The full pathname used to execute the current instance of Bash.
4505
4506'BASHOPTS'
4507     A colon-separated list of enabled shell options.  Each word in the
4508     list is a valid argument for the '-s' option to the 'shopt' builtin
4509     command (*note The Shopt Builtin::).  The options appearing in
4510     'BASHOPTS' are those reported as 'on' by 'shopt'.  If this variable
4511     is in the environment when Bash starts up, each shell option in the
4512     list will be enabled before reading any startup files.  This
4513     variable is readonly.
4514
4515'BASHPID'
4516     Expands to the process ID of the current Bash process.  This
4517     differs from '$$' under certain circumstances, such as subshells
4518     that do not require Bash to be re-initialized.
4519
4520'BASH_ALIASES'
4521     An associative array variable whose members correspond to the
4522     internal list of aliases as maintained by the 'alias' builtin.
4523     (*note Bourne Shell Builtins::).  Elements added to this array
4524     appear in the alias list; however, unsetting array elements
4525     currently does not cause aliases to be removed from the alias list.
4526     If 'BASH_ALIASES' is unset, it loses its special properties, even
4527     if it is subsequently reset.
4528
4529'BASH_ARGC'
4530     An array variable whose values are the number of parameters in each
4531     frame of the current bash execution call stack.  The number of
4532     parameters to the current subroutine (shell function or script
4533     executed with '.' or 'source') is at the top of the stack.  When a
4534     subroutine is executed, the number of parameters passed is pushed
4535     onto 'BASH_ARGC'.  The shell sets 'BASH_ARGC' only when in extended
4536     debugging mode (see *note The Shopt Builtin:: for a description of
4537     the 'extdebug' option to the 'shopt' builtin).
4538
4539'BASH_ARGV'
4540     An array variable containing all of the parameters in the current
4541     bash execution call stack.  The final parameter of the last
4542     subroutine call is at the top of the stack; the first parameter of
4543     the initial call is at the bottom.  When a subroutine is executed,
4544     the parameters supplied are pushed onto 'BASH_ARGV'.  The shell
4545     sets 'BASH_ARGV' only when in extended debugging mode (see *note
4546     The Shopt Builtin:: for a description of the 'extdebug' option to
4547     the 'shopt' builtin).
4548
4549'BASH_CMDS'
4550     An associative array variable whose members correspond to the
4551     internal hash table of commands as maintained by the 'hash' builtin
4552     (*note Bourne Shell Builtins::).  Elements added to this array
4553     appear in the hash table; however, unsetting array elements
4554     currently does not cause command names to be removed from the hash
4555     table.  If 'BASH_CMDS' is unset, it loses its special properties,
4556     even if it is subsequently reset.
4557
4558'BASH_COMMAND'
4559     The command currently being executed or about to be executed,
4560     unless the shell is executing a command as the result of a trap, in
4561     which case it is the command executing at the time of the trap.
4562
4563'BASH_COMPAT'
4564     The value is used to set the shell's compatibility level.  *Note
4565     The Shopt Builtin::, for a description of the various compatibility
4566     levels and their effects.  The value may be a decimal number (e.g.,
4567     4.2) or an integer (e.g., 42) corresponding to the desired
4568     compatibility level.  If 'BASH_COMPAT' is unset or set to the empty
4569     string, the compatibility level is set to the default for the
4570     current version.  If 'BASH_COMPAT' is set to a value that is not
4571     one of the valid compatibility levels, the shell prints an error
4572     message and sets the compatibility level to the default for the
4573     current version.  The valid compatibility levels correspond to the
4574     compatibility options accepted by the 'shopt' builtin described
4575     above (for example, COMPAT42 means that 4.2 and 42 are valid
4576     values).  The current version is also a valid value.
4577
4578'BASH_ENV'
4579     If this variable is set when Bash is invoked to execute a shell
4580     script, its value is expanded and used as the name of a startup
4581     file to read before executing the script.  *Note Bash Startup
4582     Files::.
4583
4584'BASH_EXECUTION_STRING'
4585     The command argument to the '-c' invocation option.
4586
4587'BASH_LINENO'
4588     An array variable whose members are the line numbers in source
4589     files where each corresponding member of FUNCNAME was invoked.
4590     '${BASH_LINENO[$i]}' is the line number in the source file
4591     ('${BASH_SOURCE[$i+1]}') where '${FUNCNAME[$i]}' was called (or
4592     '${BASH_LINENO[$i-1]}' if referenced within another shell
4593     function).  Use 'LINENO' to obtain the current line number.
4594
4595'BASH_LOADABLES_PATH'
4596     A colon-separated list of directories in which the shell looks for
4597     dynamically loadable builtins specified by the 'enable' command.
4598
4599'BASH_REMATCH'
4600     An array variable whose members are assigned by the '=~' binary
4601     operator to the '[[' conditional command (*note Conditional
4602     Constructs::).  The element with index 0 is the portion of the
4603     string matching the entire regular expression.  The element with
4604     index N is the portion of the string matching the Nth parenthesized
4605     subexpression.  This variable is read-only.
4606
4607'BASH_SOURCE'
4608     An array variable whose members are the source filenames where the
4609     corresponding shell function names in the 'FUNCNAME' array variable
4610     are defined.  The shell function '${FUNCNAME[$i]}' is defined in
4611     the file '${BASH_SOURCE[$i]}' and called from
4612     '${BASH_SOURCE[$i+1]}'
4613
4614'BASH_SUBSHELL'
4615     Incremented by one within each subshell or subshell environment
4616     when the shell begins executing in that environment.  The initial
4617     value is 0.
4618
4619'BASH_VERSINFO'
4620     A readonly array variable (*note Arrays::) whose members hold
4621     version information for this instance of Bash.  The values assigned
4622     to the array members are as follows:
4623
4624     'BASH_VERSINFO[0]'
4625          The major version number (the RELEASE).
4626
4627     'BASH_VERSINFO[1]'
4628          The minor version number (the VERSION).
4629
4630     'BASH_VERSINFO[2]'
4631          The patch level.
4632
4633     'BASH_VERSINFO[3]'
4634          The build version.
4635
4636     'BASH_VERSINFO[4]'
4637          The release status (e.g., BETA1).
4638
4639     'BASH_VERSINFO[5]'
4640          The value of 'MACHTYPE'.
4641
4642'BASH_VERSION'
4643     The version number of the current instance of Bash.
4644
4645'BASH_XTRACEFD'
4646     If set to an integer corresponding to a valid file descriptor, Bash
4647     will write the trace output generated when 'set -x' is enabled to
4648     that file descriptor.  This allows tracing output to be separated
4649     from diagnostic and error messages.  The file descriptor is closed
4650     when 'BASH_XTRACEFD' is unset or assigned a new value.  Unsetting
4651     'BASH_XTRACEFD' or assigning it the empty string causes the trace
4652     output to be sent to the standard error.  Note that setting
4653     'BASH_XTRACEFD' to 2 (the standard error file descriptor) and then
4654     unsetting it will result in the standard error being closed.
4655
4656'CHILD_MAX'
4657     Set the number of exited child status values for the shell to
4658     remember.  Bash will not allow this value to be decreased below a
4659     POSIX-mandated minimum, and there is a maximum value (currently
4660     8192) that this may not exceed.  The minimum value is
4661     system-dependent.
4662
4663'COLUMNS'
4664     Used by the 'select' command to determine the terminal width when
4665     printing selection lists.  Automatically set if the 'checkwinsize'
4666     option is enabled (*note The Shopt Builtin::), or in an interactive
4667     shell upon receipt of a 'SIGWINCH'.
4668
4669'COMP_CWORD'
4670     An index into '${COMP_WORDS}' of the word containing the current
4671     cursor position.  This variable is available only in shell
4672     functions invoked by the programmable completion facilities (*note
4673     Programmable Completion::).
4674
4675'COMP_LINE'
4676     The current command line.  This variable is available only in shell
4677     functions and external commands invoked by the programmable
4678     completion facilities (*note Programmable Completion::).
4679
4680'COMP_POINT'
4681     The index of the current cursor position relative to the beginning
4682     of the current command.  If the current cursor position is at the
4683     end of the current command, the value of this variable is equal to
4684     '${#COMP_LINE}'.  This variable is available only in shell
4685     functions and external commands invoked by the programmable
4686     completion facilities (*note Programmable Completion::).
4687
4688'COMP_TYPE'
4689     Set to an integer value corresponding to the type of completion
4690     attempted that caused a completion function to be called: TAB, for
4691     normal completion, '?', for listing completions after successive
4692     tabs, '!', for listing alternatives on partial word completion,
4693     '@', to list completions if the word is not unmodified, or '%', for
4694     menu completion.  This variable is available only in shell
4695     functions and external commands invoked by the programmable
4696     completion facilities (*note Programmable Completion::).
4697
4698'COMP_KEY'
4699     The key (or final key of a key sequence) used to invoke the current
4700     completion function.
4701
4702'COMP_WORDBREAKS'
4703     The set of characters that the Readline library treats as word
4704     separators when performing word completion.  If 'COMP_WORDBREAKS'
4705     is unset, it loses its special properties, even if it is
4706     subsequently reset.
4707
4708'COMP_WORDS'
4709     An array variable consisting of the individual words in the current
4710     command line.  The line is split into words as Readline would split
4711     it, using 'COMP_WORDBREAKS' as described above.  This variable is
4712     available only in shell functions invoked by the programmable
4713     completion facilities (*note Programmable Completion::).
4714
4715'COMPREPLY'
4716     An array variable from which Bash reads the possible completions
4717     generated by a shell function invoked by the programmable
4718     completion facility (*note Programmable Completion::).  Each array
4719     element contains one possible completion.
4720
4721'COPROC'
4722     An array variable created to hold the file descriptors for output
4723     from and input to an unnamed coprocess (*note Coprocesses::).
4724
4725'DIRSTACK'
4726     An array variable containing the current contents of the directory
4727     stack.  Directories appear in the stack in the order they are
4728     displayed by the 'dirs' builtin.  Assigning to members of this
4729     array variable may be used to modify directories already in the
4730     stack, but the 'pushd' and 'popd' builtins must be used to add and
4731     remove directories.  Assignment to this variable will not change
4732     the current directory.  If 'DIRSTACK' is unset, it loses its
4733     special properties, even if it is subsequently reset.
4734
4735'EMACS'
4736     If Bash finds this variable in the environment when the shell
4737     starts with value 't', it assumes that the shell is running in an
4738     Emacs shell buffer and disables line editing.
4739
4740'ENV'
4741     Similar to 'BASH_ENV'; used when the shell is invoked in POSIX Mode
4742     (*note Bash POSIX Mode::).
4743
4744'EUID'
4745     The numeric effective user id of the current user.  This variable
4746     is readonly.
4747
4748'EXECIGNORE'
4749     A colon-separated list of shell patterns (*note Pattern Matching::)
4750     defining the list of filenames to be ignored by command search
4751     using 'PATH'.  Files whose full pathnames match one of these
4752     patterns are not considered executable files for the purposes of
4753     completion and command execution via 'PATH' lookup.  This does not
4754     affect the behavior of the '[', 'test', and '[[' commands.  Full
4755     pathnames in the command hash table are not subject to
4756     'EXECIGNORE'.  Use this variable to ignore shared library files
4757     that have the executable bit set, but are not executable files.
4758     The pattern matching honors the setting of the 'extglob' shell
4759     option.
4760
4761'FCEDIT'
4762     The editor used as a default by the '-e' option to the 'fc' builtin
4763     command.
4764
4765'FIGNORE'
4766     A colon-separated list of suffixes to ignore when performing
4767     filename completion.  A filename whose suffix matches one of the
4768     entries in 'FIGNORE' is excluded from the list of matched
4769     filenames.  A sample value is '.o:~'
4770
4771'FUNCNAME'
4772     An array variable containing the names of all shell functions
4773     currently in the execution call stack.  The element with index 0 is
4774     the name of any currently-executing shell function.  The
4775     bottom-most element (the one with the highest index) is '"main"'.
4776     This variable exists only when a shell function is executing.
4777     Assignments to 'FUNCNAME' have no effect.  If 'FUNCNAME' is unset,
4778     it loses its special properties, even if it is subsequently reset.
4779
4780     This variable can be used with 'BASH_LINENO' and 'BASH_SOURCE'.
4781     Each element of 'FUNCNAME' has corresponding elements in
4782     'BASH_LINENO' and 'BASH_SOURCE' to describe the call stack.  For
4783     instance, '${FUNCNAME[$i]}' was called from the file
4784     '${BASH_SOURCE[$i+1]}' at line number '${BASH_LINENO[$i]}'.  The
4785     'caller' builtin displays the current call stack using this
4786     information.
4787
4788'FUNCNEST'
4789     If set to a numeric value greater than 0, defines a maximum
4790     function nesting level.  Function invocations that exceed this
4791     nesting level will cause the current command to abort.
4792
4793'GLOBIGNORE'
4794     A colon-separated list of patterns defining the set of filenames to
4795     be ignored by filename expansion.  If a filename matched by a
4796     filename expansion pattern also matches one of the patterns in
4797     'GLOBIGNORE', it is removed from the list of matches.  The pattern
4798     matching honors the setting of the 'extglob' shell option.
4799
4800'GROUPS'
4801     An array variable containing the list of groups of which the
4802     current user is a member.  Assignments to 'GROUPS' have no effect.
4803     If 'GROUPS' is unset, it loses its special properties, even if it
4804     is subsequently reset.
4805
4806'histchars'
4807     Up to three characters which control history expansion, quick
4808     substitution, and tokenization (*note History Interaction::).  The
4809     first character is the HISTORY EXPANSION character, that is, the
4810     character which signifies the start of a history expansion,
4811     normally '!'.  The second character is the character which
4812     signifies 'quick substitution' when seen as the first character on
4813     a line, normally '^'.  The optional third character is the
4814     character which indicates that the remainder of the line is a
4815     comment when found as the first character of a word, usually '#'.
4816     The history comment character causes history substitution to be
4817     skipped for the remaining words on the line.  It does not
4818     necessarily cause the shell parser to treat the rest of the line as
4819     a comment.
4820
4821'HISTCMD'
4822     The history number, or index in the history list, of the current
4823     command.  If 'HISTCMD' is unset, it loses its special properties,
4824     even if it is subsequently reset.
4825
4826'HISTCONTROL'
4827     A colon-separated list of values controlling how commands are saved
4828     on the history list.  If the list of values includes 'ignorespace',
4829     lines which begin with a space character are not saved in the
4830     history list.  A value of 'ignoredups' causes lines which match the
4831     previous history entry to not be saved.  A value of 'ignoreboth' is
4832     shorthand for 'ignorespace' and 'ignoredups'.  A value of
4833     'erasedups' causes all previous lines matching the current line to
4834     be removed from the history list before that line is saved.  Any
4835     value not in the above list is ignored.  If 'HISTCONTROL' is unset,
4836     or does not include a valid value, all lines read by the shell
4837     parser are saved on the history list, subject to the value of
4838     'HISTIGNORE'.  The second and subsequent lines of a multi-line
4839     compound command are not tested, and are added to the history
4840     regardless of the value of 'HISTCONTROL'.
4841
4842'HISTFILE'
4843     The name of the file to which the command history is saved.  The
4844     default value is '~/.bash_history'.
4845
4846'HISTFILESIZE'
4847     The maximum number of lines contained in the history file.  When
4848     this variable is assigned a value, the history file is truncated,
4849     if necessary, to contain no more than that number of lines by
4850     removing the oldest entries.  The history file is also truncated to
4851     this size after writing it when a shell exits.  If the value is 0,
4852     the history file is truncated to zero size.  Non-numeric values and
4853     numeric values less than zero inhibit truncation.  The shell sets
4854     the default value to the value of 'HISTSIZE' after reading any
4855     startup files.
4856
4857'HISTIGNORE'
4858     A colon-separated list of patterns used to decide which command
4859     lines should be saved on the history list.  Each pattern is
4860     anchored at the beginning of the line and must match the complete
4861     line (no implicit '*' is appended).  Each pattern is tested against
4862     the line after the checks specified by 'HISTCONTROL' are applied.
4863     In addition to the normal shell pattern matching characters, '&'
4864     matches the previous history line.  '&' may be escaped using a
4865     backslash; the backslash is removed before attempting a match.  The
4866     second and subsequent lines of a multi-line compound command are
4867     not tested, and are added to the history regardless of the value of
4868     'HISTIGNORE'.  The pattern matching honors the setting of the
4869     'extglob' shell option.
4870
4871     'HISTIGNORE' subsumes the function of 'HISTCONTROL'.  A pattern of
4872     '&' is identical to 'ignoredups', and a pattern of '[ ]*' is
4873     identical to 'ignorespace'.  Combining these two patterns,
4874     separating them with a colon, provides the functionality of
4875     'ignoreboth'.
4876
4877'HISTSIZE'
4878     The maximum number of commands to remember on the history list.  If
4879     the value is 0, commands are not saved in the history list.
4880     Numeric values less than zero result in every command being saved
4881     on the history list (there is no limit).  The shell sets the
4882     default value to 500 after reading any startup files.
4883
4884'HISTTIMEFORMAT'
4885     If this variable is set and not null, its value is used as a format
4886     string for STRFTIME to print the time stamp associated with each
4887     history entry displayed by the 'history' builtin.  If this variable
4888     is set, time stamps are written to the history file so they may be
4889     preserved across shell sessions.  This uses the history comment
4890     character to distinguish timestamps from other history lines.
4891
4892'HOSTFILE'
4893     Contains the name of a file in the same format as '/etc/hosts' that
4894     should be read when the shell needs to complete a hostname.  The
4895     list of possible hostname completions may be changed while the
4896     shell is running; the next time hostname completion is attempted
4897     after the value is changed, Bash adds the contents of the new file
4898     to the existing list.  If 'HOSTFILE' is set, but has no value, or
4899     does not name a readable file, Bash attempts to read '/etc/hosts'
4900     to obtain the list of possible hostname completions.  When
4901     'HOSTFILE' is unset, the hostname list is cleared.
4902
4903'HOSTNAME'
4904     The name of the current host.
4905
4906'HOSTTYPE'
4907     A string describing the machine Bash is running on.
4908
4909'IGNOREEOF'
4910     Controls the action of the shell on receipt of an 'EOF' character
4911     as the sole input.  If set, the value denotes the number of
4912     consecutive 'EOF' characters that can be read as the first
4913     character on an input line before the shell will exit.  If the
4914     variable exists but does not have a numeric value (or has no value)
4915     then the default is 10.  If the variable does not exist, then 'EOF'
4916     signifies the end of input to the shell.  This is only in effect
4917     for interactive shells.
4918
4919'INPUTRC'
4920     The name of the Readline initialization file, overriding the
4921     default of '~/.inputrc'.
4922
4923'LANG'
4924     Used to determine the locale category for any category not
4925     specifically selected with a variable starting with 'LC_'.
4926
4927'LC_ALL'
4928     This variable overrides the value of 'LANG' and any other 'LC_'
4929     variable specifying a locale category.
4930
4931'LC_COLLATE'
4932     This variable determines the collation order used when sorting the
4933     results of filename expansion, and determines the behavior of range
4934     expressions, equivalence classes, and collating sequences within
4935     filename expansion and pattern matching (*note Filename
4936     Expansion::).
4937
4938'LC_CTYPE'
4939     This variable determines the interpretation of characters and the
4940     behavior of character classes within filename expansion and pattern
4941     matching (*note Filename Expansion::).
4942
4943'LC_MESSAGES'
4944     This variable determines the locale used to translate double-quoted
4945     strings preceded by a '$' (*note Locale Translation::).
4946
4947'LC_NUMERIC'
4948     This variable determines the locale category used for number
4949     formatting.
4950
4951'LC_TIME'
4952     This variable determines the locale category used for data and time
4953     formatting.
4954
4955'LINENO'
4956     The line number in the script or shell function currently
4957     executing.
4958
4959'LINES'
4960     Used by the 'select' command to determine the column length for
4961     printing selection lists.  Automatically set if the 'checkwinsize'
4962     option is enabled (*note The Shopt Builtin::), or in an interactive
4963     shell upon receipt of a 'SIGWINCH'.
4964
4965'MACHTYPE'
4966     A string that fully describes the system type on which Bash is
4967     executing, in the standard GNU CPU-COMPANY-SYSTEM format.
4968
4969'MAILCHECK'
4970     How often (in seconds) that the shell should check for mail in the
4971     files specified in the 'MAILPATH' or 'MAIL' variables.  The default
4972     is 60 seconds.  When it is time to check for mail, the shell does
4973     so before displaying the primary prompt.  If this variable is
4974     unset, or set to a value that is not a number greater than or equal
4975     to zero, the shell disables mail checking.
4976
4977'MAPFILE'
4978     An array variable created to hold the text read by the 'mapfile'
4979     builtin when no variable name is supplied.
4980
4981'OLDPWD'
4982     The previous working directory as set by the 'cd' builtin.
4983
4984'OPTERR'
4985     If set to the value 1, Bash displays error messages generated by
4986     the 'getopts' builtin command.
4987
4988'OSTYPE'
4989     A string describing the operating system Bash is running on.
4990
4991'PIPESTATUS'
4992     An array variable (*note Arrays::) containing a list of exit status
4993     values from the processes in the most-recently-executed foreground
4994     pipeline (which may contain only a single command).
4995
4996'POSIXLY_CORRECT'
4997     If this variable is in the environment when Bash starts, the shell
4998     enters POSIX mode (*note Bash POSIX Mode::) before reading the
4999     startup files, as if the '--posix' invocation option had been
5000     supplied.  If it is set while the shell is running, Bash enables
5001     POSIX mode, as if the command
5002          set -o posix
5003     had been executed.
5004
5005'PPID'
5006     The process ID of the shell's parent process.  This variable is
5007     readonly.
5008
5009'PROMPT_COMMAND'
5010     If set, the value is interpreted as a command to execute before the
5011     printing of each primary prompt ('$PS1').
5012
5013'PROMPT_DIRTRIM'
5014     If set to a number greater than zero, the value is used as the
5015     number of trailing directory components to retain when expanding
5016     the '\w' and '\W' prompt string escapes (*note Controlling the
5017     Prompt::).  Characters removed are replaced with an ellipsis.
5018
5019'PS0'
5020     The value of this parameter is expanded like PS1 and displayed by
5021     interactive shells after reading a command and before the command
5022     is executed.
5023
5024'PS3'
5025     The value of this variable is used as the prompt for the 'select'
5026     command.  If this variable is not set, the 'select' command prompts
5027     with '#? '
5028
5029'PS4'
5030     The value is the prompt printed before the command line is echoed
5031     when the '-x' option is set (*note The Set Builtin::).  The first
5032     character of 'PS4' is replicated multiple times, as necessary, to
5033     indicate multiple levels of indirection.  The default is '+ '.
5034
5035'PWD'
5036     The current working directory as set by the 'cd' builtin.
5037
5038'RANDOM'
5039     Each time this parameter is referenced, a random integer between 0
5040     and 32767 is generated.  Assigning a value to this variable seeds
5041     the random number generator.
5042
5043'READLINE_LINE'
5044     The contents of the Readline line buffer, for use with 'bind -x'
5045     (*note Bash Builtins::).
5046
5047'READLINE_POINT'
5048     The position of the insertion point in the Readline line buffer,
5049     for use with 'bind -x' (*note Bash Builtins::).
5050
5051'REPLY'
5052     The default variable for the 'read' builtin.
5053
5054'SECONDS'
5055     This variable expands to the number of seconds since the shell was
5056     started.  Assignment to this variable resets the count to the value
5057     assigned, and the expanded value becomes the value assigned plus
5058     the number of seconds since the assignment.
5059
5060'SHELL'
5061     The full pathname to the shell is kept in this environment
5062     variable.  If it is not set when the shell starts, Bash assigns to
5063     it the full pathname of the current user's login shell.
5064
5065'SHELLOPTS'
5066     A colon-separated list of enabled shell options.  Each word in the
5067     list is a valid argument for the '-o' option to the 'set' builtin
5068     command (*note The Set Builtin::).  The options appearing in
5069     'SHELLOPTS' are those reported as 'on' by 'set -o'.  If this
5070     variable is in the environment when Bash starts up, each shell
5071     option in the list will be enabled before reading any startup
5072     files.  This variable is readonly.
5073
5074'SHLVL'
5075     Incremented by one each time a new instance of Bash is started.
5076     This is intended to be a count of how deeply your Bash shells are
5077     nested.
5078
5079'TIMEFORMAT'
5080     The value of this parameter is used as a format string specifying
5081     how the timing information for pipelines prefixed with the 'time'
5082     reserved word should be displayed.  The '%' character introduces an
5083     escape sequence that is expanded to a time value or other
5084     information.  The escape sequences and their meanings are as
5085     follows; the braces denote optional portions.
5086
5087     '%%'
5088          A literal '%'.
5089
5090     '%[P][l]R'
5091          The elapsed time in seconds.
5092
5093     '%[P][l]U'
5094          The number of CPU seconds spent in user mode.
5095
5096     '%[P][l]S'
5097          The number of CPU seconds spent in system mode.
5098
5099     '%P'
5100          The CPU percentage, computed as (%U + %S) / %R.
5101
5102     The optional P is a digit specifying the precision, the number of
5103     fractional digits after a decimal point.  A value of 0 causes no
5104     decimal point or fraction to be output.  At most three places after
5105     the decimal point may be specified; values of P greater than 3 are
5106     changed to 3.  If P is not specified, the value 3 is used.
5107
5108     The optional 'l' specifies a longer format, including minutes, of
5109     the form MMmSS.FFs.  The value of P determines whether or not the
5110     fraction is included.
5111
5112     If this variable is not set, Bash acts as if it had the value
5113          $'\nreal\t%3lR\nuser\t%3lU\nsys\t%3lS'
5114     If the value is null, no timing information is displayed.  A
5115     trailing newline is added when the format string is displayed.
5116
5117'TMOUT'
5118     If set to a value greater than zero, 'TMOUT' is treated as the
5119     default timeout for the 'read' builtin (*note Bash Builtins::).
5120     The 'select' command (*note Conditional Constructs::) terminates if
5121     input does not arrive after 'TMOUT' seconds when input is coming
5122     from a terminal.
5123
5124     In an interactive shell, the value is interpreted as the number of
5125     seconds to wait for a line of input after issuing the primary
5126     prompt.  Bash terminates after waiting for that number of seconds
5127     if a complete line of input does not arrive.
5128
5129'TMPDIR'
5130     If set, Bash uses its value as the name of a directory in which
5131     Bash creates temporary files for the shell's use.
5132
5133'UID'
5134     The numeric real user id of the current user.  This variable is
5135     readonly.
5136
51376 Bash Features
5138***************
5139
5140This chapter describes features unique to Bash.
5141
51426.1 Invoking Bash
5143=================
5144
5145     bash [long-opt] [-ir] [-abefhkmnptuvxdBCDHP] [-o OPTION] [-O SHOPT_OPTION] [ARGUMENT ...]
5146     bash [long-opt] [-abefhkmnptuvxdBCDHP] [-o OPTION] [-O SHOPT_OPTION] -c STRING [ARGUMENT ...]
5147     bash [long-opt] -s [-abefhkmnptuvxdBCDHP] [-o OPTION] [-O SHOPT_OPTION] [ARGUMENT ...]
5148
5149   All of the single-character options used with the 'set' builtin
5150(*note The Set Builtin::) can be used as options when the shell is
5151invoked.  In addition, there are several multi-character options that
5152you can use.  These options must appear on the command line before the
5153single-character options to be recognized.
5154
5155'--debugger'
5156     Arrange for the debugger profile to be executed before the shell
5157     starts.  Turns on extended debugging mode (see *note The Shopt
5158     Builtin:: for a description of the 'extdebug' option to the 'shopt'
5159     builtin).
5160
5161'--dump-po-strings'
5162     A list of all double-quoted strings preceded by '$' is printed on
5163     the standard output in the GNU 'gettext' PO (portable object) file
5164     format.  Equivalent to '-D' except for the output format.
5165
5166'--dump-strings'
5167     Equivalent to '-D'.
5168
5169'--help'
5170     Display a usage message on standard output and exit successfully.
5171
5172'--init-file FILENAME'
5173'--rcfile FILENAME'
5174     Execute commands from FILENAME (instead of '~/.bashrc') in an
5175     interactive shell.
5176
5177'--login'
5178     Equivalent to '-l'.
5179
5180'--noediting'
5181     Do not use the GNU Readline library (*note Command Line Editing::)
5182     to read command lines when the shell is interactive.
5183
5184'--noprofile'
5185     Don't load the system-wide startup file '/etc/profile' or any of
5186     the personal initialization files '~/.bash_profile',
5187     '~/.bash_login', or '~/.profile' when Bash is invoked as a login
5188     shell.
5189
5190'--norc'
5191     Don't read the '~/.bashrc' initialization file in an interactive
5192     shell.  This is on by default if the shell is invoked as 'sh'.
5193
5194'--posix'
5195     Change the behavior of Bash where the default operation differs
5196     from the POSIX standard to match the standard.  This is intended to
5197     make Bash behave as a strict superset of that standard.  *Note Bash
5198     POSIX Mode::, for a description of the Bash POSIX mode.
5199
5200'--restricted'
5201     Make the shell a restricted shell (*note The Restricted Shell::).
5202
5203'--verbose'
5204     Equivalent to '-v'.  Print shell input lines as they're read.
5205
5206'--version'
5207     Show version information for this instance of Bash on the standard
5208     output and exit successfully.
5209
5210   There are several single-character options that may be supplied at
5211invocation which are not available with the 'set' builtin.
5212
5213'-c'
5214     Read and execute commands from the first non-option argument
5215     COMMAND_STRING, then exit.  If there are arguments after the
5216     COMMAND_STRING, the first argument is assigned to '$0' and any
5217     remaining arguments are assigned to the positional parameters.  The
5218     assignment to '$0' sets the name of the shell, which is used in
5219     warning and error messages.
5220
5221'-i'
5222     Force the shell to run interactively.  Interactive shells are
5223     described in *note Interactive Shells::.
5224
5225'-l'
5226     Make this shell act as if it had been directly invoked by login.
5227     When the shell is interactive, this is equivalent to starting a
5228     login shell with 'exec -l bash'.  When the shell is not
5229     interactive, the login shell startup files will be executed.  'exec
5230     bash -l' or 'exec bash --login' will replace the current shell with
5231     a Bash login shell.  *Note Bash Startup Files::, for a description
5232     of the special behavior of a login shell.
5233
5234'-r'
5235     Make the shell a restricted shell (*note The Restricted Shell::).
5236
5237'-s'
5238     If this option is present, or if no arguments remain after option
5239     processing, then commands are read from the standard input.  This
5240     option allows the positional parameters to be set when invoking an
5241     interactive shell.
5242
5243'-D'
5244     A list of all double-quoted strings preceded by '$' is printed on
5245     the standard output.  These are the strings that are subject to
5246     language translation when the current locale is not 'C' or 'POSIX'
5247     (*note Locale Translation::).  This implies the '-n' option; no
5248     commands will be executed.
5249
5250'[-+]O [SHOPT_OPTION]'
5251     SHOPT_OPTION is one of the shell options accepted by the 'shopt'
5252     builtin (*note The Shopt Builtin::).  If SHOPT_OPTION is present,
5253     '-O' sets the value of that option; '+O' unsets it.  If
5254     SHOPT_OPTION is not supplied, the names and values of the shell
5255     options accepted by 'shopt' are printed on the standard output.  If
5256     the invocation option is '+O', the output is displayed in a format
5257     that may be reused as input.
5258
5259'--'
5260     A '--' signals the end of options and disables further option
5261     processing.  Any arguments after the '--' are treated as filenames
5262     and arguments.
5263
5264   A _login_ shell is one whose first character of argument zero is '-',
5265or one invoked with the '--login' option.
5266
5267   An _interactive_ shell is one started without non-option arguments,
5268unless '-s' is specified, without specifying the '-c' option, and whose
5269input and output are both connected to terminals (as determined by
5270'isatty(3)'), or one started with the '-i' option.  *Note Interactive
5271Shells::, for more information.
5272
5273   If arguments remain after option processing, and neither the '-c' nor
5274the '-s' option has been supplied, the first argument is assumed to be
5275the name of a file containing shell commands (*note Shell Scripts::).
5276When Bash is invoked in this fashion, '$0' is set to the name of the
5277file, and the positional parameters are set to the remaining arguments.
5278Bash reads and executes commands from this file, then exits.  Bash's
5279exit status is the exit status of the last command executed in the
5280script.  If no commands are executed, the exit status is 0.
5281
52826.2 Bash Startup Files
5283======================
5284
5285This section describes how Bash executes its startup files.  If any of
5286the files exist but cannot be read, Bash reports an error.  Tildes are
5287expanded in filenames as described above under Tilde Expansion (*note
5288Tilde Expansion::).
5289
5290   Interactive shells are described in *note Interactive Shells::.
5291
5292Invoked as an interactive login shell, or with '--login'
5293........................................................
5294
5295When Bash is invoked as an interactive login shell, or as a
5296non-interactive shell with the '--login' option, it first reads and
5297executes commands from the file '/etc/profile', if that file exists.
5298After reading that file, it looks for '~/.bash_profile',
5299'~/.bash_login', and '~/.profile', in that order, and reads and executes
5300commands from the first one that exists and is readable.  The
5301'--noprofile' option may be used when the shell is started to inhibit
5302this behavior.
5303
5304   When an interactive login shell exits, or a non-interactive login
5305shell executes the 'exit' builtin command, Bash reads and executes
5306commands from the file '~/.bash_logout', if it exists.
5307
5308Invoked as an interactive non-login shell
5309.........................................
5310
5311When an interactive shell that is not a login shell is started, Bash
5312reads and executes commands from '~/.bashrc', if that file exists.  This
5313may be inhibited by using the '--norc' option.  The '--rcfile FILE'
5314option will force Bash to read and execute commands from FILE instead of
5315'~/.bashrc'.
5316
5317   So, typically, your '~/.bash_profile' contains the line
5318     if [ -f ~/.bashrc ]; then . ~/.bashrc; fi
5319after (or before) any login-specific initializations.
5320
5321Invoked non-interactively
5322.........................
5323
5324When Bash is started non-interactively, to run a shell script, for
5325example, it looks for the variable 'BASH_ENV' in the environment,
5326expands its value if it appears there, and uses the expanded value as
5327the name of a file to read and execute.  Bash behaves as if the
5328following command were executed:
5329     if [ -n "$BASH_ENV" ]; then . "$BASH_ENV"; fi
5330but the value of the 'PATH' variable is not used to search for the
5331filename.
5332
5333   As noted above, if a non-interactive shell is invoked with the
5334'--login' option, Bash attempts to read and execute commands from the
5335login shell startup files.
5336
5337Invoked with name 'sh'
5338......................
5339
5340If Bash is invoked with the name 'sh', it tries to mimic the startup
5341behavior of historical versions of 'sh' as closely as possible, while
5342conforming to the POSIX standard as well.
5343
5344   When invoked as an interactive login shell, or as a non-interactive
5345shell with the '--login' option, it first attempts to read and execute
5346commands from '/etc/profile' and '~/.profile', in that order.  The
5347'--noprofile' option may be used to inhibit this behavior.  When invoked
5348as an interactive shell with the name 'sh', Bash looks for the variable
5349'ENV', expands its value if it is defined, and uses the expanded value
5350as the name of a file to read and execute.  Since a shell invoked as
5351'sh' does not attempt to read and execute commands from any other
5352startup files, the '--rcfile' option has no effect.  A non-interactive
5353shell invoked with the name 'sh' does not attempt to read any other
5354startup files.
5355
5356   When invoked as 'sh', Bash enters POSIX mode after the startup files
5357are read.
5358
5359Invoked in POSIX mode
5360.....................
5361
5362When Bash is started in POSIX mode, as with the '--posix' command line
5363option, it follows the POSIX standard for startup files.  In this mode,
5364interactive shells expand the 'ENV' variable and commands are read and
5365executed from the file whose name is the expanded value.  No other
5366startup files are read.
5367
5368Invoked by remote shell daemon
5369..............................
5370
5371Bash attempts to determine when it is being run with its standard input
5372connected to a network connection, as when executed by the remote shell
5373daemon, usually 'rshd', or the secure shell daemon 'sshd'.  If Bash
5374determines it is being run in this fashion, it reads and executes
5375commands from '~/.bashrc', if that file exists and is readable.  It will
5376not do this if invoked as 'sh'.  The '--norc' option may be used to
5377inhibit this behavior, and the '--rcfile' option may be used to force
5378another file to be read, but neither 'rshd' nor 'sshd' generally invoke
5379the shell with those options or allow them to be specified.
5380
5381Invoked with unequal effective and real UID/GIDs
5382................................................
5383
5384If Bash is started with the effective user (group) id not equal to the
5385real user (group) id, and the '-p' option is not supplied, no startup
5386files are read, shell functions are not inherited from the environment,
5387the 'SHELLOPTS', 'BASHOPTS', 'CDPATH', and 'GLOBIGNORE' variables, if
5388they appear in the environment, are ignored, and the effective user id
5389is set to the real user id.  If the '-p' option is supplied at
5390invocation, the startup behavior is the same, but the effective user id
5391is not reset.
5392
53936.3 Interactive Shells
5394======================
5395
53966.3.1 What is an Interactive Shell?
5397-----------------------------------
5398
5399An interactive shell is one started without non-option arguments, unless
5400'-s' is specified, without specifying the '-c' option, and whose input
5401and error output are both connected to terminals (as determined by
5402'isatty(3)'), or one started with the '-i' option.
5403
5404   An interactive shell generally reads from and writes to a user's
5405terminal.
5406
5407   The '-s' invocation option may be used to set the positional
5408parameters when an interactive shell is started.
5409
54106.3.2 Is this Shell Interactive?
5411--------------------------------
5412
5413To determine within a startup script whether or not Bash is running
5414interactively, test the value of the '-' special parameter.  It contains
5415'i' when the shell is interactive.  For example:
5416
5417     case "$-" in
5418     *i*)	echo This shell is interactive ;;
5419     *)	echo This shell is not interactive ;;
5420     esac
5421
5422   Alternatively, startup scripts may examine the variable 'PS1'; it is
5423unset in non-interactive shells, and set in interactive shells.  Thus:
5424
5425     if [ -z "$PS1" ]; then
5426             echo This shell is not interactive
5427     else
5428             echo This shell is interactive
5429     fi
5430
54316.3.3 Interactive Shell Behavior
5432--------------------------------
5433
5434When the shell is running interactively, it changes its behavior in
5435several ways.
5436
5437  1. Startup files are read and executed as described in *note Bash
5438     Startup Files::.
5439
5440  2. Job Control (*note Job Control::) is enabled by default.  When job
5441     control is in effect, Bash ignores the keyboard-generated job
5442     control signals 'SIGTTIN', 'SIGTTOU', and 'SIGTSTP'.
5443
5444  3. Bash expands and displays 'PS1' before reading the first line of a
5445     command, and expands and displays 'PS2' before reading the second
5446     and subsequent lines of a multi-line command.  Bash displays 'PS0'
5447     after it reads a command but before executing it.
5448
5449  4. Bash executes the value of the 'PROMPT_COMMAND' variable as a
5450     command before printing the primary prompt, '$PS1' (*note Bash
5451     Variables::).
5452
5453  5. Readline (*note Command Line Editing::) is used to read commands
5454     from the user's terminal.
5455
5456  6. Bash inspects the value of the 'ignoreeof' option to 'set -o'
5457     instead of exiting immediately when it receives an 'EOF' on its
5458     standard input when reading a command (*note The Set Builtin::).
5459
5460  7. Command history (*note Bash History Facilities::) and history
5461     expansion (*note History Interaction::) are enabled by default.
5462     Bash will save the command history to the file named by '$HISTFILE'
5463     when a shell with history enabled exits.
5464
5465  8. Alias expansion (*note Aliases::) is performed by default.
5466
5467  9. In the absence of any traps, Bash ignores 'SIGTERM' (*note
5468     Signals::).
5469
5470  10. In the absence of any traps, 'SIGINT' is caught and handled
5471     ((*note Signals::).  'SIGINT' will interrupt some shell builtins.
5472
5473  11. An interactive login shell sends a 'SIGHUP' to all jobs on exit if
5474     the 'huponexit' shell option has been enabled (*note Signals::).
5475
5476  12. The '-n' invocation option is ignored, and 'set -n' has no effect
5477     (*note The Set Builtin::).
5478
5479  13. Bash will check for mail periodically, depending on the values of
5480     the 'MAIL', 'MAILPATH', and 'MAILCHECK' shell variables (*note Bash
5481     Variables::).
5482
5483  14. Expansion errors due to references to unbound shell variables
5484     after 'set -u' has been enabled will not cause the shell to exit
5485     (*note The Set Builtin::).
5486
5487  15. The shell will not exit on expansion errors caused by VAR being
5488     unset or null in '${VAR:?WORD}' expansions (*note Shell Parameter
5489     Expansion::).
5490
5491  16. Redirection errors encountered by shell builtins will not cause
5492     the shell to exit.
5493
5494  17. When running in POSIX mode, a special builtin returning an error
5495     status will not cause the shell to exit (*note Bash POSIX Mode::).
5496
5497  18. A failed 'exec' will not cause the shell to exit (*note Bourne
5498     Shell Builtins::).
5499
5500  19. Parser syntax errors will not cause the shell to exit.
5501
5502  20. Simple spelling correction for directory arguments to the 'cd'
5503     builtin is enabled by default (see the description of the 'cdspell'
5504     option to the 'shopt' builtin in *note The Shopt Builtin::).
5505
5506  21. The shell will check the value of the 'TMOUT' variable and exit if
5507     a command is not read within the specified number of seconds after
5508     printing '$PS1' (*note Bash Variables::).
5509
55106.4 Bash Conditional Expressions
5511================================
5512
5513Conditional expressions are used by the '[[' compound command and the
5514'test' and '[' builtin commands.
5515
5516   Expressions may be unary or binary.  Unary expressions are often used
5517to examine the status of a file.  There are string operators and numeric
5518comparison operators as well.  Bash handles several filenames specially
5519when they are used in expressions.  If the operating system on which
5520Bash is running provides these special files, Bash will use them;
5521otherwise it will emulate them internally with this behavior: If the
5522FILE argument to one of the primaries is of the form '/dev/fd/N', then
5523file descriptor N is checked.  If the FILE argument to one of the
5524primaries is one of '/dev/stdin', '/dev/stdout', or '/dev/stderr', file
5525descriptor 0, 1, or 2, respectively, is checked.
5526
5527   When used with '[[', the '<' and '>' operators sort lexicographically
5528using the current locale.  The 'test' command uses ASCII ordering.
5529
5530   Unless otherwise specified, primaries that operate on files follow
5531symbolic links and operate on the target of the link, rather than the
5532link itself.
5533
5534'-a FILE'
5535     True if FILE exists.
5536
5537'-b FILE'
5538     True if FILE exists and is a block special file.
5539
5540'-c FILE'
5541     True if FILE exists and is a character special file.
5542
5543'-d FILE'
5544     True if FILE exists and is a directory.
5545
5546'-e FILE'
5547     True if FILE exists.
5548
5549'-f FILE'
5550     True if FILE exists and is a regular file.
5551
5552'-g FILE'
5553     True if FILE exists and its set-group-id bit is set.
5554
5555'-h FILE'
5556     True if FILE exists and is a symbolic link.
5557
5558'-k FILE'
5559     True if FILE exists and its "sticky" bit is set.
5560
5561'-p FILE'
5562     True if FILE exists and is a named pipe (FIFO).
5563
5564'-r FILE'
5565     True if FILE exists and is readable.
5566
5567'-s FILE'
5568     True if FILE exists and has a size greater than zero.
5569
5570'-t FD'
5571     True if file descriptor FD is open and refers to a terminal.
5572
5573'-u FILE'
5574     True if FILE exists and its set-user-id bit is set.
5575
5576'-w FILE'
5577     True if FILE exists and is writable.
5578
5579'-x FILE'
5580     True if FILE exists and is executable.
5581
5582'-G FILE'
5583     True if FILE exists and is owned by the effective group id.
5584
5585'-L FILE'
5586     True if FILE exists and is a symbolic link.
5587
5588'-N FILE'
5589     True if FILE exists and has been modified since it was last read.
5590
5591'-O FILE'
5592     True if FILE exists and is owned by the effective user id.
5593
5594'-S FILE'
5595     True if FILE exists and is a socket.
5596
5597'FILE1 -ef FILE2'
5598     True if FILE1 and FILE2 refer to the same device and inode numbers.
5599
5600'FILE1 -nt FILE2'
5601     True if FILE1 is newer (according to modification date) than FILE2,
5602     or if FILE1 exists and FILE2 does not.
5603
5604'FILE1 -ot FILE2'
5605     True if FILE1 is older than FILE2, or if FILE2 exists and FILE1
5606     does not.
5607
5608'-o OPTNAME'
5609     True if the shell option OPTNAME is enabled.  The list of options
5610     appears in the description of the '-o' option to the 'set' builtin
5611     (*note The Set Builtin::).
5612
5613'-v VARNAME'
5614     True if the shell variable VARNAME is set (has been assigned a
5615     value).
5616
5617'-R VARNAME'
5618     True if the shell variable VARNAME is set and is a name reference.
5619
5620'-z STRING'
5621     True if the length of STRING is zero.
5622
5623'-n STRING'
5624'STRING'
5625     True if the length of STRING is non-zero.
5626
5627'STRING1 == STRING2'
5628'STRING1 = STRING2'
5629     True if the strings are equal.  When used with the '[[' command,
5630     this performs pattern matching as described above (*note
5631     Conditional Constructs::).
5632
5633     '=' should be used with the 'test' command for POSIX conformance.
5634
5635'STRING1 != STRING2'
5636     True if the strings are not equal.
5637
5638'STRING1 < STRING2'
5639     True if STRING1 sorts before STRING2 lexicographically.
5640
5641'STRING1 > STRING2'
5642     True if STRING1 sorts after STRING2 lexicographically.
5643
5644'ARG1 OP ARG2'
5645     'OP' is one of '-eq', '-ne', '-lt', '-le', '-gt', or '-ge'.  These
5646     arithmetic binary operators return true if ARG1 is equal to, not
5647     equal to, less than, less than or equal to, greater than, or
5648     greater than or equal to ARG2, respectively.  ARG1 and ARG2 may be
5649     positive or negative integers.
5650
56516.5 Shell Arithmetic
5652====================
5653
5654The shell allows arithmetic expressions to be evaluated, as one of the
5655shell expansions or by using the '((' compound command, the 'let'
5656builtin, or the '-i' option to the 'declare' builtin.
5657
5658   Evaluation is done in fixed-width integers with no check for
5659overflow, though division by 0 is trapped and flagged as an error.  The
5660operators and their precedence, associativity, and values are the same
5661as in the C language.  The following list of operators is grouped into
5662levels of equal-precedence operators.  The levels are listed in order of
5663decreasing precedence.
5664
5665'ID++ ID--'
5666     variable post-increment and post-decrement
5667
5668'++ID --ID'
5669     variable pre-increment and pre-decrement
5670
5671'- +'
5672     unary minus and plus
5673
5674'! ~'
5675     logical and bitwise negation
5676
5677'**'
5678     exponentiation
5679
5680'* / %'
5681     multiplication, division, remainder
5682
5683'+ -'
5684     addition, subtraction
5685
5686'<< >>'
5687     left and right bitwise shifts
5688
5689'<= >= < >'
5690     comparison
5691
5692'== !='
5693     equality and inequality
5694
5695'&'
5696     bitwise AND
5697
5698'^'
5699     bitwise exclusive OR
5700
5701'|'
5702     bitwise OR
5703
5704'&&'
5705     logical AND
5706
5707'||'
5708     logical OR
5709
5710'expr ? expr : expr'
5711     conditional operator
5712
5713'= *= /= %= += -= <<= >>= &= ^= |='
5714     assignment
5715
5716'expr1 , expr2'
5717     comma
5718
5719   Shell variables are allowed as operands; parameter expansion is
5720performed before the expression is evaluated.  Within an expression,
5721shell variables may also be referenced by name without using the
5722parameter expansion syntax.  A shell variable that is null or unset
5723evaluates to 0 when referenced by name without using the parameter
5724expansion syntax.  The value of a variable is evaluated as an arithmetic
5725expression when it is referenced, or when a variable which has been
5726given the INTEGER attribute using 'declare -i' is assigned a value.  A
5727null value evaluates to 0.  A shell variable need not have its INTEGER
5728attribute turned on to be used in an expression.
5729
5730   Constants with a leading 0 are interpreted as octal numbers.  A
5731leading '0x' or '0X' denotes hexadecimal.  Otherwise, numbers take the
5732form [BASE'#']N, where the optional BASE is a decimal number between 2
5733and 64 representing the arithmetic base, and N is a number in that base.
5734If BASE'#' is omitted, then base 10 is used.  When specifying N, the
5735digits greater than 9 are represented by the lowercase letters, the
5736uppercase letters, '@', and '_', in that order.  If BASE is less than or
5737equal to 36, lowercase and uppercase letters may be used interchangeably
5738to represent numbers between 10 and 35.
5739
5740   Operators are evaluated in order of precedence.  Sub-expressions in
5741parentheses are evaluated first and may override the precedence rules
5742above.
5743
57446.6 Aliases
5745===========
5746
5747ALIASES allow a string to be substituted for a word when it is used as
5748the first word of a simple command.  The shell maintains a list of
5749aliases that may be set and unset with the 'alias' and 'unalias' builtin
5750commands.
5751
5752   The first word of each simple command, if unquoted, is checked to see
5753if it has an alias.  If so, that word is replaced by the text of the
5754alias.  The characters '/', '$', '`', '=' and any of the shell
5755metacharacters or quoting characters listed above may not appear in an
5756alias name.  The replacement text may contain any valid shell input,
5757including shell metacharacters.  The first word of the replacement text
5758is tested for aliases, but a word that is identical to an alias being
5759expanded is not expanded a second time.  This means that one may alias
5760'ls' to '"ls -F"', for instance, and Bash does not try to recursively
5761expand the replacement text.  If the last character of the alias value
5762is a BLANK, then the next command word following the alias is also
5763checked for alias expansion.
5764
5765   Aliases are created and listed with the 'alias' command, and removed
5766with the 'unalias' command.
5767
5768   There is no mechanism for using arguments in the replacement text, as
5769in 'csh'.  If arguments are needed, a shell function should be used
5770(*note Shell Functions::).
5771
5772   Aliases are not expanded when the shell is not interactive, unless
5773the 'expand_aliases' shell option is set using 'shopt' (*note The Shopt
5774Builtin::).
5775
5776   The rules concerning the definition and use of aliases are somewhat
5777confusing.  Bash always reads at least one complete line of input before
5778executing any of the commands on that line.  Aliases are expanded when a
5779command is read, not when it is executed.  Therefore, an alias
5780definition appearing on the same line as another command does not take
5781effect until the next line of input is read.  The commands following the
5782alias definition on that line are not affected by the new alias.  This
5783behavior is also an issue when functions are executed.  Aliases are
5784expanded when a function definition is read, not when the function is
5785executed, because a function definition is itself a command.  As a
5786consequence, aliases defined in a function are not available until after
5787that function is executed.  To be safe, always put alias definitions on
5788a separate line, and do not use 'alias' in compound commands.
5789
5790   For almost every purpose, shell functions are preferred over aliases.
5791
57926.7 Arrays
5793==========
5794
5795Bash provides one-dimensional indexed and associative array variables.
5796Any variable may be used as an indexed array; the 'declare' builtin will
5797explicitly declare an array.  There is no maximum limit on the size of
5798an array, nor any requirement that members be indexed or assigned
5799contiguously.  Indexed arrays are referenced using integers (including
5800arithmetic expressions (*note Shell Arithmetic::)) and are zero-based;
5801associative arrays use arbitrary strings.  Unless otherwise noted,
5802indexed array indices must be non-negative integers.
5803
5804   An indexed array is created automatically if any variable is assigned
5805to using the syntax
5806     NAME[SUBSCRIPT]=VALUE
5807
5808The SUBSCRIPT is treated as an arithmetic expression that must evaluate
5809to a number.  To explicitly declare an array, use
5810     declare -a NAME
5811The syntax
5812     declare -a NAME[SUBSCRIPT]
5813is also accepted; the SUBSCRIPT is ignored.
5814
5815Associative arrays are created using
5816     declare -A NAME.
5817
5818   Attributes may be specified for an array variable using the 'declare'
5819and 'readonly' builtins.  Each attribute applies to all members of an
5820array.
5821
5822   Arrays are assigned to using compound assignments of the form
5823     NAME=(VALUE1 VALUE2 ... )
5824where each VALUE is of the form '[SUBSCRIPT]='STRING.  Indexed array
5825assignments do not require anything but STRING.  When assigning to
5826indexed arrays, if the optional subscript is supplied, that index is
5827assigned to; otherwise the index of the element assigned is the last
5828index assigned to by the statement plus one.  Indexing starts at zero.
5829
5830   When assigning to an associative array, the subscript is required.
5831
5832   This syntax is also accepted by the 'declare' builtin.  Individual
5833array elements may be assigned to using the 'NAME[SUBSCRIPT]=VALUE'
5834syntax introduced above.
5835
5836   When assigning to an indexed array, if NAME is subscripted by a
5837negative number, that number is interpreted as relative to one greater
5838than the maximum index of NAME, so negative indices count back from the
5839end of the array, and an index of -1 references the last element.
5840
5841   Any element of an array may be referenced using '${NAME[SUBSCRIPT]}'.
5842The braces are required to avoid conflicts with the shell's filename
5843expansion operators.  If the SUBSCRIPT is '@' or '*', the word expands
5844to all members of the array NAME.  These subscripts differ only when the
5845word appears within double quotes.  If the word is double-quoted,
5846'${NAME[*]}' expands to a single word with the value of each array
5847member separated by the first character of the 'IFS' variable, and
5848'${NAME[@]}' expands each element of NAME to a separate word.  When
5849there are no array members, '${NAME[@]}' expands to nothing.  If the
5850double-quoted expansion occurs within a word, the expansion of the first
5851parameter is joined with the beginning part of the original word, and
5852the expansion of the last parameter is joined with the last part of the
5853original word.  This is analogous to the expansion of the special
5854parameters '@' and '*'.  '${#NAME[SUBSCRIPT]}' expands to the length of
5855'${NAME[SUBSCRIPT]}'.  If SUBSCRIPT is '@' or '*', the expansion is the
5856number of elements in the array.  If the SUBSCRIPT used to reference an
5857element of an indexed array evaluates to a number less than zero, it is
5858interpreted as relative to one greater than the maximum index of the
5859array, so negative indices count back from the end of the array, and an
5860index of -1 refers to the last element.
5861
5862   Referencing an array variable without a subscript is equivalent to
5863referencing with a subscript of 0.  Any reference to a variable using a
5864valid subscript is legal, and 'bash' will create an array if necessary.
5865
5866   An array variable is considered set if a subscript has been assigned
5867a value.  The null string is a valid value.
5868
5869   It is possible to obtain the keys (indices) of an array as well as
5870the values.  ${!NAME[@]} and ${!NAME[*]} expand to the indices assigned
5871in array variable NAME.  The treatment when in double quotes is similar
5872to the expansion of the special parameters '@' and '*' within double
5873quotes.
5874
5875   The 'unset' builtin is used to destroy arrays.  'unset
5876NAME[SUBSCRIPT]' destroys the array element at index SUBSCRIPT.
5877Negative subscripts to indexed arrays are interpreted as described
5878above.  Care must be taken to avoid unwanted side effects caused by
5879filename expansion.  'unset NAME', where NAME is an array, removes the
5880entire array.  A subscript of '*' or '@' also removes the entire array.
5881
5882   The 'declare', 'local', and 'readonly' builtins each accept a '-a'
5883option to specify an indexed array and a '-A' option to specify an
5884associative array.  If both options are supplied, '-A' takes precedence.
5885The 'read' builtin accepts a '-a' option to assign a list of words read
5886from the standard input to an array, and can read values from the
5887standard input into individual array elements.  The 'set' and 'declare'
5888builtins display array values in a way that allows them to be reused as
5889input.
5890
58916.8 The Directory Stack
5892=======================
5893
5894The directory stack is a list of recently-visited directories.  The
5895'pushd' builtin adds directories to the stack as it changes the current
5896directory, and the 'popd' builtin removes specified directories from the
5897stack and changes the current directory to the directory removed.  The
5898'dirs' builtin displays the contents of the directory stack.  The
5899current directory is always the "top" of the directory stack.
5900
5901   The contents of the directory stack are also visible as the value of
5902the 'DIRSTACK' shell variable.
5903
59046.8.1 Directory Stack Builtins
5905------------------------------
5906
5907'dirs'
5908          dirs [-clpv] [+N | -N]
5909
5910     Display the list of currently remembered directories.  Directories
5911     are added to the list with the 'pushd' command; the 'popd' command
5912     removes directories from the list.  The current directory is always
5913     the first directory in the stack.
5914
5915     '-c'
5916          Clears the directory stack by deleting all of the elements.
5917     '-l'
5918          Produces a listing using full pathnames; the default listing
5919          format uses a tilde to denote the home directory.
5920     '-p'
5921          Causes 'dirs' to print the directory stack with one entry per
5922          line.
5923     '-v'
5924          Causes 'dirs' to print the directory stack with one entry per
5925          line, prefixing each entry with its index in the stack.
5926     '+N'
5927          Displays the Nth directory (counting from the left of the list
5928          printed by 'dirs' when invoked without options), starting with
5929          zero.
5930     '-N'
5931          Displays the Nth directory (counting from the right of the
5932          list printed by 'dirs' when invoked without options), starting
5933          with zero.
5934
5935'popd'
5936          popd [-n] [+N | -N]
5937
5938     When no arguments are given, 'popd' removes the top directory from
5939     the stack and performs a 'cd' to the new top directory.  The
5940     elements are numbered from 0 starting at the first directory listed
5941     with 'dirs'; that is, 'popd' is equivalent to 'popd +0'.
5942
5943     '-n'
5944          Suppresses the normal change of directory when removing
5945          directories from the stack, so that only the stack is
5946          manipulated.
5947     '+N'
5948          Removes the Nth directory (counting from the left of the list
5949          printed by 'dirs'), starting with zero.
5950     '-N'
5951          Removes the Nth directory (counting from the right of the list
5952          printed by 'dirs'), starting with zero.
5953
5954'pushd'
5955          pushd [-n] [+N | -N | DIR]
5956
5957     Save the current directory on the top of the directory stack and
5958     then 'cd' to DIR.  With no arguments, 'pushd' exchanges the top two
5959     directories and makes the new top the current directory.
5960
5961     '-n'
5962          Suppresses the normal change of directory when rotating or
5963          adding directories to the stack, so that only the stack is
5964          manipulated.
5965     '+N'
5966          Brings the Nth directory (counting from the left of the list
5967          printed by 'dirs', starting with zero) to the top of the list
5968          by rotating the stack.
5969     '-N'
5970          Brings the Nth directory (counting from the right of the list
5971          printed by 'dirs', starting with zero) to the top of the list
5972          by rotating the stack.
5973     'DIR'
5974          Makes DIR be the top of the stack, making it the new current
5975          directory as if it had been supplied as an argument to the
5976          'cd' builtin.
5977
59786.9 Controlling the Prompt
5979==========================
5980
5981The value of the variable 'PROMPT_COMMAND' is examined just before Bash
5982prints each primary prompt.  If 'PROMPT_COMMAND' is set and has a
5983non-null value, then the value is executed just as if it had been typed
5984on the command line.
5985
5986   In addition, the following table describes the special characters
5987which can appear in the prompt variables 'PS1' to 'PS4':
5988
5989'\a'
5990     A bell character.
5991'\d'
5992     The date, in "Weekday Month Date" format (e.g., "Tue May 26").
5993'\D{FORMAT}'
5994     The FORMAT is passed to 'strftime'(3) and the result is inserted
5995     into the prompt string; an empty FORMAT results in a
5996     locale-specific time representation.  The braces are required.
5997'\e'
5998     An escape character.
5999'\h'
6000     The hostname, up to the first '.'.
6001'\H'
6002     The hostname.
6003'\j'
6004     The number of jobs currently managed by the shell.
6005'\l'
6006     The basename of the shell's terminal device name.
6007'\n'
6008     A newline.
6009'\r'
6010     A carriage return.
6011'\s'
6012     The name of the shell, the basename of '$0' (the portion following
6013     the final slash).
6014'\t'
6015     The time, in 24-hour HH:MM:SS format.
6016'\T'
6017     The time, in 12-hour HH:MM:SS format.
6018'\@'
6019     The time, in 12-hour am/pm format.
6020'\A'
6021     The time, in 24-hour HH:MM format.
6022'\u'
6023     The username of the current user.
6024'\v'
6025     The version of Bash (e.g., 2.00)
6026'\V'
6027     The release of Bash, version + patchlevel (e.g., 2.00.0)
6028'\w'
6029     The current working directory, with '$HOME' abbreviated with a
6030     tilde (uses the '$PROMPT_DIRTRIM' variable).
6031'\W'
6032     The basename of '$PWD', with '$HOME' abbreviated with a tilde.
6033'\!'
6034     The history number of this command.
6035'\#'
6036     The command number of this command.
6037'\$'
6038     If the effective uid is 0, '#', otherwise '$'.
6039'\NNN'
6040     The character whose ASCII code is the octal value NNN.
6041'\\'
6042     A backslash.
6043'\['
6044     Begin a sequence of non-printing characters.  This could be used to
6045     embed a terminal control sequence into the prompt.
6046'\]'
6047     End a sequence of non-printing characters.
6048
6049   The command number and the history number are usually different: the
6050history number of a command is its position in the history list, which
6051may include commands restored from the history file (*note Bash History
6052Facilities::), while the command number is the position in the sequence
6053of commands executed during the current shell session.
6054
6055   After the string is decoded, it is expanded via parameter expansion,
6056command substitution, arithmetic expansion, and quote removal, subject
6057to the value of the 'promptvars' shell option (*note Bash Builtins::).
6058
60596.10 The Restricted Shell
6060=========================
6061
6062If Bash is started with the name 'rbash', or the '--restricted' or '-r'
6063option is supplied at invocation, the shell becomes restricted.  A
6064restricted shell is used to set up an environment more controlled than
6065the standard shell.  A restricted shell behaves identically to 'bash'
6066with the exception that the following are disallowed or not performed:
6067
6068   * Changing directories with the 'cd' builtin.
6069   * Setting or unsetting the values of the 'SHELL', 'PATH', 'ENV', or
6070     'BASH_ENV' variables.
6071   * Specifying command names containing slashes.
6072   * Specifying a filename containing a slash as an argument to the '.'
6073     builtin command.
6074   * Specifying a filename containing a slash as an argument to the '-p'
6075     option to the 'hash' builtin command.
6076   * Importing function definitions from the shell environment at
6077     startup.
6078   * Parsing the value of 'SHELLOPTS' from the shell environment at
6079     startup.
6080   * Redirecting output using the '>', '>|', '<>', '>&', '&>', and '>>'
6081     redirection operators.
6082   * Using the 'exec' builtin to replace the shell with another command.
6083   * Adding or deleting builtin commands with the '-f' and '-d' options
6084     to the 'enable' builtin.
6085   * Using the 'enable' builtin command to enable disabled shell
6086     builtins.
6087   * Specifying the '-p' option to the 'command' builtin.
6088   * Turning off restricted mode with 'set +r' or 'set +o restricted'.
6089
6090   These restrictions are enforced after any startup files are read.
6091
6092   When a command that is found to be a shell script is executed (*note
6093Shell Scripts::), 'rbash' turns off any restrictions in the shell
6094spawned to execute the script.
6095
60966.11 Bash POSIX Mode
6097====================
6098
6099Starting Bash with the '--posix' command-line option or executing 'set
6100-o posix' while Bash is running will cause Bash to conform more closely
6101to the POSIX standard by changing the behavior to match that specified
6102by POSIX in areas where the Bash default differs.
6103
6104   When invoked as 'sh', Bash enters POSIX mode after reading the
6105startup files.
6106
6107   The following list is what's changed when 'POSIX mode' is in effect:
6108
6109  1. When a command in the hash table no longer exists, Bash will
6110     re-search '$PATH' to find the new location.  This is also available
6111     with 'shopt -s checkhash'.
6112
6113  2. The message printed by the job control code and builtins when a job
6114     exits with a non-zero status is 'Done(status)'.
6115
6116  3. The message printed by the job control code and builtins when a job
6117     is stopped is 'Stopped(SIGNAME)', where SIGNAME is, for example,
6118     'SIGTSTP'.
6119
6120  4. Alias expansion is always enabled, even in non-interactive shells.
6121
6122  5. Reserved words appearing in a context where reserved words are
6123     recognized do not undergo alias expansion.
6124
6125  6. The POSIX 'PS1' and 'PS2' expansions of '!' to the history number
6126     and '!!' to '!' are enabled, and parameter expansion is performed
6127     on the values of 'PS1' and 'PS2' regardless of the setting of the
6128     'promptvars' option.
6129
6130  7. The POSIX startup files are executed ('$ENV') rather than the
6131     normal Bash files.
6132
6133  8. Tilde expansion is only performed on assignments preceding a
6134     command name, rather than on all assignment statements on the line.
6135
6136  9. The default history file is '~/.sh_history' (this is the default
6137     value of '$HISTFILE').
6138
6139  10. Redirection operators do not perform filename expansion on the
6140     word in the redirection unless the shell is interactive.
6141
6142  11. Redirection operators do not perform word splitting on the word in
6143     the redirection.
6144
6145  12. Function names must be valid shell 'name's.  That is, they may not
6146     contain characters other than letters, digits, and underscores, and
6147     may not start with a digit.  Declaring a function with an invalid
6148     name causes a fatal syntax error in non-interactive shells.
6149
6150  13. Function names may not be the same as one of the POSIX special
6151     builtins.
6152
6153  14. POSIX special builtins are found before shell functions during
6154     command lookup.
6155
6156  15. When printing shell function definitions (e.g., by 'type'), Bash
6157     does not print the 'function' keyword.
6158
6159  16. Literal tildes that appear as the first character in elements of
6160     the 'PATH' variable are not expanded as described above under *note
6161     Tilde Expansion::.
6162
6163  17. The 'time' reserved word may be used by itself as a command.  When
6164     used in this way, it displays timing statistics for the shell and
6165     its completed children.  The 'TIMEFORMAT' variable controls the
6166     format of the timing information.
6167
6168  18. When parsing and expanding a ${...} expansion that appears within
6169     double quotes, single quotes are no longer special and cannot be
6170     used to quote a closing brace or other special character, unless
6171     the operator is one of those defined to perform pattern removal.
6172     In this case, they do not have to appear as matched pairs.
6173
6174  19. The parser does not recognize 'time' as a reserved word if the
6175     next token begins with a '-'.
6176
6177  20. The '!' character does not introduce history expansion within a
6178     double-quoted string, even if the 'histexpand' option is enabled.
6179
6180  21. If a POSIX special builtin returns an error status, a
6181     non-interactive shell exits.  The fatal errors are those listed in
6182     the POSIX standard, and include things like passing incorrect
6183     options, redirection errors, variable assignment errors for
6184     assignments preceding the command name, and so on.
6185
6186  22. A non-interactive shell exits with an error status if a variable
6187     assignment error occurs when no command name follows the assignment
6188     statements.  A variable assignment error occurs, for example, when
6189     trying to assign a value to a readonly variable.
6190
6191  23. A non-interactive shell exits with an error status if a variable
6192     assignment error occurs in an assignment statement preceding a
6193     special builtin, but not with any other simple command.
6194
6195  24. A non-interactive shell exits with an error status if the
6196     iteration variable in a 'for' statement or the selection variable
6197     in a 'select' statement is a readonly variable.
6198
6199  25. Non-interactive shells exit if FILENAME in '.'  FILENAME is not
6200     found.
6201
6202  26. Non-interactive shells exit if a syntax error in an arithmetic
6203     expansion results in an invalid expression.
6204
6205  27. Non-interactive shells exit if a parameter expansion error occurs.
6206
6207  28. Non-interactive shells exit if there is a syntax error in a script
6208     read with the '.' or 'source' builtins, or in a string processed by
6209     the 'eval' builtin.
6210
6211  29. Process substitution is not available.
6212
6213  30. While variable indirection is available, it may not be applied to
6214     the '#' and '?' special parameters.
6215
6216  31. When expanding the '*' special parameter in a pattern context
6217     where the expansion is double-quoted does not treat the '$*' as if
6218     it were double-quoted.
6219
6220  32. Assignment statements preceding POSIX special builtins persist in
6221     the shell environment after the builtin completes.
6222
6223  33. Assignment statements preceding shell function calls persist in
6224     the shell environment after the function returns, as if a POSIX
6225     special builtin command had been executed.
6226
6227  34. The 'command' builtin does not prevent builtins that take
6228     assignment statements as arguments from expanding them as
6229     assignment statements; when not in POSIX mode, assignment builtins
6230     lose their assignment statement expansion properties when preceded
6231     by 'command'.
6232
6233  35. The 'bg' builtin uses the required format to describe each job
6234     placed in the background, which does not include an indication of
6235     whether the job is the current or previous job.
6236
6237  36. The output of 'kill -l' prints all the signal names on a single
6238     line, separated by spaces, without the 'SIG' prefix.
6239
6240  37. The 'kill' builtin does not accept signal names with a 'SIG'
6241     prefix.
6242
6243  38. The 'export' and 'readonly' builtin commands display their output
6244     in the format required by POSIX.
6245
6246  39. The 'trap' builtin displays signal names without the leading
6247     'SIG'.
6248
6249  40. The 'trap' builtin doesn't check the first argument for a possible
6250     signal specification and revert the signal handling to the original
6251     disposition if it is, unless that argument consists solely of
6252     digits and is a valid signal number.  If users want to reset the
6253     handler for a given signal to the original disposition, they should
6254     use '-' as the first argument.
6255
6256  41. The '.' and 'source' builtins do not search the current directory
6257     for the filename argument if it is not found by searching 'PATH'.
6258
6259  42. Enabling POSIX mode has the effect of setting the
6260     'inherit_errexit' option, so subshells spawned to execute command
6261     substitutions inherit the value of the '-e' option from the parent
6262     shell.  When the 'inherit_errexit' option is not enabled, Bash
6263     clears the '-e' option in such subshells.
6264
6265  43. When the 'alias' builtin displays alias definitions, it does not
6266     display them with a leading 'alias ' unless the '-p' option is
6267     supplied.
6268
6269  44. When the 'set' builtin is invoked without options, it does not
6270     display shell function names and definitions.
6271
6272  45. When the 'set' builtin is invoked without options, it displays
6273     variable values without quotes, unless they contain shell
6274     metacharacters, even if the result contains nonprinting characters.
6275
6276  46. When the 'cd' builtin is invoked in LOGICAL mode, and the pathname
6277     constructed from '$PWD' and the directory name supplied as an
6278     argument does not refer to an existing directory, 'cd' will fail
6279     instead of falling back to PHYSICAL mode.
6280
6281  47. The 'pwd' builtin verifies that the value it prints is the same as
6282     the current directory, even if it is not asked to check the file
6283     system with the '-P' option.
6284
6285  48. When listing the history, the 'fc' builtin does not include an
6286     indication of whether or not a history entry has been modified.
6287
6288  49. The default editor used by 'fc' is 'ed'.
6289
6290  50. The 'type' and 'command' builtins will not report a non-executable
6291     file as having been found, though the shell will attempt to execute
6292     such a file if it is the only so-named file found in '$PATH'.
6293
6294  51. The 'vi' editing mode will invoke the 'vi' editor directly when
6295     the 'v' command is run, instead of checking '$VISUAL' and
6296     '$EDITOR'.
6297
6298  52. When the 'xpg_echo' option is enabled, Bash does not attempt to
6299     interpret any arguments to 'echo' as options.  Each argument is
6300     displayed, after escape characters are converted.
6301
6302  53. The 'ulimit' builtin uses a block size of 512 bytes for the '-c'
6303     and '-f' options.
6304
6305  54. The arrival of 'SIGCHLD' when a trap is set on 'SIGCHLD' does not
6306     interrupt the 'wait' builtin and cause it to return immediately.
6307     The trap command is run once for each child that exits.
6308
6309  55. The 'read' builtin may be interrupted by a signal for which a trap
6310     has been set.  If Bash receives a trapped signal while executing
6311     'read', the trap handler executes and 'read' returns an exit status
6312     greater than 128.
6313
6314  56. Bash removes an exited background process's status from the list
6315     of such statuses after the 'wait' builtin is used to obtain it.
6316
6317   There is other POSIX behavior that Bash does not implement by default
6318even when in POSIX mode.  Specifically:
6319
6320  1. The 'fc' builtin checks '$EDITOR' as a program to edit history
6321     entries if 'FCEDIT' is unset, rather than defaulting directly to
6322     'ed'.  'fc' uses 'ed' if 'EDITOR' is unset.
6323
6324  2. As noted above, Bash requires the 'xpg_echo' option to be enabled
6325     for the 'echo' builtin to be fully conformant.
6326
6327   Bash can be configured to be POSIX-conformant by default, by
6328specifying the '--enable-strict-posix-default' to 'configure' when
6329building (*note Optional Features::).
6330
63317 Job Control
6332*************
6333
6334This chapter discusses what job control is, how it works, and how Bash
6335allows you to access its facilities.
6336
63377.1 Job Control Basics
6338======================
6339
6340Job control refers to the ability to selectively stop (suspend) the
6341execution of processes and continue (resume) their execution at a later
6342point.  A user typically employs this facility via an interactive
6343interface supplied jointly by the operating system kernel's terminal
6344driver and Bash.
6345
6346   The shell associates a JOB with each pipeline.  It keeps a table of
6347currently executing jobs, which may be listed with the 'jobs' command.
6348When Bash starts a job asynchronously, it prints a line that looks like:
6349     [1] 25647
6350indicating that this job is job number 1 and that the process ID of the
6351last process in the pipeline associated with this job is 25647.  All of
6352the processes in a single pipeline are members of the same job.  Bash
6353uses the JOB abstraction as the basis for job control.
6354
6355   To facilitate the implementation of the user interface to job
6356control, the operating system maintains the notion of a current terminal
6357process group ID.  Members of this process group (processes whose
6358process group ID is equal to the current terminal process group ID)
6359receive keyboard-generated signals such as 'SIGINT'.  These processes
6360are said to be in the foreground.  Background processes are those whose
6361process group ID differs from the terminal's; such processes are immune
6362to keyboard-generated signals.  Only foreground processes are allowed to
6363read from or, if the user so specifies with 'stty tostop', write to the
6364terminal.  Background processes which attempt to read from (write to
6365when 'stty tostop' is in effect) the terminal are sent a 'SIGTTIN'
6366('SIGTTOU') signal by the kernel's terminal driver, which, unless
6367caught, suspends the process.
6368
6369   If the operating system on which Bash is running supports job
6370control, Bash contains facilities to use it.  Typing the SUSPEND
6371character (typically '^Z', Control-Z) while a process is running causes
6372that process to be stopped and returns control to Bash.  Typing the
6373DELAYED SUSPEND character (typically '^Y', Control-Y) causes the process
6374to be stopped when it attempts to read input from the terminal, and
6375control to be returned to Bash.  The user then manipulates the state of
6376this job, using the 'bg' command to continue it in the background, the
6377'fg' command to continue it in the foreground, or the 'kill' command to
6378kill it.  A '^Z' takes effect immediately, and has the additional side
6379effect of causing pending output and typeahead to be discarded.
6380
6381   There are a number of ways to refer to a job in the shell.  The
6382character '%' introduces a job specification (JOBSPEC).
6383
6384   Job number 'n' may be referred to as '%n'.  The symbols '%%' and '%+'
6385refer to the shell's notion of the current job, which is the last job
6386stopped while it was in the foreground or started in the background.  A
6387single '%' (with no accompanying job specification) also refers to the
6388current job.  The previous job may be referenced using '%-'.  If there
6389is only a single job, '%+' and '%-' can both be used to refer to that
6390job.  In output pertaining to jobs (e.g., the output of the 'jobs'
6391command), the current job is always flagged with a '+', and the previous
6392job with a '-'.
6393
6394   A job may also be referred to using a prefix of the name used to
6395start it, or using a substring that appears in its command line.  For
6396example, '%ce' refers to a stopped 'ce' job.  Using '%?ce', on the other
6397hand, refers to any job containing the string 'ce' in its command line.
6398If the prefix or substring matches more than one job, Bash reports an
6399error.
6400
6401   Simply naming a job can be used to bring it into the foreground: '%1'
6402is a synonym for 'fg %1', bringing job 1 from the background into the
6403foreground.  Similarly, '%1 &' resumes job 1 in the background,
6404equivalent to 'bg %1'
6405
6406   The shell learns immediately whenever a job changes state.  Normally,
6407Bash waits until it is about to print a prompt before reporting changes
6408in a job's status so as to not interrupt any other output.  If the '-b'
6409option to the 'set' builtin is enabled, Bash reports such changes
6410immediately (*note The Set Builtin::).  Any trap on 'SIGCHLD' is
6411executed for each child process that exits.
6412
6413   If an attempt to exit Bash is made while jobs are stopped, (or
6414running, if the 'checkjobs' option is enabled - see *note The Shopt
6415Builtin::), the shell prints a warning message, and if the 'checkjobs'
6416option is enabled, lists the jobs and their statuses.  The 'jobs'
6417command may then be used to inspect their status.  If a second attempt
6418to exit is made without an intervening command, Bash does not print
6419another warning, and any stopped jobs are terminated.
6420
64217.2 Job Control Builtins
6422========================
6423
6424'bg'
6425          bg [JOBSPEC ...]
6426
6427     Resume each suspended job JOBSPEC in the background, as if it had
6428     been started with '&'.  If JOBSPEC is not supplied, the current job
6429     is used.  The return status is zero unless it is run when job
6430     control is not enabled, or, when run with job control enabled, any
6431     JOBSPEC was not found or specifies a job that was started without
6432     job control.
6433
6434'fg'
6435          fg [JOBSPEC]
6436
6437     Resume the job JOBSPEC in the foreground and make it the current
6438     job.  If JOBSPEC is not supplied, the current job is used.  The
6439     return status is that of the command placed into the foreground, or
6440     non-zero if run when job control is disabled or, when run with job
6441     control enabled, JOBSPEC does not specify a valid job or JOBSPEC
6442     specifies a job that was started without job control.
6443
6444'jobs'
6445          jobs [-lnprs] [JOBSPEC]
6446          jobs -x COMMAND [ARGUMENTS]
6447
6448     The first form lists the active jobs.  The options have the
6449     following meanings:
6450
6451     '-l'
6452          List process IDs in addition to the normal information.
6453
6454     '-n'
6455          Display information only about jobs that have changed status
6456          since the user was last notified of their status.
6457
6458     '-p'
6459          List only the process ID of the job's process group leader.
6460
6461     '-r'
6462          Display only running jobs.
6463
6464     '-s'
6465          Display only stopped jobs.
6466
6467     If JOBSPEC is given, output is restricted to information about that
6468     job.  If JOBSPEC is not supplied, the status of all jobs is listed.
6469
6470     If the '-x' option is supplied, 'jobs' replaces any JOBSPEC found
6471     in COMMAND or ARGUMENTS with the corresponding process group ID,
6472     and executes COMMAND, passing it ARGUMENTs, returning its exit
6473     status.
6474
6475'kill'
6476          kill [-s SIGSPEC] [-n SIGNUM] [-SIGSPEC] JOBSPEC or PID
6477          kill -l|-L [EXIT_STATUS]
6478
6479     Send a signal specified by SIGSPEC or SIGNUM to the process named
6480     by job specification JOBSPEC or process ID PID.  SIGSPEC is either
6481     a case-insensitive signal name such as 'SIGINT' (with or without
6482     the 'SIG' prefix) or a signal number; SIGNUM is a signal number.
6483     If SIGSPEC and SIGNUM are not present, 'SIGTERM' is used.  The '-l'
6484     option lists the signal names.  If any arguments are supplied when
6485     '-l' is given, the names of the signals corresponding to the
6486     arguments are listed, and the return status is zero.  EXIT_STATUS
6487     is a number specifying a signal number or the exit status of a
6488     process terminated by a signal.  The '-L' option is equivalent to
6489     '-l'.  The return status is zero if at least one signal was
6490     successfully sent, or non-zero if an error occurs or an invalid
6491     option is encountered.
6492
6493'wait'
6494          wait [-n] [JOBSPEC or PID ...]
6495
6496     Wait until the child process specified by each process ID PID or
6497     job specification JOBSPEC exits and return the exit status of the
6498     last command waited for.  If a job spec is given, all processes in
6499     the job are waited for.  If no arguments are given, all currently
6500     active child processes are waited for, and the return status is
6501     zero.  If the '-n' option is supplied, 'wait' waits for any job to
6502     terminate and returns its exit status.  If neither JOBSPEC nor PID
6503     specifies an active child process of the shell, the return status
6504     is 127.
6505
6506'disown'
6507          disown [-ar] [-h] [JOBSPEC ... | PID ... ]
6508
6509     Without options, remove each JOBSPEC from the table of active jobs.
6510     If the '-h' option is given, the job is not removed from the table,
6511     but is marked so that 'SIGHUP' is not sent to the job if the shell
6512     receives a 'SIGHUP'.  If JOBSPEC is not present, and neither the
6513     '-a' nor the '-r' option is supplied, the current job is used.  If
6514     no JOBSPEC is supplied, the '-a' option means to remove or mark all
6515     jobs; the '-r' option without a JOBSPEC argument restricts
6516     operation to running jobs.
6517
6518'suspend'
6519          suspend [-f]
6520
6521     Suspend the execution of this shell until it receives a 'SIGCONT'
6522     signal.  A login shell cannot be suspended; the '-f' option can be
6523     used to override this and force the suspension.
6524
6525   When job control is not active, the 'kill' and 'wait' builtins do not
6526accept JOBSPEC arguments.  They must be supplied process IDs.
6527
65287.3 Job Control Variables
6529=========================
6530
6531'auto_resume'
6532     This variable controls how the shell interacts with the user and
6533     job control.  If this variable exists then single word simple
6534     commands without redirections are treated as candidates for
6535     resumption of an existing job.  There is no ambiguity allowed; if
6536     there is more than one job beginning with the string typed, then
6537     the most recently accessed job will be selected.  The name of a
6538     stopped job, in this context, is the command line used to start it.
6539     If this variable is set to the value 'exact', the string supplied
6540     must match the name of a stopped job exactly; if set to
6541     'substring', the string supplied needs to match a substring of the
6542     name of a stopped job.  The 'substring' value provides
6543     functionality analogous to the '%?' job ID (*note Job Control
6544     Basics::).  If set to any other value, the supplied string must be
6545     a prefix of a stopped job's name; this provides functionality
6546     analogous to the '%' job ID.
6547
65488 Command Line Editing
6549**********************
6550
6551This chapter describes the basic features of the GNU command line
6552editing interface.  Command line editing is provided by the Readline
6553library, which is used by several different programs, including Bash.
6554Command line editing is enabled by default when using an interactive
6555shell, unless the '--noediting' option is supplied at shell invocation.
6556Line editing is also used when using the '-e' option to the 'read'
6557builtin command (*note Bash Builtins::).  By default, the line editing
6558commands are similar to those of Emacs.  A vi-style line editing
6559interface is also available.  Line editing can be enabled at any time
6560using the '-o emacs' or '-o vi' options to the 'set' builtin command
6561(*note The Set Builtin::), or disabled using the '+o emacs' or '+o vi'
6562options to 'set'.
6563
65648.1 Introduction to Line Editing
6565================================
6566
6567The following paragraphs describe the notation used to represent
6568keystrokes.
6569
6570   The text 'C-k' is read as 'Control-K' and describes the character
6571produced when the <k> key is pressed while the Control key is depressed.
6572
6573   The text 'M-k' is read as 'Meta-K' and describes the character
6574produced when the Meta key (if you have one) is depressed, and the <k>
6575key is pressed.  The Meta key is labeled <ALT> on many keyboards.  On
6576keyboards with two keys labeled <ALT> (usually to either side of the
6577space bar), the <ALT> on the left side is generally set to work as a
6578Meta key.  The <ALT> key on the right may also be configured to work as
6579a Meta key or may be configured as some other modifier, such as a
6580Compose key for typing accented characters.
6581
6582   If you do not have a Meta or <ALT> key, or another key working as a
6583Meta key, the identical keystroke can be generated by typing <ESC>
6584_first_, and then typing <k>.  Either process is known as "metafying"
6585the <k> key.
6586
6587   The text 'M-C-k' is read as 'Meta-Control-k' and describes the
6588character produced by "metafying" 'C-k'.
6589
6590   In addition, several keys have their own names.  Specifically, <DEL>,
6591<ESC>, <LFD>, <SPC>, <RET>, and <TAB> all stand for themselves when seen
6592in this text, or in an init file (*note Readline Init File::).  If your
6593keyboard lacks a <LFD> key, typing <C-j> will produce the desired
6594character.  The <RET> key may be labeled <Return> or <Enter> on some
6595keyboards.
6596
65978.2 Readline Interaction
6598========================
6599
6600Often during an interactive session you type in a long line of text,
6601only to notice that the first word on the line is misspelled.  The
6602Readline library gives you a set of commands for manipulating the text
6603as you type it in, allowing you to just fix your typo, and not forcing
6604you to retype the majority of the line.  Using these editing commands,
6605you move the cursor to the place that needs correction, and delete or
6606insert the text of the corrections.  Then, when you are satisfied with
6607the line, you simply press <RET>.  You do not have to be at the end of
6608the line to press <RET>; the entire line is accepted regardless of the
6609location of the cursor within the line.
6610
66118.2.1 Readline Bare Essentials
6612------------------------------
6613
6614In order to enter characters into the line, simply type them.  The typed
6615character appears where the cursor was, and then the cursor moves one
6616space to the right.  If you mistype a character, you can use your erase
6617character to back up and delete the mistyped character.
6618
6619   Sometimes you may mistype a character, and not notice the error until
6620you have typed several other characters.  In that case, you can type
6621'C-b' to move the cursor to the left, and then correct your mistake.
6622Afterwards, you can move the cursor to the right with 'C-f'.
6623
6624   When you add text in the middle of a line, you will notice that
6625characters to the right of the cursor are 'pushed over' to make room for
6626the text that you have inserted.  Likewise, when you delete text behind
6627the cursor, characters to the right of the cursor are 'pulled back' to
6628fill in the blank space created by the removal of the text.  A list of
6629the bare essentials for editing the text of an input line follows.
6630
6631'C-b'
6632     Move back one character.
6633'C-f'
6634     Move forward one character.
6635<DEL> or <Backspace>
6636     Delete the character to the left of the cursor.
6637'C-d'
6638     Delete the character underneath the cursor.
6639Printing characters
6640     Insert the character into the line at the cursor.
6641'C-_' or 'C-x C-u'
6642     Undo the last editing command.  You can undo all the way back to an
6643     empty line.
6644
6645(Depending on your configuration, the <Backspace> key be set to delete
6646the character to the left of the cursor and the <DEL> key set to delete
6647the character underneath the cursor, like 'C-d', rather than the
6648character to the left of the cursor.)
6649
66508.2.2 Readline Movement Commands
6651--------------------------------
6652
6653The above table describes the most basic keystrokes that you need in
6654order to do editing of the input line.  For your convenience, many other
6655commands have been added in addition to 'C-b', 'C-f', 'C-d', and <DEL>.
6656Here are some commands for moving more rapidly about the line.
6657
6658'C-a'
6659     Move to the start of the line.
6660'C-e'
6661     Move to the end of the line.
6662'M-f'
6663     Move forward a word, where a word is composed of letters and
6664     digits.
6665'M-b'
6666     Move backward a word.
6667'C-l'
6668     Clear the screen, reprinting the current line at the top.
6669
6670   Notice how 'C-f' moves forward a character, while 'M-f' moves forward
6671a word.  It is a loose convention that control keystrokes operate on
6672characters while meta keystrokes operate on words.
6673
66748.2.3 Readline Killing Commands
6675-------------------------------
6676
6677"Killing" text means to delete the text from the line, but to save it
6678away for later use, usually by "yanking" (re-inserting) it back into the
6679line.  ('Cut' and 'paste' are more recent jargon for 'kill' and 'yank'.)
6680
6681   If the description for a command says that it 'kills' text, then you
6682can be sure that you can get the text back in a different (or the same)
6683place later.
6684
6685   When you use a kill command, the text is saved in a "kill-ring".  Any
6686number of consecutive kills save all of the killed text together, so
6687that when you yank it back, you get it all.  The kill ring is not line
6688specific; the text that you killed on a previously typed line is
6689available to be yanked back later, when you are typing another line.
6690
6691   Here is the list of commands for killing text.
6692
6693'C-k'
6694     Kill the text from the current cursor position to the end of the
6695     line.
6696
6697'M-d'
6698     Kill from the cursor to the end of the current word, or, if between
6699     words, to the end of the next word.  Word boundaries are the same
6700     as those used by 'M-f'.
6701
6702'M-<DEL>'
6703     Kill from the cursor the start of the current word, or, if between
6704     words, to the start of the previous word.  Word boundaries are the
6705     same as those used by 'M-b'.
6706
6707'C-w'
6708     Kill from the cursor to the previous whitespace.  This is different
6709     than 'M-<DEL>' because the word boundaries differ.
6710
6711   Here is how to "yank" the text back into the line.  Yanking means to
6712copy the most-recently-killed text from the kill buffer.
6713
6714'C-y'
6715     Yank the most recently killed text back into the buffer at the
6716     cursor.
6717
6718'M-y'
6719     Rotate the kill-ring, and yank the new top.  You can only do this
6720     if the prior command is 'C-y' or 'M-y'.
6721
67228.2.4 Readline Arguments
6723------------------------
6724
6725You can pass numeric arguments to Readline commands.  Sometimes the
6726argument acts as a repeat count, other times it is the sign of the
6727argument that is significant.  If you pass a negative argument to a
6728command which normally acts in a forward direction, that command will
6729act in a backward direction.  For example, to kill text back to the
6730start of the line, you might type 'M-- C-k'.
6731
6732   The general way to pass numeric arguments to a command is to type
6733meta digits before the command.  If the first 'digit' typed is a minus
6734sign ('-'), then the sign of the argument will be negative.  Once you
6735have typed one meta digit to get the argument started, you can type the
6736remainder of the digits, and then the command.  For example, to give the
6737'C-d' command an argument of 10, you could type 'M-1 0 C-d', which will
6738delete the next ten characters on the input line.
6739
67408.2.5 Searching for Commands in the History
6741-------------------------------------------
6742
6743Readline provides commands for searching through the command history
6744(*note Bash History Facilities::) for lines containing a specified
6745string.  There are two search modes: "incremental" and
6746"non-incremental".
6747
6748   Incremental searches begin before the user has finished typing the
6749search string.  As each character of the search string is typed,
6750Readline displays the next entry from the history matching the string
6751typed so far.  An incremental search requires only as many characters as
6752needed to find the desired history entry.  To search backward in the
6753history for a particular string, type 'C-r'.  Typing 'C-s' searches
6754forward through the history.  The characters present in the value of the
6755'isearch-terminators' variable are used to terminate an incremental
6756search.  If that variable has not been assigned a value, the <ESC> and
6757'C-J' characters will terminate an incremental search.  'C-g' will abort
6758an incremental search and restore the original line.  When the search is
6759terminated, the history entry containing the search string becomes the
6760current line.
6761
6762   To find other matching entries in the history list, type 'C-r' or
6763'C-s' as appropriate.  This will search backward or forward in the
6764history for the next entry matching the search string typed so far.  Any
6765other key sequence bound to a Readline command will terminate the search
6766and execute that command.  For instance, a <RET> will terminate the
6767search and accept the line, thereby executing the command from the
6768history list.  A movement command will terminate the search, make the
6769last line found the current line, and begin editing.
6770
6771   Readline remembers the last incremental search string.  If two 'C-r's
6772are typed without any intervening characters defining a new search
6773string, any remembered search string is used.
6774
6775   Non-incremental searches read the entire search string before
6776starting to search for matching history lines.  The search string may be
6777typed by the user or be part of the contents of the current line.
6778
67798.3 Readline Init File
6780======================
6781
6782Although the Readline library comes with a set of Emacs-like keybindings
6783installed by default, it is possible to use a different set of
6784keybindings.  Any user can customize programs that use Readline by
6785putting commands in an "inputrc" file, conventionally in his home
6786directory.  The name of this file is taken from the value of the shell
6787variable 'INPUTRC'.  If that variable is unset, the default is
6788'~/.inputrc'.  If that file does not exist or cannot be read, the
6789ultimate default is '/etc/inputrc'.
6790
6791   When a program which uses the Readline library starts up, the init
6792file is read, and the key bindings are set.
6793
6794   In addition, the 'C-x C-r' command re-reads this init file, thus
6795incorporating any changes that you might have made to it.
6796
67978.3.1 Readline Init File Syntax
6798-------------------------------
6799
6800There are only a few basic constructs allowed in the Readline init file.
6801Blank lines are ignored.  Lines beginning with a '#' are comments.
6802Lines beginning with a '$' indicate conditional constructs (*note
6803Conditional Init Constructs::).  Other lines denote variable settings
6804and key bindings.
6805
6806Variable Settings
6807     You can modify the run-time behavior of Readline by altering the
6808     values of variables in Readline using the 'set' command within the
6809     init file.  The syntax is simple:
6810
6811          set VARIABLE VALUE
6812
6813     Here, for example, is how to change from the default Emacs-like key
6814     binding to use 'vi' line editing commands:
6815
6816          set editing-mode vi
6817
6818     Variable names and values, where appropriate, are recognized
6819     without regard to case.  Unrecognized variable names are ignored.
6820
6821     Boolean variables (those that can be set to on or off) are set to
6822     on if the value is null or empty, ON (case-insensitive), or 1.  Any
6823     other value results in the variable being set to off.
6824
6825     The 'bind -V' command lists the current Readline variable names and
6826     values.  *Note Bash Builtins::.
6827
6828     A great deal of run-time behavior is changeable with the following
6829     variables.
6830
6831     'bell-style'
6832          Controls what happens when Readline wants to ring the terminal
6833          bell.  If set to 'none', Readline never rings the bell.  If
6834          set to 'visible', Readline uses a visible bell if one is
6835          available.  If set to 'audible' (the default), Readline
6836          attempts to ring the terminal's bell.
6837
6838     'bind-tty-special-chars'
6839          If set to 'on' (the default), Readline attempts to bind the
6840          control characters treated specially by the kernel's terminal
6841          driver to their Readline equivalents.
6842
6843     'blink-matching-paren'
6844          If set to 'on', Readline attempts to briefly move the cursor
6845          to an opening parenthesis when a closing parenthesis is
6846          inserted.  The default is 'off'.
6847
6848     'colored-completion-prefix'
6849          If set to 'on', when listing completions, Readline displays
6850          the common prefix of the set of possible completions using a
6851          different color.  The color definitions are taken from the
6852          value of the 'LS_COLORS' environment variable.  The default is
6853          'off'.
6854
6855     'colored-stats'
6856          If set to 'on', Readline displays possible completions using
6857          different colors to indicate their file type.  The color
6858          definitions are taken from the value of the 'LS_COLORS'
6859          environment variable.  The default is 'off'.
6860
6861     'comment-begin'
6862          The string to insert at the beginning of the line when the
6863          'insert-comment' command is executed.  The default value is
6864          '"#"'.
6865
6866     'completion-display-width'
6867          The number of screen columns used to display possible matches
6868          when performing completion.  The value is ignored if it is
6869          less than 0 or greater than the terminal screen width.  A
6870          value of 0 will cause matches to be displayed one per line.
6871          The default value is -1.
6872
6873     'completion-ignore-case'
6874          If set to 'on', Readline performs filename matching and
6875          completion in a case-insensitive fashion.  The default value
6876          is 'off'.
6877
6878     'completion-map-case'
6879          If set to 'on', and COMPLETION-IGNORE-CASE is enabled,
6880          Readline treats hyphens ('-') and underscores ('_') as
6881          equivalent when performing case-insensitive filename matching
6882          and completion.
6883
6884     'completion-prefix-display-length'
6885          The length in characters of the common prefix of a list of
6886          possible completions that is displayed without modification.
6887          When set to a value greater than zero, common prefixes longer
6888          than this value are replaced with an ellipsis when displaying
6889          possible completions.
6890
6891     'completion-query-items'
6892          The number of possible completions that determines when the
6893          user is asked whether the list of possibilities should be
6894          displayed.  If the number of possible completions is greater
6895          than this value, Readline will ask the user whether or not he
6896          wishes to view them; otherwise, they are simply listed.  This
6897          variable must be set to an integer value greater than or equal
6898          to 0.  A negative value means Readline should never ask.  The
6899          default limit is '100'.
6900
6901     'convert-meta'
6902          If set to 'on', Readline will convert characters with the
6903          eighth bit set to an ASCII key sequence by stripping the
6904          eighth bit and prefixing an <ESC> character, converting them
6905          to a meta-prefixed key sequence.  The default value is 'on',
6906          but will be set to 'off' if the locale is one that contains
6907          eight-bit characters.
6908
6909     'disable-completion'
6910          If set to 'On', Readline will inhibit word completion.
6911          Completion characters will be inserted into the line as if
6912          they had been mapped to 'self-insert'.  The default is 'off'.
6913
6914     'echo-control-characters'
6915          When set to 'on', on operating systems that indicate they
6916          support it, readline echoes a character corresponding to a
6917          signal generated from the keyboard.  The default is 'on'.
6918
6919     'editing-mode'
6920          The 'editing-mode' variable controls which default set of key
6921          bindings is used.  By default, Readline starts up in Emacs
6922          editing mode, where the keystrokes are most similar to Emacs.
6923          This variable can be set to either 'emacs' or 'vi'.
6924
6925     'emacs-mode-string'
6926          This string is displayed immediately before the last line of
6927          the primary prompt when emacs editing mode is active.  The
6928          value is expanded like a key binding, so the standard set of
6929          meta- and control prefixes and backslash escape sequences is
6930          available.  Use the '\1' and '\2' escapes to begin and end
6931          sequences of non-printing characters, which can be used to
6932          embed a terminal control sequence into the mode string.  The
6933          default is '@'.
6934
6935     'enable-bracketed-paste'
6936          When set to 'On', Readline will configure the terminal in a
6937          way that will enable it to insert each paste into the editing
6938          buffer as a single string of characters, instead of treating
6939          each character as if it had been read from the keyboard.  This
6940          can prevent pasted characters from being interpreted as
6941          editing commands.  The default is 'off'.
6942
6943     'enable-keypad'
6944          When set to 'on', Readline will try to enable the application
6945          keypad when it is called.  Some systems need this to enable
6946          the arrow keys.  The default is 'off'.
6947
6948     'enable-meta-key'
6949          When set to 'on', Readline will try to enable any meta
6950          modifier key the terminal claims to support when it is called.
6951          On many terminals, the meta key is used to send eight-bit
6952          characters.  The default is 'on'.
6953
6954     'expand-tilde'
6955          If set to 'on', tilde expansion is performed when Readline
6956          attempts word completion.  The default is 'off'.
6957
6958     'history-preserve-point'
6959          If set to 'on', the history code attempts to place the point
6960          (the current cursor position) at the same location on each
6961          history line retrieved with 'previous-history' or
6962          'next-history'.  The default is 'off'.
6963
6964     'history-size'
6965          Set the maximum number of history entries saved in the history
6966          list.  If set to zero, any existing history entries are
6967          deleted and no new entries are saved.  If set to a value less
6968          than zero, the number of history entries is not limited.  By
6969          default, the number of history entries is not limited.  If an
6970          attempt is made to set HISTORY-SIZE to a non-numeric value,
6971          the maximum number of history entries will be set to 500.
6972
6973     'horizontal-scroll-mode'
6974          This variable can be set to either 'on' or 'off'.  Setting it
6975          to 'on' means that the text of the lines being edited will
6976          scroll horizontally on a single screen line when they are
6977          longer than the width of the screen, instead of wrapping onto
6978          a new screen line.  By default, this variable is set to 'off'.
6979
6980     'input-meta'
6981          If set to 'on', Readline will enable eight-bit input (it will
6982          not clear the eighth bit in the characters it reads),
6983          regardless of what the terminal claims it can support.  The
6984          default value is 'off', but Readline will set it to 'on' if
6985          the locale contains eight-bit characters.  The name
6986          'meta-flag' is a synonym for this variable.
6987
6988     'isearch-terminators'
6989          The string of characters that should terminate an incremental
6990          search without subsequently executing the character as a
6991          command (*note Searching::).  If this variable has not been
6992          given a value, the characters <ESC> and 'C-J' will terminate
6993          an incremental search.
6994
6995     'keymap'
6996          Sets Readline's idea of the current keymap for key binding
6997          commands.  Acceptable 'keymap' names are 'emacs',
6998          'emacs-standard', 'emacs-meta', 'emacs-ctlx', 'vi', 'vi-move',
6999          'vi-command', and 'vi-insert'.  'vi' is equivalent to
7000          'vi-command' ('vi-move' is also a synonym); 'emacs' is
7001          equivalent to 'emacs-standard'.  The default value is 'emacs'.
7002          The value of the 'editing-mode' variable also affects the
7003          default keymap.
7004
7005     'keyseq-timeout'
7006          Specifies the duration Readline will wait for a character when
7007          reading an ambiguous key sequence (one that can form a
7008          complete key sequence using the input read so far, or can take
7009          additional input to complete a longer key sequence).  If no
7010          input is received within the timeout, Readline will use the
7011          shorter but complete key sequence.  Readline uses this value
7012          to determine whether or not input is available on the current
7013          input source ('rl_instream' by default).  The value is
7014          specified in milliseconds, so a value of 1000 means that
7015          Readline will wait one second for additional input.  If this
7016          variable is set to a value less than or equal to zero, or to a
7017          non-numeric value, Readline will wait until another key is
7018          pressed to decide which key sequence to complete.  The default
7019          value is '500'.
7020
7021     'mark-directories'
7022          If set to 'on', completed directory names have a slash
7023          appended.  The default is 'on'.
7024
7025     'mark-modified-lines'
7026          This variable, when set to 'on', causes Readline to display an
7027          asterisk ('*') at the start of history lines which have been
7028          modified.  This variable is 'off' by default.
7029
7030     'mark-symlinked-directories'
7031          If set to 'on', completed names which are symbolic links to
7032          directories have a slash appended (subject to the value of
7033          'mark-directories').  The default is 'off'.
7034
7035     'match-hidden-files'
7036          This variable, when set to 'on', causes Readline to match
7037          files whose names begin with a '.' (hidden files) when
7038          performing filename completion.  If set to 'off', the leading
7039          '.' must be supplied by the user in the filename to be
7040          completed.  This variable is 'on' by default.
7041
7042     'menu-complete-display-prefix'
7043          If set to 'on', menu completion displays the common prefix of
7044          the list of possible completions (which may be empty) before
7045          cycling through the list.  The default is 'off'.
7046
7047     'output-meta'
7048          If set to 'on', Readline will display characters with the
7049          eighth bit set directly rather than as a meta-prefixed escape
7050          sequence.  The default is 'off', but Readline will set it to
7051          'on' if the locale contains eight-bit characters.
7052
7053     'page-completions'
7054          If set to 'on', Readline uses an internal 'more'-like pager to
7055          display a screenful of possible completions at a time.  This
7056          variable is 'on' by default.
7057
7058     'print-completions-horizontally'
7059          If set to 'on', Readline will display completions with matches
7060          sorted horizontally in alphabetical order, rather than down
7061          the screen.  The default is 'off'.
7062
7063     'revert-all-at-newline'
7064          If set to 'on', Readline will undo all changes to history
7065          lines before returning when 'accept-line' is executed.  By
7066          default, history lines may be modified and retain individual
7067          undo lists across calls to 'readline'.  The default is 'off'.
7068
7069     'show-all-if-ambiguous'
7070          This alters the default behavior of the completion functions.
7071          If set to 'on', words which have more than one possible
7072          completion cause the matches to be listed immediately instead
7073          of ringing the bell.  The default value is 'off'.
7074
7075     'show-all-if-unmodified'
7076          This alters the default behavior of the completion functions
7077          in a fashion similar to SHOW-ALL-IF-AMBIGUOUS.  If set to
7078          'on', words which have more than one possible completion
7079          without any possible partial completion (the possible
7080          completions don't share a common prefix) cause the matches to
7081          be listed immediately instead of ringing the bell.  The
7082          default value is 'off'.
7083
7084     'show-mode-in-prompt'
7085          If set to 'on', add a character to the beginning of the prompt
7086          indicating the editing mode: emacs, vi command, or vi
7087          insertion.  The mode strings are user-settable.  The default
7088          value is 'off'.
7089
7090     'skip-completed-text'
7091          If set to 'on', this alters the default completion behavior
7092          when inserting a single match into the line.  It's only active
7093          when performing completion in the middle of a word.  If
7094          enabled, readline does not insert characters from the
7095          completion that match characters after point in the word being
7096          completed, so portions of the word following the cursor are
7097          not duplicated.  For instance, if this is enabled, attempting
7098          completion when the cursor is after the 'e' in 'Makefile' will
7099          result in 'Makefile' rather than 'Makefilefile', assuming
7100          there is a single possible completion.  The default value is
7101          'off'.
7102
7103     'vi-cmd-mode-string'
7104          This string is displayed immediately before the last line of
7105          the primary prompt when vi editing mode is active and in
7106          command mode.  The value is expanded like a key binding, so
7107          the standard set of meta- and control prefixes and backslash
7108          escape sequences is available.  Use the '\1' and '\2' escapes
7109          to begin and end sequences of non-printing characters, which
7110          can be used to embed a terminal control sequence into the mode
7111          string.  The default is '(cmd)'.
7112
7113     'vi-ins-mode-string'
7114          This string is displayed immediately before the last line of
7115          the primary prompt when vi editing mode is active and in
7116          insertion mode.  The value is expanded like a key binding, so
7117          the standard set of meta- and control prefixes and backslash
7118          escape sequences is available.  Use the '\1' and '\2' escapes
7119          to begin and end sequences of non-printing characters, which
7120          can be used to embed a terminal control sequence into the mode
7121          string.  The default is '(ins)'.
7122
7123     'visible-stats'
7124          If set to 'on', a character denoting a file's type is appended
7125          to the filename when listing possible completions.  The
7126          default is 'off'.
7127
7128Key Bindings
7129     The syntax for controlling key bindings in the init file is simple.
7130     First you need to find the name of the command that you want to
7131     change.  The following sections contain tables of the command name,
7132     the default keybinding, if any, and a short description of what the
7133     command does.
7134
7135     Once you know the name of the command, simply place on a line in
7136     the init file the name of the key you wish to bind the command to,
7137     a colon, and then the name of the command.  There can be no space
7138     between the key name and the colon - that will be interpreted as
7139     part of the key name.  The name of the key can be expressed in
7140     different ways, depending on what you find most comfortable.
7141
7142     In addition to command names, readline allows keys to be bound to a
7143     string that is inserted when the key is pressed (a MACRO).
7144
7145     The 'bind -p' command displays Readline function names and bindings
7146     in a format that can put directly into an initialization file.
7147     *Note Bash Builtins::.
7148
7149     KEYNAME: FUNCTION-NAME or MACRO
7150          KEYNAME is the name of a key spelled out in English.  For
7151          example:
7152               Control-u: universal-argument
7153               Meta-Rubout: backward-kill-word
7154               Control-o: "> output"
7155
7156          In the above example, 'C-u' is bound to the function
7157          'universal-argument', 'M-DEL' is bound to the function
7158          'backward-kill-word', and 'C-o' is bound to run the macro
7159          expressed on the right hand side (that is, to insert the text
7160          '> output' into the line).
7161
7162          A number of symbolic character names are recognized while
7163          processing this key binding syntax: DEL, ESC, ESCAPE, LFD,
7164          NEWLINE, RET, RETURN, RUBOUT, SPACE, SPC, and TAB.
7165
7166     "KEYSEQ": FUNCTION-NAME or MACRO
7167          KEYSEQ differs from KEYNAME above in that strings denoting an
7168          entire key sequence can be specified, by placing the key
7169          sequence in double quotes.  Some GNU Emacs style key escapes
7170          can be used, as in the following example, but the special
7171          character names are not recognized.
7172
7173               "\C-u": universal-argument
7174               "\C-x\C-r": re-read-init-file
7175               "\e[11~": "Function Key 1"
7176
7177          In the above example, 'C-u' is again bound to the function
7178          'universal-argument' (just as it was in the first example),
7179          ''C-x' 'C-r'' is bound to the function 're-read-init-file',
7180          and '<ESC> <[> <1> <1> <~>' is bound to insert the text
7181          'Function Key 1'.
7182
7183     The following GNU Emacs style escape sequences are available when
7184     specifying key sequences:
7185
7186     '\C-'
7187          control prefix
7188     '\M-'
7189          meta prefix
7190     '\e'
7191          an escape character
7192     '\\'
7193          backslash
7194     '\"'
7195          <">, a double quotation mark
7196     '\''
7197          <'>, a single quote or apostrophe
7198
7199     In addition to the GNU Emacs style escape sequences, a second set
7200     of backslash escapes is available:
7201
7202     '\a'
7203          alert (bell)
7204     '\b'
7205          backspace
7206     '\d'
7207          delete
7208     '\f'
7209          form feed
7210     '\n'
7211          newline
7212     '\r'
7213          carriage return
7214     '\t'
7215          horizontal tab
7216     '\v'
7217          vertical tab
7218     '\NNN'
7219          the eight-bit character whose value is the octal value NNN
7220          (one to three digits)
7221     '\xHH'
7222          the eight-bit character whose value is the hexadecimal value
7223          HH (one or two hex digits)
7224
7225     When entering the text of a macro, single or double quotes must be
7226     used to indicate a macro definition.  Unquoted text is assumed to
7227     be a function name.  In the macro body, the backslash escapes
7228     described above are expanded.  Backslash will quote any other
7229     character in the macro text, including '"' and '''.  For example,
7230     the following binding will make ''C-x' \' insert a single '\' into
7231     the line:
7232          "\C-x\\": "\\"
7233
72348.3.2 Conditional Init Constructs
7235---------------------------------
7236
7237Readline implements a facility similar in spirit to the conditional
7238compilation features of the C preprocessor which allows key bindings and
7239variable settings to be performed as the result of tests.  There are
7240four parser directives used.
7241
7242'$if'
7243     The '$if' construct allows bindings to be made based on the editing
7244     mode, the terminal being used, or the application using Readline.
7245     The text of the test extends to the end of the line; no characters
7246     are required to isolate it.
7247
7248     'mode'
7249          The 'mode=' form of the '$if' directive is used to test
7250          whether Readline is in 'emacs' or 'vi' mode.  This may be used
7251          in conjunction with the 'set keymap' command, for instance, to
7252          set bindings in the 'emacs-standard' and 'emacs-ctlx' keymaps
7253          only if Readline is starting out in 'emacs' mode.
7254
7255     'term'
7256          The 'term=' form may be used to include terminal-specific key
7257          bindings, perhaps to bind the key sequences output by the
7258          terminal's function keys.  The word on the right side of the
7259          '=' is tested against both the full name of the terminal and
7260          the portion of the terminal name before the first '-'.  This
7261          allows 'sun' to match both 'sun' and 'sun-cmd', for instance.
7262
7263     'application'
7264          The APPLICATION construct is used to include
7265          application-specific settings.  Each program using the
7266          Readline library sets the APPLICATION NAME, and you can test
7267          for a particular value.  This could be used to bind key
7268          sequences to functions useful for a specific program.  For
7269          instance, the following command adds a key sequence that
7270          quotes the current or previous word in Bash:
7271               $if Bash
7272               # Quote the current or previous word
7273               "\C-xq": "\eb\"\ef\""
7274               $endif
7275
7276'$endif'
7277     This command, as seen in the previous example, terminates an '$if'
7278     command.
7279
7280'$else'
7281     Commands in this branch of the '$if' directive are executed if the
7282     test fails.
7283
7284'$include'
7285     This directive takes a single filename as an argument and reads
7286     commands and bindings from that file.  For example, the following
7287     directive reads from '/etc/inputrc':
7288          $include /etc/inputrc
7289
72908.3.3 Sample Init File
7291----------------------
7292
7293Here is an example of an INPUTRC file.  This illustrates key binding,
7294variable assignment, and conditional syntax.
7295
7296     # This file controls the behaviour of line input editing for
7297     # programs that use the GNU Readline library.  Existing
7298     # programs include FTP, Bash, and GDB.
7299     #
7300     # You can re-read the inputrc file with C-x C-r.
7301     # Lines beginning with '#' are comments.
7302     #
7303     # First, include any system-wide bindings and variable
7304     # assignments from /etc/Inputrc
7305     $include /etc/Inputrc
7306
7307     #
7308     # Set various bindings for emacs mode.
7309
7310     set editing-mode emacs
7311
7312     $if mode=emacs
7313
7314     Meta-Control-h:	backward-kill-word	Text after the function name is ignored
7315
7316     #
7317     # Arrow keys in keypad mode
7318     #
7319     #"\M-OD":        backward-char
7320     #"\M-OC":        forward-char
7321     #"\M-OA":        previous-history
7322     #"\M-OB":        next-history
7323     #
7324     # Arrow keys in ANSI mode
7325     #
7326     "\M-[D":        backward-char
7327     "\M-[C":        forward-char
7328     "\M-[A":        previous-history
7329     "\M-[B":        next-history
7330     #
7331     # Arrow keys in 8 bit keypad mode
7332     #
7333     #"\M-\C-OD":       backward-char
7334     #"\M-\C-OC":       forward-char
7335     #"\M-\C-OA":       previous-history
7336     #"\M-\C-OB":       next-history
7337     #
7338     # Arrow keys in 8 bit ANSI mode
7339     #
7340     #"\M-\C-[D":       backward-char
7341     #"\M-\C-[C":       forward-char
7342     #"\M-\C-[A":       previous-history
7343     #"\M-\C-[B":       next-history
7344
7345     C-q: quoted-insert
7346
7347     $endif
7348
7349     # An old-style binding.  This happens to be the default.
7350     TAB: complete
7351
7352     # Macros that are convenient for shell interaction
7353     $if Bash
7354     # edit the path
7355     "\C-xp": "PATH=${PATH}\e\C-e\C-a\ef\C-f"
7356     # prepare to type a quoted word --
7357     # insert open and close double quotes
7358     # and move to just after the open quote
7359     "\C-x\"": "\"\"\C-b"
7360     # insert a backslash (testing backslash escapes
7361     # in sequences and macros)
7362     "\C-x\\": "\\"
7363     # Quote the current or previous word
7364     "\C-xq": "\eb\"\ef\""
7365     # Add a binding to refresh the line, which is unbound
7366     "\C-xr": redraw-current-line
7367     # Edit variable on current line.
7368     "\M-\C-v": "\C-a\C-k$\C-y\M-\C-e\C-a\C-y="
7369     $endif
7370
7371     # use a visible bell if one is available
7372     set bell-style visible
7373
7374     # don't strip characters to 7 bits when reading
7375     set input-meta on
7376
7377     # allow iso-latin1 characters to be inserted rather
7378     # than converted to prefix-meta sequences
7379     set convert-meta off
7380
7381     # display characters with the eighth bit set directly
7382     # rather than as meta-prefixed characters
7383     set output-meta on
7384
7385     # if there are more than 150 possible completions for
7386     # a word, ask the user if he wants to see all of them
7387     set completion-query-items 150
7388
7389     # For FTP
7390     $if Ftp
7391     "\C-xg": "get \M-?"
7392     "\C-xt": "put \M-?"
7393     "\M-.": yank-last-arg
7394     $endif
7395
73968.4 Bindable Readline Commands
7397==============================
7398
7399This section describes Readline commands that may be bound to key
7400sequences.  You can list your key bindings by executing 'bind -P' or,
7401for a more terse format, suitable for an INPUTRC file, 'bind -p'.
7402(*Note Bash Builtins::.)  Command names without an accompanying key
7403sequence are unbound by default.
7404
7405   In the following descriptions, "point" refers to the current cursor
7406position, and "mark" refers to a cursor position saved by the 'set-mark'
7407command.  The text between the point and mark is referred to as the
7408"region".
7409
74108.4.1 Commands For Moving
7411-------------------------
7412
7413'beginning-of-line (C-a)'
7414     Move to the start of the current line.
7415
7416'end-of-line (C-e)'
7417     Move to the end of the line.
7418
7419'forward-char (C-f)'
7420     Move forward a character.
7421
7422'backward-char (C-b)'
7423     Move back a character.
7424
7425'forward-word (M-f)'
7426     Move forward to the end of the next word.  Words are composed of
7427     letters and digits.
7428
7429'backward-word (M-b)'
7430     Move back to the start of the current or previous word.  Words are
7431     composed of letters and digits.
7432
7433'shell-forward-word ()'
7434     Move forward to the end of the next word.  Words are delimited by
7435     non-quoted shell metacharacters.
7436
7437'shell-backward-word ()'
7438     Move back to the start of the current or previous word.  Words are
7439     delimited by non-quoted shell metacharacters.
7440
7441'clear-screen (C-l)'
7442     Clear the screen and redraw the current line, leaving the current
7443     line at the top of the screen.
7444
7445'redraw-current-line ()'
7446     Refresh the current line.  By default, this is unbound.
7447
74488.4.2 Commands For Manipulating The History
7449-------------------------------------------
7450
7451'accept-line (Newline or Return)'
7452     Accept the line regardless of where the cursor is.  If this line is
7453     non-empty, add it to the history list according to the setting of
7454     the 'HISTCONTROL' and 'HISTIGNORE' variables.  If this line is a
7455     modified history line, then restore the history line to its
7456     original state.
7457
7458'previous-history (C-p)'
7459     Move 'back' through the history list, fetching the previous
7460     command.
7461
7462'next-history (C-n)'
7463     Move 'forward' through the history list, fetching the next command.
7464
7465'beginning-of-history (M-<)'
7466     Move to the first line in the history.
7467
7468'end-of-history (M->)'
7469     Move to the end of the input history, i.e., the line currently
7470     being entered.
7471
7472'reverse-search-history (C-r)'
7473     Search backward starting at the current line and moving 'up'
7474     through the history as necessary.  This is an incremental search.
7475
7476'forward-search-history (C-s)'
7477     Search forward starting at the current line and moving 'down'
7478     through the history as necessary.  This is an incremental search.
7479
7480'non-incremental-reverse-search-history (M-p)'
7481     Search backward starting at the current line and moving 'up'
7482     through the history as necessary using a non-incremental search for
7483     a string supplied by the user.  The search string may match
7484     anywhere in a history line.
7485
7486'non-incremental-forward-search-history (M-n)'
7487     Search forward starting at the current line and moving 'down'
7488     through the history as necessary using a non-incremental search for
7489     a string supplied by the user.  The search string may match
7490     anywhere in a history line.
7491
7492'history-search-forward ()'
7493     Search forward through the history for the string of characters
7494     between the start of the current line and the point.  The search
7495     string must match at the beginning of a history line.  This is a
7496     non-incremental search.  By default, this command is unbound.
7497
7498'history-search-backward ()'
7499     Search backward through the history for the string of characters
7500     between the start of the current line and the point.  The search
7501     string must match at the beginning of a history line.  This is a
7502     non-incremental search.  By default, this command is unbound.
7503
7504'history-substr-search-forward ()'
7505     Search forward through the history for the string of characters
7506     between the start of the current line and the point.  The search
7507     string may match anywhere in a history line.  This is a
7508     non-incremental search.  By default, this command is unbound.
7509
7510'history-substr-search-backward ()'
7511     Search backward through the history for the string of characters
7512     between the start of the current line and the point.  The search
7513     string may match anywhere in a history line.  This is a
7514     non-incremental search.  By default, this command is unbound.
7515
7516'yank-nth-arg (M-C-y)'
7517     Insert the first argument to the previous command (usually the
7518     second word on the previous line) at point.  With an argument N,
7519     insert the Nth word from the previous command (the words in the
7520     previous command begin with word 0).  A negative argument inserts
7521     the Nth word from the end of the previous command.  Once the
7522     argument N is computed, the argument is extracted as if the '!N'
7523     history expansion had been specified.
7524
7525'yank-last-arg (M-. or M-_)'
7526     Insert last argument to the previous command (the last word of the
7527     previous history entry).  With a numeric argument, behave exactly
7528     like 'yank-nth-arg'.  Successive calls to 'yank-last-arg' move back
7529     through the history list, inserting the last word (or the word
7530     specified by the argument to the first call) of each line in turn.
7531     Any numeric argument supplied to these successive calls determines
7532     the direction to move through the history.  A negative argument
7533     switches the direction through the history (back or forward).  The
7534     history expansion facilities are used to extract the last argument,
7535     as if the '!$' history expansion had been specified.
7536
75378.4.3 Commands For Changing Text
7538--------------------------------
7539
7540'end-of-file (usually C-d)'
7541     The character indicating end-of-file as set, for example, by
7542     'stty'.  If this character is read when there are no characters on
7543     the line, and point is at the beginning of the line, Readline
7544     interprets it as the end of input and returns EOF.
7545
7546'delete-char (C-d)'
7547     Delete the character at point.  If this function is bound to the
7548     same character as the tty EOF character, as 'C-d' commonly is, see
7549     above for the effects.
7550
7551'backward-delete-char (Rubout)'
7552     Delete the character behind the cursor.  A numeric argument means
7553     to kill the characters instead of deleting them.
7554
7555'forward-backward-delete-char ()'
7556     Delete the character under the cursor, unless the cursor is at the
7557     end of the line, in which case the character behind the cursor is
7558     deleted.  By default, this is not bound to a key.
7559
7560'quoted-insert (C-q or C-v)'
7561     Add the next character typed to the line verbatim.  This is how to
7562     insert key sequences like 'C-q', for example.
7563
7564'self-insert (a, b, A, 1, !, ...)'
7565     Insert yourself.
7566
7567'bracketed-paste-begin ()'
7568     This function is intended to be bound to the "bracketed paste"
7569     escape sequence sent by some terminals, and such a binding is
7570     assigned by default.  It allows Readline to insert the pasted text
7571     as a single unit without treating each character as if it had been
7572     read from the keyboard.  The characters are inserted as if each one
7573     was bound to 'self-insert') instead of executing any editing
7574     commands.
7575
7576'transpose-chars (C-t)'
7577     Drag the character before the cursor forward over the character at
7578     the cursor, moving the cursor forward as well.  If the insertion
7579     point is at the end of the line, then this transposes the last two
7580     characters of the line.  Negative arguments have no effect.
7581
7582'transpose-words (M-t)'
7583     Drag the word before point past the word after point, moving point
7584     past that word as well.  If the insertion point is at the end of
7585     the line, this transposes the last two words on the line.
7586
7587'upcase-word (M-u)'
7588     Uppercase the current (or following) word.  With a negative
7589     argument, uppercase the previous word, but do not move the cursor.
7590
7591'downcase-word (M-l)'
7592     Lowercase the current (or following) word.  With a negative
7593     argument, lowercase the previous word, but do not move the cursor.
7594
7595'capitalize-word (M-c)'
7596     Capitalize the current (or following) word.  With a negative
7597     argument, capitalize the previous word, but do not move the cursor.
7598
7599'overwrite-mode ()'
7600     Toggle overwrite mode.  With an explicit positive numeric argument,
7601     switches to overwrite mode.  With an explicit non-positive numeric
7602     argument, switches to insert mode.  This command affects only
7603     'emacs' mode; 'vi' mode does overwrite differently.  Each call to
7604     'readline()' starts in insert mode.
7605
7606     In overwrite mode, characters bound to 'self-insert' replace the
7607     text at point rather than pushing the text to the right.
7608     Characters bound to 'backward-delete-char' replace the character
7609     before point with a space.
7610
7611     By default, this command is unbound.
7612
76138.4.4 Killing And Yanking
7614-------------------------
7615
7616'kill-line (C-k)'
7617     Kill the text from point to the end of the line.
7618
7619'backward-kill-line (C-x Rubout)'
7620     Kill backward from the cursor to the beginning of the current line.
7621
7622'unix-line-discard (C-u)'
7623     Kill backward from the cursor to the beginning of the current line.
7624
7625'kill-whole-line ()'
7626     Kill all characters on the current line, no matter where point is.
7627     By default, this is unbound.
7628
7629'kill-word (M-d)'
7630     Kill from point to the end of the current word, or if between
7631     words, to the end of the next word.  Word boundaries are the same
7632     as 'forward-word'.
7633
7634'backward-kill-word (M-<DEL>)'
7635     Kill the word behind point.  Word boundaries are the same as
7636     'backward-word'.
7637
7638'shell-kill-word ()'
7639     Kill from point to the end of the current word, or if between
7640     words, to the end of the next word.  Word boundaries are the same
7641     as 'shell-forward-word'.
7642
7643'shell-backward-kill-word ()'
7644     Kill the word behind point.  Word boundaries are the same as
7645     'shell-backward-word'.
7646
7647'unix-word-rubout (C-w)'
7648     Kill the word behind point, using white space as a word boundary.
7649     The killed text is saved on the kill-ring.
7650
7651'unix-filename-rubout ()'
7652     Kill the word behind point, using white space and the slash
7653     character as the word boundaries.  The killed text is saved on the
7654     kill-ring.
7655
7656'delete-horizontal-space ()'
7657     Delete all spaces and tabs around point.  By default, this is
7658     unbound.
7659
7660'kill-region ()'
7661     Kill the text in the current region.  By default, this command is
7662     unbound.
7663
7664'copy-region-as-kill ()'
7665     Copy the text in the region to the kill buffer, so it can be yanked
7666     right away.  By default, this command is unbound.
7667
7668'copy-backward-word ()'
7669     Copy the word before point to the kill buffer.  The word boundaries
7670     are the same as 'backward-word'.  By default, this command is
7671     unbound.
7672
7673'copy-forward-word ()'
7674     Copy the word following point to the kill buffer.  The word
7675     boundaries are the same as 'forward-word'.  By default, this
7676     command is unbound.
7677
7678'yank (C-y)'
7679     Yank the top of the kill ring into the buffer at point.
7680
7681'yank-pop (M-y)'
7682     Rotate the kill-ring, and yank the new top.  You can only do this
7683     if the prior command is 'yank' or 'yank-pop'.
7684
76858.4.5 Specifying Numeric Arguments
7686----------------------------------
7687
7688'digit-argument (M-0, M-1, ... M--)'
7689     Add this digit to the argument already accumulating, or start a new
7690     argument.  'M--' starts a negative argument.
7691
7692'universal-argument ()'
7693     This is another way to specify an argument.  If this command is
7694     followed by one or more digits, optionally with a leading minus
7695     sign, those digits define the argument.  If the command is followed
7696     by digits, executing 'universal-argument' again ends the numeric
7697     argument, but is otherwise ignored.  As a special case, if this
7698     command is immediately followed by a character that is neither a
7699     digit nor minus sign, the argument count for the next command is
7700     multiplied by four.  The argument count is initially one, so
7701     executing this function the first time makes the argument count
7702     four, a second time makes the argument count sixteen, and so on.
7703     By default, this is not bound to a key.
7704
77058.4.6 Letting Readline Type For You
7706-----------------------------------
7707
7708'complete (<TAB>)'
7709     Attempt to perform completion on the text before point.  The actual
7710     completion performed is application-specific.  Bash attempts
7711     completion treating the text as a variable (if the text begins with
7712     '$'), username (if the text begins with '~'), hostname (if the text
7713     begins with '@'), or command (including aliases and functions) in
7714     turn.  If none of these produces a match, filename completion is
7715     attempted.
7716
7717'possible-completions (M-?)'
7718     List the possible completions of the text before point.  When
7719     displaying completions, Readline sets the number of columns used
7720     for display to the value of 'completion-display-width', the value
7721     of the environment variable 'COLUMNS', or the screen width, in that
7722     order.
7723
7724'insert-completions (M-*)'
7725     Insert all completions of the text before point that would have
7726     been generated by 'possible-completions'.
7727
7728'menu-complete ()'
7729     Similar to 'complete', but replaces the word to be completed with a
7730     single match from the list of possible completions.  Repeated
7731     execution of 'menu-complete' steps through the list of possible
7732     completions, inserting each match in turn.  At the end of the list
7733     of completions, the bell is rung (subject to the setting of
7734     'bell-style') and the original text is restored.  An argument of N
7735     moves N positions forward in the list of matches; a negative
7736     argument may be used to move backward through the list.  This
7737     command is intended to be bound to <TAB>, but is unbound by
7738     default.
7739
7740'menu-complete-backward ()'
7741     Identical to 'menu-complete', but moves backward through the list
7742     of possible completions, as if 'menu-complete' had been given a
7743     negative argument.
7744
7745'delete-char-or-list ()'
7746     Deletes the character under the cursor if not at the beginning or
7747     end of the line (like 'delete-char').  If at the end of the line,
7748     behaves identically to 'possible-completions'.  This command is
7749     unbound by default.
7750
7751'complete-filename (M-/)'
7752     Attempt filename completion on the text before point.
7753
7754'possible-filename-completions (C-x /)'
7755     List the possible completions of the text before point, treating it
7756     as a filename.
7757
7758'complete-username (M-~)'
7759     Attempt completion on the text before point, treating it as a
7760     username.
7761
7762'possible-username-completions (C-x ~)'
7763     List the possible completions of the text before point, treating it
7764     as a username.
7765
7766'complete-variable (M-$)'
7767     Attempt completion on the text before point, treating it as a shell
7768     variable.
7769
7770'possible-variable-completions (C-x $)'
7771     List the possible completions of the text before point, treating it
7772     as a shell variable.
7773
7774'complete-hostname (M-@)'
7775     Attempt completion on the text before point, treating it as a
7776     hostname.
7777
7778'possible-hostname-completions (C-x @)'
7779     List the possible completions of the text before point, treating it
7780     as a hostname.
7781
7782'complete-command (M-!)'
7783     Attempt completion on the text before point, treating it as a
7784     command name.  Command completion attempts to match the text
7785     against aliases, reserved words, shell functions, shell builtins,
7786     and finally executable filenames, in that order.
7787
7788'possible-command-completions (C-x !)'
7789     List the possible completions of the text before point, treating it
7790     as a command name.
7791
7792'dynamic-complete-history (M-<TAB>)'
7793     Attempt completion on the text before point, comparing the text
7794     against lines from the history list for possible completion
7795     matches.
7796
7797'dabbrev-expand ()'
7798     Attempt menu completion on the text before point, comparing the
7799     text against lines from the history list for possible completion
7800     matches.
7801
7802'complete-into-braces (M-{)'
7803     Perform filename completion and insert the list of possible
7804     completions enclosed within braces so the list is available to the
7805     shell (*note Brace Expansion::).
7806
78078.4.7 Keyboard Macros
7808---------------------
7809
7810'start-kbd-macro (C-x ()'
7811     Begin saving the characters typed into the current keyboard macro.
7812
7813'end-kbd-macro (C-x ))'
7814     Stop saving the characters typed into the current keyboard macro
7815     and save the definition.
7816
7817'call-last-kbd-macro (C-x e)'
7818     Re-execute the last keyboard macro defined, by making the
7819     characters in the macro appear as if typed at the keyboard.
7820
7821'print-last-kbd-macro ()'
7822     Print the last keboard macro defined in a format suitable for the
7823     INPUTRC file.
7824
78258.4.8 Some Miscellaneous Commands
7826---------------------------------
7827
7828're-read-init-file (C-x C-r)'
7829     Read in the contents of the INPUTRC file, and incorporate any
7830     bindings or variable assignments found there.
7831
7832'abort (C-g)'
7833     Abort the current editing command and ring the terminal's bell
7834     (subject to the setting of 'bell-style').
7835
7836'do-uppercase-version (M-a, M-b, M-X, ...)'
7837     If the metafied character X is lowercase, run the command that is
7838     bound to the corresponding uppercase character.
7839
7840'prefix-meta (<ESC>)'
7841     Metafy the next character typed.  This is for keyboards without a
7842     meta key.  Typing '<ESC> f' is equivalent to typing 'M-f'.
7843
7844'undo (C-_ or C-x C-u)'
7845     Incremental undo, separately remembered for each line.
7846
7847'revert-line (M-r)'
7848     Undo all changes made to this line.  This is like executing the
7849     'undo' command enough times to get back to the beginning.
7850
7851'tilde-expand (M-&)'
7852     Perform tilde expansion on the current word.
7853
7854'set-mark (C-@)'
7855     Set the mark to the point.  If a numeric argument is supplied, the
7856     mark is set to that position.
7857
7858'exchange-point-and-mark (C-x C-x)'
7859     Swap the point with the mark.  The current cursor position is set
7860     to the saved position, and the old cursor position is saved as the
7861     mark.
7862
7863'character-search (C-])'
7864     A character is read and point is moved to the next occurrence of
7865     that character.  A negative count searches for previous
7866     occurrences.
7867
7868'character-search-backward (M-C-])'
7869     A character is read and point is moved to the previous occurrence
7870     of that character.  A negative count searches for subsequent
7871     occurrences.
7872
7873'skip-csi-sequence ()'
7874     Read enough characters to consume a multi-key sequence such as
7875     those defined for keys like Home and End.  Such sequences begin
7876     with a Control Sequence Indicator (CSI), usually ESC-[.  If this
7877     sequence is bound to "\e[", keys producing such sequences will have
7878     no effect unless explicitly bound to a readline command, instead of
7879     inserting stray characters into the editing buffer.  This is
7880     unbound by default, but usually bound to ESC-[.
7881
7882'insert-comment (M-#)'
7883     Without a numeric argument, the value of the 'comment-begin'
7884     variable is inserted at the beginning of the current line.  If a
7885     numeric argument is supplied, this command acts as a toggle: if the
7886     characters at the beginning of the line do not match the value of
7887     'comment-begin', the value is inserted, otherwise the characters in
7888     'comment-begin' are deleted from the beginning of the line.  In
7889     either case, the line is accepted as if a newline had been typed.
7890     The default value of 'comment-begin' causes this command to make
7891     the current line a shell comment.  If a numeric argument causes the
7892     comment character to be removed, the line will be executed by the
7893     shell.
7894
7895'dump-functions ()'
7896     Print all of the functions and their key bindings to the Readline
7897     output stream.  If a numeric argument is supplied, the output is
7898     formatted in such a way that it can be made part of an INPUTRC
7899     file.  This command is unbound by default.
7900
7901'dump-variables ()'
7902     Print all of the settable variables and their values to the
7903     Readline output stream.  If a numeric argument is supplied, the
7904     output is formatted in such a way that it can be made part of an
7905     INPUTRC file.  This command is unbound by default.
7906
7907'dump-macros ()'
7908     Print all of the Readline key sequences bound to macros and the
7909     strings they output.  If a numeric argument is supplied, the output
7910     is formatted in such a way that it can be made part of an INPUTRC
7911     file.  This command is unbound by default.
7912
7913'glob-complete-word (M-g)'
7914     The word before point is treated as a pattern for pathname
7915     expansion, with an asterisk implicitly appended.  This pattern is
7916     used to generate a list of matching file names for possible
7917     completions.
7918
7919'glob-expand-word (C-x *)'
7920     The word before point is treated as a pattern for pathname
7921     expansion, and the list of matching file names is inserted,
7922     replacing the word.  If a numeric argument is supplied, a '*' is
7923     appended before pathname expansion.
7924
7925'glob-list-expansions (C-x g)'
7926     The list of expansions that would have been generated by
7927     'glob-expand-word' is displayed, and the line is redrawn.  If a
7928     numeric argument is supplied, a '*' is appended before pathname
7929     expansion.
7930
7931'display-shell-version (C-x C-v)'
7932     Display version information about the current instance of Bash.
7933
7934'shell-expand-line (M-C-e)'
7935     Expand the line as the shell does.  This performs alias and history
7936     expansion as well as all of the shell word expansions (*note Shell
7937     Expansions::).
7938
7939'history-expand-line (M-^)'
7940     Perform history expansion on the current line.
7941
7942'magic-space ()'
7943     Perform history expansion on the current line and insert a space
7944     (*note History Interaction::).
7945
7946'alias-expand-line ()'
7947     Perform alias expansion on the current line (*note Aliases::).
7948
7949'history-and-alias-expand-line ()'
7950     Perform history and alias expansion on the current line.
7951
7952'insert-last-argument (M-. or M-_)'
7953     A synonym for 'yank-last-arg'.
7954
7955'operate-and-get-next (C-o)'
7956     Accept the current line for execution and fetch the next line
7957     relative to the current line from the history for editing.  Any
7958     argument is ignored.
7959
7960'edit-and-execute-command (C-xC-e)'
7961     Invoke an editor on the current command line, and execute the
7962     result as shell commands.  Bash attempts to invoke '$VISUAL',
7963     '$EDITOR', and 'emacs' as the editor, in that order.
7964
79658.5 Readline vi Mode
7966====================
7967
7968While the Readline library does not have a full set of 'vi' editing
7969functions, it does contain enough to allow simple editing of the line.
7970The Readline 'vi' mode behaves as specified in the POSIX standard.
7971
7972   In order to switch interactively between 'emacs' and 'vi' editing
7973modes, use the 'set -o emacs' and 'set -o vi' commands (*note The Set
7974Builtin::).  The Readline default is 'emacs' mode.
7975
7976   When you enter a line in 'vi' mode, you are already placed in
7977'insertion' mode, as if you had typed an 'i'.  Pressing <ESC> switches
7978you into 'command' mode, where you can edit the text of the line with
7979the standard 'vi' movement keys, move to previous history lines with 'k'
7980and subsequent lines with 'j', and so forth.
7981
79828.6 Programmable Completion
7983===========================
7984
7985When word completion is attempted for an argument to a command for which
7986a completion specification (a COMPSPEC) has been defined using the
7987'complete' builtin (*note Programmable Completion Builtins::), the
7988programmable completion facilities are invoked.
7989
7990   First, the command name is identified.  If a compspec has been
7991defined for that command, the compspec is used to generate the list of
7992possible completions for the word.  If the command word is the empty
7993string (completion attempted at the beginning of an empty line), any
7994compspec defined with the '-E' option to 'complete' is used.  If the
7995command word is a full pathname, a compspec for the full pathname is
7996searched for first.  If no compspec is found for the full pathname, an
7997attempt is made to find a compspec for the portion following the final
7998slash.  If those searches do not result in a compspec, any compspec
7999defined with the '-D' option to 'complete' is used as the default.
8000
8001   Once a compspec has been found, it is used to generate the list of
8002matching words.  If a compspec is not found, the default Bash completion
8003described above (*note Commands For Completion::) is performed.
8004
8005   First, the actions specified by the compspec are used.  Only matches
8006which are prefixed by the word being completed are returned.  When the
8007'-f' or '-d' option is used for filename or directory name completion,
8008the shell variable 'FIGNORE' is used to filter the matches.  *Note Bash
8009Variables::, for a description of 'FIGNORE'.
8010
8011   Any completions specified by a filename expansion pattern to the '-G'
8012option are generated next.  The words generated by the pattern need not
8013match the word being completed.  The 'GLOBIGNORE' shell variable is not
8014used to filter the matches, but the 'FIGNORE' shell variable is used.
8015
8016   Next, the string specified as the argument to the '-W' option is
8017considered.  The string is first split using the characters in the 'IFS'
8018special variable as delimiters.  Shell quoting is honored.  Each word is
8019then expanded using brace expansion, tilde expansion, parameter and
8020variable expansion, command substitution, and arithmetic expansion, as
8021described above (*note Shell Expansions::).  The results are split using
8022the rules described above (*note Word Splitting::).  The results of the
8023expansion are prefix-matched against the word being completed, and the
8024matching words become the possible completions.
8025
8026   After these matches have been generated, any shell function or
8027command specified with the '-F' and '-C' options is invoked.  When the
8028command or function is invoked, the 'COMP_LINE', 'COMP_POINT',
8029'COMP_KEY', and 'COMP_TYPE' variables are assigned values as described
8030above (*note Bash Variables::).  If a shell function is being invoked,
8031the 'COMP_WORDS' and 'COMP_CWORD' variables are also set.  When the
8032function or command is invoked, the first argument ($1) is the name of
8033the command whose arguments are being completed, the second argument
8034($2) is the word being completed, and the third argument ($3) is the
8035word preceding the word being completed on the current command line.  No
8036filtering of the generated completions against the word being completed
8037is performed; the function or command has complete freedom in generating
8038the matches.
8039
8040   Any function specified with '-F' is invoked first.  The function may
8041use any of the shell facilities, including the 'compgen' and 'compopt'
8042builtins described below (*note Programmable Completion Builtins::), to
8043generate the matches.  It must put the possible completions in the
8044'COMPREPLY' array variable, one per array element.
8045
8046   Next, any command specified with the '-C' option is invoked in an
8047environment equivalent to command substitution.  It should print a list
8048of completions, one per line, to the standard output.  Backslash may be
8049used to escape a newline, if necessary.
8050
8051   After all of the possible completions are generated, any filter
8052specified with the '-X' option is applied to the list.  The filter is a
8053pattern as used for pathname expansion; a '&' in the pattern is replaced
8054with the text of the word being completed.  A literal '&' may be escaped
8055with a backslash; the backslash is removed before attempting a match.
8056Any completion that matches the pattern will be removed from the list.
8057A leading '!' negates the pattern; in this case any completion not
8058matching the pattern will be removed.  If the 'nocasematch' shell option
8059(see the description of 'shopt' in *note The Shopt Builtin::) is
8060enabled, the match is performed without regard to the case of alphabetic
8061characters.
8062
8063   Finally, any prefix and suffix specified with the '-P' and '-S'
8064options are added to each member of the completion list, and the result
8065is returned to the Readline completion code as the list of possible
8066completions.
8067
8068   If the previously-applied actions do not generate any matches, and
8069the '-o dirnames' option was supplied to 'complete' when the compspec
8070was defined, directory name completion is attempted.
8071
8072   If the '-o plusdirs' option was supplied to 'complete' when the
8073compspec was defined, directory name completion is attempted and any
8074matches are added to the results of the other actions.
8075
8076   By default, if a compspec is found, whatever it generates is returned
8077to the completion code as the full set of possible completions.  The
8078default Bash completions are not attempted, and the Readline default of
8079filename completion is disabled.  If the '-o bashdefault' option was
8080supplied to 'complete' when the compspec was defined, the default Bash
8081completions are attempted if the compspec generates no matches.  If the
8082'-o default' option was supplied to 'complete' when the compspec was
8083defined, Readline's default completion will be performed if the compspec
8084(and, if attempted, the default Bash completions) generate no matches.
8085
8086   When a compspec indicates that directory name completion is desired,
8087the programmable completion functions force Readline to append a slash
8088to completed names which are symbolic links to directories, subject to
8089the value of the MARK-DIRECTORIES Readline variable, regardless of the
8090setting of the MARK-SYMLINKED-DIRECTORIES Readline variable.
8091
8092   There is some support for dynamically modifying completions.  This is
8093most useful when used in combination with a default completion specified
8094with '-D'.  It's possible for shell functions executed as completion
8095handlers to indicate that completion should be retried by returning an
8096exit status of 124.  If a shell function returns 124, and changes the
8097compspec associated with the command on which completion is being
8098attempted (supplied as the first argument when the function is
8099executed), programmable completion restarts from the beginning, with an
8100attempt to find a new compspec for that command.  This allows a set of
8101completions to be built dynamically as completion is attempted, rather
8102than being loaded all at once.
8103
8104   For instance, assuming that there is a library of compspecs, each
8105kept in a file corresponding to the name of the command, the following
8106default completion function would load completions dynamically:
8107
8108     _completion_loader()
8109     {
8110         . "/etc/bash_completion.d/$1.sh" >/dev/null 2>&1 && return 124
8111     }
8112     complete -D -F _completion_loader -o bashdefault -o default
8113
81148.7 Programmable Completion Builtins
8115====================================
8116
8117Three builtin commands are available to manipulate the programmable
8118completion facilities: one to specify how the arguments to a particular
8119command are to be completed, and two to modify the completion as it is
8120happening.
8121
8122'compgen'
8123          compgen [OPTION] [WORD]
8124
8125     Generate possible completion matches for WORD according to the
8126     OPTIONs, which may be any option accepted by the 'complete' builtin
8127     with the exception of '-p' and '-r', and write the matches to the
8128     standard output.  When using the '-F' or '-C' options, the various
8129     shell variables set by the programmable completion facilities,
8130     while available, will not have useful values.
8131
8132     The matches will be generated in the same way as if the
8133     programmable completion code had generated them directly from a
8134     completion specification with the same flags.  If WORD is
8135     specified, only those completions matching WORD will be displayed.
8136
8137     The return value is true unless an invalid option is supplied, or
8138     no matches were generated.
8139
8140'complete'
8141          complete [-abcdefgjksuv] [-o COMP-OPTION] [-DE] [-A ACTION] [-G GLOBPAT] [-W WORDLIST]
8142          [-F FUNCTION] [-C COMMAND] [-X FILTERPAT]
8143          [-P PREFIX] [-S SUFFIX] NAME [NAME ...]
8144          complete -pr [-DE] [NAME ...]
8145
8146     Specify how arguments to each NAME should be completed.  If the
8147     '-p' option is supplied, or if no options are supplied, existing
8148     completion specifications are printed in a way that allows them to
8149     be reused as input.  The '-r' option removes a completion
8150     specification for each NAME, or, if no NAMEs are supplied, all
8151     completion specifications.  The '-D' option indicates that the
8152     remaining options and actions should apply to the "default" command
8153     completion; that is, completion attempted on a command for which no
8154     completion has previously been defined.  The '-E' option indicates
8155     that the remaining options and actions should apply to "empty"
8156     command completion; that is, completion attempted on a blank line.
8157
8158     The process of applying these completion specifications when word
8159     completion is attempted is described above (*note Programmable
8160     Completion::).  The '-D' option takes precedence over '-E'.
8161
8162     Other options, if specified, have the following meanings.  The
8163     arguments to the '-G', '-W', and '-X' options (and, if necessary,
8164     the '-P' and '-S' options) should be quoted to protect them from
8165     expansion before the 'complete' builtin is invoked.
8166
8167     '-o COMP-OPTION'
8168          The COMP-OPTION controls several aspects of the compspec's
8169          behavior beyond the simple generation of completions.
8170          COMP-OPTION may be one of:
8171
8172          'bashdefault'
8173               Perform the rest of the default Bash completions if the
8174               compspec generates no matches.
8175
8176          'default'
8177               Use Readline's default filename completion if the
8178               compspec generates no matches.
8179
8180          'dirnames'
8181               Perform directory name completion if the compspec
8182               generates no matches.
8183
8184          'filenames'
8185               Tell Readline that the compspec generates filenames, so
8186               it can perform any filename-specific processing (like
8187               adding a slash to directory names quoting special
8188               characters, or suppressing trailing spaces).  This option
8189               is intended to be used with shell functions specified
8190               with '-F'.
8191
8192          'noquote'
8193               Tell Readline not to quote the completed words if they
8194               are filenames (quoting filenames is the default).
8195
8196          'nosort'
8197               Tell Readline not to sort the list of possible
8198               completions alphabetically.
8199
8200          'nospace'
8201               Tell Readline not to append a space (the default) to
8202               words completed at the end of the line.
8203
8204          'plusdirs'
8205               After any matches defined by the compspec are generated,
8206               directory name completion is attempted and any matches
8207               are added to the results of the other actions.
8208
8209     '-A ACTION'
8210          The ACTION may be one of the following to generate a list of
8211          possible completions:
8212
8213          'alias'
8214               Alias names.  May also be specified as '-a'.
8215
8216          'arrayvar'
8217               Array variable names.
8218
8219          'binding'
8220               Readline key binding names (*note Bindable Readline
8221               Commands::).
8222
8223          'builtin'
8224               Names of shell builtin commands.  May also be specified
8225               as '-b'.
8226
8227          'command'
8228               Command names.  May also be specified as '-c'.
8229
8230          'directory'
8231               Directory names.  May also be specified as '-d'.
8232
8233          'disabled'
8234               Names of disabled shell builtins.
8235
8236          'enabled'
8237               Names of enabled shell builtins.
8238
8239          'export'
8240               Names of exported shell variables.  May also be specified
8241               as '-e'.
8242
8243          'file'
8244               File names.  May also be specified as '-f'.
8245
8246          'function'
8247               Names of shell functions.
8248
8249          'group'
8250               Group names.  May also be specified as '-g'.
8251
8252          'helptopic'
8253               Help topics as accepted by the 'help' builtin (*note Bash
8254               Builtins::).
8255
8256          'hostname'
8257               Hostnames, as taken from the file specified by the
8258               'HOSTFILE' shell variable (*note Bash Variables::).
8259
8260          'job'
8261               Job names, if job control is active.  May also be
8262               specified as '-j'.
8263
8264          'keyword'
8265               Shell reserved words.  May also be specified as '-k'.
8266
8267          'running'
8268               Names of running jobs, if job control is active.
8269
8270          'service'
8271               Service names.  May also be specified as '-s'.
8272
8273          'setopt'
8274               Valid arguments for the '-o' option to the 'set' builtin
8275               (*note The Set Builtin::).
8276
8277          'shopt'
8278               Shell option names as accepted by the 'shopt' builtin
8279               (*note Bash Builtins::).
8280
8281          'signal'
8282               Signal names.
8283
8284          'stopped'
8285               Names of stopped jobs, if job control is active.
8286
8287          'user'
8288               User names.  May also be specified as '-u'.
8289
8290          'variable'
8291               Names of all shell variables.  May also be specified as
8292               '-v'.
8293
8294     '-C COMMAND'
8295          COMMAND is executed in a subshell environment, and its output
8296          is used as the possible completions.
8297
8298     '-F FUNCTION'
8299          The shell function FUNCTION is executed in the current shell
8300          environment.  When it is executed, $1 is the name of the
8301          command whose arguments are being completed, $2 is the word
8302          being completed, and $3 is the word preceding the word being
8303          completed, as described above (*note Programmable
8304          Completion::).  When it finishes, the possible completions are
8305          retrieved from the value of the 'COMPREPLY' array variable.
8306
8307     '-G GLOBPAT'
8308          The filename expansion pattern GLOBPAT is expanded to generate
8309          the possible completions.
8310
8311     '-P PREFIX'
8312          PREFIX is added at the beginning of each possible completion
8313          after all other options have been applied.
8314
8315     '-S SUFFIX'
8316          SUFFIX is appended to each possible completion after all other
8317          options have been applied.
8318
8319     '-W WORDLIST'
8320          The WORDLIST is split using the characters in the 'IFS'
8321          special variable as delimiters, and each resultant word is
8322          expanded.  The possible completions are the members of the
8323          resultant list which match the word being completed.
8324
8325     '-X FILTERPAT'
8326          FILTERPAT is a pattern as used for filename expansion.  It is
8327          applied to the list of possible completions generated by the
8328          preceding options and arguments, and each completion matching
8329          FILTERPAT is removed from the list.  A leading '!' in
8330          FILTERPAT negates the pattern; in this case, any completion
8331          not matching FILTERPAT is removed.
8332
8333     The return value is true unless an invalid option is supplied, an
8334     option other than '-p' or '-r' is supplied without a NAME argument,
8335     an attempt is made to remove a completion specification for a NAME
8336     for which no specification exists, or an error occurs adding a
8337     completion specification.
8338
8339'compopt'
8340          compopt [-o OPTION] [-DE] [+o OPTION] [NAME]
8341     Modify completion options for each NAME according to the OPTIONs,
8342     or for the currently-executing completion if no NAMEs are supplied.
8343     If no OPTIONs are given, display the completion options for each
8344     NAME or the current completion.  The possible values of OPTION are
8345     those valid for the 'complete' builtin described above.  The '-D'
8346     option indicates that the remaining options should apply to the
8347     "default" command completion; that is, completion attempted on a
8348     command for which no completion has previously been defined.  The
8349     '-E' option indicates that the remaining options should apply to
8350     "empty" command completion; that is, completion attempted on a
8351     blank line.
8352
8353     The '-D' option takes precedence over '-E'.
8354
8355     The return value is true unless an invalid option is supplied, an
8356     attempt is made to modify the options for a NAME for which no
8357     completion specification exists, or an output error occurs.
8358
83598.8 A Programmable Completion Example
8360=====================================
8361
8362The most common way to obtain additional completion functionality beyond
8363the default actions 'complete' and 'compgen' provide is to use a shell
8364function and bind it to a particular command using 'complete -F'.
8365
8366   The following function provides completions for the 'cd' builtin.  It
8367is a reasonably good example of what shell functions must do when used
8368for completion.  This function uses the word passsed as '$2' to
8369determine the directory name to complete.  You can also use the
8370'COMP_WORDS' array variable; the current word is indexed by the
8371'COMP_CWORD' variable.
8372
8373   The function relies on the 'complete' and 'compgen' builtins to do
8374much of the work, adding only the things that the Bash 'cd' does beyond
8375accepting basic directory names: tilde expansion (*note Tilde
8376Expansion::), searching directories in $CDPATH, which is described above
8377(*note Bourne Shell Builtins::), and basic support for the 'cdable_vars'
8378shell option (*note The Shopt Builtin::).  '_comp_cd' modifies the value
8379of IFS so that it contains only a newline to accommodate file names
8380containing spaces and tabs - 'compgen' prints the possible completions
8381it generates one per line.
8382
8383   Possible completions go into the COMPREPLY array variable, one
8384completion per array element.  The programmable completion system
8385retrieves the completions from there when the function returns.
8386
8387     # A completion function for the cd builtin
8388     # based on the cd completion function from the bash_completion package
8389     _comp_cd()
8390     {
8391         local IFS=$' \t\n'    # normalize IFS
8392         local cur _skipdot _cdpath
8393         local i j k
8394
8395         # Tilde expansion, with side effect of expanding tilde to full pathname
8396         case "$2" in
8397         \~*)    eval cur="$2" ;;
8398         *)      cur=$2 ;;
8399         esac
8400
8401         # no cdpath or absolute pathname -- straight directory completion
8402         if [[ -z "${CDPATH:-}" ]] || [[ "$cur" == @(./*|../*|/*) ]]; then
8403             # compgen prints paths one per line; could also use while loop
8404             IFS=$'\n'
8405             COMPREPLY=( $(compgen -d -- "$cur") )
8406             IFS=$' \t\n'
8407         # CDPATH+directories in the current directory if not in CDPATH
8408         else
8409             IFS=$'\n'
8410             _skipdot=false
8411             # preprocess CDPATH to convert null directory names to .
8412             _cdpath=${CDPATH/#:/.:}
8413             _cdpath=${_cdpath//::/:.:}
8414             _cdpath=${_cdpath/%:/:.}
8415             for i in ${_cdpath//:/$'\n'}; do
8416                 if [[ $i -ef . ]]; then _skipdot=true; fi
8417                 k="${#COMPREPLY[@]}"
8418                 for j in $( compgen -d -- "$i/$cur" ); do
8419                     COMPREPLY[k++]=${j#$i/}        # cut off directory
8420                 done
8421             done
8422             $_skipdot || COMPREPLY+=( $(compgen -d -- "$cur") )
8423             IFS=$' \t\n'
8424         fi
8425
8426         # variable names if appropriate shell option set and no completions
8427         if shopt -q cdable_vars && [[ ${#COMPREPLY[@]} -eq 0 ]]; then
8428             COMPREPLY=( $(compgen -v -- "$cur") )
8429         fi
8430
8431         return 0
8432     }
8433
8434   We install the completion function using the '-F' option to
8435'complete':
8436
8437     # Tell readline to quote appropriate and append slashes to directories;
8438     # use the bash default completion for other arguments
8439     complete -o filenames -o nospace -o bashdefault -F _comp_cd cd
8440
8441Since we'd like Bash and Readline to take care of some of the other
8442details for us, we use several other options to tell Bash and Readline
8443what to do.  The '-o filenames' option tells Readline that the possible
8444completions should be treated as filenames, and quoted appropriately.
8445That option will also cause Readline to append a slash to filenames it
8446can determine are directories (which is why we might want to extend
8447'_comp_cd' to append a slash if we're using directories found via
8448CDPATH: Readline can't tell those completions are directories).  The '-o
8449nospace' option tells Readline to not append a space character to the
8450directory name, in case we want to append to it.  The '-o bashdefault'
8451option brings in the rest of the "Bash default" completions - possible
8452completion that Bash adds to the default Readline set.  These include
8453things like command name completion, variable completion for words
8454beginning with '{', completions containing pathname expansion patterns
8455(*note Filename Expansion::), and so on.
8456
8457   Once installed using 'complete', '_comp_cd' will be called every time
8458we attempt word completion for a 'cd' command.
8459
8460   Many more examples - an extensive collection of completions for most
8461of the common GNU, Unix, and Linux commands - are available as part of
8462the bash_completion project.  This is installed by default on many
8463GNU/Linux distributions.  Originally written by Ian Macdonald, the
8464project now lives at <http://bash-completion.alioth.debian.org/>.  There
8465are ports for other systems such as Solaris and Mac OS X.
8466
8467   An older version of the bash_completion package is distributed with
8468bash in the 'examples/complete' subdirectory.
8469
84709 Using History Interactively
8471*****************************
8472
8473This chapter describes how to use the GNU History Library interactively,
8474from a user's standpoint.  It should be considered a user's guide.  For
8475information on using the GNU History Library in other programs, see the
8476GNU Readline Library Manual.
8477
84789.1 Bash History Facilities
8479===========================
8480
8481When the '-o history' option to the 'set' builtin is enabled (*note The
8482Set Builtin::), the shell provides access to the "command history", the
8483list of commands previously typed.  The value of the 'HISTSIZE' shell
8484variable is used as the number of commands to save in a history list.
8485The text of the last '$HISTSIZE' commands (default 500) is saved.  The
8486shell stores each command in the history list prior to parameter and
8487variable expansion but after history expansion is performed, subject to
8488the values of the shell variables 'HISTIGNORE' and 'HISTCONTROL'.
8489
8490   When the shell starts up, the history is initialized from the file
8491named by the 'HISTFILE' variable (default '~/.bash_history').  The file
8492named by the value of 'HISTFILE' is truncated, if necessary, to contain
8493no more than the number of lines specified by the value of the
8494'HISTFILESIZE' variable.  When a shell with history enabled exits, the
8495last '$HISTSIZE' lines are copied from the history list to the file
8496named by '$HISTFILE'.  If the 'histappend' shell option is set (*note
8497Bash Builtins::), the lines are appended to the history file, otherwise
8498the history file is overwritten.  If 'HISTFILE' is unset, or if the
8499history file is unwritable, the history is not saved.  After saving the
8500history, the history file is truncated to contain no more than
8501'$HISTFILESIZE' lines.  If 'HISTFILESIZE' is unset, or set to null, a
8502non-numeric value, or a numeric value less than zero, the history file
8503is not truncated.
8504
8505   If the 'HISTTIMEFORMAT' is set, the time stamp information associated
8506with each history entry is written to the history file, marked with the
8507history comment character.  When the history file is read, lines
8508beginning with the history comment character followed immediately by a
8509digit are interpreted as timestamps for the following history entry.
8510
8511   The builtin command 'fc' may be used to list or edit and re-execute a
8512portion of the history list.  The 'history' builtin may be used to
8513display or modify the history list and manipulate the history file.
8514When using command-line editing, search commands are available in each
8515editing mode that provide access to the history list (*note Commands For
8516History::).
8517
8518   The shell allows control over which commands are saved on the history
8519list.  The 'HISTCONTROL' and 'HISTIGNORE' variables may be set to cause
8520the shell to save only a subset of the commands entered.  The 'cmdhist'
8521shell option, if enabled, causes the shell to attempt to save each line
8522of a multi-line command in the same history entry, adding semicolons
8523where necessary to preserve syntactic correctness.  The 'lithist' shell
8524option causes the shell to save the command with embedded newlines
8525instead of semicolons.  The 'shopt' builtin is used to set these
8526options.  *Note Bash Builtins::, for a description of 'shopt'.
8527
85289.2 Bash History Builtins
8529=========================
8530
8531Bash provides two builtin commands which manipulate the history list and
8532history file.
8533
8534'fc'
8535          fc [-e ENAME] [-lnr] [FIRST] [LAST]
8536          fc -s [PAT=REP] [COMMAND]
8537
8538     The first form selects a range of commands from FIRST to LAST from
8539     the history list and displays or edits and re-executes them.  Both
8540     FIRST and LAST may be specified as a string (to locate the most
8541     recent command beginning with that string) or as a number (an index
8542     into the history list, where a negative number is used as an offset
8543     from the current command number).  If LAST is not specified it is
8544     set to FIRST.  If FIRST is not specified it is set to the previous
8545     command for editing and -16 for listing.  If the '-l' flag is
8546     given, the commands are listed on standard output.  The '-n' flag
8547     suppresses the command numbers when listing.  The '-r' flag
8548     reverses the order of the listing.  Otherwise, the editor given by
8549     ENAME is invoked on a file containing those commands.  If ENAME is
8550     not given, the value of the following variable expansion is used:
8551     '${FCEDIT:-${EDITOR:-vi}}'.  This says to use the value of the
8552     'FCEDIT' variable if set, or the value of the 'EDITOR' variable if
8553     that is set, or 'vi' if neither is set.  When editing is complete,
8554     the edited commands are echoed and executed.
8555
8556     In the second form, COMMAND is re-executed after each instance of
8557     PAT in the selected command is replaced by REP.  COMMAND is
8558     intepreted the same as FIRST above.
8559
8560     A useful alias to use with the 'fc' command is 'r='fc -s'', so that
8561     typing 'r cc' runs the last command beginning with 'cc' and typing
8562     'r' re-executes the last command (*note Aliases::).
8563
8564'history'
8565          history [N]
8566          history -c
8567          history -d OFFSET
8568          history [-anrw] [FILENAME]
8569          history -ps ARG
8570
8571     With no options, display the history list with line numbers.  Lines
8572     prefixed with a '*' have been modified.  An argument of N lists
8573     only the last N lines.  If the shell variable 'HISTTIMEFORMAT' is
8574     set and not null, it is used as a format string for STRFTIME to
8575     display the time stamp associated with each displayed history
8576     entry.  No intervening blank is printed between the formatted time
8577     stamp and the history line.
8578
8579     Options, if supplied, have the following meanings:
8580
8581     '-c'
8582          Clear the history list.  This may be combined with the other
8583          options to replace the history list completely.
8584
8585     '-d OFFSET'
8586          Delete the history entry at position OFFSET.  OFFSET should be
8587          specified as it appears when the history is displayed.
8588
8589     '-a'
8590          Append the new history lines to the history file.  These are
8591          history lines entered since the beginning of the current Bash
8592          session, but not already appended to the history file.
8593
8594     '-n'
8595          Append the history lines not already read from the history
8596          file to the current history list.  These are lines appended to
8597          the history file since the beginning of the current Bash
8598          session.
8599
8600     '-r'
8601          Read the history file and append its contents to the history
8602          list.
8603
8604     '-w'
8605          Write out the current history list to the history file.
8606
8607     '-p'
8608          Perform history substitution on the ARGs and display the
8609          result on the standard output, without storing the results in
8610          the history list.
8611
8612     '-s'
8613          The ARGs are added to the end of the history list as a single
8614          entry.
8615
8616     When any of the '-w', '-r', '-a', or '-n' options is used, if
8617     FILENAME is given, then it is used as the history file.  If not,
8618     then the value of the 'HISTFILE' variable is used.
8619
86209.3 History Expansion
8621=====================
8622
8623The History library provides a history expansion feature that is similar
8624to the history expansion provided by 'csh'.  This section describes the
8625syntax used to manipulate the history information.
8626
8627   History expansions introduce words from the history list into the
8628input stream, making it easy to repeat commands, insert the arguments to
8629a previous command into the current input line, or fix errors in
8630previous commands quickly.
8631
8632   History expansion is performed immediately after a complete line is
8633read, before the shell breaks it into words.
8634
8635   History expansion takes place in two parts.  The first is to
8636determine which line from the history list should be used during
8637substitution.  The second is to select portions of that line for
8638inclusion into the current one.  The line selected from the history is
8639called the "event", and the portions of that line that are acted upon
8640are called "words".  Various "modifiers" are available to manipulate the
8641selected words.  The line is broken into words in the same fashion that
8642Bash does, so that several words surrounded by quotes are considered one
8643word.  History expansions are introduced by the appearance of the
8644history expansion character, which is '!' by default.  Only '\' and '''
8645may be used to escape the history expansion character, but the history
8646expansion character is also treated as quoted if it immediately precedes
8647the closing double quote in a double-quoted string.
8648
8649   Several shell options settable with the 'shopt' builtin (*note Bash
8650Builtins::) may be used to tailor the behavior of history expansion.  If
8651the 'histverify' shell option is enabled, and Readline is being used,
8652history substitutions are not immediately passed to the shell parser.
8653Instead, the expanded line is reloaded into the Readline editing buffer
8654for further modification.  If Readline is being used, and the
8655'histreedit' shell option is enabled, a failed history expansion will be
8656reloaded into the Readline editing buffer for correction.  The '-p'
8657option to the 'history' builtin command may be used to see what a
8658history expansion will do before using it.  The '-s' option to the
8659'history' builtin may be used to add commands to the end of the history
8660list without actually executing them, so that they are available for
8661subsequent recall.  This is most useful in conjunction with Readline.
8662
8663   The shell allows control of the various characters used by the
8664history expansion mechanism with the 'histchars' variable, as explained
8665above (*note Bash Variables::).  The shell uses the history comment
8666character to mark history timestamps when writing the history file.
8667
86689.3.1 Event Designators
8669-----------------------
8670
8671An event designator is a reference to a command line entry in the
8672history list.  Unless the reference is absolute, events are relative to
8673the current position in the history list.
8674
8675'!'
8676     Start a history substitution, except when followed by a space, tab,
8677     the end of the line, '=' or '(' (when the 'extglob' shell option is
8678     enabled using the 'shopt' builtin).
8679
8680'!N'
8681     Refer to command line N.
8682
8683'!-N'
8684     Refer to the command N lines back.
8685
8686'!!'
8687     Refer to the previous command.  This is a synonym for '!-1'.
8688
8689'!STRING'
8690     Refer to the most recent command preceding the current position in
8691     the history list starting with STRING.
8692
8693'!?STRING[?]'
8694     Refer to the most recent command preceding the current position in
8695     the history list containing STRING.  The trailing '?' may be
8696     omitted if the STRING is followed immediately by a newline.
8697
8698'^STRING1^STRING2^'
8699     Quick Substitution.  Repeat the last command, replacing STRING1
8700     with STRING2.  Equivalent to '!!:s/STRING1/STRING2/'.
8701
8702'!#'
8703     The entire command line typed so far.
8704
87059.3.2 Word Designators
8706----------------------
8707
8708Word designators are used to select desired words from the event.  A ':'
8709separates the event specification from the word designator.  It may be
8710omitted if the word designator begins with a '^', '$', '*', '-', or '%'.
8711Words are numbered from the beginning of the line, with the first word
8712being denoted by 0 (zero).  Words are inserted into the current line
8713separated by single spaces.
8714
8715   For example,
8716
8717'!!'
8718     designates the preceding command.  When you type this, the
8719     preceding command is repeated in toto.
8720
8721'!!:$'
8722     designates the last argument of the preceding command.  This may be
8723     shortened to '!$'.
8724
8725'!fi:2'
8726     designates the second argument of the most recent command starting
8727     with the letters 'fi'.
8728
8729   Here are the word designators:
8730
8731'0 (zero)'
8732     The '0'th word.  For many applications, this is the command word.
8733
8734'N'
8735     The Nth word.
8736
8737'^'
8738     The first argument; that is, word 1.
8739
8740'$'
8741     The last argument.
8742
8743'%'
8744     The word matched by the most recent '?STRING?' search.
8745
8746'X-Y'
8747     A range of words; '-Y' abbreviates '0-Y'.
8748
8749'*'
8750     All of the words, except the '0'th.  This is a synonym for '1-$'.
8751     It is not an error to use '*' if there is just one word in the
8752     event; the empty string is returned in that case.
8753
8754'X*'
8755     Abbreviates 'X-$'
8756
8757'X-'
8758     Abbreviates 'X-$' like 'X*', but omits the last word.
8759
8760   If a word designator is supplied without an event specification, the
8761previous command is used as the event.
8762
87639.3.3 Modifiers
8764---------------
8765
8766After the optional word designator, you can add a sequence of one or
8767more of the following modifiers, each preceded by a ':'.
8768
8769'h'
8770     Remove a trailing pathname component, leaving only the head.
8771
8772't'
8773     Remove all leading pathname components, leaving the tail.
8774
8775'r'
8776     Remove a trailing suffix of the form '.SUFFIX', leaving the
8777     basename.
8778
8779'e'
8780     Remove all but the trailing suffix.
8781
8782'p'
8783     Print the new command but do not execute it.
8784
8785'q'
8786     Quote the substituted words, escaping further substitutions.
8787
8788'x'
8789     Quote the substituted words as with 'q', but break into words at
8790     spaces, tabs, and newlines.
8791
8792's/OLD/NEW/'
8793     Substitute NEW for the first occurrence of OLD in the event line.
8794     Any delimiter may be used in place of '/'.  The delimiter may be
8795     quoted in OLD and NEW with a single backslash.  If '&' appears in
8796     NEW, it is replaced by OLD.  A single backslash will quote the '&'.
8797     The final delimiter is optional if it is the last character on the
8798     input line.
8799
8800'&'
8801     Repeat the previous substitution.
8802
8803'g'
8804'a'
8805     Cause changes to be applied over the entire event line.  Used in
8806     conjunction with 's', as in 'gs/OLD/NEW/', or with '&'.
8807
8808'G'
8809     Apply the following 's' modifier once to each word in the event.
8810
881110 Installing Bash
8812******************
8813
8814This chapter provides basic instructions for installing Bash on the
8815various supported platforms.  The distribution supports the GNU
8816operating systems, nearly every version of Unix, and several non-Unix
8817systems such as BeOS and Interix.  Other independent ports exist for
8818MS-DOS, OS/2, and Windows platforms.
8819
882010.1 Basic Installation
8821=======================
8822
8823These are installation instructions for Bash.
8824
8825   The simplest way to compile Bash is:
8826
8827  1. 'cd' to the directory containing the source code and type
8828     './configure' to configure Bash for your system.  If you're using
8829     'csh' on an old version of System V, you might need to type 'sh
8830     ./configure' instead to prevent 'csh' from trying to execute
8831     'configure' itself.
8832
8833     Running 'configure' takes some time.  While running, it prints
8834     messages telling which features it is checking for.
8835
8836  2. Type 'make' to compile Bash and build the 'bashbug' bug reporting
8837     script.
8838
8839  3. Optionally, type 'make tests' to run the Bash test suite.
8840
8841  4. Type 'make install' to install 'bash' and 'bashbug'.  This will
8842     also install the manual pages and Info file.
8843
8844   The 'configure' shell script attempts to guess correct values for
8845various system-dependent variables used during compilation.  It uses
8846those values to create a 'Makefile' in each directory of the package
8847(the top directory, the 'builtins', 'doc', and 'support' directories,
8848each directory under 'lib', and several others).  It also creates a
8849'config.h' file containing system-dependent definitions.  Finally, it
8850creates a shell script named 'config.status' that you can run in the
8851future to recreate the current configuration, a file 'config.cache' that
8852saves the results of its tests to speed up reconfiguring, and a file
8853'config.log' containing compiler output (useful mainly for debugging
8854'configure').  If at some point 'config.cache' contains results you
8855don't want to keep, you may remove or edit it.
8856
8857   To find out more about the options and arguments that the 'configure'
8858script understands, type
8859
8860     bash-2.04$ ./configure --help
8861
8862at the Bash prompt in your Bash source directory.
8863
8864   If you need to do unusual things to compile Bash, please try to
8865figure out how 'configure' could check whether or not to do them, and
8866mail diffs or instructions to <bash-maintainers@gnu.org> so they can be
8867considered for the next release.
8868
8869   The file 'configure.ac' is used to create 'configure' by a program
8870called Autoconf.  You only need 'configure.ac' if you want to change it
8871or regenerate 'configure' using a newer version of Autoconf.  If you do
8872this, make sure you are using Autoconf version 2.50 or newer.
8873
8874   You can remove the program binaries and object files from the source
8875code directory by typing 'make clean'.  To also remove the files that
8876'configure' created (so you can compile Bash for a different kind of
8877computer), type 'make distclean'.
8878
887910.2 Compilers and Options
8880==========================
8881
8882Some systems require unusual options for compilation or linking that the
8883'configure' script does not know about.  You can give 'configure'
8884initial values for variables by setting them in the environment.  Using
8885a Bourne-compatible shell, you can do that on the command line like
8886this:
8887
8888     CC=c89 CFLAGS=-O2 LIBS=-lposix ./configure
8889
8890   On systems that have the 'env' program, you can do it like this:
8891
8892     env CPPFLAGS=-I/usr/local/include LDFLAGS=-s ./configure
8893
8894   The configuration process uses GCC to build Bash if it is available.
8895
889610.3 Compiling For Multiple Architectures
8897=========================================
8898
8899You can compile Bash for more than one kind of computer at the same
8900time, by placing the object files for each architecture in their own
8901directory.  To do this, you must use a version of 'make' that supports
8902the 'VPATH' variable, such as GNU 'make'.  'cd' to the directory where
8903you want the object files and executables to go and run the 'configure'
8904script from the source directory.  You may need to supply the
8905'--srcdir=PATH' argument to tell 'configure' where the source files are.
8906'configure' automatically checks for the source code in the directory
8907that 'configure' is in and in '..'.
8908
8909   If you have to use a 'make' that does not supports the 'VPATH'
8910variable, you can compile Bash for one architecture at a time in the
8911source code directory.  After you have installed Bash for one
8912architecture, use 'make distclean' before reconfiguring for another
8913architecture.
8914
8915   Alternatively, if your system supports symbolic links, you can use
8916the 'support/mkclone' script to create a build tree which has symbolic
8917links back to each file in the source directory.  Here's an example that
8918creates a build directory in the current directory from a source
8919directory '/usr/gnu/src/bash-2.0':
8920
8921     bash /usr/gnu/src/bash-2.0/support/mkclone -s /usr/gnu/src/bash-2.0 .
8922
8923The 'mkclone' script requires Bash, so you must have already built Bash
8924for at least one architecture before you can create build directories
8925for other architectures.
8926
892710.4 Installation Names
8928=======================
8929
8930By default, 'make install' will install into '/usr/local/bin',
8931'/usr/local/man', etc.  You can specify an installation prefix other
8932than '/usr/local' by giving 'configure' the option '--prefix=PATH', or
8933by specifying a value for the 'DESTDIR' 'make' variable when running
8934'make install'.
8935
8936   You can specify separate installation prefixes for
8937architecture-specific files and architecture-independent files.  If you
8938give 'configure' the option '--exec-prefix=PATH', 'make install' will
8939use PATH as the prefix for installing programs and libraries.
8940Documentation and other data files will still use the regular prefix.
8941
894210.5 Specifying the System Type
8943===============================
8944
8945There may be some features 'configure' can not figure out automatically,
8946but need to determine by the type of host Bash will run on.  Usually
8947'configure' can figure that out, but if it prints a message saying it
8948can not guess the host type, give it the '--host=TYPE' option.  'TYPE'
8949can either be a short name for the system type, such as 'sun4', or a
8950canonical name with three fields: 'CPU-COMPANY-SYSTEM' (e.g.,
8951'i386-unknown-freebsd4.2').
8952
8953   See the file 'support/config.sub' for the possible values of each
8954field.
8955
895610.6 Sharing Defaults
8957=====================
8958
8959If you want to set default values for 'configure' scripts to share, you
8960can create a site shell script called 'config.site' that gives default
8961values for variables like 'CC', 'cache_file', and 'prefix'.  'configure'
8962looks for 'PREFIX/share/config.site' if it exists, then
8963'PREFIX/etc/config.site' if it exists.  Or, you can set the
8964'CONFIG_SITE' environment variable to the location of the site script.
8965A warning: the Bash 'configure' looks for a site script, but not all
8966'configure' scripts do.
8967
896810.7 Operation Controls
8969=======================
8970
8971'configure' recognizes the following options to control how it operates.
8972
8973'--cache-file=FILE'
8974     Use and save the results of the tests in FILE instead of
8975     './config.cache'.  Set FILE to '/dev/null' to disable caching, for
8976     debugging 'configure'.
8977
8978'--help'
8979     Print a summary of the options to 'configure', and exit.
8980
8981'--quiet'
8982'--silent'
8983'-q'
8984     Do not print messages saying which checks are being made.
8985
8986'--srcdir=DIR'
8987     Look for the Bash source code in directory DIR.  Usually
8988     'configure' can determine that directory automatically.
8989
8990'--version'
8991     Print the version of Autoconf used to generate the 'configure'
8992     script, and exit.
8993
8994   'configure' also accepts some other, not widely used, boilerplate
8995options.  'configure --help' prints the complete list.
8996
899710.8 Optional Features
8998======================
8999
9000The Bash 'configure' has a number of '--enable-FEATURE' options, where
9001FEATURE indicates an optional part of Bash.  There are also several
9002'--with-PACKAGE' options, where PACKAGE is something like 'bash-malloc'
9003or 'purify'.  To turn off the default use of a package, use
9004'--without-PACKAGE'.  To configure Bash without a feature that is
9005enabled by default, use '--disable-FEATURE'.
9006
9007   Here is a complete list of the '--enable-' and '--with-' options that
9008the Bash 'configure' recognizes.
9009
9010'--with-afs'
9011     Define if you are using the Andrew File System from Transarc.
9012
9013'--with-bash-malloc'
9014     Use the Bash version of 'malloc' in the directory 'lib/malloc'.
9015     This is not the same 'malloc' that appears in GNU libc, but an
9016     older version originally derived from the 4.2 BSD 'malloc'.  This
9017     'malloc' is very fast, but wastes some space on each allocation.
9018     This option is enabled by default.  The 'NOTES' file contains a
9019     list of systems for which this should be turned off, and
9020     'configure' disables this option automatically for a number of
9021     systems.
9022
9023'--with-curses'
9024     Use the curses library instead of the termcap library.  This should
9025     be supplied if your system has an inadequate or incomplete termcap
9026     database.
9027
9028'--with-gnu-malloc'
9029     A synonym for '--with-bash-malloc'.
9030
9031'--with-installed-readline[=PREFIX]'
9032     Define this to make Bash link with a locally-installed version of
9033     Readline rather than the version in 'lib/readline'.  This works
9034     only with Readline 5.0 and later versions.  If PREFIX is 'yes' or
9035     not supplied, 'configure' uses the values of the make variables
9036     'includedir' and 'libdir', which are subdirectories of 'prefix' by
9037     default, to find the installed version of Readline if it is not in
9038     the standard system include and library directories.  If PREFIX is
9039     'no', Bash links with the version in 'lib/readline'.  If PREFIX is
9040     set to any other value, 'configure' treats it as a directory
9041     pathname and looks for the installed version of Readline in
9042     subdirectories of that directory (include files in PREFIX/'include'
9043     and the library in PREFIX/'lib').
9044
9045'--with-purify'
9046     Define this to use the Purify memory allocation checker from
9047     Rational Software.
9048
9049'--enable-minimal-config'
9050     This produces a shell with minimal features, close to the
9051     historical Bourne shell.
9052
9053   There are several '--enable-' options that alter how Bash is compiled
9054and linked, rather than changing run-time features.
9055
9056'--enable-largefile'
9057     Enable support for large files
9058     (http://www.sas.com/standards/large_file/x_open.20Mar96.html) if
9059     the operating system requires special compiler options to build
9060     programs which can access large files.  This is enabled by default,
9061     if the operating system provides large file support.
9062
9063'--enable-profiling'
9064     This builds a Bash binary that produces profiling information to be
9065     processed by 'gprof' each time it is executed.
9066
9067'--enable-static-link'
9068     This causes Bash to be linked statically, if 'gcc' is being used.
9069     This could be used to build a version to use as root's shell.
9070
9071   The 'minimal-config' option can be used to disable all of the
9072following options, but it is processed first, so individual options may
9073be enabled using 'enable-FEATURE'.
9074
9075   All of the following options except for 'disabled-builtins',
9076'direxpand-default', and 'xpg-echo-default' are enabled by default,
9077unless the operating system does not provide the necessary support.
9078
9079'--enable-alias'
9080     Allow alias expansion and include the 'alias' and 'unalias'
9081     builtins (*note Aliases::).
9082
9083'--enable-arith-for-command'
9084     Include support for the alternate form of the 'for' command that
9085     behaves like the C language 'for' statement (*note Looping
9086     Constructs::).
9087
9088'--enable-array-variables'
9089     Include support for one-dimensional array shell variables (*note
9090     Arrays::).
9091
9092'--enable-bang-history'
9093     Include support for 'csh'-like history substitution (*note History
9094     Interaction::).
9095
9096'--enable-brace-expansion'
9097     Include 'csh'-like brace expansion ( 'b{a,b}c' ==> 'bac bbc' ).
9098     See *note Brace Expansion::, for a complete description.
9099
9100'--enable-casemod-attributes'
9101     Include support for case-modifying attributes in the 'declare'
9102     builtin and assignment statements.  Variables with the UPPERCASE
9103     attribute, for example, will have their values converted to
9104     uppercase upon assignment.
9105
9106'--enable-casemod-expansion'
9107     Include support for case-modifying word expansions.
9108
9109'--enable-command-timing'
9110     Include support for recognizing 'time' as a reserved word and for
9111     displaying timing statistics for the pipeline following 'time'
9112     (*note Pipelines::).  This allows pipelines as well as shell
9113     builtins and functions to be timed.
9114
9115'--enable-cond-command'
9116     Include support for the '[[' conditional command.  (*note
9117     Conditional Constructs::).
9118
9119'--enable-cond-regexp'
9120     Include support for matching POSIX regular expressions using the
9121     '=~' binary operator in the '[[' conditional command.  (*note
9122     Conditional Constructs::).
9123
9124'--enable-coprocesses'
9125     Include support for coprocesses and the 'coproc' reserved word
9126     (*note Pipelines::).
9127
9128'--enable-debugger'
9129     Include support for the bash debugger (distributed separately).
9130
9131'--enable-direxpand-default'
9132     Cause the 'direxpand' shell option (*note The Shopt Builtin::) to
9133     be enabled by default when the shell starts.  It is normally
9134     disabled by default.
9135
9136'--enable-directory-stack'
9137     Include support for a 'csh'-like directory stack and the 'pushd',
9138     'popd', and 'dirs' builtins (*note The Directory Stack::).
9139
9140'--enable-disabled-builtins'
9141     Allow builtin commands to be invoked via 'builtin xxx' even after
9142     'xxx' has been disabled using 'enable -n xxx'.  See *note Bash
9143     Builtins::, for details of the 'builtin' and 'enable' builtin
9144     commands.
9145
9146'--enable-dparen-arithmetic'
9147     Include support for the '((...))' command (*note Conditional
9148     Constructs::).
9149
9150'--enable-extended-glob'
9151     Include support for the extended pattern matching features
9152     described above under *note Pattern Matching::.
9153
9154'--enable-extended-glob-default'
9155     Set the default value of the EXTGLOB shell option described above
9156     under *note The Shopt Builtin:: to be enabled.
9157
9158'--enable-function-import'
9159     Include support for importing function definitions exported by
9160     another instance of the shell from the environment.  This option is
9161     enabled by default.
9162
9163'--enable-glob-asciirange-default'
9164     Set the default value of the GLOBASCIIRANGES shell option described
9165     above under *note The Shopt Builtin:: to be enabled.  This controls
9166     the behavior of character ranges when used in pattern matching
9167     bracket expressions.
9168
9169'--enable-help-builtin'
9170     Include the 'help' builtin, which displays help on shell builtins
9171     and variables (*note Bash Builtins::).
9172
9173'--enable-history'
9174     Include command history and the 'fc' and 'history' builtin commands
9175     (*note Bash History Facilities::).
9176
9177'--enable-job-control'
9178     This enables the job control features (*note Job Control::), if the
9179     operating system supports them.
9180
9181'--enable-multibyte'
9182     This enables support for multibyte characters if the operating
9183     system provides the necessary support.
9184
9185'--enable-net-redirections'
9186     This enables the special handling of filenames of the form
9187     '/dev/tcp/HOST/PORT' and '/dev/udp/HOST/PORT' when used in
9188     redirections (*note Redirections::).
9189
9190'--enable-process-substitution'
9191     This enables process substitution (*note Process Substitution::) if
9192     the operating system provides the necessary support.
9193
9194'--enable-progcomp'
9195     Enable the programmable completion facilities (*note Programmable
9196     Completion::).  If Readline is not enabled, this option has no
9197     effect.
9198
9199'--enable-prompt-string-decoding'
9200     Turn on the interpretation of a number of backslash-escaped
9201     characters in the '$PS1', '$PS2', '$PS3', and '$PS4' prompt
9202     strings.  See *note Controlling the Prompt::, for a complete list
9203     of prompt string escape sequences.
9204
9205'--enable-readline'
9206     Include support for command-line editing and history with the Bash
9207     version of the Readline library (*note Command Line Editing::).
9208
9209'--enable-restricted'
9210     Include support for a "restricted shell".  If this is enabled,
9211     Bash, when called as 'rbash', enters a restricted mode.  See *note
9212     The Restricted Shell::, for a description of restricted mode.
9213
9214'--enable-select'
9215     Include the 'select' compound command, which allows the generation
9216     of simple menus (*note Conditional Constructs::).
9217
9218'--enable-separate-helpfiles'
9219     Use external files for the documentation displayed by the 'help'
9220     builtin instead of storing the text internally.
9221
9222'--enable-single-help-strings'
9223     Store the text displayed by the 'help' builtin as a single string
9224     for each help topic.  This aids in translating the text to
9225     different languages.  You may need to disable this if your compiler
9226     cannot handle very long string literals.
9227
9228'--enable-strict-posix-default'
9229     Make Bash POSIX-conformant by default (*note Bash POSIX Mode::).
9230
9231'--enable-usg-echo-default'
9232     A synonym for '--enable-xpg-echo-default'.
9233
9234'--enable-xpg-echo-default'
9235     Make the 'echo' builtin expand backslash-escaped characters by
9236     default, without requiring the '-e' option.  This sets the default
9237     value of the 'xpg_echo' shell option to 'on', which makes the Bash
9238     'echo' behave more like the version specified in the Single Unix
9239     Specification, version 3.  *Note Bash Builtins::, for a description
9240     of the escape sequences that 'echo' recognizes.
9241
9242   The file 'config-top.h' contains C Preprocessor '#define' statements
9243for options which are not settable from 'configure'.  Some of these are
9244not meant to be changed; beware of the consequences if you do.  Read the
9245comments associated with each definition for more information about its
9246effect.
9247
9248Appendix A Reporting Bugs
9249*************************
9250
9251Please report all bugs you find in Bash.  But first, you should make
9252sure that it really is a bug, and that it appears in the latest version
9253of Bash.  The latest version of Bash is always available for FTP from
9254<ftp://ftp.gnu.org/pub/gnu/bash/>.
9255
9256   Once you have determined that a bug actually exists, use the
9257'bashbug' command to submit a bug report.  If you have a fix, you are
9258encouraged to mail that as well!  Suggestions and 'philosophical' bug
9259reports may be mailed to <bug-bash@gnu.org> or posted to the Usenet
9260newsgroup 'gnu.bash.bug'.
9261
9262   All bug reports should include:
9263   * The version number of Bash.
9264   * The hardware and operating system.
9265   * The compiler used to compile Bash.
9266   * A description of the bug behaviour.
9267   * A short script or 'recipe' which exercises the bug and may be used
9268     to reproduce it.
9269
9270'bashbug' inserts the first three items automatically into the template
9271it provides for filing a bug report.
9272
9273   Please send all reports concerning this manual to <bug-bash@gnu.org>.
9274
9275Appendix B Major Differences From The Bourne Shell
9276**************************************************
9277
9278Bash implements essentially the same grammar, parameter and variable
9279expansion, redirection, and quoting as the Bourne Shell.  Bash uses the
9280POSIX standard as the specification of how these features are to be
9281implemented.  There are some differences between the traditional Bourne
9282shell and Bash; this section quickly details the differences of
9283significance.  A number of these differences are explained in greater
9284depth in previous sections.  This section uses the version of 'sh'
9285included in SVR4.2 (the last version of the historical Bourne shell) as
9286the baseline reference.
9287
9288   * Bash is POSIX-conformant, even where the POSIX specification
9289     differs from traditional 'sh' behavior (*note Bash POSIX Mode::).
9290
9291   * Bash has multi-character invocation options (*note Invoking
9292     Bash::).
9293
9294   * Bash has command-line editing (*note Command Line Editing::) and
9295     the 'bind' builtin.
9296
9297   * Bash provides a programmable word completion mechanism (*note
9298     Programmable Completion::), and builtin commands 'complete',
9299     'compgen', and 'compopt', to manipulate it.
9300
9301   * Bash has command history (*note Bash History Facilities::) and the
9302     'history' and 'fc' builtins to manipulate it.  The Bash history
9303     list maintains timestamp information and uses the value of the
9304     'HISTTIMEFORMAT' variable to display it.
9305
9306   * Bash implements 'csh'-like history expansion (*note History
9307     Interaction::).
9308
9309   * Bash has one-dimensional array variables (*note Arrays::), and the
9310     appropriate variable expansions and assignment syntax to use them.
9311     Several of the Bash builtins take options to act on arrays.  Bash
9312     provides a number of built-in array variables.
9313
9314   * The '$'...'' quoting syntax, which expands ANSI-C backslash-escaped
9315     characters in the text between the single quotes, is supported
9316     (*note ANSI-C Quoting::).
9317
9318   * Bash supports the '$"..."' quoting syntax to do locale-specific
9319     translation of the characters between the double quotes.  The '-D',
9320     '--dump-strings', and '--dump-po-strings' invocation options list
9321     the translatable strings found in a script (*note Locale
9322     Translation::).
9323
9324   * Bash implements the '!' keyword to negate the return value of a
9325     pipeline (*note Pipelines::).  Very useful when an 'if' statement
9326     needs to act only if a test fails.  The Bash '-o pipefail' option
9327     to 'set' will cause a pipeline to return a failure status if any
9328     command fails.
9329
9330   * Bash has the 'time' reserved word and command timing (*note
9331     Pipelines::).  The display of the timing statistics may be
9332     controlled with the 'TIMEFORMAT' variable.
9333
9334   * Bash implements the 'for (( EXPR1 ; EXPR2 ; EXPR3 ))' arithmetic
9335     for command, similar to the C language (*note Looping
9336     Constructs::).
9337
9338   * Bash includes the 'select' compound command, which allows the
9339     generation of simple menus (*note Conditional Constructs::).
9340
9341   * Bash includes the '[[' compound command, which makes conditional
9342     testing part of the shell grammar (*note Conditional Constructs::),
9343     including optional regular expression matching.
9344
9345   * Bash provides optional case-insensitive matching for the 'case' and
9346     '[[' constructs.
9347
9348   * Bash includes brace expansion (*note Brace Expansion::) and tilde
9349     expansion (*note Tilde Expansion::).
9350
9351   * Bash implements command aliases and the 'alias' and 'unalias'
9352     builtins (*note Aliases::).
9353
9354   * Bash provides shell arithmetic, the '((' compound command (*note
9355     Conditional Constructs::), and arithmetic expansion (*note Shell
9356     Arithmetic::).
9357
9358   * Variables present in the shell's initial environment are
9359     automatically exported to child processes.  The Bourne shell does
9360     not normally do this unless the variables are explicitly marked
9361     using the 'export' command.
9362
9363   * Bash supports the '+=' assignment operator, which appends to the
9364     value of the variable named on the left hand side.
9365
9366   * Bash includes the POSIX pattern removal '%', '#', '%%' and '##'
9367     expansions to remove leading or trailing substrings from variable
9368     values (*note Shell Parameter Expansion::).
9369
9370   * The expansion '${#xx}', which returns the length of '${xx}', is
9371     supported (*note Shell Parameter Expansion::).
9372
9373   * The expansion '${var:'OFFSET'[:'LENGTH']}', which expands to the
9374     substring of 'var''s value of length LENGTH, beginning at OFFSET,
9375     is present (*note Shell Parameter Expansion::).
9376
9377   * The expansion '${var/[/]'PATTERN'[/'REPLACEMENT']}', which matches
9378     PATTERN and replaces it with REPLACEMENT in the value of 'var', is
9379     available (*note Shell Parameter Expansion::).
9380
9381   * The expansion '${!PREFIX*}' expansion, which expands to the names
9382     of all shell variables whose names begin with PREFIX, is available
9383     (*note Shell Parameter Expansion::).
9384
9385   * Bash has INDIRECT variable expansion using '${!word}' (*note Shell
9386     Parameter Expansion::).
9387
9388   * Bash can expand positional parameters beyond '$9' using '${NUM}'.
9389
9390   * The POSIX '$()' form of command substitution is implemented (*note
9391     Command Substitution::), and preferred to the Bourne shell's '``'
9392     (which is also implemented for backwards compatibility).
9393
9394   * Bash has process substitution (*note Process Substitution::).
9395
9396   * Bash automatically assigns variables that provide information about
9397     the current user ('UID', 'EUID', and 'GROUPS'), the current host
9398     ('HOSTTYPE', 'OSTYPE', 'MACHTYPE', and 'HOSTNAME'), and the
9399     instance of Bash that is running ('BASH', 'BASH_VERSION', and
9400     'BASH_VERSINFO').  *Note Bash Variables::, for details.
9401
9402   * The 'IFS' variable is used to split only the results of expansion,
9403     not all words (*note Word Splitting::).  This closes a longstanding
9404     shell security hole.
9405
9406   * The filename expansion bracket expression code uses '!' and '^' to
9407     negate the set of characters between the brackets.  The Bourne
9408     shell uses only '!'.
9409
9410   * Bash implements the full set of POSIX filename expansion operators,
9411     including CHARACTER CLASSES, EQUIVALENCE CLASSES, and COLLATING
9412     SYMBOLS (*note Filename Expansion::).
9413
9414   * Bash implements extended pattern matching features when the
9415     'extglob' shell option is enabled (*note Pattern Matching::).
9416
9417   * It is possible to have a variable and a function with the same
9418     name; 'sh' does not separate the two name spaces.
9419
9420   * Bash functions are permitted to have local variables using the
9421     'local' builtin, and thus useful recursive functions may be written
9422     (*note Bash Builtins::).
9423
9424   * Variable assignments preceding commands affect only that command,
9425     even builtins and functions (*note Environment::).  In 'sh', all
9426     variable assignments preceding commands are global unless the
9427     command is executed from the file system.
9428
9429   * Bash performs filename expansion on filenames specified as operands
9430     to input and output redirection operators (*note Redirections::).
9431
9432   * Bash contains the '<>' redirection operator, allowing a file to be
9433     opened for both reading and writing, and the '&>' redirection
9434     operator, for directing standard output and standard error to the
9435     same file (*note Redirections::).
9436
9437   * Bash includes the '<<<' redirection operator, allowing a string to
9438     be used as the standard input to a command.
9439
9440   * Bash implements the '[n]<&WORD' and '[n]>&WORD' redirection
9441     operators, which move one file descriptor to another.
9442
9443   * Bash treats a number of filenames specially when they are used in
9444     redirection operators (*note Redirections::).
9445
9446   * Bash can open network connections to arbitrary machines and
9447     services with the redirection operators (*note Redirections::).
9448
9449   * The 'noclobber' option is available to avoid overwriting existing
9450     files with output redirection (*note The Set Builtin::).  The '>|'
9451     redirection operator may be used to override 'noclobber'.
9452
9453   * The Bash 'cd' and 'pwd' builtins (*note Bourne Shell Builtins::)
9454     each take '-L' and '-P' options to switch between logical and
9455     physical modes.
9456
9457   * Bash allows a function to override a builtin with the same name,
9458     and provides access to that builtin's functionality within the
9459     function via the 'builtin' and 'command' builtins (*note Bash
9460     Builtins::).
9461
9462   * The 'command' builtin allows selective disabling of functions when
9463     command lookup is performed (*note Bash Builtins::).
9464
9465   * Individual builtins may be enabled or disabled using the 'enable'
9466     builtin (*note Bash Builtins::).
9467
9468   * The Bash 'exec' builtin takes additional options that allow users
9469     to control the contents of the environment passed to the executed
9470     command, and what the zeroth argument to the command is to be
9471     (*note Bourne Shell Builtins::).
9472
9473   * Shell functions may be exported to children via the environment
9474     using 'export -f' (*note Shell Functions::).
9475
9476   * The Bash 'export', 'readonly', and 'declare' builtins can take a
9477     '-f' option to act on shell functions, a '-p' option to display
9478     variables with various attributes set in a format that can be used
9479     as shell input, a '-n' option to remove various variable
9480     attributes, and 'name=value' arguments to set variable attributes
9481     and values simultaneously.
9482
9483   * The Bash 'hash' builtin allows a name to be associated with an
9484     arbitrary filename, even when that filename cannot be found by
9485     searching the '$PATH', using 'hash -p' (*note Bourne Shell
9486     Builtins::).
9487
9488   * Bash includes a 'help' builtin for quick reference to shell
9489     facilities (*note Bash Builtins::).
9490
9491   * The 'printf' builtin is available to display formatted output
9492     (*note Bash Builtins::).
9493
9494   * The Bash 'read' builtin (*note Bash Builtins::) will read a line
9495     ending in '\' with the '-r' option, and will use the 'REPLY'
9496     variable as a default if no non-option arguments are supplied.  The
9497     Bash 'read' builtin also accepts a prompt string with the '-p'
9498     option and will use Readline to obtain the line when given the '-e'
9499     option.  The 'read' builtin also has additional options to control
9500     input: the '-s' option will turn off echoing of input characters as
9501     they are read, the '-t' option will allow 'read' to time out if
9502     input does not arrive within a specified number of seconds, the
9503     '-n' option will allow reading only a specified number of
9504     characters rather than a full line, and the '-d' option will read
9505     until a particular character rather than newline.
9506
9507   * The 'return' builtin may be used to abort execution of scripts
9508     executed with the '.' or 'source' builtins (*note Bourne Shell
9509     Builtins::).
9510
9511   * Bash includes the 'shopt' builtin, for finer control of shell
9512     optional capabilities (*note The Shopt Builtin::), and allows these
9513     options to be set and unset at shell invocation (*note Invoking
9514     Bash::).
9515
9516   * Bash has much more optional behavior controllable with the 'set'
9517     builtin (*note The Set Builtin::).
9518
9519   * The '-x' ('xtrace') option displays commands other than simple
9520     commands when performing an execution trace (*note The Set
9521     Builtin::).
9522
9523   * The 'test' builtin (*note Bourne Shell Builtins::) is slightly
9524     different, as it implements the POSIX algorithm, which specifies
9525     the behavior based on the number of arguments.
9526
9527   * Bash includes the 'caller' builtin, which displays the context of
9528     any active subroutine call (a shell function or a script executed
9529     with the '.' or 'source' builtins).  This supports the bash
9530     debugger.
9531
9532   * The 'trap' builtin (*note Bourne Shell Builtins::) allows a 'DEBUG'
9533     pseudo-signal specification, similar to 'EXIT'.  Commands specified
9534     with a 'DEBUG' trap are executed before every simple command, 'for'
9535     command, 'case' command, 'select' command, every arithmetic 'for'
9536     command, and before the first command executes in a shell function.
9537     The 'DEBUG' trap is not inherited by shell functions unless the
9538     function has been given the 'trace' attribute or the 'functrace'
9539     option has been enabled using the 'shopt' builtin.  The 'extdebug'
9540     shell option has additional effects on the 'DEBUG' trap.
9541
9542     The 'trap' builtin (*note Bourne Shell Builtins::) allows an 'ERR'
9543     pseudo-signal specification, similar to 'EXIT' and 'DEBUG'.
9544     Commands specified with an 'ERR' trap are executed after a simple
9545     command fails, with a few exceptions.  The 'ERR' trap is not
9546     inherited by shell functions unless the '-o errtrace' option to the
9547     'set' builtin is enabled.
9548
9549     The 'trap' builtin (*note Bourne Shell Builtins::) allows a
9550     'RETURN' pseudo-signal specification, similar to 'EXIT' and
9551     'DEBUG'.  Commands specified with an 'RETURN' trap are executed
9552     before execution resumes after a shell function or a shell script
9553     executed with '.' or 'source' returns.  The 'RETURN' trap is not
9554     inherited by shell functions unless the function has been given the
9555     'trace' attribute or the 'functrace' option has been enabled using
9556     the 'shopt' builtin.
9557
9558   * The Bash 'type' builtin is more extensive and gives more
9559     information about the names it finds (*note Bash Builtins::).
9560
9561   * The Bash 'umask' builtin permits a '-p' option to cause the output
9562     to be displayed in the form of a 'umask' command that may be reused
9563     as input (*note Bourne Shell Builtins::).
9564
9565   * Bash implements a 'csh'-like directory stack, and provides the
9566     'pushd', 'popd', and 'dirs' builtins to manipulate it (*note The
9567     Directory Stack::).  Bash also makes the directory stack visible as
9568     the value of the 'DIRSTACK' shell variable.
9569
9570   * Bash interprets special backslash-escaped characters in the prompt
9571     strings when interactive (*note Controlling the Prompt::).
9572
9573   * The Bash restricted mode is more useful (*note The Restricted
9574     Shell::); the SVR4.2 shell restricted mode is too limited.
9575
9576   * The 'disown' builtin can remove a job from the internal shell job
9577     table (*note Job Control Builtins::) or suppress the sending of
9578     'SIGHUP' to a job when the shell exits as the result of a 'SIGHUP'.
9579
9580   * Bash includes a number of features to support a separate debugger
9581     for shell scripts.
9582
9583   * The SVR4.2 shell has two privilege-related builtins ('mldmode' and
9584     'priv') not present in Bash.
9585
9586   * Bash does not have the 'stop' or 'newgrp' builtins.
9587
9588   * Bash does not use the 'SHACCT' variable or perform shell
9589     accounting.
9590
9591   * The SVR4.2 'sh' uses a 'TIMEOUT' variable like Bash uses 'TMOUT'.
9592
9593More features unique to Bash may be found in *note Bash Features::.
9594
9595B.1 Implementation Differences From The SVR4.2 Shell
9596====================================================
9597
9598Since Bash is a completely new implementation, it does not suffer from
9599many of the limitations of the SVR4.2 shell.  For instance:
9600
9601   * Bash does not fork a subshell when redirecting into or out of a
9602     shell control structure such as an 'if' or 'while' statement.
9603
9604   * Bash does not allow unbalanced quotes.  The SVR4.2 shell will
9605     silently insert a needed closing quote at 'EOF' under certain
9606     circumstances.  This can be the cause of some hard-to-find errors.
9607
9608   * The SVR4.2 shell uses a baroque memory management scheme based on
9609     trapping 'SIGSEGV'.  If the shell is started from a process with
9610     'SIGSEGV' blocked (e.g., by using the 'system()' C library function
9611     call), it misbehaves badly.
9612
9613   * In a questionable attempt at security, the SVR4.2 shell, when
9614     invoked without the '-p' option, will alter its real and effective
9615     UID and GID if they are less than some magic threshold value,
9616     commonly 100.  This can lead to unexpected results.
9617
9618   * The SVR4.2 shell does not allow users to trap 'SIGSEGV', 'SIGALRM',
9619     or 'SIGCHLD'.
9620
9621   * The SVR4.2 shell does not allow the 'IFS', 'MAILCHECK', 'PATH',
9622     'PS1', or 'PS2' variables to be unset.
9623
9624   * The SVR4.2 shell treats '^' as the undocumented equivalent of '|'.
9625
9626   * Bash allows multiple option arguments when it is invoked ('-x -v');
9627     the SVR4.2 shell allows only one option argument ('-xv').  In fact,
9628     some versions of the shell dump core if the second argument begins
9629     with a '-'.
9630
9631   * The SVR4.2 shell exits a script if any builtin fails; Bash exits a
9632     script only if one of the POSIX special builtins fails, and only
9633     for certain failures, as enumerated in the POSIX standard.
9634
9635   * The SVR4.2 shell behaves differently when invoked as 'jsh' (it
9636     turns on job control).
9637
9638Appendix C GNU Free Documentation License
9639*****************************************
9640
9641                     Version 1.3, 3 November 2008
9642
9643     Copyright (C) 2000, 2001, 2002, 2007, 2008 Free Software Foundation, Inc.
9644     <http://fsf.org/>
9645
9646     Everyone is permitted to copy and distribute verbatim copies
9647     of this license document, but changing it is not allowed.
9648
9649  0. PREAMBLE
9650
9651     The purpose of this License is to make a manual, textbook, or other
9652     functional and useful document "free" in the sense of freedom: to
9653     assure everyone the effective freedom to copy and redistribute it,
9654     with or without modifying it, either commercially or
9655     noncommercially.  Secondarily, this License preserves for the
9656     author and publisher a way to get credit for their work, while not
9657     being considered responsible for modifications made by others.
9658
9659     This License is a kind of "copyleft", which means that derivative
9660     works of the document must themselves be free in the same sense.
9661     It complements the GNU General Public License, which is a copyleft
9662     license designed for free software.
9663
9664     We have designed this License in order to use it for manuals for
9665     free software, because free software needs free documentation: a
9666     free program should come with manuals providing the same freedoms
9667     that the software does.  But this License is not limited to
9668     software manuals; it can be used for any textual work, regardless
9669     of subject matter or whether it is published as a printed book.  We
9670     recommend this License principally for works whose purpose is
9671     instruction or reference.
9672
9673  1. APPLICABILITY AND DEFINITIONS
9674
9675     This License applies to any manual or other work, in any medium,
9676     that contains a notice placed by the copyright holder saying it can
9677     be distributed under the terms of this License.  Such a notice
9678     grants a world-wide, royalty-free license, unlimited in duration,
9679     to use that work under the conditions stated herein.  The
9680     "Document", below, refers to any such manual or work.  Any member
9681     of the public is a licensee, and is addressed as "you".  You accept
9682     the license if you copy, modify or distribute the work in a way
9683     requiring permission under copyright law.
9684
9685     A "Modified Version" of the Document means any work containing the
9686     Document or a portion of it, either copied verbatim, or with
9687     modifications and/or translated into another language.
9688
9689     A "Secondary Section" is a named appendix or a front-matter section
9690     of the Document that deals exclusively with the relationship of the
9691     publishers or authors of the Document to the Document's overall
9692     subject (or to related matters) and contains nothing that could
9693     fall directly within that overall subject.  (Thus, if the Document
9694     is in part a textbook of mathematics, a Secondary Section may not
9695     explain any mathematics.)  The relationship could be a matter of
9696     historical connection with the subject or with related matters, or
9697     of legal, commercial, philosophical, ethical or political position
9698     regarding them.
9699
9700     The "Invariant Sections" are certain Secondary Sections whose
9701     titles are designated, as being those of Invariant Sections, in the
9702     notice that says that the Document is released under this License.
9703     If a section does not fit the above definition of Secondary then it
9704     is not allowed to be designated as Invariant.  The Document may
9705     contain zero Invariant Sections.  If the Document does not identify
9706     any Invariant Sections then there are none.
9707
9708     The "Cover Texts" are certain short passages of text that are
9709     listed, as Front-Cover Texts or Back-Cover Texts, in the notice
9710     that says that the Document is released under this License.  A
9711     Front-Cover Text may be at most 5 words, and a Back-Cover Text may
9712     be at most 25 words.
9713
9714     A "Transparent" copy of the Document means a machine-readable copy,
9715     represented in a format whose specification is available to the
9716     general public, that is suitable for revising the document
9717     straightforwardly with generic text editors or (for images composed
9718     of pixels) generic paint programs or (for drawings) some widely
9719     available drawing editor, and that is suitable for input to text
9720     formatters or for automatic translation to a variety of formats
9721     suitable for input to text formatters.  A copy made in an otherwise
9722     Transparent file format whose markup, or absence of markup, has
9723     been arranged to thwart or discourage subsequent modification by
9724     readers is not Transparent.  An image format is not Transparent if
9725     used for any substantial amount of text.  A copy that is not
9726     "Transparent" is called "Opaque".
9727
9728     Examples of suitable formats for Transparent copies include plain
9729     ASCII without markup, Texinfo input format, LaTeX input format,
9730     SGML or XML using a publicly available DTD, and standard-conforming
9731     simple HTML, PostScript or PDF designed for human modification.
9732     Examples of transparent image formats include PNG, XCF and JPG.
9733     Opaque formats include proprietary formats that can be read and
9734     edited only by proprietary word processors, SGML or XML for which
9735     the DTD and/or processing tools are not generally available, and
9736     the machine-generated HTML, PostScript or PDF produced by some word
9737     processors for output purposes only.
9738
9739     The "Title Page" means, for a printed book, the title page itself,
9740     plus such following pages as are needed to hold, legibly, the
9741     material this License requires to appear in the title page.  For
9742     works in formats which do not have any title page as such, "Title
9743     Page" means the text near the most prominent appearance of the
9744     work's title, preceding the beginning of the body of the text.
9745
9746     The "publisher" means any person or entity that distributes copies
9747     of the Document to the public.
9748
9749     A section "Entitled XYZ" means a named subunit of the Document
9750     whose title either is precisely XYZ or contains XYZ in parentheses
9751     following text that translates XYZ in another language.  (Here XYZ
9752     stands for a specific section name mentioned below, such as
9753     "Acknowledgements", "Dedications", "Endorsements", or "History".)
9754     To "Preserve the Title" of such a section when you modify the
9755     Document means that it remains a section "Entitled XYZ" according
9756     to this definition.
9757
9758     The Document may include Warranty Disclaimers next to the notice
9759     which states that this License applies to the Document.  These
9760     Warranty Disclaimers are considered to be included by reference in
9761     this License, but only as regards disclaiming warranties: any other
9762     implication that these Warranty Disclaimers may have is void and
9763     has no effect on the meaning of this License.
9764
9765  2. VERBATIM COPYING
9766
9767     You may copy and distribute the Document in any medium, either
9768     commercially or noncommercially, provided that this License, the
9769     copyright notices, and the license notice saying this License
9770     applies to the Document are reproduced in all copies, and that you
9771     add no other conditions whatsoever to those of this License.  You
9772     may not use technical measures to obstruct or control the reading
9773     or further copying of the copies you make or distribute.  However,
9774     you may accept compensation in exchange for copies.  If you
9775     distribute a large enough number of copies you must also follow the
9776     conditions in section 3.
9777
9778     You may also lend copies, under the same conditions stated above,
9779     and you may publicly display copies.
9780
9781  3. COPYING IN QUANTITY
9782
9783     If you publish printed copies (or copies in media that commonly
9784     have printed covers) of the Document, numbering more than 100, and
9785     the Document's license notice requires Cover Texts, you must
9786     enclose the copies in covers that carry, clearly and legibly, all
9787     these Cover Texts: Front-Cover Texts on the front cover, and
9788     Back-Cover Texts on the back cover.  Both covers must also clearly
9789     and legibly identify you as the publisher of these copies.  The
9790     front cover must present the full title with all words of the title
9791     equally prominent and visible.  You may add other material on the
9792     covers in addition.  Copying with changes limited to the covers, as
9793     long as they preserve the title of the Document and satisfy these
9794     conditions, can be treated as verbatim copying in other respects.
9795
9796     If the required texts for either cover are too voluminous to fit
9797     legibly, you should put the first ones listed (as many as fit
9798     reasonably) on the actual cover, and continue the rest onto
9799     adjacent pages.
9800
9801     If you publish or distribute Opaque copies of the Document
9802     numbering more than 100, you must either include a machine-readable
9803     Transparent copy along with each Opaque copy, or state in or with
9804     each Opaque copy a computer-network location from which the general
9805     network-using public has access to download using public-standard
9806     network protocols a complete Transparent copy of the Document, free
9807     of added material.  If you use the latter option, you must take
9808     reasonably prudent steps, when you begin distribution of Opaque
9809     copies in quantity, to ensure that this Transparent copy will
9810     remain thus accessible at the stated location until at least one
9811     year after the last time you distribute an Opaque copy (directly or
9812     through your agents or retailers) of that edition to the public.
9813
9814     It is requested, but not required, that you contact the authors of
9815     the Document well before redistributing any large number of copies,
9816     to give them a chance to provide you with an updated version of the
9817     Document.
9818
9819  4. MODIFICATIONS
9820
9821     You may copy and distribute a Modified Version of the Document
9822     under the conditions of sections 2 and 3 above, provided that you
9823     release the Modified Version under precisely this License, with the
9824     Modified Version filling the role of the Document, thus licensing
9825     distribution and modification of the Modified Version to whoever
9826     possesses a copy of it.  In addition, you must do these things in
9827     the Modified Version:
9828
9829       A. Use in the Title Page (and on the covers, if any) a title
9830          distinct from that of the Document, and from those of previous
9831          versions (which should, if there were any, be listed in the
9832          History section of the Document).  You may use the same title
9833          as a previous version if the original publisher of that
9834          version gives permission.
9835
9836       B. List on the Title Page, as authors, one or more persons or
9837          entities responsible for authorship of the modifications in
9838          the Modified Version, together with at least five of the
9839          principal authors of the Document (all of its principal
9840          authors, if it has fewer than five), unless they release you
9841          from this requirement.
9842
9843       C. State on the Title page the name of the publisher of the
9844          Modified Version, as the publisher.
9845
9846       D. Preserve all the copyright notices of the Document.
9847
9848       E. Add an appropriate copyright notice for your modifications
9849          adjacent to the other copyright notices.
9850
9851       F. Include, immediately after the copyright notices, a license
9852          notice giving the public permission to use the Modified
9853          Version under the terms of this License, in the form shown in
9854          the Addendum below.
9855
9856       G. Preserve in that license notice the full lists of Invariant
9857          Sections and required Cover Texts given in the Document's
9858          license notice.
9859
9860       H. Include an unaltered copy of this License.
9861
9862       I. Preserve the section Entitled "History", Preserve its Title,
9863          and add to it an item stating at least the title, year, new
9864          authors, and publisher of the Modified Version as given on the
9865          Title Page.  If there is no section Entitled "History" in the
9866          Document, create one stating the title, year, authors, and
9867          publisher of the Document as given on its Title Page, then add
9868          an item describing the Modified Version as stated in the
9869          previous sentence.
9870
9871       J. Preserve the network location, if any, given in the Document
9872          for public access to a Transparent copy of the Document, and
9873          likewise the network locations given in the Document for
9874          previous versions it was based on.  These may be placed in the
9875          "History" section.  You may omit a network location for a work
9876          that was published at least four years before the Document
9877          itself, or if the original publisher of the version it refers
9878          to gives permission.
9879
9880       K. For any section Entitled "Acknowledgements" or "Dedications",
9881          Preserve the Title of the section, and preserve in the section
9882          all the substance and tone of each of the contributor
9883          acknowledgements and/or dedications given therein.
9884
9885       L. Preserve all the Invariant Sections of the Document, unaltered
9886          in their text and in their titles.  Section numbers or the
9887          equivalent are not considered part of the section titles.
9888
9889       M. Delete any section Entitled "Endorsements".  Such a section
9890          may not be included in the Modified Version.
9891
9892       N. Do not retitle any existing section to be Entitled
9893          "Endorsements" or to conflict in title with any Invariant
9894          Section.
9895
9896       O. Preserve any Warranty Disclaimers.
9897
9898     If the Modified Version includes new front-matter sections or
9899     appendices that qualify as Secondary Sections and contain no
9900     material copied from the Document, you may at your option designate
9901     some or all of these sections as invariant.  To do this, add their
9902     titles to the list of Invariant Sections in the Modified Version's
9903     license notice.  These titles must be distinct from any other
9904     section titles.
9905
9906     You may add a section Entitled "Endorsements", provided it contains
9907     nothing but endorsements of your Modified Version by various
9908     parties--for example, statements of peer review or that the text
9909     has been approved by an organization as the authoritative
9910     definition of a standard.
9911
9912     You may add a passage of up to five words as a Front-Cover Text,
9913     and a passage of up to 25 words as a Back-Cover Text, to the end of
9914     the list of Cover Texts in the Modified Version.  Only one passage
9915     of Front-Cover Text and one of Back-Cover Text may be added by (or
9916     through arrangements made by) any one entity.  If the Document
9917     already includes a cover text for the same cover, previously added
9918     by you or by arrangement made by the same entity you are acting on
9919     behalf of, you may not add another; but you may replace the old
9920     one, on explicit permission from the previous publisher that added
9921     the old one.
9922
9923     The author(s) and publisher(s) of the Document do not by this
9924     License give permission to use their names for publicity for or to
9925     assert or imply endorsement of any Modified Version.
9926
9927  5. COMBINING DOCUMENTS
9928
9929     You may combine the Document with other documents released under
9930     this License, under the terms defined in section 4 above for
9931     modified versions, provided that you include in the combination all
9932     of the Invariant Sections of all of the original documents,
9933     unmodified, and list them all as Invariant Sections of your
9934     combined work in its license notice, and that you preserve all
9935     their Warranty Disclaimers.
9936
9937     The combined work need only contain one copy of this License, and
9938     multiple identical Invariant Sections may be replaced with a single
9939     copy.  If there are multiple Invariant Sections with the same name
9940     but different contents, make the title of each such section unique
9941     by adding at the end of it, in parentheses, the name of the
9942     original author or publisher of that section if known, or else a
9943     unique number.  Make the same adjustment to the section titles in
9944     the list of Invariant Sections in the license notice of the
9945     combined work.
9946
9947     In the combination, you must combine any sections Entitled
9948     "History" in the various original documents, forming one section
9949     Entitled "History"; likewise combine any sections Entitled
9950     "Acknowledgements", and any sections Entitled "Dedications".  You
9951     must delete all sections Entitled "Endorsements."
9952
9953  6. COLLECTIONS OF DOCUMENTS
9954
9955     You may make a collection consisting of the Document and other
9956     documents released under this License, and replace the individual
9957     copies of this License in the various documents with a single copy
9958     that is included in the collection, provided that you follow the
9959     rules of this License for verbatim copying of each of the documents
9960     in all other respects.
9961
9962     You may extract a single document from such a collection, and
9963     distribute it individually under this License, provided you insert
9964     a copy of this License into the extracted document, and follow this
9965     License in all other respects regarding verbatim copying of that
9966     document.
9967
9968  7. AGGREGATION WITH INDEPENDENT WORKS
9969
9970     A compilation of the Document or its derivatives with other
9971     separate and independent documents or works, in or on a volume of a
9972     storage or distribution medium, is called an "aggregate" if the
9973     copyright resulting from the compilation is not used to limit the
9974     legal rights of the compilation's users beyond what the individual
9975     works permit.  When the Document is included in an aggregate, this
9976     License does not apply to the other works in the aggregate which
9977     are not themselves derivative works of the Document.
9978
9979     If the Cover Text requirement of section 3 is applicable to these
9980     copies of the Document, then if the Document is less than one half
9981     of the entire aggregate, the Document's Cover Texts may be placed
9982     on covers that bracket the Document within the aggregate, or the
9983     electronic equivalent of covers if the Document is in electronic
9984     form.  Otherwise they must appear on printed covers that bracket
9985     the whole aggregate.
9986
9987  8. TRANSLATION
9988
9989     Translation is considered a kind of modification, so you may
9990     distribute translations of the Document under the terms of section
9991     4.  Replacing Invariant Sections with translations requires special
9992     permission from their copyright holders, but you may include
9993     translations of some or all Invariant Sections in addition to the
9994     original versions of these Invariant Sections.  You may include a
9995     translation of this License, and all the license notices in the
9996     Document, and any Warranty Disclaimers, provided that you also
9997     include the original English version of this License and the
9998     original versions of those notices and disclaimers.  In case of a
9999     disagreement between the translation and the original version of
10000     this License or a notice or disclaimer, the original version will
10001     prevail.
10002
10003     If a section in the Document is Entitled "Acknowledgements",
10004     "Dedications", or "History", the requirement (section 4) to
10005     Preserve its Title (section 1) will typically require changing the
10006     actual title.
10007
10008  9. TERMINATION
10009
10010     You may not copy, modify, sublicense, or distribute the Document
10011     except as expressly provided under this License.  Any attempt
10012     otherwise to copy, modify, sublicense, or distribute it is void,
10013     and will automatically terminate your rights under this License.
10014
10015     However, if you cease all violation of this License, then your
10016     license from a particular copyright holder is reinstated (a)
10017     provisionally, unless and until the copyright holder explicitly and
10018     finally terminates your license, and (b) permanently, if the
10019     copyright holder fails to notify you of the violation by some
10020     reasonable means prior to 60 days after the cessation.
10021
10022     Moreover, your license from a particular copyright holder is
10023     reinstated permanently if the copyright holder notifies you of the
10024     violation by some reasonable means, this is the first time you have
10025     received notice of violation of this License (for any work) from
10026     that copyright holder, and you cure the violation prior to 30 days
10027     after your receipt of the notice.
10028
10029     Termination of your rights under this section does not terminate
10030     the licenses of parties who have received copies or rights from you
10031     under this License.  If your rights have been terminated and not
10032     permanently reinstated, receipt of a copy of some or all of the
10033     same material does not give you any rights to use it.
10034
10035  10. FUTURE REVISIONS OF THIS LICENSE
10036
10037     The Free Software Foundation may publish new, revised versions of
10038     the GNU Free Documentation License from time to time.  Such new
10039     versions will be similar in spirit to the present version, but may
10040     differ in detail to address new problems or concerns.  See
10041     <http://www.gnu.org/copyleft/>.
10042
10043     Each version of the License is given a distinguishing version
10044     number.  If the Document specifies that a particular numbered
10045     version of this License "or any later version" applies to it, you
10046     have the option of following the terms and conditions either of
10047     that specified version or of any later version that has been
10048     published (not as a draft) by the Free Software Foundation.  If the
10049     Document does not specify a version number of this License, you may
10050     choose any version ever published (not as a draft) by the Free
10051     Software Foundation.  If the Document specifies that a proxy can
10052     decide which future versions of this License can be used, that
10053     proxy's public statement of acceptance of a version permanently
10054     authorizes you to choose that version for the Document.
10055
10056  11. RELICENSING
10057
10058     "Massive Multiauthor Collaboration Site" (or "MMC Site") means any
10059     World Wide Web server that publishes copyrightable works and also
10060     provides prominent facilities for anybody to edit those works.  A
10061     public wiki that anybody can edit is an example of such a server.
10062     A "Massive Multiauthor Collaboration" (or "MMC") contained in the
10063     site means any set of copyrightable works thus published on the MMC
10064     site.
10065
10066     "CC-BY-SA" means the Creative Commons Attribution-Share Alike 3.0
10067     license published by Creative Commons Corporation, a not-for-profit
10068     corporation with a principal place of business in San Francisco,
10069     California, as well as future copyleft versions of that license
10070     published by that same organization.
10071
10072     "Incorporate" means to publish or republish a Document, in whole or
10073     in part, as part of another Document.
10074
10075     An MMC is "eligible for relicensing" if it is licensed under this
10076     License, and if all works that were first published under this
10077     License somewhere other than this MMC, and subsequently
10078     incorporated in whole or in part into the MMC, (1) had no cover
10079     texts or invariant sections, and (2) were thus incorporated prior
10080     to November 1, 2008.
10081
10082     The operator of an MMC Site may republish an MMC contained in the
10083     site under CC-BY-SA on the same site at any time before August 1,
10084     2009, provided the MMC is eligible for relicensing.
10085
10086ADDENDUM: How to use this License for your documents
10087====================================================
10088
10089To use this License in a document you have written, include a copy of
10090the License in the document and put the following copyright and license
10091notices just after the title page:
10092
10093       Copyright (C)  YEAR  YOUR NAME.
10094       Permission is granted to copy, distribute and/or modify this document
10095       under the terms of the GNU Free Documentation License, Version 1.3
10096       or any later version published by the Free Software Foundation;
10097       with no Invariant Sections, no Front-Cover Texts, and no Back-Cover
10098       Texts.  A copy of the license is included in the section entitled ``GNU
10099       Free Documentation License''.
10100
10101   If you have Invariant Sections, Front-Cover Texts and Back-Cover
10102Texts, replace the "with...Texts."  line with this:
10103
10104         with the Invariant Sections being LIST THEIR TITLES, with
10105         the Front-Cover Texts being LIST, and with the Back-Cover Texts
10106         being LIST.
10107
10108   If you have Invariant Sections without Cover Texts, or some other
10109combination of the three, merge those two alternatives to suit the
10110situation.
10111
10112   If your document contains nontrivial examples of program code, we
10113recommend releasing these examples in parallel under your choice of free
10114software license, such as the GNU General Public License, to permit
10115their use in free software.
10116
10117Appendix D Indexes
10118******************
10119
10120D.1 Index of Shell Builtin Commands
10121===================================
10122
10123* Menu:
10124
10125* .:                                     Bourne Shell Builtins.
10126                                                             (line 2655)
10127* ::                                     Bourne Shell Builtins.
10128                                                             (line 2649)
10129* [:                                     Bourne Shell Builtins.
10130                                                             (line 2906)
10131* alias:                                 Bash Builtins.      (line 3076)
10132* bg:                                    Job Control Builtins.
10133                                                             (line 6425)
10134* bind:                                  Bash Builtins.      (line 3086)
10135* break:                                 Bourne Shell Builtins.
10136                                                             (line 2674)
10137* builtin:                               Bash Builtins.      (line 3167)
10138* caller:                                Bash Builtins.      (line 3176)
10139* cd:                                    Bourne Shell Builtins.
10140                                                             (line 2682)
10141* command:                               Bash Builtins.      (line 3193)
10142* compgen:                               Programmable Completion Builtins.
10143                                                             (line 8123)
10144* complete:                              Programmable Completion Builtins.
10145                                                             (line 8141)
10146* compopt:                               Programmable Completion Builtins.
10147                                                             (line 8340)
10148* continue:                              Bourne Shell Builtins.
10149                                                             (line 2723)
10150* declare:                               Bash Builtins.      (line 3213)
10151* dirs:                                  Directory Stack Builtins.
10152                                                             (line 5908)
10153* disown:                                Job Control Builtins.
10154                                                             (line 6507)
10155* echo:                                  Bash Builtins.      (line 3310)
10156* enable:                                Bash Builtins.      (line 3359)
10157* eval:                                  Bourne Shell Builtins.
10158                                                             (line 2732)
10159* exec:                                  Bourne Shell Builtins.
10160                                                             (line 2740)
10161* exit:                                  Bourne Shell Builtins.
10162                                                             (line 2757)
10163* export:                                Bourne Shell Builtins.
10164                                                             (line 2764)
10165* fc:                                    Bash History Builtins.
10166                                                             (line 8535)
10167* fg:                                    Job Control Builtins.
10168                                                             (line 6435)
10169* getopts:                               Bourne Shell Builtins.
10170                                                             (line 2780)
10171* hash:                                  Bourne Shell Builtins.
10172                                                             (line 2823)
10173* help:                                  Bash Builtins.      (line 3388)
10174* history:                               Bash History Builtins.
10175                                                             (line 8565)
10176* jobs:                                  Job Control Builtins.
10177                                                             (line 6445)
10178* kill:                                  Job Control Builtins.
10179                                                             (line 6476)
10180* let:                                   Bash Builtins.      (line 3407)
10181* local:                                 Bash Builtins.      (line 3415)
10182* logout:                                Bash Builtins.      (line 3429)
10183* mapfile:                               Bash Builtins.      (line 3434)
10184* popd:                                  Directory Stack Builtins.
10185                                                             (line 5936)
10186* printf:                                Bash Builtins.      (line 3479)
10187* pushd:                                 Directory Stack Builtins.
10188                                                             (line 5954)
10189* pwd:                                   Bourne Shell Builtins.
10190                                                             (line 2843)
10191* read:                                  Bash Builtins.      (line 3523)
10192* readarray:                             Bash Builtins.      (line 3615)
10193* readonly:                              Bourne Shell Builtins.
10194                                                             (line 2853)
10195* return:                                Bourne Shell Builtins.
10196                                                             (line 2872)
10197* set:                                   The Set Builtin.    (line 3782)
10198* shift:                                 Bourne Shell Builtins.
10199                                                             (line 2893)
10200* shopt:                                 The Shopt Builtin.  (line 4058)
10201* source:                                Bash Builtins.      (line 3624)
10202* suspend:                               Job Control Builtins.
10203                                                             (line 6519)
10204* test:                                  Bourne Shell Builtins.
10205                                                             (line 2906)
10206* times:                                 Bourne Shell Builtins.
10207                                                             (line 2981)
10208* trap:                                  Bourne Shell Builtins.
10209                                                             (line 2987)
10210* type:                                  Bash Builtins.      (line 3629)
10211* typeset:                               Bash Builtins.      (line 3661)
10212* ulimit:                                Bash Builtins.      (line 3667)
10213* umask:                                 Bourne Shell Builtins.
10214                                                             (line 3036)
10215* unalias:                               Bash Builtins.      (line 3766)
10216* unset:                                 Bourne Shell Builtins.
10217                                                             (line 3054)
10218* wait:                                  Job Control Builtins.
10219                                                             (line 6494)
10220
10221D.2 Index of Shell Reserved Words
10222=================================
10223
10224* Menu:
10225
10226* !:                                     Pipelines.          (line  550)
10227* [[:                                    Conditional Constructs.
10228                                                             (line  834)
10229* ]]:                                    Conditional Constructs.
10230                                                             (line  834)
10231* {:                                     Command Grouping.   (line  965)
10232* }:                                     Command Grouping.   (line  965)
10233* case:                                  Conditional Constructs.
10234                                                             (line  741)
10235* do:                                    Looping Constructs. (line  666)
10236* done:                                  Looping Constructs. (line  666)
10237* elif:                                  Conditional Constructs.
10238                                                             (line  720)
10239* else:                                  Conditional Constructs.
10240                                                             (line  720)
10241* esac:                                  Conditional Constructs.
10242                                                             (line  741)
10243* fi:                                    Conditional Constructs.
10244                                                             (line  720)
10245* for:                                   Looping Constructs. (line  686)
10246* function:                              Shell Functions.    (line 1110)
10247* if:                                    Conditional Constructs.
10248                                                             (line  720)
10249* in:                                    Conditional Constructs.
10250                                                             (line  741)
10251* select:                                Conditional Constructs.
10252                                                             (line  792)
10253* then:                                  Conditional Constructs.
10254                                                             (line  720)
10255* time:                                  Pipelines.          (line  550)
10256* until:                                 Looping Constructs. (line  666)
10257* while:                                 Looping Constructs. (line  676)
10258
10259D.3 Parameter and Variable Index
10260================================
10261
10262* Menu:
10263
10264* !:                                     Special Parameters. (line 1333)
10265* #:                                     Special Parameters. (line 1316)
10266* $:                                     Special Parameters. (line 1328)
10267* $!:                                    Special Parameters. (line 1334)
10268* $#:                                    Special Parameters. (line 1317)
10269* $$:                                    Special Parameters. (line 1329)
10270* $*:                                    Special Parameters. (line 1293)
10271* $-:                                    Special Parameters. (line 1324)
10272* $0:                                    Special Parameters. (line 1339)
10273* $?:                                    Special Parameters. (line 1320)
10274* $@:                                    Special Parameters. (line 1306)
10275* $_:                                    Special Parameters. (line 1348)
10276* *:                                     Special Parameters. (line 1292)
10277* -:                                     Special Parameters. (line 1323)
10278* 0:                                     Special Parameters. (line 1338)
10279* ?:                                     Special Parameters. (line 1319)
10280* @:                                     Special Parameters. (line 1305)
10281* _:                                     Special Parameters. (line 1347)
10282* auto_resume:                           Job Control Variables.
10283                                                             (line 6531)
10284* BASH:                                  Bash Variables.     (line 4503)
10285* BASHOPTS:                              Bash Variables.     (line 4506)
10286* BASHPID:                               Bash Variables.     (line 4515)
10287* BASH_ALIASES:                          Bash Variables.     (line 4520)
10288* BASH_ARGC:                             Bash Variables.     (line 4529)
10289* BASH_ARGV:                             Bash Variables.     (line 4539)
10290* BASH_CMDS:                             Bash Variables.     (line 4549)
10291* BASH_COMMAND:                          Bash Variables.     (line 4558)
10292* BASH_COMPAT:                           Bash Variables.     (line 4563)
10293* BASH_ENV:                              Bash Variables.     (line 4578)
10294* BASH_EXECUTION_STRING:                 Bash Variables.     (line 4584)
10295* BASH_LINENO:                           Bash Variables.     (line 4587)
10296* BASH_LOADABLES_PATH:                   Bash Variables.     (line 4595)
10297* BASH_REMATCH:                          Bash Variables.     (line 4599)
10298* BASH_SOURCE:                           Bash Variables.     (line 4607)
10299* BASH_SUBSHELL:                         Bash Variables.     (line 4614)
10300* BASH_VERSINFO:                         Bash Variables.     (line 4619)
10301* BASH_VERSION:                          Bash Variables.     (line 4642)
10302* BASH_XTRACEFD:                         Bash Variables.     (line 4645)
10303* bell-style:                            Readline Init File Syntax.
10304                                                             (line 6832)
10305* bind-tty-special-chars:                Readline Init File Syntax.
10306                                                             (line 6839)
10307* blink-matching-paren:                  Readline Init File Syntax.
10308                                                             (line 6844)
10309* CDPATH:                                Bourne Shell Variables.
10310                                                             (line 4446)
10311* CHILD_MAX:                             Bash Variables.     (line 4656)
10312* colored-completion-prefix:             Readline Init File Syntax.
10313                                                             (line 6849)
10314* colored-stats:                         Readline Init File Syntax.
10315                                                             (line 6856)
10316* COLUMNS:                               Bash Variables.     (line 4663)
10317* comment-begin:                         Readline Init File Syntax.
10318                                                             (line 6862)
10319* completion-display-width:              Readline Init File Syntax.
10320                                                             (line 6867)
10321* completion-ignore-case:                Readline Init File Syntax.
10322                                                             (line 6874)
10323* completion-map-case:                   Readline Init File Syntax.
10324                                                             (line 6879)
10325* completion-prefix-display-length:      Readline Init File Syntax.
10326                                                             (line 6885)
10327* completion-query-items:                Readline Init File Syntax.
10328                                                             (line 6892)
10329* COMPREPLY:                             Bash Variables.     (line 4715)
10330* COMP_CWORD:                            Bash Variables.     (line 4669)
10331* COMP_KEY:                              Bash Variables.     (line 4698)
10332* COMP_LINE:                             Bash Variables.     (line 4675)
10333* COMP_POINT:                            Bash Variables.     (line 4680)
10334* COMP_TYPE:                             Bash Variables.     (line 4688)
10335* COMP_WORDBREAKS:                       Bash Variables.     (line 4702)
10336* COMP_WORDS:                            Bash Variables.     (line 4708)
10337* convert-meta:                          Readline Init File Syntax.
10338                                                             (line 6902)
10339* COPROC:                                Bash Variables.     (line 4721)
10340* DIRSTACK:                              Bash Variables.     (line 4725)
10341* disable-completion:                    Readline Init File Syntax.
10342                                                             (line 6910)
10343* echo-control-characters:               Readline Init File Syntax.
10344                                                             (line 6915)
10345* editing-mode:                          Readline Init File Syntax.
10346                                                             (line 6920)
10347* EMACS:                                 Bash Variables.     (line 4735)
10348* emacs-mode-string:                     Readline Init File Syntax.
10349                                                             (line 6926)
10350* enable-bracketed-paste:                Readline Init File Syntax.
10351                                                             (line 6936)
10352* enable-keypad:                         Readline Init File Syntax.
10353                                                             (line 6944)
10354* ENV:                                   Bash Variables.     (line 4740)
10355* EUID:                                  Bash Variables.     (line 4744)
10356* EXECIGNORE:                            Bash Variables.     (line 4748)
10357* expand-tilde:                          Readline Init File Syntax.
10358                                                             (line 6955)
10359* FCEDIT:                                Bash Variables.     (line 4761)
10360* FIGNORE:                               Bash Variables.     (line 4765)
10361* FUNCNAME:                              Bash Variables.     (line 4771)
10362* FUNCNEST:                              Bash Variables.     (line 4788)
10363* GLOBIGNORE:                            Bash Variables.     (line 4793)
10364* GROUPS:                                Bash Variables.     (line 4800)
10365* histchars:                             Bash Variables.     (line 4806)
10366* HISTCMD:                               Bash Variables.     (line 4821)
10367* HISTCONTROL:                           Bash Variables.     (line 4826)
10368* HISTFILE:                              Bash Variables.     (line 4842)
10369* HISTFILESIZE:                          Bash Variables.     (line 4846)
10370* HISTIGNORE:                            Bash Variables.     (line 4857)
10371* history-preserve-point:                Readline Init File Syntax.
10372                                                             (line 6959)
10373* history-size:                          Readline Init File Syntax.
10374                                                             (line 6965)
10375* HISTSIZE:                              Bash Variables.     (line 4877)
10376* HISTTIMEFORMAT:                        Bash Variables.     (line 4884)
10377* HOME:                                  Bourne Shell Variables.
10378                                                             (line 4450)
10379* horizontal-scroll-mode:                Readline Init File Syntax.
10380                                                             (line 6974)
10381* HOSTFILE:                              Bash Variables.     (line 4892)
10382* HOSTNAME:                              Bash Variables.     (line 4903)
10383* HOSTTYPE:                              Bash Variables.     (line 4906)
10384* IFS:                                   Bourne Shell Variables.
10385                                                             (line 4455)
10386* IGNOREEOF:                             Bash Variables.     (line 4909)
10387* input-meta:                            Readline Init File Syntax.
10388                                                             (line 6981)
10389* INPUTRC:                               Bash Variables.     (line 4919)
10390* isearch-terminators:                   Readline Init File Syntax.
10391                                                             (line 6989)
10392* keymap:                                Readline Init File Syntax.
10393                                                             (line 6996)
10394* LANG:                                  Bash Variables.     (line 4923)
10395* LC_ALL:                                Bash Variables.     (line 4927)
10396* LC_COLLATE:                            Bash Variables.     (line 4931)
10397* LC_CTYPE:                              Bash Variables.     (line 4938)
10398* LC_MESSAGES:                           Locale Translation. (line  500)
10399* LC_MESSAGES <1>:                       Bash Variables.     (line 4943)
10400* LC_NUMERIC:                            Bash Variables.     (line 4947)
10401* LC_TIME:                               Bash Variables.     (line 4951)
10402* LINENO:                                Bash Variables.     (line 4955)
10403* LINES:                                 Bash Variables.     (line 4959)
10404* MACHTYPE:                              Bash Variables.     (line 4965)
10405* MAIL:                                  Bourne Shell Variables.
10406                                                             (line 4459)
10407* MAILCHECK:                             Bash Variables.     (line 4969)
10408* MAILPATH:                              Bourne Shell Variables.
10409                                                             (line 4464)
10410* MAPFILE:                               Bash Variables.     (line 4977)
10411* mark-modified-lines:                   Readline Init File Syntax.
10412                                                             (line 7026)
10413* mark-symlinked-directories:            Readline Init File Syntax.
10414                                                             (line 7031)
10415* match-hidden-files:                    Readline Init File Syntax.
10416                                                             (line 7036)
10417* menu-complete-display-prefix:          Readline Init File Syntax.
10418                                                             (line 7043)
10419* meta-flag:                             Readline Init File Syntax.
10420                                                             (line 6981)
10421* OLDPWD:                                Bash Variables.     (line 4981)
10422* OPTARG:                                Bourne Shell Variables.
10423                                                             (line 4471)
10424* OPTERR:                                Bash Variables.     (line 4984)
10425* OPTIND:                                Bourne Shell Variables.
10426                                                             (line 4475)
10427* OSTYPE:                                Bash Variables.     (line 4988)
10428* output-meta:                           Readline Init File Syntax.
10429                                                             (line 7048)
10430* page-completions:                      Readline Init File Syntax.
10431                                                             (line 7054)
10432* PATH:                                  Bourne Shell Variables.
10433                                                             (line 4479)
10434* PIPESTATUS:                            Bash Variables.     (line 4991)
10435* POSIXLY_CORRECT:                       Bash Variables.     (line 4996)
10436* PPID:                                  Bash Variables.     (line 5005)
10437* PROMPT_COMMAND:                        Bash Variables.     (line 5009)
10438* PROMPT_DIRTRIM:                        Bash Variables.     (line 5013)
10439* PS0:                                   Bash Variables.     (line 5019)
10440* PS1:                                   Bourne Shell Variables.
10441                                                             (line 4485)
10442* PS2:                                   Bourne Shell Variables.
10443                                                             (line 4490)
10444* PS3:                                   Bash Variables.     (line 5024)
10445* PS4:                                   Bash Variables.     (line 5029)
10446* PWD:                                   Bash Variables.     (line 5035)
10447* RANDOM:                                Bash Variables.     (line 5038)
10448* READLINE_LINE:                         Bash Variables.     (line 5043)
10449* READLINE_POINT:                        Bash Variables.     (line 5047)
10450* REPLY:                                 Bash Variables.     (line 5051)
10451* revert-all-at-newline:                 Readline Init File Syntax.
10452                                                             (line 7064)
10453* SECONDS:                               Bash Variables.     (line 5054)
10454* SHELL:                                 Bash Variables.     (line 5060)
10455* SHELLOPTS:                             Bash Variables.     (line 5065)
10456* SHLVL:                                 Bash Variables.     (line 5074)
10457* show-all-if-ambiguous:                 Readline Init File Syntax.
10458                                                             (line 7070)
10459* show-all-if-unmodified:                Readline Init File Syntax.
10460                                                             (line 7076)
10461* show-mode-in-prompt:                   Readline Init File Syntax.
10462                                                             (line 7085)
10463* skip-completed-text:                   Readline Init File Syntax.
10464                                                             (line 7091)
10465* TEXTDOMAIN:                            Locale Translation. (line  500)
10466* TEXTDOMAINDIR:                         Locale Translation. (line  500)
10467* TIMEFORMAT:                            Bash Variables.     (line 5079)
10468* TMOUT:                                 Bash Variables.     (line 5117)
10469* TMPDIR:                                Bash Variables.     (line 5129)
10470* UID:                                   Bash Variables.     (line 5133)
10471* vi-cmd-mode-string:                    Readline Init File Syntax.
10472                                                             (line 7104)
10473* vi-ins-mode-string:                    Readline Init File Syntax.
10474                                                             (line 7114)
10475* visible-stats:                         Readline Init File Syntax.
10476                                                             (line 7124)
10477
10478D.4 Function Index
10479==================
10480
10481* Menu:
10482
10483* abort (C-g):                           Miscellaneous Commands.
10484                                                             (line 7832)
10485* accept-line (Newline or Return):       Commands For History.
10486                                                             (line 7451)
10487* alias-expand-line ():                  Miscellaneous Commands.
10488                                                             (line 7946)
10489* backward-char (C-b):                   Commands For Moving.
10490                                                             (line 7422)
10491* backward-delete-char (Rubout):         Commands For Text.  (line 7551)
10492* backward-kill-line (C-x Rubout):       Commands For Killing.
10493                                                             (line 7619)
10494* backward-kill-word (M-<DEL>):          Commands For Killing.
10495                                                             (line 7634)
10496* backward-word (M-b):                   Commands For Moving.
10497                                                             (line 7429)
10498* beginning-of-history (M-<):            Commands For History.
10499                                                             (line 7465)
10500* beginning-of-line (C-a):               Commands For Moving.
10501                                                             (line 7413)
10502* bracketed-paste-begin ():              Commands For Text.  (line 7567)
10503* call-last-kbd-macro (C-x e):           Keyboard Macros.    (line 7817)
10504* capitalize-word (M-c):                 Commands For Text.  (line 7595)
10505* character-search (C-]):                Miscellaneous Commands.
10506                                                             (line 7863)
10507* character-search-backward (M-C-]):     Miscellaneous Commands.
10508                                                             (line 7868)
10509* clear-screen (C-l):                    Commands For Moving.
10510                                                             (line 7441)
10511* complete (<TAB>):                      Commands For Completion.
10512                                                             (line 7708)
10513* complete-command (M-!):                Commands For Completion.
10514                                                             (line 7782)
10515* complete-filename (M-/):               Commands For Completion.
10516                                                             (line 7751)
10517* complete-hostname (M-@):               Commands For Completion.
10518                                                             (line 7774)
10519* complete-into-braces (M-{):            Commands For Completion.
10520                                                             (line 7802)
10521* complete-username (M-~):               Commands For Completion.
10522                                                             (line 7758)
10523* complete-variable (M-$):               Commands For Completion.
10524                                                             (line 7766)
10525* copy-backward-word ():                 Commands For Killing.
10526                                                             (line 7668)
10527* copy-forward-word ():                  Commands For Killing.
10528                                                             (line 7673)
10529* copy-region-as-kill ():                Commands For Killing.
10530                                                             (line 7664)
10531* dabbrev-expand ():                     Commands For Completion.
10532                                                             (line 7797)
10533* delete-char (C-d):                     Commands For Text.  (line 7546)
10534* delete-char-or-list ():                Commands For Completion.
10535                                                             (line 7745)
10536* delete-horizontal-space ():            Commands For Killing.
10537                                                             (line 7656)
10538* digit-argument (M-0, M-1, ... M--):    Numeric Arguments.  (line 7688)
10539* display-shell-version (C-x C-v):       Miscellaneous Commands.
10540                                                             (line 7931)
10541* do-uppercase-version (M-a, M-b, M-X, ...): Miscellaneous Commands.
10542                                                             (line 7836)
10543* downcase-word (M-l):                   Commands For Text.  (line 7591)
10544* dump-functions ():                     Miscellaneous Commands.
10545                                                             (line 7895)
10546* dump-macros ():                        Miscellaneous Commands.
10547                                                             (line 7907)
10548* dump-variables ():                     Miscellaneous Commands.
10549                                                             (line 7901)
10550* dynamic-complete-history (M-<TAB>):    Commands For Completion.
10551                                                             (line 7792)
10552* edit-and-execute-command (C-xC-e):     Miscellaneous Commands.
10553                                                             (line 7960)
10554* end-kbd-macro (C-x )):                 Keyboard Macros.    (line 7813)
10555* end-of-file (usually C-d):             Commands For Text.  (line 7540)
10556* end-of-history (M->):                  Commands For History.
10557                                                             (line 7468)
10558* end-of-line (C-e):                     Commands For Moving.
10559                                                             (line 7416)
10560* exchange-point-and-mark (C-x C-x):     Miscellaneous Commands.
10561                                                             (line 7858)
10562* forward-backward-delete-char ():       Commands For Text.  (line 7555)
10563* forward-char (C-f):                    Commands For Moving.
10564                                                             (line 7419)
10565* forward-search-history (C-s):          Commands For History.
10566                                                             (line 7476)
10567* forward-word (M-f):                    Commands For Moving.
10568                                                             (line 7425)
10569* glob-complete-word (M-g):              Miscellaneous Commands.
10570                                                             (line 7913)
10571* glob-expand-word (C-x *):              Miscellaneous Commands.
10572                                                             (line 7919)
10573* glob-list-expansions (C-x g):          Miscellaneous Commands.
10574                                                             (line 7925)
10575* history-and-alias-expand-line ():      Miscellaneous Commands.
10576                                                             (line 7949)
10577* history-expand-line (M-^):             Miscellaneous Commands.
10578                                                             (line 7939)
10579* history-search-backward ():            Commands For History.
10580                                                             (line 7498)
10581* history-search-forward ():             Commands For History.
10582                                                             (line 7492)
10583* history-substr-search-backward ():     Commands For History.
10584                                                             (line 7510)
10585* history-substr-search-forward ():      Commands For History.
10586                                                             (line 7504)
10587* insert-comment (M-#):                  Miscellaneous Commands.
10588                                                             (line 7882)
10589* insert-completions (M-*):              Commands For Completion.
10590                                                             (line 7724)
10591* insert-last-argument (M-. or M-_):     Miscellaneous Commands.
10592                                                             (line 7952)
10593* kill-line (C-k):                       Commands For Killing.
10594                                                             (line 7616)
10595* kill-region ():                        Commands For Killing.
10596                                                             (line 7660)
10597* kill-whole-line ():                    Commands For Killing.
10598                                                             (line 7625)
10599* kill-word (M-d):                       Commands For Killing.
10600                                                             (line 7629)
10601* magic-space ():                        Miscellaneous Commands.
10602                                                             (line 7942)
10603* menu-complete ():                      Commands For Completion.
10604                                                             (line 7728)
10605* menu-complete-backward ():             Commands For Completion.
10606                                                             (line 7740)
10607* next-history (C-n):                    Commands For History.
10608                                                             (line 7462)
10609* non-incremental-forward-search-history (M-n): Commands For History.
10610                                                             (line 7486)
10611* non-incremental-reverse-search-history (M-p): Commands For History.
10612                                                             (line 7480)
10613* operate-and-get-next (C-o):            Miscellaneous Commands.
10614                                                             (line 7955)
10615* overwrite-mode ():                     Commands For Text.  (line 7599)
10616* possible-command-completions (C-x !):  Commands For Completion.
10617                                                             (line 7788)
10618* possible-completions (M-?):            Commands For Completion.
10619                                                             (line 7717)
10620* possible-filename-completions (C-x /): Commands For Completion.
10621                                                             (line 7754)
10622* possible-hostname-completions (C-x @): Commands For Completion.
10623                                                             (line 7778)
10624* possible-username-completions (C-x ~): Commands For Completion.
10625                                                             (line 7762)
10626* possible-variable-completions (C-x $): Commands For Completion.
10627                                                             (line 7770)
10628* prefix-meta (<ESC>):                   Miscellaneous Commands.
10629                                                             (line 7840)
10630* previous-history (C-p):                Commands For History.
10631                                                             (line 7458)
10632* print-last-kbd-macro ():               Keyboard Macros.    (line 7821)
10633* quoted-insert (C-q or C-v):            Commands For Text.  (line 7560)
10634* re-read-init-file (C-x C-r):           Miscellaneous Commands.
10635                                                             (line 7828)
10636* redraw-current-line ():                Commands For Moving.
10637                                                             (line 7445)
10638* reverse-search-history (C-r):          Commands For History.
10639                                                             (line 7472)
10640* revert-line (M-r):                     Miscellaneous Commands.
10641                                                             (line 7847)
10642* self-insert (a, b, A, 1, !, ...):      Commands For Text.  (line 7564)
10643* set-mark (C-@):                        Miscellaneous Commands.
10644                                                             (line 7854)
10645* shell-backward-kill-word ():           Commands For Killing.
10646                                                             (line 7643)
10647* shell-backward-word ():                Commands For Moving.
10648                                                             (line 7437)
10649* shell-expand-line (M-C-e):             Miscellaneous Commands.
10650                                                             (line 7934)
10651* shell-forward-word ():                 Commands For Moving.
10652                                                             (line 7433)
10653* shell-kill-word ():                    Commands For Killing.
10654                                                             (line 7638)
10655* skip-csi-sequence ():                  Miscellaneous Commands.
10656                                                             (line 7873)
10657* start-kbd-macro (C-x ():               Keyboard Macros.    (line 7810)
10658* tilde-expand (M-&):                    Miscellaneous Commands.
10659                                                             (line 7851)
10660* transpose-chars (C-t):                 Commands For Text.  (line 7576)
10661* transpose-words (M-t):                 Commands For Text.  (line 7582)
10662* undo (C-_ or C-x C-u):                 Miscellaneous Commands.
10663                                                             (line 7844)
10664* universal-argument ():                 Numeric Arguments.  (line 7692)
10665* unix-filename-rubout ():               Commands For Killing.
10666                                                             (line 7651)
10667* unix-line-discard (C-u):               Commands For Killing.
10668                                                             (line 7622)
10669* unix-word-rubout (C-w):                Commands For Killing.
10670                                                             (line 7647)
10671* upcase-word (M-u):                     Commands For Text.  (line 7587)
10672* yank (C-y):                            Commands For Killing.
10673                                                             (line 7678)
10674* yank-last-arg (M-. or M-_):            Commands For History.
10675                                                             (line 7525)
10676* yank-nth-arg (M-C-y):                  Commands For History.
10677                                                             (line 7516)
10678* yank-pop (M-y):                        Commands For Killing.
10679                                                             (line 7681)
10680
10681D.5 Concept Index
10682=================
10683
10684* Menu:
10685
10686* alias expansion:                       Aliases.            (line 5747)
10687* arithmetic evaluation:                 Shell Arithmetic.   (line 5654)
10688* arithmetic expansion:                  Arithmetic Expansion.
10689                                                             (line 1864)
10690* arithmetic, shell:                     Shell Arithmetic.   (line 5654)
10691* arrays:                                Arrays.             (line 5795)
10692* background:                            Job Control Basics. (line 6340)
10693* Bash configuration:                    Basic Installation. (line 8823)
10694* Bash installation:                     Basic Installation. (line 8823)
10695* Bourne shell:                          Basic Shell Features.
10696                                                             (line  326)
10697* brace expansion:                       Brace Expansion.    (line 1396)
10698* builtin:                               Definitions.        (line  247)
10699* command editing:                       Readline Bare Essentials.
10700                                                             (line 6614)
10701* command execution:                     Command Search and Execution.
10702                                                             (line 2343)
10703* command expansion:                     Simple Command Expansion.
10704                                                             (line 2303)
10705* command history:                       Bash History Facilities.
10706                                                             (line 8481)
10707* command search:                        Command Search and Execution.
10708                                                             (line 2343)
10709* command substitution:                  Command Substitution.
10710                                                             (line 1835)
10711* command timing:                        Pipelines.          (line  550)
10712* commands, compound:                    Compound Commands.  (line  644)
10713* commands, conditional:                 Conditional Constructs.
10714                                                             (line  719)
10715* commands, grouping:                    Command Grouping.   (line  950)
10716* commands, lists:                       Lists.              (line  600)
10717* commands, looping:                     Looping Constructs. (line  660)
10718* commands, pipelines:                   Pipelines.          (line  547)
10719* commands, shell:                       Shell Commands.     (line  523)
10720* commands, simple:                      Simple Commands.    (line  534)
10721* comments, shell:                       Comments.           (line  511)
10722* completion builtins:                   Programmable Completion Builtins.
10723                                                             (line 8117)
10724* configuration:                         Basic Installation. (line 8823)
10725* control operator:                      Definitions.        (line  251)
10726* coprocess:                             Coprocesses.        (line  984)
10727* directory stack:                       The Directory Stack.
10728                                                             (line 5894)
10729* editing command lines:                 Readline Bare Essentials.
10730                                                             (line 6614)
10731* environment:                           Environment.        (line 2458)
10732* evaluation, arithmetic:                Shell Arithmetic.   (line 5654)
10733* event designators:                     Event Designators.  (line 8671)
10734* execution environment:                 Command Execution Environment.
10735                                                             (line 2387)
10736* exit status:                           Definitions.        (line  256)
10737* exit status <1>:                       Exit Status.        (line 2491)
10738* expansion:                             Shell Expansions.   (line 1359)
10739* expansion, arithmetic:                 Arithmetic Expansion.
10740                                                             (line 1864)
10741* expansion, brace:                      Brace Expansion.    (line 1396)
10742* expansion, filename:                   Filename Expansion. (line 1942)
10743* expansion, parameter:                  Shell Parameter Expansion.
10744                                                             (line 1509)
10745* expansion, pathname:                   Filename Expansion. (line 1942)
10746* expansion, tilde:                      Tilde Expansion.    (line 1449)
10747* expressions, arithmetic:               Shell Arithmetic.   (line 5654)
10748* expressions, conditional:              Bash Conditional Expressions.
10749                                                             (line 5513)
10750* field:                                 Definitions.        (line  260)
10751* filename:                              Definitions.        (line  265)
10752* filename expansion:                    Filename Expansion. (line 1942)
10753* foreground:                            Job Control Basics. (line 6340)
10754* functions, shell:                      Shell Functions.    (line 1103)
10755* history builtins:                      Bash History Builtins.
10756                                                             (line 8531)
10757* history events:                        Event Designators.  (line 8673)
10758* history expansion:                     History Interaction.
10759                                                             (line 8623)
10760* history list:                          Bash History Facilities.
10761                                                             (line 8481)
10762* History, how to use:                   A Programmable Completion Example.
10763                                                             (line 8470)
10764* identifier:                            Definitions.        (line  281)
10765* initialization file, readline:         Readline Init File. (line 6782)
10766* installation:                          Basic Installation. (line 8823)
10767* interaction, readline:                 Readline Interaction.
10768                                                             (line 6600)
10769* interactive shell:                     Invoking Bash.      (line 5267)
10770* interactive shell <1>:                 Interactive Shells. (line 5396)
10771* internationalization:                  Locale Translation. (line  495)
10772* job:                                   Definitions.        (line  268)
10773* job control:                           Definitions.        (line  272)
10774* job control <1>:                       Job Control Basics. (line 6340)
10775* kill ring:                             Readline Killing Commands.
10776                                                             (line 6689)
10777* killing text:                          Readline Killing Commands.
10778                                                             (line 6677)
10779* localization:                          Locale Translation. (line  495)
10780* login shell:                           Invoking Bash.      (line 5264)
10781* matching, pattern:                     Pattern Matching.   (line 1980)
10782* metacharacter:                         Definitions.        (line  276)
10783* name:                                  Definitions.        (line  281)
10784* native languages:                      Locale Translation. (line  495)
10785* notation, readline:                    Readline Bare Essentials.
10786                                                             (line 6614)
10787* operator, shell:                       Definitions.        (line  287)
10788* parameter expansion:                   Shell Parameter Expansion.
10789                                                             (line 1509)
10790* parameters:                            Shell Parameters.   (line 1201)
10791* parameters, positional:                Positional Parameters.
10792                                                             (line 1273)
10793* parameters, special:                   Special Parameters. (line 1289)
10794* pathname expansion:                    Filename Expansion. (line 1942)
10795* pattern matching:                      Pattern Matching.   (line 1980)
10796* pipeline:                              Pipelines.          (line  547)
10797* POSIX:                                 Definitions.        (line  239)
10798* POSIX Mode:                            Bash POSIX Mode.    (line 6099)
10799* process group:                         Definitions.        (line  292)
10800* process group ID:                      Definitions.        (line  296)
10801* process substitution:                  Process Substitution.
10802                                                             (line 1885)
10803* programmable completion:               Programmable Completion.
10804                                                             (line 7985)
10805* prompting:                             Controlling the Prompt.
10806                                                             (line 5981)
10807* quoting:                               Quoting.            (line  388)
10808* quoting, ANSI:                         ANSI-C Quoting.     (line  444)
10809* Readline, how to use:                  Job Control Variables.
10810                                                             (line 6548)
10811* redirection:                           Redirections.       (line 2066)
10812* reserved word:                         Definitions.        (line  300)
10813* restricted shell:                      The Restricted Shell.
10814                                                             (line 6062)
10815* return status:                         Definitions.        (line  305)
10816* shell arithmetic:                      Shell Arithmetic.   (line 5654)
10817* shell function:                        Shell Functions.    (line 1103)
10818* shell script:                          Shell Scripts.      (line 2562)
10819* shell variable:                        Shell Parameters.   (line 1201)
10820* shell, interactive:                    Interactive Shells. (line 5396)
10821* signal:                                Definitions.        (line  308)
10822* signal handling:                       Signals.            (line 2525)
10823* special builtin:                       Definitions.        (line  312)
10824* special builtin <1>:                   Special Builtins.   (line 4411)
10825* startup files:                         Bash Startup Files. (line 5285)
10826* suspending jobs:                       Job Control Basics. (line 6340)
10827* tilde expansion:                       Tilde Expansion.    (line 1449)
10828* token:                                 Definitions.        (line  316)
10829* translation, native languages:         Locale Translation. (line  495)
10830* variable, shell:                       Shell Parameters.   (line 1201)
10831* variables, readline:                   Readline Init File Syntax.
10832                                                             (line 6831)
10833* word:                                  Definitions.        (line  320)
10834* word splitting:                        Word Splitting.     (line 1908)
10835* yanking text:                          Readline Killing Commands.
10836                                                             (line 6677)