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