]> git.ipfire.org Git - thirdparty/bash.git/blob - doc/bash.1
55c562208ab98d9f5a36bbd095f8a6dea6376577
[thirdparty/bash.git] / doc / bash.1
1 .\"
2 .\" MAN PAGE COMMENTS to
3 .\"
4 .\" Chet Ramey
5 .\" Case Western Reserve University
6 .\" chet.ramey@case.edu
7 .\"
8 .\" Last Change: Mon Sep 19 11:13:21 EDT 2022
9 .\"
10 .\" bash_builtins, strip all but Built-Ins section
11 .if \n(zZ=1 .ig zZ
12 .if \n(zY=1 .ig zY
13 .TH BASH 1 "2022 September 19" "GNU Bash 5.2"
14 .\"
15 .\" There's some problem with having a `@'
16 .\" in a tagged paragraph with the BSD man macros.
17 .\" It has to do with `@' appearing in the }1 macro.
18 .\" This is a problem on 4.3 BSD and Ultrix, but Sun
19 .\" appears to have fixed it.
20 .\" If you're seeing the characters
21 .\" `@u-3p' appearing before the lines reading
22 .\" `possible-hostname-completions
23 .\" and `complete-hostname' down in READLINE,
24 .\" then uncomment this redefinition.
25 .\"
26 .\" .de }1
27 .\" .ds ]X \&\\*(]B\\
28 .\" .nr )E 0
29 .\" .if !"\\$1"" .nr )I \\$1n
30 .\" .}f
31 .\" .ll \\n(LLu
32 .\" .in \\n()Ru+\\n(INu+\\n()Iu
33 .\" .ti \\n(INu
34 .\" .ie !\\n()Iu+\\n()Ru-\w\a\\*(]X\au-3p \{\\*(]X
35 .\" .br\}
36 .\" .el \\*(]X\h\a|\\n()Iu+\\n()Ru\a\c
37 .\" .}f
38 .\" ..
39 .\"
40 .\" File Name macro. This used to be `.PN', for Path Name,
41 .\" but Sun doesn't seem to like that very much.
42 .\"
43 .de FN
44 \fI\|\\$1\|\fP
45 ..
46 .SH NAME
47 bash \- GNU Bourne-Again SHell
48 .SH SYNOPSIS
49 .B bash
50 [options]
51 [command_string | file]
52 .SH COPYRIGHT
53 .if n Bash is Copyright (C) 1989-2022 by the Free Software Foundation, Inc.
54 .if t Bash is Copyright \(co 1989-2022 by the Free Software Foundation, Inc.
55 .SH DESCRIPTION
56 .B Bash
57 is an \fBsh\fR-compatible command language interpreter that
58 executes commands read from the standard input or from a file.
59 .B Bash
60 also incorporates useful features from the \fIKorn\fP and \fIC\fP
61 shells (\fBksh\fP and \fBcsh\fP).
62 .PP
63 .B Bash
64 is intended to be a conformant implementation of the
65 Shell and Utilities portion of the IEEE POSIX specification
66 (IEEE Standard 1003.1).
67 .B Bash
68 can be configured to be POSIX-conformant by default.
69 .SH OPTIONS
70 All of the single-character shell options documented in the
71 description of the \fBset\fR builtin command, including \fB\-o\fP,
72 can be used as options when the shell is invoked.
73 In addition, \fBbash\fR
74 interprets the following options when it is invoked:
75 .PP
76 .PD 0
77 .TP 10
78 .B \-c
79 If the
80 .B \-c
81 option is present, then commands are read from the first non-option argument
82 .IR command_string .
83 If there are arguments after the
84 .IR command_string ,
85 the first argument is assigned to
86 .B $0
87 and any remaining arguments are assigned to the positional parameters.
88 The assignment to
89 .B $0
90 sets the name of the shell, which is used in warning and error messages.
91 .TP
92 .B \-i
93 If the
94 .B \-i
95 option is present, the shell is
96 .IR interactive .
97 .TP
98 .B \-l
99 Make
100 .B bash
101 act as if it had been invoked as a login shell (see
102 .SM
103 .B INVOCATION
104 below).
105 .TP
106 .B \-r
107 If the
108 .B \-r
109 option is present, the shell becomes
110 .I restricted
111 (see
112 .SM
113 .B "RESTRICTED SHELL"
114 below).
115 .TP
116 .B \-s
117 If the
118 .B \-s
119 option is present, or if no arguments remain after option
120 processing, then commands are read from the standard input.
121 This option allows the positional parameters to be set
122 when invoking an interactive shell or when reading input
123 through a pipe.
124 .TP
125 .B \-D
126 A list of all double-quoted strings preceded by \fB$\fP
127 is printed on the standard output.
128 These are the strings that
129 are subject to language translation when the current locale
130 is not \fBC\fP or \fBPOSIX\fP.
131 This implies the \fB\-n\fP option; no commands will be executed.
132 .TP
133 .B [\-+]O [\fIshopt_option\fP]
134 \fIshopt_option\fP is one of the shell options accepted by the
135 \fBshopt\fP builtin (see
136 .SM
137 .B SHELL BUILTIN COMMANDS
138 below).
139 If \fIshopt_option\fP is present, \fB\-O\fP sets the value of that option;
140 \fB+O\fP unsets it.
141 If \fIshopt_option\fP is not supplied, the names and values of the shell
142 options accepted by \fBshopt\fP are printed on the standard output.
143 If the invocation option is \fB+O\fP, the output is displayed in a format
144 that may be reused as input.
145 .TP
146 .B \-\-
147 A
148 .B \-\-
149 signals the end of options and disables further option processing.
150 Any arguments after the
151 .B \-\-
152 are treated as filenames and arguments. An argument of
153 .B \-
154 is equivalent to \fB\-\-\fP.
155 .PD
156 .PP
157 .B Bash
158 also interprets a number of multi-character options.
159 These options must appear on the command line before the
160 single-character options to be recognized.
161 .PP
162 .PD 0
163 .TP
164 .B \-\-debugger
165 Arrange for the debugger profile to be executed before the shell
166 starts.
167 Turns on extended debugging mode (see the description of the
168 .B extdebug
169 option to the
170 .B shopt
171 builtin below).
172 .TP
173 .B \-\-dump\-po\-strings
174 Equivalent to \fB\-D\fP, but the output is in the GNU \fIgettext\fP
175 \fBpo\fP (portable object) file format.
176 .TP
177 .B \-\-dump\-strings
178 Equivalent to \fB\-D\fP.
179 .TP
180 .B \-\-help
181 Display a usage message on standard output and exit successfully.
182 .TP
183 \fB\-\-init\-file\fP \fIfile\fP
184 .PD 0
185 .TP
186 \fB\-\-rcfile\fP \fIfile\fP
187 .PD
188 Execute commands from
189 .I file
190 instead of the standard personal initialization file
191 .I ~/.bashrc
192 if the shell is interactive (see
193 .SM
194 .B INVOCATION
195 below).
196 .TP
197 .B \-\-login
198 Equivalent to \fB\-l\fP.
199 .TP
200 .B \-\-noediting
201 Do not use the GNU
202 .B readline
203 library to read command lines when the shell is interactive.
204 .TP
205 .B \-\-noprofile
206 Do not read either the system-wide startup file
207 .FN /etc/profile
208 or any of the personal initialization files
209 .IR ~/.bash_profile ,
210 .IR ~/.bash_login ,
211 or
212 .IR ~/.profile .
213 By default,
214 .B bash
215 reads these files when it is invoked as a login shell (see
216 .SM
217 .B INVOCATION
218 below).
219 .TP
220 .B \-\-norc
221 Do not read and execute the personal initialization file
222 .I ~/.bashrc
223 if the shell is interactive.
224 This option is on by default if the shell is invoked as
225 .BR sh .
226 .TP
227 .B \-\-posix
228 Change the behavior of \fBbash\fP where the default operation differs
229 from the POSIX standard to match the standard (\fIposix mode\fP).
230 See
231 .SM
232 .B "SEE ALSO"
233 below for a reference to a document that details how posix mode affects
234 bash's behavior.
235 .TP
236 .B \-\-restricted
237 The shell becomes restricted (see
238 .SM
239 .B "RESTRICTED SHELL"
240 below).
241 .TP
242 .B \-\-verbose
243 Equivalent to \fB\-v\fP.
244 .TP
245 .B \-\-version
246 Show version information for this instance of
247 .B bash
248 on the standard output and exit successfully.
249 .PD
250 .SH ARGUMENTS
251 If arguments remain after option processing, and neither the
252 .B \-c
253 nor the
254 .B \-s
255 option has been supplied, the first argument is assumed to
256 be the name of a file containing shell commands.
257 If
258 .B bash
259 is invoked in this fashion,
260 .B $0
261 is set to the name of the file, and the positional parameters
262 are set to the remaining arguments.
263 .B Bash
264 reads and executes commands from this file, then exits.
265 \fBBash\fP's exit status is the exit status of the last command
266 executed in the script.
267 If no commands are executed, the exit status is 0.
268 An attempt is first made to open the file in the current directory, and,
269 if no file is found, then the shell searches the directories in
270 .SM
271 .B PATH
272 for the script.
273 .SH INVOCATION
274 A \fIlogin shell\fP is one whose first character of argument zero is a
275 .BR \- ,
276 or one started with the
277 .B \-\-login
278 option.
279 .PP
280 An \fIinteractive\fP shell is one started without non-option arguments
281 (unless \fB\-s\fP is specified)
282 and without the
283 .B \-c
284 option,
285 whose standard input and error are
286 both connected to terminals (as determined by
287 .IR isatty (3)),
288 or one started with the
289 .B \-i
290 option.
291 .SM
292 .B PS1
293 is set and
294 .B $\-
295 includes
296 .B i
297 if
298 .B bash
299 is interactive,
300 allowing a shell script or a startup file to test this state.
301 .PP
302 The following paragraphs describe how
303 .B bash
304 executes its startup files.
305 If any of the files exist but cannot be read,
306 .B bash
307 reports an error.
308 Tildes are expanded in filenames as described below under
309 .B "Tilde Expansion"
310 in the
311 .SM
312 .B EXPANSION
313 section.
314 .PP
315 When
316 .B bash
317 is invoked as an interactive login shell, or as a non-interactive shell
318 with the \fB\-\-login\fP option, it first reads and
319 executes commands from the file \fI/etc/profile\fP, if that
320 file exists.
321 After reading that file, it looks for \fI~/.bash_profile\fP,
322 \fI~/.bash_login\fP, and \fI~/.profile\fP, in that order, and reads
323 and executes commands from the first one that exists and is readable.
324 The
325 .B \-\-noprofile
326 option may be used when the shell is started to inhibit this behavior.
327 .PP
328 When an interactive login shell exits,
329 or a non-interactive login shell executes the \fBexit\fP builtin command,
330 .B bash
331 reads and executes commands from the file \fI~/.bash_logout\fP, if it
332 exists.
333 .PP
334 When an interactive shell that is not a login shell is started,
335 .B bash
336 reads and executes commands from \fI~/.bashrc\fP, if that file exists.
337 This may be inhibited by using the
338 .B \-\-norc
339 option.
340 The \fB\-\-rcfile\fP \fIfile\fP option will force
341 .B bash
342 to read and execute commands from \fIfile\fP instead of \fI~/.bashrc\fP.
343 .PP
344 When
345 .B bash
346 is started non-interactively, to run a shell script, for example, it
347 looks for the variable
348 .SM
349 .B BASH_ENV
350 in the environment, expands its value if it appears there, and uses the
351 expanded value as the name of a file to read and execute.
352 .B Bash
353 behaves as if the following command were executed:
354 .sp .5
355 .RS
356 .if t \f(CWif [ \-n "$BASH_ENV" ]; then . "$BASH_ENV"; fi\fP
357 .if n if [ \-n "$BASH_ENV" ]; then . "$BASH_ENV"; fi
358 .RE
359 .sp .5
360 but the value of the
361 .SM
362 .B PATH
363 variable is not used to search for the filename.
364 .PP
365 If
366 .B bash
367 is invoked with the name
368 .BR sh ,
369 it tries to mimic the startup behavior of historical versions of
370 .B sh
371 as closely as possible,
372 while conforming to the POSIX standard as well.
373 When invoked as an interactive login shell, or a non-interactive
374 shell with the \fB\-\-login\fP option, it first attempts to
375 read and execute commands from
376 .I /etc/profile
377 and
378 .IR ~/.profile ,
379 in that order.
380 The
381 .B \-\-noprofile
382 option may be used to inhibit this behavior.
383 When invoked as an interactive shell with the name
384 .BR sh ,
385 .B bash
386 looks for the variable
387 .SM
388 .BR ENV ,
389 expands its value if it is defined, and uses the
390 expanded value as the name of a file to read and execute.
391 Since a shell invoked as
392 .B sh
393 does not attempt to read and execute commands from any other startup
394 files, the
395 .B \-\-rcfile
396 option has no effect.
397 A non-interactive shell invoked with the name
398 .B sh
399 does not attempt to read any other startup files.
400 When invoked as
401 .BR sh ,
402 .B bash
403 enters
404 .I posix
405 mode after the startup files are read.
406 .PP
407 When
408 .B bash
409 is started in
410 .I posix
411 mode, as with the
412 .B \-\-posix
413 command line option, it follows the POSIX standard for startup files.
414 In this mode, interactive shells expand the
415 .SM
416 .B ENV
417 variable and commands are read and executed from the file
418 whose name is the expanded value.
419 No other startup files are read.
420 .PP
421 .B Bash
422 attempts to determine when it is being run with its standard input
423 connected to a network connection, as when executed by
424 the historical remote shell daemon, usually \fIrshd\fP,
425 or the secure shell daemon \fIsshd\fP.
426 If
427 .B bash
428 determines it is being run non-interactively in this fashion,
429 it reads and executes commands from \fI~/.bashrc\fP,
430 if that file exists and is readable.
431 It will not do this if invoked as \fBsh\fP.
432 The
433 .B \-\-norc
434 option may be used to inhibit this behavior, and the
435 .B \-\-rcfile
436 option may be used to force another file to be read, but neither
437 \fIrshd\fP nor \fIsshd\fP generally invoke the shell with those options
438 or allow them to be specified.
439 .PP
440 If the shell is started with the effective user (group) id not equal to the
441 real user (group) id, and the \fB\-p\fP option is not supplied, no startup
442 files are read, shell functions are not inherited from the environment, the
443 .SM
444 .BR SHELLOPTS ,
445 .SM
446 .BR BASHOPTS ,
447 .SM
448 .BR CDPATH ,
449 and
450 .SM
451 .B GLOBIGNORE
452 variables, if they appear in the environment, are ignored,
453 and the effective user id is set to the real user id.
454 If the \fB\-p\fP option is supplied at invocation, the startup behavior is
455 the same, but the effective user id is not reset.
456 .SH DEFINITIONS
457 The following definitions are used throughout the rest of this
458 document.
459 .PD 0
460 .TP
461 .B blank
462 A space or tab.
463 .TP
464 .B word
465 A sequence of characters considered as a single unit by the shell.
466 Also known as a
467 .BR token .
468 .TP
469 .B name
470 A
471 .I word
472 consisting only of alphanumeric characters and underscores, and
473 beginning with an alphabetic character or an underscore. Also
474 referred to as an
475 .BR identifier .
476 .TP
477 .B metacharacter
478 A character that, when unquoted, separates words. One of the following:
479 .br
480 .RS
481 .PP
482 .if t \fB| & ; ( ) < > space tab newline\fP
483 .if n \fB| & ; ( ) < > space tab newline\fP
484 .RE
485 .TP
486 .B control operator
487 A \fItoken\fP that performs a control function. It is one of the following
488 symbols:
489 .RS
490 .PP
491 .if t \fB|| & && ; ;; ;& ;;& ( ) | |& <newline>\fP
492 .if n \fB|| & && ; ;; ;& ;;& ( ) | |& <newline>\fP
493 .RE
494 .PD
495 .SH "RESERVED WORDS"
496 \fIReserved words\fP are words that have a special meaning to the shell.
497 The following words are recognized as reserved when unquoted and either
498 the first word of a command (see
499 .SM
500 .B SHELL GRAMMAR
501 below), the third word of a
502 .B case
503 or
504 .B select
505 command
506 (only \fBin\fP is valid), or the third word of a
507 .B for
508 command (only \fBin\fP and \fBdo\fP are valid):
509 .if t .RS
510 .PP
511 .B
512 .if n ! case coproc do done elif else esac fi for function if in select then until while { } time [[ ]]
513 .if t ! case coproc do done elif else esac fi for function if in select then until while { } time [[ ]]
514 .if t .RE
515 .SH "SHELL GRAMMAR"
516 This section describes the syntax of the various forms of shell commands.
517 .SS Simple Commands
518 A \fIsimple command\fP is a sequence of optional variable assignments
519 followed by \fBblank\fP-separated words and redirections, and
520 terminated by a \fIcontrol operator\fP. The first word
521 specifies the command to be executed, and is passed as argument zero.
522 The remaining words are passed as arguments to the invoked command.
523 .PP
524 The return value of a \fIsimple command\fP is its exit status, or
525 128+\fIn\^\fP if the command is terminated by signal
526 .IR n .
527 .SS Pipelines
528 A \fIpipeline\fP is a sequence of one or more commands separated by
529 one of the control operators
530 .B |
531 or \fB|&\fP.
532 The format for a pipeline is:
533 .RS
534 .PP
535 [\fBtime\fP [\fB\-p\fP]] [ ! ] \fIcommand1\fP [ [\fB|\fP\(bv\fB|&\fP] \fIcommand2\fP ... ]
536 .RE
537 .PP
538 The standard output of
539 .I command1
540 is connected via a pipe to the standard input of
541 .IR command2 .
542 This connection is performed before any redirections specified by the
543 .IR command1 (see
544 .SM
545 .B REDIRECTION
546 below).
547 If \fB|&\fP is used, \fIcommand1\fP's standard error, in addition to its
548 standard output, is connected to
549 \fIcommand2\fP's standard input through the pipe;
550 it is shorthand for \fB2>&1 |\fP.
551 This implicit redirection of the standard error to the standard output is
552 performed after any redirections specified by \fIcommand1\fP.
553 .PP
554 The return status of a pipeline is the exit status of the last
555 command, unless the \fBpipefail\fP option is enabled.
556 If \fBpipefail\fP is enabled, the pipeline's return status is the
557 value of the last (rightmost) command to exit with a non-zero status,
558 or zero if all commands exit successfully.
559 If the reserved word
560 .B !
561 precedes a pipeline, the exit status of that pipeline is the logical
562 negation of the exit status as described above.
563 The shell waits for all commands in the pipeline to
564 terminate before returning a value.
565 .PP
566 If the
567 .B time
568 reserved word precedes a pipeline, the elapsed as well as user and
569 system time consumed by its execution are reported when the pipeline
570 terminates.
571 The \fB\-p\fP option changes the output format to that specified by POSIX.
572 When the shell is in \fIposix mode\fP, it does not recognize
573 \fBtime\fP as a reserved word if the next token begins with a `-'.
574 The
575 .SM
576 .B TIMEFORMAT
577 variable may be set to a format string that specifies how the timing
578 information should be displayed; see the description of
579 .SM
580 .B TIMEFORMAT
581 under
582 .B "Shell Variables"
583 below.
584 .PP
585 When the shell is in \fIposix mode\fP, \fBtime\fP
586 may be followed by a newline. In this case, the shell displays the
587 total user and system time consumed by the shell and its children.
588 The
589 .SM
590 .B TIMEFORMAT
591 variable may be used to specify the format of
592 the time information.
593 .PP
594 Each command in a multi-command pipeline,
595 where pipes are created,
596 is executed in a \fIsubshell\fP, which is a
597 separate process.
598 See
599 .SM
600 \fBCOMMAND EXECUTION ENVIRONMENT\fP
601 for a description of subshells and a subshell environment.
602 If the \fBlastpipe\fP option is enabled using the \fBshopt\fP builtin
603 (see the description of \fBshopt\fP below),
604 the last element of a pipeline may be run by the shell process
605 when job control is not active.
606 .SS Lists
607 A \fIlist\fP is a sequence of one or more pipelines separated by one
608 of the operators
609 .BR ; ,
610 .BR & ,
611 .BR && ,
612 or
613 .BR || ,
614 and optionally terminated by one of
615 .BR ; ,
616 .BR & ,
617 or
618 .BR <newline> .
619 .PP
620 Of these list operators,
621 .B &&
622 and
623 .B ||
624 have equal precedence, followed by
625 .B ;
626 and
627 .BR & ,
628 which have equal precedence.
629 .PP
630 A sequence of one or more newlines may appear in a \fIlist\fP instead
631 of a semicolon to delimit commands.
632 .PP
633 If a command is terminated by the control operator
634 .BR & ,
635 the shell executes the command in the \fIbackground\fP
636 in a subshell.
637 The shell does not wait for the command to
638 finish, and the return status is 0.
639 These are referred to as \fIasynchronous\fP commands.
640 Commands separated by a
641 .B ;
642 are executed sequentially; the shell waits for each
643 command to terminate in turn. The return status is the
644 exit status of the last command executed.
645 .PP
646 AND and OR lists are sequences of one or more pipelines separated by the
647 \fB&&\fP and \fB||\fP control operators, respectively.
648 AND and OR lists are executed with left associativity.
649 An AND list has the form
650 .RS
651 .PP
652 \fIcommand1\fP \fB&&\fP \fIcommand2\fP
653 .RE
654 .PP
655 .I command2
656 is executed if, and only if,
657 .I command1
658 returns an exit status of zero (success).
659 .PP
660 An OR list has the form
661 .RS
662 .PP
663 \fIcommand1\fP \fB||\fP \fIcommand2\fP
664 .RE
665 .PP
666 .I command2
667 is executed if, and only if,
668 .I command1
669 returns a non-zero exit status.
670 The return status of
671 AND and OR lists is the exit status of the last command
672 executed in the list.
673 .SS Compound Commands
674 A \fIcompound command\fP is one of the following.
675 In most cases a \fIlist\fP in a command's description may be separated from
676 the rest of the command by one or more newlines, and may be followed by a
677 newline in place of a semicolon.
678 .TP
679 (\fIlist\fP)
680 \fIlist\fP is executed in a subshell (see
681 .SM
682 \fBCOMMAND EXECUTION ENVIRONMENT\fP
683 below for a description of a subshell environment).
684 Variable assignments and builtin
685 commands that affect the shell's environment do not remain in effect
686 after the command completes. The return status is the exit status of
687 \fIlist\fP.
688 .TP
689 { \fIlist\fP; }
690 \fIlist\fP is simply executed in the current shell environment.
691 \fIlist\fP must be terminated with a newline or semicolon.
692 This is known as a \fIgroup command\fP.
693 The return status is the exit status of
694 \fIlist\fP.
695 Note that unlike the metacharacters \fB(\fP and \fB)\fP, \fB{\fP and
696 \fB}\fP are \fIreserved words\fP and must occur where a reserved
697 word is permitted to be recognized. Since they do not cause a word
698 break, they must be separated from \fIlist\fP by whitespace or another
699 shell metacharacter.
700 .TP
701 ((\fIexpression\fP))
702 The \fIexpression\fP is evaluated according to the rules described
703 below under
704 .SM
705 .BR "ARITHMETIC EVALUATION" .
706 If the value of the expression is non-zero, the return status is 0;
707 otherwise the return status is 1.
708 The \fIexpression\fP
709 undergoes the same expansions
710 as if it were within double quotes,
711 but double quote characters in \fIexpression\fP are not treated specially
712 and are removed.
713 .TP
714 \fB[[\fP \fIexpression\fP \fB]]\fP
715 Return a status of 0 or 1 depending on the evaluation of
716 the conditional expression \fIexpression\fP.
717 Expressions are composed of the primaries described below under
718 .SM
719 .BR "CONDITIONAL EXPRESSIONS" .
720 The words between the \fB[[\fP and \fB]]\fP do not undergo word splitting
721 and pathname expansion.
722 The shell performs tilde expansion, parameter and
723 variable expansion, arithmetic expansion, command substitution, process
724 substitution, and quote removal on those words
725 (the expansions that would occur if the words were enclosed in double quotes).
726 Conditional operators such as \fB\-f\fP must be unquoted to be recognized
727 as primaries.
728 .if t .sp 0.5
729 .if n .sp 1
730 When used with \fB[[\fP, the \fB<\fP and \fB>\fP operators sort
731 lexicographically using the current locale.
732 .if t .sp 0.5
733 .if n .sp 1
734 When the \fB==\fP and \fB!=\fP operators are used, the string to the
735 right of the operator is considered a pattern and matched according
736 to the rules described below under \fBPattern Matching\fP,
737 as if the \fBextglob\fP shell option were enabled.
738 The \fB=\fP operator is equivalent to \fB==\fP.
739 If the
740 .B nocasematch
741 shell option is enabled, the match is performed without regard to the case
742 of alphabetic characters.
743 The return value is 0 if the string matches (\fB==\fP) or does not match
744 (\fB!=\fP) the pattern, and 1 otherwise.
745 Any part of the pattern may be quoted to force the quoted portion
746 to be matched as a string.
747 .if t .sp 0.5
748 .if n .sp 1
749 An additional binary operator, \fB=~\fP, is available, with the same
750 precedence as \fB==\fP and \fB!=\fP.
751 When it is used, the string to the right of the operator is considered
752 a POSIX extended regular expression and matched accordingly
753 (using the POSIX \fIregcomp\fP and \fIregexec\fP interfaces
754 usually described in \fIregex\fP(3)).
755 The return value is 0 if the string matches
756 the pattern, and 1 otherwise.
757 If the regular expression is syntactically incorrect, the conditional
758 expression's return value is 2.
759 If the
760 .B nocasematch
761 shell option is enabled, the match is performed without regard to the case
762 of alphabetic characters.
763 If any part of the pattern is quoted, the quoted portion is matched literally.
764 This means every character in the quoted portion matches itself,
765 instead of having any special pattern matching meaning.
766 If the pattern is stored in a shell variable, quoting the variable
767 expansion forces the entire pattern to be matched literally.
768 Treat bracket expressions in regular expressions carefully,
769 since normal quoting and pattern characters lose their meanings
770 between brackets.
771 .if t .sp 0.5
772 .if n .sp 1
773 The pattern will match if it matches any part of the string.
774 Anchor the pattern using the \fB^\fP and \fB$\fP regular expression
775 operators to force it to match the entire string.
776 The array variable
777 .SM
778 .B BASH_REMATCH
779 records which parts of the string matched the pattern.
780 The element of
781 .SM
782 .B BASH_REMATCH
783 with index 0 contains the portion of
784 the string matching the entire regular expression.
785 Substrings matched by parenthesized subexpressions within the regular
786 expression are saved in the remaining
787 .SM
788 .B BASH_REMATCH
789 indices. The element of
790 .SM
791 .B BASH_REMATCH
792 with index \fIn\fP is the portion of the
793 string matching the \fIn\fPth parenthesized subexpression.
794 Bash sets
795 .SM
796 .B BASH_REMATCH
797 in the global scope; declaring it as a local variable will lead to
798 unexpected results.
799 .if t .sp 0.5
800 .if n .sp 1
801 Expressions may be combined using the following operators, listed
802 in decreasing order of precedence:
803 .if t .sp 0.5
804 .if n .sp 1
805 .RS
806 .PD 0
807 .TP
808 .B ( \fIexpression\fP )
809 Returns the value of \fIexpression\fP.
810 This may be used to override the normal precedence of operators.
811 .TP
812 .B ! \fIexpression\fP
813 True if
814 .I expression
815 is false.
816 .TP
817 \fIexpression1\fP \fB&&\fP \fIexpression2\fP
818 True if both
819 .I expression1
820 and
821 .I expression2
822 are true.
823 .TP
824 \fIexpression1\fP \fB||\fP \fIexpression2\fP
825 True if either
826 .I expression1
827 or
828 .I expression2
829 is true.
830 .PD
831 .LP
832 The \fB&&\fP and \fB||\fP
833 operators do not evaluate \fIexpression2\fP if the value of
834 \fIexpression1\fP is sufficient to determine the return value of
835 the entire conditional expression.
836 .RE
837 .TP
838 \fBfor\fP \fIname\fP [ [ \fBin\fP [ \fIword ...\fP ] ] ; ] \fBdo\fP \fIlist\fP ; \fBdone\fP
839 The list of words following \fBin\fP is expanded, generating a list
840 of items.
841 The variable \fIname\fP is set to each element of this list
842 in turn, and \fIlist\fP is executed each time.
843 If the \fBin\fP \fIword\fP is omitted, the \fBfor\fP command executes
844 \fIlist\fP once for each positional parameter that is set (see
845 .SM
846 .B PARAMETERS
847 below).
848 The return status is the exit status of the last command that executes.
849 If the expansion of the items following \fBin\fP results in an empty
850 list, no commands are executed, and the return status is 0.
851 .TP
852 \fBfor\fP (( \fIexpr1\fP ; \fIexpr2\fP ; \fIexpr3\fP )) ; \fBdo\fP \fIlist\fP ; \fBdone\fP
853 First, the arithmetic expression \fIexpr1\fP is evaluated according
854 to the rules described below under
855 .SM
856 .BR "ARITHMETIC EVALUATION" .
857 The arithmetic expression \fIexpr2\fP is then evaluated repeatedly
858 until it evaluates to zero.
859 Each time \fIexpr2\fP evaluates to a non-zero value, \fIlist\fP is
860 executed and the arithmetic expression \fIexpr3\fP is evaluated.
861 If any expression is omitted, it behaves as if it evaluates to 1.
862 The return value is the exit status of the last command in \fIlist\fP
863 that is executed, or false if any of the expressions is invalid.
864 .TP
865 \fBselect\fP \fIname\fP [ \fBin\fP \fIword\fP ] ; \fBdo\fP \fIlist\fP ; \fBdone\fP
866 The list of words following \fBin\fP is expanded, generating a list
867 of items, and the set of expanded words is printed on the standard
868 error, each preceded by a number. If the \fBin\fP
869 \fIword\fP is omitted, the positional parameters are printed (see
870 .SM
871 .B PARAMETERS
872 below).
873 .B select
874 then displays the
875 .SM
876 .B PS3
877 prompt and reads a line from the standard input.
878 If the line consists of a number corresponding to one of
879 the displayed words, then the value of
880 .I name
881 is set to that word.
882 If the line is empty, the words and prompt are displayed again.
883 If EOF is read, the \fBselect\fP command completes and returns 1.
884 Any other value read causes
885 .I name
886 to be set to null. The line read is saved in the variable
887 .SM
888 .BR REPLY .
889 The
890 .I list
891 is executed after each selection until a
892 .B break
893 command is executed.
894 The exit status of
895 .B select
896 is the exit status of the last command executed in
897 .IR list ,
898 or zero if no commands were executed.
899 .TP
900 \fBcase\fP \fIword\fP \fBin\fP [ [(] \fIpattern\fP [ \fB|\fP \fIpattern\fP ] \
901 ... ) \fIlist\fP ;; ] ... \fBesac\fP
902 A \fBcase\fP command first expands \fIword\fP, and tries to match
903 it against each \fIpattern\fP in turn, using the matching rules
904 described under
905 .B Pattern Matching
906 below.
907 The \fIword\fP is expanded using tilde
908 expansion, parameter and variable expansion, arithmetic expansion,
909 command substitution, process substitution and quote removal.
910 Each \fIpattern\fP examined is expanded using tilde
911 expansion, parameter and variable expansion, arithmetic expansion,
912 command substitution, process substitution, and quote removal.
913 If the
914 .B nocasematch
915 shell option is enabled, the match is performed without regard to the case
916 of alphabetic characters.
917 When a match is found, the corresponding \fIlist\fP is executed.
918 If the \fB;;\fP operator is used, no subsequent matches are attempted after
919 the first pattern match.
920 Using \fB;&\fP in place of \fB;;\fP causes execution to continue with
921 the \fIlist\fP associated with the next set of patterns.
922 Using \fB;;&\fP in place of \fB;;\fP causes the shell to test the next
923 pattern list in the statement, if any, and execute any associated \fIlist\fP
924 on a successful match,
925 continuing the case statement execution as if the pattern list had not matched.
926 The exit status is zero if no
927 pattern matches. Otherwise, it is the exit status of the
928 last command executed in \fIlist\fP.
929 .TP
930 \fBif\fP \fIlist\fP; \fBthen\fP \fIlist\fP; \
931 [ \fBelif\fP \fIlist\fP; \fBthen\fP \fIlist\fP; ] ... \
932 [ \fBelse\fP \fIlist\fP; ] \fBfi\fP
933 The
934 .B if
935 .I list
936 is executed. If its exit status is zero, the
937 \fBthen\fP \fIlist\fP is executed. Otherwise, each \fBelif\fP
938 \fIlist\fP is executed in turn, and if its exit status is zero,
939 the corresponding \fBthen\fP \fIlist\fP is executed and the
940 command completes. Otherwise, the \fBelse\fP \fIlist\fP is
941 executed, if present. The exit status is the exit status of the
942 last command executed, or zero if no condition tested true.
943 .TP
944 \fBwhile\fP \fIlist-1\fP; \fBdo\fP \fIlist-2\fP; \fBdone\fP
945 .PD 0
946 .TP
947 \fBuntil\fP \fIlist-1\fP; \fBdo\fP \fIlist-2\fP; \fBdone\fP
948 .PD
949 The \fBwhile\fP command continuously executes the list
950 \fIlist-2\fP as long as the last command in the list \fIlist-1\fP returns
951 an exit status of zero. The \fBuntil\fP command is identical
952 to the \fBwhile\fP command, except that the test is negated:
953 .I list-2
954 is executed as long as the last command in
955 .I list-1
956 returns a non-zero exit status.
957 The exit status of the \fBwhile\fP and \fBuntil\fP commands
958 is the exit status
959 of the last command executed in \fIlist-2\fP, or zero if
960 none was executed.
961 .SS Coprocesses
962 A \fIcoprocess\fP is a shell command preceded by the \fBcoproc\fP reserved
963 word.
964 A coprocess is executed asynchronously in a subshell, as if the command
965 had been terminated with the \fB&\fP control operator, with a two-way pipe
966 established between the executing shell and the coprocess.
967 .PP
968 The syntax for a coprocess is:
969 .RS
970 .PP
971 \fBcoproc\fP [\fINAME\fP] \fIcommand\fP [\fIredirections\fP]
972 .RE
973 .PP
974 This creates a coprocess named \fINAME\fP.
975 \fIcommand\fP may be either a simple command or a compound
976 command (see above).
977 \fINAME\fP is a shell variable name.
978 If \fINAME\fP is not supplied, the default name is \fBCOPROC\fP.
979 .PP
980 The recommended form to use for a coprocess is
981 .RS
982 .PP
983 \fBcoproc\fP \fINAME\fP { \fIcommand\fP [\fIredirections\fP]; }
984 .RE
985 .PP
986 This form is recommended because simple commands result in the coprocess
987 always being named \fBCOPROC\fP, and it is simpler to use and more complete
988 than the other compound commands.
989 .PP
990 If \fIcommand\fP is a compound command, \fINAME\fP is optional. The
991 word following \fBcoproc\fP determines whether that word is interpreted
992 as a variable name: it is interpreted as \fINAME\fP if it is not a
993 reserved word that introduces a compound command.
994 If \fIcommand\fP is a simple command, \fINAME\fP is not allowed; this
995 is to avoid confusion between \fINAME\fP and the first word of the simple
996 command.
997 .PP
998 When the coprocess is executed, the shell creates an array variable (see
999 .B Arrays
1000 below) named \fINAME\fP in the context of the executing shell.
1001 The standard output of
1002 .I command
1003 is connected via a pipe to a file descriptor in the executing shell,
1004 and that file descriptor is assigned to \fINAME\fP[0].
1005 The standard input of
1006 .I command
1007 is connected via a pipe to a file descriptor in the executing shell,
1008 and that file descriptor is assigned to \fINAME\fP[1].
1009 This pipe is established before any redirections specified by the
1010 command (see
1011 .SM
1012 .B REDIRECTION
1013 below).
1014 The file descriptors can be utilized as arguments to shell commands
1015 and redirections using standard word expansions.
1016 Other than those created to execute command and process substitutions,
1017 the file descriptors are not available in subshells.
1018 .PP
1019 The process ID of the shell spawned to execute the coprocess is
1020 available as the value of the variable \fINAME\fP_PID.
1021 The \fBwait\fP
1022 builtin command may be used to wait for the coprocess to terminate.
1023 .PP
1024 Since the coprocess is created as an asynchronous command,
1025 the \fBcoproc\fP command always returns success.
1026 The return status of a coprocess is the exit status of \fIcommand\fP.
1027 .SS Shell Function Definitions
1028 A shell function is an object that is called like a simple command and
1029 executes a compound command with a new set of positional parameters.
1030 Shell functions are declared as follows:
1031 .TP
1032 \fIfname\fP () \fIcompound\-command\fP [\fIredirection\fP]
1033 .PD 0
1034 .TP
1035 \fBfunction\fP \fIfname\fP [()] \fIcompound\-command\fP [\fIredirection\fP]
1036 .PD
1037 This defines a function named \fIfname\fP.
1038 The reserved word \fBfunction\fP is optional.
1039 If the \fBfunction\fP reserved word is supplied, the parentheses are optional.
1040 The \fIbody\fP of the function is the compound command
1041 .I compound\-command
1042 (see \fBCompound Commands\fP above).
1043 That command is usually a \fIlist\fP of commands between { and }, but
1044 may be any command listed under \fBCompound Commands\fP above.
1045 If the \fBfunction\fP reserved word is used, but the
1046 parentheses are not supplied, the braces are recommended.
1047 \fIcompound\-command\fP is executed whenever \fIfname\fP is specified as the
1048 name of a simple command.
1049 When in \fIposix mode\fP, \fIfname\fP must be a valid shell \fIname\fP
1050 and may not be the name of one of the
1051 POSIX \fIspecial builtins\fP.
1052 In default mode, a function name can be any unquoted shell word that does
1053 not contain \fB$\fP.
1054 Any redirections (see
1055 .SM
1056 .B REDIRECTION
1057 below) specified when a function is defined are performed
1058 when the function is executed.
1059 The exit status of a function definition is zero unless a syntax error
1060 occurs or a readonly function with the same name already exists.
1061 When executed, the exit status of a function is the exit status of the
1062 last command executed in the body. (See
1063 .SM
1064 .B FUNCTIONS
1065 below.)
1066 .SH COMMENTS
1067 In a non-interactive shell, or an interactive shell in which the
1068 .B interactive_comments
1069 option to the
1070 .B shopt
1071 builtin is enabled (see
1072 .SM
1073 .B "SHELL BUILTIN COMMANDS"
1074 below), a word beginning with
1075 .B #
1076 causes that word and all remaining characters on that line to
1077 be ignored. An interactive shell without the
1078 .B interactive_comments
1079 option enabled does not allow comments. The
1080 .B interactive_comments
1081 option is on by default in interactive shells.
1082 .SH QUOTING
1083 \fIQuoting\fP is used to remove the special meaning of certain
1084 characters or words to the shell. Quoting can be used to
1085 disable special treatment for special characters, to prevent
1086 reserved words from being recognized as such, and to prevent
1087 parameter expansion.
1088 .PP
1089 Each of the \fImetacharacters\fP listed above under
1090 .SM
1091 .B DEFINITIONS
1092 has special meaning to the shell and must be quoted if it is to
1093 represent itself.
1094 .PP
1095 When the command history expansion facilities are being used
1096 (see
1097 .SM
1098 .B HISTORY EXPANSION
1099 below), the
1100 \fIhistory expansion\fP character, usually \fB!\fP, must be quoted
1101 to prevent history expansion.
1102 .PP
1103 There are three quoting mechanisms: the
1104 .IR "escape character" ,
1105 single quotes, and double quotes.
1106 .PP
1107 A non-quoted backslash (\fB\e\fP) is the
1108 .IR "escape character" .
1109 It preserves the literal value of the next character that follows,
1110 with the exception of <newline>. If a \fB\e\fP<newline> pair
1111 appears, and the backslash is not itself quoted, the \fB\e\fP<newline>
1112 is treated as a line continuation (that is, it is removed from the
1113 input stream and effectively ignored).
1114 .PP
1115 Enclosing characters in single quotes preserves the literal value
1116 of each character within the quotes. A single quote may not occur
1117 between single quotes, even when preceded by a backslash.
1118 .PP
1119 Enclosing characters in double quotes preserves the literal value
1120 of all characters within the quotes, with the exception of
1121 .BR $ ,
1122 .BR \` ,
1123 .BR \e ,
1124 and, when history expansion is enabled,
1125 .BR ! .
1126 When the shell is in \fIposix mode\fP, the \fB!\fP has no special meaning
1127 within double quotes, even when history expansion is enabled.
1128 The characters
1129 .B $
1130 and
1131 .B \`
1132 retain their special meaning within double quotes. The backslash
1133 retains its special meaning only when followed by one of the following
1134 characters:
1135 .BR $ ,
1136 .BR \` ,
1137 \^\fB"\fP\^,
1138 .BR \e ,
1139 or
1140 .BR <newline> .
1141 A double quote may be quoted within double quotes by preceding it with
1142 a backslash.
1143 If enabled, history expansion will be performed unless an
1144 .B !
1145 appearing in double quotes is escaped using a backslash.
1146 The backslash preceding the
1147 .B !
1148 is not removed.
1149 .PP
1150 The special parameters
1151 .B *
1152 and
1153 .B @
1154 have special meaning when in double
1155 quotes (see
1156 .SM
1157 .B PARAMETERS
1158 below).
1159 .PP
1160 Character sequences of the form \fB$\fP\(aq\fIstring\fP\(aq are treated
1161 as a special variant of single quotes.
1162 The sequence expands to \fIstring\fP, with backslash-escaped characters
1163 in \fIstring\fP replaced as specified by the ANSI C standard.
1164 Backslash escape sequences, if present, are decoded as follows:
1165 .RS
1166 .PD 0
1167 .TP
1168 .B \ea
1169 alert (bell)
1170 .TP
1171 .B \eb
1172 backspace
1173 .TP
1174 .B \ee
1175 .TP
1176 .B \eE
1177 an escape character
1178 .TP
1179 .B \ef
1180 form feed
1181 .TP
1182 .B \en
1183 new line
1184 .TP
1185 .B \er
1186 carriage return
1187 .TP
1188 .B \et
1189 horizontal tab
1190 .TP
1191 .B \ev
1192 vertical tab
1193 .TP
1194 .B \e\e
1195 backslash
1196 .TP
1197 .B \e\(aq
1198 single quote
1199 .TP
1200 .B \e\(dq
1201 double quote
1202 .TP
1203 .B \e?
1204 question mark
1205 .TP
1206 .B \e\fInnn\fP
1207 the eight-bit character whose value is the octal value \fInnn\fP
1208 (one to three octal digits)
1209 .TP
1210 .B \ex\fIHH\fP
1211 the eight-bit character whose value is the hexadecimal value \fIHH\fP
1212 (one or two hex digits)
1213 .TP
1214 .B \eu\fIHHHH\fP
1215 the Unicode (ISO/IEC 10646) character whose value is the hexadecimal value
1216 \fIHHHH\fP (one to four hex digits)
1217 .TP
1218 .B \eU\fIHHHHHHHH\fP
1219 the Unicode (ISO/IEC 10646) character whose value is the hexadecimal value
1220 \fIHHHHHHHH\fP (one to eight hex digits)
1221 .TP
1222 .B \ec\fIx\fP
1223 a control-\fIx\fP character
1224 .PD
1225 .RE
1226 .LP
1227 The expanded result is single-quoted, as if the dollar sign had
1228 not been present.
1229 .PP
1230 A double-quoted string preceded by a dollar sign (\fB$\fP\(dq\fIstring\fP\(dq)
1231 will cause the string to be translated according to the current locale.
1232 The \fIgettext\fP infrastructure performs the lookup and
1233 translation, using the \fBLC_MESSAGES\fP, \fBTEXTDOMAINDIR\fP,
1234 and \fBTEXTDOMAIN\fP shell variables.
1235 If the current locale is \fBC\fP or \fBPOSIX\fP,
1236 if there are no translations available,
1237 or if the string is not translated,
1238 the dollar sign is ignored.
1239 This is a form of double quoting, so the string remains double-quoted
1240 by default, whether or not it is translated and replaced.
1241 If the \fBnoexpand_translation\fP option is enabled
1242 using the \fBshopt\fP builtin,
1243 translated strings are single-quoted instead of double-quoted.
1244 See the description of
1245 .B shopt
1246 below under
1247 .SM
1248 .BR SHELL BUILTIN COMMANDS .
1249 .SH PARAMETERS
1250 A
1251 .I parameter
1252 is an entity that stores values.
1253 It can be a
1254 .IR name ,
1255 a number, or one of the special characters listed below under
1256 .BR "Special Parameters" .
1257 A
1258 .I variable
1259 is a parameter denoted by a
1260 .IR name .
1261 A variable has a \fIvalue\fP and zero or more \fIattributes\fP.
1262 Attributes are assigned using the
1263 .B declare
1264 builtin command (see
1265 .B declare
1266 below in
1267 .SM
1268 .BR "SHELL BUILTIN COMMANDS" ).
1269 .PP
1270 A parameter is set if it has been assigned a value. The null string is
1271 a valid value. Once a variable is set, it may be unset only by using
1272 the
1273 .B unset
1274 builtin command (see
1275 .SM
1276 .B SHELL BUILTIN COMMANDS
1277 below).
1278 .PP
1279 A
1280 .I variable
1281 may be assigned to by a statement of the form
1282 .RS
1283 .PP
1284 \fIname\fP=[\fIvalue\fP]
1285 .RE
1286 .PP
1287 If
1288 .I value
1289 is not given, the variable is assigned the null string. All
1290 .I values
1291 undergo tilde expansion, parameter and variable expansion,
1292 command substitution, arithmetic expansion, and quote
1293 removal (see
1294 .SM
1295 .B EXPANSION
1296 below). If the variable has its
1297 .B integer
1298 attribute set, then
1299 .I value
1300 is evaluated as an arithmetic expression even if the $((...)) expansion is
1301 not used (see
1302 .B "Arithmetic Expansion"
1303 below).
1304 Word splitting and pathname expansion are not performed.
1305 Assignment statements may also appear as arguments to the
1306 .BR alias ,
1307 .BR declare ,
1308 .BR typeset ,
1309 .BR export ,
1310 .BR readonly ,
1311 and
1312 .B local
1313 builtin commands (\fIdeclaration\fP commands).
1314 When in \fIposix mode\fP, these builtins may appear in a command after
1315 one or more instances of the \fBcommand\fP builtin and retain these
1316 assignment statement properties.
1317 .PP
1318 In the context where an assignment statement is assigning a value
1319 to a shell variable or array index, the += operator can be used to
1320 append to or add to the variable's previous value.
1321 This includes arguments to builtin commands such as \fBdeclare\fP that
1322 accept assignment statements (\fIdeclaration\fP commands).
1323 When += is applied to a variable for which the \fBinteger\fP attribute has been
1324 set, \fIvalue\fP is evaluated as an arithmetic expression and added to the
1325 variable's current value, which is also evaluated.
1326 When += is applied to an array variable using compound assignment (see
1327 .B Arrays
1328 below), the
1329 variable's value is not unset (as it is when using =), and new values are
1330 appended to the array beginning at one greater than the array's maximum index
1331 (for indexed arrays) or added as additional key\-value pairs in an
1332 associative array.
1333 When applied to a string-valued variable, \fIvalue\fP is expanded and
1334 appended to the variable's value.
1335 .PP
1336 A variable can be assigned the \fInameref\fP attribute using the
1337 \fB\-n\fP option to the \fBdeclare\fP or \fBlocal\fP builtin commands
1338 (see the descriptions of \fBdeclare\fP and \fBlocal\fP below)
1339 to create a \fInameref\fP, or a reference to another variable.
1340 This allows variables to be manipulated indirectly.
1341 Whenever the nameref variable is referenced, assigned to, unset, or has
1342 its attributes modified (other than using or changing the \fInameref\fP
1343 attribute itself), the
1344 operation is actually performed on the variable specified by the nameref
1345 variable's value.
1346 A nameref is commonly used within shell functions to refer to a variable
1347 whose name is passed as an argument to the function.
1348 For instance, if a variable name is passed to a shell function as its first
1349 argument, running
1350 .sp .5
1351 .RS
1352 .if t \f(CWdeclare -n ref=$1\fP
1353 .if n declare -n ref=$1
1354 .RE
1355 .sp .5
1356 inside the function creates a nameref variable \fBref\fP whose value is
1357 the variable name passed as the first argument.
1358 References and assignments to \fBref\fP, and changes to its attributes,
1359 are treated as references, assignments, and attribute modifications
1360 to the variable whose name was passed as \fB$1\fP.
1361 If the control variable in a \fBfor\fP loop has the nameref attribute,
1362 the list of words can be a list of shell variables, and a name reference
1363 will be established for each word in the list, in turn, when the loop is
1364 executed.
1365 Array variables cannot be given the \fBnameref\fP attribute.
1366 However, nameref variables can reference array variables and subscripted
1367 array variables.
1368 Namerefs can be unset using the \fB\-n\fP option to the \fBunset\fP builtin.
1369 Otherwise, if \fBunset\fP is executed with the name of a nameref variable
1370 as an argument, the variable referenced by the nameref variable will be unset.
1371 .SS Positional Parameters
1372 A
1373 .I positional parameter
1374 is a parameter denoted by one or more
1375 digits, other than the single digit 0. Positional parameters are
1376 assigned from the shell's arguments when it is invoked,
1377 and may be reassigned using the
1378 .B set
1379 builtin command. Positional parameters may not be assigned to
1380 with assignment statements. The positional parameters are
1381 temporarily replaced when a shell function is executed (see
1382 .SM
1383 .B FUNCTIONS
1384 below).
1385 .PP
1386 When a positional parameter consisting of more than a single
1387 digit is expanded, it must be enclosed in braces (see
1388 .SM
1389 .B EXPANSION
1390 below).
1391 .SS Special Parameters
1392 The shell treats several parameters specially. These parameters may
1393 only be referenced; assignment to them is not allowed.
1394 .PD 0
1395 .TP
1396 .B *
1397 Expands to the positional parameters, starting from one.
1398 When the expansion is not within double quotes, each positional parameter
1399 expands to a separate word.
1400 In contexts where it is performed, those words
1401 are subject to further word splitting and pathname expansion.
1402 When the expansion occurs within double quotes, it expands to a single word
1403 with the value of each parameter separated by the first character of the
1404 .SM
1405 .B IFS
1406 special variable. That is, "\fB$*\fP" is equivalent
1407 to "\fB$1\fP\fIc\fP\fB$2\fP\fIc\fP\fB...\fP", where
1408 .I c
1409 is the first character of the value of the
1410 .SM
1411 .B IFS
1412 variable. If
1413 .SM
1414 .B IFS
1415 is unset, the parameters are separated by spaces.
1416 If
1417 .SM
1418 .B IFS
1419 is null, the parameters are joined without intervening separators.
1420 .TP
1421 .B @
1422 Expands to the positional parameters, starting from one.
1423 In contexts where word splitting is performed, this expands each
1424 positional parameter to a separate word; if not within double
1425 quotes, these words are subject to word splitting.
1426 In contexts where word splitting is not performed,
1427 this expands to a single word
1428 with each positional parameter separated by a space.
1429 When the
1430 expansion occurs within double quotes, each parameter expands to a
1431 separate word. That is, "\fB$@\fP" is equivalent to
1432 "\fB$1\fP" "\fB$2\fP" ...
1433 If the double-quoted expansion occurs within a word, the expansion of
1434 the first parameter is joined with the beginning part of the original
1435 word, and the expansion of the last parameter is joined with the last
1436 part of the original word.
1437 When there are no positional parameters, "\fB$@\fP" and
1438 .B $@
1439 expand to nothing (i.e., they are removed).
1440 .TP
1441 .B #
1442 Expands to the number of positional parameters in decimal.
1443 .TP
1444 .B ?
1445 Expands to the exit status of the most recently executed foreground
1446 pipeline.
1447 .TP
1448 .B \-
1449 Expands to the current option flags as specified upon invocation,
1450 by the
1451 .B set
1452 builtin command, or those set by the shell itself
1453 (such as the
1454 .B \-i
1455 option).
1456 .TP
1457 .B $
1458 Expands to the process ID of the shell. In a subshell, it
1459 expands to the process ID of the current shell, not the
1460 subshell.
1461 .TP
1462 .B !
1463 Expands to the process ID of the job most recently placed into the
1464 background, whether executed as an asynchronous command or using
1465 the \fBbg\fP builtin (see
1466 .SM
1467 .B "JOB CONTROL"
1468 below).
1469 .TP
1470 .B 0
1471 Expands to the name of the shell or shell script. This is set at
1472 shell initialization. If
1473 .B bash
1474 is invoked with a file of commands,
1475 .B $0
1476 is set to the name of that file. If
1477 .B bash
1478 is started with the
1479 .B \-c
1480 option, then
1481 .B $0
1482 is set to the first argument after the string to be
1483 executed, if one is present. Otherwise, it is set
1484 to the filename used to invoke
1485 .BR bash ,
1486 as given by argument zero.
1487 .PD
1488 .SS Shell Variables
1489 The following variables are set by the shell:
1490 .PP
1491 .PD 0
1492 .TP
1493 .B _
1494 At shell startup, set to the pathname used to invoke the
1495 shell or shell script being executed as passed in the environment
1496 or argument list.
1497 Subsequently, expands to the last argument to the previous simple
1498 command executed in the foreground, after expansion.
1499 Also set to the full pathname used to invoke each command executed
1500 and placed in the environment exported to that command.
1501 When checking mail, this parameter holds the name of the mail file
1502 currently being checked.
1503 .TP
1504 .B BASH
1505 Expands to the full filename used to invoke this instance of
1506 .BR bash .
1507 .TP
1508 .B BASHOPTS
1509 A colon-separated list of enabled shell options. Each word in
1510 the list is a valid argument for the
1511 .B \-s
1512 option to the
1513 .B shopt
1514 builtin command (see
1515 .SM
1516 .B "SHELL BUILTIN COMMANDS"
1517 below). The options appearing in
1518 .SM
1519 .B BASHOPTS
1520 are those reported as
1521 .I on
1522 by \fBshopt\fP.
1523 If this variable is in the environment when
1524 .B bash
1525 starts up, each shell option in the list will be enabled before
1526 reading any startup files.
1527 This variable is read-only.
1528 .TP
1529 .B BASHPID
1530 Expands to the process ID of the current \fBbash\fP process.
1531 This differs from \fB$$\fP under certain circumstances, such as subshells
1532 that do not require \fBbash\fP to be re-initialized.
1533 Assignments to
1534 .SM
1535 .B BASHPID
1536 have no effect.
1537 If
1538 .B BASHPID
1539 is unset, it loses its special properties, even if it is
1540 subsequently reset.
1541 .TP
1542 .B BASH_ALIASES
1543 An associative array variable whose members correspond to the internal
1544 list of aliases as maintained by the \fBalias\fP builtin.
1545 Elements added to this array appear in the alias list; however,
1546 unsetting array elements currently does not cause aliases to be removed
1547 from the alias list.
1548 If
1549 .B BASH_ALIASES
1550 is unset, it loses its special properties, even if it is
1551 subsequently reset.
1552 .TP
1553 .B BASH_ARGC
1554 An array variable whose values are the number of parameters in each
1555 frame of the current \fBbash\fP execution call stack.
1556 The number of
1557 parameters to the current subroutine (shell function or script executed
1558 with \fB.\fP or \fBsource\fP) is at the top of the stack.
1559 When a subroutine is executed, the number of parameters passed is pushed onto
1560 .SM
1561 .BR BASH_ARGC .
1562 The shell sets
1563 .SM
1564 .B BASH_ARGC
1565 only when in extended debugging mode (see the description of the
1566 .B extdebug
1567 option to the
1568 .B shopt
1569 builtin below).
1570 Setting \fBextdebug\fP after the shell has started to execute a script,
1571 or referencing this variable when \fBextdebug\fP is not set,
1572 may result in inconsistent values.
1573 .TP
1574 .B BASH_ARGV
1575 An array variable containing all of the parameters in the current \fBbash\fP
1576 execution call stack. The final parameter of the last subroutine call
1577 is at the top of the stack; the first parameter of the initial call is
1578 at the bottom. When a subroutine is executed, the parameters supplied
1579 are pushed onto
1580 .SM
1581 .BR BASH_ARGV .
1582 The shell sets
1583 .SM
1584 .B BASH_ARGV
1585 only when in extended debugging mode
1586 (see the description of the
1587 .B extdebug
1588 option to the
1589 .B shopt
1590 builtin below).
1591 Setting \fBextdebug\fP after the shell has started to execute a script,
1592 or referencing this variable when \fBextdebug\fP is not set,
1593 may result in inconsistent values.
1594 .TP
1595 .B BASH_ARGV0
1596 When referenced, this variable expands to the name of the shell or shell
1597 script (identical to
1598 .BR $0 ;
1599 see the description of special parameter 0 above).
1600 Assignment to
1601 .B BASH_ARGV0
1602 causes the value assigned to also be assigned to \fB$0\fP.
1603 If
1604 .B BASH_ARGV0
1605 is unset, it loses its special properties, even if it is
1606 subsequently reset.
1607 .TP
1608 .B BASH_CMDS
1609 An associative array variable whose members correspond to the internal
1610 hash table of commands as maintained by the \fBhash\fP builtin.
1611 Elements added to this array appear in the hash table; however,
1612 unsetting array elements currently does not cause command names to be removed
1613 from the hash table.
1614 If
1615 .B BASH_CMDS
1616 is unset, it loses its special properties, even if it is
1617 subsequently reset.
1618 .TP
1619 .B BASH_COMMAND
1620 The command currently being executed or about to be executed, unless the
1621 shell is executing a command as the result of a trap,
1622 in which case it is the command executing at the time of the trap.
1623 If
1624 .B BASH_COMMAND
1625 is unset, it loses its special properties, even if it is
1626 subsequently reset.
1627 .TP
1628 .B BASH_EXECUTION_STRING
1629 The command argument to the \fB\-c\fP invocation option.
1630 .TP
1631 .B BASH_LINENO
1632 An array variable whose members are the line numbers in source files
1633 where each corresponding member of
1634 .SM
1635 .B FUNCNAME
1636 was invoked.
1637 \fB${BASH_LINENO[\fP\fI$i\fP\fB]}\fP is the line number in the source
1638 file (\fB${BASH_SOURCE[\fP\fI$i+1\fP\fB]}\fP) where
1639 \fB${FUNCNAME[\fP\fI$i\fP\fB]}\fP was called
1640 (or \fB${BASH_LINENO[\fP\fI$i-1\fP\fB]}\fP if referenced within another
1641 shell function).
1642 Use
1643 .SM
1644 .B LINENO
1645 to obtain the current line number.
1646 .TP
1647 .B BASH_LOADABLES_PATH
1648 A colon-separated list of directories in which the shell looks for
1649 dynamically loadable builtins specified by the
1650 .B enable
1651 command.
1652 .TP
1653 .B BASH_REMATCH
1654 An array variable whose members are assigned by the \fB=~\fP binary
1655 operator to the \fB[[\fP conditional command.
1656 The element with index 0 is the portion of the string
1657 matching the entire regular expression.
1658 The element with index \fIn\fP is the portion of the
1659 string matching the \fIn\fPth parenthesized subexpression.
1660 .TP
1661 .B BASH_SOURCE
1662 An array variable whose members are the source filenames
1663 where the corresponding shell function names in the
1664 .SM
1665 .B FUNCNAME
1666 array variable are defined.
1667 The shell function
1668 \fB${FUNCNAME[\fP\fI$i\fP\fB]}\fP is defined in the file
1669 \fB${BASH_SOURCE[\fP\fI$i\fP\fB]}\fP and called from
1670 \fB${BASH_SOURCE[\fP\fI$i+1\fP\fB]}\fP.
1671 .TP
1672 .B BASH_SUBSHELL
1673 Incremented by one within each subshell or subshell environment when
1674 the shell begins executing in that environment.
1675 The initial value is 0.
1676 If
1677 .B BASH_SUBSHELL
1678 is unset, it loses its special properties, even if it is
1679 subsequently reset.
1680 .TP
1681 .B BASH_VERSINFO
1682 A readonly array variable whose members hold version information for
1683 this instance of
1684 .BR bash .
1685 The values assigned to the array members are as follows:
1686 .sp .5
1687 .RS
1688 .TP 24
1689 .B BASH_VERSINFO[\fR0\fP]
1690 The major version number (the \fIrelease\fP).
1691 .TP
1692 .B BASH_VERSINFO[\fR1\fP]
1693 The minor version number (the \fIversion\fP).
1694 .TP
1695 .B BASH_VERSINFO[\fR2\fP]
1696 The patch level.
1697 .TP
1698 .B BASH_VERSINFO[\fR3\fP]
1699 The build version.
1700 .TP
1701 .B BASH_VERSINFO[\fR4\fP]
1702 The release status (e.g., \fIbeta1\fP).
1703 .TP
1704 .B BASH_VERSINFO[\fR5\fP]
1705 The value of
1706 .SM
1707 .BR MACHTYPE .
1708 .RE
1709 .TP
1710 .B BASH_VERSION
1711 Expands to a string describing the version of this instance of
1712 .BR bash .
1713 .TP
1714 .B COMP_CWORD
1715 An index into \fB${COMP_WORDS}\fP of the word containing the current
1716 cursor position.
1717 This variable is available only in shell functions invoked by the
1718 programmable completion facilities (see \fBProgrammable Completion\fP
1719 below).
1720 .TP
1721 .B COMP_KEY
1722 The key (or final key of a key sequence) used to invoke the current
1723 completion function.
1724 .TP
1725 .B COMP_LINE
1726 The current command line.
1727 This variable is available only in shell functions and external
1728 commands invoked by the
1729 programmable completion facilities (see \fBProgrammable Completion\fP
1730 below).
1731 .TP
1732 .B COMP_POINT
1733 The index of the current cursor position relative to the beginning of
1734 the current command.
1735 If the current cursor position is at the end of the current command,
1736 the value of this variable is equal to \fB${#COMP_LINE}\fP.
1737 This variable is available only in shell functions and external
1738 commands invoked by the
1739 programmable completion facilities (see \fBProgrammable Completion\fP
1740 below).
1741 .TP
1742 .B COMP_TYPE
1743 Set to an integer value corresponding to the type of completion attempted
1744 that caused a completion function to be called:
1745 \fITAB\fP, for normal completion,
1746 \fI?\fP, for listing completions after successive tabs,
1747 \fI!\fP, for listing alternatives on partial word completion,
1748 \fI@\fP, to list completions if the word is not unmodified,
1749 or
1750 \fI%\fP, for menu completion.
1751 This variable is available only in shell functions and external
1752 commands invoked by the
1753 programmable completion facilities (see \fBProgrammable Completion\fP
1754 below).
1755 .TP
1756 .B COMP_WORDBREAKS
1757 The set of characters that the \fBreadline\fP library treats as word
1758 separators when performing word completion.
1759 If
1760 .SM
1761 .B COMP_WORDBREAKS
1762 is unset, it loses its special properties, even if it is
1763 subsequently reset.
1764 .TP
1765 .B COMP_WORDS
1766 An array variable (see \fBArrays\fP below) consisting of the individual
1767 words in the current command line.
1768 The line is split into words as \fBreadline\fP would split it, using
1769 .SM
1770 .B COMP_WORDBREAKS
1771 as described above.
1772 This variable is available only in shell functions invoked by the
1773 programmable completion facilities (see \fBProgrammable Completion\fP
1774 below).
1775 .TP
1776 .B COPROC
1777 An array variable (see \fBArrays\fP below) created to hold the file descriptors
1778 for output from and input to an unnamed coprocess (see \fBCoprocesses\fP
1779 above).
1780 .TP
1781 .B DIRSTACK
1782 An array variable (see
1783 .B Arrays
1784 below) containing the current contents of the directory stack.
1785 Directories appear in the stack in the order they are displayed by the
1786 .B dirs
1787 builtin.
1788 Assigning to members of this array variable may be used to modify
1789 directories already in the stack, but the
1790 .B pushd
1791 and
1792 .B popd
1793 builtins must be used to add and remove directories.
1794 Assignment to this variable will not change the current directory.
1795 If
1796 .SM
1797 .B DIRSTACK
1798 is unset, it loses its special properties, even if it is
1799 subsequently reset.
1800 .TP
1801 .B EPOCHREALTIME
1802 Each time this parameter is referenced, it expands to the number of seconds
1803 since the Unix Epoch (see \fItime\fP\fR(3)\fP) as a floating point value
1804 with micro-second granularity.
1805 Assignments to
1806 .SM
1807 .B EPOCHREALTIME
1808 are ignored.
1809 If
1810 .SM
1811 .B EPOCHREALTIME
1812 is unset, it loses its special properties, even if it is
1813 subsequently reset.
1814 .TP
1815 .B EPOCHSECONDS
1816 Each time this parameter is referenced, it expands to the number of seconds
1817 since the Unix Epoch (see \fItime\fP\fR(3)\fP).
1818 Assignments to
1819 .SM
1820 .B EPOCHSECONDS
1821 are ignored.
1822 If
1823 .SM
1824 .B EPOCHSECONDS
1825 is unset, it loses its special properties, even if it is
1826 subsequently reset.
1827 .TP
1828 .B EUID
1829 Expands to the effective user ID of the current user, initialized at
1830 shell startup. This variable is readonly.
1831 .TP
1832 .B FUNCNAME
1833 An array variable containing the names of all shell functions
1834 currently in the execution call stack.
1835 The element with index 0 is the name of any currently-executing
1836 shell function.
1837 The bottom-most element (the one with the highest index) is
1838 .if t \f(CW"main"\fP.
1839 .if n "main".
1840 This variable exists only when a shell function is executing.
1841 Assignments to
1842 .SM
1843 .B FUNCNAME
1844 have no effect.
1845 If
1846 .SM
1847 .B FUNCNAME
1848 is unset, it loses its special properties, even if it is
1849 subsequently reset.
1850 .if t .sp 0.5
1851 .if n .sp 1
1852 This variable can be used with \fBBASH_LINENO\fP and \fBBASH_SOURCE\fP.
1853 Each element of \fBFUNCNAME\fP has corresponding elements in
1854 \fBBASH_LINENO\fP and \fBBASH_SOURCE\fP to describe the call stack.
1855 For instance, \fB${FUNCNAME[\fP\fI$i\fP\fB]}\fP was called from the file
1856 \fB${BASH_SOURCE[\fP\fI$i+1\fP\fB]}\fP at line number
1857 \fB${BASH_LINENO[\fP\fI$i\fP\fB]}\fP.
1858 The \fBcaller\fP builtin displays the current call stack using this
1859 information.
1860 .TP
1861 .B GROUPS
1862 An array variable containing the list of groups of which the current
1863 user is a member.
1864 Assignments to
1865 .SM
1866 .B GROUPS
1867 have no effect.
1868 If
1869 .SM
1870 .B GROUPS
1871 is unset, it loses its special properties, even if it is
1872 subsequently reset.
1873 .TP
1874 .B HISTCMD
1875 The history number, or index in the history list, of the current
1876 command.
1877 Assignments to
1878 .SM
1879 .B HISTCMD
1880 are ignored.
1881 If
1882 .SM
1883 .B HISTCMD
1884 is unset, it loses its special properties, even if it is
1885 subsequently reset.
1886 .TP
1887 .B HOSTNAME
1888 Automatically set to the name of the current host.
1889 .TP
1890 .B HOSTTYPE
1891 Automatically set to a string that uniquely
1892 describes the type of machine on which
1893 .B bash
1894 is executing.
1895 The default is system-dependent.
1896 .TP
1897 .B LINENO
1898 Each time this parameter is referenced, the shell substitutes
1899 a decimal number representing the current sequential line number
1900 (starting with 1) within a script or function. When not in a
1901 script or function, the value substituted is not guaranteed to
1902 be meaningful.
1903 If
1904 .SM
1905 .B LINENO
1906 is unset, it loses its special properties, even if it is
1907 subsequently reset.
1908 .TP
1909 .B MACHTYPE
1910 Automatically set to a string that fully describes the system
1911 type on which
1912 .B bash
1913 is executing, in the standard GNU \fIcpu-company-system\fP format.
1914 The default is system-dependent.
1915 .TP
1916 .B MAPFILE
1917 An array variable (see \fBArrays\fP below) created to hold the text
1918 read by the \fBmapfile\fP builtin when no variable name is supplied.
1919 .TP
1920 .B OLDPWD
1921 The previous working directory as set by the
1922 .B cd
1923 command.
1924 .TP
1925 .B OPTARG
1926 The value of the last option argument processed by the
1927 .B getopts
1928 builtin command (see
1929 .SM
1930 .B SHELL BUILTIN COMMANDS
1931 below).
1932 .TP
1933 .B OPTIND
1934 The index of the next argument to be processed by the
1935 .B getopts
1936 builtin command (see
1937 .SM
1938 .B SHELL BUILTIN COMMANDS
1939 below).
1940 .TP
1941 .B OSTYPE
1942 Automatically set to a string that
1943 describes the operating system on which
1944 .B bash
1945 is executing.
1946 The default is system-dependent.
1947 .TP
1948 .B PIPESTATUS
1949 An array variable (see
1950 .B Arrays
1951 below) containing a list of exit status values from the processes
1952 in the most-recently-executed foreground pipeline (which may
1953 contain only a single command).
1954 .TP
1955 .B PPID
1956 The process ID of the shell's parent. This variable is readonly.
1957 .TP
1958 .B PWD
1959 The current working directory as set by the
1960 .B cd
1961 command.
1962 .TP
1963 .B RANDOM
1964 Each time this parameter is referenced, it expands to a random integer
1965 between 0 and 32767.
1966 Assigning
1967 a value to
1968 .SM
1969 .BR RANDOM
1970 initializes (seeds) the sequence of random numbers.
1971 If
1972 .SM
1973 .B RANDOM
1974 is unset, it loses its special properties, even if it is
1975 subsequently reset.
1976 .TP
1977 .B READLINE_ARGUMENT
1978 Any numeric argument given to a readline command that was defined using
1979 .if t \f(CWbind -x\fP
1980 .if n "bind -x"
1981 (see
1982 .SM
1983 .B "SHELL BUILTIN COMMANDS"
1984 below)
1985 when it was invoked.
1986 .TP
1987 .B READLINE_LINE
1988 The contents of the
1989 .B readline
1990 line buffer, for use with
1991 .if t \f(CWbind -x\fP
1992 .if n "bind -x"
1993 (see
1994 .SM
1995 .B "SHELL BUILTIN COMMANDS"
1996 below).
1997 .TP
1998 .B READLINE_MARK
1999 The position of the mark (saved insertion point) in the
2000 .B readline
2001 line buffer, for use with
2002 .if t \f(CWbind -x\fP
2003 .if n "bind -x"
2004 (see
2005 .SM
2006 .B "SHELL BUILTIN COMMANDS"
2007 below).
2008 The characters between the insertion point and the mark are often
2009 called the \fIregion\fP.
2010 .TP
2011 .B READLINE_POINT
2012 The position of the insertion point in the
2013 .B readline
2014 line buffer, for use with
2015 .if t \f(CWbind -x\fP
2016 .if n "bind -x"
2017 (see
2018 .SM
2019 .B "SHELL BUILTIN COMMANDS"
2020 below).
2021 .TP
2022 .B REPLY
2023 Set to the line of input read by the
2024 .B read
2025 builtin command when no arguments are supplied.
2026 .TP
2027 .B SECONDS
2028 Each time this parameter is
2029 referenced, it expands to the number of seconds since shell invocation.
2030 If a value is assigned to
2031 .SM
2032 .BR SECONDS ,
2033 the value returned upon subsequent
2034 references is
2035 the number of seconds since the assignment plus the value assigned.
2036 The number of seconds at shell invocation and the current time are always
2037 determined by querying the system clock.
2038 If
2039 .SM
2040 .B SECONDS
2041 is unset, it loses its special properties, even if it is
2042 subsequently reset.
2043 .TP
2044 .B SHELLOPTS
2045 A colon-separated list of enabled shell options. Each word in
2046 the list is a valid argument for the
2047 .B \-o
2048 option to the
2049 .B set
2050 builtin command (see
2051 .SM
2052 .B "SHELL BUILTIN COMMANDS"
2053 below). The options appearing in
2054 .SM
2055 .B SHELLOPTS
2056 are those reported as
2057 .I on
2058 by \fBset \-o\fP.
2059 If this variable is in the environment when
2060 .B bash
2061 starts up, each shell option in the list will be enabled before
2062 reading any startup files.
2063 This variable is read-only.
2064 .TP
2065 .B SHLVL
2066 Incremented by one each time an instance of
2067 .B bash
2068 is started.
2069 .TP
2070 .B SRANDOM
2071 This variable expands to a 32-bit pseudo-random number each time it is
2072 referenced. The random number generator is not linear on systems that
2073 support \f(CW/dev/urandom\fP or \fIarc4random\fP, so each returned number
2074 has no relationship to the numbers preceding it.
2075 The random number generator cannot be seeded, so assignments to this
2076 variable have no effect.
2077 If
2078 .SM
2079 .B SRANDOM
2080 is unset, it loses its special properties,
2081 even if it is subsequently reset.
2082 .TP
2083 .B UID
2084 Expands to the user ID of the current user, initialized at shell startup.
2085 This variable is readonly.
2086 .PD
2087 .PP
2088 The following variables are used by the shell. In some cases,
2089 .B bash
2090 assigns a default value to a variable; these cases are noted
2091 below.
2092 .PP
2093 .PD 0
2094 .TP
2095 .B BASH_COMPAT
2096 The value is used to set the shell's compatibility level.
2097 See
2098 .SM
2099 .B "SHELL COMPATIBILITY MODE"
2100 below for a description of the various compatibility
2101 levels and their effects.
2102 The value may be a decimal number (e.g., 4.2) or an integer (e.g., 42)
2103 corresponding to the desired compatibility level.
2104 If \fBBASH_COMPAT\fP is unset or set to the empty string, the compatibility
2105 level is set to the default for the current version.
2106 If \fBBASH_COMPAT\fP is set to a value that is not one of the valid
2107 compatibility levels, the shell prints an error message and sets the
2108 compatibility level to the default for the current version.
2109 The valid values correspond to the compatibility levels
2110 described below under
2111 .SM
2112 .BR "SHELL COMPATIBILITY MODE" .
2113 For example, 4.2 and 42 are valid values that correspond
2114 to the \fBcompat42\fP \fBshopt\fP option
2115 and set the compatibility level to 42.
2116 The current version is also a valid value.
2117 .TP
2118 .B BASH_ENV
2119 If this parameter is set when \fBbash\fP is executing a shell script,
2120 its value is interpreted as a filename containing commands to
2121 initialize the shell, as in
2122 .IR ~/.bashrc .
2123 The value of
2124 .SM
2125 .B BASH_ENV
2126 is subjected to parameter expansion, command substitution, and arithmetic
2127 expansion before being interpreted as a filename.
2128 .SM
2129 .B PATH
2130 is not used to search for the resultant filename.
2131 .TP
2132 .B BASH_XTRACEFD
2133 If set to an integer corresponding to a valid file descriptor, \fBbash\fP
2134 will write the trace output generated when
2135 .if t \f(CWset -x\fP
2136 .if n \fIset -x\fP
2137 is enabled to that file descriptor.
2138 The file descriptor is closed when
2139 .SM
2140 .B BASH_XTRACEFD
2141 is unset or assigned a new value.
2142 Unsetting
2143 .SM
2144 .B BASH_XTRACEFD
2145 or assigning it the empty string causes the
2146 trace output to be sent to the standard error.
2147 Note that setting
2148 .SM
2149 .B BASH_XTRACEFD
2150 to 2 (the standard error file
2151 descriptor) and then unsetting it will result in the standard error
2152 being closed.
2153 .TP
2154 .B CDPATH
2155 The search path for the
2156 .B cd
2157 command.
2158 This is a colon-separated list of directories in which the shell looks
2159 for destination directories specified by the
2160 .B cd
2161 command.
2162 A sample value is
2163 .if t \f(CW".:~:/usr"\fP.
2164 .if n ".:~:/usr".
2165 .TP
2166 .B CHILD_MAX
2167 Set the number of exited child status values for the shell to remember.
2168 Bash will not allow this value to be decreased below a POSIX-mandated
2169 minimum, and there is a maximum value (currently 8192) that this may
2170 not exceed.
2171 The minimum value is system-dependent.
2172 .TP
2173 .B COLUMNS
2174 Used by the \fBselect\fP compound command to determine the terminal width
2175 when printing selection lists.
2176 Automatically set if the
2177 .B checkwinsize
2178 option is enabled or in an interactive shell upon receipt of a
2179 .SM
2180 .BR SIGWINCH .
2181 .TP
2182 .B COMPREPLY
2183 An array variable from which \fBbash\fP reads the possible completions
2184 generated by a shell function invoked by the programmable completion
2185 facility (see \fBProgrammable Completion\fP below).
2186 Each array element contains one possible completion.
2187 .TP
2188 .B EMACS
2189 If \fBbash\fP finds this variable in the environment when the shell starts
2190 with value
2191 .if t \f(CWt\fP,
2192 .if n "t",
2193 it assumes that the shell is running in an Emacs shell buffer and disables
2194 line editing.
2195 .TP
2196 .B ENV
2197 Expanded and executed similarly to
2198 .SM
2199 .B BASH_ENV
2200 (see \fBINVOCATION\fP above)
2201 when an interactive shell is invoked in \fIposix mode\fP.
2202 .TP
2203 .B EXECIGNORE
2204 A colon-separated list of shell patterns (see \fBPattern Matching\fP)
2205 defining the list of filenames to be ignored by command search using
2206 \fBPATH\fP.
2207 Files whose full pathnames match one of these patterns are not considered
2208 executable files for the purposes of completion and command execution
2209 via \fBPATH\fP lookup.
2210 This does not affect the behavior of the \fB[\fP, \fBtest\fP, and \fB[[\fP
2211 commands.
2212 Full pathnames in the command hash table are not subject to \fBEXECIGNORE\fP.
2213 Use this variable to ignore shared library files that have the executable
2214 bit set, but are not executable files.
2215 The pattern matching honors the setting of the \fBextglob\fP shell
2216 option.
2217 .TP
2218 .B FCEDIT
2219 The default editor for the
2220 .B fc
2221 builtin command.
2222 .TP
2223 .B FIGNORE
2224 A colon-separated list of suffixes to ignore when performing
2225 filename completion (see
2226 .SM
2227 .B READLINE
2228 below).
2229 A filename whose suffix matches one of the entries in
2230 .SM
2231 .B FIGNORE
2232 is excluded from the list of matched filenames.
2233 A sample value is
2234 .if t \f(CW".o:~"\fP.
2235 .if n ".o:~".
2236 .TP
2237 .B FUNCNEST
2238 If set to a numeric value greater than 0, defines a maximum function
2239 nesting level. Function invocations that exceed this nesting level
2240 will cause the current command to abort.
2241 .TP
2242 .B GLOBIGNORE
2243 A colon-separated list of patterns defining the set of file names to
2244 be ignored by pathname expansion.
2245 If a file name matched by a pathname expansion pattern also matches one
2246 of the patterns in
2247 .SM
2248 .BR GLOBIGNORE ,
2249 it is removed from the list of matches.
2250 .TP
2251 .B HISTCONTROL
2252 A colon-separated list of values controlling how commands are saved on
2253 the history list.
2254 If the list of values includes
2255 .IR ignorespace ,
2256 lines which begin with a
2257 .B space
2258 character are not saved in the history list.
2259 A value of
2260 .I ignoredups
2261 causes lines matching the previous history entry to not be saved.
2262 A value of
2263 .I ignoreboth
2264 is shorthand for \fIignorespace\fP and \fIignoredups\fP.
2265 A value of
2266 .I erasedups
2267 causes all previous lines matching the current line to be removed from
2268 the history list before that line is saved.
2269 Any value not in the above list is ignored.
2270 If
2271 .SM
2272 .B HISTCONTROL
2273 is unset, or does not include a valid value,
2274 all lines read by the shell parser are saved on the history list,
2275 subject to the value of
2276 .SM
2277 .BR HISTIGNORE .
2278 The second and subsequent lines of a multi-line compound command are
2279 not tested, and are added to the history regardless of the value of
2280 .SM
2281 .BR HISTCONTROL .
2282 .TP
2283 .B HISTFILE
2284 The name of the file in which command history is saved (see
2285 .SM
2286 .B HISTORY
2287 below). The default value is \fI~/.bash_history\fP. If unset, the
2288 command history is not saved when a shell exits.
2289 .TP
2290 .B HISTFILESIZE
2291 The maximum number of lines contained in the history file. When this
2292 variable is assigned a value, the history file is truncated, if
2293 necessary,
2294 to contain no more than that number of lines by removing the oldest entries.
2295 The history file is also truncated to this size after
2296 writing it when a shell exits.
2297 If the value is 0, the history file is truncated to zero size.
2298 Non-numeric values and numeric values less than zero inhibit truncation.
2299 The shell sets the default value to the value of \fBHISTSIZE\fP
2300 after reading any startup files.
2301 .TP
2302 .B HISTIGNORE
2303 A colon-separated list of patterns used to decide which command lines
2304 should be saved on the history list. Each pattern is anchored at the
2305 beginning of the line and must match the complete line (no implicit
2306 `\fB*\fP' is appended). Each pattern is tested against the line
2307 after the checks specified by
2308 .SM
2309 .B HISTCONTROL
2310 are applied.
2311 In addition to the normal shell pattern matching characters, `\fB&\fP'
2312 matches the previous history line. `\fB&\fP' may be escaped using a
2313 backslash; the backslash is removed before attempting a match.
2314 The second and subsequent lines of a multi-line compound command are
2315 not tested, and are added to the history regardless of the value of
2316 .SM
2317 .BR HISTIGNORE .
2318 The pattern matching honors the setting of the \fBextglob\fP shell
2319 option.
2320 .TP
2321 .B HISTSIZE
2322 The number of commands to remember in the command history (see
2323 .SM
2324 .B HISTORY
2325 below).
2326 If the value is 0, commands are not saved in the history list.
2327 Numeric values less than zero result in every command being saved
2328 on the history list (there is no limit).
2329 The shell sets the default value to 500 after reading any startup files.
2330 .TP
2331 .B HISTTIMEFORMAT
2332 If this variable is set and not null, its value is used as a format string
2333 for \fIstrftime\fP(3) to print the time stamp associated with each history
2334 entry displayed by the \fBhistory\fP builtin.
2335 If this variable is set, time stamps are written to the history file so
2336 they may be preserved across shell sessions.
2337 This uses the history comment character to distinguish timestamps from
2338 other history lines.
2339 .TP
2340 .B HOME
2341 The home directory of the current user; the default argument for the
2342 \fBcd\fP builtin command.
2343 The value of this variable is also used when performing tilde expansion.
2344 .TP
2345 .B HOSTFILE
2346 Contains the name of a file in the same format as
2347 .FN /etc/hosts
2348 that should be read when the shell needs to complete a
2349 hostname.
2350 The list of possible hostname completions may be changed while the
2351 shell is running;
2352 the next time hostname completion is attempted after the
2353 value is changed,
2354 .B bash
2355 adds the contents of the new file to the existing list.
2356 If
2357 .SM
2358 .B HOSTFILE
2359 is set, but has no value, or does not name a readable file,
2360 \fBbash\fP attempts to read
2361 .FN /etc/hosts
2362 to obtain the list of possible hostname completions.
2363 When
2364 .SM
2365 .B HOSTFILE
2366 is unset, the hostname list is cleared.
2367 .TP
2368 .B IFS
2369 The
2370 .I Internal Field Separator
2371 that is used
2372 for word splitting after expansion and to
2373 split lines into words with the
2374 .B read
2375 builtin command. The default value is
2376 ``<space><tab><newline>''.
2377 .TP
2378 .B IGNOREEOF
2379 Controls the
2380 action of an interactive shell on receipt of an
2381 .SM
2382 .B EOF
2383 character as the sole input. If set, the value is the number of
2384 consecutive
2385 .SM
2386 .B EOF
2387 characters which must be
2388 typed as the first characters on an input line before
2389 .B bash
2390 exits. If the variable exists but does not have a numeric value, or
2391 has no value, the default value is 10. If it does not exist,
2392 .SM
2393 .B EOF
2394 signifies the end of input to the shell.
2395 .TP
2396 .B INPUTRC
2397 The filename for the
2398 .B readline
2399 startup file, overriding the default of
2400 .FN ~/.inputrc
2401 (see
2402 .SM
2403 .B READLINE
2404 below).
2405 .TP
2406 .B INSIDE_EMACS
2407 If this variable appears in the environment when the shell starts,
2408 \fBbash\fP assumes that it is running inside an Emacs shell buffer
2409 and may disable line editing, depending on the value of \fBTERM\fP.
2410 .TP
2411 .B LANG
2412 Used to determine the locale category for any category not specifically
2413 selected with a variable starting with \fBLC_\fP.
2414 .TP
2415 .B LC_ALL
2416 This variable overrides the value of
2417 .SM
2418 .B LANG
2419 and any other
2420 \fBLC_\fP variable specifying a locale category.
2421 .TP
2422 .B LC_COLLATE
2423 This variable determines the collation order used when sorting the
2424 results of pathname expansion, and determines the behavior of range
2425 expressions, equivalence classes, and collating sequences within
2426 pathname expansion and pattern matching.
2427 .TP
2428 .B LC_CTYPE
2429 This variable determines the interpretation of characters and the
2430 behavior of character classes within pathname expansion and pattern
2431 matching.
2432 .TP
2433 .B LC_MESSAGES
2434 This variable determines the locale used to translate double-quoted
2435 strings preceded by a \fB$\fP.
2436 .TP
2437 .B LC_NUMERIC
2438 This variable determines the locale category used for number formatting.
2439 .TP
2440 .B LC_TIME
2441 This variable determines the locale category used for data and time
2442 formatting.
2443 .TP
2444 .B LINES
2445 Used by the \fBselect\fP compound command to determine the column length
2446 for printing selection lists.
2447 Automatically set if the
2448 .B checkwinsize
2449 option is enabled or in an interactive shell upon receipt of a
2450 .SM
2451 .BR SIGWINCH .
2452 .TP
2453 .B MAIL
2454 If this parameter is set to a file or directory name and the
2455 .SM
2456 .B MAILPATH
2457 variable is not set,
2458 .B bash
2459 informs the user of the arrival of mail in the specified file or
2460 Maildir-format directory.
2461 .TP
2462 .B MAILCHECK
2463 Specifies how
2464 often (in seconds)
2465 .B bash
2466 checks for mail. The default is 60 seconds. When it is time to check
2467 for mail, the shell does so before displaying the primary prompt.
2468 If this variable is unset, or set to a value that is not a number
2469 greater than or equal to zero, the shell disables mail checking.
2470 .TP
2471 .B MAILPATH
2472 A colon-separated list of filenames to be checked for mail.
2473 The message to be printed when mail arrives in a particular file
2474 may be specified by separating the filename from the message with a `?'.
2475 When used in the text of the message, \fB$_\fP expands to the name of
2476 the current mailfile.
2477 Example:
2478 .RS
2479 .PP
2480 \fBMAILPATH\fP=\(aq/var/mail/bfox?"You have mail":~/shell\-mail?"$_ has mail!"\(aq
2481 .PP
2482 .B Bash
2483 can be configured to supply
2484 a default value for this variable (there is no value by default),
2485 but the location of the user
2486 mail files that it uses is system dependent (e.g., /var/mail/\fB$USER\fP).
2487 .RE
2488 .TP
2489 .B OPTERR
2490 If set to the value 1,
2491 .B bash
2492 displays error messages generated by the
2493 .B getopts
2494 builtin command (see
2495 .SM
2496 .B SHELL BUILTIN COMMANDS
2497 below).
2498 .SM
2499 .B OPTERR
2500 is initialized to 1 each time the shell is invoked or a shell
2501 script is executed.
2502 .TP
2503 .B PATH
2504 The search path for commands. It
2505 is a colon-separated list of directories in which
2506 the shell looks for commands (see
2507 .SM
2508 .B COMMAND EXECUTION
2509 below).
2510 A zero-length (null) directory name in the value of
2511 .SM
2512 .B PATH
2513 indicates the current directory.
2514 A null directory name may appear as two adjacent colons, or as an initial
2515 or trailing colon.
2516 The default path is system-dependent,
2517 and is set by the administrator who installs
2518 .BR bash .
2519 A common value is
2520 .na
2521 .if t \f(CW/usr/local/bin:/usr/local/sbin:/usr/bin:/usr/sbin:/bin:/sbin\fP.
2522 .if n ``/usr/local/bin:/usr/local/sbin:/usr/bin:/usr/sbin:/bin:/sbin''.
2523 .ad
2524 .TP
2525 .B POSIXLY_CORRECT
2526 If this variable is in the environment when \fBbash\fP starts, the shell
2527 enters \fIposix mode\fP before reading the startup files, as if the
2528 .B \-\-posix
2529 invocation option had been supplied. If it is set while the shell is
2530 running, \fBbash\fP enables \fIposix mode\fP, as if the command
2531 .if t \f(CWset -o posix\fP
2532 .if n \fIset -o posix\fP
2533 had been executed.
2534 When the shell enters \fIposix mode\fP, it sets this variable if it was
2535 not already set.
2536 .TP
2537 .B PROMPT_COMMAND
2538 If this variable is set, and is an array,
2539 the value of each set element is executed as a command
2540 prior to issuing each primary prompt.
2541 If this is set but not an array variable,
2542 its value is used as a command to execute instead.
2543 .TP
2544 .B PROMPT_DIRTRIM
2545 If set to a number greater than zero, the value is used as the number of
2546 trailing directory components to retain when expanding the \fB\ew\fP and
2547 \fB\eW\fP prompt string escapes (see
2548 .SM
2549 .B PROMPTING
2550 below). Characters removed are replaced with an ellipsis.
2551 .TP
2552 .B PS0
2553 The value of this parameter is expanded (see
2554 .SM
2555 .B PROMPTING
2556 below) and displayed by interactive shells after reading a command
2557 and before the command is executed.
2558 .TP
2559 .B PS1
2560 The value of this parameter is expanded (see
2561 .SM
2562 .B PROMPTING
2563 below) and used as the primary prompt string. The default value is
2564 ``\fB\es\-\ev\e$ \fP''.
2565 .TP
2566 .B PS2
2567 The value of this parameter is expanded as with
2568 .SM
2569 .B PS1
2570 and used as the secondary prompt string. The default is
2571 ``\fB> \fP''.
2572 .TP
2573 .B PS3
2574 The value of this parameter is used as the prompt for the
2575 .B select
2576 command (see
2577 .SM
2578 .B SHELL GRAMMAR
2579 above).
2580 .TP
2581 .B PS4
2582 The value of this parameter is expanded as with
2583 .SM
2584 .B PS1
2585 and the value is printed before each command
2586 .B bash
2587 displays during an execution trace. The first character of
2588 the expanded value of
2589 .SM
2590 .B PS4
2591 is replicated multiple times, as necessary, to indicate multiple
2592 levels of indirection. The default is ``\fB+ \fP''.
2593 .TP
2594 .B SHELL
2595 This variable expands to the full pathname to the shell.
2596 If it is not set when the shell starts,
2597 .B bash
2598 assigns to it the full pathname of the current user's login shell.
2599 .TP
2600 .B TIMEFORMAT
2601 The value of this parameter is used as a format string specifying
2602 how the timing information for pipelines prefixed with the
2603 .B time
2604 reserved word should be displayed.
2605 The \fB%\fP character introduces an escape sequence that is
2606 expanded to a time value or other information.
2607 The escape sequences and their meanings are as follows; the
2608 braces denote optional portions.
2609 .sp .5
2610 .RS
2611 .PD 0
2612 .TP 10
2613 .B %%
2614 A literal \fB%\fP.
2615 .TP
2616 .B %[\fIp\fP][l]R
2617 The elapsed time in seconds.
2618 .TP
2619 .B %[\fIp\fP][l]U
2620 The number of CPU seconds spent in user mode.
2621 .TP
2622 .B %[\fIp\fP][l]S
2623 The number of CPU seconds spent in system mode.
2624 .TP
2625 .B %P
2626 The CPU percentage, computed as (%U + %S) / %R.
2627 .PD
2628 .RE
2629 .IP
2630 The optional \fIp\fP is a digit specifying the \fIprecision\fP,
2631 the number of fractional digits after a decimal point.
2632 A value of 0 causes no decimal point or fraction to be output.
2633 At most three places after the decimal point may be specified;
2634 values of \fIp\fP greater than 3 are changed to 3.
2635 If \fIp\fP is not specified, the value 3 is used.
2636 .IP
2637 The optional \fBl\fP specifies a longer format, including
2638 minutes, of the form \fIMM\fPm\fISS\fP.\fIFF\fPs.
2639 The value of \fIp\fP determines whether or not the fraction is
2640 included.
2641 .IP
2642 If this variable is not set, \fBbash\fP acts as if it had the
2643 value \fB$\(aq\enreal\et%3lR\enuser\et%3lU\ensys\et%3lS\(aq\fP.
2644 If the value is null, no timing information is displayed.
2645 A trailing newline is added when the format string is displayed.
2646 .PD 0
2647 .TP
2648 .B TMOUT
2649 If set to a value greater than zero,
2650 .SM
2651 .B TMOUT
2652 is treated as the
2653 default timeout for the \fBread\fP builtin.
2654 The \fBselect\fP command terminates if input does not arrive
2655 after
2656 .SM
2657 .B TMOUT
2658 seconds when input is coming from a terminal.
2659 In an interactive shell, the value is interpreted as the
2660 number of seconds to wait for a line of input after issuing the
2661 primary prompt.
2662 .B Bash
2663 terminates after waiting for that number of seconds if a complete
2664 line of input does not arrive.
2665 .TP
2666 .B TMPDIR
2667 If set, \fBbash\fP uses its value as the name of a directory in which
2668 \fBbash\fP creates temporary files for the shell's use.
2669 .TP
2670 .B auto_resume
2671 This variable controls how the shell interacts with the user and
2672 job control. If this variable is set, single word simple
2673 commands without redirections are treated as candidates for resumption
2674 of an existing stopped job. There is no ambiguity allowed; if there is
2675 more than one job beginning with the string typed, the job most recently
2676 accessed is selected. The
2677 .I name
2678 of a stopped job, in this context, is the command line used to
2679 start it.
2680 If set to the value
2681 .IR exact ,
2682 the string supplied must match the name of a stopped job exactly;
2683 if set to
2684 .IR substring ,
2685 the string supplied needs to match a substring of the name of a
2686 stopped job. The
2687 .I substring
2688 value provides functionality analogous to the
2689 .B %?
2690 job identifier (see
2691 .SM
2692 .B JOB CONTROL
2693 below). If set to any other value, the supplied string must
2694 be a prefix of a stopped job's name; this provides functionality
2695 analogous to the \fB%\fP\fIstring\fP job identifier.
2696 .TP
2697 .B histchars
2698 The two or three characters which control history expansion
2699 and tokenization (see
2700 .SM
2701 .B HISTORY EXPANSION
2702 below). The first character is the \fIhistory expansion\fP character,
2703 the character which signals the start of a history
2704 expansion, normally `\fB!\fP'.
2705 The second character is the \fIquick substitution\fP
2706 character, which is used as shorthand for re-running the previous
2707 command entered, substituting one string for another in the command.
2708 The default is `\fB^\fP'.
2709 The optional third character is the character
2710 which indicates that the remainder of the line is a comment when found
2711 as the first character of a word, normally `\fB#\fP'. The history
2712 comment character causes history substitution to be skipped for the
2713 remaining words on the line. It does not necessarily cause the shell
2714 parser to treat the rest of the line as a comment.
2715 .PD
2716 .SS Arrays
2717 .B Bash
2718 provides one-dimensional indexed and associative array variables.
2719 Any variable may be used as an indexed array; the
2720 .B declare
2721 builtin will explicitly declare an array.
2722 There is no maximum
2723 limit on the size of an array, nor any requirement that members
2724 be indexed or assigned contiguously.
2725 Indexed arrays are referenced using integers (including arithmetic
2726 expressions) and are zero-based; associative arrays are referenced
2727 using arbitrary strings.
2728 Unless otherwise noted, indexed array indices must be non-negative integers.
2729 .PP
2730 An indexed array is created automatically if any variable is assigned to
2731 using the syntax \fIname\fP[\fIsubscript\fP]=\fIvalue\fP. The
2732 .I subscript
2733 is treated as an arithmetic expression that must evaluate to a number.
2734 To explicitly declare an indexed array, use
2735 .B declare \-a \fIname\fP
2736 (see
2737 .SM
2738 .B SHELL BUILTIN COMMANDS
2739 below).
2740 .B declare \-a \fIname\fP[\fIsubscript\fP]
2741 is also accepted; the \fIsubscript\fP is ignored.
2742 .PP
2743 Associative arrays are created using
2744 .BR "declare \-A \fIname\fP" .
2745 .PP
2746 Attributes may be
2747 specified for an array variable using the
2748 .B declare
2749 and
2750 .B readonly
2751 builtins. Each attribute applies to all members of an array.
2752 .PP
2753 Arrays are assigned to using compound assignments of the form
2754 \fIname\fP=\fB(\fPvalue\fI1\fP ... value\fIn\fP\fB)\fP, where each
2755 \fIvalue\fP may be of the form [\fIsubscript\fP]=\fIstring\fP.
2756 Indexed array assignments do not require anything but \fIstring\fP.
2757 Each \fIvalue\fP in the list is expanded using all the shell expansions
2758 described below under
2759 .SM
2760 .BR EXPANSION .
2761 When assigning to indexed arrays, if the optional brackets and subscript
2762 are supplied, that index is assigned to;
2763 otherwise the index of the element assigned is the last index assigned
2764 to by the statement plus one. Indexing starts at zero.
2765 .PP
2766 When assigning to an associative array, the words in a compound assignment
2767 may be either assignment statements, for which the subscript is required,
2768 or a list of words that is interpreted as a sequence of alternating keys
2769 and values:
2770 \fIname\fP=\fB( \fP\fIkey1 value1 key2 value2\fP ...\fB)\fP.
2771 These are treated identically to
2772 \fIname\fP=\fB(\fP [\fIkey1\fP]=\fIvalue1\fP [\fIkey2\fP]=\fIvalue2\fP ...\fB)\fP.
2773 The first word in the list determines how the remaining words
2774 are interpreted; all assignments in a list must be of the same type.
2775 When using key/value pairs, the keys may not be missing or empty;
2776 a final missing value is treated like the empty string.
2777 .PP
2778 This syntax is also accepted by the
2779 .B declare
2780 builtin. Individual array elements may be assigned to using the
2781 \fIname\fP[\fIsubscript\fP]=\fIvalue\fP syntax introduced above.
2782 When assigning to an indexed array, if
2783 .I name
2784 is subscripted by a negative number, that number is
2785 interpreted as relative to one greater than the maximum index of
2786 \fIname\fP, so negative indices count back from the end of the
2787 array, and an index of \-1 references the last element.
2788 .PP
2789 The += operator will append to an array variable when assigning
2790 using the compound assignment syntax; see
2791 .SM
2792 .B PARAMETERS
2793 above.
2794 .PP
2795 Any element of an array may be referenced using
2796 ${\fIname\fP[\fIsubscript\fP]}. The braces are required to avoid
2797 conflicts with pathname expansion. If
2798 \fIsubscript\fP is \fB@\fP or \fB*\fP, the word expands to
2799 all members of \fIname\fP. These subscripts differ only when the
2800 word appears within double quotes. If the word is double-quoted,
2801 ${\fIname\fP[*]} expands to a single
2802 word with the value of each array member separated by the first
2803 character of the
2804 .SM
2805 .B IFS
2806 special variable, and ${\fIname\fP[@]} expands each element of
2807 \fIname\fP to a separate word. When there are no array members,
2808 ${\fIname\fP[@]} expands to nothing.
2809 If the double-quoted expansion occurs within a word, the expansion of
2810 the first parameter is joined with the beginning part of the original
2811 word, and the expansion of the last parameter is joined with the last
2812 part of the original word.
2813 This is analogous to the expansion
2814 of the special parameters \fB*\fP and \fB@\fP (see
2815 .B Special Parameters
2816 above). ${#\fIname\fP[\fIsubscript\fP]} expands to the length of
2817 ${\fIname\fP[\fIsubscript\fP]}. If \fIsubscript\fP is \fB*\fP or
2818 \fB@\fP, the expansion is the number of elements in the array.
2819 If the
2820 .I subscript
2821 used to reference an element of an indexed array
2822 evaluates to a number less than zero, it is
2823 interpreted as relative to one greater than the maximum index of the array,
2824 so negative indices count back from the end of the
2825 array, and an index of \-1 references the last element.
2826 .PP
2827 Referencing an array variable without a subscript is equivalent to
2828 referencing the array with a subscript of 0.
2829 Any reference to a variable using a valid subscript is legal, and
2830 .B bash
2831 will create an array if necessary.
2832 .PP
2833 An array variable is considered set if a subscript has been assigned a
2834 value. The null string is a valid value.
2835 .PP
2836 It is possible to obtain the keys (indices) of an array as well as the values.
2837 ${\fB!\fP\fIname\fP[\fI@\fP]} and ${\fB!\fP\fIname\fP[\fI*\fP]}
2838 expand to the indices assigned in array variable \fIname\fP.
2839 The treatment when in double quotes is similar to the expansion of the
2840 special parameters \fI@\fP and \fI*\fP within double quotes.
2841 .PP
2842 The
2843 .B unset
2844 builtin is used to destroy arrays. \fBunset\fP \fIname\fP[\fIsubscript\fP]
2845 destroys the array element at index \fIsubscript\fP,
2846 for both indexed and associative arrays.
2847 Negative subscripts to indexed arrays are interpreted as described above.
2848 Unsetting the last element of an array variable does not unset the variable.
2849 \fBunset\fP \fIname\fP, where \fIname\fP is an array,
2850 removes the entire array.
2851 \fBunset\fP \fIname\fP[\fIsubscript\fP], where
2852 \fIsubscript\fP is \fB*\fP or \fB@\fP, behaves differently depending on
2853 whether \fIname\fP is an indexed or associative array.
2854 If \fIname\fP is an associative array, this unsets the element with
2855 subscript \fB*\fP or \fB@\fP.
2856 If \fIname\fP is an indexed array, unset removes all of the elements but
2857 does not remove the array itself.
2858 .PP
2859 When using a variable name with a subscript as an argument to a command,
2860 such as with \fBunset\fP, without using the word expansion syntax
2861 described above, the argument is subject to pathname expansion.
2862 If pathname expansion is not desired, the argument should be quoted.
2863 .PP
2864 The
2865 .BR declare ,
2866 .BR local ,
2867 and
2868 .B readonly
2869 builtins each accept a
2870 .B \-a
2871 option to specify an indexed array and a
2872 .B \-A
2873 option to specify an associative array.
2874 If both options are supplied,
2875 .B \-A
2876 takes precedence.
2877 The
2878 .B read
2879 builtin accepts a
2880 .B \-a
2881 option to assign a list of words read from the standard input
2882 to an array. The
2883 .B set
2884 and
2885 .B declare
2886 builtins display array values in a way that allows them to be
2887 reused as assignments.
2888 .SH EXPANSION
2889 Expansion is performed on the command line after it has been split into
2890 words. There are seven kinds of expansion performed:
2891 .IR "brace expansion" ,
2892 .IR "tilde expansion" ,
2893 .IR "parameter and variable expansion" ,
2894 .IR "command substitution" ,
2895 .IR "arithmetic expansion" ,
2896 .IR "word splitting" ,
2897 and
2898 .IR "pathname expansion" .
2899 .PP
2900 The order of expansions is:
2901 brace expansion;
2902 tilde expansion, parameter and variable expansion, arithmetic expansion,
2903 and command substitution (done in a left-to-right fashion);
2904 word splitting;
2905 and pathname expansion.
2906 .PP
2907 On systems that can support it, there is an additional expansion
2908 available: \fIprocess substitution\fP.
2909 This is performed at the
2910 same time as tilde, parameter, variable, and arithmetic expansion and
2911 command substitution.
2912 .PP
2913 After these expansions are performed, quote characters present in the
2914 original word are removed unless they have been quoted themselves
2915 (\fIquote removal\fP).
2916 .PP
2917 Only brace expansion, word splitting, and pathname expansion
2918 can increase the number of words of the expansion; other expansions
2919 expand a single word to a single word.
2920 The only exceptions to this are the expansions of
2921 "\fB$@\fP" and "\fB${\fP\fIname\fP\fB[@]}\fP",
2922 and, in most cases, \fB$*\fP and \fB${\fP\fIname\fP\fB[*]}\fP
2923 as explained above (see
2924 .SM
2925 .BR PARAMETERS ).
2926 .SS Brace Expansion
2927 .I "Brace expansion"
2928 is a mechanism by which arbitrary strings
2929 may be generated. This mechanism is similar to
2930 \fIpathname expansion\fP, but the filenames generated
2931 need not exist. Patterns to be brace expanded take
2932 the form of an optional
2933 .IR preamble ,
2934 followed by either a series of comma-separated strings or
2935 a sequence expression between a pair of braces, followed by
2936 an optional
2937 .IR postscript .
2938 The preamble is prefixed to each string contained
2939 within the braces, and the postscript is then appended
2940 to each resulting string, expanding left to right.
2941 .PP
2942 Brace expansions may be nested. The results of each expanded
2943 string are not sorted; left to right order is preserved.
2944 For example, a\fB{\fPd,c,b\fB}\fPe expands into `ade ace abe'.
2945 .PP
2946 A sequence expression takes the form
2947 \fB{\fP\fIx\fP\fB..\fP\fIy\fP\fB[..\fP\fIincr\fP\fB]}\fP,
2948 where \fIx\fP and \fIy\fP are either integers or single letters,
2949 and \fIincr\fP, an optional increment, is an integer.
2950 When integers are supplied, the expression expands to each number between
2951 \fIx\fP and \fIy\fP, inclusive.
2952 Supplied integers may be prefixed with \fI0\fP to force each term to have the
2953 same width.
2954 When either \fIx\fP or \fPy\fP begins with a zero, the shell
2955 attempts to force all generated terms to contain the same number of digits,
2956 zero-padding where necessary.
2957 When letters are supplied, the expression expands to each character
2958 lexicographically between \fIx\fP and \fIy\fP, inclusive,
2959 using the default C locale.
2960 Note that both \fIx\fP and \fIy\fP must be of the same type
2961 (integer or letter).
2962 When the increment is supplied, it is used as the difference between
2963 each term. The default increment is 1 or \-1 as appropriate.
2964 .PP
2965 Brace expansion is performed before any other expansions,
2966 and any characters special to other expansions are preserved
2967 in the result. It is strictly textual.
2968 .B Bash
2969 does not apply any syntactic interpretation to the context of the
2970 expansion or the text between the braces.
2971 .PP
2972 A correctly-formed brace expansion must contain unquoted opening
2973 and closing braces, and at least one unquoted comma or a valid
2974 sequence expression.
2975 Any incorrectly formed brace expansion is left unchanged.
2976 A \fB{\fP or \fB,\fP may be quoted with a backslash to prevent its
2977 being considered part of a brace expression.
2978 To avoid conflicts with parameter expansion, the string \fB${\fP
2979 is not considered eligible for brace expansion, and inhibits brace
2980 expansion until the closing \fB}\fP.
2981 .PP
2982 This construct is typically used as shorthand when the common
2983 prefix of the strings to be generated is longer than in the
2984 above example:
2985 .RS
2986 .PP
2987 mkdir /usr/local/src/bash/{old,new,dist,bugs}
2988 .RE
2989 or
2990 .RS
2991 chown root /usr/{ucb/{ex,edit},lib/{ex?.?*,how_ex}}
2992 .RE
2993 .PP
2994 Brace expansion introduces a slight incompatibility with
2995 historical versions of
2996 .BR sh .
2997 .B sh
2998 does not treat opening or closing braces specially when they
2999 appear as part of a word, and preserves them in the output.
3000 .B Bash
3001 removes braces from words as a consequence of brace
3002 expansion. For example, a word entered to
3003 .B sh
3004 as \fIfile{1,2}\fP
3005 appears identically in the output. The same word is
3006 output as
3007 .I file1 file2
3008 after expansion by
3009 .BR bash .
3010 If strict compatibility with
3011 .B sh
3012 is desired, start
3013 .B bash
3014 with the
3015 .B +B
3016 option or disable brace expansion with the
3017 .B +B
3018 option to the
3019 .B set
3020 command (see
3021 .SM
3022 .B SHELL BUILTIN COMMANDS
3023 below).
3024 .SS Tilde Expansion
3025 If a word begins with an unquoted tilde character (`\fB~\fP'), all of
3026 the characters preceding the first unquoted slash (or all characters,
3027 if there is no unquoted slash) are considered a \fItilde-prefix\fP.
3028 If none of the characters in the tilde-prefix are quoted, the
3029 characters in the tilde-prefix following the tilde are treated as a
3030 possible \fIlogin name\fP.
3031 If this login name is the null string, the tilde is replaced with the
3032 value of the shell parameter
3033 .SM
3034 .BR HOME .
3035 If
3036 .SM
3037 .B HOME
3038 is unset, the home directory of the user executing the shell is
3039 substituted instead.
3040 Otherwise, the tilde-prefix is replaced with the home directory
3041 associated with the specified login name.
3042 .PP
3043 If the tilde-prefix is a `~+', the value of the shell variable
3044 .SM
3045 .B PWD
3046 replaces the tilde-prefix.
3047 If the tilde-prefix is a `~\-', the value of the shell variable
3048 .SM
3049 .BR OLDPWD ,
3050 if it is set, is substituted.
3051 If the characters following the tilde in the tilde-prefix consist
3052 of a number \fIN\fP, optionally prefixed
3053 by a `+' or a `\-', the tilde-prefix is replaced with the corresponding
3054 element from the directory stack, as it would be displayed by the
3055 .B dirs
3056 builtin invoked with the tilde-prefix as an argument.
3057 If the characters following the tilde in the tilde-prefix consist of a
3058 number without a leading `+' or `\-', `+' is assumed.
3059 .PP
3060 If the login name is invalid, or the tilde expansion fails, the word
3061 is unchanged.
3062 .PP
3063 Each variable assignment is checked for unquoted tilde-prefixes immediately
3064 following a
3065 .B :
3066 or the first
3067 .BR = .
3068 In these cases, tilde expansion is also performed.
3069 Consequently, one may use filenames with tildes in assignments to
3070 .SM
3071 .BR PATH ,
3072 .SM
3073 .BR MAILPATH ,
3074 and
3075 .SM
3076 .BR CDPATH ,
3077 and the shell assigns the expanded value.
3078 .PP
3079 Bash also performs tilde expansion on words satisfying the conditions of
3080 variable assignments (as described above under
3081 .SM
3082 .BR PARAMETERS )
3083 when they appear as arguments to simple commands.
3084 Bash does not do this, except for the \fIdeclaration\fP commands listed
3085 above, when in \fIposix mode\fP.
3086 .SS Parameter Expansion
3087 The `\fB$\fP' character introduces parameter expansion,
3088 command substitution, or arithmetic expansion. The parameter name
3089 or symbol to be expanded may be enclosed in braces, which
3090 are optional but serve to protect the variable to be expanded from
3091 characters immediately following it which could be
3092 interpreted as part of the name.
3093 .PP
3094 When braces are used, the matching ending brace is the first `\fB}\fP'
3095 not escaped by a backslash or within a quoted string, and not within an
3096 embedded arithmetic expansion, command substitution, or parameter
3097 expansion.
3098 .PP
3099 .PD 0
3100 .TP
3101 ${\fIparameter\fP}
3102 The value of \fIparameter\fP is substituted. The braces are required
3103 when
3104 .I parameter
3105 is a positional parameter with more than one digit,
3106 or when
3107 .I parameter
3108 is followed by a character which is not to be
3109 interpreted as part of its name.
3110 The \fIparameter\fP is a shell parameter as described above
3111 \fBPARAMETERS\fP) or an array reference (\fBArrays\fP).
3112 .PD
3113 .PP
3114 If the first character of \fIparameter\fP is an exclamation point (\fB!\fP),
3115 and \fIparameter\fP is not a \fInameref\fP,
3116 it introduces a level of indirection.
3117 \fBBash\fP uses the value formed by expanding the rest of
3118 \fIparameter\fP as the new \fIparameter\fP; this is then
3119 expanded and that value is used in the rest of the expansion, rather
3120 than the expansion of the original \fIparameter\fP.
3121 This is known as \fIindirect expansion\fP.
3122 The value is subject to tilde expansion,
3123 parameter expansion, command substitution, and arithmetic expansion.
3124 If \fIparameter\fP is a nameref, this expands to the name of the
3125 parameter referenced by \fIparameter\fP instead of performing the
3126 complete indirect expansion.
3127 The exceptions to this are the expansions of ${\fB!\fP\fIprefix\fP\fB*\fP} and
3128 ${\fB!\fP\fIname\fP[\fI@\fP]} described below.
3129 The exclamation point must immediately follow the left brace in order to
3130 introduce indirection.
3131 .PP
3132 In each of the cases below, \fIword\fP is subject to tilde expansion,
3133 parameter expansion, command substitution, and arithmetic expansion.
3134 .PP
3135 When not performing substring expansion, using the forms documented below
3136 (e.g., \fB:-\fP),
3137 \fBbash\fP tests for a parameter that is unset or null. Omitting the colon
3138 results in a test only for a parameter that is unset.
3139 .PP
3140 .PD 0
3141 .TP
3142 ${\fIparameter\fP\fB:\-\fP\fIword\fP}
3143 \fBUse Default Values\fP. If
3144 .I parameter
3145 is unset or null, the expansion of
3146 .I word
3147 is substituted. Otherwise, the value of
3148 .I parameter
3149 is substituted.
3150 .TP
3151 ${\fIparameter\fP\fB:=\fP\fIword\fP}
3152 \fBAssign Default Values\fP.
3153 If
3154 .I parameter
3155 is unset or null, the expansion of
3156 .I word
3157 is assigned to
3158 .IR parameter .
3159 The value of
3160 .I parameter
3161 is then substituted. Positional parameters and special parameters may
3162 not be assigned to in this way.
3163 .TP
3164 ${\fIparameter\fP\fB:?\fP\fIword\fP}
3165 \fBDisplay Error if Null or Unset\fP.
3166 If
3167 .I parameter
3168 is null or unset, the expansion of \fIword\fP (or a message to that effect
3169 if
3170 .I word
3171 is not present) is written to the standard error and the shell, if it
3172 is not interactive, exits. Otherwise, the value of \fIparameter\fP is
3173 substituted.
3174 .TP
3175 ${\fIparameter\fP\fB:+\fP\fIword\fP}
3176 \fBUse Alternate Value\fP.
3177 If
3178 .I parameter
3179 is null or unset, nothing is substituted, otherwise the expansion of
3180 .I word
3181 is substituted.
3182 .TP
3183 ${\fIparameter\fP\fB:\fP\fIoffset\fP}
3184 .PD 0
3185 .TP
3186 ${\fIparameter\fP\fB:\fP\fIoffset\fP\fB:\fP\fIlength\fP}
3187 .PD
3188 \fBSubstring Expansion\fP.
3189 Expands to up to \fIlength\fP characters of the value of \fIparameter\fP
3190 starting at the character specified by \fIoffset\fP.
3191 If \fIparameter\fP is \fB@\fP or \fB*\fP, an indexed array subscripted by
3192 \fB@\fP or \fB*\fP, or an associative array name, the results differ as
3193 described below.
3194 If \fIlength\fP is omitted, expands to the substring of the value of
3195 \fIparameter\fP starting at the character specified by \fIoffset\fP
3196 and extending to the end of the value.
3197 \fIlength\fP and \fIoffset\fP are arithmetic expressions (see
3198 .SM
3199 .B
3200 ARITHMETIC EVALUATION
3201 below).
3202 .sp 1
3203 If \fIoffset\fP evaluates to a number less than zero, the value
3204 is used as an offset in characters
3205 from the end of the value of \fIparameter\fP.
3206 If \fIlength\fP evaluates to a number less than zero,
3207 it is interpreted as an offset in characters
3208 from the end of the value of \fIparameter\fP rather than
3209 a number of characters, and the expansion is the characters between
3210 \fIoffset\fP and that result.
3211 Note that a negative offset must be separated from the colon by at least
3212 one space to avoid being confused with the \fB:-\fP expansion.
3213 .sp 1
3214 If \fIparameter\fP is \fB@\fP or \fB*\fP, the result is \fIlength\fP
3215 positional parameters beginning at \fIoffset\fP.
3216 A negative \fIoffset\fP is taken relative to one greater than the greatest
3217 positional parameter, so an offset of \-1 evaluates to the last positional
3218 parameter.
3219 It is an expansion error if \fIlength\fP evaluates to a number less than
3220 zero.
3221 .sp 1
3222 If \fIparameter\fP is an indexed array name subscripted by @ or *,
3223 the result is the \fIlength\fP
3224 members of the array beginning with ${\fIparameter\fP[\fIoffset\fP]}.
3225 A negative \fIoffset\fP is taken relative to one greater than the maximum
3226 index of the specified array.
3227 It is an expansion error if \fIlength\fP evaluates to a number less than
3228 zero.
3229 .sp 1
3230 Substring expansion applied to an associative array produces undefined
3231 results.
3232 .sp 1
3233 Substring indexing is zero-based unless the positional parameters
3234 are used, in which case the indexing starts at 1 by default.
3235 If \fIoffset\fP is 0, and the positional parameters are used, \fB$0\fP is
3236 prefixed to the list.
3237 .TP
3238 ${\fB!\fP\fIprefix\fP\fB*\fP}
3239 .PD 0
3240 .TP
3241 ${\fB!\fP\fIprefix\fP\fB@\fP}
3242 .PD
3243 \fBNames matching prefix\fP.
3244 Expands to the names of variables whose names begin with \fIprefix\fP,
3245 separated by the first character of the
3246 .SM
3247 .B IFS
3248 special variable.
3249 When \fI@\fP is used and the expansion appears within double quotes, each
3250 variable name expands to a separate word.
3251 .TP
3252 ${\fB!\fP\fIname\fP[\fI@\fP]}
3253 .PD 0
3254 .TP
3255 ${\fB!\fP\fIname\fP[\fI*\fP]}
3256 .PD
3257 \fBList of array keys\fP.
3258 If \fIname\fP is an array variable, expands to the list of array indices
3259 (keys) assigned in \fIname\fP.
3260 If \fIname\fP is not an array, expands to 0 if \fIname\fP is set and null
3261 otherwise.
3262 When \fI@\fP is used and the expansion appears within double quotes, each
3263 key expands to a separate word.
3264 .TP
3265 ${\fB#\fP\fIparameter\fP}
3266 \fBParameter length\fP.
3267 The length in characters of the value of \fIparameter\fP is substituted.
3268 If
3269 .I parameter
3270 is
3271 .B *
3272 or
3273 .BR @ ,
3274 the value substituted is the number of positional parameters.
3275 If
3276 .I parameter
3277 is an array name subscripted by
3278 .B *
3279 or
3280 .BR @ ,
3281 the value substituted is the number of elements in the array.
3282 If
3283 .I parameter
3284 is an indexed array name subscripted by a negative number, that number is
3285 interpreted as relative to one greater than the maximum index of
3286 \fIparameter\fP, so negative indices count back from the end of the
3287 array, and an index of \-1 references the last element.
3288 .TP
3289 ${\fIparameter\fP\fB#\fP\fIword\fP}
3290 .PD 0
3291 .TP
3292 ${\fIparameter\fP\fB##\fP\fIword\fP}
3293 .PD
3294 \fBRemove matching prefix pattern\fP.
3295 The
3296 .I word
3297 is expanded to produce a pattern just as in pathname
3298 expansion, and matched against the expanded value of
3299 .I parameter
3300 using the rules described under
3301 .B Pattern Matching
3302 below.
3303 If the pattern matches the beginning of
3304 the value of
3305 .IR parameter ,
3306 then the result of the expansion is the expanded value of
3307 .I parameter
3308 with the shortest matching pattern (the ``\fB#\fP'' case) or the
3309 longest matching pattern (the ``\fB##\fP'' case) deleted.
3310 If
3311 .I parameter
3312 is
3313 .B @
3314 or
3315 .BR * ,
3316 the pattern removal operation is applied to each positional
3317 parameter in turn, and the expansion is the resultant list.
3318 If
3319 .I parameter
3320 is an array variable subscripted with
3321 .B @
3322 or
3323 .BR * ,
3324 the pattern removal operation is applied to each member of the
3325 array in turn, and the expansion is the resultant list.
3326 .TP
3327 ${\fIparameter\fP\fB%\fP\fIword\fP}
3328 .PD 0
3329 .TP
3330 ${\fIparameter\fP\fB%%\fP\fIword\fP}
3331 .PD
3332 \fBRemove matching suffix pattern\fP.
3333 The \fIword\fP is expanded to produce a pattern just as in
3334 pathname expansion, and matched against the expanded value of
3335 .I parameter
3336 using the rules described under
3337 .B Pattern Matching
3338 below.
3339 If the pattern matches a trailing portion of the expanded value of
3340 .IR parameter ,
3341 then the result of the expansion is the expanded value of
3342 .I parameter
3343 with the shortest matching pattern (the ``\fB%\fP'' case) or the
3344 longest matching pattern (the ``\fB%%\fP'' case) deleted.
3345 If
3346 .I parameter
3347 is
3348 .B @
3349 or
3350 .BR * ,
3351 the pattern removal operation is applied to each positional
3352 parameter in turn, and the expansion is the resultant list.
3353 If
3354 .I parameter
3355 is an array variable subscripted with
3356 .B @
3357 or
3358 .BR * ,
3359 the pattern removal operation is applied to each member of the
3360 array in turn, and the expansion is the resultant list.
3361 .TP
3362 ${\fIparameter\fP\fB/\fP\fIpattern\fP\fB/\fP\fIstring\fP}
3363 .PD 0
3364 .TP
3365 ${\fIparameter\fP\fB//\fP\fIpattern\fP\fB/\fP\fIstring\fP}
3366 .TP
3367 ${\fIparameter\fP\fB/#\fP\fIpattern\fP\fB/\fP\fIstring\fP}
3368 .TP
3369 ${\fIparameter\fP\fB/%\fP\fIpattern\fP\fB/\fP\fIstring\fP}
3370 .PD
3371 \fBPattern substitution\fP.
3372 The \fIpattern\fP is expanded to produce a pattern just as in
3373 pathname expansion.
3374 \fIParameter\fP is expanded and the longest match of \fIpattern\fP
3375 against its value is replaced with \fIstring\fP.
3376 \fIstring\fP undergoes tilde expansion, parameter and variable expansion,
3377 arithmetic expansion, command and process substitution, and quote removal.
3378 The match is performed using the rules described under
3379 .B Pattern Matching
3380 below.
3381 In the first form above, only the first match is replaced.
3382 If there are two slashes separating \fIparameter\fP and \fIpattern\fP
3383 (the second form above), all matches of \fIpattern\fP are
3384 replaced with \fIstring\fP.
3385 If \fIpattern\fP is preceded by \fB#\fP (the third form above),
3386 it must match at the beginning of the expanded value of \fIparameter\fP.
3387 If \fIpattern\fP is preceded by \fB%\fP (the fourth form above),
3388 it must match at the end of the expanded value of \fIparameter\fP.
3389 If the expansion of \fIstring\fP is null,
3390 matches of \fIpattern\fP are deleted.
3391 If \fIstring\fP is null,
3392 matches of \fIpattern\fP are deleted
3393 and the \fB/\fP following \fIpattern\fP may be omitted.
3394 .sp 1
3395 If the \fBpatsub_replacement\fP shell option is enabled using \fBshopt\fP,
3396 any unquoted instances of \fB&\fP in \fIstring\fP are replaced with the
3397 matching portion of \fIpattern\fP.
3398 .sp 1
3399 Quoting any part of \fIstring\fP inhibits replacement in the
3400 expansion of the quoted portion, including replacement strings stored
3401 in shell variables.
3402 Backslash will escape \fB&\fP in \fIstring\fP; the backslash is removed
3403 in order to permit a literal \fB&\fP in the replacement string.
3404 Backslash can also be used to escape a backslash; \fB\e\e\fP results in
3405 a literal backslash in the replacement.
3406 Users should take care if \fIstring\fP is double-quoted to avoid
3407 unwanted interactions between the backslash and double-quoting, since
3408 backslash has special meaning within double quotes.
3409 Pattern substitution performs the check for unquoted \fB&\fP after
3410 expanding \fIstring\fP;
3411 shell programmers should quote any occurrences of \fB&\fP
3412 they want to be taken literally in the replacement
3413 and ensure any instances of \fB&\fP they want to be replaced are unquoted.
3414 .sp 1
3415 If the
3416 .B nocasematch
3417 shell option is enabled, the match is performed without regard to the case
3418 of alphabetic characters.
3419 If
3420 .I parameter
3421 is
3422 .B @
3423 or
3424 .BR * ,
3425 the substitution operation is applied to each positional
3426 parameter in turn, and the expansion is the resultant list.
3427 If
3428 .I parameter
3429 is an array variable subscripted with
3430 .B @
3431 or
3432 .BR * ,
3433 the substitution operation is applied to each member of the
3434 array in turn, and the expansion is the resultant list.
3435 .TP
3436 ${\fIparameter\fP\fB^\fP\fIpattern\fP}
3437 .PD 0
3438 .TP
3439 ${\fIparameter\fP\fB^^\fP\fIpattern\fP}
3440 .TP
3441 ${\fIparameter\fP\fB,\fP\fIpattern\fP}
3442 .TP
3443 ${\fIparameter\fP\fB,,\fP\fIpattern\fP}
3444 .PD
3445 \fBCase modification\fP.
3446 This expansion modifies the case of alphabetic characters in \fIparameter\fP.
3447 The \fIpattern\fP is expanded to produce a pattern just as in
3448 pathname expansion.
3449 Each character in the expanded value of \fIparameter\fP is tested against
3450 \fIpattern\fP, and, if it matches the pattern, its case is converted.
3451 The pattern should not attempt to match more than one character.
3452 The \fB^\fP operator converts lowercase letters matching \fIpattern\fP
3453 to uppercase; the \fB,\fP operator converts matching uppercase letters
3454 to lowercase.
3455 The \fB^^\fP and \fB,,\fP expansions convert each matched character in the
3456 expanded value; the \fB^\fP and \fB,\fP expansions match and convert only
3457 the first character in the expanded value.
3458 If \fIpattern\fP is omitted, it is treated like a \fB?\fP, which matches
3459 every character.
3460 If
3461 .I parameter
3462 is
3463 .B @
3464 or
3465 .BR * ,
3466 the case modification operation is applied to each positional
3467 parameter in turn, and the expansion is the resultant list.
3468 If
3469 .I parameter
3470 is an array variable subscripted with
3471 .B @
3472 or
3473 .BR * ,
3474 the case modification operation is applied to each member of the
3475 array in turn, and the expansion is the resultant list.
3476 .TP
3477 ${\fIparameter\fP\fB@\fP\fIoperator\fP}
3478 \fBParameter transformation\fP.
3479 The expansion is either a transformation of the value of \fIparameter\fP
3480 or information about \fIparameter\fP itself, depending on the value of
3481 \fIoperator\fP. Each \fIoperator\fP is a single letter:
3482 .sp 1
3483 .RS
3484 .PD 0
3485 .TP
3486 .B U
3487 The expansion is a string that is the value of \fIparameter\fP with lowercase
3488 alphabetic characters converted to uppercase.
3489 .TP
3490 .B u
3491 The expansion is a string that is the value of \fIparameter\fP with the first
3492 character converted to uppercase, if it is alphabetic.
3493 .TP
3494 .B L
3495 The expansion is a string that is the value of \fIparameter\fP with uppercase
3496 alphabetic characters converted to lowercase.
3497 .TP
3498 .B Q
3499 The expansion is a string that is the value of \fIparameter\fP quoted in a
3500 format that can be reused as input.
3501 .TP
3502 .B E
3503 The expansion is a string that is the value of \fIparameter\fP with backslash
3504 escape sequences expanded as with the \fB$\(aq...\(aq\fP quoting mechanism.
3505 .TP
3506 .B P
3507 The expansion is a string that is the result of expanding the value of
3508 \fIparameter\fP as if it were a prompt string (see \fBPROMPTING\fP below).
3509 .TP
3510 .B A
3511 The expansion is a string in the form of
3512 an assignment statement or \fBdeclare\fP command that, if
3513 evaluated, will recreate \fIparameter\fP with its attributes and value.
3514 .TP
3515 .B K
3516 Produces a possibly-quoted version of the value of \fIparameter\fP,
3517 except that it prints the values of
3518 indexed and associative arrays as a sequence of quoted key-value pairs
3519 (see \fBArrays\fP above).
3520 .TP
3521 .B a
3522 The expansion is a string consisting of flag values representing
3523 \fIparameter\fP's attributes.
3524 .TP
3525 .B k
3526 Like the K transformation, but expands the keys and values of
3527 indexed and associative arrays to separate words after word splitting.
3528 .PD
3529 .PP
3530 If
3531 .I parameter
3532 is
3533 .B @
3534 or
3535 .BR * ,
3536 the operation is applied to each positional
3537 parameter in turn, and the expansion is the resultant list.
3538 If
3539 .I parameter
3540 is an array variable subscripted with
3541 .B @
3542 or
3543 .BR * ,
3544 the operation is applied to each member of the
3545 array in turn, and the expansion is the resultant list.
3546 .sp 1
3547 The result of the expansion is subject to word splitting and pathname
3548 expansion as described below.
3549 .RE
3550 .SS Command Substitution
3551 \fICommand substitution\fP allows the output of a command to replace
3552 the command name. There are two forms:
3553 .RS
3554 .PP
3555 \fB$(\fP\fIcommand\fP\|\fB)\fP
3556 .RE
3557 or
3558 .RS
3559 \fB\`\fP\fIcommand\fP\fB\`\fP
3560 .RE
3561 .PP
3562 .B Bash
3563 performs the expansion by executing \fIcommand\fP in a subshell environment
3564 and replacing the command substitution with the standard output of the
3565 command, with any trailing newlines deleted.
3566 Embedded newlines are not deleted, but they may be removed during
3567 word splitting.
3568 The command substitution \fB$(cat \fIfile\fP)\fR can be replaced by
3569 the equivalent but faster \fB$(< \fIfile\fP)\fR.
3570 .PP
3571 When the old-style backquote form of substitution is used,
3572 backslash retains its literal meaning except when followed by
3573 .BR $ ,
3574 .BR \` ,
3575 or
3576 .BR \e .
3577 The first backquote not preceded by a backslash terminates the
3578 command substitution.
3579 When using the $(\^\fIcommand\fP\|) form, all characters between the
3580 parentheses make up the command; none are treated specially.
3581 .PP
3582 Command substitutions may be nested. To nest when using the backquoted form,
3583 escape the inner backquotes with backslashes.
3584 .PP
3585 If the substitution appears within double quotes, word splitting and
3586 pathname expansion are not performed on the results.
3587 .SS Arithmetic Expansion
3588 Arithmetic expansion allows the evaluation of an arithmetic expression
3589 and the substitution of the result. The format for arithmetic expansion is:
3590 .RS
3591 .PP
3592 \fB$((\fP\fIexpression\fP\fB))\fP
3593 .RE
3594 .PP
3595 The
3596 .I expression
3597 undergoes the same expansions
3598 as if it were within double quotes,
3599 but double quote characters in \fIexpression\fP are not treated specially
3600 and are removed.
3601 All tokens in the expression undergo parameter and variable expansion,
3602 command substitution, and quote removal.
3603 The result is treated as the arithmetic expression to be evaluated.
3604 Arithmetic expansions may be nested.
3605 .PP
3606 The evaluation is performed according to the rules listed below under
3607 .SM
3608 .BR "ARITHMETIC EVALUATION" .
3609 If
3610 .I expression
3611 is invalid,
3612 .B bash
3613 prints a message indicating failure and no substitution occurs.
3614 .SS Process Substitution
3615 \fIProcess substitution\fP allows a process's input or output to be
3616 referred to using a filename.
3617 It takes the form of
3618 \fB<(\fP\fIlist\^\fP\fB)\fP
3619 or
3620 \fB>(\fP\fIlist\^\fP\fB)\fP.
3621 The process \fIlist\fP is run asynchronously, and its input or output
3622 appears as a filename.
3623 This filename is
3624 passed as an argument to the current command as the result of the
3625 expansion.
3626 If the \fB>(\fP\fIlist\^\fP\fB)\fP form is used, writing to
3627 the file will provide input for \fIlist\fP. If the
3628 \fB<(\fP\fIlist\^\fP\fB)\fP form is used, the file passed as an
3629 argument should be read to obtain the output of \fIlist\fP.
3630 Process substitution is supported on systems that support named
3631 pipes (\fIFIFOs\fP) or the \fB/dev/fd\fP method of naming open files.
3632 .PP
3633 When available, process substitution is performed
3634 simultaneously with parameter and variable expansion,
3635 command substitution,
3636 and arithmetic expansion.
3637 .SS Word Splitting
3638 The shell scans the results of
3639 parameter expansion,
3640 command substitution,
3641 and
3642 arithmetic expansion
3643 that did not occur within double quotes for
3644 .IR "word splitting" .
3645 .PP
3646 The shell treats each character of
3647 .SM
3648 .B IFS
3649 as a delimiter, and splits the results of the other
3650 expansions into words using these characters as field terminators.
3651 If
3652 .SM
3653 .B IFS
3654 is unset, or its
3655 value is exactly
3656 .BR <space><tab><newline> ,
3657 the default, then
3658 sequences of
3659 .BR <space> ,
3660 .BR <tab> ,
3661 and
3662 .B <newline>
3663 at the beginning and end of the results of the previous
3664 expansions are ignored, and
3665 any sequence of
3666 .SM
3667 .B IFS
3668 characters not at the beginning or end serves to delimit words.
3669 If
3670 .SM
3671 .B IFS
3672 has a value other than the default, then sequences of
3673 the whitespace characters
3674 .BR space ,
3675 .BR tab ,
3676 and
3677 .B newline
3678 are ignored at the beginning and end of the
3679 word, as long as the whitespace character is in the
3680 value of
3681 .SM
3682 .B IFS
3683 (an
3684 .SM
3685 .B IFS
3686 whitespace character).
3687 Any character in
3688 .SM
3689 .B IFS
3690 that is not
3691 .SM
3692 .B IFS
3693 whitespace, along with any adjacent
3694 .SM
3695 .B IFS
3696 whitespace characters, delimits a field.
3697 A sequence of
3698 .SM
3699 .B IFS
3700 whitespace characters is also treated as a delimiter.
3701 If the value of
3702 .SM
3703 .B IFS
3704 is null, no word splitting occurs.
3705 .PP
3706 Explicit null arguments (\^\f3"\^"\fP or \^\f3\(aq\^\(aq\fP\^) are retained
3707 and passed to commands as empty strings.
3708 Unquoted implicit null arguments, resulting from the expansion of
3709 parameters that have no values, are removed.
3710 If a parameter with no value is expanded within double quotes, a
3711 null argument results and is retained
3712 and passed to a command as an empty string.
3713 When a quoted null argument appears as part of a word whose expansion is
3714 non-null, the null argument is removed.
3715 That is, the word
3716 \f(CW\-d\(aq\^\(aq\fP becomes \f(CW\-d\fP after word splitting and
3717 null argument removal.
3718 .PP
3719 Note that if no expansion occurs, no splitting
3720 is performed.
3721 .SS Pathname Expansion
3722 After word splitting,
3723 unless the
3724 .B \-f
3725 option has been set,
3726 .B bash
3727 scans each word for the characters
3728 .BR * ,
3729 .BR ? ,
3730 and
3731 .BR [ .
3732 If one of these characters appears, and is not quoted, then the word is
3733 regarded as a
3734 .IR pattern ,
3735 and replaced with an alphabetically sorted list of
3736 filenames matching the pattern
3737 (see
3738 .SM
3739 .B "Pattern Matching"
3740 below).
3741 If no matching filenames are found,
3742 and the shell option
3743 .B nullglob
3744 is not enabled, the word is left unchanged.
3745 If the
3746 .B nullglob
3747 option is set, and no matches are found,
3748 the word is removed.
3749 If the
3750 .B failglob
3751 shell option is set, and no matches are found, an error message
3752 is printed and the command is not executed.
3753 If the shell option
3754 .B nocaseglob
3755 is enabled, the match is performed without regard to the case
3756 of alphabetic characters.
3757 When a pattern is used for pathname expansion,
3758 the character
3759 .B ``.''
3760 at the start of a name or immediately following a slash
3761 must be matched explicitly, unless the shell option
3762 .B dotglob
3763 is set.
3764 In order to match the filenames
3765 .B ``.''
3766 and
3767 .BR ``..'' ,
3768 the pattern must begin with ``.'' (for example, ``.?''),
3769 even if
3770 .B dotglob
3771 is set.
3772 If the
3773 .B globskipdots
3774 shell option is enabled, the filenames
3775 .B ``.''
3776 and
3777 .BR ``..''
3778 are never matched, even if the pattern begins with a
3779 .BR ``.'' .
3780 When not matching pathnames, the
3781 .B ``.''
3782 character is not treated specially.
3783 When matching a pathname, the slash character must always be
3784 matched explicitly by a slash in the pattern, but in other matching
3785 contexts it can be matched by a special pattern character as described
3786 below under
3787 .SM
3788 .BR "Pattern Matching" .
3789 See the description of
3790 .B shopt
3791 below under
3792 .SM
3793 .B SHELL BUILTIN COMMANDS
3794 for a description of the
3795 .BR nocaseglob ,
3796 .BR nullglob ,
3797 .BR globskipdots ,
3798 .BR failglob ,
3799 and
3800 .B dotglob
3801 shell options.
3802 .PP
3803 The
3804 .SM
3805 .B GLOBIGNORE
3806 shell variable may be used to restrict the set of file names matching a
3807 .IR pattern .
3808 If
3809 .SM
3810 .B GLOBIGNORE
3811 is set, each matching file name that also matches one of the patterns in
3812 .SM
3813 .B GLOBIGNORE
3814 is removed from the list of matches.
3815 If the \fBnocaseglob\fP option is set, the matching against the patterns in
3816 .SM
3817 .B GLOBIGNORE
3818 is performed without regard to case.
3819 The filenames
3820 .B ``.''
3821 and
3822 .B ``..''
3823 are always ignored when
3824 .SM
3825 .B GLOBIGNORE
3826 is set and not null. However, setting
3827 .SM
3828 .B GLOBIGNORE
3829 to a non-null value has the effect of enabling the
3830 .B dotglob
3831 shell option, so all other filenames beginning with a
3832 .B ``.''
3833 will match.
3834 To get the old behavior of ignoring filenames beginning with a
3835 .BR ``.'' ,
3836 make
3837 .B ``.*''
3838 one of the patterns in
3839 .SM
3840 .BR GLOBIGNORE .
3841 The
3842 .B dotglob
3843 option is disabled when
3844 .SM
3845 .B GLOBIGNORE
3846 is unset.
3847 The pattern matching honors the setting of the \fBextglob\fP shell
3848 option.
3849 .PP
3850 \fBPattern Matching\fP
3851 .PP
3852 Any character that appears in a pattern, other than the special pattern
3853 characters described below, matches itself. The NUL character may not
3854 occur in a pattern. A backslash escapes the following character; the
3855 escaping backslash is discarded when matching.
3856 The special pattern characters must be quoted if
3857 they are to be matched literally.
3858 .PP
3859 The special pattern characters have the following meanings:
3860 .PP
3861 .PD 0
3862 .RS
3863 .TP
3864 .B *
3865 Matches any string, including the null string.
3866 When the \fBglobstar\fP shell option is enabled, and \fB*\fP is used in
3867 a pathname expansion context, two adjacent \fB*\fPs used as a single
3868 pattern will match all files and zero or more directories and
3869 subdirectories.
3870 If followed by a \fB/\fP, two adjacent \fB*\fPs will match only directories
3871 and subdirectories.
3872 .TP
3873 .B ?
3874 Matches any single character.
3875 .TP
3876 .B [...]
3877 Matches any one of the enclosed characters. A pair of characters
3878 separated by a hyphen denotes a
3879 \fIrange expression\fP;
3880 any character that falls between those two characters, inclusive,
3881 using the current locale's collating sequence and character set,
3882 is matched. If the first character following the
3883 .B [
3884 is a
3885 .B !
3886 or a
3887 .B ^
3888 then any character not enclosed is matched.
3889 The sorting order of characters in range expressions,
3890 and the characters included in the range,
3891 are determined by
3892 the current locale and the values of the
3893 .SM
3894 .B LC_COLLATE
3895 or
3896 .SM
3897 .B LC_ALL
3898 shell variables, if set.
3899 To obtain the traditional interpretation of range expressions, where
3900 .B [a\-d]
3901 is equivalent to
3902 .BR [abcd] ,
3903 set value of the
3904 .B LC_ALL
3905 shell variable to
3906 .BR C ,
3907 or enable the
3908 .B globasciiranges
3909 shell option.
3910 A
3911 .B \-
3912 may be matched by including it as the first or last character
3913 in the set.
3914 A
3915 .B ]
3916 may be matched by including it as the first character
3917 in the set.
3918 .br
3919 .if t .sp 0.5
3920 .if n .sp 1
3921 Within
3922 .B [
3923 and
3924 .BR ] ,
3925 \fIcharacter classes\fP can be specified using the syntax
3926 \fB[:\fP\fIclass\fP\fB:]\fP, where \fIclass\fP is one of the
3927 following classes defined in the POSIX standard:
3928 .PP
3929 .RS
3930 .B
3931 .if n alnum alpha ascii blank cntrl digit graph lower print punct space upper word xdigit
3932 .if t alnum alpha ascii blank cntrl digit graph lower print punct space upper word xdigit
3933 .br
3934 A character class matches any character belonging to that class.
3935 The \fBword\fP character class matches letters, digits, and the character _.
3936 .br
3937 .if t .sp 0.5
3938 .if n .sp 1
3939 Within
3940 .B [
3941 and
3942 .BR ] ,
3943 an \fIequivalence class\fP can be specified using the syntax
3944 \fB[=\fP\fIc\fP\fB=]\fP, which matches all characters with the
3945 same collation weight (as defined by the current locale) as
3946 the character \fIc\fP.
3947 .br
3948 .if t .sp 0.5
3949 .if n .sp 1
3950 Within
3951 .B [
3952 and
3953 .BR ] ,
3954 the syntax \fB[.\fP\fIsymbol\fP\fB.]\fP matches the collating symbol
3955 \fIsymbol\fP.
3956 .RE
3957 .RE
3958 .PD
3959 .PP
3960 If the \fBextglob\fP shell option is enabled using the \fBshopt\fP
3961 builtin, the shell recognizes several extended pattern matching operators.
3962 In the following description, a \fIpattern-list\fP is a list of one
3963 or more patterns separated by a \fB|\fP.
3964 Composite patterns may be formed using one or more of the following
3965 sub-patterns:
3966 .sp 1
3967 .PD 0
3968 .RS
3969 .TP
3970 \fB?(\fP\^\fIpattern-list\^\fP\fB)\fP
3971 Matches zero or one occurrence of the given patterns
3972 .TP
3973 \fB*(\fP\^\fIpattern-list\^\fP\fB)\fP
3974 Matches zero or more occurrences of the given patterns
3975 .TP
3976 \fB+(\fP\^\fIpattern-list\^\fP\fB)\fP
3977 Matches one or more occurrences of the given patterns
3978 .TP
3979 \fB@(\fP\^\fIpattern-list\^\fP\fB)\fP
3980 Matches one of the given patterns
3981 .TP
3982 \fB!(\fP\^\fIpattern-list\^\fP\fB)\fP
3983 Matches anything except one of the given patterns
3984 .RE
3985 .PD
3986 .PP
3987 The\fBextglob\fP option changes the behavior of the parser, since the
3988 parentheses are normally treated as operators with syntactic meaning.
3989 To ensure that extended matching patterns are parsed correctly, make sure
3990 that \fBextglob\fP is enabled before parsing constructs containing the
3991 patterns, including shell functions and command substitutions.
3992 .PP
3993 When matching filenames, the \fBdotglob\fP shell option determines
3994 the set of filenames that are tested:
3995 when \fBdotglob\fP is enabled, the set of filenames includes all files
3996 beginning with ``.'', but ``.'' and ``..'' must be matched by a
3997 pattern or sub-pattern that begins with a dot;
3998 when it is disabled, the set does not
3999 include any filenames beginning with ``.'' unless the pattern
4000 or sub-pattern begins with a ``.''.
4001 As above, ``.'' only has a special meaning when matching filenames.
4002 .PP
4003 Complicated extended pattern matching against long strings is slow,
4004 especially when the patterns contain alternations and the strings
4005 contain multiple matches.
4006 Using separate matches against shorter strings, or using arrays of
4007 strings instead of a single long string, may be faster.
4008 .SS Quote Removal
4009 After the preceding expansions, all unquoted occurrences of the
4010 characters
4011 .BR \e ,
4012 .BR \(aq ,
4013 and \^\f3"\fP\^ that did not result from one of the above
4014 expansions are removed.
4015 .SH REDIRECTION
4016 Before a command is executed, its input and output
4017 may be
4018 .I redirected
4019 using a special notation interpreted by the shell.
4020 \fIRedirection\fP allows commands' file handles to be
4021 duplicated, opened, closed,
4022 made to refer to different files,
4023 and can change the files the command reads from and writes to.
4024 Redirection may also be used to modify file handles in the
4025 current shell execution environment.
4026 The following redirection
4027 operators may precede or appear anywhere within a
4028 .I simple command
4029 or may follow a
4030 .IR command .
4031 Redirections are processed in the order they appear, from
4032 left to right.
4033 .PP
4034 Each redirection that may be preceded by a file descriptor number
4035 may instead be preceded by a word of the form {\fIvarname\fP}.
4036 In this case, for each redirection operator except
4037 >&- and <&-, the shell will allocate a file descriptor greater
4038 than or equal to 10 and assign it to \fIvarname\fP.
4039 If >&- or <&- is preceded
4040 by {\fIvarname\fP}, the value of \fIvarname\fP defines the file
4041 descriptor to close.
4042 If {\fIvarname\fP} is supplied, the redirection persists beyond
4043 the scope of the command, allowing the shell programmer to manage
4044 the file descriptor's lifetime manually.
4045 The \fBvarredir_close\fP shell option manages this behavior.
4046 .PP
4047 In the following descriptions, if the file descriptor number is
4048 omitted, and the first character of the redirection operator is
4049 .BR < ,
4050 the redirection refers to the standard input (file descriptor
4051 0). If the first character of the redirection operator is
4052 .BR > ,
4053 the redirection refers to the standard output (file descriptor
4054 1).
4055 .PP
4056 The word following the redirection operator in the following
4057 descriptions, unless otherwise noted, is subjected to
4058 brace expansion, tilde expansion, parameter and variable expansion,
4059 command substitution, arithmetic expansion, quote removal,
4060 pathname expansion, and word splitting.
4061 If it expands to more than one word,
4062 .B bash
4063 reports an error.
4064 .PP
4065 Note that the order of redirections is significant. For example,
4066 the command
4067 .RS
4068 .PP
4069 ls \fB>\fP dirlist 2\fB>&\fP1
4070 .RE
4071 .PP
4072 directs both standard output and standard error to the file
4073 .IR dirlist ,
4074 while the command
4075 .RS
4076 .PP
4077 ls 2\fB>&\fP1 \fB>\fP dirlist
4078 .RE
4079 .PP
4080 directs only the standard output to file
4081 .IR dirlist ,
4082 because the standard error was duplicated from the standard output
4083 before the standard output was redirected to
4084 .IR dirlist .
4085 .PP
4086 \fBBash\fP handles several filenames specially when they are used in
4087 redirections, as described in the following table.
4088 If the operating system on which \fBbash\fP is running provides these
4089 special files, bash will use them; otherwise it will emulate them
4090 internally with the behavior described below.
4091 .RS
4092 .PP
4093 .PD 0
4094 .TP
4095 .B /dev/fd/\fIfd\fP
4096 If \fIfd\fP is a valid integer, file descriptor \fIfd\fP is duplicated.
4097 .TP
4098 .B /dev/stdin
4099 File descriptor 0 is duplicated.
4100 .TP
4101 .B /dev/stdout
4102 File descriptor 1 is duplicated.
4103 .TP
4104 .B /dev/stderr
4105 File descriptor 2 is duplicated.
4106 .TP
4107 .B /dev/tcp/\fIhost\fP/\fIport\fP
4108 If \fIhost\fP is a valid hostname or Internet address, and \fIport\fP
4109 is an integer port number or service name, \fBbash\fP attempts to open
4110 the corresponding TCP socket.
4111 .TP
4112 .B /dev/udp/\fIhost\fP/\fIport\fP
4113 If \fIhost\fP is a valid hostname or Internet address, and \fIport\fP
4114 is an integer port number or service name, \fBbash\fP attempts to open
4115 the corresponding UDP socket.
4116 .PD
4117 .RE
4118 .PP
4119 A failure to open or create a file causes the redirection to fail.
4120 .PP
4121 Redirections using file descriptors greater than 9 should be used with
4122 care, as they may conflict with file descriptors the shell uses
4123 internally.
4124 .SS Redirecting Input
4125 Redirection of input causes the file whose name results from
4126 the expansion of
4127 .I word
4128 to be opened for reading on file descriptor
4129 .IR n ,
4130 or the standard input (file descriptor 0) if
4131 .I n
4132 is not specified.
4133 .PP
4134 The general format for redirecting input is:
4135 .RS
4136 .PP
4137 [\fIn\fP]\fB<\fP\fIword\fP
4138 .RE
4139 .SS Redirecting Output
4140 Redirection of output causes the file whose name results from
4141 the expansion of
4142 .I word
4143 to be opened for writing on file descriptor
4144 .IR n ,
4145 or the standard output (file descriptor 1) if
4146 .I n
4147 is not specified. If the file does not exist it is created;
4148 if it does exist it is truncated to zero size.
4149 .PP
4150 The general format for redirecting output is:
4151 .RS
4152 .PP
4153 [\fIn\fP]\fB>\fP\fIword\fP
4154 .RE
4155 .PP
4156 If the redirection operator is
4157 .BR > ,
4158 and the
4159 .B noclobber
4160 option to the
4161 .B set
4162 builtin has been enabled, the redirection will fail if the file
4163 whose name results from the expansion of \fIword\fP exists and is
4164 a regular file.
4165 If the redirection operator is
4166 .BR >| ,
4167 or the redirection operator is
4168 .B >
4169 and the
4170 .B noclobber
4171 option to the
4172 .B set
4173 builtin command is not enabled, the redirection is attempted even
4174 if the file named by \fIword\fP exists.
4175 .SS Appending Redirected Output
4176 Redirection of output in this fashion
4177 causes the file whose name results from
4178 the expansion of
4179 .I word
4180 to be opened for appending on file descriptor
4181 .IR n ,
4182 or the standard output (file descriptor 1) if
4183 .I n
4184 is not specified. If the file does not exist it is created.
4185 .PP
4186 The general format for appending output is:
4187 .RS
4188 .PP
4189 [\fIn\fP]\fB>>\fP\fIword\fP
4190 .RE
4191 .SS Redirecting Standard Output and Standard Error
4192 This construct allows both the
4193 standard output (file descriptor 1) and
4194 the standard error output (file descriptor 2)
4195 to be redirected to the file whose name is the
4196 expansion of
4197 .IR word .
4198 .PP
4199 There are two formats for redirecting standard output and
4200 standard error:
4201 .RS
4202 .PP
4203 \fB&>\fP\fIword\fP
4204 .RE
4205 and
4206 .RS
4207 \fB>&\fP\fIword\fP
4208 .RE
4209 .PP
4210 Of the two forms, the first is preferred.
4211 This is semantically equivalent to
4212 .RS
4213 .PP
4214 \fB>\fP\fIword\fP 2\fB>&\fP1
4215 .RE
4216 .PP
4217 When using the second form, \fIword\fP may not expand to a number or
4218 \fB\-\fP. If it does, other redirection operators apply
4219 (see \fBDuplicating File Descriptors\fP below) for compatibility
4220 reasons.
4221 .SS Appending Standard Output and Standard Error
4222 This construct allows both the
4223 standard output (file descriptor 1) and
4224 the standard error output (file descriptor 2)
4225 to be appended to the file whose name is the
4226 expansion of
4227 .IR word .
4228 .PP
4229 The format for appending standard output and standard error is:
4230 .RS
4231 .PP
4232 \fB&>>\fP\fIword\fP
4233 .RE
4234 .PP
4235 This is semantically equivalent to
4236 .RS
4237 .PP
4238 \fB>>\fP\fIword\fP 2\fB>&\fP1
4239 .RE
4240 .PP
4241 (see \fBDuplicating File Descriptors\fP below).
4242 .SS Here Documents
4243 This type of redirection instructs the shell to read input from the
4244 current source until a line containing only
4245 .I delimiter
4246 (with no trailing blanks)
4247 is seen. All of
4248 the lines read up to that point are then used as the standard
4249 input (or file descriptor \fIn\fP if \fIn\fP is specified) for a command.
4250 .PP
4251 The format of here-documents is:
4252 .RS
4253 .PP
4254 .nf
4255 [\fIn\fP]\fB<<\fP[\fB\-\fP]\fIword\fP
4256 \fIhere-document\fP
4257 \fIdelimiter\fP
4258 .fi
4259 .RE
4260 .PP
4261 No parameter and variable expansion, command substitution,
4262 arithmetic expansion, or pathname expansion is performed on
4263 .IR word .
4264 If any part of
4265 .I word
4266 is quoted, the
4267 .I delimiter
4268 is the result of quote removal on
4269 .IR word ,
4270 and the lines in the here-document are not expanded.
4271 If \fIword\fP is unquoted,
4272 all lines of the here-document are subjected to
4273 parameter expansion, command substitution, and arithmetic expansion,
4274 the character sequence
4275 .B \e<newline>
4276 is ignored, and
4277 .B \e
4278 must be used to quote the characters
4279 .BR \e ,
4280 .BR $ ,
4281 and
4282 .BR \` .
4283 .PP
4284 If the redirection operator is
4285 .BR <<\- ,
4286 then all leading tab characters are stripped from input lines and the
4287 line containing
4288 .IR delimiter .
4289 This allows
4290 here-documents within shell scripts to be indented in a
4291 natural fashion.
4292 .SS "Here Strings"
4293 A variant of here documents, the format is:
4294 .RS
4295 .PP
4296 .nf
4297 [\fIn\fP]\fB<<<\fP\fIword\fP
4298 .fi
4299 .RE
4300 .PP
4301 The \fIword\fP undergoes
4302 tilde expansion, parameter and variable expansion,
4303 command substitution, arithmetic expansion, and quote removal.
4304 Pathname expansion and word splitting are not performed.
4305 The result is supplied as a single string, with a newline appended,
4306 to the command on its
4307 standard input (or file descriptor \fIn\fP if \fIn\fP is specified).
4308 .SS "Duplicating File Descriptors"
4309 The redirection operator
4310 .RS
4311 .PP
4312 [\fIn\fP]\fB<&\fP\fIword\fP
4313 .RE
4314 .PP
4315 is used to duplicate input file descriptors.
4316 If
4317 .I word
4318 expands to one or more digits, the file descriptor denoted by
4319 .I n
4320 is made to be a copy of that file descriptor.
4321 If the digits in
4322 .I word
4323 do not specify a file descriptor open for input, a redirection error occurs.
4324 If
4325 .I word
4326 evaluates to
4327 .BR \- ,
4328 file descriptor
4329 .I n
4330 is closed. If
4331 .I n
4332 is not specified, the standard input (file descriptor 0) is used.
4333 .PP
4334 The operator
4335 .RS
4336 .PP
4337 [\fIn\fP]\fB>&\fP\fIword\fP
4338 .RE
4339 .PP
4340 is used similarly to duplicate output file descriptors. If
4341 .I n
4342 is not specified, the standard output (file descriptor 1) is used.
4343 If the digits in
4344 .I word
4345 do not specify a file descriptor open for output, a redirection error occurs.
4346 If
4347 .I word
4348 evaluates to
4349 .BR \- ,
4350 file descriptor
4351 .I n
4352 is closed.
4353 As a special case, if \fIn\fP is omitted, and \fIword\fP does not
4354 expand to one or more digits or \fB\-\fP, the standard output and standard
4355 error are redirected as described previously.
4356 .SS "Moving File Descriptors"
4357 The redirection operator
4358 .RS
4359 .PP
4360 [\fIn\fP]\fB<&\fP\fIdigit\fP\fB\-\fP
4361 .RE
4362 .PP
4363 moves the file descriptor \fIdigit\fP to file descriptor
4364 .IR n ,
4365 or the standard input (file descriptor 0) if \fIn\fP is not specified.
4366 \fIdigit\fP is closed after being duplicated to \fIn\fP.
4367 .PP
4368 Similarly, the redirection operator
4369 .RS
4370 .PP
4371 [\fIn\fP]\fB>&\fP\fIdigit\fP\fB\-\fP
4372 .RE
4373 .PP
4374 moves the file descriptor \fIdigit\fP to file descriptor
4375 .IR n ,
4376 or the standard output (file descriptor 1) if \fIn\fP is not specified.
4377 .SS "Opening File Descriptors for Reading and Writing"
4378 The redirection operator
4379 .RS
4380 .PP
4381 [\fIn\fP]\fB<>\fP\fIword\fP
4382 .RE
4383 .PP
4384 causes the file whose name is the expansion of
4385 .I word
4386 to be opened for both reading and writing on file descriptor
4387 .IR n ,
4388 or on file descriptor 0 if
4389 .I n
4390 is not specified. If the file does not exist, it is created.
4391 .SH ALIASES
4392 \fIAliases\fP allow a string to be substituted for a word when it is used
4393 as the first word of a simple command.
4394 The shell maintains a list of aliases that may be set and unset with the
4395 .B alias
4396 and
4397 .B unalias
4398 builtin commands (see
4399 .SM
4400 .B SHELL BUILTIN COMMANDS
4401 below).
4402 The first word of each simple command, if unquoted,
4403 is checked to see if it has an
4404 alias. If so, that word is replaced by the text of the alias.
4405 The characters \fB/\fP, \fB$\fP, \fB\`\fP, and \fB=\fP and
4406 any of the shell \fImetacharacters\fP or quoting characters
4407 listed above may not appear in an alias name.
4408 The replacement text may contain any valid shell input,
4409 including shell metacharacters.
4410 The first word of the replacement text is tested
4411 for aliases, but a word that is identical to an alias being expanded
4412 is not expanded a second time.
4413 This means that one may alias
4414 .B ls
4415 to
4416 .BR "ls \-F" ,
4417 for instance, and
4418 .B bash
4419 does not try to recursively expand the replacement text.
4420 If the last character of the alias value is a
4421 .IR blank ,
4422 then the next command
4423 word following the alias is also checked for alias expansion.
4424 .PP
4425 Aliases are created and listed with the
4426 .B alias
4427 command, and removed with the
4428 .B unalias
4429 command.
4430 .PP
4431 There is no mechanism for using arguments in the replacement text.
4432 If arguments are needed, use a shell function (see
4433 .SM
4434 .B FUNCTIONS
4435 below).
4436 .PP
4437 Aliases are not expanded when the shell is not interactive, unless
4438 the
4439 .B expand_aliases
4440 shell option is set using
4441 .B shopt
4442 (see the description of
4443 .B shopt
4444 under
4445 .SM
4446 \fBSHELL BUILTIN COMMANDS\fP
4447 below).
4448 .PP
4449 The rules concerning the definition and use of aliases are
4450 somewhat confusing.
4451 .B Bash
4452 always reads at least one complete line of input,
4453 and all lines that make up a compound command,
4454 before executing any of the commands on that line or the compound command.
4455 Aliases are expanded when a
4456 command is read, not when it is executed. Therefore, an
4457 alias definition appearing on the same line as another
4458 command does not take effect until the next line of input is read.
4459 The commands following the alias definition
4460 on that line are not affected by the new alias.
4461 This behavior is also an issue when functions are executed.
4462 Aliases are expanded when a function definition is read,
4463 not when the function is executed, because a function definition
4464 is itself a command. As a consequence, aliases
4465 defined in a function are not available until after that
4466 function is executed. To be safe, always put
4467 alias definitions on a separate line, and do not use
4468 .B alias
4469 in compound commands.
4470 .PP
4471 For almost every purpose, aliases are superseded by
4472 shell functions.
4473 .SH FUNCTIONS
4474 A shell function, defined as described above under
4475 .SM
4476 .BR "SHELL GRAMMAR" ,
4477 stores a series of commands for later execution.
4478 When the name of a shell function is used as a simple command name,
4479 the list of commands associated with that function name is executed.
4480 Functions are executed in the context of the
4481 current shell; no new process is created to interpret
4482 them (contrast this with the execution of a shell script).
4483 When a function is executed, the arguments to the
4484 function become the positional parameters
4485 during its execution.
4486 The special parameter
4487 .B #
4488 is updated to reflect the change. Special parameter \fB0\fP
4489 is unchanged.
4490 The first element of the
4491 .SM
4492 .B FUNCNAME
4493 variable is set to the name of the function while the function
4494 is executing.
4495 .PP
4496 All other aspects of the shell execution
4497 environment are identical between a function and its caller
4498 with these exceptions: the
4499 .SM
4500 .B DEBUG
4501 and
4502 .B RETURN
4503 traps (see the description of the
4504 .B trap
4505 builtin under
4506 .SM
4507 .B SHELL BUILTIN COMMANDS
4508 below) are not inherited unless the function has been given the
4509 \fBtrace\fP attribute (see the description of the
4510 .SM
4511 .B declare
4512 builtin below) or the
4513 \fB\-o functrace\fP shell option has been enabled with
4514 the \fBset\fP builtin
4515 (in which case all functions inherit the \fBDEBUG\fP and \fBRETURN\fP traps),
4516 and the
4517 .SM
4518 .B ERR
4519 trap is not inherited unless the \fB\-o errtrace\fP shell option has
4520 been enabled.
4521 .PP
4522 Variables local to the function may be declared with the
4523 .B local
4524 builtin command (\fIlocal variables\fP).
4525 Ordinarily, variables and their values
4526 are shared between the function and its caller.
4527 If a variable is declared \fBlocal\fP, the variable's visible scope
4528 is restricted to that function and its children (including the functions
4529 it calls).
4530 .PP
4531 In the following description, the \fIcurrent scope\fP is a currently-
4532 executing function.
4533 Previous scopes consist of that function's caller and so on,
4534 back to the "global" scope, where the shell is not executing
4535 any shell function.
4536 Consequently, a local variable at the current scope is a variable
4537 declared using the \fBlocal\fP or \fBdeclare\fP builtins in the
4538 function that is currently executing.
4539 .PP
4540 Local variables "shadow" variables with the same name declared at
4541 previous scopes.
4542 For instance, a local variable declared in a function
4543 hides a global variable of the same name: references and assignments
4544 refer to the local variable, leaving the global variable unmodified.
4545 When the function returns, the global variable is once again visible.
4546 .PP
4547 The shell uses \fIdynamic scoping\fP to control a variable's visibility
4548 within functions.
4549 With dynamic scoping, visible variables and their values
4550 are a result of the sequence of function calls that caused execution
4551 to reach the current function.
4552 The value of a variable that a function sees depends
4553 on its value within its caller, if any, whether that caller is
4554 the "global" scope or another shell function.
4555 This is also the value that a local variable
4556 declaration "shadows", and the value that is restored when the function
4557 returns.
4558 .PP
4559 For example, if a variable \fIvar\fP is declared as local in function
4560 \fIfunc1\fP, and \fIfunc1\fP calls another function \fIfunc2\fP,
4561 references to \fIvar\fP made from within \fIfunc2\fP will resolve to the
4562 local variable \fIvar\fP from \fIfunc1\fP, shadowing any global variable
4563 named \fIvar\fP.
4564 .PP
4565 The \fBunset\fP builtin also acts using the same dynamic scope: if a
4566 variable is local to the current scope, \fBunset\fP will unset it;
4567 otherwise the unset will refer to the variable found in any calling scope
4568 as described above.
4569 If a variable at the current local scope is unset, it will remain so
4570 (appearing as unset)
4571 until it is reset in that scope or until the function returns.
4572 Once the function returns, any instance of the variable at a previous
4573 scope will become visible.
4574 If the unset acts on a variable at a previous scope, any instance of a
4575 variable with that name that had been shadowed will become visible
4576 (see below how the \fBlocalvar_unset\fP shell option changes this behavior).
4577 .PP
4578 The \fBFUNCNEST\fP variable, if set to a numeric value greater
4579 than 0, defines a maximum function nesting level. Function
4580 invocations that exceed the limit cause the entire command to
4581 abort.
4582 .PP
4583 If the builtin command
4584 .B return
4585 is executed in a function, the function completes and
4586 execution resumes with the next command after the function
4587 call.
4588 Any command associated with the \fBRETURN\fP trap is executed
4589 before execution resumes.
4590 When a function completes, the values of the
4591 positional parameters and the special parameter
4592 .B #
4593 are restored to the values they had prior to the function's
4594 execution.
4595 .PP
4596 Function names and definitions may be listed with the
4597 .B \-f
4598 option to the
4599 .B declare
4600 or
4601 .B typeset
4602 builtin commands. The
4603 .B \-F
4604 option to
4605 .B declare
4606 or
4607 .B typeset
4608 will list the function names only
4609 (and optionally the source file and line number, if the \fBextdebug\fP
4610 shell option is enabled).
4611 Functions may be exported so that child shell processes
4612 (those created when executing a separate shell invocation)
4613 automatically have them defined with the
4614 .B \-f
4615 option to the
4616 .B export
4617 builtin.
4618 A function definition may be deleted using the \fB\-f\fP option to
4619 the
4620 .B unset
4621 builtin.
4622 .PP
4623 Functions may be recursive.
4624 The \fBFUNCNEST\fP variable may be used to limit the depth of the
4625 function call stack and restrict the number of function invocations.
4626 By default, no limit is imposed on the number of recursive calls.
4627 .SH "ARITHMETIC EVALUATION"
4628 The shell allows arithmetic expressions to be evaluated, under
4629 certain circumstances (see the \fBlet\fP and \fBdeclare\fP builtin
4630 commands, the \fB((\fP compound command, and \fBArithmetic Expansion\fP).
4631 Evaluation is done in fixed-width integers with no check for overflow,
4632 though division by 0 is trapped and flagged as an error.
4633 The operators and their precedence, associativity, and values
4634 are the same as in the C language.
4635 The following list of operators is grouped into levels of
4636 equal-precedence operators.
4637 The levels are listed in order of decreasing precedence.
4638 .PP
4639 .PD 0
4640 .TP
4641 .B \fIid\fP++ \fIid\fP\-\-
4642 variable post-increment and post-decrement
4643 .TP
4644 .B \- +
4645 unary minus and plus
4646 .TP
4647 .B ++\fIid\fP \-\-\fIid\fP
4648 variable pre-increment and pre-decrement
4649 .TP
4650 .B ! ~
4651 logical and bitwise negation
4652 .TP
4653 .B **
4654 exponentiation
4655 .TP
4656 .B * / %
4657 multiplication, division, remainder
4658 .TP
4659 .B + \-
4660 addition, subtraction
4661 .TP
4662 .B << >>
4663 left and right bitwise shifts
4664 .TP
4665 .B <= >= < >
4666 comparison
4667 .TP
4668 .B == !=
4669 equality and inequality
4670 .TP
4671 .B &
4672 bitwise AND
4673 .TP
4674 .B ^
4675 bitwise exclusive OR
4676 .TP
4677 .B |
4678 bitwise OR
4679 .TP
4680 .B &&
4681 logical AND
4682 .TP
4683 .B ||
4684 logical OR
4685 .TP
4686 .B \fIexpr\fP?\fIexpr\fP:\fIexpr\fP
4687 conditional operator
4688 .TP
4689 .B = *= /= %= += \-= <<= >>= &= ^= |=
4690 assignment
4691 .TP
4692 .B \fIexpr1\fP , \fIexpr2\fP
4693 comma
4694 .PD
4695 .PP
4696 Shell variables are allowed as operands; parameter expansion is
4697 performed before the expression is evaluated.
4698 Within an expression, shell variables may also be referenced by name
4699 without using the parameter expansion syntax.
4700 A shell variable that is null or unset evaluates to 0 when referenced
4701 by name without using the parameter expansion syntax.
4702 The value of a variable is evaluated as an arithmetic expression
4703 when it is referenced, or when a variable which has been given the
4704 \fIinteger\fP attribute using \fBdeclare \-i\fP is assigned a value.
4705 A null value evaluates to 0.
4706 A shell variable need not have its \fIinteger\fP attribute
4707 turned on to be used in an expression.
4708 .PP
4709 Integer constants follow the C language definition, without suffixes or
4710 character constants.
4711 Constants with a leading 0 are interpreted as octal numbers.
4712 A leading 0x or 0X denotes hexadecimal.
4713 Otherwise, numbers take the form [\fIbase#\fP]n, where the optional \fIbase\fP
4714 is a decimal number between 2 and 64 representing the arithmetic
4715 base, and \fIn\fP is a number in that base.
4716 If \fIbase#\fP is omitted, then base 10 is used.
4717 When specifying \fIn\fP,
4718 if a non-digit is required,
4719 the digits greater than 9 are represented by the lowercase letters,
4720 the uppercase letters, @, and _, in that order.
4721 If \fIbase\fP is less than or equal to 36, lowercase and uppercase
4722 letters may be used interchangeably to represent numbers between 10
4723 and 35.
4724 .PP
4725 Operators are evaluated in order of precedence. Sub-expressions in
4726 parentheses are evaluated first and may override the precedence
4727 rules above.
4728 .SH "CONDITIONAL EXPRESSIONS"
4729 Conditional expressions are used by the \fB[[\fP compound command and
4730 the \fBtest\fP and \fB[\fP builtin commands to test file attributes
4731 and perform string and arithmetic comparisons.
4732 The \fBtest\fP and \fB[\fP commands determine their behavior based on
4733 the number of arguments; see the descriptions of those commands for any
4734 other command-specific actions.
4735 .PP
4736 Expressions are formed from the following unary or binary primaries.
4737 \fBBash\fP handles several filenames specially when they are used in
4738 expressions.
4739 If the operating system on which \fBbash\fP is running provides these
4740 special files, bash will use them; otherwise it will emulate them
4741 internally with this behavior:
4742 If any \fIfile\fP argument to one of the primaries is of the form
4743 \fI/dev/fd/n\fP, then file descriptor \fIn\fP is checked.
4744 If the \fIfile\fP argument to one of the primaries is one of
4745 \fI/dev/stdin\fP, \fI/dev/stdout\fP, or \fI/dev/stderr\fP, file
4746 descriptor 0, 1, or 2, respectively, is checked.
4747 .PP
4748 Unless otherwise specified, primaries that operate on files follow symbolic
4749 links and operate on the target of the link, rather than the link itself.
4750 .if t .sp 0.5
4751 .if n .sp 1
4752 When used with \fB[[\fP, the \fB<\fP and \fB>\fP operators sort
4753 lexicographically using the current locale.
4754 The \fBtest\fP command sorts using ASCII ordering.
4755 .sp 1
4756 .PD 0
4757 .TP
4758 .B \-a \fIfile\fP
4759 True if \fIfile\fP exists.
4760 .TP
4761 .B \-b \fIfile\fP
4762 True if \fIfile\fP exists and is a block special file.
4763 .TP
4764 .B \-c \fIfile\fP
4765 True if \fIfile\fP exists and is a character special file.
4766 .TP
4767 .B \-d \fIfile\fP
4768 True if \fIfile\fP exists and is a directory.
4769 .TP
4770 .B \-e \fIfile\fP
4771 True if \fIfile\fP exists.
4772 .TP
4773 .B \-f \fIfile\fP
4774 True if \fIfile\fP exists and is a regular file.
4775 .TP
4776 .B \-g \fIfile\fP
4777 True if \fIfile\fP exists and is set-group-id.
4778 .TP
4779 .B \-h \fIfile\fP
4780 True if \fIfile\fP exists and is a symbolic link.
4781 .TP
4782 .B \-k \fIfile\fP
4783 True if \fIfile\fP exists and its ``sticky'' bit is set.
4784 .TP
4785 .B \-p \fIfile\fP
4786 True if \fIfile\fP exists and is a named pipe (FIFO).
4787 .TP
4788 .B \-r \fIfile\fP
4789 True if \fIfile\fP exists and is readable.
4790 .TP
4791 .B \-s \fIfile\fP
4792 True if \fIfile\fP exists and has a size greater than zero.
4793 .TP
4794 .B \-t \fIfd\fP
4795 True if file descriptor
4796 .I fd
4797 is open and refers to a terminal.
4798 .TP
4799 .B \-u \fIfile\fP
4800 True if \fIfile\fP exists and its set-user-id bit is set.
4801 .TP
4802 .B \-w \fIfile\fP
4803 True if \fIfile\fP exists and is writable.
4804 .TP
4805 .B \-x \fIfile\fP
4806 True if \fIfile\fP exists and is executable.
4807 .TP
4808 .B \-G \fIfile\fP
4809 True if \fIfile\fP exists and is owned by the effective group id.
4810 .TP
4811 .B \-L \fIfile\fP
4812 True if \fIfile\fP exists and is a symbolic link.
4813 .TP
4814 .B \-N \fIfile\fP
4815 True if \fIfile\fP exists and has been modified since it was last read.
4816 .TP
4817 .B \-O \fIfile\fP
4818 True if \fIfile\fP exists and is owned by the effective user id.
4819 .TP
4820 .B \-S \fIfile\fP
4821 True if \fIfile\fP exists and is a socket.
4822 .TP
4823 \fIfile1\fP \fB\-ef\fP \fIfile2\fP
4824 True if \fIfile1\fP and \fIfile2\fP refer to the same device and
4825 inode numbers.
4826 .TP
4827 \fIfile1\fP \-\fBnt\fP \fIfile2\fP
4828 True if \fIfile1\fP is newer (according to modification date) than \fIfile2\fP,
4829 or if \fIfile1\fP exists and \fPfile2\fP does not.
4830 .TP
4831 \fIfile1\fP \-\fBot\fP \fIfile2\fP
4832 True if \fIfile1\fP is older than \fIfile2\fP, or if \fIfile2\fP exists
4833 and \fIfile1\fP does not.
4834 .TP
4835 .B \-o \fIoptname\fP
4836 True if the shell option
4837 .I optname
4838 is enabled.
4839 See the list of options under the description of the
4840 .B \-o
4841 option to the
4842 .B set
4843 builtin below.
4844 .TP
4845 .B \-v \fIvarname\fP
4846 True if the shell variable
4847 .I varname
4848 is set (has been assigned a value).
4849 .TP
4850 .B \-R \fIvarname\fP
4851 True if the shell variable
4852 .I varname
4853 is set and is a name reference.
4854 .TP
4855 .B \-z \fIstring\fP
4856 True if the length of \fIstring\fP is zero.
4857 .TP
4858 \fIstring\fP
4859 .PD 0
4860 .TP
4861 .B \-n \fIstring\fP
4862 .PD
4863 True if the length of
4864 .I string
4865 is non-zero.
4866 .TP
4867 \fIstring1\fP \fB==\fP \fIstring2\fP
4868 .PD 0
4869 .TP
4870 \fIstring1\fP \fB=\fP \fIstring2\fP
4871 .PD
4872 True if the strings are equal. \fB=\fP should be used
4873 with the \fBtest\fP command for POSIX conformance.
4874 When used with the \fB[[\fP command, this performs pattern matching as
4875 described above (\fBCompound Commands\fP).
4876 .TP
4877 \fIstring1\fP \fB!=\fP \fIstring2\fP
4878 True if the strings are not equal.
4879 .TP
4880 \fIstring1\fP \fB<\fP \fIstring2\fP
4881 True if \fIstring1\fP sorts before \fIstring2\fP lexicographically.
4882 .TP
4883 \fIstring1\fP \fB>\fP \fIstring2\fP
4884 True if \fIstring1\fP sorts after \fIstring2\fP lexicographically.
4885 .TP
4886 .I \fIarg1\fP \fBOP\fP \fIarg2\fP
4887 .SM
4888 .B OP
4889 is one of
4890 .BR \-eq ,
4891 .BR \-ne ,
4892 .BR \-lt ,
4893 .BR \-le ,
4894 .BR \-gt ,
4895 or
4896 .BR \-ge .
4897 These arithmetic binary operators return true if \fIarg1\fP
4898 is equal to, not equal to, less than, less than or equal to,
4899 greater than, or greater than or equal to \fIarg2\fP, respectively.
4900 .I Arg1
4901 and
4902 .I arg2
4903 may be positive or negative integers.
4904 When used with the \fB[[\fP command,
4905 .I Arg1
4906 and
4907 .I Arg2
4908 are evaluated as arithmetic expressions (see
4909 .SM
4910 .B "ARITHMETIC EVALUATION"
4911 above).
4912 .PD
4913 .SH "SIMPLE COMMAND EXPANSION"
4914 When a simple command is executed, the shell performs the following
4915 expansions, assignments, and redirections, from left to right, in
4916 the following order.
4917 .IP 1.
4918 The words that the parser has marked as variable assignments (those
4919 preceding the command name) and redirections are saved for later
4920 processing.
4921 .IP 2.
4922 The words that are not variable assignments or redirections are
4923 expanded. If any words remain after expansion, the first word
4924 is taken to be the name of the command and the remaining words are
4925 the arguments.
4926 .IP 3.
4927 Redirections are performed as described above under
4928 .SM
4929 .BR REDIRECTION .
4930 .IP 4.
4931 The text after the \fB=\fP in each variable assignment undergoes tilde
4932 expansion, parameter expansion, command substitution, arithmetic expansion,
4933 and quote removal before being assigned to the variable.
4934 .PP
4935 If no command name results, the variable assignments affect the current
4936 shell environment.
4937 In the case of such a command (one that consists only of assignment
4938 statements and redirections), assignment statements are performed before
4939 redirections.
4940 Otherwise, the variables are added to the environment
4941 of the executed command and do not affect the current shell environment.
4942 If any of the assignments attempts to assign a value to a readonly variable,
4943 an error occurs, and the command exits with a non-zero status.
4944 .PP
4945 If no command name results, redirections are performed, but do not
4946 affect the current shell environment. A redirection error causes the
4947 command to exit with a non-zero status.
4948 .PP
4949 If there is a command name left after expansion, execution proceeds as
4950 described below. Otherwise, the command exits. If one of the expansions
4951 contained a command substitution, the exit status of the command is
4952 the exit status of the last command substitution performed. If there
4953 were no command substitutions, the command exits with a status of zero.
4954 .SH "COMMAND EXECUTION"
4955 After a command has been split into words, if it results in a
4956 simple command and an optional list of arguments, the following
4957 actions are taken.
4958 .PP
4959 If the command name contains no slashes, the shell attempts to
4960 locate it. If there exists a shell function by that name, that
4961 function is invoked as described above in
4962 .SM
4963 .BR FUNCTIONS .
4964 If the name does not match a function, the shell searches for
4965 it in the list of shell builtins. If a match is found, that
4966 builtin is invoked.
4967 .PP
4968 If the name is neither a shell function nor a builtin,
4969 and contains no slashes,
4970 .B bash
4971 searches each element of the
4972 .SM
4973 .B PATH
4974 for a directory containing an executable file by that name.
4975 .B Bash
4976 uses a hash table to remember the full pathnames of executable
4977 files (see
4978 .B hash
4979 under
4980 .SM
4981 .B "SHELL BUILTIN COMMANDS"
4982 below).
4983 A full search of the directories in
4984 .SM
4985 .B PATH
4986 is performed only if the command is not found in the hash table.
4987 If the search is unsuccessful, the shell searches for a defined shell
4988 function named \fBcommand_not_found_handle\fP.
4989 If that function exists, it is invoked in a separate execution environment
4990 with the original command and
4991 the original command's arguments as its arguments, and the function's
4992 exit status becomes the exit status of that subshell.
4993 If that function is not defined, the shell prints an error
4994 message and returns an exit status of 127.
4995 .PP
4996 If the search is successful, or if the command name contains
4997 one or more slashes, the shell executes the named program in a
4998 separate execution environment.
4999 Argument 0 is set to the name given, and the remaining arguments
5000 to the command are set to the arguments given, if any.
5001 .PP
5002 If this execution fails because the file is not in executable
5003 format, and the file is not a directory, it is assumed to be
5004 a \fIshell script\fP, a file
5005 containing shell commands, and the shell creates a
5006 new instance of itself
5007 to execute it.
5008 This subshell reinitializes itself, so
5009 that the effect is as if a new shell had been invoked
5010 to handle the script, with the exception that the locations of
5011 commands remembered by the parent (see
5012 .B hash
5013 below under
5014 .SM
5015 \fBSHELL BUILTIN COMMANDS\fP)
5016 are retained by the child.
5017 .PP
5018 If the program is a file beginning with
5019 .BR #! ,
5020 the remainder of the first line specifies an interpreter
5021 for the program. The shell executes the
5022 specified interpreter on operating systems that do not
5023 handle this executable format themselves. The arguments to the
5024 interpreter consist of a single optional argument following the
5025 interpreter name on the first line of the program, followed
5026 by the name of the program, followed by the command
5027 arguments, if any.
5028 .SH COMMAND EXECUTION ENVIRONMENT
5029 The shell has an \fIexecution environment\fP, which consists of the
5030 following:
5031 .IP \(bu
5032 open files inherited by the shell at invocation, as modified by
5033 redirections supplied to the \fBexec\fP builtin
5034 .IP \(bu
5035 the current working directory as set by \fBcd\fP, \fBpushd\fP, or
5036 \fBpopd\fP, or inherited by the shell at invocation
5037 .IP \(bu
5038 the file creation mode mask as set by \fBumask\fP or inherited from
5039 the shell's parent
5040 .IP \(bu
5041 current traps set by \fBtrap\fP
5042 .IP \(bu
5043 shell parameters that are set by variable assignment or with \fBset\fP
5044 or inherited from the shell's parent in the environment
5045 .IP \(bu
5046 shell functions defined during execution or inherited from the shell's
5047 parent in the environment
5048 .IP \(bu
5049 options enabled at invocation (either by default or with command-line
5050 arguments) or by \fBset\fP
5051 .IP \(bu
5052 options enabled by \fBshopt\fP
5053 .IP \(bu
5054 shell aliases defined with \fBalias\fP
5055 .IP \(bu
5056 various process IDs, including those of background jobs, the value
5057 of \fB$$\fP, and the value of
5058 .SM
5059 .B PPID
5060 .PP
5061 When a simple command other than a builtin or shell function
5062 is to be executed, it
5063 is invoked in a separate execution environment that consists of
5064 the following.
5065 Unless otherwise noted, the values are inherited from the shell.
5066 .if n .sp 1
5067 .IP \(bu
5068 the shell's open files, plus any modifications and additions specified
5069 by redirections to the command
5070 .IP \(bu
5071 the current working directory
5072 .IP \(bu
5073 the file creation mode mask
5074 .IP \(bu
5075 shell variables and functions marked for export, along with variables
5076 exported for the command, passed in the environment
5077 .IP \(bu
5078 traps caught by the shell are reset to the values inherited from the
5079 shell's parent, and traps ignored by the shell are ignored
5080 .PP
5081 A command invoked in this separate environment cannot affect the
5082 shell's execution environment.
5083 .PP
5084 A \fIsubshell\fP is a copy of the shell process.
5085 .PP
5086 Command substitution, commands grouped with parentheses,
5087 and asynchronous commands are invoked in a
5088 subshell environment that is a duplicate of the shell environment,
5089 except that traps caught by the shell are reset to the values
5090 that the shell inherited from its parent at invocation. Builtin
5091 commands that are invoked as part of a pipeline are also executed in a
5092 subshell environment. Changes made to the subshell environment
5093 cannot affect the shell's execution environment.
5094 .PP
5095 Subshells spawned to execute command substitutions inherit the value of
5096 the \fB\-e\fP option from the parent shell. When not in \fIposix mode\fP,
5097 \fBbash\fP clears the \fB\-e\fP option in such subshells.
5098 .PP
5099 If a command is followed by a \fB&\fP and job control is not active, the
5100 default standard input for the command is the empty file \fI/dev/null\fP.
5101 Otherwise, the invoked command inherits the file descriptors of the calling
5102 shell as modified by redirections.
5103 .SH ENVIRONMENT
5104 When a program is invoked it is given an array of strings
5105 called the
5106 .IR environment .
5107 This is a list of
5108 \fIname\fP\-\fIvalue\fP pairs, of the form
5109 .IR "name\fR=\fPvalue" .
5110 .PP
5111 The shell provides several ways to manipulate the environment.
5112 On invocation, the shell scans its own environment and
5113 creates a parameter for each name found, automatically marking
5114 it for
5115 .I export
5116 to child processes. Executed commands inherit the environment.
5117 The
5118 .B export
5119 and
5120 .B declare \-x
5121 commands allow parameters and functions to be added to and
5122 deleted from the environment. If the value of a parameter
5123 in the environment is modified, the new value becomes part
5124 of the environment, replacing the old. The environment
5125 inherited by any executed command consists of the shell's
5126 initial environment, whose values may be modified in the shell,
5127 less any pairs removed by the
5128 .B unset
5129 command, plus any additions via the
5130 .B export
5131 and
5132 .B declare \-x
5133 commands.
5134 .PP
5135 The environment for any
5136 .I simple command
5137 or function may be augmented temporarily by prefixing it with
5138 parameter assignments, as described above in
5139 .SM
5140 .BR PARAMETERS .
5141 These assignment statements affect only the environment seen
5142 by that command.
5143 .PP
5144 If the
5145 .B \-k
5146 option is set (see the
5147 .B set
5148 builtin command below), then
5149 .I all
5150 parameter assignments are placed in the environment for a command,
5151 not just those that precede the command name.
5152 .PP
5153 When
5154 .B bash
5155 invokes an external command, the variable
5156 .B _
5157 is set to the full filename of the command and passed to that
5158 command in its environment.
5159 .SH "EXIT STATUS"
5160 The exit status of an executed command is the value returned by the
5161 \fIwaitpid\fP system call or equivalent function. Exit statuses
5162 fall between 0 and 255, though, as explained below, the shell may
5163 use values above 125 specially. Exit statuses from shell builtins and
5164 compound commands are also limited to this range. Under certain
5165 circumstances, the shell will use special values to indicate specific
5166 failure modes.
5167 .PP
5168 For the shell's purposes, a command which exits with a
5169 zero exit status has succeeded. An exit status of zero
5170 indicates success. A non-zero exit status indicates failure.
5171 When a command terminates on a fatal signal \fIN\fP, \fBbash\fP uses
5172 the value of 128+\fIN\fP as the exit status.
5173 .PP
5174 If a command is not found, the child process created to
5175 execute it returns a status of 127. If a command is found
5176 but is not executable, the return status is 126.
5177 .PP
5178 If a command fails because of an error during expansion or redirection,
5179 the exit status is greater than zero.
5180 .PP
5181 Shell builtin commands return a status of 0 (\fItrue\fP) if
5182 successful, and non-zero (\fIfalse\fP) if an error occurs
5183 while they execute.
5184 All builtins return an exit status of 2 to indicate incorrect usage,
5185 generally invalid options or missing arguments.
5186 .PP
5187 The exit status of the last command is available in the special
5188 parameter $?.
5189 .PP
5190 \fBBash\fP itself returns the exit status of the last command
5191 executed, unless a syntax error occurs, in which case it exits
5192 with a non-zero value. See also the \fBexit\fP builtin
5193 command below.
5194 .SH SIGNALS
5195 When \fBbash\fP is interactive, in the absence of any traps, it ignores
5196 .SM
5197 .B SIGTERM
5198 (so that \fBkill 0\fP does not kill an interactive shell),
5199 and
5200 .SM
5201 .B SIGINT
5202 is caught and handled (so that the \fBwait\fP builtin is interruptible).
5203 In all cases, \fBbash\fP ignores
5204 .SM
5205 .BR SIGQUIT .
5206 If job control is in effect,
5207 .B bash
5208 ignores
5209 .SM
5210 .BR SIGTTIN ,
5211 .SM
5212 .BR SIGTTOU ,
5213 and
5214 .SM
5215 .BR SIGTSTP .
5216 .PP
5217 Non-builtin commands run by \fBbash\fP have signal handlers
5218 set to the values inherited by the shell from its parent.
5219 When job control is not in effect, asynchronous commands
5220 ignore
5221 .SM
5222 .B SIGINT
5223 and
5224 .SM
5225 .B SIGQUIT
5226 in addition to these inherited handlers.
5227 Commands run as a result of command substitution ignore the
5228 keyboard-generated job control signals
5229 .SM
5230 .BR SIGTTIN ,
5231 .SM
5232 .BR SIGTTOU ,
5233 and
5234 .SM
5235 .BR SIGTSTP .
5236 .PP
5237 The shell exits by default upon receipt of a
5238 .SM
5239 .BR SIGHUP .
5240 Before exiting, an interactive shell resends the
5241 .SM
5242 .B SIGHUP
5243 to all jobs, running or stopped.
5244 Stopped jobs are sent
5245 .SM
5246 .B SIGCONT
5247 to ensure that they receive the
5248 .SM
5249 .BR SIGHUP .
5250 To prevent the shell from
5251 sending the signal to a particular job, it should be removed from the
5252 jobs table with the
5253 .B disown
5254 builtin (see
5255 .SM
5256 .B "SHELL BUILTIN COMMANDS"
5257 below) or marked
5258 to not receive
5259 .SM
5260 .B SIGHUP
5261 using
5262 .BR "disown \-h" .
5263 .PP
5264 If the
5265 .B huponexit
5266 shell option has been set with
5267 .BR shopt ,
5268 .B bash
5269 sends a
5270 .SM
5271 .B SIGHUP
5272 to all jobs when an interactive login shell exits.
5273 .PP
5274 If \fBbash\fP is waiting for a command to complete and receives a signal
5275 for which a trap has been set, the trap will not be executed until
5276 the command completes.
5277 When \fBbash\fP is waiting for an asynchronous command via the \fBwait\fP
5278 builtin, the reception of a signal for which a trap has been set will
5279 cause the \fBwait\fP builtin to return immediately with an exit status
5280 greater than 128, immediately after which the trap is executed.
5281 .PP
5282 When job control is not enabled, and \fBbash\fP is waiting for a foreground
5283 command to complete, the shell receives keyboard-generated signals
5284 such as
5285 .SM
5286 .B SIGINT
5287 (usually generated by \fB^C\fP) that users commonly intend to send
5288 to that command.
5289 This happens because the shell and the command are in the
5290 same process group as the terminal, and \fB^C\fP sends
5291 .SM
5292 .B SIGINT
5293 to all processes in that process group.
5294 .PP
5295 When \fBbash\fP is running without job control enabled and receives
5296 .SM
5297 .B SIGINT
5298 while waiting for a foreground command, it waits until that foreground
5299 command terminates and then decides what to do about the
5300 .SM
5301 .BR SIGINT :
5302 .IP 1.
5303 If the command terminates due to the
5304 .SM
5305 .BR SIGINT ,
5306 \fBbash\fP concludes
5307 that the user meant to end the entire script, and acts on the
5308 .SM
5309 .B SIGINT
5310 (e.g., by running a
5311 .SM
5312 .B SIGINT
5313 trap or exiting itself);
5314 .IP 2.
5315 If the command does not terminate due to
5316 .SM
5317 .BR SIGINT ,
5318 the program handled the
5319 .SM
5320 .B SIGINT
5321 itself and did not treat it as a fatal signal.
5322 In that case, \fBbash\fP does not treat
5323 .SM
5324 .B SIGINT
5325 as a fatal signal, either, instead assuming that the
5326 .SM
5327 .B SIGINT
5328 was used as part of the program's normal operation
5329 (e.g., emacs uses it to abort editing
5330 commands) or deliberately discarded.
5331 However, \fBbash\fP will run any
5332 trap set on
5333 .SM
5334 .BR SIGINT ,
5335 as it does with any other trapped signal it
5336 receives while it is waiting for the foreground command to
5337 complete, for compatibility.
5338 .SH "JOB CONTROL"
5339 .I Job control
5340 refers to the ability to selectively stop (\fIsuspend\fP)
5341 the execution of processes and continue (\fIresume\fP)
5342 their execution at a later point. A user typically employs
5343 this facility via an interactive interface supplied jointly
5344 by the operating system kernel's terminal driver and
5345 .BR bash .
5346 .PP
5347 The shell associates a
5348 .I job
5349 with each pipeline. It keeps a table of currently executing
5350 jobs, which may be listed with the
5351 .B jobs
5352 command. When
5353 .B bash
5354 starts a job asynchronously (in the
5355 .IR background ),
5356 it prints a line that looks like:
5357 .RS
5358 .PP
5359 [1] 25647
5360 .RE
5361 .PP
5362 indicating that this job is job number 1 and that the process ID
5363 of the last process in the pipeline associated with this job is 25647.
5364 All of the processes in a single pipeline are members of the same job.
5365 .B Bash
5366 uses the
5367 .I job
5368 abstraction as the basis for job control.
5369 .PP
5370 To facilitate the implementation of the user interface to job
5371 control, the operating system maintains the notion of a \fIcurrent terminal
5372 process group ID\fP. Members of this process group (processes whose
5373 process group ID is equal to the current terminal process group ID)
5374 receive keyboard-generated signals such as
5375 .SM
5376 .BR SIGINT .
5377 These processes are said to be in the
5378 .IR foreground .
5379 .I Background
5380 processes are those whose process group ID differs from the terminal's;
5381 such processes are immune to keyboard-generated signals.
5382 Only foreground processes are allowed to read from or, if the
5383 user so specifies with \f(CWstty tostop\fP, write to the
5384 terminal.
5385 Background processes which attempt to read from (write to when
5386 \f(CWstty tostop\fP is in effect) the
5387 terminal are sent a
5388 .SM
5389 .B SIGTTIN (SIGTTOU)
5390 signal by the kernel's terminal driver,
5391 which, unless caught, suspends the process.
5392 .PP
5393 If the operating system on which
5394 .B bash
5395 is running supports
5396 job control,
5397 .B bash
5398 contains facilities to use it.
5399 Typing the
5400 .I suspend
5401 character (typically
5402 .BR ^Z ,
5403 Control-Z) while a process is running
5404 causes that process to be stopped and returns control to
5405 .BR bash .
5406 Typing the
5407 .I "delayed suspend"
5408 character (typically
5409 .BR ^Y ,
5410 Control-Y) causes the process to be stopped when it
5411 attempts to read input from the terminal, and control to
5412 be returned to
5413 .BR bash .
5414 The user may then manipulate the state of this job, using the
5415 .B bg
5416 command to continue it in the background, the
5417 .B fg
5418 command to continue it in the foreground, or
5419 the
5420 .B kill
5421 command to kill it. A \fB^Z\fP takes effect immediately,
5422 and has the additional side effect of causing pending output
5423 and typeahead to be discarded.
5424 .PP
5425 There are a number of ways to refer to a job in the shell.
5426 The character
5427 .B %
5428 introduces a job specification (\fIjobspec\fP). Job number
5429 .I n
5430 may be referred to as
5431 .BR %n .
5432 A job may also be referred to using a prefix of the name used to
5433 start it, or using a substring that appears in its command line.
5434 For example,
5435 .B %ce
5436 refers to a stopped
5437 job whose command name begins with
5438 .BR ce .
5439 If a prefix matches more than one job,
5440 .B bash
5441 reports an error. Using
5442 .BR %?ce ,
5443 on the other hand, refers to any job containing the string
5444 .B ce
5445 in its command line. If the substring matches more than one job,
5446 .B bash
5447 reports an error. The symbols
5448 .B %%
5449 and
5450 .B %+
5451 refer to the shell's notion of the
5452 .IR "current job" ,
5453 which is the last job stopped while it was in
5454 the foreground or started in the background.
5455 The
5456 .I "previous job"
5457 may be referenced using
5458 .BR %\- .
5459 If there is only a single job, \fB%+\fP and \fB%\-\fP can both be used
5460 to refer to that job.
5461 In output pertaining to jobs (e.g., the output of the
5462 .B jobs
5463 command), the current job is always flagged with a
5464 .BR + ,
5465 and the previous job with a
5466 .BR \- .
5467 A single % (with no accompanying job specification) also refers to the
5468 current job.
5469 .PP
5470 Simply naming a job can be used to bring it into the
5471 foreground:
5472 .B %1
5473 is a synonym for
5474 \fB``fg %1''\fP,
5475 bringing job 1 from the background into the foreground.
5476 Similarly,
5477 .B ``%1 &''
5478 resumes job 1 in the background, equivalent to
5479 \fB``bg %1''\fP.
5480 .PP
5481 The shell learns immediately whenever a job changes state.
5482 Normally,
5483 .B bash
5484 waits until it is about to print a prompt before reporting
5485 changes in a job's status so as to not interrupt
5486 any other output. If the
5487 .B \-b
5488 option to the
5489 .B set
5490 builtin command
5491 is enabled,
5492 .B bash
5493 reports such changes immediately.
5494 Any trap on
5495 .SM
5496 .B SIGCHLD
5497 is executed for each child that exits.
5498 .PP
5499 If an attempt to exit
5500 .B bash
5501 is made while jobs are stopped (or, if the \fBcheckjobs\fP shell option has
5502 been enabled using the \fBshopt\fP builtin, running), the shell prints a
5503 warning message, and, if the \fBcheckjobs\fP option is enabled, lists the
5504 jobs and their statuses.
5505 The
5506 .B jobs
5507 command may then be used to inspect their status.
5508 If a second attempt to exit is made without an intervening command,
5509 the shell does not print another warning, and any stopped
5510 jobs are terminated.
5511 .PP
5512 When the shell is waiting for a job or process using the \fBwait\fP
5513 builtin, and job control is enabled, \fBwait\fP will return when the
5514 job changes state. The \fB\-f\fP option causes \fBwait\fP to wait
5515 until the job or process terminates before returning.
5516 .SH PROMPTING
5517 When executing interactively,
5518 .B bash
5519 displays the primary prompt
5520 .SM
5521 .B PS1
5522 when it is ready to read a command, and the secondary prompt
5523 .SM
5524 .B PS2
5525 when it needs more input to complete a command.
5526 .B Bash
5527 displays
5528 .SM
5529 .B PS0
5530 after it reads a command but before executing it.
5531 .B Bash
5532 displays
5533 .SM
5534 .B PS4
5535 as described above
5536 before tracing each command when the \fB\-x\fP option is enabled.
5537 .B Bash
5538 allows these prompt strings to be customized by inserting a number of
5539 backslash-escaped special characters that are decoded as follows:
5540 .RS
5541 .PD 0
5542 .TP
5543 .B \ea
5544 an ASCII bell character (07)
5545 .TP
5546 .B \ed
5547 the date in "Weekday Month Date" format (e.g., "Tue May 26")
5548 .TP
5549 .B \eD{\fIformat\fP}
5550 the \fIformat\fP is passed to \fIstrftime\fP(3) and the result is inserted
5551 into the prompt string; an empty \fIformat\fP results in a locale-specific
5552 time representation. The braces are required
5553 .TP
5554 .B \ee
5555 an ASCII escape character (033)
5556 .TP
5557 .B \eh
5558 the hostname up to the first `.'
5559 .TP
5560 .B \eH
5561 the hostname
5562 .TP
5563 .B \ej
5564 the number of jobs currently managed by the shell
5565 .TP
5566 .B \el
5567 the basename of the shell's terminal device name
5568 .TP
5569 .B \en
5570 newline
5571 .TP
5572 .B \er
5573 carriage return
5574 .TP
5575 .B \es
5576 the name of the shell, the basename of
5577 .B $0
5578 (the portion following the final slash)
5579 .TP
5580 .B \et
5581 the current time in 24-hour HH:MM:SS format
5582 .TP
5583 .B \eT
5584 the current time in 12-hour HH:MM:SS format
5585 .TP
5586 .B \e@
5587 the current time in 12-hour am/pm format
5588 .TP
5589 .B \eA
5590 the current time in 24-hour HH:MM format
5591 .TP
5592 .B \eu
5593 the username of the current user
5594 .TP
5595 .B \ev
5596 the version of \fBbash\fP (e.g., 2.00)
5597 .TP
5598 .B \eV
5599 the release of \fBbash\fP, version + patch level (e.g., 2.00.0)
5600 .TP
5601 .B \ew
5602 the value of the \fBPWD\fP shell variable (\fB$PWD\fP),
5603 with
5604 .SM
5605 .B $HOME
5606 abbreviated with a tilde
5607 (uses the value of the
5608 .SM
5609 .B PROMPT_DIRTRIM
5610 variable)
5611 .TP
5612 .B \eW
5613 the basename of \fB$PWD\fP,
5614 with
5615 .SM
5616 .B $HOME
5617 abbreviated with a tilde
5618 .TP
5619 .B \e!
5620 the history number of this command
5621 .TP
5622 .B \e#
5623 the command number of this command
5624 .TP
5625 .B \e$
5626 if the effective UID is 0, a
5627 .BR # ,
5628 otherwise a
5629 .B $
5630 .TP
5631 .B \e\fInnn\fP
5632 the character corresponding to the octal number \fInnn\fP
5633 .TP
5634 .B \e\e
5635 a backslash
5636 .TP
5637 .B \e[
5638 begin a sequence of non-printing characters, which could be used to
5639 embed a terminal control sequence into the prompt
5640 .TP
5641 .B \e]
5642 end a sequence of non-printing characters
5643 .PD
5644 .RE
5645 .PP
5646 The command number and the history number are usually different:
5647 the history number of a command is its position in the history
5648 list, which may include commands restored from the history file
5649 (see
5650 .SM
5651 .B HISTORY
5652 below), while the command number is the position in the sequence
5653 of commands executed during the current shell session.
5654 After the string is decoded, it is expanded via
5655 parameter expansion, command substitution, arithmetic
5656 expansion, and quote removal, subject to the value of the
5657 .B promptvars
5658 shell option (see the description of the
5659 .B shopt
5660 command under
5661 .SM
5662 .B "SHELL BUILTIN COMMANDS"
5663 below).
5664 This can have unwanted side effects if escaped portions of the string
5665 appear within command substitution or contain characters special to
5666 word expansion.
5667 .SH READLINE
5668 This is the library that handles reading input when using an interactive
5669 shell, unless the
5670 .B \-\-noediting
5671 option is given at shell invocation.
5672 Line editing is also used when using the \fB\-e\fP option to the
5673 \fBread\fP builtin.
5674 By default, the line editing commands are similar to those of Emacs.
5675 A vi-style line editing interface is also available.
5676 Line editing can be enabled at any time using the
5677 .B \-o emacs
5678 or
5679 .B \-o vi
5680 options to the
5681 .B set
5682 builtin (see
5683 .SM
5684 .B SHELL BUILTIN COMMANDS
5685 below).
5686 To turn off line editing after the shell is running, use the
5687 .B +o emacs
5688 or
5689 .B +o vi
5690 options to the
5691 .B set
5692 builtin.
5693 .SS "Readline Notation"
5694 In this section, the Emacs-style notation is used to denote
5695 keystrokes. Control keys are denoted by C\-\fIkey\fR, e.g., C\-n
5696 means Control\-N. Similarly,
5697 .I meta
5698 keys are denoted by M\-\fIkey\fR, so M\-x means Meta\-X. (On keyboards
5699 without a
5700 .I meta
5701 key, M\-\fIx\fP means ESC \fIx\fP, i.e., press the Escape key
5702 then the
5703 .I x
5704 key. This makes ESC the \fImeta prefix\fP.
5705 The combination M\-C\-\fIx\fP means ESC\-Control\-\fIx\fP,
5706 or press the Escape key
5707 then hold the Control key while pressing the
5708 .I x
5709 key.)
5710 .PP
5711 Readline commands may be given numeric
5712 .IR arguments ,
5713 which normally act as a repeat count.
5714 Sometimes, however, it is the sign of the argument that is significant.
5715 Passing a negative argument to a command that acts in the forward
5716 direction (e.g., \fBkill\-line\fP) causes that command to act in a
5717 backward direction.
5718 Commands whose behavior with arguments deviates from this are noted
5719 below.
5720 .PP
5721 When a command is described as \fIkilling\fP text, the text
5722 deleted is saved for possible future retrieval
5723 (\fIyanking\fP). The killed text is saved in a
5724 \fIkill ring\fP. Consecutive kills cause the text to be
5725 accumulated into one unit, which can be yanked all at once.
5726 Commands which do not kill text separate the chunks of text
5727 on the kill ring.
5728 .SS "Readline Initialization"
5729 Readline is customized by putting commands in an initialization
5730 file (the \fIinputrc\fP file).
5731 The name of this file is taken from the value of the
5732 .SM
5733 .B INPUTRC
5734 variable. If that variable is unset, the default is
5735 .IR ~/.inputrc .
5736 If that file does not exist or cannot be read, the ultimate default is
5737 .IR /etc/inputrc .
5738 When a program which uses the readline library starts up, the
5739 initialization file is read, and the key bindings and variables
5740 are set.
5741 There are only a few basic constructs allowed in the
5742 readline initialization file.
5743 Blank lines are ignored.
5744 Lines beginning with a \fB#\fP are comments.
5745 Lines beginning with a \fB$\fP indicate conditional constructs.
5746 Other lines denote key bindings and variable settings.
5747 .PP
5748 The default key-bindings may be changed with an
5749 .I inputrc
5750 file.
5751 Other programs that use this library may add their own commands
5752 and bindings.
5753 .PP
5754 For example, placing
5755 .RS
5756 .PP
5757 M\-Control\-u: universal\-argument
5758 .RE
5759 or
5760 .RS
5761 C\-Meta\-u: universal\-argument
5762 .RE
5763 into the
5764 .I inputrc
5765 would make M\-C\-u execute the readline command
5766 .IR universal\-argument .
5767 .PP
5768 The following symbolic character names are recognized:
5769 .IR RUBOUT ,
5770 .IR DEL ,
5771 .IR ESC ,
5772 .IR LFD ,
5773 .IR NEWLINE ,
5774 .IR RET ,
5775 .IR RETURN ,
5776 .IR SPC ,
5777 .IR SPACE ,
5778 and
5779 .IR TAB .
5780 .PP
5781 In addition to command names, readline allows keys to be bound
5782 to a string that is inserted when the key is pressed (a \fImacro\fP).
5783 .SS "Readline Key Bindings"
5784 The syntax for controlling key bindings in the
5785 .I inputrc
5786 file is simple. All that is required is the name of the
5787 command or the text of a macro and a key sequence to which
5788 it should be bound. The name may be specified in one of two ways:
5789 as a symbolic key name, possibly with \fIMeta\-\fP or \fIControl\-\fP
5790 prefixes, or as a key sequence.
5791 .PP
5792 When using the form \fBkeyname\fP:\^\fIfunction\-name\fP or \fImacro\fP,
5793 .I keyname
5794 is the name of a key spelled out in English. For example:
5795 .sp
5796 .RS
5797 Control-u: universal\-argument
5798 .br
5799 Meta-Rubout: backward-kill-word
5800 .br
5801 Control-o: "> output"
5802 .RE
5803 .LP
5804 In the above example,
5805 .I C\-u
5806 is bound to the function
5807 .BR universal\-argument ,
5808 .I M\-DEL
5809 is bound to the function
5810 .BR backward\-kill\-word ,
5811 and
5812 .I C\-o
5813 is bound to run the macro
5814 expressed on the right hand side (that is, to insert the text
5815 .if t \f(CW> output\fP
5816 .if n ``> output''
5817 into the line).
5818 .PP
5819 In the second form, \fB"keyseq"\fP:\^\fIfunction\-name\fP or \fImacro\fP,
5820 .B keyseq
5821 differs from
5822 .B keyname
5823 above in that strings denoting
5824 an entire key sequence may be specified by placing the sequence
5825 within double quotes. Some GNU Emacs style key escapes can be
5826 used, as in the following example, but the symbolic character names
5827 are not recognized.
5828 .sp
5829 .RS
5830 "\eC\-u": universal\-argument
5831 .br
5832 "\eC\-x\eC\-r": re\-read\-init\-file
5833 .br
5834 "\ee[11~": "Function Key 1"
5835 .RE
5836 .PP
5837 In this example,
5838 .I C\-u
5839 is again bound to the function
5840 .BR universal\-argument .
5841 .I "C\-x C\-r"
5842 is bound to the function
5843 .BR re\-read\-init\-file ,
5844 and
5845 .I "ESC [ 1 1 ~"
5846 is bound to insert the text
5847 .if t \f(CWFunction Key 1\fP.
5848 .if n ``Function Key 1''.
5849 .PP
5850 The full set of GNU Emacs style escape sequences is
5851 .RS
5852 .PD 0
5853 .TP
5854 .B \eC\-
5855 control prefix
5856 .TP
5857 .B \eM\-
5858 meta prefix
5859 .TP
5860 .B \ee
5861 an escape character
5862 .TP
5863 .B \e\e
5864 backslash
5865 .TP
5866 .B \e"
5867 literal "
5868 .TP
5869 .B \e\(aq
5870 literal \(aq
5871 .RE
5872 .PD
5873 .PP
5874 In addition to the GNU Emacs style escape sequences, a second
5875 set of backslash escapes is available:
5876 .RS
5877 .PD 0
5878 .TP
5879 .B \ea
5880 alert (bell)
5881 .TP
5882 .B \eb
5883 backspace
5884 .TP
5885 .B \ed
5886 delete
5887 .TP
5888 .B \ef
5889 form feed
5890 .TP
5891 .B \en
5892 newline
5893 .TP
5894 .B \er
5895 carriage return
5896 .TP
5897 .B \et
5898 horizontal tab
5899 .TP
5900 .B \ev
5901 vertical tab
5902 .TP
5903 .B \e\fInnn\fP
5904 the eight-bit character whose value is the octal value \fInnn\fP
5905 (one to three digits)
5906 .TP
5907 .B \ex\fIHH\fP
5908 the eight-bit character whose value is the hexadecimal value \fIHH\fP
5909 (one or two hex digits)
5910 .RE
5911 .PD
5912 .PP
5913 When entering the text of a macro, single or double quotes must
5914 be used to indicate a macro definition.
5915 Unquoted text is assumed to be a function name.
5916 In the macro body, the backslash escapes described above are expanded.
5917 Backslash will quote any other character in the macro text,
5918 including " and \(aq.
5919 .PP
5920 .B Bash
5921 allows the current readline key bindings to be displayed or modified
5922 with the
5923 .B bind
5924 builtin command. The editing mode may be switched during interactive
5925 use by using the
5926 .B \-o
5927 option to the
5928 .B set
5929 builtin command (see
5930 .SM
5931 .B SHELL BUILTIN COMMANDS
5932 below).
5933 .SS "Readline Variables"
5934 Readline has variables that can be used to further customize its
5935 behavior. A variable may be set in the
5936 .I inputrc
5937 file with a statement of the form
5938 .RS
5939 .PP
5940 \fBset\fP \fIvariable\-name\fP \fIvalue\fP
5941 .RE
5942 or using the \fBbind\fP builtin command (see
5943 .SM
5944 .B SHELL BUILTIN COMMANDS
5945 below).
5946 .PP
5947 Except where noted, readline variables can take the values
5948 .B On
5949 or
5950 .B Off
5951 (without regard to case).
5952 Unrecognized variable names are ignored.
5953 When a variable value is read, empty or null values, "on" (case-insensitive),
5954 and "1" are equivalent to \fBOn\fP. All other values are equivalent to
5955 \fBOff\fP.
5956 The variables and their default values are:
5957 .PP
5958 .PD 0
5959 .TP
5960 .B active\-region\-start\-color
5961 A string variable that controls the text color and background when displaying
5962 the text in the active region (see the description of
5963 \fBenable\-active\-region\fP below).
5964 This string must not take up any physical character positions on the display,
5965 so it should consist only of terminal escape sequences.
5966 It is output to the terminal before displaying the text in the active region.
5967 This variable is reset to the default value whenever the terminal type changes.
5968 The default value is the string that puts the terminal in standout mode,
5969 as obtained from the terminal's terminfo description.
5970 A sample value might be \f(CW"\ee[01;33m"\fP.
5971 .TP
5972 .B active\-region\-end\-color
5973 A string variable that "undoes" the effects of \fBactive\-region\-start\-color\fP
5974 and restores "normal" terminal display appearance after displaying text
5975 in the active region.
5976 This string must not take up any physical character positions on the display,
5977 so it should consist only of terminal escape sequences.
5978 It is output to the terminal after displaying the text in the active region.
5979 This variable is reset to the default value whenever the terminal type changes.
5980 The default value is the string that restores the terminal from standout mode,
5981 as obtained from the terminal's terminfo description.
5982 A sample value might be \f(CW"\ee[0m"\fP.
5983 .TP
5984 .B bell\-style (audible)
5985 Controls what happens when readline wants to ring the terminal bell.
5986 If set to \fBnone\fP, readline never rings the bell. If set to
5987 \fBvisible\fP, readline uses a visible bell if one is available.
5988 If set to \fBaudible\fP, readline attempts to ring the terminal's bell.
5989 .TP
5990 .B bind\-tty\-special\-chars (On)
5991 If set to \fBOn\fP, readline attempts to bind the control characters
5992 treated specially by the kernel's terminal driver to their readline
5993 equivalents.
5994 .TP
5995 .B blink\-matching\-paren (Off)
5996 If set to \fBOn\fP, readline attempts to briefly move the cursor to an
5997 opening parenthesis when a closing parenthesis is inserted.
5998 .TP
5999 .B colored\-completion\-prefix (Off)
6000 If set to \fBOn\fP, when listing completions, readline displays the
6001 common prefix of the set of possible completions using a different color.
6002 The color definitions are taken from the value of the \fBLS_COLORS\fP
6003 environment variable.
6004 If there is a color definition in \fB$LS_COLORS\fP for the custom suffix
6005 "readline-colored-completion-prefix", readline uses this color for
6006 the common prefix instead of its default.
6007 .TP
6008 .B colored\-stats (Off)
6009 If set to \fBOn\fP, readline displays possible completions using different
6010 colors to indicate their file type.
6011 The color definitions are taken from the value of the \fBLS_COLORS\fP
6012 environment variable.
6013 .TP
6014 .B comment\-begin (``#'')
6015 The string that is inserted when the readline
6016 .B insert\-comment
6017 command is executed.
6018 This command is bound to
6019 .B M\-#
6020 in emacs mode and to
6021 .B #
6022 in vi command mode.
6023 .TP
6024 .B completion\-display\-width (\-1)
6025 The number of screen columns used to display possible matches
6026 when performing completion.
6027 The value is ignored if it is less than 0 or greater than the terminal
6028 screen width.
6029 A value of 0 will cause matches to be displayed one per line.
6030 The default value is \-1.
6031 .TP
6032 .B completion\-ignore\-case (Off)
6033 If set to \fBOn\fP, readline performs filename matching and completion
6034 in a case\-insensitive fashion.
6035 .TP
6036 .B completion\-map\-case (Off)
6037 If set to \fBOn\fP, and \fBcompletion\-ignore\-case\fP is enabled, readline
6038 treats hyphens (\fI\-\fP) and underscores (\fI_\fP) as equivalent when
6039 performing case\-insensitive filename matching and completion.
6040 .TP
6041 .B completion\-prefix\-display\-length (0)
6042 The length in characters of the common prefix of a list of possible
6043 completions that is displayed without modification. When set to a
6044 value greater than zero, common prefixes longer than this value are
6045 replaced with an ellipsis when displaying possible completions.
6046 .TP
6047 .B completion\-query\-items (100)
6048 This determines when the user is queried about viewing
6049 the number of possible completions
6050 generated by the \fBpossible\-completions\fP command.
6051 It may be set to any integer value greater than or equal to zero.
6052 If the number of possible completions is greater than
6053 or equal to the value of this variable,
6054 readline will ask whether or not the user wishes to view them;
6055 otherwise they are simply listed on the terminal.
6056 A zero value means readline should never ask; negative values are
6057 treated as zero.
6058 .TP
6059 .B convert\-meta (On)
6060 If set to \fBOn\fP, readline will convert characters with the
6061 eighth bit set to an ASCII key sequence
6062 by stripping the eighth bit and prefixing an
6063 escape character (in effect, using escape as the \fImeta prefix\fP).
6064 The default is \fIOn\fP, but readline will set it to \fIOff\fP if the
6065 locale contains eight-bit characters.
6066 This variable is dependent on the \fBLC_CTYPE\fP locale category, and
6067 may change if the locale is changed.
6068 .TP
6069 .B disable\-completion (Off)
6070 If set to \fBOn\fP, readline will inhibit word completion. Completion
6071 characters will be inserted into the line as if they had been
6072 mapped to \fBself-insert\fP.
6073 .TP
6074 .B echo\-control\-characters (On)
6075 When set to \fBOn\fP, on operating systems that indicate they support it,
6076 readline echoes a character corresponding to a signal generated from the
6077 keyboard.
6078 .TP
6079 .B editing\-mode (emacs)
6080 Controls whether readline begins with a set of key bindings similar
6081 to \fIEmacs\fP or \fIvi\fP.
6082 .B editing\-mode
6083 can be set to either
6084 .B emacs
6085 or
6086 .BR vi .
6087 .TP
6088 .B emacs\-mode\-string (@)
6089 If the \fIshow\-mode\-in\-prompt\fP variable is enabled,
6090 this string is displayed immediately before the last line of the primary
6091 prompt when emacs editing mode is active. The value is expanded like a
6092 key binding, so the standard set of meta- and control prefixes and
6093 backslash escape sequences is available.
6094 Use the \e1 and \e2 escapes to begin and end sequences of
6095 non-printing characters, which can be used to embed a terminal control
6096 sequence into the mode string.
6097 .TP
6098 .B enable\-active\-region (On)
6099 The \fIpoint\fP is the current cursor position, and \fImark\fP refers
6100 to a saved cursor position.
6101 The text between the point and mark is referred to as the \fIregion\fP.
6102 When this variable is set to \fIOn\fP, readline allows certain commands
6103 to designate the region as \fIactive\fP.
6104 When the region is active, readline highlights the text in the region using
6105 the value of the \fBactive\-region\-start\-color\fP, which defaults to the
6106 string that enables
6107 the terminal's standout mode.
6108 The active region shows the text inserted by bracketed-paste and any
6109 matching text found by incremental and non-incremental history searches.
6110 .TP
6111 .B enable\-bracketed\-paste (On)
6112 When set to \fBOn\fP, readline configures the terminal to insert each
6113 paste into the editing buffer as a single string of characters, instead
6114 of treating each character as if it had been read from the keyboard.
6115 This prevents readline from executing any editing commands bound to key
6116 sequences appearing in the pasted text.
6117 .TP
6118 .B enable\-keypad (Off)
6119 When set to \fBOn\fP, readline will try to enable the application
6120 keypad when it is called. Some systems need this to enable the
6121 arrow keys.
6122 .TP
6123 .B enable\-meta\-key (On)
6124 When set to \fBOn\fP, readline will try to enable any meta modifier
6125 key the terminal claims to support when it is called. On many terminals,
6126 the meta key is used to send eight-bit characters.
6127 .TP
6128 .B expand\-tilde (Off)
6129 If set to \fBOn\fP, tilde expansion is performed when readline
6130 attempts word completion.
6131 .TP
6132 .B history\-preserve\-point (Off)
6133 If set to \fBOn\fP, the history code attempts to place point at the
6134 same location on each history line retrieved with \fBprevious-history\fP
6135 or \fBnext-history\fP.
6136 .TP
6137 .B history\-size (unset)
6138 Set the maximum number of history entries saved in the history list.
6139 If set to zero, any existing history entries are deleted and no new entries
6140 are saved.
6141 If set to a value less than zero, the number of history entries is not
6142 limited.
6143 By default, the number of history entries is set to the value of the
6144 \fBHISTSIZE\fP shell variable.
6145 If an attempt is made to set \fIhistory\-size\fP to a non-numeric value,
6146 the maximum number of history entries will be set to 500.
6147 .TP
6148 .B horizontal\-scroll\-mode (Off)
6149 When set to \fBOn\fP, makes readline use a single line for display,
6150 scrolling the input horizontally on a single screen line when it
6151 becomes longer than the screen width rather than wrapping to a new line.
6152 This setting is automatically enabled for terminals of height 1.
6153 .TP
6154 .B input\-meta (Off)
6155 If set to \fBOn\fP, readline will enable eight-bit input (that is,
6156 it will not strip the eighth bit from the characters it reads),
6157 regardless of what the terminal claims it can support. The name
6158 .B meta\-flag
6159 is a synonym for this variable.
6160 The default is \fIOff\fP, but readline will set it to \fIOn\fP if the
6161 locale contains eight-bit characters.
6162 This variable is dependent on the \fBLC_CTYPE\fP locale category, and
6163 may change if the locale is changed.
6164 .TP
6165 .B isearch\-terminators (``C\-[C\-J'')
6166 The string of characters that should terminate an incremental
6167 search without subsequently executing the character as a command.
6168 If this variable has not been given a value, the characters
6169 \fIESC\fP and \fIC\-J\fP will terminate an incremental search.
6170 .TP
6171 .B keymap (emacs)
6172 Set the current readline keymap. The set of valid keymap names is
6173 \fIemacs, emacs\-standard, emacs\-meta, emacs\-ctlx, vi,
6174 vi\-command\fP, and
6175 .IR vi\-insert .
6176 \fIvi\fP is equivalent to \fIvi\-command\fP; \fIemacs\fP is
6177 equivalent to \fIemacs\-standard\fP. The default value is
6178 .IR emacs ;
6179 the value of
6180 .B editing\-mode
6181 also affects the default keymap.
6182 .TP
6183 .B keyseq\-timeout (500)
6184 Specifies the duration \fIreadline\fP will wait for a character when reading an
6185 ambiguous key sequence (one that can form a complete key sequence using
6186 the input read so far, or can take additional input to complete a longer
6187 key sequence).
6188 If no input is received within the timeout, \fIreadline\fP will use the shorter
6189 but complete key sequence.
6190 The value is specified in milliseconds, so a value of 1000 means that
6191 \fIreadline\fP will wait one second for additional input.
6192 If this variable is set to a value less than or equal to zero, or to a
6193 non-numeric value, \fIreadline\fP will wait until another key is pressed to
6194 decide which key sequence to complete.
6195 .TP
6196 .B mark\-directories (On)
6197 If set to \fBOn\fP, completed directory names have a slash
6198 appended.
6199 .TP
6200 .B mark\-modified\-lines (Off)
6201 If set to \fBOn\fP, history lines that have been modified are displayed
6202 with a preceding asterisk (\fB*\fP).
6203 .TP
6204 .B mark\-symlinked\-directories (Off)
6205 If set to \fBOn\fP, completed names which are symbolic links to directories
6206 have a slash appended (subject to the value of
6207 \fBmark\-directories\fP).
6208 .TP
6209 .B match\-hidden\-files (On)
6210 This variable, when set to \fBOn\fP, causes readline to match files whose
6211 names begin with a `.' (hidden files) when performing filename
6212 completion.
6213 If set to \fBOff\fP, the leading `.' must be
6214 supplied by the user in the filename to be completed.
6215 .TP
6216 .B menu\-complete\-display\-prefix (Off)
6217 If set to \fBOn\fP, menu completion displays the common prefix of the
6218 list of possible completions (which may be empty) before cycling through
6219 the list.
6220 .TP
6221 .B output\-meta (Off)
6222 If set to \fBOn\fP, readline will display characters with the
6223 eighth bit set directly rather than as a meta-prefixed escape
6224 sequence.
6225 The default is \fIOff\fP, but readline will set it to \fIOn\fP if the
6226 locale contains eight-bit characters.
6227 This variable is dependent on the \fBLC_CTYPE\fP locale category, and
6228 may change if the locale is changed.
6229 .TP
6230 .B page\-completions (On)
6231 If set to \fBOn\fP, readline uses an internal \fImore\fP-like pager
6232 to display a screenful of possible completions at a time.
6233 .TP
6234 .B print\-completions\-horizontally (Off)
6235 If set to \fBOn\fP, readline will display completions with matches
6236 sorted horizontally in alphabetical order, rather than down the screen.
6237 .TP
6238 .B revert\-all\-at\-newline (Off)
6239 If set to \fBOn\fP, readline will undo all changes to history lines
6240 before returning when \fBaccept\-line\fP is executed. By default,
6241 history lines may be modified and retain individual undo lists across
6242 calls to \fBreadline\fP.
6243 .TP
6244 .B show\-all\-if\-ambiguous (Off)
6245 This alters the default behavior of the completion functions. If
6246 set to
6247 .BR On ,
6248 words which have more than one possible completion cause the
6249 matches to be listed immediately instead of ringing the bell.
6250 .TP
6251 .B show\-all\-if\-unmodified (Off)
6252 This alters the default behavior of the completion functions in
6253 a fashion similar to \fBshow\-all\-if\-ambiguous\fP.
6254 If set to
6255 .BR On ,
6256 words which have more than one possible completion without any
6257 possible partial completion (the possible completions don't share
6258 a common prefix) cause the matches to be listed immediately instead
6259 of ringing the bell.
6260 .TP
6261 .B show\-mode\-in\-prompt (Off)
6262 If set to \fBOn\fP, add a string to the beginning of the prompt
6263 indicating the editing mode: emacs, vi command, or vi insertion.
6264 The mode strings are user-settable (e.g., \fIemacs\-mode\-string\fP).
6265 .TP
6266 .B skip\-completed\-text (Off)
6267 If set to \fBOn\fP, this alters the default completion behavior when
6268 inserting a single match into the line. It's only active when
6269 performing completion in the middle of a word. If enabled, readline
6270 does not insert characters from the completion that match characters
6271 after point in the word being completed, so portions of the word
6272 following the cursor are not duplicated.
6273 .TP
6274 .B vi\-cmd\-mode\-string ((cmd))
6275 If the \fIshow\-mode\-in\-prompt\fP variable is enabled,
6276 this string is displayed immediately before the last line of the primary
6277 prompt when vi editing mode is active and in command mode.
6278 The value is expanded like a
6279 key binding, so the standard set of meta- and control prefixes and
6280 backslash escape sequences is available.
6281 Use the \e1 and \e2 escapes to begin and end sequences of
6282 non-printing characters, which can be used to embed a terminal control
6283 sequence into the mode string.
6284 .TP
6285 .B vi\-ins\-mode\-string ((ins))
6286 If the \fIshow\-mode\-in\-prompt\fP variable is enabled,
6287 this string is displayed immediately before the last line of the primary
6288 prompt when vi editing mode is active and in insertion mode.
6289 The value is expanded like a
6290 key binding, so the standard set of meta- and control prefixes and
6291 backslash escape sequences is available.
6292 Use the \e1 and \e2 escapes to begin and end sequences of
6293 non-printing characters, which can be used to embed a terminal control
6294 sequence into the mode string.
6295 .TP
6296 .B visible\-stats (Off)
6297 If set to \fBOn\fP, a character denoting a file's type as reported
6298 by \fIstat\fP(2) is appended to the filename when listing possible
6299 completions.
6300 .PD
6301 .SS "Readline Conditional Constructs"
6302 Readline implements a facility similar in spirit to the conditional
6303 compilation features of the C preprocessor which allows key
6304 bindings and variable settings to be performed as the result
6305 of tests. There are four parser directives used.
6306 .IP \fB$if\fP
6307 The
6308 .B $if
6309 construct allows bindings to be made based on the
6310 editing mode, the terminal being used, or the application using
6311 readline. The text of the test, after any comparison operator,
6312 extends to the end of the line;
6313 unless otherwise noted, no characters are required to isolate it.
6314 .RS
6315 .IP \fBmode\fP
6316 The \fBmode=\fP form of the \fB$if\fP directive is used to test
6317 whether readline is in emacs or vi mode.
6318 This may be used in conjunction
6319 with the \fBset keymap\fP command, for instance, to set bindings in
6320 the \fIemacs\-standard\fP and \fIemacs\-ctlx\fP keymaps only if
6321 readline is starting out in emacs mode.
6322 .IP \fBterm\fP
6323 The \fBterm=\fP form may be used to include terminal-specific
6324 key bindings, perhaps to bind the key sequences output by the
6325 terminal's function keys. The word on the right side of the
6326 .B =
6327 is tested against both the full name of the terminal and the portion
6328 of the terminal name before the first \fB\-\fP. This allows
6329 .I sun
6330 to match both
6331 .I sun
6332 and
6333 .IR sun\-cmd ,
6334 for instance.
6335 .IP \fBversion\fP
6336 The \fBversion\fP test may be used to perform comparisons against
6337 specific readline versions.
6338 The \fBversion\fP expands to the current readline version.
6339 The set of comparison operators includes
6340 .BR = ,
6341 (and
6342 .BR == ),
6343 .BR != ,
6344 .BR <= ,
6345 .BR >= ,
6346 .BR < ,
6347 and
6348 .BR > .
6349 The version number supplied on the right side of the operator consists
6350 of a major version number, an optional decimal point, and an optional
6351 minor version (e.g., \fB7.1\fP). If the minor version is omitted, it
6352 is assumed to be \fB0\fP.
6353 The operator may be separated from the string \fBversion\fP
6354 and from the version number argument by whitespace.
6355 .IP \fBapplication\fP
6356 The \fBapplication\fP construct is used to include
6357 application-specific settings. Each program using the readline
6358 library sets the \fIapplication name\fP, and an initialization
6359 file can test for a particular value.
6360 This could be used to bind key sequences to functions useful for
6361 a specific program. For instance, the following command adds a
6362 key sequence that quotes the current or previous word in \fBbash\fP:
6363 .sp 1
6364 .RS
6365 .nf
6366 \fB$if\fP Bash
6367 # Quote the current or previous word
6368 "\eC\-xq": "\eeb\e"\eef\e""
6369 \fB$endif\fP
6370 .fi
6371 .RE
6372 .IP \fIvariable\fP
6373 The \fIvariable\fP construct provides simple equality tests for readline
6374 variables and values.
6375 The permitted comparison operators are \fI=\fP, \fI==\fP, and \fI!=\fP.
6376 The variable name must be separated from the comparison operator by
6377 whitespace; the operator may be separated from the value on the right hand
6378 side by whitespace.
6379 Both string and boolean variables may be tested. Boolean variables must be
6380 tested against the values \fIon\fP and \fIoff\fP.
6381 .RE
6382 .IP \fB$endif\fP
6383 This command, as seen in the previous example, terminates an
6384 \fB$if\fP command.
6385 .IP \fB$else\fP
6386 Commands in this branch of the \fB$if\fP directive are executed if
6387 the test fails.
6388 .IP \fB$include\fP
6389 This directive takes a single filename as an argument and reads commands
6390 and bindings from that file. For example, the following directive
6391 would read \fI/etc/inputrc\fP:
6392 .sp 1
6393 .RS
6394 .nf
6395 \fB$include\fP \^ \fI/etc/inputrc\fP
6396 .fi
6397 .RE
6398 .SS Searching
6399 Readline provides commands for searching through the command history
6400 (see
6401 .SM
6402 .B HISTORY
6403 below) for lines containing a specified string.
6404 There are two search modes:
6405 .I incremental
6406 and
6407 .IR non-incremental .
6408 .PP
6409 Incremental searches begin before the user has finished typing the
6410 search string.
6411 As each character of the search string is typed, readline displays
6412 the next entry from the history matching the string typed so far.
6413 An incremental search requires only as many characters as needed to
6414 find the desired history entry.
6415 The characters present in the value of the \fBisearch-terminators\fP
6416 variable are used to terminate an incremental search.
6417 If that variable has not been assigned a value the Escape and
6418 Control-J characters will terminate an incremental search.
6419 Control-G will abort an incremental search and restore the original
6420 line.
6421 When the search is terminated, the history entry containing the
6422 search string becomes the current line.
6423 .PP
6424 To find other matching entries in the history list, type Control-S or
6425 Control-R as appropriate.
6426 This will search backward or forward in the history for the next
6427 entry matching the search string typed so far.
6428 Any other key sequence bound to a readline command will terminate
6429 the search and execute that command.
6430 For instance, a \fInewline\fP will terminate the search and accept
6431 the line, thereby executing the command from the history list.
6432 .PP
6433 Readline remembers the last incremental search string. If two
6434 Control-Rs are typed without any intervening characters defining a
6435 new search string, any remembered search string is used.
6436 .PP
6437 Non-incremental searches read the entire search string before starting
6438 to search for matching history lines. The search string may be
6439 typed by the user or be part of the contents of the current line.
6440 .SS "Readline Command Names"
6441 The following is a list of the names of the commands and the default
6442 key sequences to which they are bound.
6443 Command names without an accompanying key sequence are unbound by default.
6444 In the following descriptions, \fIpoint\fP refers to the current cursor
6445 position, and \fImark\fP refers to a cursor position saved by the
6446 \fBset\-mark\fP command.
6447 The text between the point and mark is referred to as the \fIregion\fP.
6448 .SS Commands for Moving
6449 .PD 0
6450 .TP
6451 .B beginning\-of\-line (C\-a)
6452 Move to the start of the current line.
6453 .TP
6454 .B end\-of\-line (C\-e)
6455 Move to the end of the line.
6456 .TP
6457 .B forward\-char (C\-f)
6458 Move forward a character.
6459 .TP
6460 .B backward\-char (C\-b)
6461 Move back a character.
6462 .TP
6463 .B forward\-word (M\-f)
6464 Move forward to the end of the next word. Words are composed of
6465 alphanumeric characters (letters and digits).
6466 .TP
6467 .B backward\-word (M\-b)
6468 Move back to the start of the current or previous word.
6469 Words are composed of alphanumeric characters (letters and digits).
6470 .TP
6471 .B shell\-forward\-word
6472 Move forward to the end of the next word.
6473 Words are delimited by non-quoted shell metacharacters.
6474 .TP
6475 .B shell\-backward\-word
6476 Move back to the start of the current or previous word.
6477 Words are delimited by non-quoted shell metacharacters.
6478 .TP
6479 .B previous\-screen\-line
6480 Attempt to move point to the same physical screen column on the previous
6481 physical screen line. This will not have the desired effect if the current
6482 readline line does not take up more than one physical line or if point is not
6483 greater than the length of the prompt plus the screen width.
6484 .TP
6485 .B next\-screen\-line
6486 Attempt to move point to the same physical screen column on the next
6487 physical screen line. This will not have the desired effect if the current
6488 readline line does not take up more than one physical line or if the length
6489 of the current readline line is not greater than the length of the prompt
6490 plus the screen width.
6491 .TP
6492 .B clear\-display (M\-C\-l)
6493 Clear the screen and, if possible, the terminal's scrollback buffer,
6494 then redraw the current line,
6495 leaving the current line at the top of the screen.
6496 .TP
6497 .B clear\-screen (C\-l)
6498 Clear the screen,
6499 then redraw the current line,
6500 leaving the current line at the top of the screen.
6501 With an argument, refresh the current line without clearing the
6502 screen.
6503 .TP
6504 .B redraw\-current\-line
6505 Refresh the current line.
6506 .PD
6507 .SS Commands for Manipulating the History
6508 .PD 0
6509 .TP
6510 .B accept\-line (Newline, Return)
6511 Accept the line regardless of where the cursor is. If this line is
6512 non-empty, add it to the history list according to the state of the
6513 .SM
6514 .B HISTCONTROL
6515 variable. If the line is a modified history
6516 line, then restore the history line to its original state.
6517 .TP
6518 .B previous\-history (C\-p)
6519 Fetch the previous command from the history list, moving back in
6520 the list.
6521 .TP
6522 .B next\-history (C\-n)
6523 Fetch the next command from the history list, moving forward in the
6524 list.
6525 .TP
6526 .B beginning\-of\-history (M\-<)
6527 Move to the first line in the history.
6528 .TP
6529 .B end\-of\-history (M\->)
6530 Move to the end of the input history, i.e., the line currently being
6531 entered.
6532 .TP
6533 .B operate\-and\-get\-next (C\-o)
6534 Accept the current line for execution and fetch the next line
6535 relative to the current line from the history for editing.
6536 A numeric argument, if supplied, specifies the history entry to use instead
6537 of the current line.
6538 .TP
6539 .B
6540 fetch\-history
6541 With a numeric argument, fetch that entry from the history list
6542 and make it the current line.
6543 Without an argument, move back to the first entry in the history list.
6544 .TP
6545 .B reverse\-search\-history (C\-r)
6546 Search backward starting at the current line and moving `up' through
6547 the history as necessary. This is an incremental search.
6548 .TP
6549 .B forward\-search\-history (C\-s)
6550 Search forward starting at the current line and moving `down' through
6551 the history as necessary. This is an incremental search.
6552 .TP
6553 .B non\-incremental\-reverse\-search\-history (M\-p)
6554 Search backward through the history starting at the current line
6555 using a non-incremental search for a string supplied by the user.
6556 .TP
6557 .B non\-incremental\-forward\-search\-history (M\-n)
6558 Search forward through the history using a non-incremental search for
6559 a string supplied by the user.
6560 .TP
6561 .B history\-search\-forward
6562 Search forward through the history for the string of characters
6563 between the start of the current line and the point.
6564 This is a non-incremental search.
6565 .TP
6566 .B history\-search\-backward
6567 Search backward through the history for the string of characters
6568 between the start of the current line and the point.
6569 This is a non-incremental search.
6570 .TP
6571 .B history\-substring\-search\-backward
6572 Search backward through the history for the string of characters
6573 between the start of the current line and the current cursor
6574 position (the \fIpoint\fP).
6575 The search string may match anywhere in a history line.
6576 This is a non-incremental search.
6577 .TP
6578 .B history\-substring\-search\-forward
6579 Search forward through the history for the string of characters
6580 between the start of the current line and the point.
6581 The search string may match anywhere in a history line.
6582 This is a non-incremental search.
6583 .TP
6584 .B yank\-nth\-arg (M\-C\-y)
6585 Insert the first argument to the previous command (usually
6586 the second word on the previous line) at point.
6587 With an argument
6588 .IR n ,
6589 insert the \fIn\fPth word from the previous command (the words
6590 in the previous command begin with word 0). A negative argument
6591 inserts the \fIn\fPth word from the end of the previous command.
6592 Once the argument \fIn\fP is computed, the argument is extracted
6593 as if the "!\fIn\fP" history expansion had been specified.
6594 .TP
6595 .B
6596 yank\-last\-arg (M\-.\^, M\-_\^)
6597 Insert the last argument to the previous command (the last word of
6598 the previous history entry).
6599 With a numeric argument, behave exactly like \fByank\-nth\-arg\fP.
6600 Successive calls to \fByank\-last\-arg\fP move back through the history
6601 list, inserting the last word (or the word specified by the argument to
6602 the first call) of each line in turn.
6603 Any numeric argument supplied to these successive calls determines
6604 the direction to move through the history. A negative argument switches
6605 the direction through the history (back or forward).
6606 The history expansion facilities are used to extract the last word,
6607 as if the "!$" history expansion had been specified.
6608 .TP
6609 .B shell\-expand\-line (M\-C\-e)
6610 Expand the line as the shell does. This
6611 performs alias and history expansion as well as all of the shell
6612 word expansions. See
6613 .SM
6614 .B HISTORY EXPANSION
6615 below for a description of history expansion.
6616 .TP
6617 .B history\-expand\-line (M\-^)
6618 Perform history expansion on the current line.
6619 See
6620 .SM
6621 .B HISTORY EXPANSION
6622 below for a description of history expansion.
6623 .TP
6624 .B magic\-space
6625 Perform history expansion on the current line and insert a space.
6626 See
6627 .SM
6628 .B HISTORY EXPANSION
6629 below for a description of history expansion.
6630 .TP
6631 .B alias\-expand\-line
6632 Perform alias expansion on the current line.
6633 See
6634 .SM
6635 .B ALIASES
6636 above for a description of alias expansion.
6637 .TP
6638 .B history\-and\-alias\-expand\-line
6639 Perform history and alias expansion on the current line.
6640 .TP
6641 .B insert\-last\-argument (M\-.\^, M\-_\^)
6642 A synonym for \fByank\-last\-arg\fP.
6643 .TP
6644 .B edit\-and\-execute\-command (C\-x C\-e)
6645 Invoke an editor on the current command line, and execute the result as shell
6646 commands.
6647 \fBBash\fP attempts to invoke
6648 .SM
6649 .BR $VISUAL ,
6650 .SM
6651 .BR $EDITOR ,
6652 and \fIemacs\fP as the editor, in that order.
6653 .PD
6654 .SS Commands for Changing Text
6655 .PD 0
6656 .TP
6657 .B \fIend\-of\-file\fP (usually C\-d)
6658 The character indicating end-of-file as set, for example, by
6659 .if t \f(CWstty\fP.
6660 .if n ``stty''.
6661 If this character is read when there are no characters
6662 on the line, and point is at the beginning of the line, readline
6663 interprets it as the end of input and returns
6664 .SM
6665 .BR EOF .
6666 .TP
6667 .B delete\-char (C\-d)
6668 Delete the character at point.
6669 If this function is bound to the
6670 same character as the tty \fBEOF\fP character, as \fBC\-d\fP
6671 commonly is, see above for the effects.
6672 .TP
6673 .B backward\-delete\-char (Rubout)
6674 Delete the character behind the cursor. When given a numeric argument,
6675 save the deleted text on the kill ring.
6676 .TP
6677 .B forward\-backward\-delete\-char
6678 Delete the character under the cursor, unless the cursor is at the
6679 end of the line, in which case the character behind the cursor is
6680 deleted.
6681 .TP
6682 .B quoted\-insert (C\-q, C\-v)
6683 Add the next character typed to the line verbatim. This is
6684 how to insert characters like \fBC\-q\fP, for example.
6685 .TP
6686 .B tab\-insert (C\-v TAB)
6687 Insert a tab character.
6688 .TP
6689 .B self\-insert (a,\ b,\ A,\ 1,\ !,\ ...)
6690 Insert the character typed.
6691 .TP
6692 .B transpose\-chars (C\-t)
6693 Drag the character before point forward over the character at point,
6694 moving point forward as well.
6695 If point is at the end of the line, then this transposes
6696 the two characters before point.
6697 Negative arguments have no effect.
6698 .TP
6699 .B transpose\-words (M\-t)
6700 Drag the word before point past the word after point,
6701 moving point over that word as well.
6702 If point is at the end of the line, this transposes
6703 the last two words on the line.
6704 .TP
6705 .B upcase\-word (M\-u)
6706 Uppercase the current (or following) word. With a negative argument,
6707 uppercase the previous word, but do not move point.
6708 .TP
6709 .B downcase\-word (M\-l)
6710 Lowercase the current (or following) word. With a negative argument,
6711 lowercase the previous word, but do not move point.
6712 .TP
6713 .B capitalize\-word (M\-c)
6714 Capitalize the current (or following) word. With a negative argument,
6715 capitalize the previous word, but do not move point.
6716 .TP
6717 .B overwrite\-mode
6718 Toggle overwrite mode. With an explicit positive numeric argument,
6719 switches to overwrite mode. With an explicit non-positive numeric
6720 argument, switches to insert mode. This command affects only
6721 \fBemacs\fP mode; \fBvi\fP mode does overwrite differently.
6722 Each call to \fIreadline()\fP starts in insert mode.
6723 In overwrite mode, characters bound to \fBself\-insert\fP replace
6724 the text at point rather than pushing the text to the right.
6725 Characters bound to \fBbackward\-delete\-char\fP replace the character
6726 before point with a space. By default, this command is unbound.
6727 .PD
6728 .SS Killing and Yanking
6729 .PD 0
6730 .TP
6731 .B kill\-line (C\-k)
6732 Kill the text from point to the end of the line.
6733 .TP
6734 .B backward\-kill\-line (C\-x Rubout)
6735 Kill backward to the beginning of the line.
6736 .TP
6737 .B unix\-line\-discard (C\-u)
6738 Kill backward from point to the beginning of the line.
6739 The killed text is saved on the kill-ring.
6740 .\" There is no real difference between this and backward-kill-line
6741 .TP
6742 .B kill\-whole\-line
6743 Kill all characters on the current line, no matter where point is.
6744 .TP
6745 .B kill\-word (M\-d)
6746 Kill from point to the end of the current word, or if between
6747 words, to the end of the next word.
6748 Word boundaries are the same as those used by \fBforward\-word\fP.
6749 .TP
6750 .B backward\-kill\-word (M\-Rubout)
6751 Kill the word behind point.
6752 Word boundaries are the same as those used by \fBbackward\-word\fP.
6753 .TP
6754 .B shell\-kill\-word
6755 Kill from point to the end of the current word, or if between
6756 words, to the end of the next word.
6757 Word boundaries are the same as those used by \fBshell\-forward\-word\fP.
6758 .TP
6759 .B shell\-backward\-kill\-word
6760 Kill the word behind point.
6761 Word boundaries are the same as those used by \fBshell\-backward\-word\fP.
6762 .TP
6763 .B unix\-word\-rubout (C\-w)
6764 Kill the word behind point, using white space as a word boundary.
6765 The killed text is saved on the kill-ring.
6766 .TP
6767 .B unix\-filename\-rubout
6768 Kill the word behind point, using white space and the slash character
6769 as the word boundaries.
6770 The killed text is saved on the kill-ring.
6771 .TP
6772 .B delete\-horizontal\-space (M\-\e)
6773 Delete all spaces and tabs around point.
6774 .TP
6775 .B kill\-region
6776 Kill the text in the current region.
6777 .TP
6778 .B copy\-region\-as\-kill
6779 Copy the text in the region to the kill buffer.
6780 .TP
6781 .B copy\-backward\-word
6782 Copy the word before point to the kill buffer.
6783 The word boundaries are the same as \fBbackward\-word\fP.
6784 .TP
6785 .B copy\-forward\-word
6786 Copy the word following point to the kill buffer.
6787 The word boundaries are the same as \fBforward\-word\fP.
6788 .TP
6789 .B yank (C\-y)
6790 Yank the top of the kill ring into the buffer at point.
6791 .TP
6792 .B yank\-pop (M\-y)
6793 Rotate the kill ring, and yank the new top. Only works following
6794 .B yank
6795 or
6796 .BR yank\-pop .
6797 .PD
6798 .SS Numeric Arguments
6799 .PD 0
6800 .TP
6801 .B digit\-argument (M\-0, M\-1, ..., M\-\-)
6802 Add this digit to the argument already accumulating, or start a new
6803 argument. M\-\- starts a negative argument.
6804 .TP
6805 .B universal\-argument
6806 This is another way to specify an argument.
6807 If this command is followed by one or more digits, optionally with a
6808 leading minus sign, those digits define the argument.
6809 If the command is followed by digits, executing
6810 .B universal\-argument
6811 again ends the numeric argument, but is otherwise ignored.
6812 As a special case, if this command is immediately followed by a
6813 character that is neither a digit nor minus sign, the argument count
6814 for the next command is multiplied by four.
6815 The argument count is initially one, so executing this function the
6816 first time makes the argument count four, a second time makes the
6817 argument count sixteen, and so on.
6818 .PD
6819 .SS Completing
6820 .PD 0
6821 .TP
6822 .B complete (TAB)
6823 Attempt to perform completion on the text before point.
6824 .B Bash
6825 attempts completion treating the text as a variable (if the
6826 text begins with \fB$\fP), username (if the text begins with
6827 \fB~\fP), hostname (if the text begins with \fB@\fP), or
6828 command (including aliases and functions) in turn. If none
6829 of these produces a match, filename completion is attempted.
6830 .TP
6831 .B possible\-completions (M\-?)
6832 List the possible completions of the text before point.
6833 .TP
6834 .B insert\-completions (M\-*)
6835 Insert all completions of the text before point
6836 that would have been generated by
6837 \fBpossible\-completions\fP.
6838 .TP
6839 .B menu\-complete
6840 Similar to \fBcomplete\fP, but replaces the word to be completed
6841 with a single match from the list of possible completions.
6842 Repeated execution of \fBmenu\-complete\fP steps through the list
6843 of possible completions, inserting each match in turn.
6844 At the end of the list of completions, the bell is rung
6845 (subject to the setting of \fBbell\-style\fP)
6846 and the original text is restored.
6847 An argument of \fIn\fP moves \fIn\fP positions forward in the list
6848 of matches; a negative argument may be used to move backward
6849 through the list.
6850 This command is intended to be bound to \fBTAB\fP, but is unbound
6851 by default.
6852 .TP
6853 .B menu\-complete\-backward
6854 Identical to \fBmenu\-complete\fP, but moves backward through the list
6855 of possible completions, as if \fBmenu\-complete\fP had been given a
6856 negative argument. This command is unbound by default.
6857 .TP
6858 .B delete\-char\-or\-list
6859 Deletes the character under the cursor if not at the beginning or
6860 end of the line (like \fBdelete\-char\fP).
6861 If at the end of the line, behaves identically to
6862 \fBpossible\-completions\fP.
6863 This command is unbound by default.
6864 .TP
6865 .B complete\-filename (M\-/)
6866 Attempt filename completion on the text before point.
6867 .TP
6868 .B possible\-filename\-completions (C\-x /)
6869 List the possible completions of the text before point,
6870 treating it as a filename.
6871 .TP
6872 .B complete\-username (M\-~)
6873 Attempt completion on the text before point, treating
6874 it as a username.
6875 .TP
6876 .B possible\-username\-completions (C\-x ~)
6877 List the possible completions of the text before point,
6878 treating it as a username.
6879 .TP
6880 .B complete\-variable (M\-$)
6881 Attempt completion on the text before point, treating
6882 it as a shell variable.
6883 .TP
6884 .B possible\-variable\-completions (C\-x $)
6885 List the possible completions of the text before point,
6886 treating it as a shell variable.
6887 .TP
6888 .B complete\-hostname (M\-@)
6889 Attempt completion on the text before point, treating
6890 it as a hostname.
6891 .TP
6892 .B possible\-hostname\-completions (C\-x @)
6893 List the possible completions of the text before point,
6894 treating it as a hostname.
6895 .TP
6896 .B complete\-command (M\-!)
6897 Attempt completion on the text before point, treating
6898 it as a command name. Command completion attempts to
6899 match the text against aliases, reserved words, shell
6900 functions, shell builtins, and finally executable filenames,
6901 in that order.
6902 .TP
6903 .B possible\-command\-completions (C\-x !)
6904 List the possible completions of the text before point,
6905 treating it as a command name.
6906 .TP
6907 .B dynamic\-complete\-history (M\-TAB)
6908 Attempt completion on the text before point, comparing
6909 the text against lines from the history list for possible
6910 completion matches.
6911 .TP
6912 .B dabbrev\-expand
6913 Attempt menu completion on the text before point, comparing
6914 the text against lines from the history list for possible
6915 completion matches.
6916 .TP
6917 .B complete\-into\-braces (M\-{)
6918 Perform filename completion and insert the list of possible completions
6919 enclosed within braces so the list is available to the shell (see
6920 .B Brace Expansion
6921 above).
6922 .PD
6923 .SS Keyboard Macros
6924 .PD 0
6925 .TP
6926 .B start\-kbd\-macro (C\-x (\^)
6927 Begin saving the characters typed into the current keyboard macro.
6928 .TP
6929 .B end\-kbd\-macro (C\-x )\^)
6930 Stop saving the characters typed into the current keyboard macro
6931 and store the definition.
6932 .TP
6933 .B call\-last\-kbd\-macro (C\-x e)
6934 Re-execute the last keyboard macro defined, by making the characters
6935 in the macro appear as if typed at the keyboard.
6936 .TP
6937 .B print\-last\-kbd\-macro ()
6938 Print the last keyboard macro defined in a format suitable for the
6939 \fIinputrc\fP file.
6940 .PD
6941 .SS Miscellaneous
6942 .PD 0
6943 .TP
6944 .B re\-read\-init\-file (C\-x C\-r)
6945 Read in the contents of the \fIinputrc\fP file, and incorporate
6946 any bindings or variable assignments found there.
6947 .TP
6948 .B abort (C\-g)
6949 Abort the current editing command and
6950 ring the terminal's bell (subject to the setting of
6951 .BR bell\-style ).
6952 .TP
6953 .B do\-lowercase\-version (M\-A, M\-B, M\-\fIx\fP, ...)
6954 If the metafied character \fIx\fP is uppercase, run the command
6955 that is bound to the corresponding metafied lowercase character.
6956 The behavior is undefined if \fIx\fP is already lowercase.
6957 .TP
6958 .B prefix\-meta (ESC)
6959 Metafy the next character typed.
6960 .SM
6961 .B ESC
6962 .B f
6963 is equivalent to
6964 .BR Meta\-f .
6965 .TP
6966 .B undo (C\-_, C\-x C\-u)
6967 Incremental undo, separately remembered for each line.
6968 .TP
6969 .B revert\-line (M\-r)
6970 Undo all changes made to this line. This is like executing the
6971 .B undo
6972 command enough times to return the line to its initial state.
6973 .TP
6974 .B tilde\-expand (M\-&)
6975 Perform tilde expansion on the current word.
6976 .TP
6977 .B set\-mark (C\-@, M\-<space>)
6978 Set the mark to the point. If a
6979 numeric argument is supplied, the mark is set to that position.
6980 .TP
6981 .B exchange\-point\-and\-mark (C\-x C\-x)
6982 Swap the point with the mark. The current cursor position is set to
6983 the saved position, and the old cursor position is saved as the mark.
6984 .TP
6985 .B character\-search (C\-])
6986 A character is read and point is moved to the next occurrence of that
6987 character. A negative argument searches for previous occurrences.
6988 .TP
6989 .B character\-search\-backward (M\-C\-])
6990 A character is read and point is moved to the previous occurrence of that
6991 character. A negative argument searches for subsequent occurrences.
6992 .TP
6993 .B skip\-csi\-sequence
6994 Read enough characters to consume a multi-key sequence such as those
6995 defined for keys like Home and End. Such sequences begin with a
6996 Control Sequence Indicator (CSI), usually ESC\-[. If this sequence is
6997 bound to "\e[", keys producing such sequences will have no effect
6998 unless explicitly bound to a readline command, instead of inserting
6999 stray characters into the editing buffer. This is unbound by default,
7000 but usually bound to ESC\-[.
7001 .TP
7002 .B insert\-comment (M\-#)
7003 Without a numeric argument, the value of the readline
7004 .B comment\-begin
7005 variable is inserted at the beginning of the current line.
7006 If a numeric argument is supplied, this command acts as a toggle: if
7007 the characters at the beginning of the line do not match the value
7008 of \fBcomment\-begin\fP, the value is inserted, otherwise
7009 the characters in \fBcomment\-begin\fP are deleted from the beginning of
7010 the line.
7011 In either case, the line is accepted as if a newline had been typed.
7012 The default value of
7013 \fBcomment\-begin\fP causes this command to make the current line
7014 a shell comment.
7015 If a numeric argument causes the comment character to be removed, the line
7016 will be executed by the shell.
7017 .TP
7018 .B spell\-correct\-word (C\-x s)
7019 Perform spelling correction on the current word, treating it as a directory
7020 or filename, in the same way as the \fBcdspell\fP shell option.
7021 Word boundaries are the same as those used by \fBshell\-forward\-word\fP.
7022 .TP
7023 .B glob\-complete\-word (M\-g)
7024 The word before point is treated as a pattern for pathname expansion,
7025 with an asterisk implicitly appended. This pattern is used to
7026 generate a list of matching filenames for possible completions.
7027 .TP
7028 .B glob\-expand\-word (C\-x *)
7029 The word before point is treated as a pattern for pathname expansion,
7030 and the list of matching filenames is inserted, replacing the word.
7031 If a numeric argument is supplied, an asterisk is appended before
7032 pathname expansion.
7033 .TP
7034 .B glob\-list\-expansions (C\-x g)
7035 The list of expansions that would have been generated by
7036 .B glob\-expand\-word
7037 is displayed, and the line is redrawn.
7038 If a numeric argument is supplied, an asterisk is appended before
7039 pathname expansion.
7040 .TP
7041 .B dump\-functions
7042 Print all of the functions and their key bindings to the
7043 readline output stream. If a numeric argument is supplied,
7044 the output is formatted in such a way that it can be made part
7045 of an \fIinputrc\fP file.
7046 .TP
7047 .B dump\-variables
7048 Print all of the settable readline variables and their values to the
7049 readline output stream. If a numeric argument is supplied,
7050 the output is formatted in such a way that it can be made part
7051 of an \fIinputrc\fP file.
7052 .TP
7053 .B dump\-macros
7054 Print all of the readline key sequences bound to macros and the
7055 strings they output. If a numeric argument is supplied,
7056 the output is formatted in such a way that it can be made part
7057 of an \fIinputrc\fP file.
7058 .TP
7059 .B display\-shell\-version (C\-x C\-v)
7060 Display version information about the current instance of
7061 .BR bash .
7062 .PD
7063 .SS Programmable Completion
7064 When word completion is attempted for an argument to a command for
7065 which a completion specification (a \fIcompspec\fP) has been defined
7066 using the \fBcomplete\fP builtin (see
7067 .SM
7068 .B "SHELL BUILTIN COMMANDS"
7069 below), the programmable completion facilities are invoked.
7070 .PP
7071 First, the command name is identified.
7072 If the command word is the empty string (completion attempted at the
7073 beginning of an empty line), any compspec defined with
7074 the \fB\-E\fP option to \fBcomplete\fP is used.
7075 If a compspec has been defined for that command, the
7076 compspec is used to generate the list of possible completions for the word.
7077 If the command word is a full pathname, a compspec for the full
7078 pathname is searched for first.
7079 If no compspec is found for the full pathname, an attempt is made to
7080 find a compspec for the portion following the final slash.
7081 If those searches do not result in a compspec, any compspec defined with
7082 the \fB\-D\fP option to \fBcomplete\fP is used as the default.
7083 If there is no default compspec, \fBbash\fP attempts alias expansion
7084 on the command word as a final resort, and attempts to find a compspec
7085 for the command word from any successful expansion.
7086 .PP
7087 Once a compspec has been found, it is used to generate the list of
7088 matching words.
7089 If a compspec is not found, the default \fBbash\fP completion as
7090 described above under \fBCompleting\fP is performed.
7091 .PP
7092 First, the actions specified by the compspec are used.
7093 Only matches which are prefixed by the word being completed are
7094 returned.
7095 When the
7096 .B \-f
7097 or
7098 .B \-d
7099 option is used for filename or directory name completion, the shell
7100 variable
7101 .SM
7102 .B FIGNORE
7103 is used to filter the matches.
7104 .PP
7105 Any completions specified by a pathname expansion pattern to the
7106 \fB\-G\fP option are generated next.
7107 The words generated by the pattern need not match the word
7108 being completed.
7109 The
7110 .SM
7111 .B GLOBIGNORE
7112 shell variable is not used to filter the matches, but the
7113 .SM
7114 .B FIGNORE
7115 variable is used.
7116 .PP
7117 Next, the string specified as the argument to the \fB\-W\fP option
7118 is considered.
7119 The string is first split using the characters in the
7120 .SM
7121 .B IFS
7122 special variable as delimiters.
7123 Shell quoting is honored.
7124 Each word is then expanded using
7125 brace expansion, tilde expansion, parameter and variable expansion,
7126 command substitution, and arithmetic expansion,
7127 as described above under
7128 .SM
7129 .BR EXPANSION .
7130 The results are split using the rules described above under
7131 \fBWord Splitting\fP.
7132 The results of the expansion are prefix-matched against the word being
7133 completed, and the matching words become the possible completions.
7134 .PP
7135 After these matches have been generated, any shell function or command
7136 specified with the \fB\-F\fP and \fB\-C\fP options is invoked.
7137 When the command or function is invoked, the
7138 .SM
7139 .BR COMP_LINE ,
7140 .SM
7141 .BR COMP_POINT ,
7142 .SM
7143 .BR COMP_KEY ,
7144 and
7145 .SM
7146 .B COMP_TYPE
7147 variables are assigned values as described above under
7148 \fBShell Variables\fP.
7149 If a shell function is being invoked, the
7150 .SM
7151 .B COMP_WORDS
7152 and
7153 .SM
7154 .B COMP_CWORD
7155 variables are also set.
7156 When the function or command is invoked,
7157 the first argument (\fB$1\fP) is the name of the command whose arguments are
7158 being completed,
7159 the second argument (\fB$2\fP) is the word being completed,
7160 and the third argument (\fB$3\fP) is the word preceding the word being
7161 completed on the current command line.
7162 No filtering of the generated completions against the word being completed
7163 is performed; the function or command has complete freedom in generating
7164 the matches.
7165 .PP
7166 Any function specified with \fB\-F\fP is invoked first.
7167 The function may use any of the shell facilities, including the
7168 \fBcompgen\fP builtin described below, to generate the matches.
7169 It must put the possible completions in the
7170 .SM
7171 .B COMPREPLY
7172 array variable, one per array element.
7173 .PP
7174 Next, any command specified with the \fB\-C\fP option is invoked
7175 in an environment equivalent to command substitution.
7176 It should print a list of completions, one per line, to the
7177 standard output.
7178 Backslash may be used to escape a newline, if necessary.
7179 .PP
7180 After all of the possible completions are generated, any filter
7181 specified with the \fB\-X\fP option is applied to the list.
7182 The filter is a pattern as used for pathname expansion; a \fB&\fP
7183 in the pattern is replaced with the text of the word being completed.
7184 A literal \fB&\fP may be escaped with a backslash; the backslash
7185 is removed before attempting a match.
7186 Any completion that matches the pattern will be removed from the list.
7187 A leading \fB!\fP negates the pattern; in this case any completion
7188 not matching the pattern will be removed.
7189 If the
7190 .B nocasematch
7191 shell option is enabled, the match is performed without regard to the case
7192 of alphabetic characters.
7193 .PP
7194 Finally, any prefix and suffix specified with the \fB\-P\fP and \fB\-S\fP
7195 options are added to each member of the completion list, and the result is
7196 returned to the readline completion code as the list of possible
7197 completions.
7198 .PP
7199 If the previously-applied actions do not generate any matches, and the
7200 \fB\-o dirnames\fP option was supplied to \fBcomplete\fP when the
7201 compspec was defined, directory name completion is attempted.
7202 .PP
7203 If the \fB\-o plusdirs\fP option was supplied to \fBcomplete\fP when the
7204 compspec was defined, directory name completion is attempted and any
7205 matches are added to the results of the other actions.
7206 .PP
7207 By default, if a compspec is found, whatever it generates is returned
7208 to the completion code as the full set of possible completions.
7209 The default \fBbash\fP completions are not attempted, and the readline
7210 default of filename completion is disabled.
7211 If the \fB\-o bashdefault\fP option was supplied to \fBcomplete\fP when
7212 the compspec was defined, the \fBbash\fP default completions are attempted
7213 if the compspec generates no matches.
7214 If the \fB\-o default\fP option was supplied to \fBcomplete\fP when the
7215 compspec was defined, readline's default completion will be performed
7216 if the compspec (and, if attempted, the default \fBbash\fP completions)
7217 generate no matches.
7218 .PP
7219 When a compspec indicates that directory name completion is desired,
7220 the programmable completion functions force readline to append a slash
7221 to completed names which are symbolic links to directories, subject to
7222 the value of the \fBmark\-directories\fP readline variable, regardless
7223 of the setting of the \fBmark-symlinked\-directories\fP readline variable.
7224 .PP
7225 There is some support for dynamically modifying completions. This is
7226 most useful when used in combination with a default completion specified
7227 with \fBcomplete \-D\fP.
7228 It's possible for shell functions executed as completion
7229 handlers to indicate that completion should be retried by returning an
7230 exit status of 124. If a shell function returns 124, and changes
7231 the compspec associated with the command on which completion is being
7232 attempted (supplied as the first argument when the function is executed),
7233 programmable completion restarts from the beginning, with an
7234 attempt to find a new compspec for that command. This allows a set of
7235 completions to be built dynamically as completion is attempted, rather than
7236 being loaded all at once.
7237 .PP
7238 For instance, assuming that there is a library of compspecs, each kept in a
7239 file corresponding to the name of the command, the following default
7240 completion function would load completions dynamically:
7241 .PP
7242 \f(CW_completion_loader()
7243 .br
7244 {
7245 .br
7246 . "/etc/bash_completion.d/$1.sh" >/dev/null 2>&1 && return 124
7247 .br
7248 }
7249 .br
7250 complete -D -F _completion_loader -o bashdefault -o default
7251 .br
7252 \fP
7253 .SH HISTORY
7254 When the
7255 .B \-o history
7256 option to the
7257 .B set
7258 builtin is enabled, the shell provides access to the
7259 \fIcommand history\fP,
7260 the list of commands previously typed.
7261 The value of the
7262 .SM
7263 .B HISTSIZE
7264 variable is used as the
7265 number of commands to save in a history list.
7266 The text of the last
7267 .SM
7268 .B HISTSIZE
7269 commands (default 500) is saved. The shell
7270 stores each command in the history list prior to parameter and
7271 variable expansion (see
7272 .SM
7273 .B EXPANSION
7274 above) but after history expansion is performed, subject to the
7275 values of the shell variables
7276 .SM
7277 .B HISTIGNORE
7278 and
7279 .SM
7280 .BR HISTCONTROL .
7281 .PP
7282 On startup, the history is initialized from the file named by
7283 the variable
7284 .SM
7285 .B HISTFILE
7286 (default \fI~/.bash_history\fP).
7287 The file named by the value of
7288 .SM
7289 .B HISTFILE
7290 is truncated, if necessary, to contain no more than
7291 the number of lines specified by the value of
7292 .SM
7293 .BR HISTFILESIZE .
7294 If \fBHISTFILESIZE\fP is unset, or set to null, a non-numeric value,
7295 or a numeric value less than zero, the history file is not truncated.
7296 When the history file is read,
7297 lines beginning with the history comment character followed immediately
7298 by a digit are interpreted as timestamps for the following history line.
7299 These timestamps are optionally displayed depending on the value of the
7300 .SM
7301 .B HISTTIMEFORMAT
7302 variable.
7303 When a shell with history enabled exits, the last
7304 .SM
7305 .B $HISTSIZE
7306 lines are copied from the history list to
7307 .SM
7308 .BR $HISTFILE .
7309 If the
7310 .B histappend
7311 shell option is enabled
7312 (see the description of
7313 .B shopt
7314 under
7315 .SM
7316 .B "SHELL BUILTIN COMMANDS"
7317 below), the lines are appended to the history file,
7318 otherwise the history file is overwritten.
7319 If
7320 .SM
7321 .B HISTFILE
7322 is unset, or if the history file is unwritable, the history is
7323 not saved.
7324 If the
7325 .SM
7326 .B HISTTIMEFORMAT
7327 variable is set, time stamps are written to the history file, marked
7328 with the history comment character, so
7329 they may be preserved across shell sessions.
7330 This uses the history comment character to distinguish timestamps from
7331 other history lines.
7332 After saving the history, the history file is truncated
7333 to contain no more than
7334 .SM
7335 .B HISTFILESIZE
7336 lines. If
7337 .SM
7338 .B HISTFILESIZE
7339 is unset, or set to null, a non-numeric value,
7340 or a numeric value less than zero, the history file is not truncated.
7341 .PP
7342 The builtin command
7343 .B fc
7344 (see
7345 .SM
7346 .B SHELL BUILTIN COMMANDS
7347 below) may be used to list or edit and re-execute a portion of
7348 the history list.
7349 The
7350 .B history
7351 builtin may be used to display or modify the history list and
7352 manipulate the history file.
7353 When using command-line editing, search commands
7354 are available in each editing mode that provide access to the
7355 history list.
7356 .PP
7357 The shell allows control over which commands are saved on the history
7358 list. The
7359 .SM
7360 .B HISTCONTROL
7361 and
7362 .SM
7363 .B HISTIGNORE
7364 variables may be set to cause the shell to save only a subset of the
7365 commands entered.
7366 The
7367 .B cmdhist
7368 shell option, if enabled, causes the shell to attempt to save each
7369 line of a multi-line command in the same history entry, adding
7370 semicolons where necessary to preserve syntactic correctness.
7371 The
7372 .B lithist
7373 shell option causes the shell to save the command with embedded newlines
7374 instead of semicolons. See the description of the
7375 .B shopt
7376 builtin below under
7377 .SM
7378 .B "SHELL BUILTIN COMMANDS"
7379 for information on setting and unsetting shell options.
7380 .SH "HISTORY EXPANSION"
7381 The shell supports a history expansion feature that
7382 is similar to the history expansion in
7383 .BR csh .
7384 This section describes what syntax features are available. This
7385 feature is enabled by default for interactive shells, and can be
7386 disabled using the
7387 .B +H
7388 option to the
7389 .B set
7390 builtin command (see
7391 .SM
7392 .B SHELL BUILTIN COMMANDS
7393 below). Non-interactive shells do not perform history expansion
7394 by default.
7395 .PP
7396 History expansions introduce words from the history list into
7397 the input stream, making it easy to repeat commands, insert the
7398 arguments to a previous command into the current input line, or
7399 fix errors in previous commands quickly.
7400 .PP
7401 History expansion is performed immediately after a complete line
7402 is read, before the shell breaks it into words, and is performed
7403 on each line individually without taking quoting on previous lines into
7404 account.
7405 It takes place in two parts.
7406 The first is to determine which line from the history list
7407 to use during substitution.
7408 The second is to select portions of that line for inclusion into
7409 the current one.
7410 The line selected from the history is the \fIevent\fP,
7411 and the portions of that line that are acted upon are \fIwords\fP.
7412 Various \fImodifiers\fP are available to manipulate the selected words.
7413 The line is broken into words in the same fashion as when reading input,
7414 so that several \fImetacharacter\fP-separated words surrounded by
7415 quotes are considered one word.
7416 History expansions are introduced by the appearance of the
7417 history expansion character, which is \^\fB!\fP\^ by default.
7418 Only backslash (\^\fB\e\fP\^) and single quotes can quote
7419 the history expansion character, but the history expansion character is
7420 also treated as quoted if it immediately precedes the closing double quote
7421 in a double-quoted string.
7422 .PP
7423 Several characters inhibit history expansion if found immediately
7424 following the history expansion character, even if it is unquoted:
7425 space, tab, newline, carriage return, and \fB=\fP.
7426 If the \fBextglob\fP shell option is enabled, \fB(\fP will also
7427 inhibit expansion.
7428 .PP
7429 Several shell options settable with the
7430 .B shopt
7431 builtin may be used to tailor the behavior of history expansion.
7432 If the
7433 .B histverify
7434 shell option is enabled (see the description of the
7435 .B shopt
7436 builtin below), and
7437 .B readline
7438 is being used, history substitutions are not immediately passed to
7439 the shell parser.
7440 Instead, the expanded line is reloaded into the
7441 .B readline
7442 editing buffer for further modification.
7443 If
7444 .B readline
7445 is being used, and the
7446 .B histreedit
7447 shell option is enabled, a failed history substitution will be reloaded
7448 into the
7449 .B readline
7450 editing buffer for correction.
7451 The
7452 .B \-p
7453 option to the
7454 .B history
7455 builtin command may be used to see what a history expansion will
7456 do before using it.
7457 The
7458 .B \-s
7459 option to the
7460 .B history
7461 builtin may be used to add commands to the end of the history list
7462 without actually executing them, so that they are available for
7463 subsequent recall.
7464 .PP
7465 The shell allows control of the various characters used by the
7466 history expansion mechanism (see the description of
7467 .B histchars
7468 above under
7469 .BR "Shell Variables" ).
7470 The shell uses
7471 the history comment character to mark history timestamps when
7472 writing the history file.
7473 .SS Event Designators
7474 An event designator is a reference to a command line entry in the
7475 history list.
7476 Unless the reference is absolute, events are relative to the current
7477 position in the history list.
7478 .PP
7479 .PD 0
7480 .TP
7481 .B !
7482 Start a history substitution, except when followed by a
7483 .BR blank ,
7484 newline, carriage return, =
7485 or ( (when the \fBextglob\fP shell option is enabled using
7486 the \fBshopt\fP builtin).
7487 .TP
7488 .B !\fIn\fR
7489 Refer to command line
7490 .IR n .
7491 .TP
7492 .B !\-\fIn\fR
7493 Refer to the current command minus
7494 .IR n .
7495 .TP
7496 .B !!
7497 Refer to the previous command. This is a synonym for `!\-1'.
7498 .TP
7499 .B !\fIstring\fR
7500 Refer to the most recent command preceding the current position in the
7501 history list starting with
7502 .IR string .
7503 .TP
7504 .B !?\fIstring\fR\fB[?]\fR
7505 Refer to the most recent command preceding the current position in the
7506 history list containing
7507 .IR string .
7508 The trailing \fB?\fP may be omitted if
7509 .I string
7510 is followed immediately by a newline.
7511 If \fIstring\fP is missing, the string from the most recent search is used;
7512 it is an error if there is no previous search string.
7513 .TP
7514 .B \d\s+2^\s-2\u\fIstring1\fP\d\s+2^\s-2\u\fIstring2\fP\d\s+2^\s-2\u
7515 Quick substitution. Repeat the previous command, replacing
7516 .I string1
7517 with
7518 .IR string2 .
7519 Equivalent to
7520 ``!!:s\d\s+2^\s-2\u\fIstring1\fP\d\s+2^\s-2\u\fIstring2\fP\d\s+2^\s-2\u''
7521 (see \fBModifiers\fP below).
7522 .TP
7523 .B !#
7524 The entire command line typed so far.
7525 .PD
7526 .SS Word Designators
7527 Word designators are used to select desired words from the event.
7528 A
7529 .B :
7530 separates the event specification from the word designator.
7531 It may be omitted if the word designator begins with a
7532 .BR ^ ,
7533 .BR $ ,
7534 .BR * ,
7535 .BR \- ,
7536 or
7537 .BR % .
7538 Words are numbered from the beginning of the line,
7539 with the first word being denoted by 0 (zero).
7540 Words are inserted into the current line separated by single spaces.
7541 .PP
7542 .PD 0
7543 .TP
7544 .B 0 (zero)
7545 The zeroth word. For the shell, this is the command
7546 word.
7547 .TP
7548 .I n
7549 The \fIn\fRth word.
7550 .TP
7551 .B ^
7552 The first argument. That is, word 1.
7553 .TP
7554 .B $
7555 The last word. This is usually the last argument, but will expand to the
7556 zeroth word if there is only one word in the line.
7557 .TP
7558 .B %
7559 The first word matched by the most recent `?\fIstring\fR?' search,
7560 if the search string begins with a character that is part of a word.
7561 .TP
7562 .I x\fB\-\fPy
7563 A range of words; `\-\fIy\fR' abbreviates `0\-\fIy\fR'.
7564 .TP
7565 .B *
7566 All of the words but the zeroth. This is a synonym
7567 for `\fI1\-$\fP'. It is not an error to use
7568 .B *
7569 if there is just one
7570 word in the event; the empty string is returned in that case.
7571 .TP
7572 .B x*
7573 Abbreviates \fIx\-$\fP.
7574 .TP
7575 .B x\-
7576 Abbreviates \fIx\-$\fP like \fBx*\fP, but omits the last word.
7577 If \fBx\fP is missing, it defaults to 0.
7578 .PD
7579 .PP
7580 If a word designator is supplied without an event specification, the
7581 previous command is used as the event.
7582 .SS Modifiers
7583 After the optional word designator, there may appear a sequence of
7584 one or more of the following modifiers, each preceded by a `:'.
7585 These modify, or edit, the word or words selected from the history event.
7586 .PP
7587 .PD 0
7588 .TP
7589 .B h
7590 Remove a trailing filename component, leaving only the head.
7591 .TP
7592 .B t
7593 Remove all leading filename components, leaving the tail.
7594 .TP
7595 .B r
7596 Remove a trailing suffix of the form \fI.xxx\fP, leaving the
7597 basename.
7598 .TP
7599 .B e
7600 Remove all but the trailing suffix.
7601 .TP
7602 .B p
7603 Print the new command but do not execute it.
7604 .TP
7605 .B q
7606 Quote the substituted words, escaping further substitutions.
7607 .TP
7608 .B x
7609 Quote the substituted words as with
7610 .BR q ,
7611 but break into words at
7612 .B blanks
7613 and newlines.
7614 The \fBq\fP and \fBx\fP modifiers are mutually exclusive; the last one
7615 supplied is used.
7616 .TP
7617 .B s/\fIold\fP/\fInew\fP/
7618 Substitute
7619 .I new
7620 for the first occurrence of
7621 .I old
7622 in the event line.
7623 Any character may be used as the delimiter in place of /.
7624 The final delimiter is optional if it is the last character of the
7625 event line.
7626 The delimiter may be quoted in
7627 .I old
7628 and
7629 .I new
7630 with a single backslash. If & appears in
7631 .IR new ,
7632 it is replaced by
7633 .IR old .
7634 A single backslash will quote the &.
7635 If
7636 .I old
7637 is null, it is set to the last
7638 .I old
7639 substituted, or, if no previous history substitutions took place,
7640 the last
7641 .I string
7642 in a
7643 .B !?\fIstring\fR\fB[?]\fR
7644 search.
7645 If
7646 .I new
7647 is null, each matching
7648 .I old
7649 is deleted.
7650 .TP
7651 .B &
7652 Repeat the previous substitution.
7653 .TP
7654 .B g
7655 Cause changes to be applied over the entire event line. This is
7656 used in conjunction with `\fB:s\fP' (e.g., `\fB:gs/\fIold\fP/\fInew\fP/\fR')
7657 or `\fB:&\fP'. If used with
7658 `\fB:s\fP', any delimiter can be used
7659 in place of /, and the final delimiter is optional
7660 if it is the last character of the event line.
7661 An \fBa\fP may be used as a synonym for \fBg\fP.
7662 .TP
7663 .B G
7664 Apply the following `\fBs\fP' or `\fB&\fP' modifier once to each word
7665 in the event line.
7666 .PD
7667 .SH "SHELL BUILTIN COMMANDS"
7668 .\" start of bash_builtins
7669 .zZ
7670 .PP
7671 Unless otherwise noted, each builtin command documented in this
7672 section as accepting options preceded by
7673 .B \-
7674 accepts
7675 .B \-\-
7676 to signify the end of the options.
7677 The \fB:\fP, \fBtrue\fP, \fBfalse\fP, and \fBtest\fP/\fB[\fP builtins
7678 do not accept options and do not treat \fB\-\-\fP specially.
7679 The \fBexit\fP, \fBlogout\fP, \fBreturn\fP,
7680 \fBbreak\fP, \fBcontinue\fP, \fBlet\fP,
7681 and \fBshift\fP builtins accept and process arguments beginning with
7682 \fB\-\fP without requiring \fB\-\-\fP.
7683 Other builtins that accept arguments but are not specified as accepting
7684 options interpret arguments beginning with \fB\-\fP as invalid options and
7685 require \fB\-\-\fP to prevent this interpretation.
7686 .sp .5
7687 .PD 0
7688 .TP
7689 \fB:\fP [\fIarguments\fP]
7690 .PD
7691 No effect; the command does nothing beyond expanding
7692 .I arguments
7693 and performing any specified
7694 redirections.
7695 The return status is zero.
7696 .TP
7697 \fB .\| \fP \fIfilename\fP [\fIarguments\fP]
7698 .PD 0
7699 .TP
7700 \fBsource\fP \fIfilename\fP [\fIarguments\fP]
7701 .PD
7702 Read and execute commands from
7703 .I filename
7704 in the current
7705 shell environment and return the exit status of the last command
7706 executed from
7707 .IR filename .
7708 If
7709 .I filename
7710 does not contain a slash, filenames in
7711 .SM
7712 .B PATH
7713 are used to find the directory containing
7714 .IR filename ,
7715 but \fIfilename\fP does not need to be executable.
7716 The file searched for in
7717 .SM
7718 .B PATH
7719 need not be executable.
7720 When \fBbash\fP is not in \fIposix mode\fP, it searches
7721 the current directory if no file is found in
7722 .SM
7723 .BR PATH .
7724 If the
7725 .B sourcepath
7726 option to the
7727 .B shopt
7728 builtin command is turned off, the
7729 .SM
7730 .B PATH
7731 is not searched.
7732 If any \fIarguments\fP are supplied, they become the positional
7733 parameters when \fIfilename\fP is executed. Otherwise the positional
7734 parameters are unchanged.
7735 If the \fB\-T\fP option is enabled, \fB.\fP inherits any trap on
7736 \fBDEBUG\fP; if it is not, any \fBDEBUG\fP trap string is saved and
7737 restored around the call to \fB.\fP, and \fB.\fP unsets the
7738 \fBDEBUG\fP trap while it executes.
7739 If \fB\-T\fP is not set, and the sourced file changes
7740 the \fBDEBUG\fP trap, the new value is retained when \fB.\fP completes.
7741 The return status is the status of the last command exited within
7742 the script (0 if no commands are executed), and false if
7743 .I filename
7744 is not found or cannot be read.
7745 .TP
7746 \fBalias\fP [\fB\-p\fP] [\fIname\fP[=\fIvalue\fP] ...]
7747 \fBAlias\fP with no arguments or with the
7748 .B \-p
7749 option prints the list of aliases in the form
7750 \fBalias\fP \fIname\fP=\fIvalue\fP on standard output.
7751 When arguments are supplied, an alias is defined for
7752 each \fIname\fP whose \fIvalue\fP is given.
7753 A trailing space in \fIvalue\fP causes the next word to be
7754 checked for alias substitution when the alias is expanded.
7755 For each \fIname\fP in the argument list for which no \fIvalue\fP
7756 is supplied, the name and value of the alias is printed.
7757 \fBAlias\fP returns true unless a \fIname\fP is given for which
7758 no alias has been defined.
7759 .TP
7760 \fBbg\fP [\fIjobspec\fP ...]
7761 Resume each suspended job \fIjobspec\fP in the background, as if it
7762 had been started with
7763 .BR & .
7764 If
7765 .I jobspec
7766 is not present, the shell's notion of the \fIcurrent job\fP is used.
7767 .B bg
7768 .I jobspec
7769 returns 0 unless run when job control is disabled or, when run with
7770 job control enabled, any specified \fIjobspec\fP was not found
7771 or was started without job control.
7772 .TP
7773 \fBbind\fP [\fB\-m\fP \fIkeymap\fP] [\fB\-lpsvPSVX\fP]
7774 .PD 0
7775 .TP
7776 \fBbind\fP [\fB\-m\fP \fIkeymap\fP] [\fB\-q\fP \fIfunction\fP] [\fB\-u\fP \fIfunction\fP] [\fB\-r\fP \fIkeyseq\fP]
7777 .TP
7778 \fBbind\fP [\fB\-m\fP \fIkeymap\fP] \fB\-f\fP \fIfilename\fP
7779 .TP
7780 \fBbind\fP [\fB\-m\fP \fIkeymap\fP] \fB\-x\fP \fIkeyseq\fP:\fIshell\-command\fP
7781 .TP
7782 \fBbind\fP [\fB\-m\fP \fIkeymap\fP] \fIkeyseq\fP:\fIfunction\-name\fP
7783 .TP
7784 \fBbind\fP [\fB\-m\fP \fIkeymap\fP] \fIkeyseq\fP:\fIreadline\-command\fP
7785 .TP
7786 \fBbind\fP \fIreadline-command-line\fP
7787 .PD
7788 Display current
7789 .B readline
7790 key and function bindings, bind a key sequence to a
7791 .B readline
7792 function or macro, or set a
7793 .B readline
7794 variable.
7795 Each non-option argument is a command as it would appear in a
7796 .B readline
7797 initialization file such as
7798 .IR .inputrc ,
7799 but each binding or command must be passed as a separate argument;
7800 e.g., '"\eC\-x\eC\-r": re\-read\-init\-file'.
7801 Options, if supplied, have the following meanings:
7802 .RS
7803 .PD 0
7804 .TP
7805 .B \-m \fIkeymap\fP
7806 Use
7807 .I keymap
7808 as the keymap to be affected by the subsequent bindings.
7809 Acceptable
7810 .I keymap
7811 names are
7812 \fIemacs, emacs\-standard, emacs\-meta, emacs\-ctlx, vi,
7813 vi\-move, vi\-command\fP, and
7814 .IR vi\-insert .
7815 \fIvi\fP is equivalent to \fIvi\-command\fP (\fIvi\-move\fP is also
7816 a synonym); \fIemacs\fP is
7817 equivalent to \fIemacs\-standard\fP.
7818 .TP
7819 .B \-l
7820 List the names of all \fBreadline\fP functions.
7821 .TP
7822 .B \-p
7823 Display \fBreadline\fP function names and bindings in such a way
7824 that they can be re-read.
7825 .TP
7826 .B \-P
7827 List current \fBreadline\fP function names and bindings.
7828 .TP
7829 .B \-s
7830 Display \fBreadline\fP key sequences bound to macros and the strings
7831 they output in such a way that they can be re-read.
7832 .TP
7833 .B \-S
7834 Display \fBreadline\fP key sequences bound to macros and the strings
7835 they output.
7836 .TP
7837 .B \-v
7838 Display \fBreadline\fP variable names and values in such a way that they
7839 can be re-read.
7840 .TP
7841 .B \-V
7842 List current \fBreadline\fP variable names and values.
7843 .TP
7844 .B \-f \fIfilename\fP
7845 Read key bindings from \fIfilename\fP.
7846 .TP
7847 .B \-q \fIfunction\fP
7848 Query about which keys invoke the named \fIfunction\fP.
7849 .TP
7850 .B \-u \fIfunction\fP
7851 Unbind all keys bound to the named \fIfunction\fP.
7852 .TP
7853 .B \-r \fIkeyseq\fP
7854 Remove any current binding for \fIkeyseq\fP.
7855 .TP
7856 .B \-x \fIkeyseq\fP:\fIshell\-command\fP
7857 Cause \fIshell\-command\fP to be executed whenever \fIkeyseq\fP is
7858 entered.
7859 When \fIshell\-command\fP is executed, the shell sets the
7860 .SM
7861 .B READLINE_LINE
7862 variable to the contents of the \fBreadline\fP line buffer and the
7863 .SM
7864 .B READLINE_POINT
7865 and
7866 .SM
7867 .B READLINE_MARK
7868 variables to the current location of the insertion point and the saved
7869 insertion point (the mark), respectively.
7870 The shell assigns any numeric argument the user supplied to the
7871 .SM
7872 .B READLINE_ARGUMENT
7873 variable.
7874 If there was no argument, that variable is not set.
7875 If the executed command changes the value of any of
7876 .SM
7877 .BR READLINE_LINE ,
7878 .SM
7879 .BR READLINE_POINT ,
7880 or
7881 .SM
7882 .BR READLINE_MARK ,
7883 those new values will be reflected in the editing state.
7884 .TP
7885 .B \-X
7886 List all key sequences bound to shell commands and the associated commands
7887 in a format that can be reused as input.
7888 .PD
7889 .PP
7890 The return value is 0 unless an unrecognized option is given or an
7891 error occurred.
7892 .RE
7893 .TP
7894 \fBbreak\fP [\fIn\fP]
7895 Exit from within a
7896 .BR for ,
7897 .BR while ,
7898 .BR until ,
7899 or
7900 .B select
7901 loop. If \fIn\fP is specified, break \fIn\fP levels.
7902 .I n
7903 must be \(>= 1. If
7904 .I n
7905 is greater than the number of enclosing loops, all enclosing loops
7906 are exited.
7907 The return value is 0 unless \fIn\fP is not greater than or equal to 1.
7908 .TP
7909 \fBbuiltin\fP \fIshell\-builtin\fP [\fIarguments\fP]
7910 Execute the specified shell builtin, passing it
7911 .IR arguments ,
7912 and return its exit status.
7913 This is useful when defining a
7914 function whose name is the same as a shell builtin,
7915 retaining the functionality of the builtin within the function.
7916 The \fBcd\fP builtin is commonly redefined this way.
7917 The return status is false if
7918 .I shell\-builtin
7919 is not a shell builtin command.
7920 .TP
7921 \fBcaller\fP [\fIexpr\fP]
7922 Returns the context of any active subroutine call (a shell function or
7923 a script executed with the \fB.\fP or \fBsource\fP builtins).
7924 Without \fIexpr\fP, \fBcaller\fP displays the line number and source
7925 filename of the current subroutine call.
7926 If a non-negative integer is supplied as \fIexpr\fP, \fBcaller\fP
7927 displays the line number, subroutine name, and source file corresponding
7928 to that position in the current execution call stack. This extra
7929 information may be used, for example, to print a stack trace. The
7930 current frame is frame 0.
7931 The return value is 0 unless the shell is not executing a subroutine
7932 call or \fIexpr\fP does not correspond to a valid position in the
7933 call stack.
7934 .TP
7935 \fBcd\fP [\fB\-L\fP|[\fB\-P\fP [\fB\-e\fP]] [\-@]] [\fIdir\fP]
7936 Change the current directory to \fIdir\fP.
7937 if \fIdir\fP is not supplied, the value of the
7938 .SM
7939 .B HOME
7940 shell variable is the default.
7941 The variable
7942 .SM
7943 .B CDPATH
7944 defines the search path for the directory containing
7945 .IR dir :
7946 each directory name in
7947 .SM
7948 .B CDPATH
7949 is searched for \fIdir\fP.
7950 Alternative directory names in
7951 .SM
7952 .B CDPATH
7953 are separated by a colon (:). A null directory name in
7954 .SM
7955 .B CDPATH
7956 is the same as the current directory, i.e., ``\fB.\fP''. If
7957 .I dir
7958 begins with a slash (/),
7959 then
7960 .SM
7961 .B CDPATH
7962 is not used. The
7963 .B \-P
7964 option causes \fBcd\fP to use the physical directory structure
7965 by resolving symbolic links while traversing \fIdir\fP and
7966 before processing instances of \fI..\fP in \fIdir\fP (see also the
7967 .B \-P
7968 option to the
7969 .B set
7970 builtin command); the
7971 .B \-L
7972 option forces symbolic links to be followed by resolving the link
7973 after processing instances of \fI..\fP in \fIdir\fP.
7974 If \fI..\fP appears in \fIdir\fP, it is processed by removing the
7975 immediately previous pathname component from \fIdir\fP, back to a slash
7976 or the beginning of \fIdir\fP.
7977 If the
7978 .B \-e
7979 option is supplied with
7980 .BR \-P ,
7981 and the current working directory cannot be successfully determined
7982 after a successful directory change, \fBcd\fP will return an unsuccessful
7983 status.
7984 On systems that support it, the \fB\-@\fP option presents the extended
7985 attributes associated with a file as a directory.
7986 An argument of
7987 .B \-
7988 is converted to
7989 .SM
7990 .B $OLDPWD
7991 before the directory change is attempted.
7992 If a non-empty directory name from
7993 .SM
7994 .B CDPATH
7995 is used, or if
7996 \fB\-\fP is the first argument, and the directory change is
7997 successful, the absolute pathname of the new working directory is
7998 written to the standard output.
7999 If the directory change is successful, \fBcd\fP sets the value of the
8000 \fBPWD\fP environment variable to the new directory name, and sets the
8001 \fBOLDPWD\fP environment variable to the value of the current working
8002 directory before the change.
8003 The return value is true if the directory was successfully changed;
8004 false otherwise.
8005 .TP
8006 \fBcommand\fP [\fB\-pVv\fP] \fIcommand\fP [\fIarg\fP ...]
8007 Run
8008 .I command
8009 with
8010 .I args
8011 suppressing the normal shell function lookup.
8012 Only builtin commands or commands found in the
8013 .SM
8014 .B PATH
8015 are executed. If the
8016 .B \-p
8017 option is given, the search for
8018 .I command
8019 is performed using a default value for
8020 .SM
8021 .B PATH
8022 that is guaranteed to find all of the standard utilities.
8023 If either the
8024 .B \-V
8025 or
8026 .B \-v
8027 option is supplied, a description of
8028 .I command
8029 is printed. The
8030 .B \-v
8031 option causes a single word indicating the command or filename
8032 used to invoke
8033 .I command
8034 to be displayed; the
8035 .B \-V
8036 option produces a more verbose description.
8037 If the
8038 .B \-V
8039 or
8040 .B \-v
8041 option is supplied, the exit status is 0 if
8042 .I command
8043 was found, and 1 if not. If neither option is supplied and
8044 an error occurred or
8045 .I command
8046 cannot be found, the exit status is 127. Otherwise, the exit status of the
8047 .B command
8048 builtin is the exit status of
8049 .IR command .
8050 .TP
8051 \fBcompgen\fP [\fIoption\fP] [\fIword\fP]
8052 Generate possible completion matches for \fIword\fP according to
8053 the \fIoption\fPs, which may be any option accepted by the
8054 .B complete
8055 builtin with the exception of \fB\-p\fP and \fB\-r\fP, and write
8056 the matches to the standard output.
8057 When using the \fB\-F\fP or \fB\-C\fP options, the various shell variables
8058 set by the programmable completion facilities, while available, will not
8059 have useful values.
8060 .sp 1
8061 The matches will be generated in the same way as if the programmable
8062 completion code had generated them directly from a completion specification
8063 with the same flags.
8064 If \fIword\fP is specified, only those completions matching \fIword\fP
8065 will be displayed.
8066 .sp 1
8067 The return value is true unless an invalid option is supplied, or no
8068 matches were generated.
8069 .TP
8070 \fBcomplete\fP [\fB\-abcdefgjksuv\fP] [\fB\-o\fP \fIcomp-option\fP] [\fB\-DEI\fP] [\fB\-A\fP \fIaction\fP] [\fB\-G\fP \fIglobpat\fP] [\fB\-W\fP \fIwordlist\fP]
8071 .br
8072 [\fB\-F\fP \fIfunction\fP] [\fB\-C\fP \fIcommand\fP] [\fB\-X\fP \fIfilterpat\fP] [\fB\-P\fP \fIprefix\fP] [\fB\-S\fP \fIsuffix\fP] \fIname\fP [\fIname ...\fP]
8073 .PD 0
8074 .TP
8075 \fBcomplete\fP \fB\-pr\fP [\fB\-DEI\fP] [\fIname\fP ...]
8076 .PD
8077 Specify how arguments to each \fIname\fP should be completed.
8078 If the \fB\-p\fP option is supplied, or if no options are supplied,
8079 existing completion specifications are printed in a way that allows
8080 them to be reused as input.
8081 The \fB\-r\fP option removes a completion specification for
8082 each \fIname\fP, or, if no \fIname\fPs are supplied, all
8083 completion specifications.
8084 The \fB\-D\fP option indicates that other supplied options and actions should
8085 apply to the ``default'' command completion; that is, completion attempted
8086 on a command for which no completion has previously been defined.
8087 The \fB\-E\fP option indicates that other supplied options and actions should
8088 apply to ``empty'' command completion; that is, completion attempted on a
8089 blank line.
8090 The \fB\-I\fP option indicates that other supplied options and actions should
8091 apply to completion on the initial non-assignment word on the line, or after
8092 a command delimiter such as \fB;\fP or \fB|\fP, which is usually command
8093 name completion.
8094 If multiple options are supplied, the \fB\-D\fP option takes precedence
8095 over \fB\-E\fP, and both take precedence over \fB\-I\fP.
8096 If any of \fB\-D\fP, \fB\-E\fP, or \fB\-I\fP are supplied, any other
8097 \fIname\fP arguments are ignored; these completions only apply to the case
8098 specified by the option.
8099 .sp 1
8100 The process of applying these completion specifications when word completion
8101 is attempted is described
8102 .ie \n(zZ=1 in \fIbash(1)\fP.
8103 .el above under \fBProgrammable Completion\fP.
8104 .sp 1
8105 Other options, if specified, have the following meanings.
8106 The arguments to the \fB\-G\fP, \fB\-W\fP, and \fB\-X\fP options
8107 (and, if necessary, the \fB\-P\fP and \fB\-S\fP options)
8108 should be quoted to protect them from expansion before the
8109 .B complete
8110 builtin is invoked.
8111 .RS
8112 .PD 0
8113 .TP 8
8114 \fB\-o\fP \fIcomp-option\fP
8115 The \fIcomp-option\fP controls several aspects of the compspec's behavior
8116 beyond the simple generation of completions.
8117 \fIcomp-option\fP may be one of:
8118 .RS
8119 .TP 8
8120 .B bashdefault
8121 Perform the rest of the default \fBbash\fP completions if the compspec
8122 generates no matches.
8123 .TP 8
8124 .B default
8125 Use readline's default filename completion if the compspec generates
8126 no matches.
8127 .TP 8
8128 .B dirnames
8129 Perform directory name completion if the compspec generates no matches.
8130 .TP 8
8131 .B filenames
8132 Tell readline that the compspec generates filenames, so it can perform any
8133 filename\-specific processing (like adding a slash to directory names,
8134 quoting special characters, or suppressing trailing spaces).
8135 Intended to be used with shell functions.
8136 .TP 8
8137 .B noquote
8138 Tell readline not to quote the completed words if they are filenames
8139 (quoting filenames is the default).
8140 .TP 8
8141 .B nosort
8142 Tell readline not to sort the list of possible completions alphabetically.
8143 .TP 8
8144 .B nospace
8145 Tell readline not to append a space (the default) to words completed at
8146 the end of the line.
8147 .TP 8
8148 .B plusdirs
8149 After any matches defined by the compspec are generated,
8150 directory name completion is attempted and any
8151 matches are added to the results of the other actions.
8152 .RE
8153 .TP 8
8154 \fB\-A\fP \fIaction\fP
8155 The \fIaction\fP may be one of the following to generate a list of possible
8156 completions:
8157 .RS
8158 .TP 8
8159 .B alias
8160 Alias names. May also be specified as \fB\-a\fP.
8161 .TP 8
8162 .B arrayvar
8163 Array variable names.
8164 .TP 8
8165 .B binding
8166 \fBReadline\fP key binding names.
8167 .TP 8
8168 .B builtin
8169 Names of shell builtin commands. May also be specified as \fB\-b\fP.
8170 .TP 8
8171 .B command
8172 Command names. May also be specified as \fB\-c\fP.
8173 .TP 8
8174 .B directory
8175 Directory names. May also be specified as \fB\-d\fP.
8176 .TP 8
8177 .B disabled
8178 Names of disabled shell builtins.
8179 .TP 8
8180 .B enabled
8181 Names of enabled shell builtins.
8182 .TP 8
8183 .B export
8184 Names of exported shell variables. May also be specified as \fB\-e\fP.
8185 .TP 8
8186 .B file
8187 File names. May also be specified as \fB\-f\fP.
8188 .TP 8
8189 .B function
8190 Names of shell functions.
8191 .TP 8
8192 .B group
8193 Group names. May also be specified as \fB\-g\fP.
8194 .TP 8
8195 .B helptopic
8196 Help topics as accepted by the \fBhelp\fP builtin.
8197 .TP 8
8198 .B hostname
8199 Hostnames, as taken from the file specified by the
8200 .SM
8201 .B HOSTFILE
8202 shell variable.
8203 .TP 8
8204 .B job
8205 Job names, if job control is active. May also be specified as \fB\-j\fP.
8206 .TP 8
8207 .B keyword
8208 Shell reserved words. May also be specified as \fB\-k\fP.
8209 .TP 8
8210 .B running
8211 Names of running jobs, if job control is active.
8212 .TP 8
8213 .B service
8214 Service names. May also be specified as \fB\-s\fP.
8215 .TP 8
8216 .B setopt
8217 Valid arguments for the \fB\-o\fP option to the \fBset\fP builtin.
8218 .TP 8
8219 .B shopt
8220 Shell option names as accepted by the \fBshopt\fP builtin.
8221 .TP 8
8222 .B signal
8223 Signal names.
8224 .TP 8
8225 .B stopped
8226 Names of stopped jobs, if job control is active.
8227 .TP 8
8228 .B user
8229 User names. May also be specified as \fB\-u\fP.
8230 .TP 8
8231 .B variable
8232 Names of all shell variables. May also be specified as \fB\-v\fP.
8233 .RE
8234 .TP 8
8235 \fB\-C\fP \fIcommand\fP
8236 \fIcommand\fP is executed in a subshell environment, and its output is
8237 used as the possible completions.
8238 Arguments are passed as with the \fB\-F\fP option.
8239 .TP 8
8240 \fB\-F\fP \fIfunction\fP
8241 The shell function \fIfunction\fP is executed in the current shell
8242 environment.
8243 When the function is executed,
8244 the first argument (\fB$1\fP) is the name of the command whose arguments are
8245 being completed,
8246 the second argument (\fB$2\fP) is the word being completed,
8247 and the third argument (\fB$3\fP) is the word preceding the word being
8248 completed on the current command line.
8249 When it finishes, the possible completions are retrieved from the value
8250 of the
8251 .SM
8252 .B COMPREPLY
8253 array variable.
8254 .TP 8
8255 \fB\-G\fP \fIglobpat\fP
8256 The pathname expansion pattern \fIglobpat\fP is expanded to generate
8257 the possible completions.
8258 .TP 8
8259 \fB\-P\fP \fIprefix\fP
8260 \fIprefix\fP is added at the beginning of each possible completion
8261 after all other options have been applied.
8262 .TP 8
8263 \fB\-S\fP \fIsuffix\fP
8264 \fIsuffix\fP is appended to each possible completion
8265 after all other options have been applied.
8266 .TP 8
8267 \fB\-W\fP \fIwordlist\fP
8268 The \fIwordlist\fP is split using the characters in the
8269 .SM
8270 .B IFS
8271 special variable as delimiters, and each resultant word is expanded.
8272 Shell quoting is honored within \fIwordlist\fP,
8273 in order to provide a
8274 mechanism for the words to contain shell metacharacters or characters
8275 in the value of
8276 .SM
8277 .BR IFS .
8278 The possible completions are the members of the resultant list which
8279 match the word being completed.
8280 .TP 8
8281 \fB\-X\fP \fIfilterpat\fP
8282 \fIfilterpat\fP is a pattern as used for pathname expansion.
8283 It is applied to the list of possible completions generated by the
8284 preceding options and arguments, and each completion matching
8285 \fIfilterpat\fP is removed from the list.
8286 A leading \fB!\fP in \fIfilterpat\fP negates the pattern; in this
8287 case, any completion not matching \fIfilterpat\fP is removed.
8288 .PD
8289 .PP
8290 The return value is true unless an invalid option is supplied, an option
8291 other than \fB\-p\fP or \fB\-r\fP is supplied without a \fIname\fP
8292 argument, an attempt is made to remove a completion specification for
8293 a \fIname\fP for which no specification exists, or
8294 an error occurs adding a completion specification.
8295 .RE
8296 .TP
8297 \fBcompopt\fP [\fB\-o\fP \fIoption\fP] [\fB\-DEI\fP] [\fB+o\fP \fIoption\fP] [\fIname\fP]
8298 Modify completion options for each \fIname\fP according to the
8299 \fIoption\fPs, or for the
8300 currently-executing completion if no \fIname\fPs are supplied.
8301 If no \fIoption\fPs are given, display the completion options for each
8302 \fIname\fP or the current completion.
8303 The possible values of \fIoption\fP are those valid for the \fBcomplete\fP
8304 builtin described above.
8305 The \fB\-D\fP option indicates that other supplied options should
8306 apply to the ``default'' command completion; that is, completion attempted
8307 on a command for which no completion has previously been defined.
8308 The \fB\-E\fP option indicates that other supplied options should
8309 apply to ``empty'' command completion; that is, completion attempted on a
8310 blank line.
8311 The \fB\-I\fP option indicates that other supplied options should
8312 apply to completion on the initial non-assignment word on the line,
8313 or after a command delimiter such as \fB;\fP or \fB|\fP, which is usually
8314 command name completion.
8315 .sp 1
8316 The return value is true unless an invalid option is supplied, an attempt
8317 is made to modify the options for a \fIname\fP for which no completion
8318 specification exists, or an output error occurs.
8319 .TP
8320 \fBcontinue\fP [\fIn\fP]
8321 Resume the next iteration of the enclosing
8322 .BR for ,
8323 .BR while ,
8324 .BR until ,
8325 or
8326 .B select
8327 loop.
8328 If
8329 .I n
8330 is specified, resume at the \fIn\fPth enclosing loop.
8331 .I n
8332 must be \(>= 1. If
8333 .I n
8334 is greater than the number of enclosing loops, the last enclosing loop
8335 (the ``top-level'' loop) is resumed.
8336 The return value is 0 unless \fIn\fP is not greater than or equal to 1.
8337 .TP
8338 \fBdeclare\fP [\fB\-aAfFgiIlnrtux\fP] [\fB\-p\fP] [\fIname\fP[=\fIvalue\fP] ...]
8339 .PD 0
8340 .TP
8341 \fBtypeset\fP [\fB\-aAfFgiIlnrtux\fP] [\fB\-p\fP] [\fIname\fP[=\fIvalue\fP] ...]
8342 .PD
8343 Declare variables and/or give them attributes.
8344 If no \fIname\fPs are given then display the values of variables.
8345 The
8346 .B \-p
8347 option will display the attributes and values of each
8348 .IR name .
8349 When
8350 .B \-p
8351 is used with \fIname\fP arguments, additional options,
8352 other than \fB\-f\fP and \fB\-F\fP, are ignored.
8353 When
8354 .B \-p
8355 is supplied without \fIname\fP arguments, it will display the attributes
8356 and values of all variables having the attributes specified by the
8357 additional options.
8358 If no other options are supplied with \fB\-p\fP, \fBdeclare\fP will display
8359 the attributes and values of all shell variables. The \fB\-f\fP option
8360 will restrict the display to shell functions.
8361 The
8362 .B \-F
8363 option inhibits the display of function definitions; only the
8364 function name and attributes are printed.
8365 If the \fBextdebug\fP shell option is enabled using \fBshopt\fP,
8366 the source file name and line number where each \fIname\fP
8367 is defined are displayed as well. The
8368 .B \-F
8369 option implies
8370 .BR \-f .
8371 The
8372 .B \-g
8373 option forces variables to be created or modified at the global scope,
8374 even when \fBdeclare\fP is executed in a shell function.
8375 It is ignored in all other cases.
8376 The
8377 .B \-I
8378 option causes local variables to inherit the attributes
8379 (except the \fInameref\fP attribute)
8380 and value of any existing variable with the same
8381 \fIname\fP at a surrounding scope.
8382 If there is no existing variable, the local variable is initially unset.
8383 The following options can
8384 be used to restrict output to variables with the specified attribute or
8385 to give variables attributes:
8386 .RS
8387 .PD 0
8388 .TP
8389 .B \-a
8390 Each \fIname\fP is an indexed array variable (see
8391 .B Arrays
8392 .ie \n(zZ=1 in \fIbash(1)\fP).
8393 .el above).
8394 .TP
8395 .B \-A
8396 Each \fIname\fP is an associative array variable (see
8397 .B Arrays
8398 .ie \n(zZ=1 in \fIbash(1)\fP).
8399 .el above).
8400 .TP
8401 .B \-f
8402 Use function names only.
8403 .TP
8404 .B \-i
8405 The variable is treated as an integer; arithmetic evaluation (see
8406 .SM
8407 .B "ARITHMETIC EVALUATION"
8408 .ie \n(zZ=1 in \fIbash(1)\fP)
8409 .el above)
8410 is performed when the variable is assigned a value.
8411 .TP
8412 .B \-l
8413 When the variable is assigned a value, all upper-case characters are
8414 converted to lower-case.
8415 The upper-case attribute is disabled.
8416 .TP
8417 .B \-n
8418 Give each \fIname\fP the \fInameref\fP attribute, making
8419 it a name reference to another variable.
8420 That other variable is defined by the value of \fIname\fP.
8421 All references, assignments, and attribute modifications
8422 to \fIname\fP, except those using or changing the
8423 \fB\-n\fP attribute itself, are performed on the variable referenced by
8424 \fIname\fP's value.
8425 The nameref attribute cannot be applied to array variables.
8426 .TP
8427 .B \-r
8428 Make \fIname\fPs readonly. These names cannot then be assigned values
8429 by subsequent assignment statements or unset.
8430 .TP
8431 .B \-t
8432 Give each \fIname\fP the \fItrace\fP attribute.
8433 Traced functions inherit the \fBDEBUG\fP and \fBRETURN\fP traps from
8434 the calling shell.
8435 The trace attribute has no special meaning for variables.
8436 .TP
8437 .B \-u
8438 When the variable is assigned a value, all lower-case characters are
8439 converted to upper-case.
8440 The lower-case attribute is disabled.
8441 .TP
8442 .B \-x
8443 Mark \fIname\fPs for export to subsequent commands via the environment.
8444 .PD
8445 .PP
8446 Using `+' instead of `\-'
8447 turns off the attribute instead,
8448 with the exceptions that \fB+a\fP and \fB+A\fP
8449 may not be used to destroy array variables and \fB+r\fP will not
8450 remove the readonly attribute.
8451 When used in a function,
8452 .B declare
8453 and
8454 .B typeset
8455 make each
8456 \fIname\fP local, as with the
8457 .B local
8458 command,
8459 unless the \fB\-g\fP option is supplied.
8460 If a variable name is followed by =\fIvalue\fP, the value of
8461 the variable is set to \fIvalue\fP.
8462 When using \fB\-a\fP or \fB\-A\fP and the compound assignment syntax to
8463 create array variables, additional attributes do not take effect until
8464 subsequent assignments.
8465 The return value is 0 unless an invalid option is encountered,
8466 an attempt is made to define a function using
8467 .if n ``\-f foo=bar'',
8468 .if t \f(CW\-f foo=bar\fP,
8469 an attempt is made to assign a value to a readonly variable,
8470 an attempt is made to assign a value to an array variable without
8471 using the compound assignment syntax (see
8472 .B Arrays
8473 .ie \n(zZ=1 in \fIbash(1)\fP),
8474 .el above),
8475 one of the \fInames\fP is not a valid shell variable name,
8476 an attempt is made to turn off readonly status for a readonly variable,
8477 an attempt is made to turn off array status for an array variable,
8478 or an attempt is made to display a non-existent function with \fB\-f\fP.
8479 .RE
8480 .TP
8481 .B dirs [\fB\-clpv\fP] [+\fIn\fP] [\-\fIn\fP]
8482 Without options, displays the list of currently remembered directories.
8483 The default display is on a single line with directory names separated
8484 by spaces.
8485 Directories are added to the list with the
8486 .B pushd
8487 command; the
8488 .B popd
8489 command removes entries from the list.
8490 The current directory is always the first directory in the stack.
8491 .RS
8492 .PD 0
8493 .TP
8494 .B \-c
8495 Clears the directory stack by deleting all of the entries.
8496 .TP
8497 .B \-l
8498 Produces a listing using full pathnames;
8499 the default listing format uses a tilde to denote the home directory.
8500 .TP
8501 .B \-p
8502 Print the directory stack with one entry per line.
8503 .TP
8504 .B \-v
8505 Print the directory stack with one entry per line,
8506 prefixing each entry with its index in the stack.
8507 .TP
8508 \fB+\fP\fIn\fP
8509 Displays the \fIn\fPth entry counting from the left of the list
8510 shown by
8511 .B dirs
8512 when invoked without options, starting with zero.
8513 .TP
8514 \fB\-\fP\fIn\fP
8515 Displays the \fIn\fPth entry counting from the right of the list
8516 shown by
8517 .B dirs
8518 when invoked without options, starting with zero.
8519 .PD
8520 .PP
8521 The return value is 0 unless an
8522 invalid option is supplied or \fIn\fP indexes beyond the end
8523 of the directory stack.
8524 .RE
8525 .TP
8526 \fBdisown\fP [\fB\-ar\fP] [\fB\-h\fP] [\fIjobspec\fP ... | \fIpid\fP ... ]
8527 Without options, remove each
8528 .I jobspec
8529 from the table of active jobs.
8530 If
8531 .I jobspec
8532 is not present, and neither the \fB\-a\fP nor the \fB\-r\fP option
8533 is supplied, the \fIcurrent job\fP is used.
8534 If the \fB\-h\fP option is given, each
8535 .I jobspec
8536 is not removed from the table, but is marked so that
8537 .SM
8538 .B SIGHUP
8539 is not sent to the job if the shell receives a
8540 .SM
8541 .BR SIGHUP .
8542 If no
8543 .I jobspec
8544 is supplied, the
8545 .B \-a
8546 option means to remove or mark all jobs; the
8547 .B \-r
8548 option without a
8549 .I jobspec
8550 argument restricts operation to running jobs.
8551 The return value is 0 unless a
8552 .I jobspec
8553 does not specify a valid job.
8554 .TP
8555 \fBecho\fP [\fB\-neE\fP] [\fIarg\fP ...]
8556 Output the \fIarg\fPs, separated by spaces, followed by a newline.
8557 The return status is 0 unless a write error occurs.
8558 If \fB\-n\fP is specified, the trailing newline is
8559 suppressed. If the \fB\-e\fP option is given, interpretation of
8560 the following backslash-escaped characters is enabled. The
8561 .B \-E
8562 option disables the interpretation of these escape characters,
8563 even on systems where they are interpreted by default.
8564 The \fBxpg_echo\fP shell option may be used to
8565 dynamically determine whether or not \fBecho\fP expands these
8566 escape characters by default.
8567 .B echo
8568 does not interpret \fB\-\-\fP to mean the end of options.
8569 .B echo
8570 interprets the following escape sequences:
8571 .RS
8572 .PD 0
8573 .TP
8574 .B \ea
8575 alert (bell)
8576 .TP
8577 .B \eb
8578 backspace
8579 .TP
8580 .B \ec
8581 suppress further output
8582 .TP
8583 .B \ee
8584 .TP
8585 .B \eE
8586 an escape character
8587 .TP
8588 .B \ef
8589 form feed
8590 .TP
8591 .B \en
8592 new line
8593 .TP
8594 .B \er
8595 carriage return
8596 .TP
8597 .B \et
8598 horizontal tab
8599 .TP
8600 .B \ev
8601 vertical tab
8602 .TP
8603 .B \e\e
8604 backslash
8605 .TP
8606 .B \e0\fInnn\fP
8607 the eight-bit character whose value is the octal value \fInnn\fP
8608 (zero to three octal digits)
8609 .TP
8610 .B \ex\fIHH\fP
8611 the eight-bit character whose value is the hexadecimal value \fIHH\fP
8612 (one or two hex digits)
8613 .TP
8614 .B \eu\fIHHHH\fP
8615 the Unicode (ISO/IEC 10646) character whose value is the hexadecimal value
8616 \fIHHHH\fP (one to four hex digits)
8617 .TP
8618 .B \eU\fIHHHHHHHH\fP
8619 the Unicode (ISO/IEC 10646) character whose value is the hexadecimal value
8620 \fIHHHHHHHH\fP (one to eight hex digits)
8621 .PD
8622 .RE
8623 .TP
8624 \fBenable\fP [\fB\-a\fP] [\fB\-dnps\fP] [\fB\-f\fP \fIfilename\fP] [\fIname\fP ...]
8625 Enable and disable builtin shell commands.
8626 Disabling a builtin allows a disk command which has the same name
8627 as a shell builtin to be executed without specifying a full pathname,
8628 even though the shell normally searches for builtins before disk commands.
8629 If \fB\-n\fP is used, each \fIname\fP
8630 is disabled; otherwise,
8631 \fInames\fP are enabled. For example, to use the
8632 .B test
8633 binary found via the
8634 .SM
8635 .B PATH
8636 instead of the shell builtin version, run
8637 .if t \f(CWenable -n test\fP.
8638 .if n ``enable -n test''.
8639 The
8640 .B \-f
8641 option means to load the new builtin command
8642 .I name
8643 from shared object
8644 .IR filename ,
8645 on systems that support dynamic loading.
8646 Bash will use the value of the \fBBASH_LOADABLES_PATH\fP variable as a
8647 colon-separated list of directories in which to search for \fIfilename\fP.
8648 The default is system-dependent.
8649 The
8650 .B \-d
8651 option will delete a builtin previously loaded with
8652 .BR \-f .
8653 If no \fIname\fP arguments are given, or if the
8654 .B \-p
8655 option is supplied, a list of shell builtins is printed.
8656 With no other option arguments, the list consists of all enabled
8657 shell builtins.
8658 If \fB\-n\fP is supplied, only disabled builtins are printed.
8659 If \fB\-a\fP is supplied, the list printed includes all builtins, with an
8660 indication of whether or not each is enabled.
8661 If \fB\-s\fP is supplied, the output is restricted to the POSIX
8662 \fIspecial\fP builtins.
8663 If no options are supplied and a \fIname\fP is not a shell builtin,
8664 \fBenable\fP will attempt to load \fIname\fP from a shared object named
8665 \fIname\fP, as if the command were
8666 .if t \f(CWenable \-f\fP \fIname name\fP .
8667 .if n ``enable -f \fIname name\fP .
8668 The return value is 0 unless a
8669 .I name
8670 is not a shell builtin or there is an error loading a new builtin
8671 from a shared object.
8672 .TP
8673 \fBeval\fP [\fIarg\fP ...]
8674 The \fIarg\fPs are read and concatenated together into a single
8675 command. This command is then read and executed by the shell, and
8676 its exit status is returned as the value of
8677 .BR eval .
8678 If there are no
8679 .IR args ,
8680 or only null arguments,
8681 .B eval
8682 returns 0.
8683 .TP
8684 \fBexec\fP [\fB\-cl\fP] [\fB\-a\fP \fIname\fP] [\fIcommand\fP [\fIarguments\fP]]
8685 If
8686 .I command
8687 is specified, it replaces the shell.
8688 No new process is created. The
8689 .I arguments
8690 become the arguments to \fIcommand\fP.
8691 If the
8692 .B \-l
8693 option is supplied,
8694 the shell places a dash at the beginning of the zeroth argument passed to
8695 .IR command .
8696 This is what
8697 .IR login (1)
8698 does. The
8699 .B \-c
8700 option causes
8701 .I command
8702 to be executed with an empty environment. If
8703 .B \-a
8704 is supplied, the shell passes
8705 .I name
8706 as the zeroth argument to the executed command.
8707 If
8708 .I command
8709 cannot be executed for some reason, a non-interactive shell exits,
8710 unless the
8711 .B execfail
8712 shell option
8713 is enabled. In that case, it returns failure.
8714 An interactive shell returns failure if the file cannot be executed.
8715 A subshell exits unconditionally if \fBexec\fP fails.
8716 If
8717 .I command
8718 is not specified, any redirections take effect in the current shell,
8719 and the return status is 0. If there is a redirection error, the
8720 return status is 1.
8721 .TP
8722 \fBexit\fP [\fIn\fP]
8723 Cause the shell to exit
8724 with a status of \fIn\fP. If
8725 .I n
8726 is omitted, the exit status
8727 is that of the last command executed.
8728 A trap on
8729 .SM
8730 .B EXIT
8731 is executed before the shell terminates.
8732 .TP
8733 \fBexport\fP [\fB\-fn\fP\^] [\fIname\fP[=\fIword\fP]] ...
8734 .PD 0
8735 .TP
8736 .B export \-p
8737 .PD
8738 The supplied
8739 .I names
8740 are marked for automatic export to the environment of
8741 subsequently executed commands. If the
8742 .B \-f
8743 option is given, the
8744 .I names
8745 refer to functions.
8746 If no
8747 .I names
8748 are given, or if the
8749 .B \-p
8750 option is supplied, a list
8751 of names of all exported variables is printed.
8752 The
8753 .B \-n
8754 option causes the export property to be removed from each
8755 \fIname\fP.
8756 If a variable name is followed by =\fIword\fP, the value of
8757 the variable is set to \fIword\fP.
8758 .B export
8759 returns an exit status of 0 unless an invalid option is
8760 encountered,
8761 one of the \fInames\fP is not a valid shell variable name, or
8762 .B \-f
8763 is supplied with a
8764 .I name
8765 that is not a function.
8766 .TP
8767 \fBfc\fP [\fB\-e\fP \fIename\fP] [\fB\-lnr\fP] [\fIfirst\fP] [\fIlast\fP]
8768 .PD 0
8769 .TP
8770 \fBfc\fP \fB\-s\fP [\fIpat\fP=\fIrep\fP] [\fIcmd\fP]
8771 .PD
8772 The first form selects a range of commands from
8773 .I first
8774 to
8775 .I last
8776 from the history list and displays or edits and re-executes them.
8777 .I First
8778 and
8779 .I last
8780 may be specified as a string (to locate the last command beginning
8781 with that string) or as a number (an index into the history list,
8782 where a negative number is used as an offset from the current
8783 command number).
8784 When listing, a \fIfirst\fP or \fIlast\fP of
8785 0 is equivalent to \-1 and \-0 is equivalent to the current
8786 command (usually the \fBfc\fP command); otherwise 0 is equivalent to \-1
8787 and \-0 is invalid.
8788 If
8789 .I last
8790 is not specified, it is set to
8791 the current command for listing (so that
8792 .if n ``fc \-l \-10''
8793 .if t \f(CWfc \-l \-10\fP
8794 prints the last 10 commands) and to
8795 .I first
8796 otherwise.
8797 If
8798 .I first
8799 is not specified, it is set to the previous
8800 command for editing and \-16 for listing.
8801 .sp 1
8802 The
8803 .B \-n
8804 option suppresses
8805 the command numbers when listing. The
8806 .B \-r
8807 option reverses the order of
8808 the commands. If the
8809 .B \-l
8810 option is given,
8811 the commands are listed on
8812 standard output. Otherwise, the editor given by
8813 .I ename
8814 is invoked
8815 on a file containing those commands. If
8816 .I ename
8817 is not given, the
8818 value of the
8819 .SM
8820 .B FCEDIT
8821 variable is used, and
8822 the value of
8823 .SM
8824 .B EDITOR
8825 if
8826 .SM
8827 .B FCEDIT
8828 is not set. If neither variable is set,
8829 .FN vi
8830 is used. When editing is complete, the edited commands are
8831 echoed and executed.
8832 .sp 1
8833 In the second form, \fIcommand\fP is re-executed after each instance
8834 of \fIpat\fP is replaced by \fIrep\fP.
8835 \fICommand\fP is interpreted the same as \fIfirst\fP above.
8836 A useful alias to use with this is
8837 .if n ``r="fc -s"'',
8838 .if t \f(CWr='fc \-s'\fP,
8839 so that typing
8840 .if n ``r cc''
8841 .if t \f(CWr cc\fP
8842 runs the last command beginning with
8843 .if n ``cc''
8844 .if t \f(CWcc\fP
8845 and typing
8846 .if n ``r''
8847 .if t \f(CWr\fP
8848 re-executes the last command.
8849 .sp 1
8850 If the first form is used, the return value is 0 unless an invalid
8851 option is encountered or
8852 .I first
8853 or
8854 .I last
8855 specify history lines out of range.
8856 If the
8857 .B \-e
8858 option is supplied, the return value is the value of the last
8859 command executed or failure if an error occurs with the temporary
8860 file of commands. If the second form is used, the return status
8861 is that of the command re-executed, unless
8862 .I cmd
8863 does not specify a valid history line, in which case
8864 .B fc
8865 returns failure.
8866 .TP
8867 \fBfg\fP [\fIjobspec\fP]
8868 Resume
8869 .I jobspec
8870 in the foreground, and make it the current job.
8871 If
8872 .I jobspec
8873 is not present, the shell's notion of the \fIcurrent job\fP is used.
8874 The return value is that of the command placed into the foreground,
8875 or failure if run when job control is disabled or, when run with
8876 job control enabled, if
8877 .I jobspec
8878 does not specify a valid job or
8879 .I jobspec
8880 specifies a job that was started without job control.
8881 .TP
8882 \fBgetopts\fP \fIoptstring\fP \fIname\fP [\fIarg ...\fP]
8883 .B getopts
8884 is used by shell procedures to parse positional parameters.
8885 .I optstring
8886 contains the option characters to be recognized; if a character
8887 is followed by a colon, the option is expected to have an
8888 argument, which should be separated from it by white space.
8889 The colon and question mark characters may not be used as
8890 option characters.
8891 Each time it is invoked,
8892 .B getopts
8893 places the next option in the shell variable
8894 .IR name ,
8895 initializing
8896 .I name
8897 if it does not exist,
8898 and the index of the next argument to be processed into the
8899 variable
8900 .SM
8901 .BR OPTIND .
8902 .SM
8903 .B OPTIND
8904 is initialized to 1 each time the shell or a shell script
8905 is invoked. When an option requires an argument,
8906 .B getopts
8907 places that argument into the variable
8908 .SM
8909 .BR OPTARG .
8910 The shell does not reset
8911 .SM
8912 .B OPTIND
8913 automatically; it must be manually reset between multiple
8914 calls to
8915 .B getopts
8916 within the same shell invocation if a new set of parameters
8917 is to be used.
8918 .sp 1
8919 When the end of options is encountered, \fBgetopts\fP exits with a
8920 return value greater than zero.
8921 .SM
8922 .B OPTIND
8923 is set to the index of the first non-option argument,
8924 and \fIname\fP is set to ?.
8925 .sp 1
8926 .B getopts
8927 normally parses the positional parameters, but if more arguments are
8928 supplied as
8929 .I arg
8930 values,
8931 .B getopts
8932 parses those instead.
8933 .sp 1
8934 .B getopts
8935 can report errors in two ways. If the first character of
8936 .I optstring
8937 is a colon,
8938 .I silent
8939 error reporting is used. In normal operation, diagnostic messages
8940 are printed when invalid options or missing option arguments are
8941 encountered.
8942 If the variable
8943 .SM
8944 .B OPTERR
8945 is set to 0, no error messages will be displayed, even if the first
8946 character of
8947 .I optstring
8948 is not a colon.
8949 .sp 1
8950 If an invalid option is seen,
8951 .B getopts
8952 places ? into
8953 .I name
8954 and, if not silent,
8955 prints an error message and unsets
8956 .SM
8957 .BR OPTARG .
8958 If
8959 .B getopts
8960 is silent,
8961 the option character found is placed in
8962 .SM
8963 .B OPTARG
8964 and no diagnostic message is printed.
8965 .sp 1
8966 If a required argument is not found, and
8967 .B getopts
8968 is not silent,
8969 a question mark (\^\fB?\fP\^) is placed in
8970 .IR name ,
8971 .SM
8972 .B OPTARG
8973 is unset, and a diagnostic message is printed.
8974 If
8975 .B getopts
8976 is silent, then a colon (\^\fB:\fP\^) is placed in
8977 .I name
8978 and
8979 .SM
8980 .B OPTARG
8981 is set to the option character found.
8982 .sp 1
8983 .B getopts
8984 returns true if an option, specified or unspecified, is found.
8985 It returns false if the end of options is encountered or an
8986 error occurs.
8987 .TP
8988 \fBhash\fP [\fB\-lr\fP] [\fB\-p\fP \fIfilename\fP] [\fB\-dt\fP] [\fIname\fP]
8989 Each time \fBhash\fP is invoked,
8990 the full pathname of the command
8991 .I name
8992 is determined by searching
8993 the directories in
8994 .B $PATH
8995 and remembered. Any previously-remembered pathname is discarded.
8996 If the
8997 .B \-p
8998 option is supplied, no path search is performed, and
8999 .I filename
9000 is used as the full filename of the command.
9001 The
9002 .B \-r
9003 option causes the shell to forget all
9004 remembered locations.
9005 The
9006 .B \-d
9007 option causes the shell to forget the remembered location of each \fIname\fP.
9008 If the
9009 .B \-t
9010 option is supplied, the full pathname to which each \fIname\fP corresponds
9011 is printed. If multiple \fIname\fP arguments are supplied with \fB\-t\fP,
9012 the \fIname\fP is printed before the hashed full pathname.
9013 The
9014 .B \-l
9015 option causes output to be displayed in a format that may be reused as input.
9016 If no arguments are given, or if only \fB\-l\fP is supplied,
9017 information about remembered commands is printed.
9018 The return status is true unless a
9019 .I name
9020 is not found or an invalid option is supplied.
9021 .TP
9022 \fBhelp\fP [\fB\-dms\fP] [\fIpattern\fP]
9023 Display helpful information about builtin commands. If
9024 .I pattern
9025 is specified,
9026 .B help
9027 gives detailed help on all commands matching
9028 .IR pattern ;
9029 otherwise help for all the builtins and shell control structures
9030 is printed.
9031 .RS
9032 .PD 0
9033 .TP
9034 .B \-d
9035 Display a short description of each \fIpattern\fP
9036 .TP
9037 .B \-m
9038 Display the description of each \fIpattern\fP in a manpage-like format
9039 .TP
9040 .B \-s
9041 Display only a short usage synopsis for each \fIpattern\fP
9042 .PD
9043 .PP
9044 The return status is 0 unless no command matches
9045 .IR pattern .
9046 .RE
9047 .TP
9048 \fBhistory [\fIn\fP]
9049 .PD 0
9050 .TP
9051 \fBhistory\fP \fB\-c\fP
9052 .TP
9053 \fBhistory \-d\fP \fIoffset\fP
9054 .TP
9055 \fBhistory \-d\fP \fIstart\fP\-\fIend\fP
9056 .TP
9057 \fBhistory\fP \fB\-anrw\fP [\fIfilename\fP]
9058 .TP
9059 \fBhistory\fP \fB\-p\fP \fIarg\fP [\fIarg ...\fP]
9060 .TP
9061 \fBhistory\fP \fB\-s\fP \fIarg\fP [\fIarg ...\fP]
9062 .PD
9063 With no options, display the command
9064 history list with line numbers. Lines listed
9065 with a
9066 .B *
9067 have been modified. An argument of
9068 .I n
9069 lists only the last
9070 .I n
9071 lines.
9072 If the shell variable
9073 .SM
9074 .B HISTTIMEFORMAT
9075 is set and not null,
9076 it is used as a format string for \fIstrftime\fP(3) to display
9077 the time stamp associated with each displayed history entry.
9078 No intervening blank is printed between the formatted time stamp
9079 and the history line.
9080 If \fIfilename\fP is supplied, it is used as the
9081 name of the history file; if not, the value of
9082 .SM
9083 .B HISTFILE
9084 is used. Options, if supplied, have the following meanings:
9085 .RS
9086 .PD 0
9087 .TP
9088 .B \-c
9089 Clear the history list by deleting all the entries.
9090 .TP
9091 \fB\-d\fP \fIoffset\fP
9092 Delete the history entry at position \fIoffset\fP.
9093 If \fIoffset\fP is negative, it is interpreted as relative to one greater
9094 than the last history position, so negative indices count back from the
9095 end of the history, and an index of \-1 refers to the current
9096 \fBhistory -d\fP command.
9097 .TP
9098 \fB\-d\fP \fIstart\fP\-\fIend\fP
9099 Delete the range of history entries between positions \fIstart\fP and
9100 \fIend\fP, inclusive.
9101 Positive and negative values for \fIstart\fP and \fIend\fP
9102 are interpreted as described above.
9103 .TP
9104 .B \-a
9105 Append the ``new'' history lines to the history file.
9106 These are history lines entered since the beginning of the current
9107 \fBbash\fP session, but not already appended to the history file.
9108 .TP
9109 .B \-n
9110 Read the history lines not already read from the history
9111 file into the current history list. These are lines
9112 appended to the history file since the beginning of the
9113 current \fBbash\fP session.
9114 .TP
9115 .B \-r
9116 Read the contents of the history file
9117 and append them to the current history list.
9118 .TP
9119 .B \-w
9120 Write the current history list to the history file, overwriting the
9121 history file's contents.
9122 .TP
9123 .B \-p
9124 Perform history substitution on the following \fIargs\fP and display
9125 the result on the standard output.
9126 Does not store the results in the history list.
9127 Each \fIarg\fP must be quoted to disable normal history expansion.
9128 .TP
9129 .B \-s
9130 Store the
9131 .I args
9132 in the history list as a single entry. The last command in the
9133 history list is removed before the
9134 .I args
9135 are added.
9136 .PD
9137 .PP
9138 If the
9139 .SM
9140 .B HISTTIMEFORMAT
9141 variable is set, the time stamp information
9142 associated with each history entry is written to the history file,
9143 marked with the history comment character.
9144 When the history file is read, lines beginning with the history
9145 comment character followed immediately by a digit are interpreted
9146 as timestamps for the following history entry.
9147 The return value is 0 unless an invalid option is encountered, an
9148 error occurs while reading or writing the history file, an invalid
9149 \fIoffset\fP or range is supplied as an argument to \fB\-d\fP, or the
9150 history expansion supplied as an argument to \fB\-p\fP fails.
9151 .RE
9152 .TP
9153 \fBjobs\fP [\fB\-lnprs\fP] [ \fIjobspec\fP ... ]
9154 .PD 0
9155 .TP
9156 \fBjobs\fP \fB\-x\fP \fIcommand\fP [ \fIargs\fP ... ]
9157 .PD
9158 The first form lists the active jobs. The options have the following
9159 meanings:
9160 .RS
9161 .PD 0
9162 .TP
9163 .B \-l
9164 List process IDs
9165 in addition to the normal information.
9166 .TP
9167 .B \-n
9168 Display information only about jobs that have changed status since
9169 the user was last notified of their status.
9170 .TP
9171 .B \-p
9172 List only the process ID of the job's process group
9173 leader.
9174 .TP
9175 .B \-r
9176 Display only running jobs.
9177 .TP
9178 .B \-s
9179 Display only stopped jobs.
9180 .PD
9181 .PP
9182 If
9183 .I jobspec
9184 is given, output is restricted to information about that job.
9185 The return status is 0 unless an invalid option is encountered
9186 or an invalid
9187 .I jobspec
9188 is supplied.
9189 .PP
9190 If the
9191 .B \-x
9192 option is supplied,
9193 .B jobs
9194 replaces any
9195 .I jobspec
9196 found in
9197 .I command
9198 or
9199 .I args
9200 with the corresponding process group ID, and executes
9201 .I command
9202 passing it
9203 .IR args ,
9204 returning its exit status.
9205 .RE
9206 .TP
9207 \fBkill\fP [\fB\-s\fP \fIsigspec\fP | \fB\-n\fP \fIsignum\fP | \fB\-\fP\fIsigspec\fP] [\fIpid\fP | \fIjobspec\fP] ...
9208 .PD 0
9209 .TP
9210 \fBkill\fP \fB\-l\fP|\fB\-L\fP [\fIsigspec\fP | \fIexit_status\fP]
9211 .PD
9212 Send the signal named by
9213 .I sigspec
9214 or
9215 .I signum
9216 to the processes named by
9217 .I pid
9218 or
9219 .IR jobspec .
9220 .I sigspec
9221 is either a case-insensitive signal name such as
9222 .SM
9223 .B SIGKILL
9224 (with or without the
9225 .SM
9226 .B SIG
9227 prefix) or a signal number;
9228 .I signum
9229 is a signal number.
9230 If
9231 .I sigspec
9232 is not present, then
9233 .SM
9234 .B SIGTERM
9235 is assumed.
9236 An argument of
9237 .B \-l
9238 lists the signal names.
9239 If any arguments are supplied when
9240 .B \-l
9241 is given, the names of the signals corresponding to the arguments are
9242 listed, and the return status is 0.
9243 The \fIexit_status\fP argument to
9244 .B \-l
9245 is a number specifying either a signal number or the exit status of
9246 a process terminated by a signal.
9247 The
9248 .B \-L
9249 option is equivalent to \fB\-l\fP.
9250 .B kill
9251 returns true if at least one signal was successfully sent, or false
9252 if an error occurs or an invalid option is encountered.
9253 .TP
9254 \fBlet\fP \fIarg\fP [\fIarg\fP ...]
9255 Each
9256 .I arg
9257 is an arithmetic expression to be evaluated (see
9258 .SM
9259 .B "ARITHMETIC EVALUATION"
9260 .ie \n(zZ=1 in \fIbash(1)\fP).
9261 .el above).
9262 If the last
9263 .I arg
9264 evaluates to 0,
9265 .B let
9266 returns 1; 0 is returned otherwise.
9267 .TP
9268 \fBlocal\fP [\fIoption\fP] [\fIname\fP[=\fIvalue\fP] ... | \- ]
9269 For each argument, a local variable named
9270 .I name
9271 is created, and assigned
9272 .IR value .
9273 The \fIoption\fP can be any of the options accepted by \fBdeclare\fP.
9274 When
9275 .B local
9276 is used within a function, it causes the variable
9277 .I name
9278 to have a visible scope restricted to that function and its children.
9279 If \fIname\fP is \-, the set of shell options is made local to the function
9280 in which \fBlocal\fP is invoked: shell options changed using the
9281 \fBset\fP builtin inside the function are restored to their original values
9282 when the function returns.
9283 The restore is effected as if a series of \fBset\fP commands were executed
9284 to restore the values that were in place before the function.
9285 With no operands,
9286 .B local
9287 writes a list of local variables to the standard output. It is
9288 an error to use
9289 .B local
9290 when not within a function. The return status is 0 unless
9291 .B local
9292 is used outside a function, an invalid
9293 .I name
9294 is supplied, or
9295 \fIname\fP is a readonly variable.
9296 .TP
9297 .B logout
9298 Exit a login shell.
9299 .TP
9300 \fBmapfile\fP [\fB\-d\fP \fIdelim\fP] [\fB\-n\fP \fIcount\fP] [\fB\-O\fP \fIorigin\fP] [\fB\-s\fP \fIcount\fP] [\fB\-t\fP] [\fB\-u\fP \fIfd\fP] [\fB\-C\fP \fIcallback\fP] [\fB\-c\fP \fIquantum\fP] [\fIarray\fP]
9301 .PD 0
9302 .TP
9303 \fBreadarray\fP [\fB\-d\fP \fIdelim\fP] [\fB\-n\fP \fIcount\fP] [\fB\-O\fP \fIorigin\fP] [\fB\-s\fP \fIcount\fP] [\fB\-t\fP] [\fB\-u\fP \fIfd\fP] [\fB\-C\fP \fIcallback\fP] [\fB\-c\fP \fIquantum\fP] [\fIarray\fP]
9304 .PD
9305 Read lines from the standard input into the indexed array variable
9306 .IR array ,
9307 or from file descriptor
9308 .I fd
9309 if the
9310 .B \-u
9311 option is supplied.
9312 The variable
9313 .SM
9314 .B MAPFILE
9315 is the default \fIarray\fP.
9316 Options, if supplied, have the following meanings:
9317 .RS
9318 .PD 0
9319 .TP
9320 .B \-d
9321 The first character of \fIdelim\fP is used to terminate each input line,
9322 rather than newline.
9323 If \fIdelim\fP is the empty string, \fBmapfile\fP will terminate a line
9324 when it reads a NUL character.
9325 .TP
9326 .B \-n
9327 Copy at most
9328 .I count
9329 lines. If \fIcount\fP is 0, all lines are copied.
9330 .TP
9331 .B \-O
9332 Begin assigning to
9333 .I array
9334 at index
9335 .IR origin .
9336 The default index is 0.
9337 .TP
9338 .B \-s
9339 Discard the first \fIcount\fP lines read.
9340 .TP
9341 .B \-t
9342 Remove a trailing \fIdelim\fP (default newline) from each line read.
9343 .TP
9344 .B \-u
9345 Read lines from file descriptor \fIfd\fP instead of the standard input.
9346 .TP
9347 .B \-C
9348 Evaluate
9349 .I callback
9350 each time \fIquantum\fP lines are read. The \fB\-c\fP option specifies
9351 .IR quantum .
9352 .TP
9353 .B \-c
9354 Specify the number of lines read between each call to
9355 .IR callback .
9356 .PD
9357 .PP
9358 If
9359 .B \-C
9360 is specified without
9361 .BR \-c ,
9362 the default quantum is 5000.
9363 When \fIcallback\fP is evaluated, it is supplied the index of the next
9364 array element to be assigned and the line to be assigned to that element
9365 as additional arguments.
9366 \fIcallback\fP is evaluated after the line is read but before the
9367 array element is assigned.
9368 .PP
9369 If not supplied with an explicit origin, \fBmapfile\fP will clear \fIarray\fP
9370 before assigning to it.
9371 .PP
9372 \fBmapfile\fP returns successfully unless an invalid option or option
9373 argument is supplied, \fIarray\fP is invalid or unassignable, or if
9374 \fIarray\fP is not an indexed array.
9375 .RE
9376 .TP
9377 \fBpopd\fP [\-\fBn\fP] [+\fIn\fP] [\-\fIn\fP]
9378 Removes entries from the directory stack.
9379 The elements are numbered from 0 starting at the first directory
9380 listed by \fBdirs\fP.
9381 With no arguments, \fBpopd\fP
9382 removes the top directory from the stack, and
9383 changes to the new top directory.
9384 Arguments, if supplied, have the following meanings:
9385 .RS
9386 .PD 0
9387 .TP
9388 .B \-n
9389 Suppresses the normal change of directory when removing directories
9390 from the stack, so that only the stack is manipulated.
9391 .TP
9392 \fB+\fP\fIn\fP
9393 Removes the \fIn\fPth entry counting from the left of the list
9394 shown by
9395 .BR dirs ,
9396 starting with zero, from the stack.
9397 For example:
9398 .if n ``popd +0''
9399 .if t \f(CWpopd +0\fP
9400 removes the first directory,
9401 .if n ``popd +1''
9402 .if t \f(CWpopd +1\fP
9403 the second.
9404 .TP
9405 \fB\-\fP\fIn\fP
9406 Removes the \fIn\fPth entry counting from the right of the list
9407 shown by
9408 .BR dirs ,
9409 starting with zero. For example:
9410 .if n ``popd -0''
9411 .if t \f(CWpopd -0\fP
9412 removes the last directory,
9413 .if n ``popd -1''
9414 .if t \f(CWpopd -1\fP
9415 the next to last.
9416 .PD
9417 .PP
9418 If the top element of the directory stack is modified, and
9419 the \fI-n\fP option was not supplied, \fBpopd\fP uses the \fBcd\fP
9420 builtin to change to the directory at the top of the stack.
9421 If the \fBcd\fP fails, \fBpopd\fP returns a non-zero value.
9422 .PP
9423 Otherwise,
9424 .B popd
9425 returns false if an invalid option is encountered, the directory stack
9426 is empty, or a non-existent directory stack entry is specified.
9427 .PP
9428 If the
9429 .B popd
9430 command is successful,
9431 bash runs
9432 .B dirs
9433 to show the final contents of the directory stack,
9434 and the return status is 0.
9435 .RE
9436 .TP
9437 \fBprintf\fP [\fB\-v\fP \fIvar\fP] \fIformat\fP [\fIarguments\fP]
9438 Write the formatted \fIarguments\fP to the standard output under the
9439 control of the \fIformat\fP.
9440 The \fB\-v\fP option causes the output to be assigned to the variable
9441 \fIvar\fP rather than being printed to the standard output.
9442 .sp 1
9443 The \fIformat\fP is a character string which contains three types of objects:
9444 plain characters, which are simply copied to standard output, character
9445 escape sequences, which are converted and copied to the standard output, and
9446 format specifications, each of which causes printing of the next successive
9447 \fIargument\fP.
9448 In addition to the standard \fIprintf\fP(1) format specifications,
9449 \fBprintf\fP interprets the following extensions:
9450 .RS
9451 .PD 0
9452 .TP
9453 .B %b
9454 causes
9455 \fBprintf\fP to expand backslash escape sequences in the corresponding
9456 \fIargument\fP
9457 in the same way as \fBecho \-e\fP.
9458 .TP
9459 .B %q
9460 causes \fBprintf\fP to output the corresponding
9461 \fIargument\fP in a format that can be reused as shell input.
9462 .TP
9463 .B %Q
9464 like \fB%q\fP, but applies any supplied precision to the \fIargument\fP
9465 before quoting it.
9466 .TP
9467 .B %(\fIdatefmt\fP)T
9468 causes \fBprintf\fP to output the date-time string resulting from using
9469 \fIdatefmt\fP as a format string for \fIstrftime\fP(3).
9470 The corresponding \fIargument\fP is an integer representing the number of
9471 seconds since the epoch.
9472 Two special argument values may be used: \-1 represents the current
9473 time, and \-2 represents the time the shell was invoked.
9474 If no argument is specified, conversion behaves as if \-1 had been given.
9475 This is an exception to the usual \fBprintf\fP behavior.
9476 .PD
9477 .PP
9478 The %b, %q, and %T directives all use the field width and precision
9479 arguments from the format specification and write that many bytes from
9480 (or use that wide a field for) the expanded argument, which usually
9481 contains more characters than the original.
9482 .PP
9483 Arguments to non-string format specifiers are treated as C constants,
9484 except that a leading plus or minus sign is allowed, and if the leading
9485 character is a single or double quote, the value is the ASCII value of
9486 the following character.
9487 .PP
9488 The \fIformat\fP is reused as necessary to consume all of the \fIarguments\fP.
9489 If the \fIformat\fP requires more \fIarguments\fP than are supplied, the
9490 extra format specifications behave as if a zero value or null string, as
9491 appropriate, had been supplied.
9492 The return value is zero on success, non-zero on failure.
9493 .RE
9494 .TP
9495 \fBpushd\fP [\fB\-n\fP] [+\fIn\fP] [\-\fIn\fP]
9496 .PD 0
9497 .TP
9498 \fBpushd\fP [\fB\-n\fP] [\fIdir\fP]
9499 .PD
9500 Adds a directory to the top of the directory stack, or rotates
9501 the stack, making the new top of the stack the current working
9502 directory.
9503 With no arguments, \fBpushd\fP exchanges the top two elements of
9504 the directory stack.
9505 Arguments, if supplied, have the following meanings:
9506 .RS
9507 .PD 0
9508 .TP
9509 .B \-n
9510 Suppresses the normal change of directory when rotating or
9511 adding directories to the stack, so that only the stack is manipulated.
9512 .TP
9513 \fB+\fP\fIn\fP
9514 Rotates the stack so that the \fIn\fPth directory
9515 (counting from the left of the list shown by
9516 .BR dirs ,
9517 starting with zero)
9518 is at the top.
9519 .TP
9520 \fB\-\fP\fIn\fP
9521 Rotates the stack so that the \fIn\fPth directory
9522 (counting from the right of the list shown by
9523 .BR dirs ,
9524 starting with zero) is at the top.
9525 .TP
9526 .I dir
9527 Adds
9528 .I dir
9529 to the directory stack at the top
9530 .PD
9531 .PP
9532 After the stack has been modified, if the \fB\-n\fP option was not
9533 supplied, \fBpushd\fP uses the \fBcd\fP builtin to change to the
9534 directory at the top of the stack.
9535 If the \fBcd\fP fails, \fBpushd\fP returns a non-zero value.
9536 .PP
9537 Otherwise, if no arguments are supplied,
9538 .B pushd
9539 returns 0 unless the directory stack is empty.
9540 When rotating the directory stack,
9541 .B pushd
9542 returns 0 unless the directory stack is empty or
9543 a non-existent directory stack element is specified.
9544 .PP
9545 If the
9546 .B pushd
9547 command is successful,
9548 bash runs
9549 .B dirs
9550 to show the final contents of the directory stack.
9551 .RE
9552 .TP
9553 \fBpwd\fP [\fB\-LP\fP]
9554 Print the absolute pathname of the current working directory.
9555 The pathname printed contains no symbolic links if the
9556 .B \-P
9557 option is supplied or the
9558 .B \-o physical
9559 option to the
9560 .B set
9561 builtin command is enabled.
9562 If the
9563 .B \-L
9564 option is used, the pathname printed may contain symbolic links.
9565 The return status is 0 unless an error occurs while
9566 reading the name of the current directory or an
9567 invalid option is supplied.
9568 .TP
9569 \fBread\fP [\fB\-ers\fP] [\fB\-a\fP \fIaname\fP] [\fB\-d\fP \fIdelim\fP] [\fB\-i\fP \fItext\fP] [\fB\-n\fP \fInchars\fP] [\fB\-N\fP \fInchars\fP] [\fB\-p\fP \fIprompt\fP] [\fB\-t\fP \fItimeout\fP] [\fB\-u\fP \fIfd\fP] [\fIname\fP ...]
9570 One line is read from the standard input, or from the file descriptor
9571 \fIfd\fP supplied as an argument to the \fB\-u\fP option,
9572 split into words as described
9573 .ie \n(zZ=1 in \fIbash(1)\fP
9574 .el above
9575 under \fBWord Splitting\fP,
9576 and the first word
9577 is assigned to the first
9578 .IR name ,
9579 the second word to the second
9580 .IR name ,
9581 and so on.
9582 If there are more words than names, the remaining words and their
9583 intervening delimiters are assigned to the last
9584 .IR name .
9585 If there are fewer words read from the input stream than names,
9586 the remaining names are assigned empty values.
9587 The characters in
9588 .SM
9589 .B IFS
9590 are used to split the line into words using the same rules the shell
9591 uses for expansion (described
9592 .ie \n(zZ=1 in \fIbash(1)\fP
9593 .el above
9594 under \fBWord Splitting\fP).
9595 The backslash character (\fB\e\fP) may be used to remove any special
9596 meaning for the next character read and for line continuation.
9597 Options, if supplied, have the following meanings:
9598 .RS
9599 .PD 0
9600 .TP
9601 .B \-a \fIaname\fP
9602 The words are assigned to sequential indices
9603 of the array variable
9604 .IR aname ,
9605 starting at 0.
9606 .I aname
9607 is unset before any new values are assigned.
9608 Other \fIname\fP arguments are ignored.
9609 .TP
9610 .B \-d \fIdelim\fP
9611 The first character of \fIdelim\fP is used to terminate the input line,
9612 rather than newline.
9613 If \fIdelim\fP is the empty string, \fBread\fP will terminate a line
9614 when it reads a NUL character.
9615 .TP
9616 .B \-e
9617 If the standard input
9618 is coming from a terminal,
9619 .B readline
9620 (see
9621 .SM
9622 .B READLINE
9623 .ie \n(zZ=1 in \fIbash(1)\fP)
9624 .el above)
9625 is used to obtain the line.
9626 Readline uses the current (or default, if line editing was not previously
9627 active) editing settings, but uses readline's default filename completion.
9628 .TP
9629 .B \-i \fItext\fP
9630 If
9631 .B readline
9632 is being used to read the line, \fItext\fP is placed into the editing
9633 buffer before editing begins.
9634 .TP
9635 .B \-n \fInchars\fP
9636 \fBread\fP returns after reading \fInchars\fP characters rather than
9637 waiting for a complete line of input, but honors a delimiter if fewer
9638 than \fInchars\fP characters are read before the delimiter.
9639 .TP
9640 .B \-N \fInchars\fP
9641 \fBread\fP returns after reading exactly \fInchars\fP characters rather
9642 than waiting for a complete line of input, unless EOF is encountered or
9643 \fBread\fP times out.
9644 Delimiter characters encountered in the input are
9645 not treated specially and do not cause \fBread\fP to return until
9646 \fInchars\fP characters are read.
9647 The result is not split on the characters in \fBIFS\fP; the intent is
9648 that the variable is assigned exactly the characters read
9649 (with the exception of backslash; see the \fB\-r\fP option below).
9650 .TP
9651 .B \-p \fIprompt\fP
9652 Display \fIprompt\fP on standard error, without a
9653 trailing newline, before attempting to read any input. The prompt
9654 is displayed only if input is coming from a terminal.
9655 .TP
9656 .B \-r
9657 Backslash does not act as an escape character.
9658 The backslash is considered to be part of the line.
9659 In particular, a backslash-newline pair may not then be used as a line
9660 continuation.
9661 .TP
9662 .B \-s
9663 Silent mode. If input is coming from a terminal, characters are
9664 not echoed.
9665 .TP
9666 .B \-t \fItimeout\fP
9667 Cause \fBread\fP to time out and return failure if a complete line of
9668 input (or a specified number of characters)
9669 is not read within \fItimeout\fP seconds.
9670 \fItimeout\fP may be a decimal number with a fractional portion following
9671 the decimal point.
9672 This option is only effective if \fBread\fP is reading input from a
9673 terminal, pipe, or other special file; it has no effect when reading
9674 from regular files.
9675 If \fBread\fP times out, \fBread\fP saves any partial input read into
9676 the specified variable \fIname\fP.
9677 If \fItimeout\fP is 0, \fBread\fP returns immediately, without trying to
9678 read any data.
9679 The exit status is 0 if input is available on the specified file descriptor,
9680 or the read will return EOF,
9681 non-zero otherwise.
9682 The exit status is greater than 128 if the timeout is exceeded.
9683 .TP
9684 .B \-u \fIfd\fP
9685 Read input from file descriptor \fIfd\fP.
9686 .PD
9687 .PP
9688 If no
9689 .I names
9690 are supplied, the line read,
9691 without the ending delimiter but otherwise unmodified,
9692 is assigned to the variable
9693 .SM
9694 .BR REPLY .
9695 The exit status is zero, unless end-of-file is encountered, \fBread\fP
9696 times out (in which case the status is greater than 128),
9697 a variable assignment error (such as assigning to a readonly variable) occurs,
9698 or an invalid file descriptor is supplied as the argument to \fB\-u\fP.
9699 .RE
9700 .TP
9701 \fBreadonly\fP [\fB\-aAf\fP] [\fB\-p\fP] [\fIname\fP[=\fIword\fP] ...]
9702 .PD
9703 The given
9704 \fInames\fP are marked readonly; the values of these
9705 .I names
9706 may not be changed by subsequent assignment.
9707 If the
9708 .B \-f
9709 option is supplied, the functions corresponding to the
9710 \fInames\fP are so
9711 marked.
9712 The
9713 .B \-a
9714 option restricts the variables to indexed arrays; the
9715 .B \-A
9716 option restricts the variables to associative arrays.
9717 If both options are supplied,
9718 .B \-A
9719 takes precedence.
9720 If no
9721 .I name
9722 arguments are given, or if the
9723 .B \-p
9724 option is supplied, a list of all readonly names is printed.
9725 The other options may be used to restrict the output to a subset of
9726 the set of readonly names.
9727 The
9728 .B \-p
9729 option causes output to be displayed in a format that
9730 may be reused as input.
9731 If a variable name is followed by =\fIword\fP, the value of
9732 the variable is set to \fIword\fP.
9733 The return status is 0 unless an invalid option is encountered,
9734 one of the
9735 .I names
9736 is not a valid shell variable name, or
9737 .B \-f
9738 is supplied with a
9739 .I name
9740 that is not a function.
9741 .TP
9742 \fBreturn\fP [\fIn\fP]
9743 Causes a function to stop executing and return the value specified by
9744 .I n
9745 to its caller.
9746 If
9747 .I n
9748 is omitted, the return status is that of the last command
9749 executed in the function body.
9750 If \fBreturn\fP is executed by a trap handler, the last command used to
9751 determine the status is the last command executed before the trap handler.
9752 If \fBreturn\fP is executed during a \fBDEBUG\fP trap, the last command
9753 used to determine the status is the last command executed by the trap
9754 handler before \fBreturn\fP was invoked.
9755 If
9756 .B return
9757 is used outside a function,
9758 but during execution of a script by the
9759 .B .
9760 (\fBsource\fP) command, it causes the shell to stop executing
9761 that script and return either
9762 .I n
9763 or the exit status of the last command executed within the
9764 script as the exit status of the script.
9765 If \fIn\fP is supplied, the return value is its least significant
9766 8 bits.
9767 The return status is non-zero if
9768 .B return
9769 is supplied a non-numeric argument, or
9770 is used outside a
9771 function and not during execution of a script by \fB.\fP\^ or \fBsource\fP.
9772 Any command associated with the \fBRETURN\fP trap is executed
9773 before execution resumes after the function or script.
9774 .TP
9775 \fBset\fP [\fB\-abefhkmnptuvxBCEHPT\fP] [\fB\-o\fP \fIoption\-name\fP] [\fB\-\-\fP] [\fB\-\fP] [\fIarg\fP ...]
9776 .PD 0
9777 .TP
9778 \fBset\fP [\fB+abefhkmnptuvxBCEHPT\fP] [\fB+o\fP \fIoption\-name\fP] [\fB\-\-\fP] [\fB\-\fP] [\fIarg\fP ...]
9779 .PD
9780 Without options, display the name and value of each shell variable
9781 in a format that can be reused as input
9782 for setting or resetting the currently-set variables.
9783 Read-only variables cannot be reset.
9784 In \fIposix mode\fP, only shell variables are listed.
9785 The output is sorted according to the current locale.
9786 When options are specified, they set or unset shell attributes.
9787 Any arguments remaining after option processing are treated
9788 as values for the positional parameters and are assigned, in order, to
9789 .BR $1 ,
9790 .BR $2 ,
9791 .B ...
9792 .BR $\fIn\fP .
9793 Options, if specified, have the following meanings:
9794 .RS
9795 .PD 0
9796 .TP 8
9797 .B \-a
9798 Each variable or function that is created or modified is given the
9799 export attribute and marked for export to the environment of
9800 subsequent commands.
9801 .TP 8
9802 .B \-b
9803 Report the status of terminated background jobs
9804 immediately, rather than before the next primary prompt. This is
9805 effective only when job control is enabled.
9806 .TP 8
9807 .B \-e
9808 Exit immediately if a
9809 \fIpipeline\fP (which may consist of a single \fIsimple command\fP),
9810 a \fIlist\fP,
9811 or a \fIcompound command\fP
9812 (see
9813 .SM
9814 .B SHELL GRAMMAR
9815 .ie \n(zZ=1 in \fIbash(1)\fP),
9816 .el above),
9817 exits with a non-zero status.
9818 The shell does not exit if the
9819 command that fails is part of the command list immediately following a
9820 .B while
9821 or
9822 .B until
9823 keyword,
9824 part of the test following the
9825 .B if
9826 or
9827 .B elif
9828 reserved words, part of any command executed in a
9829 .B &&
9830 or
9831 .B ||
9832 list except the command following the final \fB&&\fP or \fB||\fP,
9833 any command in a pipeline but the last,
9834 or if the command's return value is
9835 being inverted with
9836 .BR ! .
9837 If a compound command other than a subshell
9838 returns a non-zero status because a command failed
9839 while \fB\-e\fP was being ignored, the shell does not exit.
9840 A trap on \fBERR\fP, if set, is executed before the shell exits.
9841 This option applies to the shell environment and each subshell environment
9842 separately (see
9843 .SM
9844 .B "COMMAND EXECUTION ENVIRONMENT"
9845 .ie \n(zZ=1 in \fIbash(1)\fP),
9846 .el above),
9847 and may cause
9848 subshells to exit before executing all the commands in the subshell.
9849 .if t .sp 0.5
9850 .if n .sp 1
9851 If a compound command or shell function executes in a context
9852 where \fB\-e\fP is being ignored,
9853 none of the commands executed within the compound command or function body
9854 will be affected by the \fB\-e\fP setting, even if \fB\-e\fP is set
9855 and a command returns a failure status.
9856 If a compound command or shell function sets \fB\-e\fP while executing in
9857 a context where \fB\-e\fP is ignored, that setting will not have any
9858 effect until the compound command or the command containing the function
9859 call completes.
9860 .TP 8
9861 .B \-f
9862 Disable pathname expansion.
9863 .TP 8
9864 .B \-h
9865 Remember the location of commands as they are looked up for execution.
9866 This is enabled by default.
9867 .TP 8
9868 .B \-k
9869 All arguments in the form of assignment statements
9870 are placed in the environment for a command, not just
9871 those that precede the command name.
9872 .TP 8
9873 .B \-m
9874 Monitor mode. Job control is enabled. This option is on
9875 by default for interactive shells on systems that support
9876 it (see
9877 .SM
9878 .B JOB CONTROL
9879 .ie \n(zZ=1 in \fIbash(1)\fP).
9880 .el above).
9881 All processes run in a separate process group.
9882 When a background job completes, the shell prints a line
9883 containing its exit status.
9884 .TP 8
9885 .B \-n
9886 Read commands but do not execute them.
9887 This may be used to check a shell script for syntax errors.
9888 This is ignored by interactive shells.
9889 .TP 8
9890 .B \-o \fIoption\-name\fP
9891 The \fIoption\-name\fP can be one of the following:
9892 .RS
9893 .TP 8
9894 .B allexport
9895 Same as
9896 .BR \-a .
9897 .TP 8
9898 .B braceexpand
9899 Same as
9900 .BR \-B .
9901 .TP 8
9902 .B emacs
9903 Use an emacs-style command line editing interface. This is enabled
9904 by default when the shell is interactive, unless the shell is started
9905 with the
9906 .B \-\-noediting
9907 option.
9908 This also affects the editing interface used for \fBread \-e\fP.
9909 .TP 8
9910 .B errexit
9911 Same as
9912 .BR \-e .
9913 .TP 8
9914 .B errtrace
9915 Same as
9916 .BR \-E .
9917 .TP 8
9918 .B functrace
9919 Same as
9920 .BR \-T .
9921 .TP 8
9922 .B hashall
9923 Same as
9924 .BR \-h .
9925 .TP 8
9926 .B histexpand
9927 Same as
9928 .BR \-H .
9929 .TP 8
9930 .B history
9931 Enable command history, as described
9932 .ie \n(zZ=1 in \fIbash(1)\fP
9933 .el above
9934 under
9935 .SM
9936 .BR HISTORY .
9937 This option is on by default in interactive shells.
9938 .TP 8
9939 .B ignoreeof
9940 The effect is as if the shell command
9941 .if t \f(CWIGNOREEOF=10\fP
9942 .if n ``IGNOREEOF=10''
9943 had been executed
9944 (see
9945 .B Shell Variables
9946 .ie \n(zZ=1 in \fIbash(1)\fP).
9947 .el above).
9948 .TP 8
9949 .B keyword
9950 Same as
9951 .BR \-k .
9952 .TP 8
9953 .B monitor
9954 Same as
9955 .BR \-m .
9956 .TP 8
9957 .B noclobber
9958 Same as
9959 .BR \-C .
9960 .TP 8
9961 .B noexec
9962 Same as
9963 .BR \-n .
9964 .TP 8
9965 .B noglob
9966 Same as
9967 .BR \-f .
9968 .TP 8
9969 .B nolog
9970 Currently ignored.
9971 .TP 8
9972 .B notify
9973 Same as
9974 .BR \-b .
9975 .TP 8
9976 .B nounset
9977 Same as
9978 .BR \-u .
9979 .TP 8
9980 .B onecmd
9981 Same as
9982 .BR \-t .
9983 .TP 8
9984 .B physical
9985 Same as
9986 .BR \-P .
9987 .TP 8
9988 .B pipefail
9989 If set, the return value of a pipeline is the value of the last
9990 (rightmost) command to exit with a non-zero status, or zero if all
9991 commands in the pipeline exit successfully.
9992 This option is disabled by default.
9993 .TP 8
9994 .B posix
9995 Change the behavior of
9996 .B bash
9997 where the default operation differs
9998 from the POSIX standard to match the standard (\fIposix mode\fP).
9999 See
10000 .SM
10001 .B "SEE ALSO"
10002 .ie \n(zZ=1 in \fIbash(1)\fP
10003 .el below
10004 for a reference to a document that details how posix mode affects
10005 bash's behavior.
10006 .TP 8
10007 .B privileged
10008 Same as
10009 .BR \-p .
10010 .TP 8
10011 .B verbose
10012 Same as
10013 .BR \-v .
10014 .TP 8
10015 .B vi
10016 Use a vi-style command line editing interface.
10017 This also affects the editing interface used for \fBread \-e\fP.
10018 .TP 8
10019 .B xtrace
10020 Same as
10021 .BR \-x .
10022 .sp .5
10023 .PP
10024 If
10025 .B \-o
10026 is supplied with no \fIoption\-name\fP, the values of the current options are
10027 printed.
10028 If
10029 .B +o
10030 is supplied with no \fIoption\-name\fP, a series of
10031 .B set
10032 commands to recreate the current option settings is displayed on
10033 the standard output.
10034 .RE
10035 .TP 8
10036 .B \-p
10037 Turn on
10038 .I privileged
10039 mode. In this mode, the
10040 .SM
10041 .B $ENV
10042 and
10043 .SM
10044 .B $BASH_ENV
10045 files are not processed, shell functions are not inherited from the
10046 environment, and the
10047 .SM
10048 .BR SHELLOPTS ,
10049 .SM
10050 .BR BASHOPTS ,
10051 .SM
10052 .BR CDPATH ,
10053 and
10054 .SM
10055 .B GLOBIGNORE
10056 variables, if they appear in the environment, are ignored.
10057 If the shell is started with the effective user (group) id not equal to the
10058 real user (group) id, and the \fB\-p\fP option is not supplied, these actions
10059 are taken and the effective user id is set to the real user id.
10060 If the \fB\-p\fP option is supplied at startup, the effective user id is
10061 not reset.
10062 Turning this option off causes the effective user
10063 and group ids to be set to the real user and group ids.
10064 .TP 8
10065 .B \-r
10066 Enable restricted shell mode.
10067 This option cannot be unset once it has been set.
10068 .TP 8
10069 .B \-t
10070 Exit after reading and executing one command.
10071 .TP 8
10072 .B \-u
10073 Treat unset variables and parameters other than the special
10074 parameters "@" and "*",
10075 or array variables subscripted with "@" or "*",
10076 as an error when performing
10077 parameter expansion. If expansion is attempted on an
10078 unset variable or parameter, the shell prints an error message, and,
10079 if not interactive, exits with a non-zero status.
10080 .TP 8
10081 .B \-v
10082 Print shell input lines as they are read.
10083 .TP 8
10084 .B \-x
10085 After expanding each \fIsimple command\fP,
10086 \fBfor\fP command, \fBcase\fP command, \fBselect\fP command, or
10087 arithmetic \fBfor\fP command, display the expanded value of
10088 .SM
10089 .BR PS4 ,
10090 followed by the command and its expanded arguments
10091 or associated word list.
10092 .TP 8
10093 .B \-B
10094 The shell performs brace expansion (see
10095 .B Brace Expansion
10096 .ie \n(zZ=1 in \fIbash(1)\fP).
10097 .el above).
10098 This is on by default.
10099 .TP 8
10100 .B \-C
10101 If set,
10102 .B bash
10103 does not overwrite an existing file with the
10104 .BR > ,
10105 .BR >& ,
10106 and
10107 .B <>
10108 redirection operators. This may be overridden when
10109 creating output files by using the redirection operator
10110 .B >|
10111 instead of
10112 .BR > .
10113 .TP 8
10114 .B \-E
10115 If set, any trap on \fBERR\fP is inherited by shell functions, command
10116 substitutions, and commands executed in a subshell environment.
10117 The \fBERR\fP trap is normally not inherited in such cases.
10118 .TP 8
10119 .B \-H
10120 Enable
10121 .B !
10122 style history substitution. This option is on by
10123 default when the shell is interactive.
10124 .TP 8
10125 .B \-P
10126 If set, the shell does not resolve symbolic links when executing
10127 commands such as
10128 .B cd
10129 that change the current working directory. It uses the
10130 physical directory structure instead. By default,
10131 .B bash
10132 follows the logical chain of directories when performing commands
10133 which change the current directory.
10134 .TP 8
10135 .B \-T
10136 If set, any traps on \fBDEBUG\fP and \fBRETURN\fP are inherited by shell
10137 functions, command substitutions, and commands executed in a
10138 subshell environment.
10139 The \fBDEBUG\fP and \fBRETURN\fP traps are normally not inherited
10140 in such cases.
10141 .TP 8
10142 .B \-\-
10143 If no arguments follow this option, then the positional parameters are
10144 unset. Otherwise, the positional parameters are set to the
10145 \fIarg\fPs, even if some of them begin with a
10146 .BR \- .
10147 .TP 8
10148 .B \-
10149 Signal the end of options, cause all remaining \fIarg\fPs to be
10150 assigned to the positional parameters. The
10151 .B \-x
10152 and
10153 .B \-v
10154 options are turned off.
10155 If there are no \fIarg\fPs,
10156 the positional parameters remain unchanged.
10157 .PD
10158 .PP
10159 The options are off by default unless otherwise noted.
10160 Using + rather than \- causes these options to be turned off.
10161 The options can also be specified as arguments to an invocation of
10162 the shell.
10163 The current set of options may be found in
10164 .BR $\- .
10165 The return status is always true unless an invalid option is encountered.
10166 .RE
10167 .TP
10168 \fBshift\fP [\fIn\fP]
10169 The positional parameters from \fIn\fP+1 ... are renamed to
10170 .B $1
10171 .B ....
10172 Parameters represented by the numbers \fB$#\fP
10173 down to \fB$#\fP\-\fIn\fP+1 are unset.
10174 .I n
10175 must be a non-negative number less than or equal to \fB$#\fP.
10176 If
10177 .I n
10178 is 0, no parameters are changed.
10179 If
10180 .I n
10181 is not given, it is assumed to be 1.
10182 If
10183 .I n
10184 is greater than \fB$#\fP, the positional parameters are not changed.
10185 The return status is greater than zero if
10186 .I n
10187 is greater than
10188 .B $#
10189 or less than zero; otherwise 0.
10190 .TP
10191 \fBshopt\fP [\fB\-pqsu\fP] [\fB\-o\fP] [\fIoptname\fP ...]
10192 Toggle the values of settings controlling optional shell behavior.
10193 The settings can be either those listed below, or, if the
10194 .B \-o
10195 option is used, those available with the
10196 .B \-o
10197 option to the \fBset\fP builtin command.
10198 With no options, or with the
10199 .B \-p
10200 option, a list of all settable options is displayed, with
10201 an indication of whether or not each is set;
10202 if \fIoptnames\fP are supplied, the output is restricted to those options.
10203 The \fB\-p\fP option causes output to be displayed in a form that
10204 may be reused as input.
10205 Other options have the following meanings:
10206 .RS
10207 .PD 0
10208 .TP
10209 .B \-s
10210 Enable (set) each \fIoptname\fP.
10211 .TP
10212 .B \-u
10213 Disable (unset) each \fIoptname\fP.
10214 .TP
10215 .B \-q
10216 Suppresses normal output (quiet mode); the return status indicates
10217 whether the \fIoptname\fP is set or unset.
10218 If multiple \fIoptname\fP arguments are given with
10219 .BR \-q ,
10220 the return status is zero if all \fIoptnames\fP are enabled; non-zero
10221 otherwise.
10222 .TP
10223 .B \-o
10224 Restricts the values of \fIoptname\fP to be those defined for the
10225 .B \-o
10226 option to the
10227 .B set
10228 builtin.
10229 .PD
10230 .PP
10231 If either
10232 .B \-s
10233 or
10234 .B \-u
10235 is used with no \fIoptname\fP arguments,
10236 .B shopt
10237 shows only those options which are set or unset, respectively.
10238 Unless otherwise noted, the \fBshopt\fP options are disabled (unset)
10239 by default.
10240 .PP
10241 The return status when listing options is zero if all \fIoptnames\fP
10242 are enabled, non-zero otherwise. When setting or unsetting options,
10243 the return status is zero unless an \fIoptname\fP is not a valid shell
10244 option.
10245 .PP
10246 The list of \fBshopt\fP options is:
10247 .if t .sp .5v
10248 .if n .sp 1v
10249 .PD 0
10250 .TP 8
10251 .B assoc_expand_once
10252 If set, the shell suppresses multiple evaluation of associative array
10253 subscripts during arithmetic expression evaluation, while executing
10254 builtins that can perform variable assignments,
10255 and while executing builtins that perform array dereferencing.
10256 .TP 8
10257 .B autocd
10258 If set, a command name that is the name of a directory is executed as if
10259 it were the argument to the \fBcd\fP command.
10260 This option is only used by interactive shells.
10261 .TP 8
10262 .B cdable_vars
10263 If set, an argument to the
10264 .B cd
10265 builtin command that
10266 is not a directory is assumed to be the name of a variable whose
10267 value is the directory to change to.
10268 .TP 8
10269 .B cdspell
10270 If set, minor errors in the spelling of a directory component in a
10271 .B cd
10272 command will be corrected.
10273 The errors checked for are transposed characters,
10274 a missing character, and one character too many.
10275 If a correction is found, the corrected filename is printed,
10276 and the command proceeds.
10277 This option is only used by interactive shells.
10278 .TP 8
10279 .B checkhash
10280 If set, \fBbash\fP checks that a command found in the hash
10281 table exists before trying to execute it. If a hashed command no
10282 longer exists, a normal path search is performed.
10283 .TP 8
10284 .B checkjobs
10285 If set, \fBbash\fP lists the status of any stopped and running jobs before
10286 exiting an interactive shell. If any jobs are running, this causes
10287 the exit to be deferred until a second exit is attempted without an
10288 intervening command (see
10289 .SM
10290 .B "JOB CONTROL"
10291 .ie \n(zZ=1 in \fIbash(1)\fP).
10292 .el above).
10293 The shell always postpones exiting if any jobs are stopped.
10294 .TP 8
10295 .B checkwinsize
10296 If set, \fBbash\fP checks the window size after each external (non-builtin)
10297 command and, if necessary, updates the values of
10298 .SM
10299 .B LINES
10300 and
10301 .SM
10302 .BR COLUMNS .
10303 This option is enabled by default.
10304 .TP 8
10305 .B cmdhist
10306 If set,
10307 .B bash
10308 attempts to save all lines of a multiple-line
10309 command in the same history entry. This allows
10310 easy re-editing of multi-line commands.
10311 This option is enabled by default, but only has an effect if command
10312 history is enabled, as described
10313 .ie \n(zZ=1 in \fIbash(1)\fP
10314 .el above
10315 under
10316 .SM
10317 .BR HISTORY .
10318 .PD 0
10319 .TP 8
10320 .B compat31
10321 .TP 8
10322 .B compat32
10323 .TP 8
10324 .B compat40
10325 .TP 8
10326 .B compat41
10327 .TP 8
10328 .B compat42
10329 .TP 8
10330 .B compat43
10331 .TP 8
10332 .B compat44
10333 .TP 8
10334 .B compat50
10335 .PD
10336 These control aspects of the shell's compatibility mode
10337 (see
10338 .SM
10339 .B "SHELL COMPATIBILITY MODE"
10340 .ie \n(zZ=1 in \fIbash(1)\fP).
10341 .el below).
10342 .TP 8
10343 .B complete_fullquote
10344 If set,
10345 .B bash
10346 quotes all shell metacharacters in filenames and directory names when
10347 performing completion.
10348 If not set,
10349 .B bash
10350 removes metacharacters such as the dollar sign from the set of
10351 characters that will be quoted in completed filenames
10352 when these metacharacters appear in shell variable references in words to be
10353 completed.
10354 This means that dollar signs in variable names that expand to directories
10355 will not be quoted;
10356 however, any dollar signs appearing in filenames will not be quoted, either.
10357 This is active only when bash is using backslashes to quote completed
10358 filenames.
10359 This variable is set by default, which is the default bash behavior in
10360 versions through 4.2.
10361 .TP 8
10362 .B direxpand
10363 If set,
10364 .B bash
10365 replaces directory names with the results of word expansion when performing
10366 filename completion. This changes the contents of the readline editing
10367 buffer.
10368 If not set,
10369 .B bash
10370 attempts to preserve what the user typed.
10371 .TP 8
10372 .B dirspell
10373 If set,
10374 .B bash
10375 attempts spelling correction on directory names during word completion
10376 if the directory name initially supplied does not exist.
10377 .TP 8
10378 .B dotglob
10379 If set,
10380 .B bash
10381 includes filenames beginning with a `.' in the results of pathname
10382 expansion.
10383 The filenames
10384 .B ``.''
10385 and
10386 .B ``..''
10387 must always be matched explicitly, even if
10388 .B dotglob
10389 is set.
10390 .TP 8
10391 .B execfail
10392 If set, a non-interactive shell will not exit if
10393 it cannot execute the file specified as an argument to the
10394 .B exec
10395 builtin command. An interactive shell does not exit if
10396 .B exec
10397 fails.
10398 .TP 8
10399 .B expand_aliases
10400 If set, aliases are expanded as described
10401 .ie \n(zZ=1 in \fIbash(1)\fP
10402 .el above
10403 under
10404 .SM
10405 .BR ALIASES .
10406 This option is enabled by default for interactive shells.
10407 .TP 8
10408 .B extdebug
10409 If set at shell invocation,
10410 or in a shell startup file,
10411 arrange to execute the debugger profile
10412 before the shell starts, identical to the \fB\-\-debugger\fP option.
10413 If set after invocation, behavior intended for use by debuggers is enabled:
10414 .RS
10415 .TP
10416 .B 1.
10417 The \fB\-F\fP option to the \fBdeclare\fP builtin displays the source
10418 file name and line number corresponding to each function name supplied
10419 as an argument.
10420 .TP
10421 .B 2.
10422 If the command run by the \fBDEBUG\fP trap returns a non-zero value, the
10423 next command is skipped and not executed.
10424 .TP
10425 .B 3.
10426 If the command run by the \fBDEBUG\fP trap returns a value of 2, and the
10427 shell is executing in a subroutine (a shell function or a shell script
10428 executed by the \fB.\fP or \fBsource\fP builtins), the shell simulates
10429 a call to \fBreturn\fP.
10430 .TP
10431 .B 4.
10432 .SM
10433 .B BASH_ARGC
10434 and
10435 .SM
10436 .B BASH_ARGV
10437 are updated as described in their descriptions
10438 .ie \n(zZ=1 in \fIbash(1)\fP).
10439 .el above).
10440 .TP
10441 .B 5.
10442 Function tracing is enabled: command substitution, shell functions, and
10443 subshells invoked with \fB(\fP \fIcommand\fP \fB)\fP inherit the
10444 \fBDEBUG\fP and \fBRETURN\fP traps.
10445 .TP
10446 .B 6.
10447 Error tracing is enabled: command substitution, shell functions, and
10448 subshells invoked with \fB(\fP \fIcommand\fP \fB)\fP inherit the
10449 \fBERR\fP trap.
10450 .RE
10451 .TP 8
10452 .B extglob
10453 If set, the extended pattern matching features described
10454 .ie \n(zZ=1 in \fIbash(1)\fP
10455 .el above
10456 under
10457 \fBPathname Expansion\fP are enabled.
10458 .TP 8
10459 .B extquote
10460 If set, \fB$\fP\(aq\fIstring\fP\(aq and \fB$\fP"\fIstring\fP" quoting is
10461 performed within \fB${\fP\fIparameter\fP\fB}\fP expansions
10462 enclosed in double quotes. This option is enabled by default.
10463 .TP 8
10464 .B failglob
10465 If set, patterns which fail to match filenames during pathname expansion
10466 result in an expansion error.
10467 .TP 8
10468 .B force_fignore
10469 If set, the suffixes specified by the
10470 .SM
10471 .B FIGNORE
10472 shell variable
10473 cause words to be ignored when performing word completion even if
10474 the ignored words are the only possible completions.
10475 See
10476 .SM
10477 \fBSHELL VARIABLES\fP
10478 .ie \n(zZ=1 in \fIbash(1)\fP
10479 .el above
10480 for a description of
10481 .SM
10482 .BR FIGNORE .
10483 This option is enabled by default.
10484 .TP 8
10485 .B globasciiranges
10486 If set, range expressions used in pattern matching bracket expressions (see
10487 .SM
10488 .B Pattern Matching
10489 .ie \n(zZ=1 in \fIbash(1)\fP)
10490 .el above)
10491 behave as if in the traditional C locale when performing
10492 comparisons. That is, the current locale's collating sequence
10493 is not taken into account, so
10494 .B b
10495 will not collate between
10496 .B A
10497 and
10498 .BR B ,
10499 and upper-case and lower-case ASCII characters will collate together.
10500 .TP 8
10501 .B globskipdots
10502 If set, pathname expansion will never match the filenames
10503 .B ``.''
10504 and
10505 .BR ``..'' ,
10506 even if the pattern begins with a
10507 .BR ``.'' .
10508 This option is enabled by default.
10509 .TP 8
10510 .B globstar
10511 If set, the pattern \fB**\fP used in a pathname expansion context will
10512 match all files and zero or more directories and subdirectories.
10513 If the pattern is followed by a \fB/\fP, only directories and
10514 subdirectories match.
10515 .TP 8
10516 .B gnu_errfmt
10517 If set, shell error messages are written in the standard GNU error
10518 message format.
10519 .TP 8
10520 .B histappend
10521 If set, the history list is appended to the file named by the value
10522 of the
10523 .SM
10524 .B HISTFILE
10525 variable when the shell exits, rather than overwriting the file.
10526 .TP 8
10527 .B histreedit
10528 If set, and
10529 .B readline
10530 is being used, a user is given the opportunity to re-edit a
10531 failed history substitution.
10532 .TP 8
10533 .B histverify
10534 If set, and
10535 .B readline
10536 is being used, the results of history substitution are not immediately
10537 passed to the shell parser. Instead, the resulting line is loaded into
10538 the \fBreadline\fP editing buffer, allowing further modification.
10539 .TP 8
10540 .B hostcomplete
10541 If set, and
10542 .B readline
10543 is being used, \fBbash\fP will attempt to perform hostname completion when a
10544 word containing a \fB@\fP is being completed (see
10545 .B Completing
10546 under
10547 .SM
10548 .B READLINE
10549 .ie \n(zZ=1 in \fIbash(1)\fP).
10550 .el above).
10551 This is enabled by default.
10552 .TP 8
10553 .B huponexit
10554 If set, \fBbash\fP will send
10555 .SM
10556 .B SIGHUP
10557 to all jobs when an interactive login shell exits.
10558 .TP 8
10559 .B inherit_errexit
10560 If set, command substitution inherits the value of the \fBerrexit\fP option,
10561 instead of unsetting it in the subshell environment.
10562 This option is enabled when \fIposix mode\fP is enabled.
10563 .TP 8
10564 .B interactive_comments
10565 If set, allow a word beginning with
10566 .B #
10567 to cause that word and all remaining characters on that
10568 line to be ignored in an interactive shell (see
10569 .SM
10570 .B COMMENTS
10571 .ie \n(zZ=1 in \fIbash(1)\fP).
10572 .el above).
10573 This option is enabled by default.
10574 .TP 8
10575 .B lastpipe
10576 If set, and job control is not active, the shell runs the last command of
10577 a pipeline not executed in the background in the current shell environment.
10578 .TP 8
10579 .B lithist
10580 If set, and the
10581 .B cmdhist
10582 option is enabled, multi-line commands are saved to the history with
10583 embedded newlines rather than using semicolon separators where possible.
10584 .TP 8
10585 .B localvar_inherit
10586 If set, local variables inherit the value and attributes of a variable of
10587 the same name that exists at a previous scope before any new value is
10588 assigned. The nameref attribute is not inherited.
10589 .TP 8
10590 .B localvar_unset
10591 If set, calling \fBunset\fP on local variables in previous function scopes
10592 marks them so subsequent lookups find them unset until that function
10593 returns. This is identical to the behavior of unsetting local variables
10594 at the current function scope.
10595 .TP 8
10596 .B login_shell
10597 The shell sets this option if it is started as a login shell (see
10598 .SM
10599 .B "INVOCATION"
10600 .ie \n(zZ=1 in \fIbash(1)\fP).
10601 .el above).
10602 The value may not be changed.
10603 .TP 8
10604 .B mailwarn
10605 If set, and a file that \fBbash\fP is checking for mail has been
10606 accessed since the last time it was checked, the message ``The mail in
10607 \fImailfile\fP has been read'' is displayed.
10608 .TP 8
10609 .B no_empty_cmd_completion
10610 If set, and
10611 .B readline
10612 is being used,
10613 .B bash
10614 will not attempt to search the
10615 .SM
10616 .B PATH
10617 for possible completions when
10618 completion is attempted on an empty line.
10619 .TP 8
10620 .B nocaseglob
10621 If set,
10622 .B bash
10623 matches filenames in a case\-insensitive fashion when performing pathname
10624 expansion (see
10625 .B Pathname Expansion
10626 .ie \n(zZ=1 in \fIbash(1)\fP).
10627 .el above).
10628 .TP 8
10629 .B nocasematch
10630 If set,
10631 .B bash
10632 matches patterns in a case\-insensitive fashion when performing matching
10633 while executing \fBcase\fP or \fB[[\fP conditional commands,
10634 when performing pattern substitution word expansions,
10635 or when filtering possible completions as part of programmable completion.
10636 .TP 8
10637 .B noexpand_translation
10638 If set,
10639 .B bash
10640 encloses the translated results of $"..." quoting in single quotes
10641 instead of double quotes.
10642 If the string is not translated, this has no effect.
10643 .TP 8
10644 .B nullglob
10645 If set,
10646 .B bash
10647 allows patterns which match no
10648 files (see
10649 .B Pathname Expansion
10650 .ie \n(zZ=1 in \fIbash(1)\fP)
10651 .el above)
10652 to expand to a null string, rather than themselves.
10653 .TP 8
10654 .B patsub_replacement
10655 If set, \fBbash\fP
10656 expands occurrences of \fB&\fP in the replacement string of pattern
10657 substitution to the text matched by the pattern, as described
10658 under \fBParameter Expansion\fP
10659 .ie \n(zZ=1 in \fIbash(1)\fP.
10660 .el above.
10661 This option is enabled by default.
10662 .TP 8
10663 .B progcomp
10664 If set, the programmable completion facilities (see
10665 \fBProgrammable Completion\fP
10666 .ie \n(zZ=1 in \fIbash(1)\fP)
10667 .el above)
10668 are enabled.
10669 This option is enabled by default.
10670 .TP 8
10671 .B progcomp_alias
10672 If set, and programmable completion is enabled, \fBbash\fP treats a command
10673 name that doesn't have any completions as a possible alias and attempts
10674 alias expansion. If it has an alias, \fBbash\fP attempts programmable
10675 completion using the command word resulting from the expanded alias.
10676 .TP 8
10677 .B promptvars
10678 If set, prompt strings undergo
10679 parameter expansion, command substitution, arithmetic
10680 expansion, and quote removal after being expanded as described in
10681 .SM
10682 .B PROMPTING
10683 .ie \n(zZ=1 in \fIbash(1)\fP.
10684 .el above.
10685 This option is enabled by default.
10686 .TP 8
10687 .B restricted_shell
10688 The shell sets this option if it is started in restricted mode
10689 (see
10690 .SM
10691 .B "RESTRICTED SHELL"
10692 .ie \n(zZ=1 in \fIbash(1)\fP).
10693 .el below).
10694 The value may not be changed.
10695 This is not reset when the startup files are executed, allowing
10696 the startup files to discover whether or not a shell is restricted.
10697 .TP 8
10698 .B shift_verbose
10699 If set, the
10700 .B shift
10701 builtin prints an error message when the shift count exceeds the
10702 number of positional parameters.
10703 .TP 8
10704 .B sourcepath
10705 If set, the
10706 \fB.\fP (\fBsource\fP) builtin uses the value of
10707 .SM
10708 .B PATH
10709 to find the directory containing the file supplied as an argument.
10710 This option is enabled by default.
10711 .TP 8
10712 .B varredir_close
10713 If set, the shell automatically closes file descriptors assigned using the
10714 \fI{varname}\fP redirection syntax (see
10715 .SM
10716 .B REDIRECTION
10717 .ie \n(zZ=1 in \fIbash(1)\fP)
10718 .el above)
10719 instead of leaving them open when the command completes.
10720 .TP 8
10721 .B xpg_echo
10722 If set, the \fBecho\fP builtin expands backslash-escape sequences
10723 by default.
10724 .RE
10725 .PD
10726 .TP
10727 \fBsuspend\fP [\fB\-f\fP]
10728 Suspend the execution of this shell until it receives a
10729 .SM
10730 .B SIGCONT
10731 signal. A login shell,
10732 or a shell without job control enabled,
10733 cannot be suspended; the
10734 .B \-f
10735 option can be used to override this and force the suspension.
10736 The return status is 0 unless the shell is a login shell
10737 or job control is not enabled
10738 and
10739 .B \-f
10740 is not supplied.
10741 .TP
10742 \fBtest\fP \fIexpr\fP
10743 .PD 0
10744 .TP
10745 \fB[\fP \fIexpr\fP \fB]\fP
10746 Return a status of 0 (true) or 1 (false) depending on
10747 the evaluation of the conditional expression
10748 .IR expr .
10749 Each operator and operand must be a separate argument.
10750 Expressions are composed of the primaries described
10751 .ie \n(zZ=1 in \fIbash(1)\fP
10752 .el above
10753 under
10754 .SM
10755 .BR "CONDITIONAL EXPRESSIONS" .
10756 \fBtest\fP does not accept any options, nor does it accept and ignore
10757 an argument of \fB\-\-\fP as signifying the end of options.
10758 .if t .sp 0.5
10759 .if n .sp 1
10760 Expressions may be combined using the following operators, listed
10761 in decreasing order of precedence.
10762 The evaluation depends on the number of arguments; see below.
10763 Operator precedence is used when there are five or more arguments.
10764 .RS
10765 .PD 0
10766 .TP
10767 .B ! \fIexpr\fP
10768 True if
10769 .I expr
10770 is false.
10771 .TP
10772 .B ( \fIexpr\fP )
10773 Returns the value of \fIexpr\fP.
10774 This may be used to override the normal precedence of operators.
10775 .TP
10776 \fIexpr1\fP \-\fBa\fP \fIexpr2\fP
10777 True if both
10778 .I expr1
10779 and
10780 .I expr2
10781 are true.
10782 .TP
10783 \fIexpr1\fP \-\fBo\fP \fIexpr2\fP
10784 True if either
10785 .I expr1
10786 or
10787 .I expr2
10788 is true.
10789 .PD
10790 .PP
10791 \fBtest\fP and \fB[\fP evaluate conditional
10792 expressions using a set of rules based on the number of arguments.
10793 .if t .sp 0.5
10794 .if n .sp 1
10795 .PD 0
10796 .TP
10797 0 arguments
10798 The expression is false.
10799 .TP
10800 1 argument
10801 The expression is true if and only if the argument is not null.
10802 .TP
10803 2 arguments
10804 If the first argument is \fB!\fP, the expression is true if and
10805 only if the second argument is null.
10806 If the first argument is one of the unary conditional operators listed
10807 .ie \n(zZ=1 in \fIbash(1)\fP
10808 .el above
10809 under
10810 .SM
10811 .BR "CONDITIONAL EXPRESSIONS" ,
10812 the expression is true if the unary test is true.
10813 If the first argument is not a valid unary conditional operator, the expression
10814 is false.
10815 .TP
10816 3 arguments
10817 The following conditions are applied in the order listed.
10818 If the second argument is one of the binary conditional operators listed
10819 .ie \n(zZ=1 in \fIbash(1)\fP
10820 .el above
10821 under
10822 .SM
10823 .BR "CONDITIONAL EXPRESSIONS" ,
10824 the result of the expression is the result of the binary test using
10825 the first and third arguments as operands.
10826 The \fB\-a\fP and \fB\-o\fP operators are considered binary operators
10827 when there are three arguments.
10828 If the first argument is \fB!\fP, the value is the negation of
10829 the two-argument test using the second and third arguments.
10830 If the first argument is exactly \fB(\fP and the third argument is
10831 exactly \fB)\fP, the result is the one-argument test of the second
10832 argument.
10833 Otherwise, the expression is false.
10834 .TP
10835 4 arguments
10836 The following conditions are applied in the order listed.
10837 If the first argument is \fB!\fP, the result is the negation of
10838 the three-argument expression composed of the remaining arguments.
10839 the two-argument test using the second and third arguments.
10840 If the first argument is exactly \fB(\fP and the fourth argument is
10841 exactly \fB)\fP, the result is the two-argument test of the second
10842 and third arguments.
10843 Otherwise, the expression is parsed and evaluated according to
10844 precedence using the rules listed above.
10845 .TP
10846 5 or more arguments
10847 The expression is parsed and evaluated according to precedence
10848 using the rules listed above.
10849 .if t .sp 0.5
10850 .if n .sp 1
10851 .LP
10852 When used with \fBtest\fP or \fB[\fP, the \fB<\fP and \fB>\fP operators
10853 sort lexicographically using ASCII ordering.
10854 .RE
10855 .PD
10856 .TP
10857 .B times
10858 Print the accumulated user and system times for the shell and
10859 for processes run from the shell. The return status is 0.
10860 .TP
10861 \fBtrap\fP [\fB\-lp\fP] [[\fIarg\fP] \fIsigspec\fP ...]
10862 The command
10863 .I arg
10864 is to be read and executed when the shell receives
10865 signal(s)
10866 .IR sigspec .
10867 If
10868 .I arg
10869 is absent (and there is a single \fIsigspec\fP) or
10870 .BR \- ,
10871 each specified signal is
10872 reset to its original disposition (the value it had
10873 upon entrance to the shell).
10874 If
10875 .I arg
10876 is the null string the signal specified by each
10877 .I sigspec
10878 is ignored by the shell and by the commands it invokes.
10879 If
10880 .I arg
10881 is not present and
10882 .B \-p
10883 has been supplied, then the trap commands associated with each
10884 .I sigspec
10885 are displayed.
10886 If no arguments are supplied or if only
10887 .B \-p
10888 is given,
10889 .B trap
10890 prints the list of commands associated with each signal.
10891 The
10892 .B \-l
10893 option causes the shell to print a list of signal names and
10894 their corresponding numbers.
10895 Each
10896 .I sigspec
10897 is either
10898 a signal name defined in <\fIsignal.h\fP>, or a signal number.
10899 Signal names are case insensitive and the
10900 .SM
10901 .B SIG
10902 prefix is optional.
10903 .if t .sp 0.5
10904 .if n .sp 1
10905 If a
10906 .I sigspec
10907 is
10908 .SM
10909 .B EXIT
10910 (0) the command
10911 .I arg
10912 is executed on exit from the shell.
10913 If a
10914 .I sigspec
10915 is
10916 .SM
10917 .BR DEBUG ,
10918 the command
10919 .I arg
10920 is executed before every \fIsimple command\fP, \fIfor\fP command,
10921 \fIcase\fP command, \fIselect\fP command, every arithmetic \fIfor\fP
10922 command, and before the first command executes in a shell function (see
10923 .SM
10924 .B SHELL GRAMMAR
10925 .ie \n(zZ=1 in \fIbash(1)\fP).
10926 .el above).
10927 Refer to the description of the \fBextdebug\fP option to the
10928 \fBshopt\fP builtin for details of its effect on the \fBDEBUG\fP trap.
10929 If a
10930 .I sigspec
10931 is
10932 .SM
10933 .BR RETURN ,
10934 the command
10935 .I arg
10936 is executed each time a shell function or a script executed with
10937 the \fB.\fP or \fBsource\fP builtins finishes executing.
10938 .if t .sp 0.5
10939 .if n .sp 1
10940 If a
10941 .I sigspec
10942 is
10943 .SM
10944 .BR ERR ,
10945 the command
10946 .I arg
10947 is executed whenever
10948 a pipeline (which may consist of a single simple
10949 command), a list, or a compound command returns a
10950 non\-zero exit status,
10951 subject to the following conditions.
10952 The
10953 .SM
10954 .B ERR
10955 trap is not executed if the failed
10956 command is part of the command list immediately following a
10957 .B while
10958 or
10959 .B until
10960 keyword,
10961 part of the test in an
10962 .I if
10963 statement, part of a command executed in a
10964 .B &&
10965 or
10966 .B ||
10967 list except the command following the final \fB&&\fP or \fB||\fP,
10968 any command in a pipeline but the last,
10969 or if the command's return value is
10970 being inverted using
10971 .BR ! .
10972 These are the same conditions obeyed by the \fBerrexit\fP (\fB\-e\fP) option.
10973 .if t .sp 0.5
10974 .if n .sp 1
10975 Signals ignored upon entry to the shell cannot be trapped or reset.
10976 Trapped signals that are not being ignored are reset to their original
10977 values in a subshell or subshell environment when one is created.
10978 The return status is false if any
10979 .I sigspec
10980 is invalid; otherwise
10981 .B trap
10982 returns true.
10983 .TP
10984 \fBtype\fP [\fB\-aftpP\fP] \fIname\fP [\fIname\fP ...]
10985 With no options,
10986 indicate how each
10987 .I name
10988 would be interpreted if used as a command name.
10989 If the
10990 .B \-t
10991 option is used,
10992 .B type
10993 prints a string which is one of
10994 .IR alias ,
10995 .IR keyword ,
10996 .IR function ,
10997 .IR builtin ,
10998 or
10999 .I file
11000 if
11001 .I name
11002 is an alias, shell reserved word, function, builtin, or disk file,
11003 respectively.
11004 If the
11005 .I name
11006 is not found, then nothing is printed, and an exit status of false
11007 is returned.
11008 If the
11009 .B \-p
11010 option is used,
11011 .B type
11012 either returns the name of the disk file
11013 that would be executed if
11014 .I name
11015 were specified as a command name,
11016 or nothing if
11017 .if t \f(CWtype -t name\fP
11018 .if n ``type -t name''
11019 would not return
11020 .IR file .
11021 The
11022 .B \-P
11023 option forces a
11024 .SM
11025 .B PATH
11026 search for each \fIname\fP, even if
11027 .if t \f(CWtype -t name\fP
11028 .if n ``type -t name''
11029 would not return
11030 .IR file .
11031 If a command is hashed,
11032 .B \-p
11033 and
11034 .B \-P
11035 print the hashed value, which is not necessarily the file that appears
11036 first in
11037 .SM
11038 .BR PATH .
11039 If the
11040 .B \-a
11041 option is used,
11042 .B type
11043 prints all of the places that contain
11044 an executable named
11045 .IR name .
11046 This includes aliases and functions,
11047 if and only if the
11048 .B \-p
11049 option is not also used.
11050 The table of hashed commands is not consulted
11051 when using
11052 .BR \-a .
11053 The
11054 .B \-f
11055 option suppresses shell function lookup, as with the \fBcommand\fP builtin.
11056 .B type
11057 returns true if all of the arguments are found, false if
11058 any are not found.
11059 .TP
11060 \fBulimit\fP [\fB\-HS\fP] \fB\-a\fP
11061 .PD 0
11062 .TP
11063 \fBulimit\fP [\fB\-HS\fP] [\fB\-bcdefiklmnpqrstuvxPRT\fP [\fIlimit\fP]]
11064 .PD
11065 Provides control over the resources available to the shell and to
11066 processes started by it, on systems that allow such control.
11067 The \fB\-H\fP and \fB\-S\fP options specify that the hard or soft limit is
11068 set for the given resource.
11069 A hard limit cannot be increased by a non-root user once it is set;
11070 a soft limit may be increased up to the value of the hard limit.
11071 If neither \fB\-H\fP nor \fB\-S\fP is specified, both the soft and hard
11072 limits are set.
11073 The value of
11074 .I limit
11075 can be a number in the unit specified for the resource
11076 or one of the special values
11077 .BR hard ,
11078 .BR soft ,
11079 or
11080 .BR unlimited ,
11081 which stand for the current hard limit, the current soft limit, and
11082 no limit, respectively.
11083 If
11084 .I limit
11085 is omitted, the current value of the soft limit of the resource is
11086 printed, unless the \fB\-H\fP option is given. When more than one
11087 resource is specified, the limit name and unit, if appropriate,
11088 are printed before the value.
11089 Other options are interpreted as follows:
11090 .RS
11091 .PD 0
11092 .TP
11093 .B \-a
11094 All current limits are reported; no limits are set
11095 .TP
11096 .B \-b
11097 The maximum socket buffer size
11098 .TP
11099 .B \-c
11100 The maximum size of core files created
11101 .TP
11102 .B \-d
11103 The maximum size of a process's data segment
11104 .TP
11105 .B \-e
11106 The maximum scheduling priority ("nice")
11107 .TP
11108 .B \-f
11109 The maximum size of files written by the shell and its children
11110 .TP
11111 .B \-i
11112 The maximum number of pending signals
11113 .TP
11114 .B \-k
11115 The maximum number of kqueues that may be allocated
11116 .TP
11117 .B \-l
11118 The maximum size that may be locked into memory
11119 .TP
11120 .B \-m
11121 The maximum resident set size (many systems do not honor this limit)
11122 .TP
11123 .B \-n
11124 The maximum number of open file descriptors (most systems do not
11125 allow this value to be set)
11126 .TP
11127 .B \-p
11128 The pipe size in 512-byte blocks (this may not be set)
11129 .TP
11130 .B \-q
11131 The maximum number of bytes in POSIX message queues
11132 .TP
11133 .B \-r
11134 The maximum real-time scheduling priority
11135 .TP
11136 .B \-s
11137 The maximum stack size
11138 .TP
11139 .B \-t
11140 The maximum amount of cpu time in seconds
11141 .TP
11142 .B \-u
11143 The maximum number of processes available to a single user
11144 .TP
11145 .B \-v
11146 The maximum amount of virtual memory available to the shell and, on
11147 some systems, to its children
11148 .TP
11149 .B \-x
11150 The maximum number of file locks
11151 .TP
11152 .B \-P
11153 The maximum number of pseudoterminals
11154 .TP
11155 .B \-R
11156 The maximum time a real-time process can run before blocking, in microseconds
11157 .TP
11158 .B \-T
11159 The maximum number of threads
11160 .PD
11161 .PP
11162 If
11163 .I limit
11164 is given, and the
11165 .B \-a
11166 option is not used,
11167 \fIlimit\fP is the new value of the specified resource.
11168 If no option is given, then
11169 .B \-f
11170 is assumed. Values are in 1024-byte increments, except for
11171 .BR \-t ,
11172 which is in seconds;
11173 .BR \-R ,
11174 which is in microseconds;
11175 .BR \-p ,
11176 which is in units of 512-byte blocks;
11177 .BR \-P ,
11178 .BR \-T ,
11179 .BR \-b ,
11180 .BR \-k ,
11181 .BR \-n ,
11182 and
11183 .BR \-u ,
11184 which are unscaled values;
11185 and, when in posix mode,
11186 .B \-c
11187 and
11188 .BR \-f ,
11189 which are in 512-byte increments.
11190 The return status is 0 unless an invalid option or argument is supplied,
11191 or an error occurs while setting a new limit.
11192 .RE
11193 .TP
11194 \fBumask\fP [\fB\-p\fP] [\fB\-S\fP] [\fImode\fP]
11195 The user file-creation mask is set to
11196 .IR mode .
11197 If
11198 .I mode
11199 begins with a digit, it
11200 is interpreted as an octal number; otherwise
11201 it is interpreted as a symbolic mode mask similar
11202 to that accepted by
11203 .IR chmod (1).
11204 If
11205 .I mode
11206 is omitted, the current value of the mask is printed.
11207 The
11208 .B \-S
11209 option causes the mask to be printed in symbolic form; the
11210 default output is an octal number.
11211 If the
11212 .B \-p
11213 option is supplied, and
11214 .I mode
11215 is omitted, the output is in a form that may be reused as input.
11216 The return status is 0 if the mode was successfully changed or if
11217 no \fImode\fP argument was supplied, and false otherwise.
11218 .TP
11219 \fBunalias\fP [\-\fBa\fP] [\fIname\fP ...]
11220 Remove each \fIname\fP from the list of defined aliases. If
11221 .B \-a
11222 is supplied, all alias definitions are removed. The return
11223 value is true unless a supplied
11224 .I name
11225 is not a defined alias.
11226 .TP
11227 \fBunset\fP [\-\fBfv\fP] [\-\fBn\fP] [\fIname\fP ...]
11228 For each
11229 .IR name ,
11230 remove the corresponding variable or function.
11231 If the
11232 .B \-v
11233 option is given, each
11234 .I name
11235 refers to a shell variable, and that variable is removed.
11236 Read-only variables may not be unset.
11237 If
11238 .B \-f
11239 is specified, each
11240 .I name
11241 refers to a shell function, and the function definition
11242 is removed.
11243 If the
11244 .B \-n
11245 option is supplied, and \fIname\fP is a variable with the \fInameref\fP
11246 attribute, \fIname\fP will be unset rather than the variable it
11247 references.
11248 \fB\-n\fP has no effect if the \fB\-f\fP option is supplied.
11249 If no options are supplied, each \fIname\fP refers to a variable; if
11250 there is no variable by that name, a function with that name, if any, is
11251 unset.
11252 Each unset variable or function is removed from the environment
11253 passed to subsequent commands.
11254 If any of
11255 .SM
11256 .BR BASH_ALIASES ,
11257 .SM
11258 .BR BASH_ARGV0 ,
11259 .SM
11260 .BR BASH_CMDS ,
11261 .SM
11262 .BR BASH_COMMAND ,
11263 .SM
11264 .BR BASH_SUBSHELL ,
11265 .SM
11266 .BR BASHPID ,
11267 .SM
11268 .BR COMP_WORDBREAKS ,
11269 .SM
11270 .BR DIRSTACK ,
11271 .SM
11272 .BR EPOCHREALTIME ,
11273 .SM
11274 .BR EPOCHSECONDS ,
11275 .SM
11276 .BR FUNCNAME ,
11277 .SM
11278 .BR GROUPS ,
11279 .SM
11280 .BR HISTCMD ,
11281 .SM
11282 .BR LINENO ,
11283 .SM
11284 .BR RANDOM ,
11285 .SM
11286 .BR SECONDS ,
11287 or
11288 .SM
11289 .B SRANDOM
11290 are unset, they lose their special properties, even if they are
11291 subsequently reset. The exit status is true unless a
11292 .I name
11293 is readonly or may not be unset.
11294 .TP
11295 \fBwait\fP [\fB\-fn\fP] [\fP\-p\fP \fIvarname\fP] [\fIid ...\fP]
11296 Wait for each specified child process and return its termination status.
11297 Each
11298 .I id
11299 may be a process
11300 ID or a job specification; if a job spec is given, all processes
11301 in that job's pipeline are waited for. If
11302 .I id
11303 is not given,
11304 \fBwait\fP waits for all running background jobs and
11305 the last-executed process substitution, if its process id is the same as
11306 \fB$!\fP,
11307 and the return status is zero.
11308 If the \fB\-n\fP option is supplied,
11309 \fBwait\fP waits for a single job
11310 from the list of \fIid\fPs or, if no \fIid\fPs are supplied, any job,
11311 to complete and returns its exit status.
11312 If none of the supplied arguments is a child of the shell, or if no arguments
11313 are supplied and the shell has no unwaited-for children, the exit status
11314 is 127.
11315 If the \fB\-p\fP option is supplied, the process or job identifier of the job
11316 for which the exit status is returned is assigned to the variable
11317 \fIvarname\fP named by the option argument.
11318 The variable will be unset initially, before any assignment.
11319 This is useful only when the \fB\-n\fP option is supplied.
11320 Supplying the \fB\-f\fP option, when job control is enabled,
11321 forces \fBwait\fP to wait for \fIid\fP to terminate before returning
11322 its status, instead of returning when it changes status.
11323 If
11324 .I id
11325 specifies a non-existent process or job, the return status is 127.
11326 If \fBwait\fP is interrupted by a signal, the return status will be greater
11327 than 128, as described under
11328 .B SIGNALS
11329 .ie \n(zZ=1 in \fIbash(1)\fP.
11330 .el above.
11331 Otherwise, the return status is the exit status of the last
11332 process or job waited for.
11333 .SH "SHELL COMPATIBILITY MODE"
11334 Bash-4.0 introduced the concept of a \fIshell compatibility level\fP,
11335 specified as a set of options to the shopt builtin (
11336 .BR compat31 ,
11337 .BR compat32 ,
11338 .BR compat40 ,
11339 .BR compat41 ,
11340 and so on).
11341 There is only one current
11342 compatibility level -- each option is mutually exclusive.
11343 The compatibility level is intended to allow users to select behavior
11344 from previous versions that is incompatible with newer versions
11345 while they migrate scripts to use current features and
11346 behavior. It's intended to be a temporary solution.
11347 .PP
11348 This section does not mention behavior that is standard for a particular
11349 version (e.g., setting \fBcompat32\fP means that quoting the rhs of the regexp
11350 matching operator quotes special regexp characters in the word, which is
11351 default behavior in bash-3.2 and subsequent versions).
11352 .PP
11353 If a user enables, say, \fBcompat32\fP, it may affect the behavior of other
11354 compatibility levels up to and including the current compatibility level.
11355 The idea is that each compatibility level controls behavior that changed
11356 in that version of \fBbash\fP,
11357 but that behavior may have been present in earlier versions.
11358 For instance, the change to use locale-based comparisons with the \fB[[\fP
11359 command came in bash-4.1, and earlier versions used ASCII-based comparisons,
11360 so enabling \fBcompat32\fP will enable ASCII-based comparisons as well.
11361 That granularity may not be sufficient for
11362 all uses, and as a result users should employ compatibility levels carefully.
11363 Read the documentation for a particular feature to find out the
11364 current behavior.
11365 .PP
11366 Bash-4.3 introduced a new shell variable:
11367 .SM
11368 .BR BASH_COMPAT .
11369 The value assigned
11370 to this variable (a decimal version number like 4.2, or an integer
11371 corresponding to the \fBcompat\fP\fINN\fP option, like 42) determines the
11372 compatibility level.
11373 .PP
11374 Starting with bash-4.4, Bash has begun deprecating older compatibility
11375 levels.
11376 Eventually, the options will be removed in favor of
11377 .SM
11378 .BR BASH_COMPAT .
11379 .PP
11380 Bash-5.0 is the final version for which there will be an individual shopt
11381 option for the previous version. Users should use
11382 .SM
11383 .B BASH_COMPAT
11384 on bash-5.0 and later versions.
11385 .PP
11386 The following table describes the behavior changes controlled by each
11387 compatibility level setting.
11388 The \fBcompat\fP\fINN\fP tag is used as shorthand for setting the
11389 compatibility level
11390 to \fINN\fP using one of the following mechanisms.
11391 For versions prior to bash-5.0, the compatibility level may be set using
11392 the corresponding \fBcompat\fP\fINN\fP shopt option.
11393 For bash-4.3 and later versions, the
11394 .SM
11395 .B BASH_COMPAT
11396 variable is preferred,
11397 and it is required for bash-5.1 and later versions.
11398 .TP
11399 \fBcompat31\fP
11400 .PD 0
11401 .RS
11402 .IP \(bu
11403 quoting the rhs of the \fB[[\fP command's regexp matching operator (=~)
11404 has no special effect
11405 .RE
11406 .PD
11407 .TP
11408 \fBcompat32\fP
11409 .PD 0
11410 .RS
11411 .IP \(bu
11412 interrupting a command list such as "a ; b ; c" causes the execution
11413 of the next command in the list (in bash-4.0 and later versions,
11414 the shell acts as if it received the interrupt, so
11415 interrupting one command in a list aborts the execution of the
11416 entire list)
11417 .RE
11418 .PD
11419 .TP
11420 \fBcompat40\fP
11421 .PD 0
11422 .RS
11423 .IP \(bu
11424 the \fB<\fP and \fB>\fP operators to the \fB[[\fP command do not
11425 consider the current locale when comparing strings; they use ASCII
11426 ordering.
11427 Bash versions prior to bash-4.1 use ASCII collation and
11428 .IR strcmp (3);
11429 bash-4.1 and later use the current locale's collation sequence and
11430 .IR strcoll (3).
11431 .RE
11432 .PD
11433 .TP
11434 \fBcompat41\fP
11435 .PD 0
11436 .RS
11437 .IP \(bu
11438 in \fIposix\fP mode, \fBtime\fP may be followed by options and still be
11439 recognized as a reserved word (this is POSIX interpretation 267)
11440 .IP \(bu
11441 in \fIposix\fP mode, the parser requires that an even number of single
11442 quotes occur in the \fIword\fP portion of a double-quoted
11443 parameter expansion and treats them specially, so that characters within
11444 the single quotes are considered quoted
11445 (this is POSIX interpretation 221)
11446 .RE
11447 .PD
11448 .TP
11449 \fBcompat42\fP
11450 .PD 0
11451 .RS
11452 .IP \(bu
11453 the replacement string in double-quoted pattern substitution does not
11454 undergo quote removal, as it does in versions after bash-4.2
11455 .IP \(bu
11456 in posix mode, single quotes are considered special when expanding
11457 the \fIword\fP portion of a double-quoted parameter expansion
11458 and can be used to quote a closing brace or other special character
11459 (this is part of POSIX interpretation 221);
11460 in later versions, single quotes
11461 are not special within double-quoted word expansions
11462 .RE
11463 .PD
11464 .TP
11465 \fBcompat43\fP
11466 .PD 0
11467 .RS
11468 .IP \(bu
11469 the shell does not print a warning message if an attempt is made to
11470 use a quoted compound assignment as an argument to declare
11471 (e.g., declare -a foo=\(aq(1 2)\(aq). Later versions warn that this usage is
11472 deprecated
11473 .IP \(bu
11474 word expansion errors are considered non-fatal errors that cause the
11475 current command to fail, even in posix mode
11476 (the default behavior is to make them fatal errors that cause the shell
11477 to exit)
11478 .IP \(bu
11479 when executing a shell function, the loop state (while/until/etc.)
11480 is not reset, so \fBbreak\fP or \fBcontinue\fP in that function will break
11481 or continue loops in the calling context. Bash-4.4 and later reset
11482 the loop state to prevent this
11483 .RE
11484 .PD
11485 .TP
11486 \fBcompat44\fP
11487 .PD 0
11488 .RS
11489 .IP \(bu
11490 the shell sets up the values used by
11491 .SM
11492 .B BASH_ARGV
11493 and
11494 .SM
11495 .B BASH_ARGC
11496 so they can expand to the shell's positional parameters even if extended
11497 debugging mode is not enabled
11498 .IP \(bu
11499 a subshell inherits loops from its parent context, so \fBbreak\fP
11500 or \fBcontinue\fP will cause the subshell to exit.
11501 Bash-5.0 and later reset the loop state to prevent the exit
11502 .IP \(bu
11503 variable assignments preceding builtins like \fBexport\fP and \fBreadonly\fP
11504 that set attributes continue to affect variables with the same
11505 name in the calling environment even if the shell is not in posix
11506 mode
11507 .RE
11508 .PD
11509 .TP
11510 \fBcompat50\fP
11511 .PD 0
11512 .RS
11513 .IP \(bu
11514 Bash-5.1 changed the way
11515 .SM
11516 .B $RANDOM
11517 is generated to introduce slightly
11518 more randomness. If the shell compatibility level is set to 50 or
11519 lower, it reverts to the method from bash-5.0 and previous versions,
11520 so seeding the random number generator by assigning a value to
11521 .SM
11522 .B RANDOM
11523 will produce the same sequence as in bash-5.0
11524 .IP \(bu
11525 If the command hash table is empty, bash versions prior to bash-5.1
11526 printed an informational message to that effect, even when producing
11527 output that can be reused as input. Bash-5.1 suppresses that message
11528 when the \fB\-l\fP option is supplied.
11529 .RE
11530 .PD
11531 .TP
11532 \fBcompat51\fP
11533 .PD 0
11534 .RS
11535 .IP \(bu
11536 The \fBunset\fP builtin treats attempts to unset array subscripts \fB@\fP
11537 and \fB*\fP differently depending on whether the array is indexed or
11538 associative, and differently than in previous versions.
11539 .RE
11540 .PD
11541 .\" bash_builtins
11542 .if \n(zZ=1 .ig zZ
11543 .SH "RESTRICTED SHELL"
11544 .\" rbash.1
11545 .zY
11546 .PP
11547 If
11548 .B bash
11549 is started with the name
11550 .BR rbash ,
11551 or the
11552 .B \-r
11553 option is supplied at invocation,
11554 the shell becomes restricted.
11555 A restricted shell is used to
11556 set up an environment more controlled than the standard shell.
11557 It behaves identically to
11558 .B bash
11559 with the exception that the following are disallowed or not performed:
11560 .IP \(bu
11561 changing directories with \fBcd\fP
11562 .IP \(bu
11563 setting or unsetting the values of
11564 .SM
11565 .BR SHELL ,
11566 .SM
11567 .BR PATH ,
11568 .SM
11569 .BR HISTFILE ,
11570 .SM
11571 .BR ENV ,
11572 or
11573 .SM
11574 .B BASH_ENV
11575 .IP \(bu
11576 specifying command names containing
11577 .B /
11578 .IP \(bu
11579 specifying a filename containing a
11580 .B /
11581 as an argument to the
11582 .B .
11583 builtin command
11584 .IP \(bu
11585 specifying a filename containing a slash as an argument to the
11586 .B history
11587 builtin command
11588 .IP \(bu
11589 specifying a filename containing a slash as an argument to the
11590 .B \-p
11591 option to the
11592 .B hash
11593 builtin command
11594 .IP \(bu
11595 importing function definitions from the shell environment at startup
11596 .IP \(bu
11597 parsing the value of
11598 .SM
11599 .B SHELLOPTS
11600 from the shell environment at startup
11601 .IP \(bu
11602 redirecting output using the >, >|, <>, >&, &>, and >> redirection operators
11603 .IP \(bu
11604 using the
11605 .B exec
11606 builtin command to replace the shell with another command
11607 .IP \(bu
11608 adding or deleting builtin commands with the
11609 .B \-f
11610 and
11611 .B \-d
11612 options to the
11613 .B enable
11614 builtin command
11615 .IP \(bu
11616 using the \fBenable\fP builtin command to enable disabled shell builtins
11617 .IP \(bu
11618 specifying the
11619 .B \-p
11620 option to the
11621 .B command
11622 builtin command
11623 .IP \(bu
11624 turning off restricted mode with
11625 \fBset +r\fP or \fBshopt -u restricted_shell\fP.
11626 .PP
11627 These restrictions are enforced after any startup files are read.
11628 .PP
11629 .ie \n(zY=1 When a command that is found to be a shell script is executed,
11630 .el \{ When a command that is found to be a shell script is executed
11631 (see
11632 .SM
11633 .B "COMMAND EXECUTION"
11634 above),
11635 \}
11636 .B rbash
11637 turns off any restrictions in the shell spawned to execute the
11638 script.
11639 .\" end of rbash.1
11640 .if \n(zY=1 .ig zY
11641 .SH "SEE ALSO"
11642 .PD 0
11643 .TP
11644 \fIBash Reference Manual\fP, Brian Fox and Chet Ramey
11645 .TP
11646 \fIThe Gnu Readline Library\fP, Brian Fox and Chet Ramey
11647 .TP
11648 \fIThe Gnu History Library\fP, Brian Fox and Chet Ramey
11649 .TP
11650 \fIPortable Operating System Interface (POSIX) Part 2: Shell and Utilities\fP, IEEE --
11651 http://pubs.opengroup.org/onlinepubs/9699919799/
11652 .TP
11653 http://tiswww.case.edu/~chet/bash/POSIX -- a description of posix mode
11654 .TP
11655 \fIsh\fP(1), \fIksh\fP(1), \fIcsh\fP(1)
11656 .TP
11657 \fIemacs\fP(1), \fIvi\fP(1)
11658 .TP
11659 \fIreadline\fP(3)
11660 .PD
11661 .SH FILES
11662 .PD 0
11663 .TP
11664 .FN /bin/bash
11665 The \fBbash\fP executable
11666 .TP
11667 .FN /etc/profile
11668 The systemwide initialization file, executed for login shells
11669 .TP
11670 .FN ~/.bash_profile
11671 The personal initialization file, executed for login shells
11672 .TP
11673 .FN ~/.bashrc
11674 The individual per-interactive-shell startup file
11675 .TP
11676 .FN ~/.bash_logout
11677 The individual login shell cleanup file, executed when a login shell exits
11678 .TP
11679 .FN ~/.bash_history
11680 The default value of \fBHISTFILE\fP, the file in which bash saves the
11681 command history
11682 .TP
11683 .FN ~/.inputrc
11684 Individual \fIreadline\fP initialization file
11685 .PD
11686 .SH AUTHORS
11687 Brian Fox, Free Software Foundation
11688 .br
11689 bfox@gnu.org
11690 .PP
11691 Chet Ramey, Case Western Reserve University
11692 .br
11693 chet.ramey@case.edu
11694 .SH BUG REPORTS
11695 If you find a bug in
11696 .B bash,
11697 you should report it. But first, you should
11698 make sure that it really is a bug, and that it appears in the latest
11699 version of
11700 .BR bash .
11701 The latest version is always available from
11702 \fIftp://ftp.gnu.org/pub/gnu/bash/\fP and
11703 \fIhttp://git.savannah.gnu.org/cgit/bash.git/snapshot/bash-master.tar.gz\fP.
11704 .PP
11705 Once you have determined that a bug actually exists, use the
11706 .I bashbug
11707 command to submit a bug report.
11708 If you have a fix, you are encouraged to mail that as well!
11709 Suggestions and `philosophical' bug reports may be mailed
11710 to \fIbug-bash@gnu.org\fP or posted to the Usenet
11711 newsgroup
11712 .BR gnu.bash.bug .
11713 .PP
11714 ALL bug reports should include:
11715 .PP
11716 .PD 0
11717 .TP 20
11718 The version number of \fBbash\fR
11719 .TP
11720 The hardware and operating system
11721 .TP
11722 The compiler used to compile
11723 .TP
11724 A description of the bug behaviour
11725 .TP
11726 A short script or `recipe' which exercises the bug
11727 .PD
11728 .PP
11729 .I bashbug
11730 inserts the first three items automatically into the template
11731 it provides for filing a bug report.
11732 .PP
11733 Comments and bug reports concerning
11734 this manual page should be directed to
11735 .IR chet.ramey@case.edu .
11736 .SH BUGS
11737 It's too big and too slow.
11738 .PP
11739 There are some subtle differences between
11740 .B bash
11741 and traditional versions of
11742 .BR sh ,
11743 mostly because of the
11744 .SM
11745 .B POSIX
11746 specification.
11747 .PP
11748 Aliases are confusing in some uses.
11749 .PP
11750 Shell builtin commands and functions are not stoppable/restartable.
11751 .PP
11752 Compound commands and command sequences of the form `a ; b ; c'
11753 are not handled gracefully when process suspension is attempted.
11754 When a process is stopped, the shell immediately executes the next
11755 command in the sequence.
11756 It suffices to place the sequence of commands between
11757 parentheses to force it into a subshell, which may be stopped as
11758 a unit.
11759 .PP
11760 Array variables may not (yet) be exported.
11761 .PP
11762 There may be only one active coprocess at a time.
11763 .zZ
11764 .zY