Debian Codegraph @

upstream/mageia-cauldron/man1/bash.1

raw
1 .\"
2 .\" MAN PAGE COMMENTS to
3 .\"
4 .\" Chet Ramey
5 .\" Case Western Reserve University
6 .\" [email protected]
7 .\"
8 .\" Last Change: Mon Apr 7 16:59:13 EDT 2025
9 .\"
10 .\" For bash_builtins, strip all but "SHELL BUILTIN COMMANDS" section
11 .\" For rbash, strip all but "RESTRICTED SHELL" section
12 .\"
13 .\" Both conditionalize text based on the base page being formatted
14 .\" using the zZ and zY registers, respectively
15 .\"
16 .\" Ensure the registers are initialized to avoid groff warnings.
17 .nr zZ +0
18 .nr zY +0
19 .\" Ensure the macros/strings are initialized to avoid groff warnings.
20 .ds zZ \" empty
21 .ds zY \" empty
22 .if \n(zZ=1 .ig zZ
23 .if \n(zY=1 .ig zY
24 .TH BASH 1 "2025 April 7" "GNU Bash 5.3"
25 .\"
26 .ie \n(.g \{\
27 .ds ' \(aq
28 .ds " \(dq
29 .ds ^ \(ha
30 .ds ~ \(ti
31 .\}
32 .el \{\
33 .ds ' '
34 .\" \*" is not usable in macro arguments on AT&T troff (DWB, Solaris 10)
35 .ds " ""\" two adjacent quotes and no space before this comment
36 .ds ^ ^
37 .ds ~ ~
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 .\" \% at the beginning of the string protects the filename from hyphenation.
43 .\"
44 .de FN
45 \%\fI\|\\$1\|\fP\\$2
46 ..
47 .\"
48 .\" Quotation macro: generate consistent quoted strings that don't rely
49 .\" on the presence of the `CW' constant-width font.
50 .\"
51 .de Q
52 .ie \n(.g \(lq\\$1\(rq\\$2
53 .el \{\
54 . if t ``\\$1''\\$2
55 . if n "\\$1"\\$2
56 .\}
57 ..
58 .\" Q but disallowing hyphenation of the string
59 .de QN
60 .ie \n(.g \%\(lq\\$1\(rq\\$2
61 .el \{\
62 . if t \%``\\$1''\\$2
63 . if n \%"\\$1"\\$2
64 .\}
65 ..
66 .SH NAME
67 bash \- GNU Bourne-Again SHell
68 .SH SYNOPSIS
69 .B bash
70 [options]
71 [command_string | file]
72 .SH COPYRIGHT
73 .if n Bash is Copyright (C) 1989-2025 by the Free Software Foundation, Inc.
74 .if t Bash is Copyright \(co 1989-2025 by the Free Software Foundation, Inc.
75 .SH DESCRIPTION
76 .B Bash
77 is a command language interpreter that
78 executes commands read from the standard input, from a string,
79 or from a file.
80 It is a reimplementation and extension of the Bourne shell,
81 the historical Unix command language interpreter.
82 .B Bash
83 also incorporates useful features from the \fIKorn\fP and \fIC\fP
84 shells (\fBksh\fP and \fBcsh\fP).
85 .PP
86 .SM POSIX
87 is the name for a family of computing standards based on Unix.
88 .B Bash
89 is intended to be a conformant implementation of the
90 Shell and Utilities portion of the IEEE
91 .SM POSIX
92 specification (IEEE Standard 1003.1).
93 .B Bash
94 .SM POSIX
95 mode (hereafter referred to as \fIposix mode\fP)
96 changes the shell's behavior where its default operation differs
97 from the standard to strictly conform to the standard.
98 See
99 .SM
100 .B "SEE ALSO"
101 below for a reference to a document that details how posix mode affects
102 \fBbash\fP's behavior.
103 .B Bash
104 can be configured to be
105 .SM POSIX\c
106 -conformant by default.
107 .SH OPTIONS
108 All of the single-character shell options documented in the
109 description of the \fBset\fP builtin command, including \fB\-o\fP,
110 can be used as options when the shell is invoked.
111 In addition, \fBbash\fP
112 interprets the following options when it is invoked:
113 .PP
114 .TP 10
115 .B \-c
116 If the
117 .B \-c
118 option is present, then commands are read from the first non-option argument
119 .IR command_string .
120 If there are arguments after the
121 .IR command_string ,
122 the first argument is assigned to
123 .B $0
124 and any remaining arguments are assigned to the positional parameters.
125 The assignment to
126 .B $0
127 sets the name of the shell, which is used in warning and error messages.
128 .TP
129 .B \-i
130 If the
131 .B \-i
132 option is present, the shell is
133 .IR interactive .
134 .TP
135 .B \-l
136 Make
137 .B bash
138 act as if it had been invoked as a login shell (see
139 .SM
140 .B INVOCATION
141 below).
142 .TP
143 .B \-r
144 If the
145 .B \-r
146 option is present, the shell becomes
147 .I restricted
148 (see
149 .SM
150 .B "RESTRICTED SHELL"
151 below).
152 .TP
153 .B \-s
154 If the
155 .B \-s
156 option is present, or if no arguments remain after option
157 processing, the shell reads commands from the standard input.
158 This option allows the positional parameters to be set
159 when invoking an interactive shell or when reading input
160 through a pipe.
161 .TP
162 .B \-D
163 Print a list of all double-quoted strings preceded by \fB$\fP
164 on the standard output.
165 These are the strings that
166 are subject to language translation when the current locale
167 is not \fBC\fP or \fBPOSIX\fP.
168 This implies the \fB\-n\fP option; no commands will be executed.
169 .TP
170 .B [\-+]O [\fIshopt_option\fP]
171 \fIshopt_option\fP is one of the shell options accepted by the
172 \fBshopt\fP builtin (see
173 .SM
174 .B "SHELL BUILTIN COMMANDS"
175 below).
176 If \fIshopt_option\fP is present, \fB\-O\fP sets the value of that option;
177 \fB+O\fP unsets it.
178 If \fIshopt_option\fP is not supplied, \fBbash\fP prints
179 the names and values of the shell
180 options accepted by \fBshopt\fP on the standard output.
181 If the invocation option is \fB+O\fP, the output is displayed in a format
182 that may be reused as input.
183 .TP
184 .B \-\-
185 A
186 .B \-\-
187 signals the end of options and disables further option processing.
188 Any arguments after the
189 .B \-\-
190 are treated as a shell script filename (see below)
191 and arguments passed to that script.
192 An argument of
193 .B \-
194 is equivalent to \fB\-\-\fP.
195 .PP
196 .B Bash
197 also interprets a number of multi-character options.
198 These options must appear on the command line before the
199 single-character options to be recognized.
200 .PP
201 .TP
202 .B \-\-debugger
203 Arrange for the debugger profile to be executed before the shell
204 starts.
205 Turns on extended debugging mode (see the description of the
206 .B extdebug
207 option to the
208 .B shopt
209 builtin below).
210 .TP
211 .B \-\-dump\-po\-strings
212 Equivalent to \fB\-D\fP, but the output is in the GNU \fIgettext\fP
213 .Q po
214 (portable object) file format.
215 .TP
216 .B \-\-dump\-strings
217 Equivalent to \fB\-D\fP.
218 .TP
219 .B \-\-help
220 Display a usage message on standard output and exit successfully.
221 .TP
222 .PD 0
223 \fB\-\-init\-file\fP \fIfile\fP
224 .TP
225 \fB\-\-rcfile\fP \fIfile\fP
226 .PD
227 Execute commands from
228 .I file
229 instead of the standard personal initialization file
230 .FN \*~/.bashrc
231 if the shell is interactive (see
232 .SM
233 .B INVOCATION
234 below).
235 .TP
236 .B \-\-login
237 Equivalent to \fB\-l\fP.
238 .TP
239 .B \-\-noediting
240 Do not use the GNU
241 .B readline
242 library to read command lines when the shell is interactive.
243 .TP
244 .B \-\-noprofile
245 Do not read either the system-wide startup file
246 .FN /etc/profile
247 or any of the personal initialization files
248 .FN \*~/.bash_profile ,
249 .FN \*~/.bash_login ,
250 or
251 .FN \*~/.profile .
252 By default,
253 .B bash
254 reads these files when it is invoked as a login shell (see
255 .SM
256 .B INVOCATION
257 below).
258 .TP
259 .B \-\-norc
260 Do not read and execute the personal initialization file
261 .FN \*~/.bashrc
262 if the shell is interactive.
263 This option is on by default if the shell is invoked as
264 .BR sh .
265 .TP
266 .B \-\-posix
267 Enable posix mode;
268 change the behavior of \fBbash\fP
269 where the default operation differs from the
270 .SM POSIX
271 standard to match the standard.
272 .TP
273 .B \-\-restricted
274 The shell becomes restricted (see
275 .SM
276 .B "RESTRICTED SHELL"
277 below).
278 .TP
279 .B \-\-verbose
280 Equivalent to \fB\-v\fP.
281 .TP
282 .B \-\-version
283 Show version information for this instance of
284 .B bash
285 on the standard output and exit successfully.
286 .SH ARGUMENTS
287 If arguments remain after option processing, and neither the
288 .B \-c
289 nor the
290 .B \-s
291 option has been supplied, the first argument is treated as
292 the name of a file containing shell commands (a \fIshell script\fP).
293 When
294 .B bash
295 is invoked in this fashion,
296 .B $0
297 is set to the name of the file, and the positional parameters
298 are set to the remaining arguments.
299 .B Bash
300 reads and executes commands from this file, then exits.
301 \fBBash\fP's exit status is the exit status of the last command
302 executed in the script.
303 If no commands are executed, the exit status is 0.
304 .B Bash
305 first attempts to open the file in the current directory,
306 and, if no file is found, searches the directories in
307 .SM
308 .B PATH
309 for the script.
310 .SH INVOCATION
311 A \fIlogin shell\fP is one whose first character of argument zero is a
312 .BR \- ,
313 or one started with the
314 .B \-\-login
315 option.
316 .PP
317 An \fIinteractive shell\fP is one started without non-option arguments
318 (unless \fB\-s\fP is specified)
319 and without the
320 .B \-c
321 option,
322 and whose standard input and standard error are
323 both connected to terminals (as determined by
324 .IR isatty (3)),
325 or one started with the
326 .B \-i
327 option.
328 .B Bash
329 sets
330 .SM
331 .B PS1
332 and
333 .B $\-
334 includes
335 .B i
336 if the shell is interactive,
337 so a shell script or a startup file can test this state.
338 .PP
339 The following paragraphs describe how
340 .B bash
341 executes its startup files.
342 If any of the files exist but cannot be read,
343 .B bash
344 reports an error.
345 Tildes are expanded in filenames as described below under
346 .B "Tilde Expansion"
347 in the
348 .SM
349 .B EXPANSION
350 section.
351 .PP
352 When
353 .B bash
354 is invoked as an interactive login shell, or as a non-interactive shell
355 with the \fB\-\-login\fP option, it first reads and
356 executes commands from the file
357 .FN /etc/profile ,
358 if that file exists.
359 After reading that file, it looks for
360 .FN \*~/.bash_profile ,
361 .FN \*~/.bash_login ,
362 and
363 .FN \*~/.profile ,
364 in that order, and reads
365 and executes commands from the first one that exists and is readable.
366 The
367 .B \-\-noprofile
368 option may be used when the shell is started to inhibit this behavior.
369 .PP
370 When an interactive login shell exits,
371 or a non-interactive login shell executes the \fBexit\fP builtin command,
372 .B bash
373 reads and executes commands from the file
374 .FN \*~/.bash_logout ,
375 if it exists.
376 .PP
377 When an interactive shell that is not a login shell is started,
378 .B bash
379 reads and executes commands from
380 .FN \*~/.bashrc ,
381 if that file exists.
382 The
383 .B \-\-norc
384 option inhibits this behavior.
385 The \fB\-\-rcfile\fP \fIfile\fP option causes
386 .B bash
387 to use \fIfile\fP instead of
388 .FN \*~/.bashrc .
389 .PP
390 When
391 .B bash
392 is started non-interactively, to run a shell script, for example, it
393 looks for the variable
394 .SM
395 .B BASH_ENV
396 in the environment, expands its value if it appears there, and uses the
397 expanded value as the name of a file to read and execute.
398 .B Bash
399 behaves as if the following command were executed:
400 .PP
401 .RS
402 .EX
403 if [ \-n \*"$BASH_ENV\*" ]; then . \*"$BASH_ENV\*"; fi
404 .EE
405 .RE
406 .PP
407 but does not use the value of the
408 .SM
409 .B PATH
410 variable to search for the filename.
411 .PP
412 If
413 .B bash
414 is invoked with the name
415 .BR sh ,
416 it tries to mimic the startup behavior of historical versions of
417 .B sh
418 as closely as possible,
419 while conforming to the
420 .SM POSIX
421 standard as well.
422 When invoked as an interactive login shell, or a non-interactive
423 shell with the \fB\-\-login\fP option, it first attempts to read
424 and execute commands from
425 .FN /etc/profile
426 and
427 .FN \*~/.profile ,
428 in that order.
429 The
430 .B \-\-noprofile
431 option inhibits this behavior.
432 When invoked as an interactive shell with the name
433 .BR sh ,
434 .B bash
435 looks for the variable
436 .SM
437 .BR ENV ,
438 expands its value if it is defined, and uses the
439 expanded value as the name of a file to read and execute.
440 Since a shell invoked as
441 .B sh
442 does not attempt to read and execute commands from any other startup
443 files, the
444 .B \-\-rcfile
445 option has no effect.
446 A non-interactive shell invoked with the name
447 .B sh
448 does not attempt to read any other startup files.
449 .PP
450 When invoked as
451 .BR sh ,
452 .B bash
453 enters posix mode after reading the startup files.
454 .PP
455 When
456 .B bash
457 is started in posix mode, as with the
458 .B \-\-posix
459 command line option, it follows the
460 .SM POSIX
461 standard for startup files.
462 In this mode, interactive shells expand the
463 .SM
464 .B ENV
465 variable and read and execute commands from the file
466 whose name is the expanded value.
467 No other startup files are read.
468 .PP
469 .B Bash
470 attempts to determine when it is being run with its standard input
471 connected to a network connection, as when executed by
472 the historical and rarely-seen remote shell daemon, usually \fIrshd\fP,
473 or the secure shell daemon \fIsshd\fP.
474 If
475 .B bash
476 determines it is being run non-interactively in this fashion,
477 it reads and executes commands from
478 .FN \*~/.bashrc ,
479 if that file exists and is readable.
480 .B Bash
481 does not read this file if invoked as \fBsh\fP.
482 The
483 .B \-\-norc
484 option inhibits this behavior, and the
485 .B \-\-rcfile
486 option makes \fBbash\fP use a different file instead of
487 .FN \*~/.bashrc ,
488 but neither
489 \fIrshd\fP nor \fIsshd\fP generally invoke the shell with those options
490 or allow them to be specified.
491 .PP
492 If the shell is started with the effective user (group) id not equal to the
493 real user (group) id, and the \fB\-p\fP option is not supplied, no startup
494 files are read, shell functions are not inherited from the environment, the
495 .SM
496 .BR SHELLOPTS ,
497 .SM
498 .BR BASHOPTS ,
499 .SM
500 .BR CDPATH ,
501 and
502 .SM
503 .B GLOBIGNORE
504 variables, if they appear in the environment, are ignored,
505 and the effective user id is set to the real user id.
506 If the \fB\-p\fP option is supplied at invocation, the startup behavior is
507 the same, but the effective user id is not reset.
508 .SH DEFINITIONS
509 The following definitions are used throughout the rest of this
510 document.
511 .PD 0
512 .TP
513 .B blank
514 A space or tab.
515 .TP
516 .B whitespace
517 A character belonging to the \fBspace\fP character class in the
518 current locale, or for which \fIisspace\fP(3) returns true.
519 .TP
520 .B word
521 A sequence of characters considered as a single unit by the shell.
522 Also known as a
523 .BR token .
524 .TP
525 .B name
526 A
527 .I word
528 consisting only of alphanumeric characters and underscores, and
529 beginning with an alphabetic character or an underscore. Also
530 referred to as an
531 .BR identifier .
532 .TP
533 .B metacharacter
534 A character that, when unquoted, separates words.
535 One of the following:
536 .br
537 .RS
538 .PP
539 .if t \fB| & ; ( ) < > space tab newline\fP
540 .if n \fB| & ; ( ) < > space tab newline\fP
541 .RE
542 .TP
543 .B "control operator"
544 A \fItoken\fP that performs a control function.
545 It is one of the following symbols:
546 .RS
547 .PP
548 .if t \fB|| & && ; ;; ;& ;;& ( ) | |& <newline>\fP
549 .if n \fB|| & && ; ;; ;& ;;& ( ) | |& <newline>\fP
550 .RE
551 .PD
552 .SH "RESERVED WORDS"
553 \fIReserved words\fP are words that have a special meaning to the shell.
554 The following words are recognized as reserved when unquoted and either
555 the first word of a command (see
556 .SM
557 .B "SHELL GRAMMAR"
558 below), the third word of a
559 .B case
560 or
561 .B select
562 command
563 (only \fBin\fP is valid), or the third word of a
564 .B for
565 command (only \fBin\fP and \fBdo\fP are valid):
566 .if t .RS
567 .PP
568 .B
569 .if n ! case coproc do done elif else esac fi for function if in select \
570 then until while { } time [[ ]]
571 .if t ! case coproc do done elif else esac fi for function if in select then until while { } time [[ ]]
572 .if t .RE
573 .SH "SHELL GRAMMAR"
574 This section describes the syntax of the various forms of shell commands.
575 .SS Simple Commands
576 A \fIsimple command\fP is a sequence of optional variable assignments
577 followed by \fBblank\fP-separated words and redirections, and
578 terminated by a \fIcontrol operator\fP.
579 The first word
580 specifies the command to be executed, and is passed as argument zero.
581 The remaining words are passed as arguments to the invoked command.
582 .PP
583 The return value of a \fIsimple command\fP is its exit status, or
584 128+\fIn\^\fP if the command is terminated by signal
585 .IR n .
586 .SS Pipelines
587 A \fIpipeline\fP is a sequence of one or more commands separated by
588 one of the control operators
589 .B |
590 or \fB|&\fP.
591 The format for a pipeline is:
592 .RS
593 .PP
594 [\fBtime\fP [\fB\-p\fP]] [ ! ] \fIcommand1\fP [ [\fB|\fP\(bv\fB|&\fP] \fIcommand2\fP .\|.\|.\& ]
595 .RE
596 .PP
597 The standard output of
598 .I command1
599 is connected via a pipe to the standard input of
600 .IR command2 .
601 This connection is performed before any redirections specified by the
602 .IR command1 (see
603 .SM
604 .B REDIRECTION
605 below).
606 If \fB|&\fP is the pipeline operator,
607 \fIcommand1\fP's standard error, in addition to its
608 standard output, is connected to
609 \fIcommand2\fP's standard input through the pipe;
610 it is shorthand for \fB2>&1 |\fP.
611 This implicit redirection of the standard error to the standard output is
612 performed after any redirections specified by \fIcommand1\fP.
613 .PP
614 The return status of a pipeline is the exit status of the last
615 command, unless the \fBpipefail\fP option is enabled.
616 If \fBpipefail\fP is enabled, the pipeline's return status is the
617 value of the last (rightmost) command to exit with a non-zero status,
618 or zero if all commands exit successfully.
619 If the reserved word
620 .B !
621 precedes a pipeline, the exit status of that pipeline is the logical
622 negation of the exit status as described above.
623 If a pipeline is executed synchronously,
624 the shell waits for all commands in the pipeline to
625 terminate before returning a value.
626 .PP
627 If the
628 .B time
629 reserved word precedes a pipeline, the shell reports the
630 elapsed as well as user and system time consumed by its execution
631 when the pipeline terminates.
632 The \fB\-p\fP option changes the output format to that specified by
633 .SM POSIX\c
634 \&.
635 When the shell is in posix mode, it does not recognize
636 \fBtime\fP as a reserved word if the next token begins with a
637 .Q \- .
638 The value of the
639 .SM
640 .B TIMEFORMAT
641 variable is a format string that specifies how the timing
642 information should be displayed; see the description of
643 .SM
644 .B TIMEFORMAT
645 below under
646 .BR "Shell Variables" .
647 .PP
648 When the shell is in posix mode, \fBtime\fP
649 may appear by itself as the only word in a simple command.
650 In this case, the shell displays the
651 total user and system time consumed by the shell and its children.
652 The
653 .SM
654 .B TIMEFORMAT
655 variable specifies the format of the time information.
656 .PP
657 Each command in a multi-command pipeline,
658 where pipes are created,
659 is executed in a \fIsubshell\fP, which is a
660 separate process.
661 See
662 .SM
663 .B "COMMAND EXECUTION ENVIRONMENT"
664 for a description of subshells and a subshell environment.
665 If the \fBlastpipe\fP option is enabled using the \fBshopt\fP builtin
666 (see the description of \fBshopt\fP below),
667 and job control is not active,
668 the last element of a pipeline may be run by the shell process.
669 .SS Lists
670 A \fIlist\fP is a sequence of one or more pipelines separated by one
671 of the operators
672 .BR ; ,
673 .BR & ,
674 .BR && ,
675 or
676 .BR || ,
677 and optionally terminated by one of
678 .BR ; ,
679 .BR & ,
680 or
681 .BR <newline> .
682 .PP
683 Of these list operators,
684 .B &&
685 and
686 .B ||
687 have equal precedence, followed by
688 .B ;
689 and
690 .BR & ,
691 which have equal precedence.
692 .PP
693 A sequence of one or more newlines may appear in a \fIlist\fP instead
694 of a semicolon to delimit commands.
695 .PP
696 If a command is terminated by the control operator
697 .BR & ,
698 the shell executes the command in the \fIbackground\fP
699 in a subshell.
700 The shell does not wait for the command to
701 finish, and the return status is 0.
702 These are referred to as \fIasynchronous\fP commands.
703 Commands separated by a
704 .B ;
705 are executed sequentially; the shell waits for each
706 command to terminate in turn.
707 The return status is the exit status of the last command executed.
708 .PP
709 AND and OR lists are sequences of one or more pipelines separated by the
710 \fB&&\fP and \fB||\fP control operators, respectively.
711 AND and OR lists are executed with left associativity.
712 An AND list has the form
713 .RS
714 .PP
715 \fIcommand1\fP \fB&&\fP \fIcommand2\fP
716 .RE
717 .PP
718 .I command2
719 is executed if, and only if,
720 .I command1
721 returns an exit status of zero (success).
722 .PP
723 An OR list has the form
724 .RS
725 .PP
726 \fIcommand1\fP \fB||\fP \fIcommand2\fP
727 .RE
728 .PP
729 .I command2
730 is executed if, and only if,
731 .I command1
732 returns a non-zero exit status.
733 The return status of
734 AND and OR lists is the exit status of the last command
735 executed in the list.
736 .SS Compound Commands
737 A \fIcompound command\fP is one of the following.
738 In most cases a \fIlist\fP in a command's description may be separated from
739 the rest of the command by one or more newlines, and may be followed by a
740 newline in place of a semicolon.
741 .TP
742 (\fIlist\fP)
743 \fIlist\fP is executed in a subshell (see
744 .SM
745 .B "COMMAND EXECUTION ENVIRONMENT"
746 below for a description of a subshell environment).
747 Variable assignments and builtin
748 commands that affect the shell's environment do not remain in effect
749 after the command completes.
750 The return status is the exit status of \fIlist\fP.
751 .TP
752 { \fIlist\fP; }
753 \fIlist\fP is executed in the current shell environment.
754 \fIlist\fP must be terminated with a newline or semicolon.
755 This is known as a \fIgroup command\fP.
756 The return status is the exit status of \fIlist\fP.
757 .IP
758 Note that unlike the metacharacters \fB(\fP and \fB)\fP, \fB{\fP and
759 \fB}\fP are \fIreserved words\fP and must occur where a reserved
760 word is permitted to be recognized.
761 Since they do not cause a word break, they must be separated from
762 \fIlist\fP by whitespace or another shell metacharacter.
763 .TP
764 ((\fIexpression\fP))
765 The arithmetic \fIexpression\fP is evaluated according to the rules
766 described below under
767 .SM
768 .BR "ARITHMETIC EVALUATION" .
769 If the value of the expression is non-zero, the return status is 0;
770 otherwise the return status is 1.
771 The \fIexpression\fP
772 undergoes the same expansions
773 as if it were within double quotes,
774 but unescaped double quote characters
775 in \fIexpression\fP are not treated
776 specially and are removed.
777 Since this can potentially result in empty strings, this command treats
778 those as expressions that evaluate to 0.
779 .TP
780 \fB[[\fP \fIexpression\fP \fB]]\fP
781 .PD
782 Evaluate the conditional expression \fIexpression\fP
783 and return a status of zero (true) or non-zero (false).
784 Expressions are composed of the primaries described below under
785 .SM
786 .BR "CONDITIONAL EXPRESSIONS" .
787 The words between the \fB[[\fP and \fB]]\fP do not undergo word splitting
788 and pathname expansion.
789 The shell performs tilde expansion, parameter and
790 variable expansion, arithmetic expansion, command substitution, process
791 substitution, and quote removal on those words.
792 Conditional operators such as \fB\-f\fP must be unquoted to be recognized
793 as primaries.
794 .IP
795 When used with \fB[[\fP, the \fB<\fP and \fB>\fP operators sort
796 lexicographically using the current locale.
797 .IP
798 When the \fB==\fP and \fB!=\fP operators are used, the string to the
799 right of the operator is considered a pattern and matched according
800 to the rules described below under \fBPattern Matching\fP,
801 as if the \fBextglob\fP shell option were enabled.
802 The \fB=\fP operator is equivalent to \fB==\fP.
803 If the
804 .B nocasematch
805 shell option is enabled, the match is performed without regard to the case
806 of alphabetic characters.
807 The return value is 0 if the string matches (\fB==\fP) or does not match
808 (\fB!=\fP) the pattern, and 1 otherwise.
809 If any part of the pattern is quoted, the quoted portion is matched
810 as a string: every character in the quoted portion matches itself,
811 instead of having any special pattern matching meaning.
812 .IP
813 An additional binary operator, \fB=\*~\fP, is available, with the same
814 precedence as \fB==\fP and \fB!=\fP.
815 When it is used, the string to the right of the operator is considered
816 a
817 .SM POSIX
818 extended regular expression and matched accordingly
819 (using the
820 .SM POSIX
821 \fIregcomp\fP and \fIregexec\fP interfaces
822 usually described in
823 .IR regex (3)).
824 The return value is 0 if the string matches
825 the pattern, and 1 otherwise.
826 If the regular expression is syntactically incorrect, the conditional
827 expression's return value is 2.
828 If the
829 .B nocasematch
830 shell option is enabled, the match is performed without regard to the case
831 of alphabetic characters.
832 .IP
833 If any part of the pattern is quoted, the quoted portion is matched literally,
834 as above.
835 If the pattern is stored in a shell variable, quoting the variable
836 expansion forces the entire pattern to be matched literally.
837 Treat bracket expressions in regular expressions carefully,
838 since normal quoting and pattern characters lose their meanings
839 between brackets.
840 .IP
841 The match succeeds if the pattern matches any part of the string.
842 Anchor the pattern using the \fB\*^\fP and \fB$\fP regular expression
843 operators to force it to match the entire string.
844 .IP
845 The array variable
846 .SM
847 .B BASH_REMATCH
848 records which parts of the string matched the pattern.
849 The element of
850 .SM
851 .B BASH_REMATCH
852 with index 0 contains the portion of
853 the string matching the entire regular expression.
854 Substrings matched by parenthesized subexpressions within the regular
855 expression are saved in the remaining
856 .SM
857 .B BASH_REMATCH
858 indices.
859 The element of
860 .SM
861 .B BASH_REMATCH
862 with index \fIn\fP is the portion of the
863 string matching the \fIn\fPth parenthesized subexpression.
864 \fBBash\fP sets
865 .SM
866 .B BASH_REMATCH
867 in the global scope; declaring it as a local variable will lead to
868 unexpected results.
869 .IP
870 Expressions may be combined using the following operators, listed
871 in decreasing order of precedence:
872 .IP
873 .RS
874 .PD 0
875 .TP
876 .B ( \fIexpression\fP )
877 Returns the value of \fIexpression\fP.
878 This may be used to override the normal precedence of operators.
879 .TP
880 .B ! \fIexpression\fP
881 True if
882 .I expression
883 is false.
884 .TP
885 \fIexpression1\fP \fB&&\fP \fIexpression2\fP
886 True if both
887 .I expression1
888 and
889 .I expression2
890 are true.
891 .TP
892 \fIexpression1\fP \fB||\fP \fIexpression2\fP
893 True if either
894 .I expression1
895 or
896 .I expression2
897 is true.
898 .PD
899 .LP
900 The \fB&&\fP and \fB||\fP
901 operators do not evaluate \fIexpression2\fP if the value of
902 \fIexpression1\fP is sufficient to determine the return value of
903 the entire conditional expression.
904 .RE
905 .TP
906 \fBfor\fP \fIname\fP [ [ \fBin\fP \fIword .\|.\|.\&\fP ] ; ] \fBdo\fP \fIlist\fP ; \fBdone\fP
907 First, expand The list of words following \fBin\fP, generating a list
908 of items.
909 Then, the variable \fIname\fP is set to each element of this list
910 in turn, and \fIlist\fP is executed each time.
911 If the \fBin\fP \fIword\fP is omitted, the \fBfor\fP command executes
912 \fIlist\fP once for each positional parameter that is set (see
913 .SM
914 .B PARAMETERS
915 below).
916 The return status is the exit status of the last command that executes.
917 If the expansion of the items following \fBin\fP results in an empty
918 list, no commands are executed, and the return status is 0.
919 .TP
920 \fBfor\fP (( \fIexpr1\fP ; \fIexpr2\fP ; \fIexpr3\fP )) [;] \fBdo\fP \fIlist\fP ; \fBdone\fP
921 First, evaluate the arithmetic expression \fIexpr1\fP according
922 to the rules described below under
923 .SM
924 .BR "ARITHMETIC EVALUATION" .
925 Then, repeatedly evaluate the arithmetic expression \fIexpr2\fP
926 until it evaluates to zero.
927 Each time \fIexpr2\fP evaluates to a non-zero value,
928 execute \fIlist\fP
929 and evaluate the arithmetic expression \fIexpr3\fP.
930 If any expression is omitted, it behaves as if it evaluates to 1.
931 The return value is the exit status of the last command in \fIlist\fP
932 that is executed, or non-zero if any of the expressions is invalid.
933 .IP
934 Use the \fBbreak\fP and \fPcontinue\fP builtins
935 (see
936 .SM
937 .B "SHELL BUILTIN COMMANDS"
938 below)
939 to control loop execution.
940 .TP
941 \fBselect\fP \fIname\fP [ \fBin\fP \fIword\fP ] ; \fBdo\fP \fIlist\fP ; \fBdone\fP
942 First, expand the list of words following \fBin\fP,
943 generating a list of items, and print the set of expanded words
944 the standard error, each preceded by a number.
945 If the \fBin\fP
946 \fIword\fP is omitted, print the positional parameters (see
947 .SM
948 .B PARAMETERS
949 below).
950 .B select
951 then displays the
952 .SM
953 .B PS3
954 prompt and reads a line from the standard input.
955 If the line consists of a number corresponding to one of
956 the displayed words, then \fBselect\fP sets the value of
957 .I name
958 to that word.
959 If the line is empty, \fBselect\fP displays the words and prompt again.
960 If EOF is read, \fBselect\fP completes and returns 1.
961 Any other value sets
962 .I name
963 to null.
964 The line read is saved in the variable
965 .SM
966 .BR REPLY .
967 The
968 .I list
969 is executed after each selection until a
970 .B break
971 command is executed.
972 The exit status of
973 .B select
974 is the exit status of the last command executed in
975 .IR list ,
976 or zero if no commands were executed.
977 .TP
978 \fBcase\fP \fIword\fP \fBin\fP [ [(] \fIpattern\fP [ \fB|\fP \fIpattern\fP ] \
979 .\|.\|.\& ) \fIlist\fP ;; ] .\|.\|.\& \
980 \fBesac\fP
981 A \fBcase\fP command first expands \fIword\fP, and tries to match
982 it against each \fIpattern\fP in turn,
983 proceeding from first to last,
984 using the matching rules
985 described under
986 .B "Pattern Matching"
987 below.
988 A pattern list is a set of one or more patterns separated by \|,
989 and the ) operator terminates the pattern list.
990 The \fIword\fP is expanded using tilde
991 expansion, parameter and variable expansion, arithmetic expansion,
992 command substitution, process substitution and quote removal.
993 Each \fIpattern\fP examined is expanded using tilde
994 expansion, parameter and variable expansion, arithmetic expansion,
995 command substitution, process substitution, and quote removal.
996 If the
997 .B nocasematch
998 shell option is enabled, the match is performed without regard to the case
999 of alphabetic characters.
1000 A \fIclause\fP is a pattern list and an associated \fIlist\fP.
1001 .IP
1002 When a match is found, \fBcase\fP executes the corresponding \fIlist\fP.
1003 If the \fB;;\fP operator terminates the case clause, the \fBcase\fP
1004 command completes after the first match.
1005 Using \fB;&\fP in place of \fB;;\fP causes execution to continue with
1006 the \fIlist\fP associated with the next pattern list.
1007 Using \fB;;&\fP in place of \fB;;\fP causes the shell to test the next
1008 pattern list in the statement, if any, and execute any associated \fIlist\fP
1009 if the match succeeds,
1010 continuing the case statement execution as if the pattern list had not matched.
1011 The exit status is zero if no pattern matches.
1012 .IP
1013 Otherwise, it is the exit status of the
1014 last command executed in the last \fIlist\fP executed.
1015 .TP
1016 \fBif\fP \fIlist\fP; \fBthen\fP \fIlist\fP; \
1017 [ \fBelif\fP \fIlist\fP; \fBthen\fP \fIlist\fP; ] .\|.\|.\& \
1018 [ \fBelse\fP \fIlist\fP; ] \fBfi\fP
1019 The
1020 .B if
1021 .I list
1022 is executed.
1023 If its exit status is zero, the
1024 \fBthen\fP \fIlist\fP is executed.
1025 Otherwise, each \fBelif\fP \fIlist\fP is executed in turn,
1026 and if its exit status is zero, the corresponding \fBthen\fP \fIlist\fP
1027 is executed and the command completes.
1028 Otherwise, the \fBelse\fP \fIlist\fP is executed, if present.
1029 The exit status is the exit status of the
1030 last command executed, or zero if no condition tested true.
1031 .TP
1032 \fBwhile\fP \fIlist-1\fP; \fBdo\fP \fIlist-2\fP; \fBdone\fP
1033 .PD 0
1034 .TP
1035 \fBuntil\fP \fIlist-1\fP; \fBdo\fP \fIlist-2\fP; \fBdone\fP
1036 .PD
1037 The \fBwhile\fP command continuously executes the list
1038 \fIlist-2\fP as long as the last command in the list \fIlist-1\fP returns
1039 an exit status of zero.
1040 The \fBuntil\fP command is identical
1041 to the \fBwhile\fP command, except that the test is negated:
1042 .I list-2
1043 is executed as long as the last command in
1044 .I list-1
1045 returns a non-zero exit status.
1046 The exit status of the \fBwhile\fP and \fBuntil\fP commands
1047 is the exit status
1048 of the last command executed in \fIlist-2\fP, or zero if
1049 none was executed.
1050 .SS Coprocesses
1051 A \fIcoprocess\fP is a shell command preceded by the \fBcoproc\fP reserved
1052 word.
1053 A coprocess is executed asynchronously in a subshell, as if the command
1054 had been terminated with the \fB&\fP control operator, with a two-way pipe
1055 established between the executing shell and the coprocess.
1056 .PP
1057 The syntax for a coprocess is:
1058 .RS
1059 .PP
1060 \fBcoproc\fP [\fINAME\fP] \fIcommand\fP [\fIredirections\fP]
1061 .RE
1062 .PP
1063 This creates a coprocess named \fINAME\fP.
1064 \fIcommand\fP may be either a simple command or a compound
1065 command (see above).
1066 \fINAME\fP is a shell variable name.
1067 If \fINAME\fP is not supplied, the default name is \fBCOPROC\fP.
1068 .PP
1069 The recommended form to use for a coprocess is
1070 .RS
1071 .PP
1072 \fBcoproc\fP \fINAME\fP { \fIcommand\fP [\fIredirections\fP]; }
1073 .RE
1074 .PP
1075 This form is preferred because simple commands result in the coprocess
1076 always being named \fBCOPROC\fP, and it is simpler to use and more complete
1077 than the other compound commands.
1078 .PP
1079 If \fIcommand\fP is a compound command, \fINAME\fP is optional. The
1080 word following \fBcoproc\fP determines whether that word is interpreted
1081 as a variable name: it is interpreted as \fINAME\fP if it is not a
1082 reserved word that introduces a compound command.
1083 If \fIcommand\fP is a simple command, \fINAME\fP is not allowed; this
1084 is to avoid confusion between \fINAME\fP and the first word of the simple
1085 command.
1086 .PP
1087 When the coprocess is executed, the shell creates an array variable (see
1088 .B Arrays
1089 below) named \fINAME\fP in the context of the executing shell.
1090 The standard output of
1091 .I command
1092 is connected via a pipe to a file descriptor in the executing shell,
1093 and that file descriptor is assigned to \fINAME\fP[0].
1094 The standard input of
1095 .I command
1096 is connected via a pipe to a file descriptor in the executing shell,
1097 and that file descriptor is assigned to \fINAME\fP[1].
1098 This pipe is established before any redirections specified by the
1099 command (see
1100 .SM
1101 .B REDIRECTION
1102 below).
1103 The file descriptors can be utilized as arguments to shell commands
1104 and redirections using standard word expansions.
1105 Other than those created to execute command and process substitutions,
1106 the file descriptors are not available in subshells.
1107 .PP
1108 The process ID of the shell spawned to execute the coprocess is
1109 available as the value of the variable \fINAME\fP_PID.
1110 The \fBwait\fP
1111 builtin may be used to wait for the coprocess to terminate.
1112 .PP
1113 Since the coprocess is created as an asynchronous command,
1114 the \fBcoproc\fP command always returns success.
1115 The return status of a coprocess is the exit status of \fIcommand\fP.
1116 .SS Shell Function Definitions
1117 A shell function is an object that is called like a simple command and
1118 executes a compound command with a new set of positional parameters.
1119 Shell functions are declared as follows:
1120 .TP
1121 \fIfname\fP () \fIcompound\-command\fP [\fIredirection\fP]
1122 .PD 0
1123 .TP
1124 \fBfunction\fP \fIfname\fP [()] \fIcompound\-command\fP [\fIredirection\fP]
1125 .PD
1126 This defines a function named \fIfname\fP.
1127 The reserved word \fBfunction\fP is optional.
1128 If the \fBfunction\fP reserved word is supplied, the parentheses are optional.
1129 The \fIbody\fP of the function is the compound command
1130 .I compound\-command
1131 (see \fBCompound Commands\fP above).
1132 That command is usually a \fIlist\fP of commands between { and }, but
1133 may be any command listed under \fBCompound Commands\fP above.
1134 If the \fBfunction\fP reserved word is used, but the
1135 parentheses are not supplied, the braces are recommended.
1136 \fIcompound\-command\fP is executed whenever \fIfname\fP is specified as the
1137 name of a simple command.
1138 When in posix mode, \fIfname\fP must be a valid shell \fIname\fP
1139 and may not be the name of one of the
1140 .SM POSIX
1141 \fIspecial builtins\fP.
1142 In default mode, a function name can be any unquoted shell word that does
1143 not contain \fB$\fP.
1144 .PP
1145 Any redirections (see
1146 .SM
1147 .B REDIRECTION
1148 below) specified when a function is defined are performed
1149 when the function is executed.
1150 .PP
1151 The exit status of a function definition is zero unless a syntax error
1152 occurs or a readonly function with the same name already exists.
1153 When executed, the exit status of a function is the exit status of the
1154 last command executed in the body. (See
1155 .SM
1156 .B FUNCTIONS
1157 below.)
1158 .SH COMMENTS
1159 In a non-interactive shell, or an interactive shell in which the
1160 .B interactive_comments
1161 option to the
1162 .B shopt
1163 builtin is enabled (see
1164 .SM
1165 .B "SHELL BUILTIN COMMANDS"
1166 below), a word beginning with
1167 .B #
1168 introduces a comment.
1169 A word begins at the beginning of a line, after unquoted whitespace, or
1170 after an operator.
1171 The comment causes that word and all remaining characters on that line to
1172 be ignored.
1173 An interactive shell without the
1174 .B interactive_comments
1175 option enabled does not allow comments.
1176 The
1177 .B interactive_comments
1178 option is enabled by default in interactive shells.
1179 .SH QUOTING
1180 \fIQuoting\fP is used to remove the special meaning of certain
1181 characters or words to the shell.
1182 Quoting can be used to
1183 disable special treatment for special characters, to prevent
1184 reserved words from being recognized as such, and to prevent
1185 parameter expansion.
1186 .PP
1187 Each of the \fImetacharacters\fP listed above under
1188 .SM
1189 .B DEFINITIONS
1190 has special meaning to the shell and must be quoted if it is to
1191 represent itself.
1192 .PP
1193 When the command history expansion facilities are being used
1194 (see
1195 .SM
1196 .B "HISTORY EXPANSION"
1197 below), the
1198 \fIhistory expansion\fP character, usually \fB!\fP, must be quoted
1199 to prevent history expansion.
1200 .PP
1201 There are four quoting mechanisms: the
1202 .IR "escape character" ,
1203 single quotes, double quotes,
1204 and dollar-single quotes.
1205 .PP
1206 A non-quoted backslash (\fB\e\fP) is the
1207 .IR "escape character" .
1208 It preserves the literal value of the next character that follows,
1209 removing any special meaning it has,
1210 with the exception of <newline>.
1211 If a \fB\e\fP<newline> pair appears, and the backslash is not itself quoted,
1212 the \fB\e\fP<newline> is treated as a line continuation (that is, it is
1213 removed from the input stream and effectively ignored).
1214 .PP
1215 Enclosing characters in single quotes preserves the literal value
1216 of each character within the quotes.
1217 A single quote may not occur
1218 between single quotes, even when preceded by a backslash.
1219 .PP
1220 Enclosing characters in double quotes preserves the literal value
1221 of all characters within the quotes, with the exception of
1222 .BR $ ,
1223 .BR \` ,
1224 .BR \e ,
1225 and, when history expansion is enabled,
1226 .BR ! .
1227 When the shell is in posix mode,
1228 the \fB!\fP has no special meaning
1229 within double quotes, even when history expansion is enabled.
1230 The characters
1231 .B $
1232 and
1233 .B \`
1234 retain their special meaning within double quotes.
1235 The backslash retains its special meaning only when followed by one of
1236 the following characters:
1237 .BR $ ,
1238 .BR \` ,
1239 \^\fB\*"\fP\^,
1240 .BR \e ,
1241 or
1242 .BR <newline> .
1243 Backslashes preceding characters without a
1244 special meaning are left unmodified.
1245 .PP
1246 A double quote may be quoted within double quotes by preceding it with
1247 a backslash.
1248 If enabled, history expansion will be performed unless an
1249 .B !
1250 appearing in double quotes is escaped using a backslash.
1251 The backslash preceding the
1252 .B !
1253 is not removed.
1254 .PP
1255 The special parameters
1256 .B *
1257 and
1258 .B @
1259 have special meaning when in double quotes
1260 (see
1261 .SM
1262 .B PARAMETERS
1263 below).
1264 .PP
1265 Character sequences of the form \fB$\fP\*'\fIstring\fP\*' are treated
1266 as a special variant of single quotes.
1267 The sequence expands to \fIstring\fP, with backslash-escaped characters
1268 in \fIstring\fP replaced as specified by the ANSI C standard.
1269 Backslash escape sequences, if present, are decoded as follows:
1270 .RS
1271 .PD 0
1272 .TP
1273 .B \ea
1274 alert (bell)
1275 .TP
1276 .B \eb
1277 backspace
1278 .TP
1279 .B \ee
1280 .TP
1281 .B \eE
1282 an escape character
1283 .TP
1284 .B \ef
1285 form feed
1286 .TP
1287 .B \en
1288 new line
1289 .TP
1290 .B \er
1291 carriage return
1292 .TP
1293 .B \et
1294 horizontal tab
1295 .TP
1296 .B \ev
1297 vertical tab
1298 .TP
1299 .B \e\e
1300 backslash
1301 .TP
1302 .B \e\*'
1303 single quote
1304 .TP
1305 .B \e\*"
1306 double quote
1307 .TP
1308 .B \e?
1309 question mark
1310 .TP
1311 .B \e\fInnn\fP
1312 The eight-bit character whose value is the octal value \fInnn\fP
1313 (one to three octal digits).
1314 .TP
1315 .B \ex\fIHH\fP
1316 The eight-bit character whose value is the hexadecimal value \fIHH\fP
1317 (one or two hex digits).
1318 .TP
1319 .B \eu\fIHHHH\fP
1320 The Unicode (ISO/IEC 10646) character whose value is the hexadecimal value
1321 \fIHHHH\fP (one to four hex digits).
1322 .TP
1323 .B \eU\fIHHHHHHHH\fP
1324 The Unicode (ISO/IEC 10646) character whose value is the hexadecimal value
1325 \fIHHHHHHHH\fP (one to eight hex digits).
1326 .TP
1327 .B \ec\fIx\fP
1328 A control-\fIx\fP character.
1329 .PD
1330 .RE
1331 .LP
1332 The expanded result is single-quoted, as if the dollar sign had
1333 not been present.
1334 .SS "Translating Strings"
1335 A double-quoted string preceded by a dollar sign (\fB$\fP\*"\fIstring\fP\*")
1336 causes the string to be translated according to the current locale.
1337 The \fIgettext\fP infrastructure performs the lookup and
1338 translation, using the \fBLC_MESSAGES\fP, \fBTEXTDOMAINDIR\fP,
1339 and \fBTEXTDOMAIN\fP shell variables.
1340 If the current locale is \fBC\fP or \fBPOSIX\fP,
1341 if there are no translations available,
1342 or if the string is not translated, the dollar sign is ignored,
1343 and the string is treated as double-quoted as described above.
1344 This is a form of double quoting, so the string remains double-quoted
1345 by default, whether or not it is translated and replaced.
1346 If the \fBnoexpand_translation\fP option is enabled
1347 using the \fBshopt\fP builtin,
1348 translated strings are single-quoted instead of double-quoted.
1349 See the description of
1350 .B shopt
1351 below under
1352 .SM
1353 .BR "SHELL BUILTIN COMMANDS" .
1354 .SH PARAMETERS
1355 A
1356 .I parameter
1357 is an entity that stores values.
1358 It can be a
1359 .IR name ,
1360 a number, or one of the special characters listed below under
1361 .BR "Special Parameters" .
1362 A
1363 .I variable
1364 is a parameter denoted by a
1365 .IR name .
1366 A variable has a \fIvalue\fP and zero or more \fIattributes\fP.
1367 Attributes are assigned using the
1368 .B declare
1369 builtin command (see
1370 .B declare
1371 below in
1372 .SM
1373 .BR "SHELL BUILTIN COMMANDS" ).
1374 The \fBexport\fP and \fBreadonly\fP builtins assign specific attributes.
1375 .PP
1376 A parameter is set if it has been assigned a value.
1377 The null string is a valid value.
1378 Once a variable is set, it may be unset only by using the
1379 .B unset
1380 builtin command (see
1381 .SM
1382 .B "SHELL BUILTIN COMMANDS"
1383 below).
1384 .PP
1385 A
1386 .I variable
1387 is assigned to using a statement of the form
1388 .RS
1389 .PP
1390 \fIname\fP=[\fIvalue\fP]
1391 .RE
1392 .PP
1393 If
1394 .I value
1395 is not given, the variable is assigned the null string.
1396 All
1397 .I values
1398 undergo tilde expansion, parameter and variable expansion,
1399 command substitution, arithmetic expansion, and quote
1400 removal (see
1401 .SM
1402 .B EXPANSION
1403 below).
1404 If the variable has its
1405 .B integer
1406 attribute set, then
1407 .I value
1408 is evaluated as an arithmetic expression even if the
1409 .BR $(( .\|.\|.\& ))
1410 expansion is not used (see
1411 .B "Arithmetic Expansion"
1412 below).
1413 Word splitting and pathname expansion are not performed.
1414 Assignment statements may also appear as arguments to the
1415 .BR alias ,
1416 .BR declare ,
1417 .BR typeset ,
1418 .BR \%export ,
1419 .BR readonly ,
1420 and
1421 .B local
1422 builtin commands (\fIdeclaration\fP commands).
1423 When in posix mode, these builtins may appear in a command after
1424 one or more instances of the \fBcommand\fP builtin and retain these
1425 assignment statement properties.
1426 .PP
1427 In the context where an assignment statement is assigning a value
1428 to a shell variable or array index, the
1429 .Q +=
1430 operator appends to or adds to
1431 the variable's previous value.
1432 This includes arguments to \fIdeclaration\fP commands such as
1433 .B \%declare
1434 that accept assignment statements.
1435 When
1436 .Q +=
1437 is applied to a variable for which the
1438 .B \%integer
1439 attribute has been set,
1440 the variable's current value and \fIvalue\fP are each evaluated as
1441 arithmetic expressions,
1442 and the sum of the results is assigned as the variable's value.
1443 The current value is usually an integer constant, but may be an expression.
1444 When
1445 .Q +=
1446 is applied to an array variable using compound assignment
1447 (see
1448 .B Arrays
1449 below),
1450 the variable's value is not unset
1451 (as it is when using
1452 .Q = ),
1453 and new values are appended to the array
1454 beginning at one greater than the array's maximum index (for indexed arrays)
1455 or added as additional key\-value pairs in an associative array.
1456 When applied to a string-valued variable, \fIvalue\fP is expanded and
1457 appended to the variable's value.
1458 .PP
1459 A variable can be assigned the \fInameref\fP attribute using the
1460 \fB\-n\fP option to the \fBdeclare\fP or \fBlocal\fP builtin commands
1461 (see the descriptions of \fBdeclare\fP and \fBlocal\fP below)
1462 to create a \fInameref\fP, or a reference to another variable.
1463 This allows variables to be manipulated indirectly.
1464 Whenever the nameref variable is referenced, assigned to, unset, or has
1465 its attributes modified (other than using or changing the \fInameref\fP
1466 attribute itself), the
1467 operation is actually performed on the variable specified by the nameref
1468 variable's value.
1469 A nameref is commonly used within shell functions to refer to a variable
1470 whose name is passed as an argument to the function.
1471 For instance, if a variable name is passed to a shell function as its first
1472 argument, running
1473 .PP
1474 .RS
1475 .EX
1476 declare \-n ref=$1
1477 .EE
1478 .RE
1479 .PP
1480 inside the function creates a local nameref variable \fBref\fP whose value
1481 is the variable name passed as the first argument.
1482 References and assignments to \fBref\fP, and changes to its attributes,
1483 are treated as references, assignments, and attribute modifications
1484 to the variable whose name was passed as \fB$1\fP.
1485 If the control variable in a \fBfor\fP loop has the nameref attribute,
1486 the list of words can be a list of shell variables, and a name reference
1487 is established for each word in the list, in turn, when the loop is
1488 executed.
1489 Array variables cannot be given the \fBnameref\fP attribute.
1490 However, nameref variables can reference array variables and subscripted
1491 array variables.
1492 Namerefs can be unset using the \fB\-n\fP option to the \fBunset\fP builtin.
1493 Otherwise, if \fBunset\fP is executed with the name of a nameref variable
1494 as an argument, the variable referenced by the nameref variable is unset.
1495 .PP
1496 When the shell starts, it reads its environment and creates a shell
1497 variable from each environment variable that has a valid name,
1498 as described below
1499 (see
1500 .SM
1501 .BR ENVIRONMENT ).
1502 .SS Positional Parameters
1503 A
1504 .I positional parameter
1505 is a parameter denoted by one or more
1506 digits, other than the single digit 0.
1507 Positional parameters are
1508 assigned from the shell's arguments when it is invoked,
1509 and may be reassigned using the
1510 .B set
1511 builtin command.
1512 Positional parameters may not be assigned to
1513 with assignment statements.
1514 The positional parameters are
1515 temporarily replaced when a shell function is executed (see
1516 .SM
1517 .B FUNCTIONS
1518 below).
1519 .PP
1520 When a positional parameter consisting of more than a single
1521 digit is expanded, it must be enclosed in braces (see
1522 .SM
1523 .B EXPANSION
1524 below).
1525 Without braces, a digit following $ can only refer to
1526 one of the first nine positional parameters (\fB$1\-$9\fP) or the
1527 special parameter \fB$0\fP (see the next section).
1528 .SS Special Parameters
1529 The shell treats several parameters specially.
1530 These parameters may only be referenced; assignment to them is
1531 not allowed.
1532 Special parameters are denoted by one of the following characters.
1533 .TP
1534 .PD 0
1535 .B *
1536 (\fB$*\fP) Expands to the positional parameters, starting from one.
1537 When the expansion is not within double quotes, each positional parameter
1538 expands to a separate word.
1539 In contexts where word expansions are performed, those words
1540 are subject to further word splitting and pathname expansion.
1541 When the expansion occurs within double quotes, it expands to a
1542 single word with the value of each parameter separated by the first
1543 character of the
1544 .SM
1545 .B IFS
1546 variable.
1547 That is,
1548 .B \*"$*\*"
1549 is equivalent to
1550 .BR \*"$1\fIc\fP$2\fIc\fP.\|.\|.\*" ,
1551 where
1552 .I c
1553 is the first character of the value of the
1554 .SM
1555 .B IFS
1556 variable.
1557 If
1558 .SM
1559 .B IFS
1560 is unset, the parameters are separated by spaces.
1561 If
1562 .SM
1563 .B IFS
1564 is null, the parameters are joined without intervening separators.
1565 .TP
1566 .B @
1567 (\fB$@\fP) Expands to the positional parameters, starting from one.
1568 In contexts where word splitting is performed, this expands each
1569 positional parameter to a separate word; if not within double
1570 quotes, these words are subject to word splitting.
1571 In contexts where word splitting is not performed,
1572 such as the value portion of an assignment statement,
1573 this expands to a single word
1574 with each positional parameter separated by a space.
1575 When the expansion occurs within double quotes,
1576 and word splitting is performed,
1577 each parameter expands to a separate word.
1578 That is,
1579 .B \&\*"$@\*"
1580 is equivalent to
1581 .B \&\*"\&$1\&\*"\ \*"$2\*"\ .\|.\|.
1582 If the double-quoted expansion occurs within a word, the expansion of
1583 the first parameter is joined with the expansion of the
1584 beginning part of the original word,
1585 and the expansion of the last parameter is joined with the
1586 expansion of the last part of the original word.
1587 When there are no positional parameters,
1588 .B \&\*"$@\*"
1589 and
1590 .B $@
1591 expand to nothing (i.e., they are removed).
1592 .TP
1593 .B #
1594 (\fB$#\fP) Expands to the number of positional parameters in decimal.
1595 .TP
1596 .B ?
1597 (\fB$?\fP) Expands to the exit status of the most recently executed command.
1598 .TP
1599 .B \-
1600 (\fB$\-\fP) Expands to the current option flags as specified upon invocation,
1601 by the
1602 .B set
1603 builtin command, or those set by the shell itself
1604 (such as the
1605 .B \-i
1606 option).
1607 .TP
1608 .B $
1609 (\fB$$\fP) Expands to the process ID of the shell.
1610 In a subshell, it expands to the process ID of the parent shell,
1611 not the subshell.
1612 .TP
1613 .B !
1614 (\fB$!\fP)Expands to the process ID of the job most recently placed into the
1615 background, whether executed as an asynchronous command or using
1616 the \fBbg\fP builtin (see
1617 .SM
1618 .B "JOB CONTROL"
1619 below).
1620 .TP
1621 .B 0
1622 (\fB$0\fP) Expands to the name of the shell or shell script.
1623 This is set at shell initialization.
1624 If \fBbash\fP is invoked with a file of commands,
1625 .B $0
1626 is set to the name of that file.
1627 If \fBbash\fP is started with the
1628 .B \-c
1629 option, then
1630 .B $0
1631 is set to the first argument after the string to be
1632 executed, if one is present.
1633 Otherwise, it is set to the filename used to invoke
1634 .BR bash ,
1635 as given by argument zero.
1636 .PD
1637 .SS "Shell Variables"
1638 The shell sets following variables:
1639 .PP
1640 .PD 0
1641 .TP
1642 .B _
1643 (\fB$_\fP, an underscore)
1644 This has a number of meanings depending on context.
1645 At shell startup, \fB_\fP is set to the pathname used to invoke the
1646 shell or shell script being executed as passed in the environment
1647 or argument list.
1648 Subsequently, it expands to the last argument to the previous simple
1649 command executed in the foreground, after expansion.
1650 It is also set to the full pathname used to invoke each command executed
1651 and placed in the environment exported to that command.
1652 When checking mail, \fB$_\fP expands to the name of the mail file
1653 currently being checked.
1654 .TP
1655 .B BASH
1656 Expands to the full filename used to invoke this instance of
1657 .BR bash .
1658 .TP
1659 .B BASHOPTS
1660 A colon-separated list of enabled shell options. Each word in
1661 the list is a valid argument for the
1662 .B \-s
1663 option to the
1664 .B shopt
1665 builtin command (see
1666 .SM
1667 .B "SHELL BUILTIN COMMANDS"
1668 below).
1669 The options appearing in
1670 .SM
1671 .B BASHOPTS
1672 are those reported as
1673 .I on
1674 by \fBshopt\fP.
1675 If this variable is in the environment when
1676 .B bash
1677 starts up, the shell enables each option in the list before
1678 reading any startup files.
1679 If this variable is exported, child shells will enable each option
1680 in the list.
1681 This variable is read-only.
1682 .TP
1683 .B BASHPID
1684 Expands to the process ID of the current \fBbash\fP process.
1685 This differs from \fB$$\fP under certain circumstances, such as subshells
1686 that do not require \fBbash\fP to be re-initialized.
1687 Assignments to
1688 .SM
1689 .B BASHPID
1690 have no effect.
1691 If
1692 .SM
1693 .B BASHPID
1694 is unset, it loses its special properties, even if it is
1695 subsequently reset.
1696 .TP
1697 .B BASH_ALIASES
1698 An associative array variable whose members correspond to the internal
1699 list of aliases as maintained by the \fBalias\fP builtin.
1700 Elements added to this array appear in the alias list; however,
1701 unsetting array elements currently does not remove aliases
1702 from the alias list.
1703 If
1704 .SM
1705 .B BASH_ALIASES
1706 is unset, it loses its special properties, even if it is
1707 subsequently reset.
1708 .TP
1709 .B BASH_ARGC
1710 An array variable whose values are the number of parameters in each
1711 frame of the current \fBbash\fP execution call stack.
1712 The number of parameters to the current subroutine (shell function or
1713 script executed with \fB.\fP or \fBsource\fP) is at the top of the stack.
1714 When a subroutine is executed, the number of parameters passed is pushed onto
1715 .SM
1716 .BR BASH_ARGC .
1717 The shell sets
1718 .SM
1719 .B BASH_ARGC
1720 only when in extended debugging mode (see the description of the
1721 .B extdebug
1722 option to the
1723 .B shopt
1724 builtin below).
1725 Setting \fBextdebug\fP after the shell has started to execute a script,
1726 or referencing this variable when \fBextdebug\fP is not set,
1727 may result in inconsistent values.
1728 Assignments to
1729 .SM
1730 .B BASH_ARGC
1731 have no effect, and it may not be unset.
1732 .TP
1733 .B BASH_ARGV
1734 An array variable containing all of the parameters in the current \fBbash\fP
1735 execution call stack.
1736 The final parameter of the last subroutine call is at the top of the stack;
1737 the first parameter of the initial call is at the bottom.
1738 When a subroutine is executed, the shell pushes the supplied parameters onto
1739 .SM
1740 .BR BASH_ARGV .
1741 The shell sets
1742 .SM
1743 .B BASH_ARGV
1744 only when in extended debugging mode
1745 (see the description of the
1746 .B extdebug
1747 option to the
1748 .B shopt
1749 builtin below).
1750 Setting \fBextdebug\fP after the shell has started to execute a script,
1751 or referencing this variable when \fBextdebug\fP is not set,
1752 may result in inconsistent values.
1753 Assignments to
1754 .SM
1755 .B BASH_ARGV
1756 have no effect, and it may not be unset.
1757 .TP
1758 .B BASH_ARGV0
1759 When referenced, this variable expands to the name of the shell or shell
1760 script (identical to
1761 .BR $0 ;
1762 see the description of special parameter 0 above).
1763 Assigning a value to
1764 .SM
1765 .B BASH_ARGV0
1766 sets \fB$0\fP to the same value.
1767 If
1768 .SM
1769 .B BASH_ARGV0
1770 is unset, it loses its special properties, even if it is
1771 subsequently reset.
1772 .TP
1773 .B BASH_CMDS
1774 An associative array variable whose members correspond to the internal
1775 hash table of commands as maintained by the \fBhash\fP builtin.
1776 Adding elements to this array makes them appear in the hash table; however,
1777 unsetting array elements currently does not remove command names
1778 from the hash table.
1779 If
1780 .SM
1781 .B BASH_CMDS
1782 is unset, it loses its special properties, even if it is
1783 subsequently reset.
1784 .TP
1785 .B BASH_COMMAND
1786 Expands to the command currently being executed or about to be executed,
1787 unless the shell is executing a command as the result of a trap,
1788 in which case it is the command executing at the time of the trap.
1789 If
1790 .SM
1791 .B BASH_COMMAND
1792 is unset, it loses its special properties, even if it is
1793 subsequently reset.
1794 .TP
1795 .B BASH_EXECUTION_STRING
1796 The command argument to the \fB\-c\fP invocation option.
1797 .TP
1798 .B BASH_LINENO
1799 An array variable whose members are the line numbers in source files
1800 where each corresponding member of
1801 .SM
1802 .B FUNCNAME
1803 was invoked.
1804 \fB${BASH_LINENO[\fP\fI$i\fP\fB]}\fP
1805 is the line number in the source file
1806 (\fB${BASH_SOURCE[\fP\fI$i+1\fP\fB]}\fP)
1807 where
1808 \fB${FUNCNAME[\fP\fI$i\fP\fB]}\fP
1809 was called
1810 (or \fB${BASH_LINENO[\fP\fI$i\-1\fP\fB]}\fP if referenced within another
1811 shell function).
1812 Use
1813 .SM
1814 .B LINENO
1815 to obtain the current line number.
1816 Assignments to
1817 .SM
1818 .B BASH_LINENO
1819 have no effect, and it may not be unset.
1820 .TP
1821 .B BASH_LOADABLES_PATH
1822 A colon-separated list of directories in which the
1823 .B enable
1824 command
1825 looks for
1826 dynamically loadable builtins.
1827 .TP
1828 .B BASH_MONOSECONDS
1829 Each time this variable is referenced, it expands to the value returned
1830 by the system's monotonic clock, if one is available.
1831 If there is no monotonic clock, this is equivalent to \fBEPOCHSECONDS\fP.
1832 If
1833 .SM
1834 .B BASH_MONOSECONDS
1835 is unset, it loses its special properties, even if it is
1836 subsequently reset.
1837 .TP
1838 .B BASH_REMATCH
1839 An array variable whose members are assigned by the \fB=\*~\fP binary
1840 operator to the \fB[[\fP conditional command.
1841 The element with index 0 is the portion of the string
1842 matching the entire regular expression.
1843 The element with index \fIn\fP is the portion of the
1844 string matching the \fIn\fPth parenthesized subexpression.
1845 .TP
1846 .B BASH_SOURCE
1847 An array variable whose members are the source filenames
1848 where the corresponding shell function names in the
1849 .SM
1850 .B FUNCNAME
1851 array variable are defined.
1852 The shell function
1853 \fB${FUNCNAME[\fP\fI$i\fP\fB]}\fP is defined in the file
1854 \fB${BASH_SOURCE[\fP\fI$i\fP\fB]}\fP and called from
1855 \fB${BASH_SOURCE[\fP\fI$i+1\fP\fB]}\fP.
1856 Assignments to
1857 .SM
1858 .B BASH_SOURCE
1859 have no effect, and it may not be unset.
1860 .TP
1861 .B BASH_SUBSHELL
1862 Incremented by one within each subshell or subshell environment when
1863 the shell begins executing in that environment.
1864 The initial value is 0.
1865 If
1866 .SM
1867 .B BASH_SUBSHELL
1868 is unset, it loses its special properties, even if it is
1869 subsequently reset.
1870 .TP
1871 .B BASH_TRAPSIG
1872 Set to the signal number corresponding to the trap action being executed
1873 during its execution.
1874 See the description of \fBtrap\fP under
1875 .SM
1876 .B "SHELL BUILTIN COMMANDS"
1877 below for information about signal numbers and trap execution.
1878 .TP
1879 .B BASH_VERSINFO
1880 A readonly array variable whose members hold version information for
1881 this instance of
1882 .BR bash .
1883 The values assigned to the array members are as follows:
1884 .PP
1885 .RS
1886 .TP 24
1887 .B BASH_VERSINFO[\fR0\fP]
1888 The major version number (the \fIrelease\fP).
1889 .TP
1890 .B BASH_VERSINFO[\fR1\fP]
1891 The minor version number (the \fIversion\fP).
1892 .TP
1893 .B BASH_VERSINFO[\fR2\fP]
1894 The patch level.
1895 .TP
1896 .B BASH_VERSINFO[\fR3\fP]
1897 The build version.
1898 .TP
1899 .B BASH_VERSINFO[\fR4\fP]
1900 The release status (e.g., \fIbeta\fP).
1901 .TP
1902 .B BASH_VERSINFO[\fR5\fP]
1903 The value of
1904 .SM
1905 .BR MACHTYPE .
1906 .RE
1907 .TP
1908 .B BASH_VERSION
1909 Expands to a string describing the version of this instance of
1910 .B bash
1911 (e.g., 5.2.37(3)-release).
1912 .TP
1913 .B COMP_CWORD
1914 An index into \fB${COMP_WORDS}\fP of the word containing the current
1915 cursor position.
1916 This variable is available only in shell functions invoked by the
1917 programmable completion facilities (see \fBProgrammable Completion\fP
1918 below).
1919 .TP
1920 .B COMP_KEY
1921 The key (or final key of a key sequence) used to invoke the current
1922 completion function.
1923 This variable is available only in shell functions and external
1924 commands invoked by the
1925 programmable completion facilities (see \fBProgrammable Completion\fP
1926 below).
1927 .TP
1928 .B COMP_LINE
1929 The current command line.
1930 This variable is available only in shell functions and external
1931 commands invoked by the
1932 programmable completion facilities (see \fBProgrammable Completion\fP
1933 below).
1934 .TP
1935 .B COMP_POINT
1936 The index of the current cursor position relative to the beginning of
1937 the current command.
1938 If the current cursor position is at the end of the current command,
1939 the value of this variable is equal to \fB${#COMP_LINE}\fP.
1940 This variable is available only in shell functions and external
1941 commands invoked by the
1942 programmable completion facilities (see \fBProgrammable Completion\fP
1943 below).
1944 .TP
1945 .B COMP_TYPE
1946 Set to an integer value corresponding to the type of attempted completion
1947 that caused a completion function to be called:
1948 \fITAB\fP, for normal completion,
1949 \fI?\fP, for listing completions after successive tabs,
1950 \fI!\fP, for listing alternatives on partial word completion,
1951 \fI@\fP, to list completions if the word is not unmodified,
1952 or
1953 \fI%\fP, for menu completion.
1954 This variable is available only in shell functions and external
1955 commands invoked by the
1956 programmable completion facilities (see \fBProgrammable Completion\fP
1957 below).
1958 .TP
1959 .B COMP_WORDBREAKS
1960 The set of characters that the \fBreadline\fP library treats as word
1961 separators when performing word completion.
1962 If
1963 .SM
1964 .B COMP_WORDBREAKS
1965 is unset, it loses its special properties, even if it is
1966 subsequently reset.
1967 .TP
1968 .B COMP_WORDS
1969 An array variable (see \fBArrays\fP below) consisting of the individual
1970 words in the current command line.
1971 The line is split into words as \fBreadline\fP would split it, using
1972 .SM
1973 .B COMP_WORDBREAKS
1974 as described above.
1975 This variable is available only in shell functions invoked by the
1976 programmable completion facilities (see \fBProgrammable Completion\fP
1977 below).
1978 .TP
1979 .B COPROC
1980 An array variable (see \fBArrays\fP below) created to hold the file descriptors
1981 for output from and input to an unnamed coprocess (see \fBCoprocesses\fP
1982 above).
1983 .TP
1984 .B DIRSTACK
1985 An array variable (see
1986 .B Arrays
1987 below) containing the current contents of the directory stack.
1988 Directories appear in the stack in the order they are displayed by the
1989 .B dirs
1990 builtin.
1991 Assigning to members of this array variable may be used to modify
1992 directories already in the stack, but the
1993 .B pushd
1994 and
1995 .B popd
1996 builtins must be used to add and remove directories.
1997 Assigning to this variable does not change the current directory.
1998 If
1999 .SM
2000 .B DIRSTACK
2001 is unset, it loses its special properties, even if it is
2002 subsequently reset.
2003 .TP
2004 .B EPOCHREALTIME
2005 Each time this parameter is referenced, it expands to the number of seconds
2006 since the Unix Epoch (see
2007 .IR time (3))
2008 as a floating-point value with micro-second granularity.
2009 Assignments to
2010 .SM
2011 .B EPOCHREALTIME
2012 are ignored.
2013 If
2014 .SM
2015 .B EPOCHREALTIME
2016 is unset, it loses its special properties, even if it is
2017 subsequently reset.
2018 .TP
2019 .B EPOCHSECONDS
2020 Each time this parameter is referenced, it expands to the number of seconds
2021 since the Unix Epoch (see
2022 .IR time (3)).
2023 Assignments to
2024 .SM
2025 .B EPOCHSECONDS
2026 are ignored.
2027 If
2028 .SM
2029 .B EPOCHSECONDS
2030 is unset, it loses its special properties, even if it is
2031 subsequently reset.
2032 .TP
2033 .B EUID
2034 Expands to the effective user ID of the current user, initialized at
2035 shell startup. This variable is readonly.
2036 .TP
2037 .B FUNCNAME
2038 .PD
2039 An array variable containing the names of all shell functions
2040 currently in the execution call stack.
2041 The element with index 0 is the name of any currently-executing
2042 shell function.
2043 The bottom-most element (the one with the highest index) is
2044 .Q main .
2045 This variable exists only when a shell function is executing.
2046 Assignments to
2047 .SM
2048 .B FUNCNAME
2049 have no effect.
2050 If
2051 .SM
2052 .B FUNCNAME
2053 is unset, it loses its special properties, even if it is
2054 subsequently reset.
2055 .IP
2056 This variable can be used with
2057 .SM
2058 .B BASH_LINENO
2059 and
2060 .SM
2061 .BR BASH_SOURCE .
2062 Each element of
2063 .SM
2064 .B \%FUNCNAME
2065 has corresponding elements in
2066 .SM
2067 .B BASH_LINENO
2068 and
2069 .SM
2070 .B BASH_SOURCE
2071 to describe the call stack.
2072 For instance,
2073 \fB\%${FUNCNAME[\fP\fI$i\fP\fB]}\fP
2074 was called from the file
2075 \fB${BASH_SOURCE[\fP\fI$i+1\fP\fB]}\fP
2076 at line number
2077 \fB${BASH_LINENO[\fP\fI$i\fP\fB]}\fP.
2078 The \fBcaller\fP builtin displays the current call stack using this
2079 information.
2080 .PD 0
2081 .TP
2082 .B GROUPS
2083 An array variable containing the list of groups of which the current
2084 user is a member.
2085 Assignments to
2086 .SM
2087 .B GROUPS
2088 have no effect.
2089 If
2090 .SM
2091 .B GROUPS
2092 is unset, it loses its special properties, even if it is
2093 subsequently reset.
2094 .TP
2095 .B HISTCMD
2096 The history number, or index in the history list, of the current
2097 command.
2098 Assignments to
2099 .SM
2100 .B HISTCMD
2101 have no effect.
2102 If
2103 .SM
2104 .B HISTCMD
2105 is unset, it loses its special properties, even if it is
2106 subsequently reset.
2107 .TP
2108 .B HOSTNAME
2109 Automatically set to the name of the current host.
2110 .TP
2111 .B HOSTTYPE
2112 Automatically set to a string that uniquely
2113 describes the type of machine on which
2114 .B bash
2115 is executing.
2116 The default is system-dependent.
2117 .TP
2118 .B LINENO
2119 Each time this parameter is referenced, the shell substitutes
2120 a decimal number representing the current sequential line number
2121 (starting with 1) within a script or function.
2122 When not in a script or function, the value substituted is not
2123 guaranteed to be meaningful.
2124 If
2125 .SM
2126 .B LINENO
2127 is unset, it loses its special properties, even if it is
2128 subsequently reset.
2129 .TP
2130 .B MACHTYPE
2131 Automatically set to a string that fully describes the system
2132 type on which
2133 .B bash
2134 is executing, in the standard GNU \fIcpu-company-system\fP format.
2135 The default is system-dependent.
2136 .TP
2137 .B MAPFILE
2138 An array variable (see \fBArrays\fP below) created to hold the text
2139 read by the \fBmapfile\fP builtin when no variable name is supplied.
2140 .TP
2141 .B OLDPWD
2142 The previous working directory as set by the
2143 .B cd
2144 command.
2145 .TP
2146 .B OPTARG
2147 The value of the last option argument processed by the
2148 .B getopts
2149 builtin command (see
2150 .SM
2151 .B "SHELL BUILTIN COMMANDS"
2152 below).
2153 .TP
2154 .B OPTIND
2155 The index of the next argument to be processed by the
2156 .B getopts
2157 builtin command (see
2158 .SM
2159 .B "SHELL BUILTIN COMMANDS"
2160 below).
2161 .TP
2162 .B OSTYPE
2163 Automatically set to a string that
2164 describes the operating system on which
2165 .B bash
2166 is executing.
2167 The default is system-dependent.
2168 .TP
2169 .B PIPESTATUS
2170 An array variable (see
2171 .B Arrays
2172 below) containing a list of exit status values from the commands
2173 in the most-recently-executed foreground pipeline, which may
2174 consist of only a simple command
2175 (see
2176 .SM
2177 .B "SHELL GRAMMAR"
2178 above).
2179 \fBBash\fP sets
2180 .SM
2181 .B PIPESTATUS
2182 after executing multi-element pipelines,
2183 timed and negated pipelines,
2184 simple commands,
2185 subshells created with the ( operator,
2186 the
2187 .B [[
2188 and
2189 .B ((
2190 compound commands, and
2191 after error conditions that result in the
2192 shell aborting command execution.
2193 .TP
2194 .B PPID
2195 The process ID of the shell's parent.
2196 This variable is readonly.
2197 .TP
2198 .B PWD
2199 The current working directory as set by the
2200 .B cd
2201 command.
2202 .TP
2203 .B RANDOM
2204 Each time this parameter is referenced, it expands to a random integer
2205 between 0 and 32767.
2206 Assigning a value to
2207 .SM
2208 .B RANDOM
2209 initializes (seeds) the sequence of random numbers.
2210 Seeding the random number generator with the same constant value
2211 produces the same sequence of values.
2212 If
2213 .SM
2214 .B RANDOM
2215 is unset, it loses its special properties, even if it is
2216 subsequently reset.
2217 .TP
2218 .B READLINE_ARGUMENT
2219 Any numeric argument given to a
2220 .B \%readline
2221 command that was defined using
2222 .Q "bind \-x"
2223 (see
2224 .SM
2225 .B "SHELL BUILTIN COMMANDS"
2226 below)
2227 when it was invoked.
2228 .TP
2229 .B READLINE_LINE
2230 The contents of the
2231 .B readline
2232 line buffer, for use with
2233 .Q "bind \-x"
2234 (see
2235 .SM
2236 .B "SHELL BUILTIN COMMANDS"
2237 below).
2238 .TP
2239 .B READLINE_MARK
2240 The position of the mark (saved insertion point) in the
2241 .B readline
2242 line buffer, for use with
2243 .Q "bind \-x"
2244 (see
2245 .SM
2246 .B "SHELL BUILTIN COMMANDS"
2247 below).
2248 The characters between the insertion point and the mark are often
2249 called the \fIregion\fP.
2250 .TP
2251 .B READLINE_POINT
2252 The position of the insertion point in the
2253 .B readline
2254 line buffer, for use with
2255 .Q "bind \-x"
2256 (see
2257 .SM
2258 .B "SHELL BUILTIN COMMANDS"
2259 below).
2260 .TP
2261 .B REPLY
2262 Set to the line of input read by the
2263 .B read
2264 builtin command when no arguments are supplied.
2265 .TP
2266 .B SECONDS
2267 Each time this parameter is
2268 referenced, it expands to the number of seconds since shell invocation.
2269 If a value is assigned to
2270 .SM
2271 .BR SECONDS ,
2272 the value returned upon subsequent
2273 references is
2274 the number of seconds since the assignment plus the value assigned.
2275 The number of seconds at shell invocation and the current time are always
2276 determined by querying the system clock at one-second resolution.
2277 If
2278 .SM
2279 .B SECONDS
2280 is unset, it loses its special properties, even if it is
2281 subsequently reset.
2282 .TP
2283 .B SHELLOPTS
2284 A colon-separated list of enabled shell options.
2285 Each word in the list is a valid argument for the
2286 .B \-o
2287 option to the
2288 .B set
2289 builtin command (see
2290 .SM
2291 .B "SHELL BUILTIN COMMANDS"
2292 below).
2293 The options appearing in
2294 .SM
2295 .B SHELLOPTS
2296 are those reported as
2297 .I on
2298 by \fBset \-o\fP.
2299 If this variable is in the environment when
2300 .B bash
2301 starts up, the shell enables each option in the list before
2302 reading any startup files.
2303 If this variable is exported, child shells will enable each option
2304 in the list.
2305 This variable is read-only.
2306 .TP
2307 .B SHLVL
2308 Incremented by one each time an instance of
2309 .B bash
2310 is started.
2311 .TP
2312 .B SRANDOM
2313 Each time it is referenced, this variable expands to a 32-bit pseudo-random
2314 number.
2315 The random number generator is not linear on systems that
2316 support
2317 .FN /dev/urandom
2318 or
2319 .IR arc4random (3),
2320 so each returned number
2321 has no relationship to the numbers preceding it.
2322 The random number generator cannot be seeded, so assignments to this
2323 variable have no effect.
2324 If
2325 .SM
2326 .B SRANDOM
2327 is unset, it loses its special properties,
2328 even if it is subsequently reset.
2329 .TP
2330 .B UID
2331 Expands to the user ID of the current user, initialized at shell startup.
2332 This variable is readonly.
2333 .PD
2334 .PP
2335 The shell uses the following variables. In some cases,
2336 .B bash
2337 assigns a default value to a variable; these cases are noted
2338 below.
2339 .PP
2340 .PD 0
2341 .TP
2342 .B BASH_COMPAT
2343 The value is used to set the shell's compatibility level.
2344 See
2345 .SM
2346 .B "SHELL COMPATIBILITY MODE"
2347 below for a description of the various compatibility
2348 levels and their effects.
2349 The value may be a decimal number (e.g., 4.2) or an integer (e.g., 42)
2350 corresponding to the desired compatibility level.
2351 If
2352 .SM
2353 .B BASH_COMPAT
2354 is unset or set to the empty string, the compatibility
2355 level is set to the default for the current version.
2356 If
2357 .SM
2358 .B BASH_COMPAT
2359 is set to a value that is not one of the valid
2360 compatibility levels, the shell prints an error message and sets the
2361 compatibility level to the default for the current version.
2362 A subset of the valid values correspond to the compatibility levels
2363 described below under
2364 .SM
2365 .BR "SHELL COMPATIBILITY MODE" .
2366 For example, 4.2 and 42 are valid values that correspond
2367 to the \fBcompat42\fP \fBshopt\fP option
2368 and set the compatibility level to 42.
2369 The current version is also a valid value.
2370 .TP
2371 .B BASH_ENV
2372 If this parameter is set when \fBbash\fP is executing a shell script,
2373 its expanded value is interpreted as a filename containing commands to
2374 initialize the shell before it reads and executes commands from the
2375 script.
2376 The value of
2377 .SM
2378 .B BASH_ENV
2379 is subjected to parameter expansion, command substitution, and arithmetic
2380 expansion before being interpreted as a filename.
2381 .SM
2382 .B PATH
2383 is not used to search for the resultant filename.
2384 .TP
2385 .B BASH_XTRACEFD
2386 If set to an integer corresponding to a valid file descriptor,
2387 \fBbash\fP writes the trace output generated when
2388 .Q "set \-x"
2389 is enabled to that file descriptor,
2390 instead of the standard error.
2391 The file descriptor is closed when
2392 .SM
2393 .B BASH_XTRACEFD
2394 is unset or assigned a new value.
2395 Unsetting
2396 .SM
2397 .B BASH_XTRACEFD
2398 or assigning it the empty string causes the
2399 trace output to be sent to the standard error.
2400 Note that setting
2401 .SM
2402 .B BASH_XTRACEFD
2403 to 2 (the standard error file
2404 descriptor) and then unsetting it will result in the standard error
2405 being closed.
2406 .TP
2407 .B CDPATH
2408 The search path for the
2409 .B cd
2410 command.
2411 This is a colon-separated list of directories where the shell looks for
2412 directories specified as arguments to the
2413 .B cd
2414 command.
2415 A sample value is
2416 .Q .:\*~:/usr .
2417 .TP
2418 .B CHILD_MAX
2419 Set the number of exited child status values for the shell to remember.
2420 \fBBash\fP will not allow this value to be decreased below a
2421 .SM POSIX\c
2422 -mandated minimum,
2423 and there is a maximum value (currently 8192) that this may not exceed.
2424 The minimum value is system-dependent.
2425 .TP
2426 .B COLUMNS
2427 Used by the \fBselect\fP compound command to determine the terminal width
2428 when printing selection lists.
2429 Automatically set if the
2430 .B checkwinsize
2431 option is enabled or in an interactive shell upon receipt of a
2432 .SM
2433 .BR SIGWINCH .
2434 .TP
2435 .B COMPREPLY
2436 An array variable from which \fBbash\fP reads the possible completions
2437 generated by a shell function invoked by the programmable completion
2438 facility (see \fBProgrammable Completion\fP below).
2439 Each array element contains one possible completion.
2440 .TP
2441 .B EMACS
2442 If \fBbash\fP finds this variable in the environment when the shell starts
2443 with value
2444 .Q t ,
2445 it assumes that the shell is running in an Emacs shell buffer and disables
2446 line editing.
2447 .TP
2448 .B ENV
2449 Expanded and executed similarly to
2450 .SM
2451 .B BASH_ENV
2452 (see
2453 .SM
2454 .B INVOCATION
2455 above) when an interactive shell is invoked in posix mode.
2456 .TP
2457 .B EXECIGNORE
2458 A colon-separated list of shell patterns (see \fBPattern Matching\fP)
2459 defining the set of filenames to be ignored by command search using
2460 .SM
2461 .BR PATH .
2462 Files whose full pathnames match one of these patterns are not considered
2463 executable files for the purposes of completion and command execution
2464 via
2465 .SM
2466 .B PATH
2467 lookup.
2468 This does not affect the behavior of the \fB[\fP, \fBtest\fP, and \fB[[\fP
2469 commands.
2470 Full pathnames in the command hash table are not subject to
2471 .SM
2472 .BR EXECIGNORE .
2473 Use this variable to ignore shared library files that have the executable
2474 bit set, but are not executable files.
2475 The pattern matching honors the setting of the \fBextglob\fP shell
2476 option.
2477 .TP
2478 .B FCEDIT
2479 The default editor for the
2480 .B fc
2481 builtin command.
2482 .TP
2483 .B FIGNORE
2484 A colon-separated list of suffixes to ignore when performing
2485 filename completion (see
2486 .SM
2487 .B READLINE
2488 below).
2489 A filename whose suffix matches one of the entries in
2490 .SM
2491 .B FIGNORE
2492 is excluded from the list of matched filenames.
2493 A sample value is
2494 .Q .o:\*~ .
2495 .TP
2496 .B FUNCNEST
2497 If set to a numeric value greater than 0, defines a maximum function
2498 nesting level.
2499 Function invocations that exceed this nesting level
2500 cause the current command to abort.
2501 .TP
2502 .B GLOBIGNORE
2503 A colon-separated list of patterns defining the set of file names to
2504 be ignored by pathname expansion.
2505 If a file name matched by a pathname expansion pattern also matches one
2506 of the patterns in
2507 .SM
2508 .BR GLOBIGNORE ,
2509 it is removed from the list of matches.
2510 The pattern matching honors the setting of the \fBextglob\fP shell
2511 option.
2512 .TP
2513 .B GLOBSORT
2514 .PD
2515 Controls how the results of pathname expansion are sorted.
2516 The value of this variable specifies the sort criteria and sort order for
2517 the results of pathname expansion.
2518 If this variable is unset or set to the null string, pathname expansion
2519 uses the historical behavior of sorting by name,
2520 in ascending lexicographic order as determined by the
2521 .SM
2522 .B \%LC_COLLATE
2523 shell variable.
2524 .IP
2525 If set, a valid value begins with an optional \fI+\fP, which is ignored,
2526 or \fI\-\fP, which reverses the sort order from ascending to descending,
2527 followed by a sort specifier.
2528 The valid sort specifiers are
2529 .IR name ,
2530 .IR \%numeric ,
2531 .IR size ,
2532 .IR mtime ,
2533 .IR atime ,
2534 .IR ctime ,
2535 and
2536 .IR blocks ,
2537 which sort the files on name,
2538 names in numeric rather than lexicographic order,
2539 file size, modification time, access time,
2540 inode change time, and number of blocks, respectively.
2541 If any of the non-name keys compare as equal (e.g., if two files are
2542 the same size), sorting uses the name as a secondary sort key.
2543 .IP
2544 For example, a value of \fI\-mtime\fP sorts the results in descending
2545 order by modification time (newest first).
2546 .IP
2547 The \fInumeric\fP specifier treats names consisting solely of digits as
2548 numbers and sorts them using their numeric value
2549 (so
2550 .Q 2
2551 sorts before
2552 .Q 10 ,
2553 for example).
2554 When using \fInumeric\fP, names containing non-digits sort after all
2555 the all-digit names and are sorted by name using the traditional behavior.
2556 .IP
2557 A sort specifier of \fInosort\fP disables sorting completely;
2558 .B bash
2559 returns the results
2560 in the order they are read from the file system,
2561 ignoring any leading \fI\-\fP.
2562 .IP
2563 If the sort specifier is missing, it defaults to \fIname\fP,
2564 so a value of \fI+\fP is equivalent to the null string,
2565 and a value of \fI-\fP sorts by name in descending order.
2566 Any invalid value restores the historical sorting behavior.
2567 .PD 0
2568 .TP
2569 .B HISTCONTROL
2570 A colon-separated list of values controlling how commands are saved on
2571 the history list.
2572 If the list of values includes
2573 .IR ignorespace ,
2574 lines which begin with a
2575 .B space
2576 character are not saved in the history list.
2577 A value of
2578 .I ignoredups
2579 causes lines matching the previous history entry not to be saved.
2580 A value of
2581 .I ignoreboth
2582 is shorthand for \fIignorespace\fP and \fIignoredups\fP.
2583 A value of
2584 .I erasedups
2585 causes all previous lines matching the current line to be removed from
2586 the history list before that line is saved.
2587 Any value not in the above list is ignored.
2588 If
2589 .SM
2590 .B HISTCONTROL
2591 is unset, or does not include a valid value,
2592 \fBbash\fP saves all lines read by the shell parser on the history list,
2593 subject to the value of
2594 .SM
2595 .BR HISTIGNORE .
2596 If the first line of a multi-line compound command was saved,
2597 the second and subsequent lines are not tested,
2598 and are added to the history regardless of the value of
2599 .SM
2600 .BR HISTCONTROL .
2601 If the first line was not saved, the second and subsequent lines of
2602 the command are not saved either.
2603 .TP
2604 .B HISTFILE
2605 The name of the file in which command history is saved (see
2606 .SM
2607 .B HISTORY
2608 below).
2609 \fBBash\fP assigns a default value of
2610 .FN \*~/.bash_history .
2611 If
2612 .SM
2613 .B HISTFILE
2614 is unset or null,
2615 the shell does not save the command history when it exits.
2616 .TP
2617 .B HISTFILESIZE
2618 The maximum number of lines contained in the history file.
2619 When this variable is assigned a value, the history file is truncated,
2620 if necessary, to contain no more than
2621 the number of history entries
2622 that total no more than that number of lines
2623 by removing the oldest entries.
2624 If the history list contains multi-line entries,
2625 the history file may contain more lines than this maximum
2626 to avoid leaving partial history entries.
2627 The history file is also truncated to this size after
2628 writing it when a shell exits or by the
2629 .B \%history
2630 builtin.
2631 If the value is 0, the history file is truncated to zero size.
2632 Non-numeric values and numeric values less than zero inhibit truncation.
2633 The shell sets the default value to the value of
2634 .SM
2635 .B HISTSIZE
2636 after reading any startup files.
2637 .TP
2638 .B HISTIGNORE
2639 A colon-separated list of patterns used to decide which command lines
2640 should be saved on the history list.
2641 If a command line matches one of the patterns in the value of
2642 .SM
2643 .BR HISTIGNORE ,
2644 it is not saved on the history list.
2645 Each pattern is anchored at the
2646 beginning of the line and must match the complete line
2647 (\fBbash\fP does not implicitly append a
2648 .Q \fB*\fP ).
2649 Each pattern is tested against the line
2650 after the checks specified by
2651 .SM
2652 .B HISTCONTROL
2653 are applied.
2654 In addition to the normal shell pattern matching characters,
2655 .Q \fB&\fP
2656 matches the previous history line.
2657 A backslash escapes the
2658 .Q \fB&\fP ;
2659 the backslash is removed before attempting a match.
2660 If the first line of a multi-line compound command was saved,
2661 the second and subsequent lines are not tested,
2662 and are added to the history regardless of the value of
2663 .SM
2664 .BR HISTIGNORE .
2665 If the first line was not saved, the second and subsequent lines of
2666 the command are not saved either.
2667 The pattern matching honors the setting of the
2668 .B \%extglob
2669 shell option.
2670 .IP
2671 .SM
2672 .B HISTIGNORE
2673 subsumes some of the function of
2674 .SM
2675 .BR HISTCONTROL .
2676 A pattern of
2677 .Q &
2678 is identical to
2679 .Q \%ignoredups ,
2680 and a pattern of
2681 .Q "[ ]*"
2682 is identical to
2683 .Q \%ignorespace .
2684 Combining these two patterns, separating them with a colon,
2685 provides the functionality of
2686 .Q \%ignoreboth .
2687 .TP
2688 .B HISTSIZE
2689 The number of commands to remember in the command history (see
2690 .SM
2691 .B HISTORY
2692 below).
2693 If the value is 0, commands are not saved in the history list.
2694 Numeric values less than zero result in every command being saved
2695 on the history list (there is no limit).
2696 The shell sets the default value to 500 after reading any startup files.
2697 .TP
2698 .B HISTTIMEFORMAT
2699 If this variable is set and not null, its value is used as a format string
2700 for
2701 .IR strftime (3)
2702 to print the time stamp associated with each history
2703 entry displayed by the \fBhistory\fP builtin.
2704 If this variable is set, the shell writes time stamps to the history file so
2705 they may be preserved across shell sessions.
2706 This uses the history comment character to distinguish timestamps from
2707 other history lines.
2708 .TP
2709 .B HOME
2710 The home directory of the current user; the default argument for the
2711 \fBcd\fP builtin command.
2712 The value of this variable is also used when performing tilde expansion.
2713 .TP
2714 .B HOSTFILE
2715 Contains the name of a file in the same format as
2716 .FN /etc/hosts
2717 that should be read when the shell needs to complete a
2718 hostname.
2719 The list of possible hostname completions may be changed while the
2720 shell is running;
2721 the next time hostname completion is attempted after the
2722 value is changed,
2723 .B bash
2724 adds the contents of the new file to the existing list.
2725 If
2726 .SM
2727 .B HOSTFILE
2728 is set, but has no value, or does not name a readable file,
2729 \fBbash\fP attempts to read
2730 .FN /etc/hosts
2731 to obtain the list of possible hostname completions.
2732 When
2733 .SM
2734 .B HOSTFILE
2735 is unset, \fBbash\fP clears the hostname list.
2736 .TP
2737 .B IFS
2738 The
2739 .I Internal Field Separator
2740 that is used
2741 for word splitting after expansion and to
2742 split lines into words with the
2743 .B read
2744 builtin command.
2745 Word splitting is described below under
2746 .SM
2747 .BR EXPANSION .
2748 The default value is
2749 .Q <space><tab><newline> .
2750 .TP
2751 .B IGNOREEOF
2752 Controls the
2753 action of an interactive shell on receipt of an
2754 .SM
2755 .B EOF
2756 character as the sole input.
2757 If set, the value is the number of consecutive
2758 .SM
2759 .B EOF
2760 characters which must be
2761 typed as the first characters on an input line before
2762 .B bash
2763 exits.
2764 If the variable is set but does not have a numeric value,
2765 or the value is null,
2766 the default value is 10.
2767 If it is unset,
2768 .SM
2769 .B EOF
2770 signifies the end of input to the shell.
2771 .TP
2772 .B INPUTRC
2773 The filename for the
2774 .B readline
2775 startup file, overriding the default of
2776 .FN \*~/.inputrc
2777 (see
2778 .SM
2779 .B READLINE
2780 below).
2781 .TP
2782 .B INSIDE_EMACS
2783 If this variable appears in the environment when the shell starts,
2784 \fBbash\fP assumes that it is running inside an Emacs shell buffer
2785 and may disable line editing, depending on the value of
2786 .SM
2787 .BR TERM .
2788 .TP
2789 .B LANG
2790 Used to determine the locale category for any category not specifically
2791 selected with a variable starting with \fBLC_\fP.
2792 .TP
2793 .B LC_ALL
2794 This variable overrides the value of
2795 .SM
2796 .B LANG
2797 and any other
2798 \fBLC_\fP variable specifying a locale category.
2799 .TP
2800 .B LC_COLLATE
2801 This variable determines the collation order used when sorting the
2802 results of pathname expansion, and determines the behavior of range
2803 expressions, equivalence classes, and collating sequences within
2804 pathname expansion and pattern matching.
2805 .TP
2806 .B LC_CTYPE
2807 This variable determines the interpretation of characters and the
2808 behavior of character classes within pathname expansion and pattern
2809 matching.
2810 .TP
2811 .B LC_MESSAGES
2812 This variable determines the locale used to translate double-quoted
2813 strings preceded by a \fB$\fP.
2814 .TP
2815 .B LC_NUMERIC
2816 This variable determines the locale category used for number formatting.
2817 .TP
2818 .B LC_TIME
2819 This variable determines the locale category used for data and time
2820 formatting.
2821 .TP
2822 .B LINES
2823 Used by the \fBselect\fP compound command to determine the column length
2824 for printing selection lists.
2825 Automatically set if the
2826 .B checkwinsize
2827 option is enabled or in an interactive shell upon receipt of a
2828 .SM
2829 .BR SIGWINCH .
2830 .TP
2831 .B MAIL
2832 If the value is set to a file or directory name and the
2833 .SM
2834 .B MAILPATH
2835 variable is not set,
2836 .B bash
2837 informs the user of the arrival of mail in the specified file or
2838 Maildir-format directory.
2839 .TP
2840 .B MAILCHECK
2841 Specifies how
2842 often (in seconds)
2843 .B bash
2844 checks for mail.
2845 The default is 60 seconds.
2846 When it is time to check for mail,
2847 the shell does so before displaying the primary prompt.
2848 If this variable is unset, or set to a value that is not a number
2849 greater than or equal to zero, the shell disables mail checking.
2850 .TP
2851 .B MAILPATH
2852 A colon-separated list of filenames to be checked for mail.
2853 The message to be printed when mail arrives in a particular file
2854 may be specified by separating the filename from the message with a
2855 .Q ? .
2856 When used in the text of the message, \fB$_\fP expands to the name of
2857 the current mailfile.
2858 For example:
2859 .RS
2860 .PP
2861 .EX
2862 \fBMAILPATH\fP=\*'/var/mail/bfox?\*"You have mail\*":\*~/shell\-mail?\*"$_ has mail!\*"\*'
2863 .EE
2864 .PP
2865 .B Bash
2866 can be configured to supply
2867 a default value for this variable (there is no value by default),
2868 but the location of the user
2869 mail files that it uses is system dependent (e.g., /var/mail/\fB$USER\fP).
2870 .RE
2871 .TP
2872 .B OPTERR
2873 If set to the value 1,
2874 .B bash
2875 displays error messages generated by the
2876 .B getopts
2877 builtin command (see
2878 .SM
2879 .B "SHELL BUILTIN COMMANDS"
2880 below).
2881 .SM
2882 .B OPTERR
2883 is initialized to 1 each time the shell is invoked or a shell
2884 script is executed.
2885 .TP
2886 .B PATH
2887 The search path for commands.
2888 It is a colon-separated list of directories in which
2889 the shell looks for commands (see
2890 .SM
2891 .B "COMMAND EXECUTION"
2892 below).
2893 A zero-length (null) directory name in the value of
2894 .SM
2895 .B PATH
2896 indicates the current directory.
2897 A null directory name may appear as two adjacent colons, or as an initial
2898 or trailing colon.
2899 The default path is system-dependent,
2900 and is set by the administrator who installs
2901 .BR bash .
2902 A common value is
2903 .RS
2904 .RS 5n
2905 .EX
2906 /usr/local/bin:/usr/local/sbin:\c
2907 .if \n(LL<78n .br
2908 /usr/bin:/usr/sbin:/bin:/sbin
2909 .EE
2910 .RE
2911 .RE
2912 .TP
2913 .B POSIXLY_CORRECT
2914 If this variable is in the environment when \fBbash\fP starts, the shell
2915 enters posix mode before reading the startup files, as if the
2916 .B \-\-posix
2917 invocation option had been supplied.
2918 If it is set while the shell is
2919 running, \fBbash\fP enables posix mode, as if the command
2920 .Q "set \-o posix"
2921 had been executed.
2922 When the shell enters posix mode, it sets this variable if it was
2923 not already set.
2924 .TP
2925 .B PROMPT_COMMAND
2926 If this variable is set, and is an array,
2927 the value of each set element is executed as a command
2928 prior to issuing each primary prompt.
2929 If this is set but not an array variable,
2930 its value is used as a command to execute instead.
2931 .TP
2932 .B PROMPT_DIRTRIM
2933 If set to a number greater than zero, the value is used as the number of
2934 trailing directory components to retain when expanding the \fB\ew\fP and
2935 \fB\eW\fP prompt string escapes (see
2936 .SM
2937 .B PROMPTING
2938 below).
2939 Characters removed are replaced with an ellipsis.
2940 .TP
2941 .B PS0
2942 The value of this parameter is expanded (see
2943 .SM
2944 .B PROMPTING
2945 below) and displayed by interactive shells after reading a command
2946 and before the command is executed.
2947 .TP
2948 .B PS1
2949 The value of this parameter is expanded (see
2950 .SM
2951 .B PROMPTING
2952 below) and used as the primary prompt string.
2953 The default value is
2954 .Q \es\-\ev\e$\ .
2955 .TP
2956 .B PS2
2957 The value of this parameter is expanded as with
2958 .SM
2959 .B PS1
2960 and used as the secondary prompt string.
2961 The default is
2962 .Q >\ .
2963 .TP
2964 .B PS3
2965 The value of this parameter is used as the prompt for the
2966 .B select
2967 command (see
2968 .SM
2969 .B "SHELL GRAMMAR"
2970 above).
2971 .TP
2972 .B PS4
2973 The value of this parameter is expanded as with
2974 .SM
2975 .B PS1
2976 and the value is printed before each command
2977 .B bash
2978 displays during an execution trace.
2979 The first character of the expanded value of
2980 .SM
2981 .B PS4
2982 is replicated multiple times, as necessary, to indicate multiple
2983 levels of indirection.
2984 The default is
2985 .Q +\ .
2986 .TP
2987 .B SHELL
2988 This variable expands to the full pathname to the shell.
2989 If it is not set when the shell starts,
2990 .B bash
2991 assigns to it the full pathname of the current user's login shell.
2992 .TP
2993 .B TIMEFORMAT
2994 The value of this parameter is used as a format string specifying
2995 how the timing information for pipelines prefixed with the
2996 .B time
2997 reserved word should be displayed.
2998 The \fB%\fP character introduces an escape sequence that is
2999 expanded to a time value or other information.
3000 The escape sequences and their meanings are as follows; the
3001 brackets denote optional portions.
3002 .PP
3003 .RS
3004 .PD 0
3005 .TP 10
3006 .B %%
3007 A literal \fB%\fP.
3008 .TP
3009 .B %[\fIp\fP][l]R
3010 The elapsed time in seconds.
3011 .TP
3012 .B %[\fIp\fP][l]U
3013 The number of CPU seconds spent in user mode.
3014 .TP
3015 .B %[\fIp\fP][l]S
3016 The number of CPU seconds spent in system mode.
3017 .TP
3018 .B %P
3019 The CPU percentage, computed as (%U + %S) / %R.
3020 .PD
3021 .RE
3022 .IP
3023 The optional \fIp\fP is a digit specifying the \fIprecision\fP,
3024 the number of fractional digits after a decimal point.
3025 A value of 0 causes no decimal point or fraction to be output.
3026 \fBtime\fP prints at most six digits after the decimal point;
3027 values of \fIp\fP greater than 6 are changed to 6.
3028 If \fIp\fP is not specified,
3029 \fBtime\fP prints three digits after the decimal point.
3030 .IP
3031 The optional \fBl\fP specifies a longer format, including
3032 minutes, of the form \fIMM\fPm\fISS\fP.\fIFF\fPs.
3033 The value of \fIp\fP determines whether or not the fraction is
3034 included.
3035 .IP
3036 If this variable is not set, \fBbash\fP acts as if it had the
3037 value \fB$\*'\enreal\et%3lR\enuser\et%3lU\ensys\et%3lS\*'\fP.
3038 If the value is null, \fBbash\fP does not display any timing information.
3039 A trailing newline is added when the format string is displayed.
3040 .PD 0
3041 .TP
3042 .B TMOUT
3043 If set to a value greater than zero,
3044 the \fBread\fP builtin uses the value as its
3045 default timeout.
3046 The \fBselect\fP command terminates if input does not arrive
3047 after
3048 .SM
3049 .B TMOUT
3050 seconds when input is coming from a terminal.
3051 In an interactive shell, the value is interpreted as the
3052 number of seconds to wait for a line of input after issuing the
3053 primary prompt.
3054 .B Bash
3055 terminates after waiting for that number of seconds if a
3056 complete line of input does not arrive.
3057 .TP
3058 .B TMPDIR
3059 If set, \fBbash\fP uses its value as the name of a directory in which
3060 \fBbash\fP creates temporary files for the shell's use.
3061 .TP
3062 .B auto_resume
3063 This variable controls how the shell interacts with the user and
3064 job control.
3065 If this variable is set, simple commands
3066 consisting of only a single word,
3067 without redirections, are treated as candidates for resumption
3068 of an existing stopped job.
3069 There is no ambiguity allowed; if there is more than one job
3070 beginning with or containing
3071 the word, this selects the most recently accessed job.
3072 The
3073 .I name
3074 of a stopped job, in this context, is the command line used to
3075 start it, as displayed by \fBjobs\fP.
3076 If set to the value
3077 .IR exact ,
3078 the word must match the name of a stopped job exactly;
3079 if set to
3080 .IR substring ,
3081 the word needs to match a substring of the name of a stopped job.
3082 The
3083 .I substring
3084 value provides functionality analogous to the
3085 .B %?
3086 job identifier (see
3087 .SM
3088 .B "JOB CONTROL"
3089 below).
3090 If set to any other value (e.g.,
3091 .IR prefix ),
3092 the word must be a prefix of a stopped job's name;
3093 this provides functionality analogous to the \fB%\fP\fIstring\fP job identifier.
3094 .TP
3095 .B histchars
3096 The two or three characters which control history expansion,
3097 quick substitution, and tokenization
3098 (see
3099 .SM
3100 .B "HISTORY EXPANSION"
3101 below).
3102 The first character is the \fIhistory expansion\fP character,
3103 the character which begins a history expansion, normally
3104 .Q \fB!\fP .
3105 The second character is the \fIquick substitution\fP character, normally
3106 .Q \fB\*^\fP .
3107 When it appears as the first character on the line,
3108 history substitution repeats the previous command,
3109 replacing one string with another.
3110 The optional third character is the
3111 \fIhistory comment\fP
3112 character, normally
3113 .Q \fB#\fP ,
3114 which indicates
3115 that the remainder of the line is a comment
3116 when it appears as the first character of a word.
3117 The history comment character disables history substitution
3118 for the remaining words on the line.
3119 It does not necessarily cause the shell parser to treat the rest of the
3120 line as a comment.
3121 .PD
3122 .SS Arrays
3123 .B Bash
3124 provides one-dimensional indexed and associative array variables.
3125 Any variable may be used as an indexed array; the
3126 .B declare
3127 builtin explicitly declares an array.
3128 There is no maximum
3129 limit on the size of an array, nor any requirement that members
3130 be indexed or assigned contiguously.
3131 Indexed arrays are referenced using arithmetic expressions
3132 that must expand to an integer
3133 (see
3134 .SM
3135 .B
3136 ARITHMETIC EVALUATION
3137 below)
3138 and are zero-based;
3139 associative arrays are referenced using arbitrary strings.
3140 Unless otherwise noted, indexed array indices must be non-negative integers.
3141 .PP
3142 The shell performs
3143 parameter and variable expansion, arithmetic expansion,
3144 command substitution, and quote removal
3145 on indexed array subscripts.
3146 Since this
3147 can potentially result in empty strings,
3148 subscript indexing treats
3149 those as expressions that evaluate to 0.
3150 .PP
3151 The shell performs
3152 tilde expansion,
3153 parameter and variable expansion, arithmetic expansion,
3154 command substitution, and quote removal
3155 on associative array subscripts.
3156 Empty strings cannot be used as associative array keys.
3157 .PP
3158 \fBBash\fP automatically creates an indexed array
3159 if any variable is assigned to using the syntax
3160 .RS
3161 \fIname\fP[\fIsubscript\fP]=\fIvalue\fP
3162 \&.
3163 .RE
3164 The
3165 .I subscript
3166 is treated as an arithmetic expression that must evaluate to a number
3167 greater than or equal to zero.
3168 To explicitly declare an indexed array, use
3169 .RS
3170 .BI "declare \-a\ " name
3171 .RE
3172 (see
3173 .SM
3174 .B "SHELL BUILTIN COMMANDS"
3175 below).
3176 .RS
3177 \fBdeclare \-a\fP \fIname\fP[\fIsubscript\fP]
3178 .RE
3179 is also accepted; the \fIsubscript\fP is ignored.
3180 .PP
3181 Associative arrays are created using
3182 .RS
3183 .BI "declare \-A\ " name
3184 .RE
3185 \&.
3186 .PP
3187 Attributes may be specified for an array variable using the
3188 .B \%declare
3189 and
3190 .B \%readonly
3191 builtins.
3192 Each attribute applies to all members of an array.
3193 .PP
3194 Arrays are assigned using compound assignments of the form
3195 \fIname\fP=\fB(\fPvalue\fI1\fP .\|.\|.\& value\fIn\fP\fB)\fP, where each
3196 \fIvalue\fP may be of the form [\fIsubscript\fP]=\fIstring\fP.
3197 Indexed array assignments do not require anything but \fIstring\fP.
3198 Each \fIvalue\fP in the list is expanded using the shell expansions
3199 described below under
3200 .SM
3201 .BR EXPANSION ,
3202 but \fIvalue\fPs that are valid variable assignments
3203 including the brackets and subscript do not undergo
3204 brace expansion and word splitting, as with individual
3205 variable assignments.
3206 .PP
3207 When assigning to indexed arrays, if the optional brackets and subscript
3208 are supplied, that index is assigned to;
3209 otherwise the index of the element assigned is the last index assigned
3210 to by the statement plus one.
3211 Indexing starts at zero.
3212 .PP
3213 When assigning to an associative array, the words in a compound assignment
3214 may be either assignment statements, for which the subscript is required,
3215 or a list of words that is interpreted as a sequence of alternating keys
3216 and values:
3217 \fIname\fP=\fB( \fP\fIkey1 value1 key2 value2\fP .\|.\|.\&\fB)\fP.
3218 These are treated identically to
3219 \fIname\fP=\fB(\fP [\fIkey1\fP]=\fIvalue1\fP [\fIkey2\fP]=\fIvalue2\fP
3220 \&.\|.\|.\&\fB)\fP.
3221 The first word in the list determines how the remaining words
3222 are interpreted; all assignments in a list must be of the same type.
3223 When using key/value pairs, the keys may not be missing or empty;
3224 a final missing value is treated like the empty string.
3225 .PP
3226 This syntax is also accepted by the
3227 .B declare
3228 builtin.
3229 Individual array elements may be assigned to using the
3230 \fIname\fP[\fIsubscript\fP]=\fIvalue\fP syntax introduced above.
3231 .PP
3232 When assigning to an indexed array, if
3233 .I name
3234 is subscripted by a negative number, that number is
3235 interpreted as relative to one greater than the maximum index of
3236 \fIname\fP, so negative indices count back from the end of the
3237 array, and an index of \-1 references the last element.
3238 .PP
3239 The
3240 .Q +=
3241 operator appends to an array variable when assigning
3242 using the compound assignment syntax; see
3243 .SM
3244 .B PARAMETERS
3245 above.
3246 .PP
3247 An array element is referenced using
3248 ${\fIname\fP[\fIsubscript\fP]}.
3249 The braces are required to avoid conflicts with pathname expansion.
3250 If \fIsubscript\fP is \fB@\fP or \fB*\fP, the word expands to
3251 all members of \fIname\fP,
3252 unless noted in the description of a builtin or word expansion.
3253 These subscripts differ only when the
3254 word appears within double quotes.
3255 If the word is double-quoted, ${\fIname\fP[*]} expands to a single
3256 word with the value of each array member separated by the first
3257 character of the
3258 .SM
3259 .B IFS
3260 special variable, and ${\fIname\fP[@]} expands each element of
3261 \fIname\fP to a separate word.
3262 When there are no array members, ${\fIname\fP[@]} expands to nothing.
3263 If the double-quoted expansion occurs within a word, the expansion of
3264 the first parameter is joined with the beginning part of the
3265 expansion of the original word,
3266 and the expansion of the last parameter is joined with the last
3267 part of the
3268 expansion of the original word.
3269 This is analogous to the expansion
3270 of the special parameters \fB*\fP and \fB@\fP (see
3271 .B "Special Parameters"
3272 above).
3273 .PP
3274 ${#\fIname\fP[\fIsubscript\fP]} expands to the length of
3275 ${\fIname\fP[\fIsubscript\fP]}.
3276 If \fIsubscript\fP is \fB*\fP or \fB@\fP,
3277 the expansion is the number of elements in the array.
3278 .PP
3279 If the
3280 .I subscript
3281 used to reference an element of an indexed array
3282 evaluates to a number less than zero, it is
3283 interpreted as relative to one greater than the maximum index of the array,
3284 so negative indices count back from the end of the
3285 array, and an index of \-1 references the last element.
3286 .PP
3287 Referencing an array variable without a subscript is equivalent to
3288 referencing the array with a subscript of 0.
3289 Any reference to a variable using a valid subscript is valid;
3290 .B bash
3291 creates an array if necessary.
3292 .PP
3293 An array variable is considered set if a subscript has been assigned a
3294 value.
3295 The null string is a valid value.
3296 .PP
3297 It is possible to obtain the keys (indices) of an array as well as the values.
3298 ${\fB!\fP\fIname\fP[\fI@\fP]} and ${\fB!\fP\fIname\fP[\fI*\fP]}
3299 expand to the indices assigned in array variable \fIname\fP.
3300 The treatment when in double quotes is similar to the expansion of the
3301 special parameters \fI@\fP and \fI*\fP within double quotes.
3302 .PP
3303 The
3304 .B unset
3305 builtin is used to destroy arrays.
3306 \fBunset\fP \fIname\fP[\fIsubscript\fP]
3307 unsets the array element at index \fIsubscript\fP,
3308 for both indexed and associative arrays.
3309 Negative subscripts to indexed arrays are interpreted as described above.
3310 Unsetting the last element of an array variable does not unset the variable.
3311 \fBunset\fP \fIname\fP, where \fIname\fP is an array,
3312 removes the entire array.
3313 \fBunset\fP \fIname\fP[\fIsubscript\fP]
3314 behaves differently depending on
3315 whether \fIname\fP is an indexed or associative array
3316 when \fIsubscript\fP is \fB*\fP or \fB@\fP.
3317 If \fIname\fP is an associative array, this unsets the element with
3318 subscript \fB*\fP or \fB@\fP.
3319 If \fIname\fP is an indexed array, unset removes all of the elements but
3320 does not remove the array itself.
3321 .PP
3322 When using a variable name with a subscript as an argument to a command,
3323 such as with \fBunset\fP, without using the word expansion syntax
3324 described above,
3325 (e.g., unset a[4]),
3326 the argument is subject to pathname expansion.
3327 Quote the argument if pathname expansion is not desired
3328 (e.g., unset \*'a[4]\*').
3329 .PP
3330 The
3331 .BR declare ,
3332 .BR local ,
3333 and
3334 .B readonly
3335 builtins each accept a
3336 .B \-a
3337 option to specify an indexed array and a
3338 .B \-A
3339 option to specify an associative array.
3340 If both options are supplied,
3341 .B \-A
3342 takes precedence.
3343 The
3344 .B read
3345 builtin accepts a
3346 .B \-a
3347 option to assign a list of words read from the standard input
3348 to an array.
3349 The
3350 .B set
3351 and
3352 .B declare
3353 builtins display array values in a way that allows them to be
3354 reused as assignments.
3355 Other builtins accept array name arguments as well
3356 (e.g., \fBmapfile\fP); see the descriptions
3357 of individual builtins below for details.
3358 The shell provides a number of builtin array variables.
3359 .SH EXPANSION
3360 Expansion is performed on the command line after it has been split into
3361 words. The shell performs these expansions:
3362 .IR "brace expansion" ,
3363 .IR "tilde expansion" ,
3364 .IR "parameter and variable expansion" ,
3365 .IR "command substitution" ,
3366 .IR "arithmetic expansion" ,
3367 .IR "word splitting" ,
3368 .IR "pathname expansion" ,
3369 and
3370 .IR "quote removal" .
3371 .PP
3372 The order of expansions is:
3373 brace expansion;
3374 tilde expansion, parameter and variable expansion, arithmetic expansion,
3375 and command substitution (done in a left-to-right fashion);
3376 word splitting;
3377 pathname expansion;
3378 and quote removal.
3379 .PP
3380 On systems that can support it, there is an additional expansion
3381 available: \fIprocess substitution\fP.
3382 This is performed at the
3383 same time as tilde, parameter, variable, and arithmetic expansion and
3384 command substitution.
3385 .PP
3386 \fIQuote removal\fP is always performed last.
3387 It removes quote characters present in the original word,
3388 not ones resulting from one of the other expansions,
3389 unless they have been quoted themselves.
3390 .PP
3391 Only brace expansion, word splitting, and pathname expansion
3392 can increase the number of words of the expansion; other expansions
3393 expand a single word to a single word.
3394 The only exceptions to this are the expansions of
3395 .B \&\*"$@\*"
3396 and
3397 .B \&\*"${\fIname\fP[@]}\*"\c \" keep leading \& for AT&T troff
3398 .BR \& , \" .BR + \& + \*" doesn't work with AT&T troff
3399 and, in most cases, \fB$*\fP and \fB${\fP\fIname\fP\fB[*]}\fP
3400 as explained above (see
3401 .SM
3402 .BR PARAMETERS ).
3403 .SS Brace Expansion
3404 .I "Brace expansion"
3405 is a mechanism to generate arbitrary strings
3406 sharing a common prefix and suffix, either of which can be empty.
3407 This mechanism is similar to
3408 \fIpathname expansion\fP, but the filenames generated
3409 need not exist.
3410 Patterns to be brace expanded are formed from an optional
3411 .IR preamble ,
3412 followed by either a series of comma-separated strings or
3413 a sequence expression between a pair of braces,
3414 followed by an optional
3415 .IR postscript .
3416 The preamble is prefixed to each string contained within the braces,
3417 and the postscript is then appended to each resulting string,
3418 expanding left to right.
3419 .PP
3420 Brace expansions may be nested.
3421 The results of each expanded string are not sorted;
3422 brace expansion preserves left to right order.
3423 For example, a\fB{\fPd,c,b\fB}\fPe expands into
3424 .Q "ade ace abe" .
3425 .PP
3426 A sequence expression takes the form
3427 \fIx\fP\fB..\fP\fIy\fP\fB[..\fP\fIincr\fP\fB]\fP,
3428 where \fIx\fP and \fIy\fP are either integers or single letters,
3429 and \fIincr\fP, an optional increment, is an integer.
3430 When integers are supplied, the expression expands to each number between
3431 \fIx\fP and \fIy\fP, inclusive.
3432 If either \fIx\fP or \fIy\fP begins with a zero,
3433 each generated term will contain the same number of digits,
3434 zero-padding where necessary.
3435 When letters are supplied, the expression expands to each character
3436 lexicographically between \fIx\fP and \fIy\fP, inclusive,
3437 using the C locale.
3438 Note that both \fIx\fP and \fIy\fP must be of the same type
3439 (integer or letter).
3440 When the increment is supplied, it is used as the difference between
3441 each term.
3442 The default increment is 1 or \-1 as appropriate.
3443 .PP
3444 Brace expansion is performed before any other expansions,
3445 and any characters special to other expansions are preserved
3446 in the result.
3447 It is strictly textual.
3448 .B Bash
3449 does not apply any syntactic interpretation to the context of the
3450 expansion or the text between the braces.
3451 .PP
3452 A correctly-formed brace expansion must contain unquoted opening
3453 and closing braces, and at least one unquoted comma or a valid
3454 sequence expression.
3455 Any incorrectly formed brace expansion is left unchanged.
3456 .PP
3457 A
3458 .Q {
3459 or
3460 Q ,
3461 may be quoted with a backslash to prevent its
3462 being considered part of a brace expression.
3463 To avoid conflicts with parameter expansion, the string
3464 .Q ${
3465 is not considered eligible for brace expansion,
3466 and inhibits brace expansion until the closing
3467 .Q } .
3468 .PP
3469 This construct is typically used as shorthand when the common
3470 prefix of the strings to be generated is longer than in the
3471 above example:
3472 .PP
3473 .RS
3474 .EX
3475 mkdir /usr/local/src/bash/{old,new,dist,bugs}
3476 .EE
3477 .RE
3478 or
3479 .RS
3480 .EX
3481 chown root /usr/{ucb/{ex,edit},lib/{ex?.?*,how_ex}}
3482 .EE
3483 .RE
3484 .PP
3485 Brace expansion introduces a slight incompatibility with
3486 historical versions of
3487 .BR sh .
3488 .B sh
3489 does not treat opening or closing braces specially when they
3490 appear as part of a word, and preserves them in the output.
3491 .B Bash
3492 removes braces from words as a consequence of brace expansion.
3493 For example, a word entered to
3494 .B sh
3495 as
3496 .Q file{1,2}
3497 appears identically in the output.
3498 .B Bash
3499 outputs that word as
3500 .Q "file1 file2"
3501 after brace expansion.
3502 Start
3503 .B bash
3504 with the
3505 .B +B
3506 option or disable brace expansion with the
3507 .B +B
3508 option to the
3509 .B set
3510 command (see
3511 .SM
3512 .B "SHELL BUILTIN COMMANDS"
3513 below) for strict \fBsh\fP compatibility.
3514 .SS Tilde Expansion
3515 If a word begins with an unquoted tilde character (\c
3516 .Q \fB\*~\fP ),
3517 all of
3518 the characters preceding the first unquoted slash (or all characters,
3519 if there is no unquoted slash) are considered a \fItilde-prefix\fP.
3520 If none of the characters in the tilde-prefix are quoted, the
3521 characters in the tilde-prefix following the tilde are treated as a
3522 possible \fIlogin name\fP.
3523 If this login name is the null string, the tilde is replaced with the
3524 value of the shell parameter
3525 .SM
3526 .BR HOME .
3527 If
3528 .SM
3529 .B HOME
3530 is unset, the tilde expands to
3531 the home directory of the user executing the shell instead.
3532 Otherwise, the tilde-prefix is replaced with the home directory
3533 associated with the specified login name.
3534 .PP
3535 If the tilde-prefix is a
3536 .Q \*~+ ,
3537 the value of the shell variable
3538 .SM
3539 .B PWD
3540 replaces the tilde-prefix.
3541 If the tilde-prefix is a
3542 .Q \*~\- ,
3543 the shell substitutes the value of the shell variable
3544 .SM
3545 .BR OLDPWD ,
3546 if it is set.
3547 If the characters following the tilde in the tilde-prefix consist
3548 of a number \fIN\fP, optionally prefixed
3549 by a
3550 .Q +
3551 or a
3552 .Q \- ,
3553 the tilde-prefix is replaced with the corresponding
3554 element from the directory stack, as it would be displayed by the
3555 .B dirs
3556 builtin invoked with the characters following the tilde in the
3557 tilde-prefix as an argument.
3558 If the characters following the tilde in the tilde-prefix consist of a
3559 number without a leading
3560 .Q +
3561 or
3562 .Q \- ,
3563 tilde expansion assumes
3564 .Q + .
3565 .PP
3566 The results of tilde expansion are treated as if they were quoted, so
3567 the replacement is not subject to word splitting and pathname expansion.
3568 .PP
3569 If the login name is invalid, or the tilde expansion fails, the
3570 tilde-prefix is unchanged.
3571 .PP
3572 \fBBash\fP checks each variable assignment
3573 for unquoted tilde-prefixes immediately
3574 following a
3575 .B :
3576 or the first
3577 .BR = ,
3578 and performs tilde expansion in these cases.
3579 Consequently, one may use filenames with tildes in assignments to
3580 .SM
3581 .BR PATH ,
3582 .SM
3583 .BR MAILPATH ,
3584 and
3585 .SM
3586 .BR CDPATH ,
3587 and the shell assigns the expanded value.
3588 .PP
3589 \fBBash\fP also performs tilde expansion on words satisfying the conditions
3590 of variable assignments (as described above under
3591 .SM
3592 .BR PARAMETERS )
3593 when they appear as arguments to simple commands.
3594 \fBBash\fP does not do this,
3595 except for the \fIdeclaration\fP commands listed above,
3596 when in posix mode.
3597 .SS Parameter Expansion
3598 The
3599 .Q \fB$\fP
3600 character introduces parameter expansion,
3601 command substitution, or arithmetic expansion.
3602 The parameter name
3603 or symbol to be expanded may be enclosed in braces, which
3604 are optional but serve to protect the variable to be expanded from
3605 characters immediately following it which could be
3606 interpreted as part of the name.
3607 .PP
3608 When braces are used, the matching ending brace is the first
3609 .Q \fB}\fP
3610 not escaped by a backslash or within a quoted string, and not within an
3611 embedded arithmetic expansion, command substitution, or parameter
3612 expansion.
3613 .PP
3614 The basic form of parameter expansion is
3615 .PP
3616 ${\fIparameter\fP}
3617 .LP
3618 which substitutes the value of \fIparameter\fP.
3619 The braces are required
3620 when
3621 .I parameter
3622 is a positional parameter with more than one digit,
3623 or when
3624 .I parameter
3625 is followed by a character which is not to be
3626 interpreted as part of its name.
3627 The \fIparameter\fP is a shell parameter as described above
3628 \fBPARAMETERS\fP) or an array reference (\fBArrays\fP).
3629 .PD
3630 .PP
3631 If the first character of \fIparameter\fP is an exclamation point (\fB!\fP),
3632 and \fIparameter\fP is not a \fInameref\fP,
3633 it introduces a level of indirection.
3634 \fBBash\fP uses the value formed by expanding the rest of
3635 \fIparameter\fP as the new \fIparameter\fP;
3636 this new parameter is then expanded and that value is used
3637 in the rest of the expansion, rather
3638 than the expansion of the original \fIparameter\fP.
3639 This is known as \fIindirect expansion\fP.
3640 The value is subject to tilde expansion,
3641 parameter expansion, command substitution, and arithmetic expansion.
3642 If \fIparameter\fP is a nameref, this expands to the name of the
3643 parameter referenced by \fIparameter\fP instead of performing the
3644 complete indirect expansion, for compatibility.
3645 The exceptions to this are the expansions of ${\fB!\fP\fIprefix\fP\fB*\fP} and
3646 ${\fB!\fP\fIname\fP[\fI@\fP]} described below.
3647 The exclamation point must immediately follow the left brace in order to
3648 introduce indirection.
3649 .PP
3650 In each of the cases below, \fIword\fP is subject to tilde expansion,
3651 parameter expansion, command substitution, and arithmetic expansion.
3652 .PP
3653 When not performing substring expansion, using the forms documented below
3654 (e.g., \fB:-\fP),
3655 \fBbash\fP tests for a parameter that is unset or null.
3656 Omitting the colon tests only for a parameter that is unset.
3657 .PP
3658 .TP
3659 ${\fIparameter\fP\fB:\-\fP\fIword\fP}
3660 \fBUse Default Values\fP. If
3661 .I parameter
3662 is unset or null, the expansion of
3663 .I word
3664 is substituted.
3665 Otherwise, the value of
3666 .I parameter
3667 is substituted.
3668 .TP
3669 ${\fIparameter\fP\fB:=\fP\fIword\fP}
3670 \fBAssign Default Values\fP.
3671 If
3672 .I parameter
3673 is unset or null, the expansion of
3674 .I word
3675 is assigned to
3676 .IR parameter ,
3677 and the expansion is the final value of
3678 .IR parameter .
3679 Positional parameters and special parameters may
3680 not be assigned in this way.
3681 .TP
3682 ${\fIparameter\fP\fB:?\fP\fIword\fP}
3683 \fBDisplay Error if Null or Unset\fP.
3684 If
3685 .I parameter
3686 is null or unset, the shell writes
3687 the expansion of \fIword\fP (or a message to that effect
3688 if
3689 .I word
3690 is not present) to the standard error and, if it
3691 is not interactive, exits with a non-zero status.
3692 An interactive shell does not exit, but does not execute the command
3693 associated with the expansion.
3694 Otherwise, the value of \fIparameter\fP is substituted.
3695 .TP
3696 ${\fIparameter\fP\fB:+\fP\fIword\fP}
3697 \fBUse Alternate Value\fP.
3698 If
3699 .I parameter
3700 is null or unset, nothing is substituted, otherwise the expansion of
3701 .I word
3702 is substituted.
3703 The value of \fIparameter\fP is not used.
3704 .TP
3705 .PD 0
3706 ${\fIparameter\fP\fB:\fP\fIoffset\fP}
3707 .TP
3708 .PD
3709 ${\fIparameter\fP\fB:\fP\fIoffset\fP\fB:\fP\fIlength\fP}
3710 \fBSubstring Expansion\fP.
3711 Expands to up to \fIlength\fP characters of the value of \fIparameter\fP
3712 starting at the character specified by \fIoffset\fP.
3713 If \fIparameter\fP is \fB@\fP or \fB*\fP, an indexed array subscripted by
3714 \fB@\fP or \fB*\fP, or an associative array name, the results differ as
3715 described below.
3716 If \fB:\fP\fIlength\fP is omitted (the first form above), this
3717 expands to the substring of the value of
3718 \fIparameter\fP starting at the character specified by \fIoffset\fP
3719 and extending to the end of the value.
3720 If \fIoffset\fP is omitted,
3721 it is treated as 0.
3722 If \fIlength\fP is omitted,
3723 but the colon after \fIoffset\fP is present,
3724 it is treated as 0.
3725 \fIlength\fP and \fIoffset\fP are arithmetic expressions (see
3726 .SM
3727 .B
3728 ARITHMETIC EVALUATION
3729 below).
3730 .IP
3731 If \fIoffset\fP evaluates to a number less than zero, the value
3732 is used as an offset in characters
3733 from the end of the value of \fIparameter\fP.
3734 If \fIlength\fP evaluates to a number less than zero,
3735 it is interpreted as an offset in characters
3736 from the end of the value of \fIparameter\fP rather than
3737 a number of characters, and the expansion is the characters between
3738 \fIoffset\fP and that result.
3739 Note that a negative offset must be separated from the colon by at least
3740 one space to avoid being confused with the \fB:-\fP expansion.
3741 .IP
3742 If \fIparameter\fP is \fB@\fP or \fB*\fP, the result is \fIlength\fP
3743 positional parameters beginning at \fIoffset\fP.
3744 A negative \fIoffset\fP is taken relative to one greater than the greatest
3745 positional parameter, so an offset of \-1 evaluates to the last positional
3746 parameter (or 0 if there are no positional parameters).
3747 It is an expansion error if \fIlength\fP evaluates to a number less than
3748 zero.
3749 .IP
3750 If \fIparameter\fP is an indexed array name subscripted by @ or *,
3751 the result is the \fIlength\fP
3752 members of the array beginning with ${\fIparameter\fP[\fIoffset\fP]}.
3753 A negative \fIoffset\fP is taken relative to one greater than the maximum
3754 index of the specified array.
3755 It is an expansion error if \fIlength\fP evaluates to a number less than
3756 zero.
3757 .IP
3758 Substring expansion applied to an associative array produces undefined
3759 results.
3760 .IP
3761 Substring indexing is zero-based unless the positional parameters
3762 are used, in which case the indexing starts at 1 by default.
3763 If \fIoffset\fP is 0, and the positional parameters are used, \fB$0\fP is
3764 prefixed to the list.
3765 .TP
3766 .PD 0
3767 ${\fB!\fP\fIprefix\fP\fB*\fP}
3768 .TP
3769 ${\fB!\fP\fIprefix\fP\fB@\fP}
3770 .PD
3771 \fBNames matching prefix\fP.
3772 Expands to the names of variables whose names begin with \fIprefix\fP,
3773 separated by the first character of the
3774 .SM
3775 .B IFS
3776 special variable.
3777 When \fI@\fP is used and the expansion appears within double quotes, each
3778 variable name expands to a separate word.
3779 .TP
3780 .PD 0
3781 ${\fB!\fP\fIname\fP[\fI@\fP]}
3782 .TP
3783 ${\fB!\fP\fIname\fP[\fI*\fP]}
3784 .PD
3785 \fBList of array keys\fP.
3786 If \fIname\fP is an array variable, expands to the list of array indices
3787 (keys) assigned in \fIname\fP.
3788 If \fIname\fP is not an array, expands to 0 if \fIname\fP is set and null
3789 otherwise.
3790 When \fI@\fP is used and the expansion appears within double quotes, each
3791 key expands to a separate word.
3792 .TP
3793 ${\fB#\fP\fIparameter\fP}
3794 \fBParameter length\fP.
3795 Substitutes the length in characters of the expanded value of \fIparameter\fP.
3796 If
3797 .I parameter
3798 is
3799 .B *
3800 or
3801 .BR @ ,
3802 the value substituted is the number of positional parameters.
3803 If
3804 .I parameter
3805 is an array name subscripted by
3806 .B *
3807 or
3808 .BR @ ,
3809 the value substituted is the number of elements in the array.
3810 If
3811 .I parameter
3812 is an indexed array name subscripted by a negative number, that number is
3813 interpreted as relative to one greater than the maximum index of
3814 \fIparameter\fP, so negative indices count back from the end of the
3815 array, and an index of \-1 references the last element.
3816 .TP
3817 .PD 0
3818 ${\fIparameter\fP\fB#\fP\fIword\fP}
3819 .TP
3820 ${\fIparameter\fP\fB##\fP\fIword\fP}
3821 .PD
3822 \fBRemove matching prefix pattern\fP.
3823 The
3824 .I word
3825 is expanded to produce a pattern just as in pathname
3826 expansion, and matched against the expanded value of
3827 .I parameter
3828 using the rules described under
3829 .B "Pattern Matching"
3830 below.
3831 If the pattern matches the beginning of
3832 the value of
3833 .IR parameter ,
3834 then the result of the expansion is the expanded value of
3835 .I parameter
3836 with the shortest matching pattern (the
3837 .Q #
3838 case) or the longest matching pattern (the
3839 .Q ##
3840 case) deleted.
3841 If
3842 .I parameter
3843 is
3844 .B @
3845 or
3846 .BR * ,
3847 the pattern removal operation is applied to each positional
3848 parameter in turn, and the expansion is the resultant list.
3849 If
3850 .I parameter
3851 is an array variable subscripted with
3852 .B @
3853 or
3854 .BR * ,
3855 the pattern removal operation is applied to each member of the
3856 array in turn, and the expansion is the resultant list.
3857 .TP
3858 .PD 0
3859 ${\fIparameter\fP\fB%\fP\fIword\fP}
3860 .TP
3861 ${\fIparameter\fP\fB%%\fP\fIword\fP}
3862 .PD
3863 \fBRemove matching suffix pattern\fP.
3864 The \fIword\fP is expanded to produce a pattern just as in
3865 pathname expansion, and matched against the expanded value of
3866 .I parameter
3867 using the rules described under
3868 .B "Pattern Matching"
3869 below.
3870 If the pattern matches a trailing portion of the expanded value of
3871 .IR parameter ,
3872 then the result of the expansion is the expanded value of
3873 .I parameter
3874 with the shortest matching pattern (the
3875 .Q %
3876 case) or the longest matching pattern (the
3877 .Q %%
3878 case) deleted.
3879 If
3880 .I parameter
3881 is
3882 .B @
3883 or
3884 .BR * ,
3885 the pattern removal operation is applied to each positional
3886 parameter in turn, and the expansion is the resultant list.
3887 If
3888 .I parameter
3889 is an array variable subscripted with
3890 .B @
3891 or
3892 .BR * ,
3893 the pattern removal operation is applied to each member of the
3894 array in turn, and the expansion is the resultant list.
3895 .TP
3896 .PD 0
3897 ${\fIparameter\fP\fB/\fP\fIpattern\fP\fB/\fP\fIstring\fP}
3898 .TP
3899 ${\fIparameter\fP\fB//\fP\fIpattern\fP\fB/\fP\fIstring\fP}
3900 .TP
3901 ${\fIparameter\fP\fB/#\fP\fIpattern\fP\fB/\fP\fIstring\fP}
3902 .TP
3903 ${\fIparameter\fP\fB/%\fP\fIpattern\fP\fB/\fP\fIstring\fP}
3904 .PD
3905 \fBPattern substitution\fP.
3906 The \fIpattern\fP is expanded to produce a pattern
3907 and matched against the expanded value of \fIparameter\fP
3908 as described under
3909 .B "Pattern Matching"
3910 below.
3911 The longest match of \fIpattern\fP
3912 in the expanded value is replaced with \fIstring\fP.
3913 \fIstring\fP undergoes tilde expansion, parameter and variable expansion,
3914 arithmetic expansion, command and process substitution, and quote removal.
3915 .IP
3916 In the first form above, only the first match is replaced.
3917 If there are two slashes separating \fIparameter\fP and \fIpattern\fP
3918 (the second form above), all matches of \fIpattern\fP are
3919 replaced with \fIstring\fP.
3920 If \fIpattern\fP is preceded by \fB#\fP (the third form above),
3921 it must match at the beginning of the expanded value of \fIparameter\fP.
3922 If \fIpattern\fP is preceded by \fB%\fP (the fourth form above),
3923 it must match at the end of the expanded value of \fIparameter\fP.
3924 .IP
3925 If the expansion of \fIstring\fP is null,
3926 matches of \fIpattern\fP are deleted
3927 and the \fB/\fP following \fIpattern\fP may be omitted.
3928 .IP
3929 If the \fBpatsub_replacement\fP shell option is enabled using \fBshopt\fP,
3930 any unquoted instances of \fB&\fP in \fIstring\fP are replaced with the
3931 matching portion of \fIpattern\fP.
3932 .IP
3933 Quoting any part of \fIstring\fP inhibits replacement in the
3934 expansion of the quoted portion, including replacement strings stored
3935 in shell variables.
3936 Backslash escapes \fB&\fP in \fIstring\fP; the backslash is removed
3937 in order to permit a literal \fB&\fP in the replacement string.
3938 Backslash can also be used to escape a backslash; \fB\e\e\fP results in
3939 a literal backslash in the replacement.
3940 Users should take care if \fIstring\fP is double-quoted to avoid
3941 unwanted interactions between the backslash and double-quoting, since
3942 backslash has special meaning within double quotes.
3943 Pattern substitution performs the check for unquoted \fB&\fP after
3944 expanding \fIstring\fP;
3945 shell programmers should quote any occurrences of \fB&\fP
3946 they want to be taken literally in the replacement
3947 and ensure any instances of \fB&\fP they want to be replaced are unquoted.
3948 .IP
3949 Like the pattern removal operators, double quotes surrounding the
3950 replacement string quote the expanded characters, while double quotes
3951 enclosing the entire parameter substitution do not, since
3952 the expansion is performed in a
3953 context that doesn't take any enclosing double quotes into account.
3954 .IP
3955 If the
3956 .B nocasematch
3957 shell option is enabled, the match is performed without regard to the case
3958 of alphabetic characters.
3959 .IP
3960 If
3961 .I parameter
3962 is
3963 .B @
3964 or
3965 .BR * ,
3966 the substitution operation is applied to each positional
3967 parameter in turn, and the expansion is the resultant list.
3968 If
3969 .I parameter
3970 is an array variable subscripted with
3971 .B @
3972 or
3973 .BR * ,
3974 the substitution operation is applied to each member of the
3975 array in turn, and the expansion is the resultant list.
3976 .TP
3977 .PD 0
3978 ${\fIparameter\fP\fB\*^\fP\fIpattern\fP}
3979 .TP
3980 ${\fIparameter\fP\fB\*^\*^\fP\fIpattern\fP}
3981 .TP
3982 ${\fIparameter\fP\fB,\fP\fIpattern\fP}
3983 .TP
3984 ${\fIparameter\fP\fB,,\fP\fIpattern\fP}
3985 .PD
3986 \fBCase modification\fP.
3987 This expansion modifies the case of alphabetic characters in \fIparameter\fP.
3988 First, the \fIpattern\fP is expanded to produce a pattern
3989 as described below under
3990 .SM
3991 .BR "Pattern Matching" .
3992 .B Bash
3993 then examines characters in the expanded value of \fIparameter\fP
3994 against \fIpattern\fP as described below.
3995 If a character matches the pattern, its case is converted.
3996 The pattern should not attempt to match more than one character.
3997 .IP
3998 Using
3999 .Q \*^
4000 converts lowercase letters matching \fIpattern\fP to uppercase;
4001 .Q ,
4002 converts matching uppercase letters to lowercase.
4003 The
4004 \fB\*^\fP and \fB,\fP variants
4005 examine the first character in the expanded value
4006 and convert its case if it matches \fIpattern\fP;
4007 the
4008 \fB\*^\*^\fP and \fB,,\fP variants
4009 examine all characters in the expanded value
4010 and convert each one that matches \fIpattern\fP.
4011 If \fIpattern\fP is omitted, it is treated like a \fB?\fP, which matches
4012 every character.
4013 .IP
4014 If
4015 .I parameter
4016 is
4017 .B @
4018 or
4019 .BR * ,
4020 the case modification operation is applied to each positional
4021 parameter in turn, and the expansion is the resultant list.
4022 If
4023 .I parameter
4024 is an array variable subscripted with
4025 .B @
4026 or
4027 .BR * ,
4028 the case modification operation is applied to each member of the
4029 array in turn, and the expansion is the resultant list.
4030 .TP
4031 .PD 0
4032 ${\fIparameter\fP\fB@\fP\fIoperator\fP}
4033 \fBParameter transformation\fP.
4034 The expansion is either a transformation of the value of \fIparameter\fP
4035 or information about \fIparameter\fP itself, depending on the value of
4036 \fIoperator\fP. Each \fIoperator\fP is a single letter:
4037 .PP
4038 .RS
4039 .TP
4040 .B U
4041 The expansion is a string that is the value of \fIparameter\fP with lowercase
4042 alphabetic characters converted to uppercase.
4043 .TP
4044 .B u
4045 The expansion is a string that is the value of \fIparameter\fP with the first
4046 character converted to uppercase, if it is alphabetic.
4047 .TP
4048 .B L
4049 The expansion is a string that is the value of \fIparameter\fP with uppercase
4050 alphabetic characters converted to lowercase.
4051 .TP
4052 .B Q
4053 The expansion is a string that is the value of \fIparameter\fP quoted in a
4054 format that can be reused as input.
4055 .TP
4056 .B E
4057 The expansion is a string that is the value of \fIparameter\fP with backslash
4058 escape sequences expanded as with the \fB$\*'\fP.\|.\|.\%\fB\*'\fP
4059 quoting mechanism.
4060 .TP
4061 .B P
4062 The expansion is a string that is the result of expanding the value of
4063 \fIparameter\fP as if it were a prompt string (see \fBPROMPTING\fP below).
4064 .TP
4065 .B A
4066 The expansion is a string in the form of
4067 an assignment statement or \fBdeclare\fP command that, if
4068 evaluated, recreates \fIparameter\fP with its attributes and value.
4069 .TP
4070 .B K
4071 Produces a possibly-quoted version of the value of \fIparameter\fP,
4072 except that it prints the values of
4073 indexed and associative arrays as a sequence of quoted key-value pairs
4074 (see \fBArrays\fP above).
4075 The keys and values are quoted in a format that can be reused as input.
4076 .TP
4077 .B a
4078 The expansion is a string consisting of flag values representing
4079 \fIparameter\fP's attributes.
4080 .TP
4081 .B k
4082 Like the K transformation, but expands the keys and values of
4083 indexed and associative arrays to separate words after word splitting.
4084 .PD
4085 .PP
4086 If
4087 .I parameter
4088 is
4089 .B @
4090 or
4091 .BR * ,
4092 the operation is applied to each positional
4093 parameter in turn, and the expansion is the resultant list.
4094 If
4095 .I parameter
4096 is an array variable subscripted with
4097 .B @
4098 or
4099 .BR * ,
4100 the operation is applied to each member of the
4101 array in turn, and the expansion is the resultant list.
4102 .PP
4103 The result of the expansion is subject to word splitting and pathname
4104 expansion as described below.
4105 .RE
4106 .SS Command Substitution
4107 \fICommand substitution\fP allows the output of a command to replace
4108 the command itself.
4109 There are two standard forms:
4110 .RS
4111 .PP
4112 \fB$(\fP\fIcommand\fP\|\fB)\fP
4113 .RE
4114 or (deprecated)
4115 .RS
4116 \fB\`\fP\fIcommand\fP\fB\`\fP.
4117 .RE
4118 .PP
4119 .B Bash
4120 performs the expansion by executing \fIcommand\fP in a subshell environment
4121 and replacing the command substitution with the standard output of the
4122 command, with any trailing newlines deleted.
4123 Embedded newlines are not deleted, but they may be removed during
4124 word splitting.
4125 The command substitution \fB$(cat \fIfile\fP)\fR can be replaced by
4126 the equivalent but faster \fB$(< \fIfile\fP)\fR.
4127 .PP
4128 With the old-style backquote form of substitution,
4129 backslash retains its literal meaning except when followed by
4130 .BR $ ,
4131 .BR \` ,
4132 or
4133 .BR \e .
4134 The first backquote not preceded by a backslash terminates the
4135 command substitution.
4136 When using the $(\^\fIcommand\fP\|) form, all characters between the
4137 parentheses make up the command; none are treated specially.
4138 .PP
4139 There is an alternate form of command substitution:
4140 .RS
4141 .PP
4142 \fB${\fP\fIc\fP \fIcommand\fP\fB;\fP\|\fB}\fP
4143 .RE
4144 .PP
4145 which executes \fIcommand\fP in the current execution environment
4146 and captures its output, again with trailing newlines removed.
4147 .PP
4148 The character \fIc\fP following the open brace must be a space, tab,
4149 newline, or \fB|\fP, and the close brace must be in a position
4150 where a reserved word may appear (i.e., preceded by a command terminator
4151 such as semicolon).
4152 \fBBash\fP allows the close brace to be joined to the remaining characters in
4153 the word without being followed by a shell metacharacter as a reserved
4154 word would usually require.
4155 .PP
4156 Any side effects of \fIcommand\fP take effect immediately
4157 in the current execution environment and persist in the current
4158 environment after the command completes (e.g., the \fBexit\fP builtin
4159 exits the shell).
4160 .PP
4161 This type of command substitution superficially resembles executing an
4162 unnamed shell function: local variables are created as when a shell
4163 function is executing, and the \fBreturn\fP builtin forces
4164 \fIcommand\fP to complete;
4165 however, the rest of the execution environment,
4166 including the positional parameters, is shared with the caller.
4167 .PP
4168 If the first character following the open brace
4169 is a \fB|\fP, the construct expands to the
4170 value of the \fBREPLY\fP shell variable after \fIcommand\fP executes,
4171 without removing any trailing newlines,
4172 and the standard output of \fIcommand\fP remains the same as in the
4173 calling shell.
4174 \fBBash\fP creates \fBREPLY\fP as an initially-unset local variable when
4175 \fIcommand\fP executes, and restores \fBREPLY\fP to the value it had
4176 before the command substitution after \fIcommand\fP completes,
4177 as with any local variable.
4178 .PP
4179 Command substitutions may be nested. To nest when using the backquoted form,
4180 escape the inner backquotes with backslashes.
4181 .PP
4182 If the substitution appears within double quotes, \fBbash\fP does not perform
4183 word splitting and pathname expansion on the results.
4184 .SS Arithmetic Expansion
4185 Arithmetic expansion evaluates an arithmetic expression
4186 and substitutes the result.
4187 The format for arithmetic expansion is:
4188 .RS
4189 .PP
4190 \fB$((\fP\fIexpression\fP\fB))\fP
4191 .RE
4192 .PP
4193 The
4194 .I expression
4195 undergoes the same expansions
4196 as if it were within double quotes,
4197 but unescaped double quote characters
4198 in \fIexpression\fP are not treated
4199 specially and are removed.
4200 All tokens in the expression undergo parameter and variable expansion,
4201 command substitution, and quote removal.
4202 The result is treated as the arithmetic expression to be evaluated.
4203 Since the way Bash handles double quotes
4204 can potentially result in empty strings,
4205 arithmetic expansion treats
4206 those as expressions that evaluate to 0.
4207 Arithmetic expansions may be nested.
4208 .PP
4209 The evaluation is performed according to the rules listed below under
4210 .SM
4211 .BR "ARITHMETIC EVALUATION" .
4212 If
4213 .I expression
4214 is invalid,
4215 .B bash
4216 prints a message to standard error indicating failure,
4217 does not perform the substitution,
4218 and does not execute the command associated with the expansion.
4219 .SS Process Substitution
4220 \fIProcess substitution\fP allows a process's input or output to be
4221 referred to using a filename.
4222 It takes the form of
4223 \fB<(\fP\fIlist\^\fP\fB)\fP
4224 or
4225 \fB>(\fP\fIlist\^\fP\fB)\fP.
4226 The process \fIlist\fP is run asynchronously, and its input or output
4227 appears as a filename.
4228 This filename is
4229 passed as an argument to the current command as the result of the
4230 expansion.
4231 .PP
4232 If the
4233 \fB>(\fP\fIlist\^\fP\fB)\fP form is used, writing to
4234 the file provides input for \fIlist\fP.
4235 If the
4236 \fB<(\fP\fIlist\^\fP\fB)\fP form is used, reading the file
4237 obtains the output of \fIlist\fP.
4238 No space may appear between the \fB<\fP or \fB>\fP
4239 and the left parenthesis, otherwise the construct would be interpreted
4240 as a redirection.
4241 .PP
4242 Process substitution is supported on systems that support named
4243 pipes (\fIFIFOs\fP) or the \fI/dev/fd\fP method of naming open files.
4244 .PP
4245 When available, process substitution is performed
4246 simultaneously with parameter and variable expansion,
4247 command substitution,
4248 and arithmetic expansion.
4249 .SS Word Splitting
4250 The shell scans the results of
4251 parameter expansion,
4252 command substitution,
4253 and
4254 arithmetic expansion
4255 that did not occur within double quotes for
4256 .IR "word splitting" .
4257 Words that were not expanded are not split.
4258 .PP
4259 The shell treats each character of
4260 .SM
4261 .B IFS
4262 as a delimiter,
4263 and splits the results of the other expansions into words
4264 using these characters as field terminators.
4265 .PP
4266 An \fIIFS whitespace\fP character is whitespace as defined above
4267 (see \fBDefinitions\fP) that appears in the value of
4268 .SM
4269 .BR IFS .
4270 Space, tab, and newline are always considered IFS whitespace, even
4271 if they don't appear in the locale's \fBspace\fP category.
4272 .PP
4273 If
4274 .SM
4275 .B IFS
4276 is unset, field splitting acts as if its value were
4277 .BR <space><tab><newline> ,
4278 and treats these characters as IFS whitespace.
4279 If the value of
4280 .SM
4281 .B IFS
4282 is null, no word splitting occurs,
4283 but implicit null arguments (see below) are still removed.
4284 .PP
4285 Word splitting begins by removing sequences of IFS whitespace characters
4286 from the beginning and end of the results of the previous expansions,
4287 then splits the remaining words.
4288 .PP
4289 If the value of
4290 .SM
4291 .B IFS
4292 consists solely of IFS whitespace,
4293 any sequence of IFS whitespace characters delimits a field,
4294 so a field consists of characters that are not unquoted IFS
4295 whitespace, and null fields result only from quoting.
4296 .PP
4297 If
4298 .SM
4299 .B IFS
4300 contains a non-whitespace character, then any character in
4301 the value of
4302 .SM
4303 .B IFS
4304 that is not IFS whitespace,
4305 along with any adjacent IFS whitespace characters, delimits a field.
4306 This means that adjacent non-IFS-whitespace delimiters produce a
4307 null field.
4308 A sequence of IFS whitespace characters also delimits a field.
4309 .PP
4310 Explicit null arguments (\^\fB\*"\^\*"\fP or
4311 \^\fB\*'\^\*'\fP\^) are retained
4312 and passed to commands as empty strings.
4313 Unquoted implicit null arguments, resulting from the expansion of
4314 parameters that have no values, are removed.
4315 Expanding a parameter with no value within double quotes
4316 produces a null field,
4317 which is retained and passed to a command as an empty string.
4318 .PP
4319 When a quoted null argument appears as part of a word whose expansion is
4320 non-null, word splitting removes the null argument portion,
4321 leaving the non-null expansion.
4322 That is, the word
4323 .Q "\-d\*'\^\*'"
4324 becomes
4325 .Q \-d
4326 after word splitting and null argument removal.
4327 .SS "Pathname Expansion"
4328 After word splitting,
4329 unless the
4330 .B \-f
4331 option has been set,
4332 .B bash
4333 scans each word for the characters
4334 .BR * ,
4335 .BR ? ,
4336 and
4337 .BR [ .
4338 If one of these characters appears, and is not quoted, then the word is
4339 regarded as a
4340 .IR pattern ,
4341 and replaced with a sorted list of filenames matching the pattern
4342 (see
4343 .SM
4344 .B "Pattern Matching"
4345 below)
4346 subject to the value of the \fBGLOBSORT\fP shell variable.
4347 .PP
4348 If no matching filenames are found,
4349 and the shell option
4350 .B nullglob
4351 is not enabled, the word is left unchanged.
4352 If the
4353 .B nullglob
4354 option is set, and no matches are found,
4355 the word is removed.
4356 If the
4357 .B failglob
4358 shell option is set, and no matches are found,
4359 \fBbash\fP prints an error message and does not execute the command.
4360 If the shell option
4361 .B nocaseglob
4362 is enabled, the match is performed without regard to the case
4363 of alphabetic characters.
4364 .PP
4365 When a pattern is used for pathname expansion,
4366 the character
4367 .Q .\&
4368 at the start of a name or immediately following a slash
4369 must be matched explicitly, unless the shell option
4370 .B dotglob
4371 is set.
4372 In order to match the filenames
4373 .FN .\&
4374 and
4375 .FN ..\& ,
4376 the pattern must begin with
4377 .Q .\&
4378 (for example,
4379 .Q .?\& ),
4380 even if
4381 .B dotglob
4382 is set.
4383 If the
4384 .B globskipdots
4385 shell option is enabled, the filenames
4386 .FN .\&
4387 and
4388 .FN ..\&
4389 never match, even if the pattern begins with a
4390 .Q .\& .
4391 When not matching pathnames, the
4392 .Q .\&
4393 character is not treated specially.
4394 .PP
4395 When matching a pathname, the slash character must always be
4396 matched explicitly by a slash in the pattern, but in other matching
4397 contexts it can be matched by a special pattern character as described
4398 below under
4399 .SM
4400 .BR "Pattern Matching" .
4401 .PP
4402 See the description of
4403 .B shopt
4404 below under
4405 .SM
4406 .B "SHELL BUILTIN COMMANDS"
4407 for a description of the
4408 .BR nocaseglob ,
4409 .BR nullglob ,
4410 .BR globskipdots ,
4411 .BR failglob ,
4412 and
4413 .B dotglob
4414 shell options.
4415 .PP
4416 The
4417 .SM
4418 .B GLOBIGNORE
4419 shell variable may be used to restrict the set of file names matching a
4420 .IR pattern .
4421 If
4422 .SM
4423 .B GLOBIGNORE
4424 is set, each matching file name that also matches one of the patterns in
4425 .SM
4426 .B GLOBIGNORE
4427 is removed from the list of matches.
4428 If the \fBnocaseglob\fP option is set, the matching against the patterns in
4429 .SM
4430 .B GLOBIGNORE
4431 is performed without regard to case.
4432 The filenames
4433 .FN .\&
4434 and
4435 .FN ..\&
4436 are always ignored when
4437 .SM
4438 .B GLOBIGNORE
4439 is set and not null.
4440 However, setting
4441 .SM
4442 .B GLOBIGNORE
4443 to a non-null value has the effect of enabling the
4444 .B dotglob
4445 shell option, so all other filenames beginning with a
4446 .Q .\&
4447 match.
4448 To get the old behavior of ignoring filenames beginning with a
4449 .Q .\& ,
4450 make
4451 .Q .*
4452 one of the patterns in
4453 .SM
4454 .B GLOBIGNORE\c
4455 \&.
4456 The
4457 .B dotglob
4458 option is disabled when
4459 .SM
4460 .B GLOBIGNORE
4461 is unset.
4462 The
4463 .B GLOBIGNORE
4464 pattern matching honors the setting of the \fBextglob\fP shell
4465 option.
4466 .PP
4467 The value of the
4468 .SM
4469 .B GLOBSORT
4470 shell variable controls how the results of pathname expansion are sorted,
4471 as described above under
4472 .BR "Shell Variables" .
4473 .PP
4474 .B "Pattern Matching"
4475 .PP
4476 Any character that appears in a pattern, other than the special pattern
4477 characters described below, matches itself.
4478 The NUL character may not occur in a pattern.
4479 A backslash escapes the following character; the escaping backslash is
4480 discarded when matching.
4481 The special pattern characters must be quoted if
4482 they are to be matched literally.
4483 .PP
4484 The special pattern characters have the following meanings:
4485 .PP
4486 .PD 0
4487 .RS
4488 .TP
4489 .B *
4490 Matches any string, including the null string.
4491 When the \fBglobstar\fP shell option is enabled, and \fB*\fP is used in
4492 a pathname expansion context, two adjacent \fB*\fPs used as a single
4493 pattern match all files and zero or more directories and
4494 subdirectories.
4495 If followed by a \fB/\fP, two adjacent \fB*\fPs match only directories
4496 and subdirectories.
4497 .TP
4498 .B ?
4499 Matches any single character.
4500 .TP
4501 .BR [ .\|.\|. ]
4502 .PD
4503 Matches any one of the characters enclosed between the brackets.
4504 This is known as a \fIbracket expression\fP
4505 and matches a single character.
4506 A pair of characters separated by a hyphen denotes a
4507 \fIrange expression\fP;
4508 any character that falls between those two characters, inclusive,
4509 using the current locale's collating sequence and character set, matches.
4510 If the first character following the
4511 .B [
4512 is a
4513 .B !
4514 or a
4515 .B \*^
4516 then any character not within the range matches.
4517 To match a
4518 .BR \- ,
4519 include it as the first or last character in the set.
4520 To match a
4521 .BR ] ,
4522 include it as the first character in the set.
4523 .IP
4524 The sorting order of characters in range expressions,
4525 and the characters included in the range,
4526 are determined by the current locale and the values of the
4527 .SM
4528 .B LC_COLLATE
4529 or
4530 .SM
4531 .B LC_ALL
4532 shell variables, if set.
4533 To obtain the traditional interpretation of range expressions, where
4534 .B [a\-d]
4535 is equivalent to
4536 .BR [abcd] ,
4537 set the value of the
4538 .B LC_COLLATE
4539 or
4540 .B LC_ALL
4541 shell variables to
4542 .BR C ,
4543 or enable the
4544 .B globasciiranges
4545 shell option.
4546 .IP
4547 Within a bracket expression,
4548 \fIcharacter classes\fP can be specified using the syntax
4549 \fB[:\fP\fIclass\fP\fB:]\fP, where \fIclass\fP is one of the
4550 following classes defined in the
4551 .SM POSIX
4552 standard:
4553 .IP
4554 .RS
4555 .B
4556 .if n alnum alpha ascii blank cntrl digit graph lower print punct space \
4557 upper word xdigit
4558 .if t alnum alpha ascii blank cntrl digit graph lower \
4559 print punct space upper word xdigit
4560 .RE
4561 .IP
4562 A character class matches any character belonging to that class.
4563 The \fBword\fP character class matches letters, digits, and the character _.
4564 .IP
4565 Within a bracket expression,
4566 an \fIequivalence class\fP can be specified using the syntax
4567 \fB[=\fP\fIc\fP\fB=]\fP, which matches all characters with the
4568 same collation weight (as defined by the current locale) as
4569 the character \fIc\fP.
4570 .IP
4571 Within a bracket expression,
4572 the syntax \fB[.\fP\fIsymbol\fP\fB.]\fP matches the collating symbol
4573 \fIsymbol\fP.
4574 .RE
4575 .PP
4576 If the \fBextglob\fP shell option is enabled using the \fBshopt\fP
4577 builtin, the shell recognizes several extended pattern matching operators.
4578 In the following description, a \fIpattern-list\fP is a list of one
4579 or more patterns separated by a \fB|\fP.
4580 Composite patterns may be formed using one or more of the following
4581 sub-patterns:
4582 .PP
4583 .PD 0
4584 .RS
4585 .TP
4586 \fB?(\fP\^\fIpattern-list\^\fP\fB)\fP
4587 Matches zero or one occurrence of the given patterns.
4588 .TP
4589 \fB*(\fP\^\fIpattern-list\^\fP\fB)\fP
4590 Matches zero or more occurrences of the given patterns.
4591 .TP
4592 \fB+(\fP\^\fIpattern-list\^\fP\fB)\fP
4593 Matches one or more occurrences of the given patterns.
4594 .TP
4595 \fB@(\fP\^\fIpattern-list\^\fP\fB)\fP
4596 Matches one of the given patterns.
4597 .TP
4598 \fB!(\fP\^\fIpattern-list\^\fP\fB)\fP
4599 Matches anything except one of the given patterns.
4600 .RE
4601 .PD
4602 .PP
4603 The \fBextglob\fP option changes the behavior of the parser, since the
4604 parentheses are normally treated as operators with syntactic meaning.
4605 To ensure that extended matching patterns are parsed correctly, make sure
4606 that \fBextglob\fP is enabled before parsing constructs containing the
4607 patterns, including shell functions and command substitutions.
4608 .PP
4609 When matching filenames, the \fBdotglob\fP shell option determines
4610 the set of filenames that are tested:
4611 when \fBdotglob\fP is enabled, the set of filenames includes all files
4612 beginning with
4613 .Q .\& ,
4614 but
4615 .FN .\&
4616 and
4617 .FN ..\&
4618 must be matched by a pattern or sub-pattern that begins with a dot;
4619 when it is disabled, the set does not
4620 include any filenames beginning with
4621 .Q .\&
4622 unless the pattern or sub-pattern begins with a
4623 .Q .\& .
4624 If the
4625 .B globskipdots
4626 shell option is enabled, the filenames
4627 .FN .\&
4628 and
4629 .FN ..\&
4630 never appear in the set.
4631 As above,
4632 .Q .\&
4633 only has a special meaning when matching filenames.
4634 .PP
4635 Complicated extended pattern matching against long strings is slow,
4636 especially when the patterns contain alternations and the strings
4637 contain multiple matches.
4638 Using separate matches against shorter strings, or using arrays of
4639 strings instead of a single long string, may be faster.
4640 .SS Quote Removal
4641 After the preceding expansions, all unquoted occurrences of the
4642 characters
4643 .BR \e ,
4644 .BR \*' ,
4645 and \^\fB\*"\fP\^ that did not result from one of the above
4646 expansions are removed.
4647 .SH REDIRECTION
4648 Before a command is executed, its input and output may be
4649 .I redirected
4650 using a special notation interpreted by the shell.
4651 \fIRedirection\fP allows commands' file handles to be
4652 duplicated, opened, closed,
4653 made to refer to different files,
4654 and can change the files the command reads from and writes to.
4655 When used with the \fBexec\fP builtin,
4656 redirections modify file handles in the current shell execution environment.
4657 The following redirection
4658 operators may precede or appear anywhere within a
4659 .I simple command
4660 or may follow a
4661 .IR command .
4662 Redirections are processed in the order they appear, from
4663 left to right.
4664 .PP
4665 Each redirection that may be preceded by a file descriptor number
4666 may instead be preceded by a word of the form {\fIvarname\fP}.
4667 In this case, for each redirection operator except
4668 .B >&\-
4669 and
4670 .BR <&\- ,
4671 the shell allocates a file descriptor greater
4672 than or equal to 10 and assigns it to \fIvarname\fP.
4673 If {\fIvarname\fP} precedes
4674 .B >&\-
4675 or
4676 .BR <&\- ,
4677 the value of \fIvarname\fP defines the file descriptor to close.
4678 If {\fIvarname\fP} is supplied, the redirection persists beyond
4679 the scope of the command, which allows the shell programmer to
4680 manage the file descriptor's lifetime manually without using
4681 the \fBexec\fP builtin.
4682 The \fBvarredir_close\fP shell option manages this behavior.
4683 .PP
4684 In the following descriptions, if the file descriptor number is
4685 omitted, and the first character of the redirection operator is
4686 .Q < ,
4687 the redirection refers to the standard input (file descriptor 0).
4688 If the first character of the redirection operator is
4689 .Q > ,
4690 the redirection refers to the standard output (file descriptor 1).
4691 .PP
4692 The \fIword\fP following the redirection operator in the following
4693 descriptions, unless otherwise noted, is subjected to
4694 brace expansion,
4695 tilde expansion,
4696 parameter and variable expansion,
4697 command substitution,
4698 arithmetic expansion,
4699 quote removal,
4700 pathname expansion,
4701 and word splitting.
4702 If it expands to more than one word,
4703 .B bash
4704 reports an error.
4705 .PP
4706 The order of redirections is significant.
4707 For example,
4708 the command
4709 .RS
4710 .PP
4711 ls \fB>\fP dirlist 2\fB>&\fP1
4712 .RE
4713 .PP
4714 directs both standard output and standard error to the file
4715 .IR dirlist ,
4716 while the command
4717 .RS
4718 .PP
4719 ls 2\fB>&\fP1 \fB>\fP dirlist
4720 .RE
4721 .PP
4722 directs only the standard output to file
4723 .IR dirlist ,
4724 because the standard error was directed to the standard output
4725 before the standard output was redirected to
4726 .IR dirlist .
4727 .PP
4728 \fBBash\fP handles several filenames specially when they are used in
4729 redirections, as described in the following table.
4730 If the operating system on which \fBbash\fP is running provides these
4731 special files, \fBbash\fP uses them; otherwise it emulates them
4732 internally with the behavior described below.
4733 .RS
4734 .PP
4735 .PD 0
4736 .TP
4737 .B /dev/fd/\fIfd\fP
4738 If \fIfd\fP is a valid integer, duplicate file descriptor \fIfd\fP.
4739 .TP
4740 .B /dev/stdin
4741 File descriptor 0 is duplicated.
4742 .TP
4743 .B /dev/stdout
4744 File descriptor 1 is duplicated.
4745 .TP
4746 .B /dev/stderr
4747 File descriptor 2 is duplicated.
4748 .TP
4749 .B /dev/tcp/\fIhost\fP/\fIport\fP
4750 If \fIhost\fP is a valid hostname or Internet address, and \fIport\fP
4751 is an integer port number or service name, \fBbash\fP attempts to open
4752 the corresponding TCP socket.
4753 .TP
4754 .B /dev/udp/\fIhost\fP/\fIport\fP
4755 If \fIhost\fP is a valid hostname or Internet address, and \fIport\fP
4756 is an integer port number or service name, \fBbash\fP attempts to open
4757 the corresponding UDP socket.
4758 .PD
4759 .RE
4760 .PP
4761 A failure to open or create a file causes the redirection to fail.
4762 .PP
4763 Redirections using file descriptors greater than 9 should be used with
4764 care, as they may conflict with file descriptors the shell uses
4765 internally.
4766 .SS Redirecting Input
4767 Redirecting input opens the file whose name results from
4768 the expansion of
4769 .I word
4770 for reading on file descriptor
4771 .IR n ,
4772 or the standard input (file descriptor 0) if
4773 .I n
4774 is not specified.
4775 .PP
4776 The general format for redirecting input is:
4777 .RS
4778 .PP
4779 [\fIn\fP]\fB<\fP\fIword\fP
4780 .RE
4781 .SS Redirecting Output
4782 Redirecting output opens the file whose name results from
4783 the expansion of
4784 .I word
4785 for writing on file descriptor
4786 .IR n ,
4787 or the standard output (file descriptor 1) if
4788 .I n
4789 is not specified.
4790 If the file does not exist it is created;
4791 if it does exist it is truncated to zero size.
4792 .PP
4793 The general format for redirecting output is:
4794 .RS
4795 .PP
4796 [\fIn\fP]\fB>\fP\fIword\fP
4797 .RE
4798 .PP
4799 If the redirection operator is
4800 .BR > ,
4801 and the
4802 .B noclobber
4803 option to the
4804 .B set
4805 builtin command has been enabled, the redirection fails if the file
4806 whose name results from the expansion of \fIword\fP exists and is
4807 a regular file.
4808 If the redirection operator is
4809 .BR >| ,
4810 or the redirection operator is
4811 .B >
4812 and the
4813 .B noclobber
4814 option to the
4815 .B set
4816 builtin is not enabled,
4817 \fBbash\fP attempts the redirection
4818 even if the file named by \fIword\fP exists.
4819 .SS Appending Redirected Output
4820 Redirecting output in this fashion opens
4821 the file whose name results from the expansion of
4822 .I word
4823 for appending on file descriptor
4824 .IR n ,
4825 or the standard output (file descriptor 1) if
4826 .I n
4827 is not specified.
4828 If the file does not exist it is created.
4829 .PP
4830 The general format for appending output is:
4831 .RS
4832 .PP
4833 [\fIn\fP]\fB>>\fP\fIword\fP
4834 .RE
4835 .SS Redirecting Standard Output and Standard Error
4836 This construct redirects both the
4837 standard output (file descriptor 1) and
4838 the standard error output (file descriptor 2)
4839 to the file whose name is the expansion of
4840 .IR word .
4841 .PP
4842 There are two formats for redirecting standard output and
4843 standard error:
4844 .RS
4845 .PP
4846 \fB&>\fP\fIword\fP
4847 .RE
4848 and
4849 .RS
4850 \fB>&\fP\fIword\fP
4851 .RE
4852 .PP
4853 Of the two forms, the first is preferred.
4854 This is semantically equivalent to
4855 .RS
4856 .PP
4857 \fB>\fP\fIword\fP 2\fB>&\fP1
4858 .RE
4859 .PP
4860 When using the second form, \fIword\fP may not expand to a number or
4861 \fB\-\fP.
4862 If it does, other redirection operators apply
4863 (see \fBDuplicating File Descriptors\fP below) for compatibility
4864 reasons.
4865 .SS Appending Standard Output and Standard Error
4866 This construct appends both the
4867 standard output (file descriptor 1) and
4868 the standard error output (file descriptor 2)
4869 to the file whose name is the expansion of
4870 .IR word .
4871 .PP
4872 The format for appending standard output and standard error is:
4873 .RS
4874 .PP
4875 \fB&>>\fP\fIword\fP
4876 .RE
4877 .PP
4878 This is semantically equivalent to
4879 .RS
4880 .PP
4881 \fB>>\fP\fIword\fP 2\fB>&\fP1
4882 .RE
4883 .PP
4884 (see \fBDuplicating File Descriptors\fP below).
4885 .SS Here Documents
4886 This type of redirection instructs the shell to read input from the
4887 current source until it reads a line containing only
4888 .I delimiter
4889 (with no trailing blanks).
4890 All of the lines read up to that point then become the standard
4891 input (or file descriptor \fIn\fP if \fIn\fP is specified) for a command.
4892 .PP
4893 The format of here-documents is:
4894 .RS
4895 .PP
4896 .nf
4897 [\fIn\fP]\fB<<\fP[\fB\-\fP]\fIword\fP
4898 \fIhere-document\fP
4899 \fIdelimiter\fP
4900 .fi
4901 .RE
4902 .PP
4903 The shell does not perform
4904 parameter and variable expansion, command substitution,
4905 arithmetic expansion, or pathname expansion on
4906 .IR word .
4907 .PP
4908 If any part of
4909 .I word
4910 is quoted, the
4911 .I delimiter
4912 is the result of quote removal on
4913 .IR word ,
4914 and the lines in the here-document are not expanded.
4915 If \fIword\fP is unquoted, the
4916 .I delimiter
4917 is \fIword\fP itself,
4918 and the here-document text is treated similarly to a double-quoted string:
4919 all lines of the here-document are subjected to
4920 parameter expansion, command substitution, and arithmetic expansion,
4921 the character sequence
4922 .B \e<newline>
4923 is treated literally, and
4924 .B \e
4925 must be used to quote the characters
4926 .BR \e ,
4927 .BR $ ,
4928 and
4929 .BR \` ;
4930 however, double quote characters have no special meaning.
4931 .PP
4932 If the redirection operator is
4933 .BR <<\- ,
4934 then the shell strips all leading tab characters from input lines
4935 and the line containing
4936 .IR delimiter .
4937 This allows
4938 here-documents within shell scripts to be indented in a
4939 natural fashion.
4940 .PP
4941 If the delimiter is not quoted, the
4942 .B \e<newline>
4943 sequence is treated as a line continuation: the two lines are joined
4944 and the backslash-newline is removed.
4945 This happens while reading the here-document, before the check for
4946 the ending delimiter, so joined lines can form the end delimiter.
4947 .SS "Here Strings"
4948 A variant of here documents, the format is:
4949 .RS
4950 .PP
4951 .nf
4952 [\fIn\fP]\fB<<<\fP\fIword\fP
4953 .fi
4954 .RE
4955 .PP
4956 The \fIword\fP undergoes
4957 tilde expansion, parameter and variable expansion,
4958 command substitution, arithmetic expansion, and quote removal.
4959 Pathname expansion and word splitting are not performed.
4960 The result is supplied as a single string, with a newline appended,
4961 to the command on its
4962 standard input (or file descriptor \fIn\fP if \fIn\fP is specified).
4963 .SS "Duplicating File Descriptors"
4964 The redirection operator
4965 .RS
4966 .PP
4967 [\fIn\fP]\fB<&\fP\fIword\fP
4968 .RE
4969 .PP
4970 is used to duplicate input file descriptors.
4971 If
4972 .I word
4973 expands to one or more digits, file descriptor
4974 .I n
4975 is made to be a copy of that file descriptor.
4976 It is a redirection error if the digits in
4977 .I word
4978 do not specify a file descriptor open for input.
4979 If
4980 .I word
4981 evaluates to
4982 .BR \- ,
4983 file descriptor
4984 .I n
4985 is closed.
4986 If
4987 .I n
4988 is not specified, this uses the standard input (file descriptor 0).
4989 .PP
4990 The operator
4991 .RS
4992 .PP
4993 [\fIn\fP]\fB>&\fP\fIword\fP
4994 .RE
4995 .PP
4996 is used similarly to duplicate output file descriptors.
4997 If
4998 .I n
4999 is not specified, this uses the standard output (file descriptor 1).
5000 It is a redirection error if the digits in
5001 .I word
5002 do not specify a file descriptor open for output.
5003 If
5004 .I word
5005 evaluates to
5006 .BR \- ,
5007 file descriptor
5008 .I n
5009 is closed.
5010 As a special case, if \fIn\fP is omitted,
5011 and \fIword\fP does not expand to one or more digits or \fB\-\fP,
5012 this redirects the standard output and standard error as described
5013 previously.
5014 .SS "Moving File Descriptors"
5015 The redirection operator
5016 .RS
5017 .PP
5018 [\fIn\fP]\fB<&\fP\fIdigit\fP\fB\-\fP
5019 .RE
5020 .PP
5021 moves the file descriptor \fIdigit\fP to file descriptor
5022 .IR n ,
5023 or the standard input (file descriptor 0) if \fIn\fP is not specified.
5024 \fIdigit\fP is closed after being duplicated to \fIn\fP.
5025 .PP
5026 Similarly, the redirection operator
5027 .RS
5028 .PP
5029 [\fIn\fP]\fB>&\fP\fIdigit\fP\fB\-\fP
5030 .RE
5031 .PP
5032 moves the file descriptor \fIdigit\fP to file descriptor
5033 .IR n ,
5034 or the standard output (file descriptor 1) if \fIn\fP is not specified.
5035 .SS "Opening File Descriptors for Reading and Writing"
5036 The redirection operator
5037 .RS
5038 .PP
5039 [\fIn\fP]\fB<>\fP\fIword\fP
5040 .RE
5041 .PP
5042 opens the file whose name is the expansion of
5043 .I word
5044 for both reading and writing on file descriptor
5045 .IR n ,
5046 or on file descriptor 0 if
5047 .I n
5048 is not specified.
5049 If the file does not exist, it is created.
5050 .SH ALIASES
5051 \fIAliases\fP allow a string to be substituted for a word that is in
5052 a position in the input where it can be the first word of a simple
5053 command.
5054 Aliases have names and corresponding values that are set
5055 and unset using the \fBalias\fP and \fBunalias\fP builtin commands
5056 (see
5057 .SM
5058 .B "SHELL BUILTIN COMMANDS"
5059 below).
5060 .PP
5061 If the shell reads an unquoted word in the right position, it checks
5062 the word to see if it matches an alias name.
5063 If it matches, the shell
5064 replaces the word with the alias value, and reads that value as if it
5065 had been read instead of the word.
5066 The shell doesn't look at any characters following the word before
5067 attempting alias substitution.
5068 .PP
5069 The characters \fB/\fP, \fB$\fP, \fB\`\fP, and \fB=\fP and
5070 any of the shell \fImetacharacters\fP or quoting characters
5071 listed above may not appear in an alias name.
5072 The replacement text may contain any valid shell input,
5073 including shell metacharacters.
5074 The first word of the replacement text is tested
5075 for aliases, but a word that is identical to an alias being expanded
5076 is not expanded a second time.
5077 This means that one may alias
5078 .B ls
5079 to
5080 .BR "ls \-F" ,
5081 for instance, and
5082 .B bash
5083 does not try to recursively expand the replacement text.
5084 .PP
5085 If the last character of the alias value is a
5086 .IR blank ,
5087 the shell checks the next command
5088 word following the alias for alias expansion.
5089 .PP
5090 Aliases are created and listed with the
5091 .B alias
5092 command, and removed with the
5093 .B unalias
5094 command.
5095 .PP
5096 There is no mechanism for using arguments in the replacement text.
5097 If arguments are needed, use a shell function (see
5098 .SM
5099 .B FUNCTIONS
5100 below) instead.
5101 .PP
5102 Aliases are not expanded when the shell is not interactive, unless
5103 the
5104 .B expand_aliases
5105 shell option is set using
5106 .B shopt
5107 (see the description of
5108 .B shopt
5109 under
5110 .SM
5111 .B "SHELL BUILTIN COMMANDS"
5112 below).
5113 .PP
5114 The rules concerning the definition and use of aliases are
5115 somewhat confusing.
5116 .B Bash
5117 always reads at least one complete line of input,
5118 and all lines that make up a compound command,
5119 before executing any of the commands on that line or the compound command.
5120 Aliases are expanded when a command is read, not when it is executed.
5121 Therefore, an
5122 alias definition appearing on the same line as another
5123 command does not take effect until the shell reads the next line of input,
5124 and an alias definition in a compound command does not take
5125 effect until the shell parses and executes the entire compound command.
5126 The commands following the alias definition
5127 on that line,
5128 or in the rest of a compound command,
5129 are not affected by the new alias.
5130 This behavior is also an issue when functions are executed.
5131 Aliases are expanded when a function definition is read,
5132 not when the function is executed, because a function definition
5133 is itself a command.
5134 As a consequence, aliases
5135 defined in a function are not available until after that
5136 function is executed.
5137 To be safe, always put
5138 alias definitions on a separate line, and do not use
5139 .B alias
5140 in compound commands.
5141 .PP
5142 For almost every purpose, shell functions are preferable to aliases.
5143 .SH FUNCTIONS
5144 A shell function, defined as described above under
5145 .SM
5146 .BR "SHELL GRAMMAR" ,
5147 stores a series of commands for later execution.
5148 When the name of a shell function is used as a simple command name,
5149 the shell executes
5150 the list of commands associated with that function name.
5151 Functions are executed in the context of the
5152 calling shell; there is no new process created to interpret
5153 them (contrast this with the execution of a shell script).
5154 .PP
5155 When a function is executed, the arguments to the
5156 function become the positional parameters
5157 during its execution.
5158 The special parameter
5159 .B #
5160 is updated to reflect the new positional parameters.
5161 Special parameter \fB0\fP is unchanged.
5162 The first element of the
5163 .SM
5164 .B FUNCNAME
5165 variable is set to the name of the function while the function
5166 is executing.
5167 .PP
5168 All other aspects of the shell execution
5169 environment are identical between a function and its caller
5170 with these exceptions: the
5171 .SM
5172 .B DEBUG
5173 and
5174 .B RETURN
5175 traps (see the description of the
5176 .B trap
5177 builtin under
5178 .SM
5179 .B "SHELL BUILTIN COMMANDS"
5180 below) are not inherited unless the function has been given the
5181 \fBtrace\fP attribute (see the description of the
5182 .SM
5183 .B declare
5184 builtin below) or the
5185 \fB\-o functrace\fP shell option has been enabled with
5186 the \fBset\fP builtin
5187 (in which case all functions inherit the \fBDEBUG\fP and \fBRETURN\fP traps),
5188 and the
5189 .SM
5190 .B ERR
5191 trap is not inherited unless the \fB\-o errtrace\fP shell option has
5192 been enabled.
5193 .PP
5194 Variables local to the function are declared with the
5195 .B local
5196 builtin command (\fIlocal variables\fP).
5197 Ordinarily, variables and their values
5198 are shared between the function and its caller.
5199 If a variable is declared \fBlocal\fP, the variable's visible scope
5200 is restricted to that function and its children (including the functions
5201 it calls).
5202 .PP
5203 In the following description, the \fIcurrent scope\fP is a currently-
5204 executing function.
5205 Previous scopes consist of that function's caller and so on,
5206 back to the
5207 .Q global
5208 scope, where the shell is not executing any shell function.
5209 A local variable at the current scope is a variable
5210 declared using the \fBlocal\fP or \fBdeclare\fP builtins in the
5211 function that is currently executing.
5212 .PP
5213 Local variables
5214 .Q shadow
5215 variables with the same name declared at previous scopes.
5216 For instance, a local variable declared in a function
5217 hides variables with the same name declared at previous scopes,
5218 including global variables: references and assignments
5219 refer to the local variable, leaving the variables
5220 at previous scopes unmodified.
5221 When the function returns, the global variable is once again visible.
5222 .PP
5223 The shell uses \fIdynamic scoping\fP to control a variable's visibility
5224 within functions.
5225 With dynamic scoping, visible variables and their values
5226 are a result of the sequence of function calls that caused execution
5227 to reach the current function.
5228 The value of a variable that a function sees depends
5229 on its value within its caller, if any, whether that caller is
5230 the global
5231 scope or another shell function.
5232 This is also the value that a local variable
5233 declaration shadows,
5234 and the value that is restored when the function returns.
5235 .PP
5236 For example, if a variable \fIvar\fP is declared as local in function
5237 \fIfunc1\fP, and \fIfunc1\fP calls another function \fIfunc2\fP,
5238 references to \fIvar\fP made from within \fIfunc2\fP resolve to the
5239 local variable \fIvar\fP from \fIfunc1\fP, shadowing any global variable
5240 named \fIvar\fP.
5241 .PP
5242 The \fBunset\fP builtin also acts using the same dynamic scope: if a
5243 variable is local to the current scope, \fBunset\fP unsets it;
5244 otherwise the unset will refer to the variable found in any calling scope
5245 as described above.
5246 If a variable at the current local scope is unset, it remains so
5247 (appearing as unset)
5248 until it is reset in that scope or until the function returns.
5249 Once the function returns, any instance of the variable at a previous
5250 scope becomes visible.
5251 If the unset acts on a variable at a previous scope, any instance of a
5252 variable with that name that had been shadowed becomes visible
5253 (see below how the \fBlocalvar_unset\fP shell option changes this behavior).
5254 .PP
5255 The
5256 .SM
5257 .B FUNCNEST
5258 variable, if set to a numeric value greater
5259 than 0, defines a maximum function nesting level.
5260 Function invocations that exceed the limit cause the entire command to
5261 abort.
5262 .PP
5263 If the builtin command
5264 .B return
5265 is executed in a function, the function completes and
5266 execution resumes with the next command after the function
5267 call.
5268 If \fBreturn\fP is supplied a numeric argument,
5269 that is the function's return status; otherwise the function's
5270 return status is the exit status of the last command executed
5271 before the \fBreturn\fP.
5272 Any command associated with the \fBRETURN\fP trap is executed
5273 before execution resumes.
5274 When a function completes, the values of the
5275 positional parameters and the special parameter
5276 .B #
5277 are restored to the values they had prior to the function's
5278 execution.
5279 .PP
5280 The
5281 .B \-f
5282 option to the
5283 .B declare
5284 or
5285 .B typeset
5286 builtin commands
5287 lists function names and definitions.
5288 The
5289 .B \-F
5290 option to
5291 .B declare
5292 or
5293 .B typeset
5294 lists the function names only
5295 (and optionally the source file and line number, if the \fBextdebug\fP
5296 shell option is enabled).
5297 Functions may be exported so that child shell processes
5298 (those created when executing a separate shell invocation)
5299 automatically have them defined with the
5300 .B \-f
5301 option to the
5302 .B export
5303 builtin.
5304 The \fB\-f\fP option to
5305 the
5306 .B unset
5307 builtin deletes a function definition.
5308 .PP
5309 Functions may be recursive.
5310 The \fBFUNCNEST\fP variable may be used to limit the depth of the
5311 function call stack and restrict the number of function invocations.
5312 By default, \fBbash\fP imposes no limit on the number of recursive calls.
5313 .SH "ARITHMETIC EVALUATION"
5314 The shell allows arithmetic expressions to be evaluated, under
5315 certain circumstances
5316 (see the \fBlet\fP and \fBdeclare\fP builtin commands,
5317 the \fB((\fP compound command,
5318 the arithmetic \fBfor\fP command,
5319 the \fB[[\fP conditional command,
5320 and \fBArithmetic Expansion\fP).
5321 .PP
5322 Evaluation is done in the largest fixed-width integers available,
5323 with no check for overflow,
5324 though division by 0 is trapped and flagged as an error.
5325 The operators and their precedence, associativity, and values
5326 are the same as in the C language.
5327 The following list of operators is grouped into levels of
5328 equal-precedence operators.
5329 The levels are listed in order of decreasing precedence.
5330 .PP
5331 .PD 0
5332 .TP
5333 .B \fIid\fP++ \fIid\fP\-\-
5334 variable post-increment and post-decrement
5335 .TP
5336 .B ++\fIid\fP \-\-\fIid\fP
5337 variable pre-increment and pre-decrement
5338 .TP
5339 .B \- +
5340 unary minus and plus
5341 .TP
5342 .B ! \*~
5343 logical and bitwise negation
5344 .TP
5345 .B **
5346 exponentiation
5347 .TP
5348 .B * / %
5349 multiplication, division, remainder
5350 .TP
5351 .B + \-
5352 addition, subtraction
5353 .TP
5354 .B << >>
5355 left and right bitwise shifts
5356 .TP
5357 .B <= >= < >
5358 comparison
5359 .TP
5360 .B == !=
5361 equality and inequality
5362 .TP
5363 .B &
5364 bitwise AND
5365 .TP
5366 .B \*^
5367 bitwise exclusive OR
5368 .TP
5369 .B |
5370 bitwise OR
5371 .TP
5372 .B &&
5373 logical AND
5374 .TP
5375 .B ||
5376 logical OR
5377 .TP
5378 .B \fIexpr\fP?\fIexpr\fP:\fIexpr\fP
5379 conditional operator
5380 .TP
5381 .B "= *= /= %= += \-= <<= >>= &= \*^= |="
5382 assignment
5383 .TP
5384 .B \fIexpr1\fP , \fIexpr2\fP
5385 comma
5386 .PD
5387 .PP
5388 Shell variables are allowed as operands; parameter expansion is
5389 performed before the expression is evaluated.
5390 Within an expression, shell variables may also be referenced by name
5391 without using the parameter expansion syntax.
5392 This means you can use "x", where \fIx\fP is a shell variable name,
5393 in an arithmetic expression, and the shell will evaluate its value as
5394 an expression and use the result.
5395 A shell variable that is null or unset evaluates to 0 when referenced
5396 by name in an expression.
5397 .PP
5398 The value of a variable is evaluated as an arithmetic expression
5399 when it is referenced, or when a variable which has been given the
5400 \fIinteger\fP attribute using \fBdeclare \-i\fP is assigned a value.
5401 A null value evaluates to 0.
5402 A shell variable need not have its \fIinteger\fP attribute
5403 turned on to be used in an expression.
5404 .PP
5405 Integer constants follow the C language definition, without suffixes or
5406 character constants.
5407 Constants with a leading 0 are interpreted as octal numbers.
5408 A leading 0x or 0X denotes hexadecimal.
5409 Otherwise, numbers take the form [\fIbase#\fP]n, where the optional \fIbase\fP
5410 is a decimal number between 2 and 64 representing the arithmetic
5411 base, and \fIn\fP is a number in that base.
5412 If \fIbase#\fP is omitted, then base 10 is used.
5413 When specifying \fIn\fP,
5414 if a non-digit is required,
5415 the digits greater than 9 are represented by the lowercase letters,
5416 the uppercase letters, @, and _, in that order.
5417 If \fIbase\fP is less than or equal to 36, lowercase and uppercase
5418 letters may be used interchangeably to represent numbers between 10
5419 and 35.
5420 .PP
5421 Operators are evaluated in precedence order.
5422 Sub-expressions in parentheses are evaluated first
5423 and may override the precedence rules above.
5424 .SH "CONDITIONAL EXPRESSIONS"
5425 Conditional expressions are used by the \fB[[\fP compound command and
5426 the \fBtest\fP and \fB[\fP builtin commands to test file attributes
5427 and perform string and arithmetic comparisons.
5428 The \fBtest\fP and \fB[\fP commands determine their behavior based on
5429 the number of arguments; see the descriptions of those commands for any
5430 other command-specific actions.
5431 .PP
5432 Expressions are formed from the unary or binary primaries listed below.
5433 Unary expressions are often used to examine the status of a file
5434 or shell variable.
5435 Binary operators are used for string, numeric, and file attribute
5436 comparisons.
5437 .PP
5438 \fBBash\fP handles several filenames specially when they are used in
5439 expressions.
5440 If the operating system on which \fBbash\fP is running provides these
5441 special files, bash will use them; otherwise it will emulate them
5442 internally with this behavior:
5443 If any \fIfile\fP argument to one of the primaries is of the form
5444 .FN /dev/fd/n ,
5445 then \fBbash\fP checks file descriptor \fIn\fP.
5446 If the \fIfile\fP argument to one of the primaries is one of
5447 .FN /dev/stdin ,
5448 .FN /dev/stdout ,
5449 or
5450 .FN /dev/stderr ,
5451 \fBbash\fP checks file descriptor 0, 1, or 2, respectively.
5452 .PP
5453 Unless otherwise specified, primaries that operate on files follow symbolic
5454 links and operate on the target of the link, rather than the link itself.
5455 .PP
5456 When used with \fB[[\fP,
5457 or when the shell is in posix mode,
5458 the \fB<\fP and \fB>\fP operators sort
5459 lexicographically using the current locale.
5460 When the shell is not in posix mode,
5461 the \fBtest\fP command sorts using ASCII ordering.
5462 .PP
5463 .PD 0
5464 .TP
5465 .B \-a \fIfile\fP
5466 True if \fIfile\fP exists.
5467 .TP
5468 .B \-b \fIfile\fP
5469 True if \fIfile\fP exists and is a block special file.
5470 .TP
5471 .B \-c \fIfile\fP
5472 True if \fIfile\fP exists and is a character special file.
5473 .TP
5474 .B \-d \fIfile\fP
5475 True if \fIfile\fP exists and is a directory.
5476 .TP
5477 .B \-e \fIfile\fP
5478 True if \fIfile\fP exists.
5479 .TP
5480 .B \-f \fIfile\fP
5481 True if \fIfile\fP exists and is a regular file.
5482 .TP
5483 .B \-g \fIfile\fP
5484 True if \fIfile\fP exists and is set-group-id.
5485 .TP
5486 .B \-h \fIfile\fP
5487 True if \fIfile\fP exists and is a symbolic link.
5488 .TP
5489 .B \-k \fIfile\fP
5490 True if \fIfile\fP exists and its
5491 .Q sticky
5492 bit is set.
5493 .TP
5494 .B \-p \fIfile\fP
5495 True if \fIfile\fP exists and is a named pipe (FIFO).
5496 .TP
5497 .B \-r \fIfile\fP
5498 True if \fIfile\fP exists and is readable.
5499 .TP
5500 .B \-s \fIfile\fP
5501 True if \fIfile\fP exists and has a size greater than zero.
5502 .TP
5503 .B \-t \fIfd\fP
5504 True if file descriptor
5505 .I fd
5506 is open and refers to a terminal.
5507 .TP
5508 .B \-u \fIfile\fP
5509 True if \fIfile\fP exists and its set-user-id bit is set.
5510 .TP
5511 .B \-w \fIfile\fP
5512 True if \fIfile\fP exists and is writable.
5513 .TP
5514 .B \-x \fIfile\fP
5515 True if \fIfile\fP exists and is executable.
5516 .TP
5517 .B \-G \fIfile\fP
5518 True if \fIfile\fP exists and is owned by the effective group id.
5519 .TP
5520 .B \-L \fIfile\fP
5521 True if \fIfile\fP exists and is a symbolic link.
5522 .TP
5523 .B \-N \fIfile\fP
5524 True if \fIfile\fP exists and has been modified since it was last
5525 accessed.
5526 .TP
5527 .B \-O \fIfile\fP
5528 True if \fIfile\fP exists and is owned by the effective user id.
5529 .TP
5530 .B \-S \fIfile\fP
5531 True if \fIfile\fP exists and is a socket.
5532 .TP
5533 .B \-o \fIoptname\fP
5534 True if the shell option
5535 .I optname
5536 is enabled.
5537 See the list of options under the description of the
5538 .B \-o
5539 option to the
5540 .B set
5541 builtin below.
5542 .TP
5543 .B \-v \fIvarname\fP
5544 True if the shell variable
5545 .I varname
5546 is set (has been assigned a value).
5547 If \fIvarname\fP is an indexed
5548 array variable name subscripted by \fI@\fP or \fI*\fP,
5549 this returns true if the array has any set elements.
5550 If \fIvarname\fP is an associative
5551 array variable name subscripted by \fI@\fP or \fI*\fP,
5552 this returns true if an element with that key is set.
5553 .TP
5554 .B \-R \fIvarname\fP
5555 True if the shell variable
5556 .I varname
5557 is set and is a name reference.
5558 .TP
5559 .B \-z \fIstring\fP
5560 True if the length of \fIstring\fP is zero.
5561 .TP
5562 \fIstring\fP
5563 .TP
5564 .B \-n \fIstring\fP
5565 True if the length of
5566 .I string
5567 is non-zero.
5568 .PD
5569 .TP
5570 \fIstring1\fP \fB==\fP \fIstring2\fP
5571 .PD 0
5572 .TP
5573 \fIstring1\fP \fB=\fP \fIstring2\fP
5574 True if the strings are equal.
5575 \fB=\fP should be used with the \fBtest\fP command for
5576 .SM POSIX
5577 conformance.
5578 When used with the \fB[[\fP command, this performs pattern matching as
5579 described above (\fBCompound Commands\fP).
5580 .TP
5581 \fIstring1\fP \fB!=\fP \fIstring2\fP
5582 True if the strings are not equal.
5583 .TP
5584 \fIstring1\fP \fB<\fP \fIstring2\fP
5585 True if \fIstring1\fP sorts before \fIstring2\fP lexicographically.
5586 .TP
5587 \fIstring1\fP \fB>\fP \fIstring2\fP
5588 True if \fIstring1\fP sorts after \fIstring2\fP lexicographically.
5589 .PD
5590 .TP
5591 .PD 0
5592 \fIfile1\fP \fB\-ef\fP \fIfile2\fP
5593 True if \fIfile1\fP and \fIfile2\fP refer to the same device and
5594 inode numbers.
5595 .TP
5596 \fIfile1\fP \-\fBnt\fP \fIfile2\fP
5597 True if \fIfile1\fP is newer (according to modification date) than \fIfile2\fP,
5598 or if \fIfile1\fP exists and \fPfile2\fP does not.
5599 .TP
5600 \fIfile1\fP \-\fBot\fP \fIfile2\fP
5601 True if \fIfile1\fP is older than \fIfile2\fP, or if \fIfile2\fP exists
5602 and \fIfile1\fP does not.
5603 .PD
5604 .TP
5605 .I \fIarg1\fP \fBOP\fP \fIarg2\fP
5606 .SM
5607 .B OP
5608 is one of
5609 .BR \-eq ,
5610 .BR \-ne ,
5611 .BR \-lt ,
5612 .BR \-le ,
5613 .BR \-gt ,
5614 or
5615 .BR \-ge .
5616 These arithmetic binary operators return true if \fIarg1\fP
5617 is equal to, not equal to, less than, less than or equal to,
5618 greater than, or greater than or equal to \fIarg2\fP, respectively.
5619 .I arg1
5620 and
5621 .I arg2
5622 may be positive or negative integers.
5623 When used with the \fB[[\fP command,
5624 .I arg1
5625 and
5626 .I arg2
5627 are evaluated as arithmetic expressions (see
5628 .SM
5629 .B "ARITHMETIC EVALUATION"
5630 above).
5631 Since the expansions the \fB[[\fP command performs on
5632 .I arg1
5633 and
5634 .I arg2
5635 can potentially result in empty strings,
5636 arithmetic expression evaluation treats
5637 those as expressions that evaluate to 0.
5638 .PD
5639 .SH "SIMPLE COMMAND EXPANSION"
5640 When the shell executes a simple command, it performs the following
5641 expansions, assignments, and redirections, from left to right, in
5642 the following order.
5643 .IP 1.
5644 The words that the parser has marked as variable assignments (those
5645 preceding the command name) and redirections are saved for later
5646 processing.
5647 .IP 2.
5648 The words that are not variable assignments or redirections are
5649 expanded.
5650 If any words remain after expansion, the first word
5651 is taken to be the name of the command and the remaining words are
5652 the arguments.
5653 .IP 3.
5654 Redirections are performed as described above under
5655 .SM
5656 .BR REDIRECTION .
5657 .IP 4.
5658 The text after the \fB=\fP in each variable assignment undergoes tilde
5659 expansion, parameter expansion, command substitution, arithmetic expansion,
5660 and quote removal before being assigned to the variable.
5661 .PP
5662 If no command name results, the variable assignments affect the current
5663 shell environment.
5664 In the case of such a command (one that consists only of assignment
5665 statements and redirections), assignment statements are performed before
5666 redirections.
5667 Otherwise, the variables are added to the environment
5668 of the executed command and do not affect the current shell environment.
5669 If any of the assignments attempts to assign a value to a readonly variable,
5670 an error occurs, and the command exits with a non-zero status.
5671 .PP
5672 If no command name results, redirections are performed, but do not
5673 affect the current shell environment.
5674 A redirection error causes the command to exit with a non-zero status.
5675 .PP
5676 If there is a command name left after expansion, execution proceeds as
5677 described below.
5678 Otherwise, the command exits.
5679 If one of the expansions contained a command substitution,
5680 the exit status of the command is the exit status of
5681 the last command substitution performed.
5682 If there were no command substitutions,
5683 the command exits with a zero status.
5684 .SH "COMMAND EXECUTION"
5685 After a command has been split into words, if it results in a
5686 simple command and an optional list of arguments, the shell performs
5687 the following actions.
5688 .PP
5689 If the command name contains no slashes, the shell attempts to
5690 locate it.
5691 If there exists a shell function by that name, that function is
5692 invoked as described above in
5693 .SM
5694 .BR FUNCTIONS .
5695 If the name does not match a function, the shell searches for
5696 it in the list of shell builtins.
5697 If a match is found, that builtin is invoked.
5698 .PP
5699 If the name is neither a shell function nor a builtin,
5700 and contains no slashes,
5701 .B bash
5702 searches each element of the
5703 .SM
5704 .B PATH
5705 for a directory containing an executable file by that name.
5706 .B Bash
5707 uses a hash table to remember the full pathnames of executable
5708 files (see
5709 .B hash
5710 under
5711 .SM
5712 .B "SHELL BUILTIN COMMANDS"
5713 below).
5714 Bash performs a full search of the directories in
5715 .SM
5716 .B PATH
5717 only if the command is not found in the hash table.
5718 If the search is unsuccessful, the shell searches for a defined shell
5719 function named \fBcommand_not_found_handle\fP.
5720 If that function exists, it is invoked in a separate execution environment
5721 with the original command and
5722 the original command's arguments as its arguments, and the function's
5723 exit status becomes the exit status of that subshell.
5724 If that function is not defined, the shell prints an error
5725 message and returns an exit status of 127.
5726 .PP
5727 If the search is successful, or if the command name contains
5728 one or more slashes, the shell executes the named program in a
5729 separate execution environment.
5730 Argument 0 is set to the name given, and the remaining arguments
5731 to the command are set to the arguments given, if any.
5732 .PP
5733 If this execution fails because the file is not in executable
5734 format, and the file is not a directory, it is assumed to be
5735 a \fIshell script\fP, a file containing shell commands,
5736 and the shell creates a new instance of itself to execute it.
5737 Bash tries to determine whether the file is a text file or a binary,
5738 and will not execute files it determines to be binaries.
5739 This subshell reinitializes itself, so
5740 that the effect is as if a new shell had been invoked
5741 to handle the script, with the exception that the locations of
5742 commands remembered by the parent (see
5743 .B hash
5744 below under
5745 .SM
5746 .B "SHELL BUILTIN COMMANDS"
5747 are retained by the child.
5748 .PP
5749 If the program is a file beginning with
5750 .BR #! ,
5751 the remainder of the first line specifies an interpreter
5752 for the program.
5753 The shell executes the
5754 specified interpreter on operating systems that do not
5755 handle this executable format themselves.
5756 The arguments to the
5757 interpreter consist of a single optional argument following the
5758 interpreter name on the first line of the program, followed
5759 by the name of the program, followed by the command
5760 arguments, if any.
5761 .SH "COMMAND EXECUTION ENVIRONMENT"
5762 The shell has an \fIexecution environment\fP, which consists of the
5763 following:
5764 .IP \(bu
5765 Open files inherited by the shell at invocation, as modified by
5766 redirections supplied to the \fBexec\fP builtin.
5767 .IP \(bu
5768 The current working directory as set by \fBcd\fP, \fBpushd\fP, or
5769 \fBpopd\fP, or inherited by the shell at invocation.
5770 .IP \(bu
5771 The file creation mode mask as set by \fBumask\fP or inherited from
5772 the shell's parent.
5773 .IP \(bu
5774 Current traps set by \fBtrap\fP.
5775 .IP \(bu
5776 Shell parameters that are set by variable assignment or with \fBset\fP
5777 or inherited from the shell's parent in the environment.
5778 .IP \(bu
5779 Shell functions defined during execution or inherited from the shell's
5780 parent in the environment.
5781 .IP \(bu
5782 Options enabled at invocation (either by default or with command-line
5783 arguments) or by \fBset\fP.
5784 .IP \(bu
5785 Options enabled by \fBshopt\fP.
5786 .IP \(bu
5787 Shell aliases defined with \fBalias\fP.
5788 .IP \(bu
5789 Various process IDs, including those of background jobs, the value
5790 of \fB$$\fP, and the value of
5791 .SM
5792 .BR PPID .
5793 .PP
5794 When a simple command other than a builtin or shell function
5795 is to be executed, it
5796 is invoked in a separate execution environment that consists of
5797 the following.
5798 Unless otherwise noted, the values are inherited from the shell.
5799 .IP \(bu
5800 The shell's open files, plus any modifications and additions specified
5801 by redirections to the command.
5802 .IP \(bu
5803 The current working directory.
5804 .IP \(bu
5805 The file creation mode mask.
5806 .IP \(bu
5807 Shell variables and functions marked for export, along with variables
5808 exported for the command, passed in the environment.
5809 .IP \(bu
5810 Traps caught by the shell are reset to the values inherited from the
5811 shell's parent, and traps ignored by the shell are ignored.
5812 .PP
5813 A command invoked in this separate environment cannot affect the
5814 shell's execution environment.
5815 .PP
5816 A \fIsubshell\fP is a copy of the shell process.
5817 .PP
5818 Command substitution, commands grouped with parentheses,
5819 and asynchronous commands are invoked in a
5820 subshell environment that is a duplicate of the shell environment,
5821 except that traps caught by the shell are reset to the values
5822 that the shell inherited from its parent at invocation.
5823 Builtin commands that are invoked as part of a pipeline,
5824 except possibly in the last element depending on the value of the
5825 \fBlastpipe\fP shell option,
5826 are also executed in a subshell environment.
5827 Changes made to the subshell environment
5828 cannot affect the shell's execution environment.
5829 .PP
5830 When the shell is in posix mode,
5831 subshells spawned to execute command substitutions inherit the value of
5832 the \fB\-e\fP option from their parent shell.
5833 When not in posix mode,
5834 \fBbash\fP clears the \fB\-e\fP option in such subshells.
5835 See the
5836 description of the \fBinherit_errexit\fP shell option below
5837 for how to control this behavior when not in posix mode.
5838 .PP
5839 If a command is followed by a \fB&\fP and job control is not active, the
5840 default standard input for the command is the empty file
5841 .FN /dev/null .
5842 Otherwise, the invoked command inherits the file descriptors of the calling
5843 shell as modified by redirections.
5844 .SH ENVIRONMENT
5845 When a program is invoked it is given an array of strings
5846 called the
5847 .IR environment .
5848 This is a list of
5849 \fIname\fP\-\fIvalue\fP pairs, of the form
5850 .IR "name\fR=\fPvalue" .
5851 .PP
5852 The shell provides several ways to manipulate the environment.
5853 On invocation, the shell scans its own environment and
5854 creates a parameter for each name found, automatically marking
5855 it for
5856 .I export
5857 to child processes.
5858 Executed commands inherit the environment.
5859 The
5860 .BR export ,
5861 .BR "declare \-x" ,
5862 and
5863 .B unset
5864 commands modify the environment by
5865 adding and deleting parameters and functions.
5866 If the value of a parameter
5867 in the environment is modified, the new value automatically
5868 becomes part of the environment, replacing the old.
5869 The environment
5870 inherited by any executed command consists of the shell's
5871 initial environment, whose values may be modified in the shell,
5872 less any pairs removed by the
5873 .B unset
5874 or
5875 .B "export \-n"
5876 commands, plus any additions via the
5877 .B export
5878 and
5879 .B "declare \-x"
5880 commands.
5881 .PP
5882 If any parameter assignments, as described above in
5883 .SM
5884 .BR PARAMETERS ,
5885 appear before a
5886 .IR "simple command" ,
5887 the variable assignments are part of that command's environment
5888 for as long as it executes.
5889 These assignment statements affect only the environment seen
5890 by that command.
5891 If these assignments precede a call to a shell function, the variables
5892 are local to the function and exported to that function's children.
5893 .PP
5894 If the
5895 .B \-k
5896 option is set (see the
5897 .B set
5898 builtin command below), then
5899 .I all
5900 parameter assignments are placed in the environment for a command,
5901 not just those that precede the command name.
5902 .PP
5903 When
5904 .B bash
5905 invokes an external command, the variable
5906 .B _
5907 is set to the full pathname of the command and passed to that
5908 command in its environment.
5909 .SH "EXIT STATUS"
5910 The exit status of an executed command is the value returned by the
5911 \fIwaitpid\fP system call or equivalent function.
5912 Exit statuses fall between 0 and 255, though, as explained below,
5913 the shell may use values above 125 specially.
5914 Exit statuses from shell builtins and compound commands are also
5915 limited to this range.
5916 Under certain circumstances, the shell will use special values to
5917 indicate specific failure modes.
5918 .PP
5919 For the shell's purposes, a command which exits with a
5920 zero exit status has succeeded.
5921 So while an exit status of zero indicates success, a non-zero
5922 exit status indicates failure.
5923 .PP
5924 When a command terminates on a fatal signal \fIN\fP, \fBbash\fP uses
5925 the value of 128+\fIN\fP as the exit status.
5926 .PP
5927 If a command is not found, the child process created to
5928 execute it returns a status of 127. If a command is found
5929 but is not executable, the return status is 126.
5930 .PP
5931 If a command fails because of an error during expansion or redirection,
5932 the exit status is greater than zero.
5933 .PP
5934 Shell builtin commands return a status of 0 (\fItrue\fP) if
5935 successful, and non-zero (\fIfalse\fP) if an error occurs
5936 while they execute.
5937 All builtins return an exit status of 2 to indicate incorrect usage,
5938 generally invalid options or missing arguments.
5939 .PP
5940 The exit status of the last command is available in the special
5941 parameter $?.
5942 .PP
5943 \fBBash\fP itself returns the exit status of the last command
5944 executed, unless a syntax error occurs, in which case it exits
5945 with a non-zero value.
5946 See also the \fBexit\fP builtin command below.
5947 .SH SIGNALS
5948 When \fBbash\fP is interactive, in the absence of any traps, it ignores
5949 .SM
5950 .B SIGTERM
5951 (so that \fBkill 0\fP does not kill an interactive shell),
5952 and catches and handles
5953 .SM
5954 .B SIGINT
5955 (so that the \fBwait\fP builtin is interruptible).
5956 When \fBbash\fP receives
5957 .SM
5958 .BR SIGINT ,
5959 it breaks out of any executing loops.
5960 In all cases, \fBbash\fP ignores
5961 .SM
5962 .BR SIGQUIT .
5963 If job control is in effect,
5964 .B bash
5965 ignores
5966 .SM
5967 .BR SIGTTIN ,
5968 .SM
5969 .BR SIGTTOU ,
5970 and
5971 .SM
5972 .BR SIGTSTP .
5973 .PP
5974 The \fBtrap\fP builtin modifies the shell's signal handling, as
5975 described below.
5976 .PP
5977 Non-builtin commands \fBbash\fP executes have signal handlers
5978 set to the values inherited by the shell from its parent,
5979 unless \fBtrap\fP sets them to be ignored, in which case the child
5980 process will ignore them as well.
5981 When job control is not in effect, asynchronous commands
5982 ignore
5983 .SM
5984 .B SIGINT
5985 and
5986 .SM
5987 .B SIGQUIT
5988 in addition to these inherited handlers.
5989 Commands run as a result of command substitution ignore the
5990 keyboard-generated job control signals
5991 .SM
5992 .BR SIGTTIN ,
5993 .SM
5994 .BR SIGTTOU ,
5995 and
5996 .SM
5997 .BR SIGTSTP .
5998 .PP
5999 The shell exits by default upon receipt of a
6000 .SM
6001 .BR SIGHUP .
6002 Before exiting, an interactive shell resends the
6003 .SM
6004 .B SIGHUP
6005 to all jobs, running or stopped.
6006 The shell sends
6007 .SM
6008 .B SIGCONT
6009 to stopped jobs to ensure that they receive the
6010 .SM
6011 .B SIGHUP
6012 (see
6013 .SM
6014 .B "JOB CONTROL"
6015 below for more information about running and stopped jobs).
6016 To prevent the shell from
6017 sending the signal to a particular job, remove it from the
6018 jobs table with the
6019 .B disown
6020 builtin (see
6021 .SM
6022 .B "SHELL BUILTIN COMMANDS"
6023 below) or mark it not to receive
6024 .SM
6025 .B SIGHUP
6026 using
6027 .BR "disown \-h" .
6028 .PP
6029 If the
6030 .B huponexit
6031 shell option has been set using
6032 .BR shopt ,
6033 .B bash
6034 sends a
6035 .SM
6036 .B SIGHUP
6037 to all jobs when an interactive login shell exits.
6038 .PP
6039 If \fBbash\fP is waiting for a command to complete and receives a signal
6040 for which a trap has been set,
6041 it will not execute the trap until the command completes.
6042 If \fBbash\fP is waiting for an asynchronous command via the \fBwait\fP
6043 builtin,
6044 and it receives a signal for which a trap has been set,
6045 the \fBwait\fP builtin will return immediately with an exit status
6046 greater than 128, immediately after which the shell executes the trap.
6047 .PP
6048 When job control is not enabled, and \fBbash\fP is waiting for a foreground
6049 command to complete, the shell receives keyboard-generated signals
6050 such as
6051 .SM
6052 .B SIGINT
6053 (usually generated by \fB\*^C\fP) that users commonly intend to send
6054 to that command.
6055 This happens because the shell and the command are in the
6056 same process group as the terminal, and \fB\*^C\fP sends
6057 .SM
6058 .B SIGINT
6059 to all processes in that process group.
6060 Since \fBbash\fP does not enable job control by default when the
6061 shell is not interactive,
6062 this scenario is most common in non-interactive shells.
6063 .PP
6064 When job control is enabled, and \fBbash\fP is waiting for a foreground
6065 command to complete, the shell does not receive keyboard-generated
6066 signals, because it is not in the same process group as the terminal.
6067 This scenario is most common in interactive shells, where \fBbash\fP
6068 attempts to enable job control by default.
6069 See
6070 .SM
6071 .B "JOB CONTROL"
6072 below for more information about process groups.
6073 .PP
6074 When job control is not enabled, and \fBbash\fP receives
6075 .SM
6076 .B SIGINT
6077 while waiting for a foreground command, it waits until that foreground
6078 command terminates and then decides what to do about the
6079 .SM
6080 .BR SIGINT :
6081 .IP 1.
6082 If the command terminates due to the
6083 .SM
6084 .BR SIGINT ,
6085 \fBbash\fP concludes
6086 that the user meant to send the
6087 .SM
6088 .B SIGINT
6089 to the shell as well, and acts on the
6090 .SM
6091 .B SIGINT
6092 (e.g., by running a
6093 .SM
6094 .B SIGINT
6095 trap,
6096 exiting a non-interactive shell,
6097 or returning to the top level to read a new command).
6098 .IP 2.
6099 If the command does not terminate due to
6100 .SM
6101 .BR SIGINT ,
6102 the program handled the
6103 .SM
6104 .B SIGINT
6105 itself and did not treat it as a fatal signal.
6106 In that case, \fBbash\fP does not treat
6107 .SM
6108 .B SIGINT
6109 as a fatal signal, either, instead assuming that the
6110 .SM
6111 .B SIGINT
6112 was used as part of the program's normal operation
6113 (e.g., emacs uses it to abort editing
6114 commands) or deliberately discarded.
6115 However, \fBbash\fP will run any
6116 trap set on
6117 .SM
6118 .BR SIGINT ,
6119 as it does with any other trapped signal it
6120 receives while it is waiting for the foreground command to
6121 complete, for compatibility.
6122 .PP
6123 When job control is enabled, \fBbash\fP does not receive keyboard-generated
6124 signals such as
6125 .SM
6126 .B SIGINT
6127 while it is waiting for a foreground command.
6128 An interactive shell does not pay attention to the
6129 .SM
6130 .BR SIGINT ,
6131 even if the foreground command terminates as a result, other than noting
6132 its exit status.
6133 If the shell is not interactive, and
6134 the foreground command terminates due to the
6135 .SM
6136 .BR SIGINT ,
6137 \fBbash\fP pretends it received the
6138 .SM
6139 .B SIGINT
6140 itself (scenario 1 above), for compatibility.
6141 .SH "JOB CONTROL"
6142 .I Job control
6143 refers to the ability to selectively stop (\fIsuspend\fP)
6144 the execution of processes and continue (\fIresume\fP)
6145 their execution at a later point.
6146 A user typically employs
6147 this facility via an interactive interface supplied jointly
6148 by the operating system kernel's terminal driver and
6149 .BR bash .
6150 .PP
6151 The shell associates a
6152 .I job
6153 with each pipeline.
6154 It keeps a table of currently executing
6155 jobs, which the
6156 .B jobs
6157 command will display.
6158 Each job has a \fIjob number\fP, which \fBjobs\fP displays between brackets.
6159 Job numbers start at 1.
6160 When
6161 .B bash
6162 starts a job asynchronously (in the
6163 .IR background ),
6164 it prints a line that looks like:
6165 .RS
6166 .PP
6167 [1] 25647
6168 .RE
6169 .PP
6170 indicating that this job is job number 1 and that the process ID
6171 of the last process in the pipeline associated with this job is 25647.
6172 All of the processes in a single pipeline are members of the same job.
6173 .B Bash
6174 uses the
6175 .I job
6176 abstraction as the basis for job control.
6177 .PP
6178 To facilitate the implementation of the user interface to job control,
6179 each process has a \fIprocess group ID\fP, and
6180 the operating system maintains the notion of a \fIcurrent terminal
6181 process group ID\fP.
6182 This terminal process group ID is associated with the
6183 \fIcontrolling terminal\fP.
6184 .PP
6185 Processes that have the same process group ID are said to be part of
6186 the same \fIprocess group\fP.
6187 Members of the \fIforeground\fP process group (processes whose
6188 process group ID is equal to the current terminal process group ID)
6189 receive keyboard-generated signals such as
6190 .SM
6191 .BR SIGINT .
6192 Processes in the foreground process group are said to be
6193 .I foreground
6194 processes.
6195 .I Background
6196 processes are those whose process group ID differs from the
6197 controlling terminal's;
6198 such processes are immune to keyboard-generated signals.
6199 Only foreground processes are allowed to read from or,
6200 if the user so specifies with
6201 .Q "stty tostop" ,
6202 write to the controlling terminal.
6203 The system sends a
6204 .SM
6205 .B "SIGTTIN (SIGTTOU)"
6206 signal to background processes which attempt to
6207 read from (write to when
6208 .Q tostop
6209 is in effect)
6210 the terminal,
6211 which, unless caught, suspends the process.
6212 .PP
6213 If the operating system on which
6214 .B bash
6215 is running supports
6216 job control,
6217 .B bash
6218 contains facilities to use it.
6219 Typing the
6220 .I suspend
6221 character (typically
6222 .BR \*^Z ,
6223 Control-Z) while a process is running
6224 stops that process and returns control to
6225 .BR bash .
6226 Typing the
6227 .I "delayed suspend"
6228 character (typically
6229 .BR \*^Y ,
6230 Control-Y) causes the process stop when it
6231 attempts to read input from the terminal, and returns control to
6232 .BR bash .
6233 The user then manipulates the state of this job, using the
6234 .B bg
6235 command to continue it in the background, the
6236 .B fg
6237 command to continue it in the foreground, or the
6238 .B kill
6239 command to kill it.
6240 The suspend character takes effect immediately,
6241 and has the additional side effect of discarding any pending output
6242 and typeahead.
6243 To force a background process to stop, or stop a process
6244 that's not associated with the current terminal session,
6245 send it the
6246 .SM
6247 .B SIGSTOP
6248 signal using \fBkill\fP.
6249 .PP
6250 There are a number of ways to refer to a job in the shell.
6251 The
6252 .B %
6253 character introduces a job specification (jobspec).
6254 .PP
6255 Job number
6256 .I n
6257 may be referred to as
6258 .BR %n .
6259 A job may also be referred to using a prefix of the name used to
6260 start it, or using a substring that appears in its command line.
6261 For example,
6262 .B %ce
6263 refers to a job whose command name begins with
6264 .BR ce .
6265 Using
6266 .BR %?ce ,
6267 on the other hand, refers to any job containing the string
6268 .B ce
6269 in its command line.
6270 If the prefix or substring matches more than one job,
6271 .B bash
6272 reports an error.
6273 .PP
6274 The symbols
6275 .B %%
6276 and
6277 .B %+
6278 refer to the shell's notion of the
6279 .IR "current job" .
6280 A single % (with no accompanying job specification) also refers to the
6281 current job.
6282 .B %\-
6283 refers to the
6284 .IR "previous job" .
6285 When a job starts in the background,
6286 a job stops while in the foreground,
6287 or a job is resumed in the background,
6288 it becomes the current job.
6289 The job that was the current job becomes the previous job.
6290 When the current job terminates, the previous job becomes the
6291 current job.
6292 If there is only a single job, \fB%+\fP and \fB%\-\fP can both be used
6293 to refer to that job.
6294 In output pertaining to jobs (e.g., the output of the
6295 .B jobs
6296 command), the current job is always marked with a
6297 .BR + ,
6298 and the previous job with a
6299 .BR \- .
6300 .PP
6301 Simply naming a job can be used to bring it into the foreground:
6302 .B %1
6303 is a synonym for
6304 .Q "fg %1" ,
6305 bringing job 1 from the background into the foreground.
6306 Similarly,
6307 .Q "%1 &"
6308 resumes job 1 in the background, equivalent to
6309 .Q "bg %1" .
6310 .PP
6311 The shell learns immediately whenever a job changes state.
6312 Normally,
6313 .B bash
6314 waits until it is about to print a prompt before
6315 notifying the user about
6316 changes in a job's status so as to not interrupt
6317 any other output,
6318 though it will notify of changes in a job's status after a
6319 foreground command in
6320 a list completes, before executing the next command in the list.
6321 If the
6322 .B \-b
6323 option to the
6324 .B set
6325 builtin command
6326 is enabled,
6327 .B bash
6328 reports status changes immediately.
6329 \fBBash\fP executes any trap on
6330 .SM
6331 .B SIGCHLD
6332 for each child that terminates.
6333 .PP
6334 When a job terminates and \fBbash\fP notifies the user about it,
6335 \fBbash\fP removes the job from the table.
6336 It will not appear in \fBjobs\fP output, but \fBwait\fP will
6337 report its exit status, as long as it's supplied the process ID
6338 associated with the job as an argument.
6339 When the table is empty, job numbers start over at 1.
6340 .PP
6341 If a user attempts to exit
6342 .B bash
6343 while jobs are stopped (or, if the \fBcheckjobs\fP shell option has
6344 been enabled using the \fBshopt\fP builtin, running), the shell prints a
6345 warning message, and, if the \fBcheckjobs\fP option is enabled, lists the
6346 jobs and their statuses.
6347 The
6348 .B jobs
6349 command may then be used to inspect their status.
6350 If the user immediately attempts to exit again,
6351 without an intervening command,
6352 \fBbash\fP does not print another warning, and
6353 terminates any stopped jobs.
6354 .PP
6355 When the shell is waiting for a job or process using the \fBwait\fP
6356 builtin, and job control is enabled, \fBwait\fP will return when the
6357 job changes state.
6358 The \fB\-f\fP option causes \fBwait\fP to wait
6359 until the job or process terminates before returning.
6360 .SH PROMPTING
6361 When executing interactively,
6362 .B bash
6363 displays the primary prompt
6364 .SM
6365 .B PS1
6366 when it is ready to read a command, and the secondary prompt
6367 .SM
6368 .B PS2
6369 when it needs more input to complete a command.
6370 .PP
6371 .B Bash
6372 examines the value of the array variable \fBPROMPT_COMMAND\fP just before
6373 printing each primary prompt.
6374 If any elements in \fBPROMPT_COMMAND\fP are set and non-null, Bash
6375 executes each value, in numeric order,
6376 just as if it had been typed on the command line.
6377 .B Bash
6378 displays
6379 .SM
6380 .B PS0
6381 after it reads a command but before executing it.
6382 .PP
6383 .B Bash
6384 displays
6385 .SM
6386 .B PS4
6387 as described above
6388 before tracing each command when the \fB\-x\fP option is enabled.
6389 .PP
6390 .B Bash
6391 allows the prompt strings
6392 \fBPS0\fP, \fBPS1\fP, \fBPS2\fP, and \fBPS4\fP,
6393 to be customized by inserting a number of
6394 backslash-escaped special characters that are decoded as follows:
6395 .RS
6396 .TP
6397 .B \ea
6398 An ASCII bell character (07).
6399 .PD 0
6400 .TP
6401 .B \ed
6402 The date in
6403 .Q "Weekday Month Date"
6404 format (e.g.,
6405 .Q "Tue May 26" ).
6406 .TP
6407 .B \eD{\fIformat\fP}
6408 The \fIformat\fP is passed to
6409 .IR strftime (3)
6410 and the result is inserted
6411 into the prompt string; an empty \fIformat\fP results in a locale-specific
6412 time representation.
6413 The braces are required.
6414 .TP
6415 .B \ee
6416 An ASCII escape character (033).
6417 .TP
6418 .B \eh
6419 The hostname up to the first
6420 .Q . .
6421 .TP
6422 .B \eH
6423 The hostname.
6424 .TP
6425 .B \ej
6426 The number of jobs currently managed by the shell.
6427 .TP
6428 .B \el
6429 The basename of the shell's terminal device name (e.g.,
6430 .Q ttys0 ).
6431 .TP
6432 .B \en
6433 A newline.
6434 .TP
6435 .B \er
6436 A carriage return.
6437 .TP
6438 .B \es
6439 The name of the shell: the basename of
6440 .B $0
6441 (the portion following the final slash).
6442 .TP
6443 .B \et
6444 The current time in 24-hour HH:MM:SS format.
6445 .TP
6446 .B \eT
6447 The current time in 12-hour HH:MM:SS format.
6448 .TP
6449 .B \e@
6450 The current time in 12-hour am/pm format.
6451 .TP
6452 .B \eA
6453 The current time in 24-hour HH:MM format.
6454 .TP
6455 .B \eu
6456 The username of the current user.
6457 .TP
6458 .B \ev
6459 The \fBbash\fP version (e.g., 2.00).
6460 .TP
6461 .B \eV
6462 The \fBbash\fP release, version + patch level (e.g., 2.00.0)
6463 .TP
6464 .B \ew
6465 The value of the \fBPWD\fP shell variable (\fB$PWD\fP),
6466 with
6467 .SM
6468 .B $HOME
6469 abbreviated with a tilde
6470 (uses the value of the
6471 .SM
6472 .B PROMPT_DIRTRIM
6473 variable).
6474 .TP
6475 .B \eW
6476 The basename of \fB$PWD\fP,
6477 with
6478 .SM
6479 .B $HOME
6480 abbreviated with a tilde.
6481 .TP
6482 .B \e!
6483 The history number of this command.
6484 .TP
6485 .B \e#
6486 The command number of this command.
6487 .TP
6488 .B \e$
6489 If the effective UID is 0, a
6490 .BR # ,
6491 otherwise a
6492 .BR $ .
6493 .TP
6494 .B \e\fInnn\fP
6495 The character corresponding to the octal number \fInnn\fP.
6496 .TP
6497 .B \e\e
6498 A backslash.
6499 .TP
6500 .B \e[
6501 Begin a sequence of non-printing characters, which could be used to
6502 embed a terminal control sequence into the prompt.
6503 .TP
6504 .B \e]
6505 End a sequence of non-printing characters.
6506 .PD
6507 .RE
6508 .PP
6509 The command number and the history number are usually different:
6510 the history number of a command is its position in the history
6511 list, which may include commands restored from the history file
6512 (see
6513 .SM
6514 .B HISTORY
6515 below), while the command number is the position in the sequence
6516 of commands executed during the current shell session.
6517 After the string is decoded, it is expanded via
6518 parameter expansion, command substitution, arithmetic
6519 expansion, and quote removal, subject to the value of the
6520 .B promptvars
6521 shell option (see the description of the
6522 .B shopt
6523 command under
6524 .SM
6525 .B "SHELL BUILTIN COMMANDS"
6526 below).
6527 This can have unwanted side effects if escaped portions of the string
6528 appear within command substitution or contain characters special to
6529 word expansion.
6530 .SH READLINE
6531 This is the library that handles reading input when using an interactive
6532 shell, unless the
6533 .B \-\-noediting
6534 option is supplied at shell invocation.
6535 Line editing is also used when using the \fB\-e\fP option to the
6536 \fBread\fP builtin.
6537 By default, the line editing commands are similar to those of emacs;
6538 a vi-style line editing interface is also available.
6539 Line editing can be enabled at any time using the
6540 .B \-o emacs
6541 or
6542 .B \-o vi
6543 options to the
6544 .B set
6545 builtin (see
6546 .SM
6547 .B "SHELL BUILTIN COMMANDS"
6548 below).
6549 To turn off line editing after the shell is running, use the
6550 .B +o emacs
6551 or
6552 .B +o vi
6553 options to the
6554 .B set
6555 builtin.
6556 .SS "Readline Notation"
6557 This section uses Emacs-style editing concepts and uses its
6558 notation for keystrokes.
6559 Control keys are denoted by C\-\fIkey\fP, e.g., C\-n means Control\-N.
6560 Similarly,
6561 .I meta
6562 keys are denoted by M\-\fIkey\fP, so M\-x means Meta\-X.
6563 The Meta key is often labeled
6564 .Q Alt
6565 or
6566 .Q Option .
6567 .PP
6568 On keyboards without a
6569 .I Meta
6570 key, M\-\fIx\fP means ESC \fIx\fP,
6571 i.e., press and release the Escape key,
6572 then press and release the
6573 .I x
6574 key, in sequence.
6575 This makes ESC the \fImeta prefix\fP.
6576 The combination M\-C\-\fIx\fP means ESC Control\-\fIx\fP:
6577 press and release the Escape key,
6578 then press and hold the Control key while pressing the
6579 .I x
6580 key, then release both.
6581 .PP
6582 On some keyboards, the Meta key modifier produces characters with
6583 the eighth bit (0200) set.
6584 You can use the \fBenable\-meta\-key\fP variable
6585 to control whether or not it does this, if the keyboard allows it.
6586 On many others, the terminal or terminal emulator converts the metafied
6587 key to a key sequence beginning with ESC as described in the
6588 preceding paragraph.
6589 .PP
6590 If your \fIMeta\fP key produces a key sequence with the ESC meta prefix,
6591 you can make M-\fIkey\fP key bindings you specify (see
6592 .B "Readline Key Bindings"
6593 below) do the same thing by setting the \fBforce\-meta\-prefix\fP variable.
6594 .PP
6595 .B Readline
6596 commands may be given numeric
6597 .IR arguments ,
6598 which normally act as a repeat count.
6599 Sometimes, however, it is the sign of the argument that is significant.
6600 Passing a negative argument
6601 to a command that acts in the forward direction (e.g., \fBkill\-line\fP)
6602 makes that command act in a backward direction.
6603 Commands whose behavior with arguments deviates from this are noted
6604 below.
6605 .PP
6606 The \fIpoint\fP is the current cursor position, and \fImark\fP refers
6607 to a saved cursor position.
6608 The text between the point and mark is referred to as the \fIregion\fP.
6609 \fBReadline\fP has the concept of an \fIactive region\fP:
6610 when the region is active, \fBreadline\fP redisplay
6611 highlights the region using the
6612 value of the \fBactive-region-start-color\fP variable.
6613 The \fBenable\-active\-region\fP variable turns this on and off.
6614 Several commands set the region to active; those are noted below.
6615 .PP
6616 When a command is described as \fIkilling\fP text, the text
6617 deleted is saved for possible future retrieval
6618 (\fIyanking\fP).
6619 The killed text is saved in a \fIkill ring\fP.
6620 Consecutive kills accumulate the deleted text
6621 into one unit, which can be yanked all at once.
6622 Commands which do not kill text separate the chunks of text
6623 on the kill ring.
6624 .SS "Readline Initialization"
6625 .B Readline
6626 is customized by putting commands in an initialization
6627 file (the \fIinputrc\fP file).
6628 The name of this file is taken from the value of the
6629 .SM
6630 .B \%INPUTRC
6631 shell variable.
6632 If that variable is unset, the default is
6633 .FN \*~/.inputrc .
6634 If that file does not exist or cannot be read, \fBreadline\fP looks for
6635 .FN /etc/inputrc .
6636 When a program that uses the \fBreadline\fP library starts up,
6637 \fBreadline\fP reads the initialization file
6638 and sets the key bindings and variables found there,
6639 before reading any user input.
6640 .PP
6641 There are only a few basic constructs allowed in the inputrc file.
6642 Blank lines are ignored.
6643 Lines beginning with a \fB#\fP are comments.
6644 Lines beginning with a \fB$\fP indicate conditional constructs.
6645 Other lines denote key bindings and variable settings.
6646 .PP
6647 The default key-bindings in this section
6648 may be changed using key binding commands in the
6649 .I inputrc
6650 file.
6651 Programs that use the \fBreadline\fP library, including \fBbash\fP,
6652 may add their own commands and bindings.
6653 .PP
6654 For example, placing
6655 .RS
6656 .PP
6657 M\-Control\-u: universal\-argument
6658 .RE
6659 or
6660 .RS
6661 C\-Meta\-u: universal\-argument
6662 .RE
6663 .LP
6664 into the
6665 .I inputrc
6666 would make M\-C\-u execute the \fBreadline\fP command
6667 .IR universal\-argument .
6668 .PP
6669 Key bindings may contain the following symbolic character names:
6670 .IR DEL ,
6671 .IR ESC ,
6672 .IR ESCAPE ,
6673 .IR LFD ,
6674 .IR NEWLINE ,
6675 .IR RET ,
6676 .IR RETURN ,
6677 .I RUBOUT
6678 (a destructive backspace),
6679 .IR SPACE ,
6680 .IR SPC ,
6681 and
6682 .IR TAB .
6683 .PP
6684 In addition to command names, \fBreadline\fP allows keys to be bound
6685 to a string that is inserted when the key is pressed (a \fImacro\fP).
6686 The difference between a macro and a command is that a macro is
6687 enclosed in single or double quotes.
6688 .SS "Readline Key Bindings"
6689 The syntax for controlling key bindings in the
6690 .I inputrc
6691 file is simple.
6692 All that is required is the name of the command or the text of a macro
6693 and a key sequence to which it should be bound.
6694 The key sequence may be specified in one of two ways:
6695 as a symbolic key name,
6696 possibly with \fIMeta\-\fP or \fIControl\-\fP prefixes,
6697 or as a key sequence composed of one or more characters
6698 enclosed in double quotes.
6699 The key sequence and name are separated by a colon.
6700 There can be no whitespace between the name and the colon.
6701 .PP
6702 When using the form \fBkeyname\fP:\^\fIfunction\-name\fP or \fImacro\fP,
6703 .I keyname
6704 is the name of a key spelled out in English. For example:
6705 .PP
6706 .RS
6707 .EX
6708 .nf
6709 Control-u: universal\-argument
6710 Meta-Rubout: backward\-kill\-word
6711 Control-o: \*"> output\*"
6712 .fi
6713 .EE
6714 .RE
6715 .LP
6716 In the above example,
6717 .I C\-u
6718 is bound to the function
6719 .BR universal\-argument ,
6720 .I M\-DEL
6721 is bound to the function
6722 .BR backward\-kill\-word ,
6723 and
6724 .I C\-o
6725 is bound to run the macro
6726 expressed on the right hand side (that is, to insert the text
6727 .Q "> output"
6728 into the line).
6729 .PP
6730 In the second form,
6731 \fB\*"keyseq\*"\fP:\^\fIfunction\-name\fP or \fImacro\fP,
6732 .B keyseq
6733 differs from
6734 .B keyname
6735 above in that strings denoting
6736 an entire key sequence may be specified by placing the sequence
6737 within double quotes.
6738 Some GNU Emacs style key escapes can be
6739 used, as in the following example, but none of
6740 the symbolic character names are recognized.
6741 .PP
6742 .RS
6743 .EX
6744 .nf
6745 \*"\eC\-u\*": universal\-argument
6746 \*"\eC\-x\eC\-r\*": re\-read\-init\-file
6747 \*"\ee[11\*~\*": \*"Function Key 1\*"
6748 .fi
6749 .EE
6750 .RE
6751 .PP
6752 In this example,
6753 .I C\-u
6754 is again bound to the function
6755 .BR universal\-argument .
6756 .I "C\-x C\-r"
6757 is bound to the function
6758 .BR re\-read\-init\-file ,
6759 and
6760 .I "ESC [ 1 1 \*~"
6761 is bound to insert the text
6762 .Q "Function Key 1" .
6763 .PP
6764 The full set of GNU Emacs style escape sequences available when specifying
6765 key sequences is
6766 .RS
6767 .PD 0
6768 .TP
6769 .B \eC\-
6770 A control prefix.
6771 .TP
6772 .B \eM\-
6773 Adding the meta prefix or converting the following character to a meta
6774 character, as described below under \fBforce-meta-prefix\fP.
6775 .TP
6776 .B \ee
6777 An escape character.
6778 .TP
6779 .B \e\e
6780 Backslash.
6781 .TP
6782 .B \e\*"
6783 Literal \*", a double quote.
6784 .TP
6785 .B \e\*'
6786 Literal \*', a single quote.
6787 .RE
6788 .PD
6789 .PP
6790 In addition to the GNU Emacs style escape sequences, a second
6791 set of backslash escapes is available:
6792 .RS
6793 .PD 0
6794 .TP
6795 .B \ea
6796 alert (bell)
6797 .TP
6798 .B \eb
6799 backspace
6800 .TP
6801 .B \ed
6802 delete
6803 .TP
6804 .B \ef
6805 form feed
6806 .TP
6807 .B \en
6808 newline
6809 .TP
6810 .B \er
6811 carriage return
6812 .TP
6813 .B \et
6814 horizontal tab
6815 .TP
6816 .B \ev
6817 vertical tab
6818 .TP
6819 .B \e\fInnn\fP
6820 The eight-bit character whose value is the octal value \fInnn\fP
6821 (one to three digits).
6822 .TP
6823 .B \ex\fIHH\fP
6824 The eight-bit character whose value is the hexadecimal value \fIHH\fP
6825 (one or two hex digits).
6826 .RE
6827 .PD
6828 .PP
6829 When entering the text of a macro, single or double quotes must
6830 be used to indicate a macro definition.
6831 Unquoted text is assumed to be a function name.
6832 The backslash escapes described above are expanded
6833 in the macro body.
6834 Backslash quotes any other character in the macro text,
6835 including \*" and \*'.
6836 .PP
6837 .B Bash
6838 will display or modify the current \fBreadline\fP key bindings with the
6839 .B bind
6840 builtin command.
6841 The
6842 .B \-o emacs
6843 or
6844 .B \-o vi
6845 options to the
6846 .B set
6847 builtin
6848 (see
6849 .SM
6850 .B "SHELL BUILTIN COMMANDS"
6851 below)
6852 change the editing mode during interactive use.
6853 .SS "Readline Variables"
6854 \fBReadline\fP has variables that can be used to further customize its
6855 behavior.
6856 A variable may be set in the
6857 .I inputrc
6858 file with a statement of the form
6859 .RS
6860 .PP
6861 \fBset\fP \fIvariable\-name\fP \fIvalue\fP
6862 .RE
6863 or using the \fBbind\fP builtin command (see
6864 .SM
6865 .B "SHELL BUILTIN COMMANDS"
6866 below).
6867 .PP
6868 Except where noted, \fBreadline\fP variables can take the values
6869 .B On
6870 or
6871 .B Off
6872 (without regard to case).
6873 Unrecognized variable names are ignored.
6874 When \fBreadline\fP reads a variable value, empty or null values,
6875 .Q "on"
6876 (case-insensitive), and
6877 .Q 1
6878 are equivalent to \fBOn\fP.
6879 All other values are equivalent to
6880 \fBOff\fP.
6881 .PP
6882 The \fBbind \-V\fP command lists the current \fBreadline\fP variable names
6883 and values (see
6884 .SM
6885 .B "SHELL BUILTIN COMMANDS"
6886 below).
6887 .PP
6888 The variables and their default values are:
6889 .PP
6890 .PD 0
6891 .TP
6892 .B active\-region\-start\-color
6893 A string variable that controls the text color and background when displaying
6894 the text in the active region (see the description of
6895 \fBenable\-active\-region\fP below).
6896 This string must not take up any physical character positions on the display,
6897 so it should consist only of terminal escape sequences.
6898 It is output to the terminal before displaying the text in the active region.
6899 This variable is reset to the default value whenever the terminal type changes.
6900 The default value is the string that puts the terminal in standout mode,
6901 as obtained from the terminal's terminfo description.
6902 A sample value might be
6903 .Q \ee[01;33m .
6904 .TP
6905 .B active\-region\-end\-color
6906 A string variable that
6907 .Q undoes
6908 the effects of \fBactive\-region\-start\-color\fP
6909 and restores
6910 .Q normal
6911 terminal display appearance after displaying text in the active region.
6912 This string must not take up any physical character positions on the display,
6913 so it should consist only of terminal escape sequences.
6914 It is output to the terminal after displaying the text in the active region.
6915 This variable is reset to the default value whenever the terminal type changes.
6916 The default value is the string that restores the terminal from standout mode,
6917 as obtained from the terminal's terminfo description.
6918 A sample value might be
6919 .Q \ee[0m .
6920 .TP
6921 .B bell\-style (audible)
6922 Controls what happens when \fBreadline\fP wants to ring the terminal bell.
6923 If set to \fBnone\fP, \fBreadline\fP never rings the bell.
6924 If set to \fBvisible\fP, \fBreadline\fP uses a visible bell if one is available.
6925 If set to \fBaudible\fP, \fBreadline\fP attempts to ring the terminal's bell.
6926 .TP
6927 .B bind\-tty\-special\-chars (On)
6928 If set to \fBOn\fP, \fBreadline\fP attempts to bind
6929 the control characters that are treated specially by the kernel's
6930 terminal driver to their \fBreadline\fP equivalents.
6931 These override the default \fBreadline\fP bindings described here.
6932 Type
6933 .Q "stty \-a"
6934 at a \fBbash\fP prompt to see your current terminal settings,
6935 including the special control characters (usually \fBcchars\fP).
6936 .TP
6937 .B blink\-matching\-paren (Off)
6938 If set to \fBOn\fP, \fBreadline\fP attempts to briefly move the cursor to an
6939 opening parenthesis when a closing parenthesis is inserted.
6940 .TP
6941 .B colored\-completion\-prefix (Off)
6942 If set to \fBOn\fP, when listing completions, \fBreadline\fP displays the
6943 common prefix of the set of possible completions using a different color.
6944 The color definitions are taken from the value of the \fBLS_COLORS\fP
6945 environment variable.
6946 If there is a color definition in \fB$LS_COLORS\fP for the custom suffix
6947 .Q .readline-colored-completion-prefix ,
6948 \fBreadline\fP uses this color for
6949 the common prefix instead of its default.
6950 .TP
6951 .B colored\-stats (Off)
6952 If set to \fBOn\fP, \fBreadline\fP displays possible completions using different
6953 colors to indicate their file type.
6954 The color definitions are taken from the value of the \fBLS_COLORS\fP
6955 environment variable.
6956 .\" Tucking multiple macro calls into a paragraph tag requires some
6957 .\" finesse. We require `\c`, and while the single-font macros don't
6958 .\" honor input trap continuation, the font alternation macros do.
6959 .TP
6960 .BR comment\-begin\ ( \c
6961 .Q \fB#\fP \fB)\fP
6962 The string that the \fBreadline\fP
6963 .B insert\-comment
6964 command inserts.
6965 This command is bound to
6966 .B M\-#
6967 in emacs mode and to
6968 .B #
6969 in vi command mode.
6970 .TP
6971 .B completion\-display\-width (\-1)
6972 The number of screen columns used to display possible matches
6973 when performing completion.
6974 The value is ignored if it is less than 0 or greater than the terminal
6975 screen width.
6976 A value of 0 causes matches to be displayed one per line.
6977 The default value is \-1.
6978 .TP
6979 .B completion\-ignore\-case (Off)
6980 If set to \fBOn\fP, \fBreadline\fP performs filename matching and completion
6981 in a case\-insensitive fashion.
6982 .TP
6983 .B completion\-map\-case (Off)
6984 If set to \fBOn\fP, and \fBcompletion\-ignore\-case\fP is enabled,
6985 .B readline
6986 treats hyphens (\fI\-\fP) and underscores (\fI_\fP) as equivalent when
6987 performing case\-insensitive filename matching and completion.
6988 .TP
6989 .B completion\-prefix\-display\-length (0)
6990 The maximum
6991 length in characters of the common prefix of a list of possible
6992 completions that is displayed without modification.
6993 When set to a value greater than zero, \fBreadline\fP
6994 replaces common prefixes longer than this value
6995 with an ellipsis when displaying possible completions.
6996 If a completion begins with a period,
6997 and \fBeadline\fP is completing filenames,
6998 it uses three underscores instead of an ellipsis.
6999 .TP
7000 .B completion\-query\-items (100)
7001 This determines when the user is queried about viewing
7002 the number of possible completions
7003 generated by the \fBpossible\-completions\fP command.
7004 It may be set to any integer value greater than or equal to zero.
7005 If the number of possible completions is greater than
7006 or equal to the value of this variable,
7007 \fBreadline\fP asks whether or not the user wishes to view them;
7008 otherwise \fBreadline\fP simply lists them on the terminal.
7009 A zero value means \fBreadline\fP should never ask; negative values are
7010 treated as zero.
7011 .TP
7012 .B convert\-meta (On)
7013 If set to \fBOn\fP, \fBreadline\fP converts characters it reads
7014 that have the eighth bit set to an ASCII key sequence by
7015 clearing the eighth bit and prefixing it with an escape character
7016 (converting the character to have the meta prefix).
7017 The default is \fIOn\fP, but \fBreadline\fP sets it to \fIOff\fP
7018 if the locale contains
7019 characters whose encodings may include bytes with the eighth bit set.
7020 This variable is dependent on the \fBLC_CTYPE\fP locale category, and
7021 may change if the locale changes.
7022 This variable also affects key bindings; see the description of
7023 \fBforce\-meta\-prefix\fP below.
7024 .TP
7025 .B disable\-completion (Off)
7026 If set to \fBOn\fP, \fBreadline\fP inhibits word completion.
7027 Completion characters are inserted into the line as if they
7028 had been mapped to \fBself-insert\fP.
7029 .TP
7030 .B echo\-control\-characters (On)
7031 When set to \fBOn\fP, on operating systems that indicate they support it,
7032 \fBreadline\fP echoes a character corresponding to a signal generated from the
7033 keyboard.
7034 .TP
7035 .B editing\-mode (emacs)
7036 Controls whether \fBreadline\fP uses a set of key bindings similar
7037 to \fIEmacs\fP or \fIvi\fP.
7038 .B editing\-mode
7039 can be set to either
7040 .B emacs
7041 or
7042 .BR vi .
7043 .TP
7044 .B emacs\-mode\-string (@)
7045 If the \fIshow\-mode\-in\-prompt\fP variable is enabled,
7046 this string is displayed immediately before the last line of the
7047 primary prompt when emacs editing mode is active.
7048 The value is expanded like a
7049 key binding, so the standard set of meta- and control- prefixes and
7050 backslash escape sequences is available.
7051 The \e1 and \e2 escapes begin and end sequences of
7052 non-printing characters, which can be used to embed a terminal control
7053 sequence into the mode string.
7054 .TP
7055 .B enable\-active\-region (On)
7056 When this variable is set to \fIOn\fP, \fBreadline\fP allows certain commands
7057 to designate the region as \fIactive\fP.
7058 When the region is active, \fBreadline\fP
7059 highlights the text in the region using the value of the
7060 .B active\-region\-start\-color
7061 variable, which defaults to the string that enables
7062 the terminal's standout mode.
7063 The active region shows the text inserted by bracketed-paste and any
7064 matching text found by incremental and non-incremental history searches.
7065 .TP
7066 .B enable\-bracketed\-paste (On)
7067 When set to \fBOn\fP, \fBreadline\fP configures the terminal to insert each
7068 paste into the editing buffer as a single string of characters, instead
7069 of treating each character as if it had been read from the keyboard.
7070 This is called \fIbracketed\-paste mode\fP;
7071 it prevents \fBreadline\fP from executing any editing commands bound to key
7072 sequences appearing in the pasted text.
7073 .TP
7074 .B enable\-keypad (Off)
7075 When set to \fBOn\fP, \fBreadline\fP tries to enable the application
7076 keypad when it is called.
7077 Some systems need this to enable the arrow keys.
7078 .TP
7079 .B enable\-meta\-key (On)
7080 When set to \fBOn\fP, \fBreadline\fP tries to enable any meta modifier
7081 key the terminal claims to support.
7082 On many terminals, the Meta key is used to send eight-bit characters;
7083 this variable checks for the terminal capability that indicates the
7084 terminal can enable and disable a mode that sets the eighth bit of a
7085 character (0200) if the Meta key is held down when the character is
7086 typed (a meta character).
7087 .TP
7088 .B expand\-tilde (Off)
7089 If set to \fBOn\fP, \fBreadline\fP performs tilde expansion when it
7090 attempts word completion.
7091 .TP
7092 .B force\-meta\-prefix (Off)
7093 If set to \fBOn\fP, \fBreadline\fP modifies its behavior when binding key
7094 sequences containing \eM- or Meta-
7095 (see \fBKey Bindings\fP above) by converting a key sequence of the form
7096 \eM\-\fIC\fP or Meta\-\fIC\fP to the two-character sequence
7097 \fBESC\fP \fIC\fP (adding the meta prefix).
7098 If
7099 .B force\-meta\-prefix
7100 is set to \fBOff\fP (the default),
7101 \fBreadline\fP uses the value of the
7102 .B convert\-meta
7103 variable to determine whether to perform this conversion:
7104 if \fBconvert\-meta\fP is \fBOn\fP,
7105 \fBreadline\fP performs the conversion described above;
7106 if it is \fBOff\fP, \fBreadline\fP converts \fIC\fP to a meta character by
7107 setting the eighth bit (0200).
7108 .TP
7109 .B history\-preserve\-point (Off)
7110 If set to \fBOn\fP, the history code attempts to place point at the
7111 same location on each history line retrieved with \fBprevious-history\fP
7112 or \fBnext-history\fP.
7113 .TP
7114 .B history\-size (unset)
7115 Set the maximum number of history entries saved in the history list.
7116 If set to zero, any existing history entries are deleted and no new entries
7117 are saved.
7118 If set to a value less than zero, the number of history entries is not
7119 limited.
7120 By default, \fBbash\fP sets the maximum number of history entries to
7121 the value of the \fBHISTSIZE\fP shell variable.
7122 Setting \fIhistory\-size\fP to a non-numeric value will set
7123 the maximum number of history entries to 500.
7124 .TP
7125 .B horizontal\-scroll\-mode (Off)
7126 Setting this variable to \fBOn\fP makes \fBreadline\fP use a single line
7127 for display, scrolling the input horizontally on a single screen line
7128 when it becomes longer than the screen width rather than wrapping to
7129 a new line.
7130 This setting is automatically enabled for terminals of height 1.
7131 .TP
7132 .B input\-meta (Off)
7133 If set to \fBOn\fP, \fBreadline\fP enables eight-bit input (that is, it
7134 does not clear the eighth bit in the characters it reads),
7135 regardless of what the terminal claims it can support.
7136 The default is \fIOff\fP, but \fBreadline\fP sets it to \fIOn\fP
7137 if the locale contains characters whose encodings may include bytes
7138 with the eighth bit set.
7139 This variable is dependent on the \fBLC_CTYPE\fP locale category, and
7140 its value may change if the locale changes.
7141 The name \fBmeta\-flag\fP is a synonym for \fBinput\-meta\fP.
7142 .TP
7143 .BR isearch\-terminators\ ( \c
7144 .Q \fBC\-[C\-j\fP \fB)\fP
7145 The string of characters that should terminate an incremental
7146 search without subsequently executing the character as a command.
7147 If this variable has not been given a value, the characters
7148 \fIESC\fP and \fBC\-j\fP terminate an incremental search.
7149 .TP
7150 .B keymap (emacs)
7151 Set the current \fBreadline\fP keymap.
7152 The set of valid keymap names is
7153 \fIemacs, emacs\-standard, emacs\-meta, emacs\-ctlx, vi,
7154 vi\-command\fP, and
7155 .IR vi\-insert .
7156 \fIvi\fP is equivalent to \fIvi\-command\fP;
7157 \fIemacs\fP is equivalent to \fIemacs\-standard\fP.
7158 The default value is \fIemacs\fP;
7159 the value of
7160 .B editing\-mode
7161 also affects the default keymap.
7162 .TP
7163 .B keyseq\-timeout (500)
7164 Specifies the duration \fBreadline\fP will wait for a character when
7165 reading an ambiguous key sequence
7166 (one that can form a complete key sequence using the input read so far,
7167 or can take additional input to complete a longer key sequence).
7168 If \fBreadline\fP does not receive any input within the timeout,
7169 it uses the shorter but complete key sequence.
7170 The value is specified in milliseconds, so a value of 1000 means that
7171 \fBreadline\fP will wait one second for additional input.
7172 If this variable is set to a value less than or equal to zero, or to a
7173 non-numeric value, \fBreadline\fP waits until another key is pressed to
7174 decide which key sequence to complete.
7175 .TP
7176 .B mark\-directories (On)
7177 If set to \fBOn\fP, completed directory names have a slash appended.
7178 .TP
7179 .B mark\-modified\-lines (Off)
7180 If set to \fBOn\fP, \fBreadline\fP displays history lines
7181 that have been modified
7182 with a preceding asterisk (\fB*\fP).
7183 .TP
7184 .B mark\-symlinked\-directories (Off)
7185 If set to \fBOn\fP, completed names which are symbolic links to directories
7186 have a slash appended, subject to the value of \fBmark\-directories\fP.
7187 .TP
7188 .B match\-hidden\-files (On)
7189 This variable, when set to \fBOn\fP, forces \fBreadline\fP to match files whose
7190 names begin with a
7191 .Q .
7192 (hidden files) when performing filename completion.
7193 If set to \fBOff\fP, the user must include the leading
7194 .Q .
7195 in the filename to be completed.
7196 .TP
7197 .B menu\-complete\-display\-prefix (Off)
7198 If set to \fBOn\fP, menu completion displays the common prefix of the
7199 list of possible completions (which may be empty) before cycling through
7200 the list.
7201 .TP
7202 .B output\-meta (Off)
7203 If set to \fBOn\fP, \fBreadline\fP displays characters with the
7204 eighth bit set directly rather than as a meta-prefixed escape
7205 sequence.
7206 The default is \fIOff\fP, but \fBreadline\fP sets it to \fIOn\fP
7207 if the locale contains characters whose encodings may include
7208 bytes with the eighth bit set.
7209 This variable is dependent on the \fBLC_CTYPE\fP locale category, and
7210 its value may change if the locale changes.
7211 .TP
7212 .B page\-completions (On)
7213 If set to \fBOn\fP, \fBreadline\fP uses an internal pager resembling
7214 .IR more (1)
7215 to display a screenful of possible completions at a time.
7216 .TP
7217 .B prefer\-visible\-bell
7218 See \fBbell\-style\fP.
7219 .TP
7220 .B print\-completions\-horizontally (Off)
7221 If set to \fBOn\fP, \fBreadline\fP displays completions with matches
7222 sorted horizontally in alphabetical order, rather than down the screen.
7223 .TP
7224 .B revert\-all\-at\-newline (Off)
7225 If set to \fBOn\fP, \fBreadline\fP will undo all changes to history lines
7226 before returning when executing \fBaccept\-line\fP.
7227 By default,
7228 history lines may be modified and retain individual undo lists across
7229 calls to \fBreadline\fP.
7230 .TP
7231 .B search\-ignore\-case (Off)
7232 If set to \fBOn\fP, \fBreadline\fP performs incremental and non-incremental
7233 history list searches in a case\-insensitive fashion.
7234 .TP
7235 .B show\-all\-if\-ambiguous (Off)
7236 This alters the default behavior of the completion functions.
7237 If set to
7238 .BR On ,
7239 words which have more than one possible completion cause the
7240 matches to be listed immediately instead of ringing the bell.
7241 .TP
7242 .B show\-all\-if\-unmodified (Off)
7243 This alters the default behavior of the completion functions in
7244 a fashion similar to \fBshow\-all\-if\-ambiguous\fP.
7245 If set to
7246 .BR On ,
7247 words which have more than one possible completion without any
7248 possible partial completion (the possible completions don't share
7249 a common prefix) cause the matches to be listed immediately instead
7250 of ringing the bell.
7251 .TP
7252 .B show\-mode\-in\-prompt (Off)
7253 If set to \fBOn\fP, add a string to the beginning of the prompt
7254 indicating the editing mode: emacs, vi command, or vi insertion.
7255 The mode strings are user-settable (e.g., \fIemacs\-mode\-string\fP).
7256 .TP
7257 .B skip\-completed\-text (Off)
7258 If set to \fBOn\fP, this alters the default completion behavior when
7259 inserting a single match into the line.
7260 It's only active when performing completion in the middle of a word.
7261 If enabled, \fBreadline\fP does not insert characters from the completion
7262 that match characters after point in the word being completed,
7263 so portions of the word following the cursor are not duplicated.
7264 .TP
7265 .B vi\-cmd\-mode\-string ((cmd))
7266 If the \fIshow\-mode\-in\-prompt\fP variable is enabled,
7267 this string is displayed immediately before the last line of the primary
7268 prompt when vi editing mode is active and in command mode.
7269 The value is expanded like a key binding, so the standard set of
7270 meta- and control- prefixes and backslash escape sequences is available.
7271 The \e1 and \e2 escapes begin and end sequences of
7272 non-printing characters, which can be used to embed a terminal control
7273 sequence into the mode string.
7274 .TP
7275 .B vi\-ins\-mode\-string ((ins))
7276 If the \fIshow\-mode\-in\-prompt\fP variable is enabled,
7277 this string is displayed immediately before the last line of the primary
7278 prompt when vi editing mode is active and in insertion mode.
7279 The value is expanded like a key binding, so the standard set of
7280 meta- and control- prefixes and backslash escape sequences is available.
7281 The \e1 and \e2 escapes begin and end sequences of
7282 non-printing characters, which can be used to embed a terminal control
7283 sequence into the mode string.
7284 .TP
7285 .B visible\-stats (Off)
7286 If set to \fBOn\fP, a character denoting a file's type as reported
7287 by \fIstat\fP(2) is appended to the filename when listing possible
7288 completions.
7289 .PD
7290 .SS "Readline Conditional Constructs"
7291 .B Readline
7292 implements a facility similar in spirit to the conditional
7293 compilation features of the C preprocessor which allows key
7294 bindings and variable settings to be performed as the result
7295 of tests.
7296 There are four parser directives available.
7297 .TP
7298 .B $if
7299 The
7300 .B $if
7301 construct allows bindings to be made based on the
7302 editing mode, the terminal being used, or the application using
7303 \fBreadline\fP.
7304 The text of the test, after any comparison operator,
7305 extends to the end of the line;
7306 unless otherwise noted, no characters are required to isolate it.
7307 .RS
7308 .TP
7309 .B mode
7310 The \fBmode=\fP form of the \fB$if\fP directive is used to test
7311 whether \fBreadline\fP is in emacs or vi mode.
7312 This may be used in conjunction
7313 with the \fBset keymap\fP command, for instance, to set bindings in
7314 the \fIemacs\-standard\fP and \fIemacs\-ctlx\fP keymaps only if
7315 \fBreadline\fP is starting out in emacs mode.
7316 .TP
7317 .B term
7318 The \fBterm=\fP form may be used to include terminal-specific
7319 key bindings, perhaps to bind the key sequences output by the
7320 terminal's function keys.
7321 The word on the right side of the
7322 .B =
7323 is tested against both the full name of the terminal and the portion
7324 of the terminal name before the first \fB\-\fP.
7325 This allows
7326 .I xterm
7327 to match both
7328 .I xterm
7329 and
7330 .IR xterm\-256color ,
7331 for instance.
7332 .TP
7333 .B version
7334 The \fBversion\fP test may be used to perform comparisons against
7335 specific \fBreadline\fP versions.
7336 The \fBversion\fP expands to the current \fBreadline\fP version.
7337 The set of comparison operators includes
7338 .BR = ,
7339 (and
7340 .BR == ),
7341 .BR != ,
7342 .BR <= ,
7343 .BR >= ,
7344 .BR < ,
7345 and
7346 .BR > .
7347 The version number supplied on the right side of the operator consists
7348 of a major version number, an optional decimal point, and an optional
7349 minor version (e.g., \fB7.1\fP).
7350 If the minor version is omitted, it
7351 defaults to \fB0\fP.
7352 The operator may be separated from the string \fBversion\fP
7353 and from the version number argument by whitespace.
7354 .TP
7355 .I application
7356 The \fIapplication\fP construct is used to include
7357 application-specific settings.
7358 Each program using the \fBreadline\fP
7359 library sets the \fIapplication name\fP, and an initialization
7360 file can test for a particular value.
7361 This could be used to bind key sequences to functions useful for
7362 a specific program.
7363 For instance, the following command adds a
7364 key sequence that quotes the current or previous word in \fBbash\fP:
7365 .PP
7366 .RS
7367 .EX
7368 .nf
7369 \fB$if\fP Bash
7370 # Quote the current or previous word
7371 \*"\eC-xq\*": \*"\eeb\e\*"\eef\e\*"\*"
7372 \fB$endif\fP
7373 .fi
7374 .EE
7375 .RE
7376 .TP
7377 .I variable
7378 The \fIvariable\fP construct provides simple equality tests for \fBreadline\fP
7379 variables and values.
7380 The permitted comparison operators are \fI=\fP, \fI==\fP, and \fI!=\fP.
7381 The variable name must be separated from the comparison operator by
7382 whitespace; the operator may be separated from the value on the right hand
7383 side by whitespace.
7384 String and boolean variables may be tested.
7385 Boolean variables must be
7386 tested against the values \fIon\fP and \fIoff\fP.
7387 .RE
7388 .TP
7389 .B $else
7390 Commands in this branch of the \fB$if\fP directive are executed if
7391 the test fails.
7392 .TP
7393 .B $endif
7394 This command, as seen in the previous example, terminates an
7395 \fB$if\fP command.
7396 .TP
7397 .B $include
7398 This directive takes a single filename as an argument and reads commands
7399 and key bindings from that file.
7400 For example, the following directive would read
7401 .FN /etc/inputrc :
7402 .PP
7403 .RS
7404 .nf
7405 \fB$include\fP \^ \fI/etc/inputrc\fP
7406 .fi
7407 .RE
7408 .SS Searching
7409 .B Readline
7410 provides commands for searching through the command history (see
7411 .SM
7412 .B HISTORY
7413 below)
7414 for lines containing a specified string.
7415 There are two search modes:
7416 .I incremental
7417 and
7418 .IR non-incremental .
7419 .PP
7420 Incremental searches begin before the user has finished typing the
7421 search string.
7422 As each character of the search string is typed, \fBreadline\fP displays
7423 the next entry from the history matching the string typed so far.
7424 An incremental search requires only as many characters as needed to
7425 find the desired history entry.
7426 When using emacs editing mode, type \fBC\-r\fP to
7427 search backward in the history for a particular string.
7428 Typing \fBC\-s\fP searches forward through the history.
7429 The characters present in the value of the \fBisearch-terminators\fP
7430 variable are used to terminate an incremental search.
7431 If that variable has not been assigned a value,
7432 \fIESC\fP and \fBC\-j\fP terminate an incremental search.
7433 \fBC\-g\fP aborts an incremental search and restores the original line.
7434 When the search is terminated, the history entry containing the
7435 search string becomes the current line.
7436 .PP
7437 To find other matching entries in the history list, type \fBC\-r\fP or
7438 \fBC\-s\fP as appropriate.
7439 This searches backward or forward in the history for the next
7440 entry matching the search string typed so far.
7441 Any other key sequence bound to a \fBreadline\fP command terminates
7442 the search and executes that command.
7443 For instance, a newline terminates the search and accepts
7444 the line, thereby executing the command from the history list.
7445 A movement command will terminate the search, make the last line found
7446 the current line, and begin editing.
7447 .PP
7448 .B Readline
7449 remembers the last incremental search string.
7450 If two \fBC\-r\fPs are typed without any intervening characters defining
7451 a new search string, \fBreadline\fP uses any remembered search string.
7452 .PP
7453 Non-incremental searches read the entire search string before starting
7454 to search for matching history entries.
7455 The search string may be
7456 typed by the user or be part of the contents of the current line.
7457 .SS "Readline Command Names"
7458 The following is a list of the names of the commands and the default
7459 key sequences to which they are bound.
7460 Command names without an accompanying key sequence are unbound by default.
7461 .PP
7462 In the following descriptions, \fIpoint\fP refers to the current cursor
7463 position, and \fImark\fP refers to a cursor position saved by the
7464 \fBset\-mark\fP command.
7465 The text between the point and mark is referred to as the \fIregion\fP.
7466 .B Readline
7467 has the concept of an \fIactive region\fP:
7468 when the region is active, \fBreadline\fP redisplay
7469 highlights the region using the value of the
7470 .B active\-region\-start\-color
7471 variable.
7472 The \fBenable\-active\-region\fP \fBreadline\fP variable turns this on and off.
7473 Several commands set the region to active; those are noted below.
7474 .SS Commands for Moving
7475 .PD 0
7476 .TP
7477 .B beginning\-of\-line (C\-a)
7478 Move to the start of the current line.
7479 This may also be bound to the Home key on some keyboards.
7480 .TP
7481 .B end\-of\-line (C\-e)
7482 Move to the end of the line.
7483 This may also be bound to the End key on some keyboards.
7484 .TP
7485 .B forward\-char (C\-f)
7486 Move forward a character.
7487 This may also be bound to the right arrow key on some keyboards.
7488 .TP
7489 .B backward\-char (C\-b)
7490 Move back a character.
7491 This may also be bound to the left arrow key on some keyboards.
7492 .TP
7493 .B forward\-word (M\-f)
7494 Move forward to the end of the next word.
7495 Words are composed of alphanumeric characters (letters and digits).
7496 .TP
7497 .B backward\-word (M\-b)
7498 Move back to the start of the current or previous word.
7499 Words are composed of alphanumeric characters (letters and digits).
7500 .TP
7501 .B shell\-forward\-word (M\-C\-f)
7502 Move forward to the end of the next word.
7503 Words are delimited by non-quoted shell metacharacters.
7504 .TP
7505 .B shell\-backward\-word (M\-C\-b)
7506 Move back to the start of the current or previous word.
7507 Words are delimited by non-quoted shell metacharacters.
7508 .TP
7509 .B previous\-screen\-line
7510 Attempt to move point to the same physical screen column on the previous
7511 physical screen line.
7512 This will not have the desired effect if the current
7513 \fBreadline\fP line does not take up more than one physical line or if
7514 point is not greater than the length of the prompt plus the screen width.
7515 .TP
7516 .B next\-screen\-line
7517 Attempt to move point to the same physical screen column on the next
7518 physical screen line.
7519 This will not have the desired effect if the current
7520 \fBreadline\fP line does not take up more than one physical line or if
7521 the length of the current \fBreadline\fP line is
7522 not greater than the length of the prompt
7523 plus the screen width.
7524 .TP
7525 .B clear\-display (M\-C\-l)
7526 Clear the screen and, if possible, the terminal's scrollback buffer,
7527 then redraw the current line,
7528 leaving the current line at the top of the screen.
7529 .TP
7530 .B clear\-screen (C\-l)
7531 Clear the screen,
7532 then redraw the current line,
7533 leaving the current line at the top of the screen.
7534 With a numeric argument, refresh the current line without clearing the
7535 screen.
7536 .TP
7537 .B redraw\-current\-line
7538 Refresh the current line.
7539 .PD
7540 .SS Commands for Manipulating the History
7541 .PD 0
7542 .TP
7543 .B accept\-line (Newline, Return)
7544 Accept the line regardless of where the cursor is.
7545 If this line is non-empty, add it to the history list according to the
7546 state of the
7547 .SM
7548 .B HISTCONTROL
7549 and
7550 .B HISTIGNORE
7551 variables.
7552 If the line is a modified history line,
7553 restore the history line to its original state.
7554 .TP
7555 .B previous\-history (C\-p)
7556 Fetch the previous command from the history list, moving back in
7557 the list.
7558 This may also be bound to the up arrow key on some keyboards.
7559 .TP
7560 .B next\-history (C\-n)
7561 Fetch the next command from the history list, moving forward in the
7562 list.
7563 This may also be bound to the down arrow key on some keyboards.
7564 .TP
7565 .B beginning\-of\-history (M\-<)
7566 Move to the first line in the history.
7567 .TP
7568 .B end\-of\-history (M\->)
7569 Move to the end of the input history, i.e., the line currently being
7570 entered.
7571 .TP
7572 .B operate\-and\-get\-next (C\-o)
7573 Accept the current line for execution as if a
7574 newline had been entered,
7575 and fetch the next line relative to the current line from the history
7576 for editing.
7577 A numeric argument, if supplied, specifies the history entry to use instead
7578 of the current line.
7579 .TP
7580 .B
7581 fetch\-history
7582 With a numeric argument, fetch that entry from the history list
7583 and make it the current line.
7584 Without an argument, move back to the first entry in the history list.
7585 .TP
7586 .B reverse\-search\-history (C\-r)
7587 Search backward starting at the current line and moving
7588 .Q up
7589 through the history as necessary.
7590 This is an incremental search.
7591 This command sets the region to the matched text and activates the region.
7592 .TP
7593 .B forward\-search\-history (C\-s)
7594 Search forward starting at the current line and moving
7595 .Q down
7596 through the history as necessary.
7597 This is an incremental search.
7598 This command sets the region to the matched text and activates the region.
7599 .TP
7600 .B non\-incremental\-reverse\-search\-history (M\-p)
7601 Search backward through the history starting at the current line
7602 using a non-incremental search for a string supplied by the user.
7603 The search string may match anywhere in a history line.
7604 .TP
7605 .B non\-incremental\-forward\-search\-history (M\-n)
7606 Search forward through the history using a non-incremental search
7607 for a string supplied by the user.
7608 The search string may match anywhere in a history line.
7609 .TP
7610 .B history\-search\-backward
7611 Search backward through the history for the string of characters
7612 between the start of the current line and the point.
7613 The search string must match at the beginning of a history line.
7614 This is a non-incremental search.
7615 This may be bound to the Page Up key on some keyboards.
7616 .TP
7617 .B history\-search\-forward
7618 Search forward through the history for the string of characters
7619 between the start of the current line and the point.
7620 The search string must match at the beginning of a history line.
7621 This is a non-incremental search.
7622 This may be bound to the Page Down key on some keyboards.
7623 .TP
7624 .B history\-substring\-search\-backward
7625 Search backward through the history for the string of characters
7626 between the start of the current line and the point.
7627 The search string may match anywhere in a history line.
7628 This is a non-incremental search.
7629 .TP
7630 .B history\-substring\-search\-forward
7631 Search forward through the history for the string of characters
7632 between the start of the current line and the point.
7633 The search string may match anywhere in a history line.
7634 This is a non-incremental search.
7635 .TP
7636 .B yank\-nth\-arg (M\-C\-y)
7637 Insert the first argument to the previous command (usually
7638 the second word on the previous line) at point.
7639 With an argument
7640 .IR n ,
7641 insert the \fIn\fPth word from the previous command (the words
7642 in the previous command begin with word 0).
7643 A negative argument inserts the \fIn\fPth word from the end of
7644 the previous command.
7645 Once the argument \fIn\fP is computed,
7646 this uses the history expansion facilities to extract the
7647 \fIn\fPth word, as if the
7648 .Q !\fIn\fP
7649 history expansion had been specified.
7650 .TP
7651 .B
7652 yank\-last\-arg (M\-.\^, M\-_\^)
7653 Insert the last argument to the previous command (the last word of
7654 the previous history entry).
7655 With a numeric argument, behave exactly like \fByank\-nth\-arg\fP.
7656 Successive calls to \fByank\-last\-arg\fP move back through the history
7657 list, inserting the last word (or the word specified by the argument to
7658 the first call) of each line in turn.
7659 Any numeric argument supplied to these successive calls determines
7660 the direction to move through the history.
7661 A negative argument switches the direction through the history
7662 (back or forward).
7663 This uses the history expansion facilities to extract the
7664 last word, as if the
7665 .Q !$
7666 history expansion had been specified.
7667 .TP
7668 .B shell\-expand\-line (M\-C\-e)
7669 Expand the line by performing shell word expansions.
7670 This performs alias and history expansion,
7671 \fB$\fP\*'\fIstring\fP\*' and \fB$\fP\*"\fIstring\fP\*" quoting,
7672 tilde expansion, parameter and variable expansion, arithmetic expansion,
7673 command and process substitution,
7674 word splitting, and quote removal.
7675 An explicit argument suppresses command and process substitution.
7676 See
7677 .SM
7678 .B "HISTORY EXPANSION"
7679 below for a description of history expansion.
7680 .TP
7681 .B history\-expand\-line (M\-\*^)
7682 Perform history expansion on the current line.
7683 See
7684 .SM
7685 .B "HISTORY EXPANSION"
7686 below for a description of history expansion.
7687 .TP
7688 .B magic\-space
7689 Perform history expansion on the current line and insert a space.
7690 See
7691 .SM
7692 .B "HISTORY EXPANSION"
7693 below for a description of history expansion.
7694 .TP
7695 .B alias\-expand\-line
7696 Perform alias expansion on the current line.
7697 See
7698 .SM
7699 .B ALIASES
7700 above for a description of alias expansion.
7701 .TP
7702 .B history\-and\-alias\-expand\-line
7703 Perform history and alias expansion on the current line.
7704 .TP
7705 .B insert\-last\-argument (M\-.\^, M\-_\^)
7706 A synonym for \fByank\-last\-arg\fP.
7707 .TP
7708 .B edit\-and\-execute\-command (C\-x C\-e)
7709 Invoke an editor on the current command line, and execute the result as shell
7710 commands.
7711 \fBBash\fP attempts to invoke
7712 .SM
7713 .BR $VISUAL ,
7714 .SM
7715 .BR $EDITOR ,
7716 and \fIemacs\fP as the editor, in that order.
7717 .PD
7718 .SS Commands for Changing Text
7719 .PD 0
7720 .TP
7721 .B \fIend\-of\-file\fP (usually C\-d)
7722 The character indicating end-of-file as set, for example, by
7723 .IR stty (1).
7724 If this character is read when there are no characters
7725 on the line, and point is at the beginning of the line, \fBreadline\fP
7726 interprets it as the end of input and returns
7727 .SM
7728 .BR EOF .
7729 .TP
7730 .B delete\-char (C\-d)
7731 Delete the character at point.
7732 If this function is bound to the
7733 same character as the tty \fBEOF\fP character, as \fBC\-d\fP
7734 commonly is, see above for the effects.
7735 This may also be bound to the Delete key on some keyboards.
7736 .TP
7737 .B backward\-delete\-char (Rubout)
7738 Delete the character behind the cursor.
7739 When given a numeric argument,
7740 save the deleted text on the kill ring.
7741 .TP
7742 .B forward\-backward\-delete\-char
7743 Delete the character under the cursor, unless the cursor is at the
7744 end of the line, in which case the character behind the cursor is
7745 deleted.
7746 .TP
7747 .B quoted\-insert (C\-q, C\-v)
7748 Add the next character typed to the line verbatim.
7749 This is how to insert characters like \fBC\-q\fP, for example.
7750 .TP
7751 .B tab\-insert (C\-v TAB)
7752 Insert a tab character.
7753 .TP
7754 .B "self\-insert (a, b, A, 1, !, \fR.\|.\|.\fP)"
7755 Insert the character typed.
7756 .TP
7757 .B bracketed\-paste\-begin
7758 This function is intended to be bound to the
7759 .Q "bracketed paste"
7760 escape
7761 sequence sent by some terminals, and such a binding is assigned by default.
7762 It allows \fBreadline\fP to insert the pasted text as a single unit
7763 without treating each character as if it had been read from the keyboard.
7764 The pasted characters
7765 are inserted as if each one was bound to \fBself\-insert\fP instead of
7766 executing any editing commands.
7767 .IP
7768 Bracketed paste sets the region to the inserted text and activates the region.
7769 .TP
7770 .B transpose\-chars (C\-t)
7771 Drag the character before point forward over the character at point,
7772 moving point forward as well.
7773 If point is at the end of the line, then this transposes
7774 the two characters before point.
7775 Negative arguments have no effect.
7776 .TP
7777 .B transpose\-words (M\-t)
7778 Drag the word before point past the word after point,
7779 moving point past that word as well.
7780 If point is at the end of the line, this transposes
7781 the last two words on the line.
7782 .TP
7783 .B shell\-transpose\-words (M-C-t)
7784 Drag the word before point past the word after point,
7785 moving point past that word as well.
7786 If the insertion point is at the end of the line, this transposes
7787 the last two words on the line.
7788 Word boundaries are the same as \fBshell\-forward\-word\fP and
7789 \fBshell\-backward\-word\fP.
7790 .TP
7791 .B upcase\-word (M\-u)
7792 Uppercase the current (or following) word.
7793 With a negative argument,
7794 uppercase the previous word, but do not move point.
7795 .TP
7796 .B downcase\-word (M\-l)
7797 Lowercase the current (or following) word.
7798 With a negative argument,
7799 lowercase the previous word, but do not move point.
7800 .TP
7801 .B capitalize\-word (M\-c)
7802 Capitalize the current (or following) word.
7803 With a negative argument,
7804 capitalize the previous word, but do not move point.
7805 .TP
7806 .B overwrite\-mode
7807 Toggle overwrite mode.
7808 With an explicit positive numeric argument, switches to overwrite mode.
7809 With an explicit non-positive numeric argument, switches to insert mode.
7810 This command affects only \fBemacs\fP mode;
7811 \fBvi\fP mode does overwrite differently.
7812 Each call to \fIreadline()\fP starts in insert mode.
7813 .IP
7814 In overwrite mode, characters bound to \fBself\-insert\fP replace
7815 the text at point rather than pushing the text to the right.
7816 Characters bound to \fBbackward\-delete\-char\fP replace the character
7817 before point with a space.
7818 By default, this command is unbound,
7819 but may be bound to the Insert key on some keyboards.
7820 .PD
7821 .SS Killing and Yanking
7822 .PD 0
7823 .TP
7824 .B kill\-line (C\-k)
7825 Kill the text from point to the end of the current line.
7826 With a negative numeric argument, kill backward from the cursor to the
7827 beginning of the line.
7828 .TP
7829 .B backward\-kill\-line (C\-x Rubout)
7830 Kill backward to the beginning of the current line.
7831 With a negative numeric argument, kill forward from the cursor to the
7832 end of the line.
7833 .TP
7834 .B unix\-line\-discard (C\-u)
7835 Kill backward from point to the beginning of the line,
7836 saving the killed text on the kill-ring.
7837 .\" There is no real difference between this and backward-kill-line
7838 .TP
7839 .B kill\-whole\-line
7840 Kill all characters on the current line, no matter where point is.
7841 .TP
7842 .B kill\-word (M\-d)
7843 Kill from point to the end of the current word, or if between
7844 words, to the end of the next word.
7845 Word boundaries are the same as those used by \fBforward\-word\fP.
7846 .TP
7847 .B backward\-kill\-word (M\-Rubout)
7848 Kill the word behind point.
7849 Word boundaries are the same as those used by \fBbackward\-word\fP.
7850 .TP
7851 .B shell\-kill\-word (M\-C\-d)
7852 Kill from point to the end of the current word, or if between
7853 words, to the end of the next word.
7854 Word boundaries are the same as those used by \fBshell\-forward\-word\fP.
7855 .TP
7856 .B shell\-backward\-kill\-word
7857 Kill the word behind point.
7858 Word boundaries are the same as those used by \fBshell\-backward\-word\fP.
7859 .TP
7860 .B unix\-word\-rubout (C\-w)
7861 Kill the word behind point, using white space as a word boundary,
7862 saving the killed text on the kill-ring.
7863 .TP
7864 .B unix\-filename\-rubout
7865 Kill the word behind point, using white space and the slash character
7866 as the word boundaries,
7867 saving the killed text on the kill-ring.
7868 .TP
7869 .B delete\-horizontal\-space (M\-\e)
7870 Delete all spaces and tabs around point.
7871 .TP
7872 .B kill\-region
7873 Kill the text in the current region.
7874 .TP
7875 .B copy\-region\-as\-kill
7876 Copy the text in the region to the kill buffer,
7877 so it can be yanked immediately.
7878 .TP
7879 .B copy\-backward\-word
7880 Copy the word before point to the kill buffer.
7881 The word boundaries are the same as \fBbackward\-word\fP.
7882 .TP
7883 .B copy\-forward\-word
7884 Copy the word following point to the kill buffer.
7885 The word boundaries are the same as \fBforward\-word\fP.
7886 .TP
7887 .B yank (C\-y)
7888 Yank the top of the kill ring into the buffer at point.
7889 .TP
7890 .B yank\-pop (M\-y)
7891 Rotate the kill ring, and yank the new top.
7892 Only works following
7893 .B yank
7894 or
7895 .BR yank\-pop .
7896 .PD
7897 .SS Numeric Arguments
7898 .PD 0
7899 .TP
7900 .B digit\-argument (M\-0, M\-1, \fR.\|.\|.\fP, M\-\-)
7901 Add this digit to the argument already accumulating, or start a new
7902 argument.
7903 M\-\- starts a negative argument.
7904 .TP
7905 .B universal\-argument
7906 This is another way to specify an argument.
7907 If this command is followed by one or more digits, optionally with a
7908 leading minus sign, those digits define the argument.
7909 If the command is followed by digits, executing
7910 .B universal\-argument
7911 again ends the numeric argument, but is otherwise ignored.
7912 As a special case, if this command is immediately followed by a
7913 character that is neither a digit nor minus sign,
7914 the argument count for the next command is multiplied by four.
7915 The argument count is initially one, so executing this function the
7916 first time makes the argument count four, a second time makes the
7917 argument count sixteen, and so on.
7918 .PD
7919 .SS Completing
7920 .PD 0
7921 .TP
7922 .B complete (TAB)
7923 Attempt to perform completion on the text before point.
7924 .B Bash
7925 attempts completion by first checking for any programmable
7926 completions for the command word (see \fBProgrammable Completion\fP below),
7927 otherwise treating the text as a
7928 variable (if the text begins with \fB$\fP),
7929 username (if the text begins with \fB\*~\fP),
7930 hostname (if the text begins with \fB@\fP), or
7931 command (including aliases, functions, and builtins) in turn.
7932 If none of these produces a match, it falls back to filename completion.
7933 .TP
7934 .B possible\-completions (M\-?)
7935 List the possible completions of the text before point.
7936 When displaying completions, \fBreadline\fP sets the number of columns used
7937 for display to the value of \fBcompletion-display-width\fP, the value of
7938 the shell variable
7939 .SM
7940 .BR COLUMNS ,
7941 or the screen width, in that order.
7942 .TP
7943 .B insert\-completions (M\-*)
7944 Insert all completions of the text before point
7945 that would have been generated by
7946 \fBpossible\-completions\fP,
7947 separated by a space.
7948 .TP
7949 .B menu\-complete
7950 Similar to \fBcomplete\fP, but replaces the word to be completed
7951 with a single match from the list of possible completions.
7952 Repeatedly executing \fBmenu\-complete\fP steps through the list
7953 of possible completions, inserting each match in turn.
7954 At the end of the list of completions,
7955 \fBmenu\-complete\fP rings the bell
7956 (subject to the setting of \fBbell\-style\fP)
7957 and restores the original text.
7958 An argument of \fIn\fP moves \fIn\fP positions forward in the list
7959 of matches; a negative argument moves backward through the list.
7960 This command is intended to be bound to \fBTAB\fP, but is unbound
7961 by default.
7962 .TP
7963 .B menu\-complete\-backward
7964 Identical to \fBmenu\-complete\fP, but moves backward through the list
7965 of possible completions, as if \fBmenu\-complete\fP had been given a
7966 negative argument.
7967 This command is unbound by default.
7968 .TP
7969 .B export\-completions
7970 Perform completion on the word before point as described above
7971 and write the list of possible completions to \fBreadline\fP's output
7972 stream using the following format, writing information on separate lines:
7973 .RS
7974 .PD
7975 .IP \(bu
7976 .PD 0
7977 the number of matches \fIN\fP;
7978 .IP \(bu
7979 the word being completed;
7980 .IP \(bu
7981 \fIS\fP:\fIE\fP,
7982 where \fIS\fP and \fIE\fP are the start and end offsets of the word
7983 in the \fBreadline\fP line buffer; then
7984 .IP \(bu
7985 each match, one per line
7986 .RE
7987 .PD
7988 .IP
7989 If there are no matches, the first line will be
7990 .Q 0 ,
7991 and this command does not print any output after the \fIS\fP:\fIE\fP.
7992 If there is only a single match, this prints a single line containing it.
7993 If there is more than one match, this prints the common prefix of the
7994 matches, which may be empty, on the first line after the \fIS\fP:\fIE\fP,
7995 then the matches on subsequent lines.
7996 In this case, \fIN\fP will include the first line with the common prefix.
7997 .IP
7998 The user or application
7999 should be able to accommodate the possibility of a blank line.
8000 The intent is that the user or application reads \fIN\fP lines after
8001 the line containing \fIS\fP:\fIE\fP to obtain the match list.
8002 This command is unbound by default.
8003 .TP
8004 .B delete\-char\-or\-list
8005 Deletes the character under the cursor if not at the beginning or
8006 end of the line (like \fBdelete\-char\fP).
8007 At the end of the line, it behaves identically to \fBpossible\-completions\fP.
8008 This command is unbound by default.
8009 .TP
8010 .B complete\-filename (M\-/)
8011 Attempt filename completion on the text before point.
8012 .TP
8013 .B possible\-filename\-completions (C\-x /)
8014 List the possible completions of the text before point,
8015 treating it as a filename.
8016 .TP
8017 .B complete\-username (M\-\*~)
8018 Attempt completion on the text before point, treating
8019 it as a username.
8020 .TP
8021 .B possible\-username\-completions (C\-x \*~)
8022 List the possible completions of the text before point,
8023 treating it as a username.
8024 .TP
8025 .B complete\-variable (M\-$)
8026 Attempt completion on the text before point, treating
8027 it as a shell variable.
8028 .TP
8029 .B possible\-variable\-completions (C\-x $)
8030 List the possible completions of the text before point,
8031 treating it as a shell variable.
8032 .TP
8033 .B complete\-hostname (M\-@)
8034 Attempt completion on the text before point, treating
8035 it as a hostname.
8036 .TP
8037 .B possible\-hostname\-completions (C\-x @)
8038 List the possible completions of the text before point,
8039 treating it as a hostname.
8040 .TP
8041 .B complete\-command (M\-!)
8042 Attempt completion on the text before point, treating
8043 it as a command name.
8044 Command completion attempts to
8045 match the text against aliases, reserved words, shell
8046 functions, shell builtins, and finally executable filenames,
8047 in that order.
8048 .TP
8049 .B possible\-command\-completions (C\-x !)
8050 List the possible completions of the text before point,
8051 treating it as a command name.
8052 .TP
8053 .B dynamic\-complete\-history (M\-TAB)
8054 Attempt completion on the text before point, comparing
8055 the text against history list entries for possible
8056 completion matches.
8057 .TP
8058 .B dabbrev\-expand
8059 Attempt menu completion on the text before point, comparing
8060 the text against lines from the history list for possible
8061 completion matches.
8062 .TP
8063 .B complete\-into\-braces (M\-{)
8064 Perform filename completion and insert the list of possible completions
8065 enclosed within braces so the list is available to the shell (see
8066 .B "Brace Expansion"
8067 above).
8068 .PD
8069 .SS "Keyboard Macros"
8070 .PD 0
8071 .TP
8072 .B start\-kbd\-macro (C\-x (\^)
8073 Begin saving the characters typed into the current keyboard macro.
8074 .TP
8075 .B end\-kbd\-macro (C\-x )\^)
8076 Stop saving the characters typed into the current keyboard macro
8077 and store the definition.
8078 .TP
8079 .B call\-last\-kbd\-macro (C\-x e)
8080 Re-execute the last keyboard macro defined, by making the characters
8081 in the macro appear as if typed at the keyboard.
8082 .TP
8083 .B print\-last\-kbd\-macro ()
8084 Print the last keyboard macro defined in a format suitable for the
8085 \fIinputrc\fP file.
8086 .PD
8087 .SS Miscellaneous
8088 .PD 0
8089 .TP
8090 .B re\-read\-init\-file (C\-x C\-r)
8091 Read in the contents of the \fIinputrc\fP file, and incorporate
8092 any bindings or variable assignments found there.
8093 .TP
8094 .B abort (C\-g)
8095 Abort the current editing command and
8096 ring the terminal's bell (subject to the setting of
8097 .BR bell\-style ).
8098 .TP
8099 .B do\-lowercase\-version (M\-A, M\-B, M\-\fIx\fP, \fR.\|.\|.\fP)
8100 If the metafied character \fIx\fP is uppercase, run the command
8101 that is bound to the corresponding metafied lowercase character.
8102 The behavior is undefined if \fIx\fP is already lowercase.
8103 .TP
8104 .B prefix\-meta (ESC)
8105 Metafy the next character typed.
8106 .SM
8107 .B ESC
8108 .B f
8109 is equivalent to
8110 .BR Meta\-f .
8111 .TP
8112 .B undo (C\-_, C\-x C\-u)
8113 Incremental undo, separately remembered for each line.
8114 .TP
8115 .B revert\-line (M\-r)
8116 Undo all changes made to this line.
8117 This is like executing the
8118 .B undo
8119 command enough times to return the line to its initial state.
8120 .TP
8121 .B tilde\-expand (M\-&)
8122 Perform tilde expansion on the current word.
8123 .TP
8124 .B set\-mark (C\-@, M\-<space>)
8125 Set the mark to the point.
8126 If a numeric argument is supplied, set the mark to that position.
8127 .TP
8128 .B exchange\-point\-and\-mark (C\-x C\-x)
8129 Swap the point with the mark.
8130 Set the current cursor position to the saved position,
8131 then set the mark to the old cursor position.
8132 .TP
8133 .B character\-search (C\-])
8134 Read a character and move point to the next occurrence of that character.
8135 A negative argument searches for previous occurrences.
8136 .TP
8137 .B character\-search\-backward (M\-C\-])
8138 Read a character and move point to the previous occurrence of that character.
8139 A negative argument searches for subsequent occurrences.
8140 .TP
8141 .B skip\-csi\-sequence
8142 Read enough characters to consume a multi-key sequence such as those
8143 defined for keys like Home and End.
8144 CSI sequences begin with a Control Sequence Indicator (CSI), usually
8145 .IR "ESC [" .
8146 If this sequence is bound to
8147 .Q \ee[ ,
8148 keys producing CSI sequences have no effect
8149 unless explicitly bound to a \fBreadline\fP command,
8150 instead of inserting stray characters into the editing buffer.
8151 This is unbound by default, but usually bound to
8152 .IR "ESC [" .
8153 .TP
8154 .B insert\-comment (M\-#)
8155 Without a numeric argument, insert the value of the \fBreadline\fP
8156 .B comment\-begin
8157 variable at the beginning of the current line.
8158 If a numeric argument is supplied, this command acts as a toggle: if
8159 the characters at the beginning of the line do not match the value
8160 of \fBcomment\-begin\fP, insert the value; otherwise delete
8161 the characters in \fBcomment-begin\fP from the beginning of the line.
8162 In either case, the line is accepted as if a newline had been typed.
8163 The default value of
8164 \fBcomment\-begin\fP causes this command to make the current line
8165 a shell comment.
8166 If a numeric argument causes the comment character to be removed, the line
8167 will be executed by the shell.
8168 .TP
8169 .B spell\-correct\-word (C\-x s)
8170 Perform spelling correction on the current word, treating it as a directory
8171 or filename, in the same way as the \fBcdspell\fP shell option.
8172 Word boundaries are the same as those used by \fBshell\-forward\-word\fP.
8173 .TP
8174 .B glob\-complete\-word (M\-g)
8175 Treat the word before point as a pattern for pathname expansion,
8176 with an asterisk implicitly appended, then use the pattern to
8177 generate a list of matching file names for possible completions.
8178 .TP
8179 .B glob\-expand\-word (C\-x *)
8180 Treat the word before point as a pattern for pathname expansion,
8181 and insert the list of matching file names, replacing the word.
8182 If a numeric argument is supplied, append a \fB*\fP before
8183 pathname expansion.
8184 .TP
8185 .B glob\-list\-expansions (C\-x g)
8186 Display the list of expansions that would have been generated by
8187 .B glob\-expand\-word
8188 and redisplay the line.
8189 If a numeric argument is supplied, append a \fB*\fP before
8190 pathname expansion.
8191 .TP
8192 .B dump\-functions
8193 Print all of the functions and their key bindings
8194 to the \fBreadline\fP output stream.
8195 If a numeric argument is supplied,
8196 the output is formatted in such a way that it can be made part
8197 of an \fIinputrc\fP file.
8198 .TP
8199 .B dump\-variables
8200 Print all of the settable \fBreadline\fP variables and their values
8201 to the \fBreadline\fP output stream.
8202 If a numeric argument is supplied,
8203 the output is formatted in such a way that it can be made part
8204 of an \fIinputrc\fP file.
8205 .TP
8206 .B dump\-macros
8207 Print all of the \fBreadline\fP key sequences bound to macros and the
8208 strings they output
8209 to the \fBreadline\fP output stream.
8210 If a numeric argument is supplied,
8211 the output is formatted in such a way that it can be made part
8212 of an \fIinputrc\fP file.
8213 .TP
8214 .B execute\-named\-command (M-x)
8215 Read a bindable \fBreadline\fP command name from the input and execute the
8216 function to which it's bound, as if the key sequence to which it was
8217 bound appeared in the input.
8218 If this function is supplied with a numeric argument, it passes that
8219 argument to the function it executes.
8220 .TP
8221 .B display\-shell\-version (C\-x C\-v)
8222 Display version information about the current instance of
8223 .BR bash .
8224 .PD
8225 .SS "Programmable Completion"
8226 When a user attempts word completion
8227 for a command or an argument to a command for
8228 which a completion specification (a \fIcompspec\fP) has been defined
8229 using the \fBcomplete\fP builtin
8230 (see
8231 .SM
8232 .B "SHELL BUILTIN COMMANDS"
8233 below),
8234 \fBreadline\fP invokes the programmable completion facilities.
8235 .PP
8236 First, \fBbash\fP identifies the command name.
8237 If a compspec has been defined for that command, the
8238 compspec is used to generate the list of possible completions for the word.
8239 If the command word is the empty string (completion attempted at the
8240 beginning of an empty line), \fBbash\fP uses any compspec defined with
8241 the \fB\-E\fP option to \fBcomplete\fP.
8242 The \fB\-I\fP option to \fBcomplete\fP
8243 indicates that the command word is the first non-assignment word
8244 on the line, or after a command delimiter such as
8245 \fB;\fP or \fB|\fP.
8246 This usually indicates command name completion.
8247 .PP
8248 If the command word is a full pathname, \fBbash\fP
8249 searches for a compspec for the full pathname first.
8250 If there is no compspec for the full pathname, \fBbash\fP attempts to
8251 find a compspec for the portion following the final slash.
8252 If those searches do not result in a compspec,
8253 or if there is no compspec for the command word,
8254 \fBbash\fP uses any compspec defined with
8255 the \fB\-D\fP option to \fBcomplete\fP as the default.
8256 If there is no default compspec, \fBbash\fP performs alias expansion
8257 on the command word as a final resort,
8258 and attempts to find a compspec for the command word
8259 resulting from any successful expansion.
8260 .PP
8261 If a compspec is not found, \fBbash\fP performs its default completion as
8262 described above under \fBCompleting\fP.
8263 Otherwise, once a compspec has been found, \fBbash\fP uses it to generate
8264 the list of matching words.
8265 .PP
8266 First, \fBbash\fP performs the \fIactions\fP specified by the compspec.
8267 This only returns matches which are prefixes
8268 of the word being completed.
8269 When the
8270 .B \-f
8271 or
8272 .B \-d
8273 option is used for filename or directory name completion,
8274 \fBbash\fP uses the shell variable
8275 .SM
8276 .B FIGNORE
8277 to filter the matches.
8278 .PP
8279 Next, programmable completion generates matches
8280 specified by a pathname expansion pattern
8281 supplied as an argument to the
8282 \fB\-G\fP option.
8283 The words generated by the pattern need not match the word
8284 being completed.
8285 \fBBash\fP
8286 uses the
8287 .SM
8288 .B FIGNORE
8289 variable to filter the matches, but does not use the
8290 .SM
8291 .B GLOBIGNORE
8292 shell variable.
8293 .PP
8294 Next, completion considers
8295 the string specified as the argument to the \fB\-W\fP option.
8296 The string is first split using the characters in the
8297 .SM
8298 .B IFS
8299 special variable as delimiters.
8300 This honors shell quoting within the string, in order to provide a
8301 mechanism for the words to contain shell metacharacters or characters
8302 in the value of
8303 .SM
8304 .BR IFS .
8305 Each word is then expanded using
8306 brace expansion, tilde expansion, parameter and variable expansion,
8307 command substitution, and arithmetic expansion,
8308 as described above under
8309 .SM
8310 .BR EXPANSION .
8311 The results are split using the rules described above under
8312 \fBWord Splitting\fP.
8313 The results of the expansion are prefix-matched against the word being
8314 completed, and the matching words become possible completions.
8315 .PP
8316 After these matches have been generated,
8317 \fBbash\fP executes any shell function or command
8318 specified with the \fB\-F\fP and \fB\-C\fP options.
8319 When the command or function is invoked, \fBbash\fP
8320 assigns values to the
8321 .SM
8322 .BR COMP_LINE ,
8323 .SM
8324 .BR COMP_POINT ,
8325 .SM
8326 .BR COMP_KEY ,
8327 and
8328 .SM
8329 .B COMP_TYPE
8330 variables as described above
8331 under \fBShell Variables\fP.
8332 If a shell function is being invoked, \fBbash\fP
8333 also sets the
8334 .SM
8335 .B COMP_WORDS
8336 and
8337 .SM
8338 .B COMP_CWORD
8339 variables.
8340 When the function or command is invoked,
8341 the first argument (\fB$1\fP) is the name of the command whose arguments
8342 are being completed,
8343 the second argument (\fB$2\fP) is the word being completed,
8344 and the third argument (\fB$3\fP) is the word preceding the word being
8345 completed on the current command line.
8346 There is no filtering of the generated completions against the
8347 word being completed;
8348 the function or command has complete freedom in generating the matches
8349 and they do not need to match a prefix of the word.
8350 .PP
8351 Any function specified with \fB\-F\fP is invoked first.
8352 The function may use any of the shell facilities, including the
8353 \fBcompgen\fP and \fBcompopt\fP
8354 builtins described below, to generate the matches.
8355 It must put the possible completions in the
8356 .SM
8357 .B COMPREPLY
8358 array variable, one per array element.
8359 .PP
8360 Next, any command specified with the \fB\-C\fP option is invoked
8361 in an environment equivalent to command substitution.
8362 It should print a list of completions, one per line, to the
8363 standard output.
8364 Backslash will escape a newline, if necessary.
8365 These are added to the set of possible completions.
8366 .PP
8367 After generating all of the possible completions,
8368 \fBbash\fP applies any filter
8369 specified with the \fB\-X\fP option to the completions in the list.
8370 The filter is a pattern as used for pathname expansion; a \fB&\fP
8371 in the pattern is replaced with the text of the word being completed.
8372 A literal \fB&\fP may be escaped with a backslash; the backslash
8373 is removed before attempting a match.
8374 Any completion that matches the pattern is removed from the list.
8375 A leading \fB!\fP negates the pattern;
8376 in this case \fBbash\fP removes
8377 any completion that does not match the pattern.
8378 If the
8379 .B nocasematch
8380 shell option is enabled,
8381 \fBbash\fP performs the match without regard to the case
8382 of alphabetic characters.
8383 .PP
8384 Finally, programmable completion adds
8385 any prefix and suffix specified with the
8386 \fB\-P\fP and \fB\-S\fP
8387 options, respectively, to each completion,
8388 and returns the result
8389 to \fBreadline\fP as the list of possible completions.
8390 .PP
8391 If the previously-applied actions do not generate any matches, and the
8392 \fB\-o dirnames\fP option was supplied to \fBcomplete\fP when the
8393 compspec was defined, \fBbash\fP attempts directory name completion.
8394 .PP
8395 If the \fB\-o plusdirs\fP option was supplied to \fBcomplete\fP when the
8396 compspec was defined, \fBbash\fP attempts directory name completion and
8397 adds any matches to the set of possible completions.
8398 .PP
8399 By default, if a compspec is found, whatever it generates is returned
8400 to the completion code as the full set of possible completions.
8401 The default \fBbash\fP completions and the \fBreadline\fP
8402 default of filename completion are disabled.
8403 If the \fB\-o bashdefault\fP option was supplied to \fBcomplete\fP when
8404 the compspec was defined,
8405 and the compspec generates no matches,
8406 \fBbash\fP attempts its default completions.
8407 If the compspec and, if attempted, the default \fBbash\fP completions
8408 generate no matches,
8409 and the \fB\-o default\fP option was supplied to
8410 \fBcomplete\fP when the compspec was defined,
8411 programmable completion performs \fBreadline\fP's default completion.
8412 .PP
8413 The options supplied to \fBcomplete\fP and \fBcompopt\fP
8414 can control how \fBreadline\fP treats the completions.
8415 For instance, the \fI\-o fullquote\fP option tells \fBreadline\fP
8416 to quote the matches as if they were filenames.
8417 See the description of \fBcomplete\fP below
8418 for details.
8419 .PP
8420 When a compspec indicates that it wants directory name completion,
8421 the programmable completion functions force \fBreadline\fP
8422 to append a slash to completed names which are symbolic links
8423 to directories, subject to the value of the
8424 \fBmark\-directories\fP \fBreadline\fP variable,
8425 regardless of the setting of the
8426 \fBmark-symlinked\-directories\fP \fBreadline\fP variable.
8427 .PP
8428 There is some support for dynamically modifying completions.
8429 This is most useful when used in combination with a default completion
8430 specified with \fBcomplete \-D\fP.
8431 It's possible for shell functions executed as completion functions
8432 to indicate that completion should be retried by returning an
8433 exit status of 124.
8434 If a shell function returns 124, and changes
8435 the compspec associated with the command on which completion is being
8436 attempted (supplied as the first argument when the function is executed),
8437 programmable completion restarts from the beginning, with an
8438 attempt to find a new compspec for that command.
8439 This can be used to build a set of completions dynamically
8440 as completion is attempted, rather than loading them all at once.
8441 .PP
8442 For instance, assuming that there is a library of compspecs, each kept in a
8443 file corresponding to the name of the command, the following default
8444 completion function would load completions dynamically:
8445 .RS
8446 .EX
8447 .nf
8448 _completion_loader()
8449 {
8450 . \*"/etc/bash_completion.d/$1.sh\*" \c
8451 .if \n(LL<80n \{\
8452 \e
8453 .br
8454 .ti +4n
8455 .\}
8456 >/dev/null 2>&1 && return 124
8457 }
8458 complete \-D \-F _completion_loader \c
8459 .if \n(LL<80n \{\
8460 \e
8461 .br
8462 .ti +4n
8463 .\}
8464 \-o bashdefault \-o default
8465 .fi
8466 .EE
8467 .RE
8468 .SH HISTORY
8469 When the
8470 .B \-o history
8471 option to the
8472 .B set
8473 builtin is enabled, the shell provides access to the
8474 \fIcommand history\fP,
8475 the list of commands previously typed.
8476 The value of the
8477 .SM
8478 .B HISTSIZE
8479 variable is used as the
8480 number of commands to save in a history list:
8481 the shell saves the text of the last
8482 .SM
8483 .B HISTSIZE
8484 commands (default 500).
8485 The shell stores each command in the history list prior to
8486 parameter and variable expansion (see
8487 .SM
8488 .B EXPANSION
8489 above) but after history expansion is performed, subject to the
8490 values of the shell variables
8491 .SM
8492 .B HISTIGNORE
8493 and
8494 .SM
8495 .BR HISTCONTROL .
8496 .PP
8497 On startup, \fBbash\fP initializes the history list
8498 by reading history entries from the
8499 file named by the
8500 .SM
8501 .B HISTFILE
8502 variable (default
8503 .FN \*~/.bash_history ).
8504 That file is referred to as the \fIhistory file\fP.
8505 The history file is truncated, if necessary,
8506 to contain no more than the number of history entries
8507 specified by the value of the
8508 .SM
8509 .B HISTFILESIZE
8510 variable.
8511 If
8512 .SM
8513 .B HISTFILESIZE
8514 is unset, or set to null, a non-numeric value,
8515 or a numeric value less than zero, the history file is not truncated.
8516 .PP
8517 When the history file is read,
8518 lines beginning with the history comment character followed immediately
8519 by a digit are interpreted as timestamps for the following history line.
8520 These timestamps are optionally displayed depending on the value of the
8521 .SM
8522 .B HISTTIMEFORMAT
8523 variable.
8524 When present, history timestamps delimit history entries, making
8525 multi-line entries possible.
8526 .PP
8527 When a shell with history enabled exits, \fBbash\fP copies the last
8528 .SM
8529 .B $HISTSIZE
8530 entries from the history list to
8531 .SM
8532 .BR $HISTFILE .
8533 If the
8534 .B histappend
8535 shell option is enabled
8536 (see the description of
8537 .B shopt
8538 under
8539 .SM
8540 .B "SHELL BUILTIN COMMANDS"
8541 below), \fBbash\fP appends the entries to the history file,
8542 otherwise it overwrites the history file.
8543 If
8544 .SM
8545 .B HISTFILE
8546 is unset or null,
8547 or if the history file is unwritable, the history is not saved.
8548 After saving the history, \fBbash\fP truncates the history file
8549 to contain no more than
8550 .SM
8551 .B HISTFILESIZE
8552 lines as described above.
8553 .PP
8554 If the
8555 .SM
8556 .B HISTTIMEFORMAT
8557 variable is set, the shell writes
8558 the timestamp information
8559 associated with each history entry to the history file,
8560 marked with the history comment character, so
8561 timestamps are preserved across shell sessions.
8562 This uses the history comment character to distinguish timestamps from
8563 other history lines.
8564 As above, when using
8565 .SM
8566 .BR HISTTIMEFORMAT ,
8567 the timestamps delimit multi-line history entries.
8568 .PP
8569 The
8570 .B fc
8571 builtin command (see
8572 .SM
8573 .B "SHELL BUILTIN COMMANDS"
8574 below) will list or edit and re-execute a portion of the history list.
8575 The
8576 .B history
8577 builtin can display or modify the history list and
8578 manipulate the history file.
8579 When using command-line editing, search commands
8580 are available in each editing mode that provide access to the
8581 history list.
8582 .PP
8583 The shell allows control over which commands are saved on the history list.
8584 The
8585 .SM
8586 .B HISTCONTROL
8587 and
8588 .SM
8589 .B HISTIGNORE
8590 variables are used to save only a subset of the commands entered.
8591 If the
8592 .B cmdhist
8593 shell option is enabled, the shell attempts to save each
8594 line of a multi-line command in the same history entry, adding
8595 semicolons where necessary to preserve syntactic correctness.
8596 The
8597 .B lithist
8598 shell option modifies \fBcmdhist\fP by saving
8599 the command with embedded newlines instead of semicolons.
8600 See the description of the
8601 .B shopt
8602 builtin below under
8603 .SM
8604 .B "SHELL BUILTIN COMMANDS"
8605 for information on setting and unsetting shell options.
8606 .SH "HISTORY EXPANSION"
8607 The shell supports a history expansion feature that
8608 is similar to the history expansion in
8609 .BR csh .
8610 This section describes what syntax features are available.
8611 .PP
8612 History expansion is enabled by default for interactive shells,
8613 and can be disabled using the
8614 .B +H
8615 option to the
8616 .B set
8617 builtin command (see
8618 .SM
8619 .B "SHELL BUILTIN COMMANDS"
8620 below).
8621 Non-interactive shells do not perform history expansion by default,
8622 but it can be enabled with
8623 .Q "set -H" .
8624 .PP
8625 History expansions introduce words from the history list into
8626 the input stream, making it easy to repeat commands, insert the
8627 arguments to a previous command into the current input line, or
8628 fix errors in previous commands quickly.
8629 .PP
8630 History expansion is performed immediately after a complete line
8631 is read, before the shell breaks it into words, and is performed
8632 on each line individually.
8633 The shell attempts to inform the history
8634 expansion functions about quoting still in effect from previous lines.
8635 .PP
8636 It takes place in two parts.
8637 The first is to determine which history list entry
8638 to use during substitution.
8639 The second is to select portions of that entry to include into
8640 the current one.
8641 .PP
8642 The entry selected from the history is the \fIevent\fP,
8643 and the portions of that entry that are acted upon are \fIwords\fP.
8644 Various \fImodifiers\fP are available to manipulate the selected words.
8645 The entry is split into words in the same fashion as when reading input,
8646 so that several \fImetacharacter\fP-separated words surrounded by
8647 quotes are considered one word.
8648 The \fIevent designator\fP selects the event, the optional
8649 \fIword designator\fP selects words from the event, and
8650 various optional \fImodifiers\fP are available to manipulate the
8651 selected words.
8652 .PP
8653 History expansions are introduced by the appearance of the
8654 history expansion character, which is \^\fB!\fP\^ by default.
8655 History expansions may appear anywhere in the input, but do not nest.
8656 .PP
8657 Only backslash (\^\fB\e\fP\^) and single quotes can quote
8658 the history expansion character, but the history expansion character is
8659 also treated as quoted if it immediately precedes the closing double quote
8660 in a double-quoted string.
8661 .PP
8662 Several characters inhibit history expansion if found immediately
8663 following the history expansion character, even if it is unquoted:
8664 space, tab, newline, carriage return, \fB=\fP,
8665 and the other shell metacharacters defined above.
8666 .PP
8667 There is a special abbreviation for substitution, active when the
8668 \fIquick substitution\fP character (described above under
8669 .BR histchars )
8670 is the first character on the line.
8671 It selects the previous history list entry, using an event designator
8672 equivalent to \fB!!\fP,
8673 and substitutes one string for another in that entry.
8674 It is described below under \fBEvent Designators\fP.
8675 This is the only history expansion that does not begin with the history
8676 expansion character.
8677 .PP
8678 Several shell options settable with the
8679 .B shopt
8680 builtin will modify history expansion behavior
8681 (see the description of the
8682 .B shopt
8683 builtin below).and
8684 If the
8685 .B histverify
8686 shell option is enabled, and
8687 .B readline
8688 is being used, history substitutions are not immediately passed to
8689 the shell parser.
8690 Instead, the expanded line is reloaded into the
8691 .B readline
8692 editing buffer for further modification.
8693 If
8694 .B readline
8695 is being used, and the
8696 .B histreedit
8697 shell option is enabled, a failed history substitution is reloaded
8698 into the
8699 .B readline
8700 editing buffer for correction.
8701 .PP
8702 The
8703 .B \-p
8704 option to the
8705 .B history
8706 builtin command shows what a history expansion will
8707 do before using it.
8708 The
8709 .B \-s
8710 option to the
8711 .B history
8712 builtin will add commands to the end of the history list
8713 without actually executing them, so that they are available for
8714 subsequent recall.
8715 .PP
8716 The shell allows control of the various characters used by the
8717 history expansion mechanism (see the description of
8718 .B histchars
8719 above under
8720 .BR "Shell Variables" ).
8721 The shell uses
8722 the history comment character to mark history timestamps when
8723 writing the history file.
8724 .SS Event Designators
8725 An event designator is a reference to an entry in the history list.
8726 The event designator
8727 consists of the portion of the word beginning with the history
8728 expansion character and ending with the word designator if present,
8729 or the end of the word.
8730 Unless the reference is absolute, events are relative to the current
8731 position in the history list.
8732 .PP
8733 .PD 0
8734 .TP
8735 .B !
8736 Start a history substitution, except when followed by a
8737 .BR blank ,
8738 newline, carriage return, =,
8739 or, when the \fBextglob\fP shell option is enabled using
8740 the \fBshopt\fP builtin, (.
8741 .TP
8742 .B !\fIn\fP
8743 Refer to history list entry
8744 .IR n .
8745 .TP
8746 .B !\-\fIn\fP
8747 Refer to the current entry minus
8748 .IR n .
8749 .TP
8750 .B !!
8751 Refer to the previous entry.
8752 This is a synonym for
8753 .Q !\-1 .
8754 .TP
8755 .B !\fIstring\fP
8756 Refer to the most recent command preceding the current position in the
8757 history list starting with
8758 .IR string .
8759 .TP
8760 .B !?\fIstring\fR\fB[?]\fP
8761 Refer to the most recent command preceding the current position in the
8762 history list containing
8763 .IR string .
8764 The trailing \fB?\fP may be omitted if
8765 .I string
8766 is followed immediately by a newline.
8767 If \fIstring\fP is missing, this uses
8768 the string from the most recent search;
8769 it is an error if there is no previous search string.
8770 .TP
8771 .B \d\s+2\*^\s-2\u\fIstring1\fP\d\s+2\*^\s-2\u\fIstring2\fP\d\s+2\*^\s-2\u
8772 Quick substitution.
8773 Repeat the previous command, replacing
8774 .I string1
8775 with
8776 .IR string2 .
8777 Equivalent to
8778 .Q !!:s\d\s+2\*^\s-2\u\fIstring1\fP\d\s+2\*^\s-2\u\fIstring2\fP\d\s+2\*^\s-2\u
8779 (see \fBModifiers\fP below).
8780 .TP
8781 .B !#
8782 The entire command line typed so far.
8783 .PD
8784 .SS Word Designators
8785 Word designators are used to select desired words from the event.
8786 They are optional; if the word designator isn't supplied, the history
8787 expansion uses the entire event.
8788 A
8789 .B :
8790 separates the event specification from the word designator.
8791 It may be omitted if the word designator begins with a
8792 .BR \*^ ,
8793 .BR $ ,
8794 .BR * ,
8795 .BR \- ,
8796 or
8797 .BR % .
8798 Words are numbered from the beginning of the line,
8799 with the first word being denoted by 0 (zero).
8800 Words are inserted into the current line separated by single spaces.
8801 .PP
8802 .PD 0
8803 .TP
8804 .B 0 (zero)
8805 The zeroth word.
8806 For the shell, this is the command word.
8807 .TP
8808 .I n
8809 The \fIn\fPth word.
8810 .TP
8811 .B \*^
8812 The first argument: word 1.
8813 .TP
8814 .B $
8815 The last word.
8816 This is usually the last argument, but will expand to the
8817 zeroth word if there is only one word in the line.
8818 .TP
8819 .B %
8820 The first word matched by the most recent
8821 .Q ?\fIstring\fP?
8822 search,
8823 if the search string begins with a character that is part of a word.
8824 By default, searches begin at the end of each line and proceed to the
8825 beginning, so the first word matched is the one closest to the end of
8826 the line.
8827 .TP
8828 .I x\fB\-\fPy
8829 A range of words;
8830 .Q \-\fIy\fP
8831 abbreviates
8832 .Q 0\-\fIy\fP .
8833 .TP
8834 .B *
8835 All of the words but the zeroth.
8836 This is a synonym for
8837 .Q \fI1\-$\fP .
8838 It is not an error to use
8839 .B *
8840 if there is just one word in the event;
8841 it expands to the empty string in that case.
8842 .TP
8843 .B x*
8844 Abbreviates \fIx\-$\fP.
8845 .TP
8846 .B x\-
8847 Abbreviates \fIx\-$\fP like \fBx*\fP, but omits the last word.
8848 If \fBx\fP is missing, it defaults to 0.
8849 .PD
8850 .PP
8851 If a word designator is supplied without an event specification, the
8852 previous command is used as the event, equivalent to \fB!!\fP.
8853 .SS Modifiers
8854 After the optional word designator, the expansion may include a
8855 sequence of one or more of the following modifiers, each preceded by a
8856 .Q : .
8857 These modify, or edit, the word or words selected from the history event.
8858 .PP
8859 .PD 0
8860 .TP
8861 .B h
8862 Remove a trailing pathname component, leaving only the head.
8863 .TP
8864 .B t
8865 Remove all leading pathname components, leaving the tail.
8866 .TP
8867 .B r
8868 Remove a trailing suffix of the form \fI.xxx\fP, leaving the
8869 basename.
8870 .TP
8871 .B e
8872 Remove all but the trailing suffix.
8873 .TP
8874 .B p
8875 Print the new command but do not execute it.
8876 .TP
8877 .B q
8878 Quote the substituted words, escaping further substitutions.
8879 .TP
8880 .B x
8881 Quote the substituted words as with
8882 .BR q ,
8883 but break into words at
8884 .B blanks
8885 and newlines.
8886 The \fBq\fP and \fBx\fP modifiers are mutually exclusive;
8887 expansion uses the last one supplied.
8888 .TP
8889 .B s/\fIold\fP/\fInew\fP/
8890 Substitute
8891 .I new
8892 for the first occurrence of
8893 .I old
8894 in the event line.
8895 Any character may be used as the delimiter in place of /.
8896 The final delimiter is optional if it is the last character of the
8897 event line.
8898 A single backslash quotes the delimiter in
8899 .I old
8900 and
8901 .IR new .
8902 If & appears in
8903 .IR new ,
8904 it is replaced with
8905 .IR old .
8906 A single backslash quotes the &.
8907 If
8908 .I old
8909 is null, it is set to the last
8910 .I old
8911 substituted, or, if no previous history substitutions took place,
8912 the last
8913 .I string
8914 in a
8915 .B !?\fIstring\fP[?]
8916 search.
8917 If
8918 .I new
8919 is null, each matching
8920 .I old
8921 is deleted.
8922 .TP
8923 .B &
8924 Repeat the previous substitution.
8925 .TP
8926 .B g
8927 Cause changes to be applied over the entire event line.
8928 This is used in conjunction with
8929 .Q \fB:s\fP
8930 (e.g.,
8931 .Q \fB:gs/\fIold\fP/\fInew\fP/\fR )
8932 or
8933 .Q \fB:&\fP .
8934 If used with
8935 .Q \fB:s\fP ,
8936 any delimiter can be used in place of /,
8937 and the final delimiter is optional
8938 if it is the last character of the event line.
8939 An \fBa\fP may be used as a synonym for \fBg\fP.
8940 .TP
8941 .B G
8942 Apply the following
8943 .Q \fBs\fP
8944 or
8945 .Q \fB&\fP
8946 modifier once to each word in the event line.
8947 .PD
8948 .SH "SHELL BUILTIN COMMANDS"
8949 .\" start of bash_builtins
8950 .zZ
8951 .PP
8952 Unless otherwise noted, each builtin command documented in this
8953 section as accepting options preceded by
8954 .B \-
8955 accepts
8956 .B \-\-
8957 to signify the end of the options.
8958 The \fB:\fP, \fBtrue\fP, \fBfalse\fP, and \fBtest\fP/\fB[\fP builtins
8959 do not accept options and do not treat \fB\-\-\fP specially.
8960 The \fBexit\fP, \fBlogout\fP, \fBreturn\fP,
8961 \fBbreak\fP, \fBcontinue\fP, \fBlet\fP,
8962 and \fBshift\fP builtins accept and process arguments beginning with
8963 \fB\-\fP without requiring \fB\-\-\fP.
8964 Other builtins that accept arguments but are not specified as accepting
8965 options interpret arguments beginning with \fB\-\fP as invalid options and
8966 require \fB\-\-\fP to prevent this interpretation.
8967 .PP
8968 .PD 0
8969 .TP
8970 \fB:\fP [\fIarguments\fP]
8971 .PD
8972 No effect; the command does nothing beyond expanding
8973 .I arguments
8974 and performing any specified
8975 redirections.
8976 The return status is zero.
8977 .TP
8978 \fB\&.\&\fP [\fB\-p\fP \fIpath\fP] \fIfilename\fP [\fIarguments\fP]
8979 .PD 0
8980 .TP
8981 \fBsource\fP [\fB\-p\fP \fIpath\fP] \fIfilename\fP [\fIarguments\fP]
8982 .PD
8983 The \fB\&.\&\fP command (\fBsource\fP) reads and execute commands from
8984 .I filename
8985 in the current shell environment and returns the exit status of the
8986 last command executed from
8987 .IR filename .
8988 .IP
8989 If \fIfilename\fP does not contain a slash, \fB\&.\&\fP searches for it.
8990 If the \fB\-p\fP option is supplied, \fB\&.\&\fP treats \fIpath\fP
8991 as a colon-separated list of directories in which to find \fIfilename\fP;
8992 otherwise, \fB\&.\&\fP uses the entries in
8993 .SM
8994 .B PATH
8995 to find the directory containing
8996 .IR filename .
8997 \fIfilename\fP does not need to be executable.
8998 When \fBbash\fP is not in posix mode, it searches
8999 the current directory if \fIfilename\fP is not found in
9000 .SM
9001 .BR PATH ,
9002 but does not search the current directory if \fB\-p\fP is supplied.
9003 If the
9004 .B sourcepath
9005 option to the
9006 .B shopt
9007 builtin command is turned off, \fB\&.\&\fP does not search
9008 .SM
9009 .BR PATH .
9010 .IP
9011 If any \fIarguments\fP are supplied, they become the positional
9012 parameters when \fIfilename\fP is executed.
9013 Otherwise the positional parameters are unchanged.
9014 .IP
9015 If the \fB\-T\fP option is enabled, \fB.\fP inherits any trap on
9016 \fBDEBUG\fP; if it is not, any \fBDEBUG\fP trap string is saved and
9017 restored around the call to \fB.\fP, and \fB.\fP unsets the
9018 \fBDEBUG\fP trap while it executes.
9019 If \fB\-T\fP is not set, and the sourced file changes
9020 the \fBDEBUG\fP trap, the new value persists after \fB.\fP completes.
9021 The return status is the status of the last command executed from
9022 \fIfilename\fP (0 if no commands are executed), and non-zero if
9023 .I filename
9024 is not found or cannot be read.
9025 .TP
9026 \fBalias\fP [\fB\-p\fP] [\fIname\fP[=\fIvalue\fP] .\|.\|.]
9027 With no arguments or with the
9028 .B \-p
9029 option, \fBalias\fP prints the list of aliases in the form
9030 \fBalias\fP \fIname\fP=\fIvalue\fP on standard output.
9031 When arguments are supplied, define an alias for
9032 each \fIname\fP whose \fIvalue\fP is given.
9033 A trailing space in \fIvalue\fP causes the next word to be
9034 checked for alias substitution when the alias is expanded
9035 during command parsing.
9036 For each \fIname\fP in the argument list for which no \fIvalue\fP
9037 is supplied, print the name and value of the alias \fIname\fP.
9038 \fBalias\fP returns true unless a \fIname\fP is given
9039 (without a corresponding =\fIvalue\fP)
9040 for which no alias has been defined.
9041 .TP
9042 \fBbg\fP [\fIjobspec\fP .\|.\|.]
9043 Resume each suspended job \fIjobspec\fP in the background, as if it
9044 had been started with
9045 .BR & .
9046 If
9047 .I jobspec
9048 is not present, the shell uses its notion of the \fIcurrent job\fP.
9049 .B bg
9050 .I jobspec
9051 returns 0 unless run when job control is disabled or, when run with
9052 job control enabled, any specified \fIjobspec\fP was not found
9053 or was started without job control.
9054 .TP
9055 \fBbind\fP [\fB\-m\fP \fIkeymap\fP] [\fB\-lsvSVX\fP]
9056 .PD 0
9057 .TP
9058 \fBbind\fP [\fB\-m\fP \fIkeymap\fP] [\fB\-q\fP \fIfunction\fP] [\fB\-u\fP \fIfunction\fP] [\fB\-r\fP \fIkeyseq\fP]
9059 .TP
9060 \fBbind\fP [\fB\-m\fP \fIkeymap\fP] \fB\-f\fP \fIfilename\fP
9061 .TP
9062 \fBbind\fP [\fB\-m\fP \fIkeymap\fP] \fB\-x\fP \fIkeyseq\fP[:] \fIshell\-command\fP
9063 .TP
9064 \fBbind\fP [\fB\-m\fP \fIkeymap\fP] \fIkeyseq\fP:\fIfunction\-name\fP
9065 .TP
9066 \fBbind\fP [\fB\-m\fP \fIkeymap\fP] \fB\-p\fP|\fB\-P\fP [\fIreadline\-command\fP]
9067 .TP
9068 \fBbind\fP [\fB\-m\fP \fIkeymap\fP] \fIkeyseq\fP:\fIreadline\-command\fP
9069 .TP
9070 \fBbind\fP \fIreadline-command-line\fP
9071 .PD
9072 Display current
9073 .B readline
9074 key and function bindings, bind a key sequence to a
9075 .B readline
9076 function or macro
9077 or to a shell command, or set a
9078 .B readline
9079 variable.
9080 Each non-option argument is a key binding or command as it would appear in a
9081 .B readline
9082 initialization file such as
9083 .IR .inputrc ,
9084 but each binding or command must be passed as a separate argument;
9085 e.g., \*'\*"\eC\-x\eC\-r\*": re\-read\-init\-file\*'.
9086 In the following descriptions, output available to be re-read is formatted
9087 as commands that would appear in a
9088 .B readline
9089 initialization file or that would be supplied as individual arguments to a
9090 .B bind
9091 command.
9092 Options, if supplied, have the following meanings:
9093 .RS
9094 .PD 0
9095 .TP
9096 .B \-m \fIkeymap\fP
9097 Use
9098 .I keymap
9099 as the keymap to be affected by the subsequent bindings.
9100 Acceptable
9101 .I keymap
9102 names are
9103 \fIemacs, emacs\-standard, emacs\-meta, emacs\-ctlx, vi,
9104 vi\-move, vi\-command\fP, and
9105 .IR vi\-insert .
9106 \fIvi\fP is equivalent to \fIvi\-command\fP
9107 (\fIvi\-move\fP is also a synonym);
9108 \fIemacs\fP is equivalent to \fIemacs\-standard\fP.
9109 .TP
9110 .B \-l
9111 List the names of all \fBreadline\fP functions.
9112 .TP
9113 .B \-p
9114 Display \fBreadline\fP function names and bindings in such a way
9115 that they can be
9116 used as an argument to a subsequent
9117 \fBbind\fP command or in a \fBreadline\fP initialization file.
9118 If arguments remain after option processing, \fBbind\fP treats
9119 them as \fBreadline\fP command names and restricts output to those names.
9120 .TP
9121 .B \-P
9122 List current \fBreadline\fP function names and bindings.
9123 If arguments remain after option processing, \fBbind\fP treats
9124 them as \fBreadline\fP command names and restricts output to those names.
9125 .TP
9126 .B \-s
9127 Display \fBreadline\fP key sequences bound to macros and the strings
9128 they output in such a way that they can be used
9129 as an argument to a subsequent \fBbind\fP command
9130 or in a \fBreadline\fP initialization file.
9131 .TP
9132 .B \-S
9133 Display \fBreadline\fP key sequences bound to macros and the strings
9134 they output.
9135 .TP
9136 .B \-v
9137 Display \fBreadline\fP variable names and values in such a way that they
9138 can be
9139 used as an argument to a subsequent
9140 \fBbind\fP command or in a \fBreadline\fP initialization file.
9141 .TP
9142 .B \-V
9143 List current \fBreadline\fP variable names and values.
9144 .TP
9145 .B \-f \fIfilename\fP
9146 Read key bindings from \fIfilename\fP.
9147 .TP
9148 .B \-q \fIfunction\fP
9149 Display key sequences that invoke the named \fBreadline\fP \fIfunction\fP.
9150 .TP
9151 .B \-u \fIfunction\fP
9152 Unbind all key sequences bound to the named \fBreadline\fP \fIfunction\fP.
9153 .TP
9154 .B \-r \fIkeyseq\fP
9155 Remove any current binding for \fIkeyseq\fP.
9156 .TP
9157 .B \-x \fIkeyseq\fP[: ]\fIshell\-command\fP
9158 Cause \fIshell\-command\fP to be executed whenever \fIkeyseq\fP is
9159 entered.
9160 The separator between \fIkeyseq\fP and \fIshell\-command\fP is either
9161 whitespace or a colon optionally followed by whitespace.
9162 If the separator is whitespace, \fIshell\-command\fP
9163 must be enclosed in double quotes and \fBreadline\fP expands any of its
9164 special backslash-escapes in \fIshell\-command\fP before saving it.
9165 If the separator is a colon, any enclosing double quotes are optional, and
9166 \fBreadline\fP does not expand the command string before saving it.
9167 Since the entire key binding expression must be a single argument, it
9168 should be enclosed in single quotes.
9169 When \fIshell\-command\fP is executed, the shell sets the
9170 .SM
9171 .B READLINE_LINE
9172 variable to the contents of the \fBreadline\fP line buffer and the
9173 .SM
9174 .B READLINE_POINT
9175 and
9176 .SM
9177 .B READLINE_MARK
9178 variables to the current location of the insertion point and the saved
9179 insertion point (the mark), respectively.
9180 The shell assigns any numeric argument the user supplied to the
9181 .SM
9182 .B READLINE_ARGUMENT
9183 variable.
9184 If there was no argument, that variable is not set.
9185 If the executed command changes the value of any of
9186 .SM
9187 .BR READLINE_LINE ,
9188 .SM
9189 .BR READLINE_POINT ,
9190 or
9191 .SM
9192 .BR READLINE_MARK ,
9193 those new values will be reflected in the editing state.
9194 .TP
9195 .B \-X
9196 List all key sequences bound to shell commands and the associated commands
9197 in a format that can be reused as
9198 an argument to a subsequent \fBbind\fP command.
9199 .PD
9200 .PP
9201 The return value is 0 unless an unrecognized option is supplied or an
9202 error occurred.
9203 .RE
9204 .TP
9205 \fBbreak\fP [\fIn\fP]
9206 Exit from within a
9207 .BR for ,
9208 .BR while ,
9209 .BR until ,
9210 or
9211 .B select
9212 loop.
9213 If \fIn\fP is specified, \fBbreak\fP exits \fIn\fP enclosing loops.
9214 .I n
9215 must be \(>= 1. If
9216 .I n
9217 is greater than the number of enclosing loops, all enclosing loops
9218 are exited.
9219 The return value is 0 unless \fIn\fP is not greater than or equal to 1.
9220 .TP
9221 \fBbuiltin\fP \fIshell\-builtin\fP [\fIarguments\fP]
9222 Execute the specified shell builtin \fIshell\-builtin\fP, passing it
9223 .IR arguments ,
9224 and return its exit status.
9225 This is useful when defining a
9226 function whose name is the same as a shell builtin,
9227 retaining the functionality of the builtin within the function.
9228 The \fBcd\fP builtin is commonly redefined this way.
9229 The return status is false if
9230 .I shell\-builtin
9231 is not a shell builtin command.
9232 .TP
9233 \fBcaller\fP [\fIexpr\fP]
9234 Returns the context of any active subroutine call (a shell function or
9235 a script executed with the \fB.\fP or \fBsource\fP builtins).
9236 .IP
9237 Without \fIexpr\fP, \fBcaller\fP displays the line number and source
9238 filename of the current subroutine call.
9239 If a non-negative integer is supplied as \fIexpr\fP, \fBcaller\fP
9240 displays the line number, subroutine name, and source file corresponding
9241 to that position in the current execution call stack.
9242 This extra information may be used, for example, to print a stack trace.
9243 The current frame is frame 0.
9244 .IP
9245 The return value is 0 unless the shell is not executing a subroutine
9246 call or \fIexpr\fP does not correspond to a valid position in the
9247 call stack.
9248 .TP
9249 .PD 0
9250 \fBcd\fP [\fB\-L\fP] [\fB\-@\fP] [\fIdir\fP]
9251 .TP
9252 \fBcd\fP \fB\-P\fP [\fB\-e\fP] [\fB\-@\fP] [\fIdir\fP]
9253 .PD
9254 Change the current directory to \fIdir\fP.
9255 if \fIdir\fP is not supplied, the value of the
9256 .SM
9257 .B HOME
9258 shell variable is used as \fIdir\fP.
9259 The variable
9260 .SM
9261 .B CDPATH
9262 exists,
9263 and \fIdir\fP does not begin with a slash (/),
9264 \fBcd\fP uses it as a search path:
9265 the shell searches each directory name in
9266 .SM
9267 .B CDPATH
9268 for \fIdir\fP.
9269 Alternative directory names in
9270 .SM
9271 .B CDPATH
9272 are separated by a colon (:).
9273 A null directory name in
9274 .SM
9275 .B CDPATH
9276 is the same as the current directory, i.e.,
9277 .Q .\& .
9278 .IP
9279 The
9280 .B \-P
9281 option causes \fBcd\fP to use the physical directory structure
9282 by resolving symbolic links while traversing \fIdir\fP and
9283 before processing instances of
9284 .FN .\|.\&
9285 in \fIdir\fP (see also the
9286 .B \-P
9287 option to the
9288 .B set
9289 builtin command).
9290 .IP
9291 The
9292 .B \-L
9293 option forces \fBcd\fP to follow symbolic links by resolving the link
9294 after processing instances of
9295 .FN .\|.\&
9296 in \fIdir\fP.
9297 If
9298 .FN .\|.\&
9299 appears in \fIdir\fP, \fBcd\fP processes it by removing the
9300 immediately previous pathname component from \fIdir\fP, back to a slash
9301 or the beginning of \fIdir\fP,
9302 and verifying that the portion of \fIdir\fP it has processed to
9303 that point is still a valid directory name after removing the pathname
9304 component.
9305 If it is not a valid directory name, \fBcd\fP returns a non-zero status.
9306 If neither
9307 .B \-L
9308 nor
9309 .B \-P
9310 is supplied,
9311 .B cd
9312 behaves as if
9313 .B \-L
9314 had been supplied.
9315 .IP
9316 If the
9317 .B \-e
9318 option is supplied with
9319 .BR \-P ,
9320 and \fBcd\fP cannot successfully determine the current working directory
9321 after a successful directory change, it returns a non-zero status.
9322 .IP
9323 On systems that support it, the \fB\-@\fP option presents the extended
9324 attributes associated with a file as a directory.
9325 .IP
9326 An argument of
9327 .B \-
9328 is converted to
9329 .SM
9330 .B $OLDPWD
9331 before attempting the directory change.
9332 .IP
9333 If \fBcd\fP uses a non-empty directory name from
9334 .SM
9335 .BR CDPATH ,
9336 or if \fB\-\fP is the first argument, and the directory change is
9337 successful, \fBcd\fP writes the absolute pathname of the new
9338 working directory to the standard output.
9339 .IP
9340 If the directory change is successful, \fBcd\fP sets the value of the
9341 \fBPWD\fP environment variable to the new directory name, and sets the
9342 \fBOLDPWD\fP environment variable to the value of the current working
9343 directory before the change.
9344 .IP
9345 The return value is true if the directory was successfully changed;
9346 false otherwise.
9347 .TP
9348 \fBcommand\fP [\fB\-pVv\fP] \fIcommand\fP [\fIarg\fP .\|.\|.]
9349 The \fBcommand\fP builtin runs
9350 .I command
9351 with
9352 .I args
9353 suppressing the normal shell function lookup for \fIcommand\fP.
9354 Only builtin commands or commands found in the
9355 .SM
9356 .B PATH
9357 named \fIcommand\fP are executed.
9358 If the
9359 .B \-p
9360 option is supplied, the search for
9361 .I command
9362 is performed using a default value for
9363 .SM
9364 .B PATH
9365 that is guaranteed to find all of the standard utilities.
9366 .IP
9367 If either the
9368 .B \-V
9369 or
9370 .B \-v
9371 option is supplied, \fBcommand\fP prints a description of
9372 .IR command .
9373 The
9374 .B \-v
9375 option displays a single word indicating the command or filename
9376 used to invoke
9377 .IR command ;
9378 the
9379 .B \-V
9380 option produces a more verbose description.
9381 .IP
9382 If the
9383 .B \-V
9384 or
9385 .B \-v
9386 option is supplied, the exit status is zero if
9387 .I command
9388 was found, and non-zero if not.
9389 If neither option is supplied and an error occurred or
9390 .I command
9391 cannot be found, the exit status is 127.
9392 Otherwise, the exit status of the
9393 .B command
9394 builtin is the exit status of
9395 .IR command .
9396 .TP
9397 \fBcompgen\fP [\fB\-V\fP \fIvarname\fP] [\fIoption\fP] [\fIword\fP]
9398 Generate possible completion matches for \fIword\fP according to
9399 the \fIoption\fPs, which may be any option accepted by the
9400 .B complete
9401 builtin with the exceptions of
9402 .BR \-p ,
9403 .BR \-r ,
9404 .BR \-D ,
9405 .BR \-E ,
9406 and
9407 .BR \-I ,
9408 and write the matches to the standard output.
9409 .IP
9410 If the \fB\-V\fP option is supplied, \fBcompgen\fP stores the generated
9411 completions into the indexed array variable \fIvarname\fP instead of writing
9412 them to the standard output.
9413 .IP
9414 When using the \fB\-F\fP or \fB\-C\fP options, the various shell variables
9415 set by the programmable completion facilities, while available, will not
9416 have useful values.
9417 .IP
9418 The matches will be generated in the same way as if the programmable
9419 completion code had generated them directly from a completion specification
9420 with the same flags.
9421 If \fIword\fP is specified, only those completions matching \fIword\fP
9422 will be displayed or stored.
9423 .IP
9424 The return value is true unless an invalid option is supplied, or no
9425 matches were generated.
9426 .TP
9427 \fBcomplete\fP [\fB\-abcdefgjksuv\fP] [\fB\-o\fP \fIcomp-option\fP] [\fB\-DEI\fP] [\fB\-A\fP \fIaction\fP]
9428 .br
9429 [\fB\-G\fP \fIglobpat\fP] [\fB\-W\fP \fIwordlist\fP] [\fB\-F\fP \fIfunction\fP] [\fB\-C\fP \fIcommand\fP]
9430 .br
9431 [\fB\-X\fP \fIfilterpat\fP] [\fB\-P\fP \fIprefix\fP] \
9432 [\fB\-S\fP \fIsuffix\fP] \fIname\fP [\fIname\fP .\|.\|.]
9433 .PD 0
9434 .TP
9435 \fBcomplete\fP \fB\-pr\fP [\fB\-DEI\fP] [\fIname\fP .\|.\|.]
9436 .PD
9437 Specify how arguments to each \fIname\fP should be completed.
9438 .IP
9439 If the \fB\-p\fP option is supplied, or if no options or \fIname\fPs
9440 are supplied, print existing completion specifications
9441 in a way that allows them to be reused as input.
9442 The \fB\-r\fP option removes a completion specification for
9443 each \fIname\fP, or, if no \fIname\fPs are supplied, all
9444 completion specifications.
9445 .IP
9446 The \fB\-D\fP option indicates that other supplied options and actions should
9447 apply to the
9448 .Q default
9449 command completion; that is, completion attempted
9450 on a command for which no completion has previously been defined.
9451 The \fB\-E\fP option indicates that other supplied options and actions should
9452 apply to
9453 .Q empty
9454 command completion; that is, completion attempted on a
9455 blank line.
9456 The \fB\-I\fP option indicates that other supplied options and actions should
9457 apply to completion on the initial non-assignment word on the line, or after
9458 a command delimiter such as \fB;\fP or \fB|\fP, which is usually command
9459 name completion.
9460 If multiple options are supplied, the \fB\-D\fP option takes precedence
9461 over \fB\-E\fP, and both take precedence over \fB\-I\fP.
9462 If any of \fB\-D\fP, \fB\-E\fP, or \fB\-I\fP are supplied, any other
9463 \fIname\fP arguments are ignored; these completions only apply to the case
9464 specified by the option.
9465 .IP
9466 The process of applying these completion specifications when
9467 attempting word completion is described
9468 .ie \n(zZ=1 in \fIbash\fP(1).
9469 .el above under \fBProgrammable Completion\fP.
9470 .IP
9471 Other options, if specified, have the following meanings.
9472 The arguments to the \fB\-G\fP, \fB\-W\fP, and \fB\-X\fP options
9473 (and, if necessary, the \fB\-P\fP and \fB\-S\fP options)
9474 should be quoted to protect them from expansion before the
9475 .B complete
9476 builtin is invoked.
9477 .IP
9478 .RS
9479 .PD 0
9480 .TP 8
9481 \fB\-o\fP \fIcomp-option\fP
9482 The \fIcomp-option\fP controls several aspects of the compspec's behavior
9483 beyond the simple generation of completions.
9484 \fIcomp-option\fP may be one of:
9485 .RS
9486 .TP 8
9487 .B bashdefault
9488 Perform the rest of the default \fBbash\fP completions if the compspec
9489 generates no matches.
9490 .TP 8
9491 .B default
9492 Use \fBreadline\fP's default filename completion if the compspec generates
9493 no matches.
9494 .TP 8
9495 .B dirnames
9496 Perform directory name completion if the compspec generates no matches.
9497 .TP 8
9498 .B filenames
9499 Tell \fBreadline\fP that the compspec generates filenames, so it can perform
9500 any filename\-specific processing (such as adding a slash to directory names,
9501 quoting special characters, or suppressing trailing spaces).
9502 This is intended to be used with shell functions.
9503 .TP 8
9504 .B fullquote
9505 Tell \fBreadline\fP to quote all the completed words even if they are not
9506 filenames.
9507 .TP 8
9508 .B noquote
9509 Tell \fBreadline\fP not to quote the completed words if they are filenames
9510 (quoting filenames is the default).
9511 .TP 8
9512 .B nosort
9513 Tell \fBreadline\fP not to sort the list of possible completions
9514 alphabetically.
9515 .TP 8
9516 .B nospace
9517 Tell \fBreadline\fP not to append a space (the default) to words completed
9518 at the end of the line.
9519 .TP 8
9520 .B plusdirs
9521 After generating any matches defined by the compspec,
9522 attempt directory name completion and add any
9523 matches to the results of the other actions.
9524 .RE
9525 .TP 8
9526 \fB\-A\fP \fIaction\fP
9527 The \fIaction\fP may be one of the following to generate a list of possible
9528 completions:
9529 .RS
9530 .TP 8
9531 .B alias
9532 Alias names.
9533 May also be specified as \fB\-a\fP.
9534 .TP 8
9535 .B arrayvar
9536 Array variable names.
9537 .TP 8
9538 .B binding
9539 \fBReadline\fP key binding names.
9540 .TP 8
9541 .B builtin
9542 Names of shell builtin commands.
9543 May also be specified as \fB\-b\fP.
9544 .TP 8
9545 .B command
9546 Command names.
9547 May also be specified as \fB\-c\fP.
9548 .TP 8
9549 .B directory
9550 Directory names.
9551 May also be specified as \fB\-d\fP.
9552 .TP 8
9553 .B disabled
9554 Names of disabled shell builtins.
9555 .TP 8
9556 .B enabled
9557 Names of enabled shell builtins.
9558 .TP 8
9559 .B export
9560 Names of exported shell variables.
9561 May also be specified as \fB\-e\fP.
9562 .TP 8
9563 .B file
9564 File and directory names, similar to \fBreadline\fP's filename completion.
9565 May also be specified as \fB\-f\fP.
9566 .TP 8
9567 .B function
9568 Names of shell functions.
9569 .TP 8
9570 .B group
9571 Group names.
9572 May also be specified as \fB\-g\fP.
9573 .TP 8
9574 .B helptopic
9575 Help topics as accepted by the \fBhelp\fP builtin.
9576 .TP 8
9577 .B hostname
9578 Hostnames, as taken from the file specified by the
9579 .SM
9580 .B HOSTFILE
9581 shell variable.
9582 .TP 8
9583 .B job
9584 Job names, if job control is active.
9585 May also be specified as \fB\-j\fP.
9586 .TP 8
9587 .B keyword
9588 Shell reserved words.
9589 May also be specified as \fB\-k\fP.
9590 .TP 8
9591 .B running
9592 Names of running jobs, if job control is active.
9593 .TP 8
9594 .B service
9595 Service names.
9596 May also be specified as \fB\-s\fP.
9597 .TP 8
9598 .B setopt
9599 Valid arguments for the \fB\-o\fP option to the \fBset\fP builtin.
9600 .TP 8
9601 .B shopt
9602 Shell option names as accepted by the \fBshopt\fP builtin.
9603 .TP 8
9604 .B signal
9605 Signal names.
9606 .TP 8
9607 .B stopped
9608 Names of stopped jobs, if job control is active.
9609 .TP 8
9610 .B user
9611 User names.
9612 May also be specified as \fB\-u\fP.
9613 .TP 8
9614 .B variable
9615 Names of all shell variables.
9616 May also be specified as \fB\-v\fP.
9617 .RE
9618 .TP 8
9619 \fB\-C\fP \fIcommand\fP
9620 \fIcommand\fP is executed in a subshell environment, and its output is
9621 used as the possible completions.
9622 Arguments are passed as with the \fB\-F\fP option.
9623 .TP 8
9624 \fB\-F\fP \fIfunction\fP
9625 The shell function \fIfunction\fP is executed in the current shell
9626 environment.
9627 When the function is executed,
9628 the first argument (\fB$1\fP) is the name of the command whose arguments are
9629 being completed,
9630 the second argument (\fB$2\fP) is the word being completed, and
9631 the third argument (\fB$3\fP) is the word preceding the word being
9632 completed on the current command line.
9633 When \fIfunction\fP finishes,
9634 programmable completion retrieves
9635 the possible completions from the value of the
9636 .SM
9637 .B COMPREPLY
9638 array variable.
9639 .TP 8
9640 \fB\-G\fP \fIglobpat\fP
9641 Expand the pathname expansion pattern \fIglobpat\fP to generate
9642 the possible completions.
9643 .TP 8
9644 \fB\-P\fP \fIprefix\fP
9645 Add \fIprefix\fP to the beginning of each possible completion
9646 after all other options have been applied.
9647 .TP 8
9648 \fB\-S\fP \fIsuffix\fP
9649 Append \fIsuffix\fP to each possible completion
9650 after all other options have been applied.
9651 .TP 8
9652 \fB\-W\fP \fIwordlist\fP
9653 Split the \fIwordlist\fP using the characters in the
9654 .SM
9655 .B IFS
9656 special variable as delimiters, and expand each resulting word.
9657 Shell quoting is honored within \fIwordlist\fP,
9658 in order to provide a
9659 mechanism for the words to contain shell metacharacters or characters
9660 in the value of
9661 .SM
9662 .BR IFS .
9663 The possible completions are the members of the resultant list which
9664 match a prefix of the word being completed.
9665 .TP 8
9666 \fB\-X\fP \fIfilterpat\fP
9667 \fIfilterpat\fP is a pattern as used for pathname expansion.
9668 It is applied to the list of possible completions generated by the
9669 preceding options and arguments, and each completion matching
9670 \fIfilterpat\fP is removed from the list.
9671 A leading \fB!\fP in \fIfilterpat\fP negates the pattern; in this
9672 case, any completion not matching \fIfilterpat\fP is removed.
9673 .PD
9674 .PP
9675 The return value is true unless an invalid option is supplied, an option
9676 other than
9677 .BR \-p ,
9678 .BR \-r ,
9679 .BR \-D ,
9680 .BR \-E ,
9681 or
9682 .B \-I
9683 is supplied without a \fIname\fP
9684 argument, an attempt is made to remove a completion specification for
9685 a \fIname\fP for which no specification exists, or
9686 an error occurs adding a completion specification.
9687 .RE
9688 .TP
9689 \fBcompopt\fP [\fB\-o\fP \fIoption\fP] [\fB\-DEI\fP] [\fB+o\fP \fIoption\fP] [\fIname\fP]
9690 Modify completion options for each \fIname\fP according to the
9691 \fIoption\fPs, or for the
9692 currently-executing completion if no \fIname\fPs are supplied.
9693 If no \fIoption\fPs are supplied, display the completion options for each
9694 \fIname\fP or the current completion.
9695 The possible values of \fIoption\fP are those valid for the \fBcomplete\fP
9696 builtin described above.
9697 .IP
9698 The \fB\-D\fP option indicates that other supplied options should
9699 apply to the
9700 .Q default
9701 command completion;
9702 the \fB\-E\fP option indicates that other supplied options should
9703 apply to
9704 .Q empty
9705 command completion; and
9706 the \fB\-I\fP option indicates that other supplied options should
9707 apply to completion on the initial word on the line.
9708 These are determined in the same way as the \fBcomplete\fP builtin.
9709 .IP
9710 If multiple options are supplied, the \fB\-D\fP option takes precedence
9711 over \fB\-E\fP, and both take precedence over \fB\-I\fP.
9712 .IP
9713 The return value is true unless an invalid option is supplied, an attempt
9714 is made to modify the options for a \fIname\fP for which no completion
9715 specification exists, or an output error occurs.
9716 .TP
9717 \fBcontinue\fP [\fIn\fP]
9718 \fBcontinue\fP resumes the next iteration of the enclosing
9719 .BR for ,
9720 .BR while ,
9721 .BR until ,
9722 or
9723 .B select
9724 loop.
9725 If
9726 .I n
9727 is specified, \fBbash\fP resumes the \fIn\fPth enclosing loop.
9728 .I n
9729 must be \(>= 1.
9730 If
9731 .I n
9732 is greater than the number of enclosing loops, the shell resumes
9733 the last enclosing loop
9734 (the
9735 .Q top-level
9736 loop).
9737 The return value is 0 unless \fIn\fP is not greater than or equal to 1.
9738 .TP
9739 \fBdeclare\fP [\fB\-aAfFgiIlnrtux\fP] [\fB\-p\fP] \
9740 [\fIname\fP[=\fIvalue\fP] .\|.\|.]
9741 .PD 0
9742 .TP
9743 \fBtypeset\fP [\fB\-aAfFgiIlnrtux\fP] [\fB\-p\fP] \
9744 [\fIname\fP[=\fIvalue\fP] .\|.\|.]
9745 .PD
9746 Declare variables and/or give them attributes.
9747 If no \fIname\fPs are given then display the values of variables
9748 or functions.
9749 The
9750 .B \-p
9751 option will display the attributes and values of each
9752 .IR name .
9753 When
9754 .B \-p
9755 is used with \fIname\fP arguments, additional options,
9756 other than \fB\-f\fP and \fB\-F\fP, are ignored.
9757 .IP
9758 When
9759 .B \-p
9760 is supplied without \fIname\fP arguments,
9761 \fBdeclare\fP will display the attributes and values
9762 of all variables having the attributes specified by the additional options.
9763 If no other options are supplied with \fB\-p\fP, \fBdeclare\fP will
9764 display the attributes and values of all shell variables.
9765 The \fB\-f\fP option restricts the display to shell functions.
9766 .IP
9767 The
9768 .B \-F
9769 option inhibits the display of function definitions; only the
9770 function name and attributes are printed.
9771 If the \fBextdebug\fP shell option is enabled using \fBshopt\fP,
9772 the source file name and line number where each \fIname\fP
9773 is defined are displayed as well.
9774 The
9775 .B \-F
9776 option implies
9777 .BR \-f .
9778 .IP
9779 The
9780 .B \-g
9781 option forces variables to be created or modified at the global scope,
9782 even when \fBdeclare\fP is executed in a shell function.
9783 It is ignored when \fBdeclare\fP is not executed in a shell function.
9784 .IP
9785 The
9786 .B \-I
9787 option causes local variables to inherit the attributes
9788 (except the \fInameref\fP attribute)
9789 and value of any existing variable with the same
9790 \fIname\fP at a surrounding scope.
9791 If there is no existing variable, the local variable is initially unset.
9792 .IP
9793 The following options can
9794 be used to restrict output to variables with the specified attribute or
9795 to give variables attributes:
9796 .RS
9797 .PD 0
9798 .TP
9799 .B \-a
9800 Each \fIname\fP is an indexed array variable (see
9801 .B Arrays
9802 .ie \n(zZ=1 in \fIbash\fP(1)).
9803 .el above).
9804 .TP
9805 .B \-A
9806 Each \fIname\fP is an associative array variable (see
9807 .B Arrays
9808 .ie \n(zZ=1 in \fIbash\fP(1)).
9809 .el above).
9810 .TP
9811 .B \-f
9812 Each \fIname\fP refers to a shell function.
9813 .TP
9814 .B \-i
9815 The variable is treated as an integer;
9816 arithmetic evaluation (see
9817 .SM
9818 .B "ARITHMETIC EVALUATION"
9819 .ie \n(zZ=1 in \fIbash\fP(1))
9820 .el above)
9821 is performed when the variable is assigned a value.
9822 .TP
9823 .B \-l
9824 When the variable is assigned a value, all upper-case characters are
9825 converted to lower-case.
9826 The upper-case attribute is disabled.
9827 .TP
9828 .B \-n
9829 Give each \fIname\fP the \fInameref\fP attribute, making
9830 it a name reference to another variable.
9831 That other variable is defined by the value of \fIname\fP.
9832 All references, assignments, and attribute modifications
9833 to \fIname\fP, except those using or changing the
9834 \fB\-n\fP attribute itself, are performed on the variable referenced by
9835 \fIname\fP's value.
9836 The nameref attribute cannot be applied to array variables.
9837 .TP
9838 .B \-r
9839 Make \fIname\fPs readonly.
9840 These names cannot then be assigned values
9841 by subsequent assignment statements or unset.
9842 .TP
9843 .B \-t
9844 Give each \fIname\fP the \fItrace\fP attribute.
9845 Traced functions inherit the \fBDEBUG\fP and \fBRETURN\fP traps from
9846 the calling shell.
9847 The trace attribute has no special meaning for variables.
9848 .TP
9849 .B \-u
9850 When the variable is assigned a value, all lower-case characters are
9851 converted to upper-case.
9852 The lower-case attribute is disabled.
9853 .TP
9854 .B \-x
9855 Mark each \fIname\fP for export to subsequent commands via the environment.
9856 .PD
9857 .PP
9858 Using
9859 .Q +
9860 instead of
9861 .Q \-
9862 turns off the specified
9863 attribute instead, with the exceptions that \fB+a\fP and \fB+A\fP
9864 may not be used to destroy array variables and \fB+r\fP will not
9865 remove the readonly attribute.
9866 .PP
9867 When used in a function,
9868 .B declare
9869 and
9870 .B typeset
9871 make each
9872 \fIname\fP local, as with the
9873 .B local
9874 command,
9875 unless the \fB\-g\fP option is supplied.
9876 If a variable name is followed by =\fIvalue\fP, the value of
9877 the variable is set to \fIvalue\fP.
9878 When using \fB\-a\fP or \fB\-A\fP and the compound assignment syntax to
9879 create array variables, additional attributes do not take effect until
9880 subsequent assignments.
9881 .PP
9882 The return value is 0 unless an invalid option is encountered,
9883 an attempt is made to define a function using
9884 .Q "\-f foo=bar" ,
9885 an attempt is made to assign a value to a readonly variable,
9886 an attempt is made to assign a value to an array variable without
9887 using the compound assignment syntax (see
9888 .B Arrays
9889 .ie \n(zZ=1 in \fIbash\fP(1)),
9890 .el above),
9891 one of the \fInames\fP is not a valid shell variable name,
9892 an attempt is made to turn off readonly status for a readonly variable,
9893 an attempt is made to turn off array status for an array variable,
9894 or an attempt is made to display a non-existent function with \fB\-f\fP.
9895 .RE
9896 .TP
9897 .B dirs [\fB\-clpv\fP] [+\fIn\fP] [\-\fIn\fP]
9898 Without options, display the list of currently remembered directories.
9899 The default display is on a single line with directory names separated
9900 by spaces.
9901 Directories are added to the list with the
9902 .B pushd
9903 command; the
9904 .B popd
9905 command removes entries from the list.
9906 The current directory is always the first directory in the stack.
9907 .IP
9908 Options, if supplied, have the following meanings:
9909 .RS
9910 .PD 0
9911 .TP
9912 .B \-c
9913 Clears the directory stack by deleting all of the entries.
9914 .TP
9915 .B \-l
9916 Produces a listing using full pathnames;
9917 the default listing format uses a tilde to denote the home directory.
9918 .TP
9919 .B \-p
9920 Print the directory stack with one entry per line.
9921 .TP
9922 .B \-v
9923 Print the directory stack with one entry per line,
9924 prefixing each entry with its index in the stack.
9925 .TP
9926 \fB+\fP\fIn\fP
9927 Displays the \fIn\fPth entry counting from the left of the list
9928 shown by
9929 .B dirs
9930 when invoked without options, starting with zero.
9931 .TP
9932 \fB\-\fP\fIn\fP
9933 Displays the \fIn\fPth entry counting from the right of the list
9934 shown by
9935 .B dirs
9936 when invoked without options, starting with zero.
9937 .PD
9938 .PP
9939 The return value is 0 unless an
9940 invalid option is supplied or \fIn\fP indexes beyond the end
9941 of the directory stack.
9942 .RE
9943 .TP
9944 \fBdisown\fP [\fB\-ar\fP] [\fB\-h\fP] [\fIid\fP .\|.\|.]
9945 Without options, remove each
9946 .I id
9947 from the table of active jobs.
9948 Each \fIid\fP may be a job specification \fIjobspec\fP
9949 or a process ID \fIpid\fP;
9950 if \fIid\fP is a \fIpid\fP,
9951 \fBdisown\fP uses the job containing \fIpid\fP as \fIjobspec\fP.
9952 .IP
9953 If the \fB\-h\fP option is supplied,
9954 \fBdisown\fP does not remove the jobs corresponding to each
9955 .I id
9956 from the jobs table,
9957 but rather marks them so the shell does not send
9958 .SM
9959 .B SIGHUP
9960 to the job if the shell receives a
9961 .SM
9962 .BR SIGHUP .
9963 .IP
9964 If no
9965 .I id
9966 is supplied, the
9967 .B \-a
9968 option means to remove or mark all jobs; the
9969 .B \-r
9970 option without an
9971 .I id
9972 argument removes or marks running jobs.
9973 If no
9974 .I id
9975 is supplied, and neither the \fB\-a\fP nor the \fB\-r\fP option
9976 is supplied, \fBdisown\fP removes or marks the current job.
9977 .IP
9978 The return value is 0 unless an
9979 .I id
9980 does not specify a valid job.
9981 .TP
9982 \fBecho\fP [\fB\-neE\fP] [\fIarg\fP .\|.\|.]
9983 Output the \fIarg\fPs, separated by spaces, followed by a newline.
9984 The return status is 0 unless a write error occurs.
9985 If \fB\-n\fP is specified, the trailing newline is not printed.
9986 .IP
9987 If the \fB\-e\fP option is given, \fBecho\fP interprets
9988 the following backslash-escaped characters.
9989 The
9990 .B \-E
9991 option disables interpretation of these escape characters,
9992 even on systems where they are interpreted by default.
9993 The \fBxpg_echo\fP shell option determines
9994 whether or not \fBecho\fP interprets any options
9995 and expands these escape characters.
9996 .B echo
9997 does not interpret \fB\-\-\fP to mean the end of options.
9998 .IP
9999 .B echo
10000 interprets the following escape sequences:
10001 .RS
10002 .PD 0
10003 .TP
10004 .B \ea
10005 alert (bell)
10006 .TP
10007 .B \eb
10008 backspace
10009 .TP
10010 .B \ec
10011 suppress further output
10012 .TP
10013 .B \ee
10014 .TP
10015 .B \eE
10016 an escape character
10017 .TP
10018 .B \ef
10019 form feed
10020 .TP
10021 .B \en
10022 new line
10023 .TP
10024 .B \er
10025 carriage return
10026 .TP
10027 .B \et
10028 horizontal tab
10029 .TP
10030 .B \ev
10031 vertical tab
10032 .TP
10033 .B \e\e
10034 backslash
10035 .TP
10036 .B \e0\fInnn\fP
10037 The eight-bit character whose value is the octal value \fInnn\fP
10038 (zero to three octal digits).
10039 .TP
10040 .B \ex\fIHH\fP
10041 The eight-bit character whose value is the hexadecimal value \fIHH\fP
10042 (one or two hex digits).
10043 .TP
10044 .B \eu\fIHHHH\fP
10045 The Unicode (ISO/IEC 10646) character whose value is the hexadecimal value
10046 \fIHHHH\fP (one to four hex digits).
10047 .TP
10048 .B \eU\fIHHHHHHHH\fP
10049 The Unicode (ISO/IEC 10646) character whose value is the hexadecimal value
10050 \fIHHHHHHHH\fP (one to eight hex digits).
10051 .PD
10052 .PP
10053 \fBecho\fP writes any unrecognized backslash-escaped characters unchanged.
10054 .RE
10055 .TP
10056 \fBenable\fP [\fB\-a\fP] [\fB\-dnps\fP] [\fB\-f\fP \fIfilename\fP] \
10057 [\fIname\fP .\|.\|.]
10058 Enable and disable builtin shell commands.
10059 Disabling a builtin allows an executable file which has the same name
10060 as a shell builtin to be executed without specifying a full pathname,
10061 even though the shell normally searches for builtins before files.
10062 .IP
10063 If \fB\-n\fP is supplied, each \fIname\fP is disabled; otherwise,
10064 \fIname\fPs are enabled.
10065 For example, to use the
10066 .B test
10067 binary found using
10068 .SM
10069 .B PATH
10070 instead of the shell builtin version, run
10071 .QN "enable \-n test" .
10072 .IP
10073 If no \fIname\fP arguments are supplied, or if the
10074 .B \-p
10075 option is supplied, print a list of shell builtins.
10076 With no other option arguments, the list consists of all enabled
10077 shell builtins.
10078 If \fB\-n\fP is supplied, print only disabled builtins.
10079 If \fB\-a\fP is supplied, the list printed includes all builtins, with an
10080 indication of whether or not each is enabled.
10081 The \fB\-s\fP option means to restrict the output to the
10082 .SM POSIX
10083 \fIspecial\fP builtins.
10084 .IP
10085 The
10086 .B \-f
10087 option means to load the new builtin command
10088 .I name
10089 from shared object
10090 .IR filename ,
10091 on systems that support dynamic loading.
10092 If \fIfilename\fP does not contain a slash,
10093 \fBBash\fP will use the value of the \fBBASH_LOADABLES_PATH\fP variable as a
10094 colon-separated list of directories in which to search for \fIfilename\fP.
10095 The default for \fBBASH_LOADABLES_PATH\fP is system-dependent,
10096 and may include
10097 .Q .\&
10098 to force a search of the current directory.
10099 The
10100 .B \-d
10101 option will delete a builtin previously loaded with \fB\-f\fP.
10102 If \fI\-s\fP is used with \fI\-f\fP, the new builtin becomes a
10103 .SM POSIX
10104 special builtin.
10105 .IP
10106 If no options are supplied and a \fIname\fP is not a shell builtin,
10107 \fBenable\fP will attempt to load \fIname\fP from a shared
10108 object named \fIname\fP, as if the command were
10109 .QN "enable \-f \fIname name\fP" .
10110 .IP
10111 The return value is 0 unless a
10112 .I name
10113 is not a shell builtin or there is an error loading a new builtin
10114 from a shared object.
10115 .TP
10116 \fBeval\fP [\fIarg\fP .\|.\|.]
10117 Concatenate the \fIarg\fPs together into a single command, separating
10118 them with spaces.
10119 \fBBash\fP then reads and execute this command, and returns its exit status
10120 as the return status of \fBeval\fP.
10121 If there are no
10122 .IR args ,
10123 or only null arguments,
10124 .B eval
10125 returns 0.
10126 .TP
10127 \fBexec\fP [\fB\-cl\fP] [\fB\-a\fP \fIname\fP] [\fIcommand\fP [\fIarguments\fP]]
10128 If
10129 .I command
10130 is specified, it replaces the shell without creating a new process.
10131 \fIcommand\fP cannot be a shell builtin or function.
10132 The
10133 .I arguments
10134 become the arguments to \fIcommand\fP.
10135 If the
10136 .B \-l
10137 option is supplied,
10138 the shell places a dash at the beginning of the zeroth argument passed to
10139 .IR command .
10140 This is what
10141 .IR login (1)
10142 does. The
10143 .B \-c
10144 option causes
10145 .I command
10146 to be executed with an empty environment.
10147 If
10148 .B \-a
10149 is supplied, the shell passes
10150 .I name
10151 as the zeroth argument to the executed command.
10152 .IP
10153 If
10154 .I command
10155 cannot be executed for some reason, a non-interactive shell exits,
10156 unless the
10157 .B execfail
10158 shell option is enabled.
10159 In that case, it returns a non-zero status.
10160 An interactive shell returns a non-zero status if the file cannot be executed.
10161 A subshell exits unconditionally if \fBexec\fP fails.
10162 .IP
10163 If
10164 .I command
10165 is not specified, any redirections take effect in the current shell,
10166 and the return status is 0. If there is a redirection error, the
10167 return status is 1.
10168 .TP
10169 \fBexit\fP [\fIn\fP]
10170 Cause the shell to exit with a status of \fIn\fP.
10171 If
10172 .I n
10173 is omitted, the exit status is that of the last command executed.
10174 Any trap on
10175 .SM
10176 .B EXIT
10177 is executed before the shell terminates.
10178 .TP
10179 \fBexport\fP [\fB\-fn\fP\^] [\fIname\fP[=\fIvalue\fP]] .\|.\|.
10180 .PD 0
10181 .TP
10182 .B export \-p [\fB\-f\fP\^]
10183 .PD
10184 The supplied
10185 .I names
10186 are marked for automatic export to the environment of
10187 subsequently executed commands.
10188 If the
10189 .B \-f
10190 option is given, the
10191 .I names
10192 refer to functions.
10193 .IP
10194 The
10195 .B \-n
10196 option unexports, or removes the export attribute, from each \fIname\fP.
10197 If no
10198 .I names
10199 are given, or if only the
10200 .B \-p
10201 option is supplied,
10202 \fBexport\fP displays a list of names of all exported
10203 variables on the standard output.
10204 Using \fB\-p\fP and \fB\-f\fP together displays exported functions.
10205 The \fB\-p\fP option displays output in a form that may be reused as input.
10206 .IP
10207 \fBexport\fP allows the value of a variable to be set when it is exported
10208 or unexported by following the variable name with =\fIvalue\fP.
10209 This sets the value of the variable to \fIvalue\fP while modifying the
10210 export attribute.
10211 .B export
10212 returns an exit status of 0 unless an invalid option is
10213 encountered,
10214 one of the \fInames\fP is not a valid shell variable name, or
10215 .B \-f
10216 is supplied with a
10217 .I name
10218 that is not a function.
10219 .TP
10220 \fBfalse\fP
10221 Does nothing; returns a non-zero status.
10222 .TP
10223 \fBfc\fP [\fB\-e\fP \fIename\fP] [\fB\-lnr\fP] [\fIfirst\fP] [\fIlast\fP]
10224 .PD 0
10225 .TP
10226 \fBfc\fP \fB\-s\fP [\fIpat\fP=\fIrep\fP] [\fIcmd\fP]
10227 .PD
10228 The first form selects a range of commands from
10229 .I first
10230 to
10231 .I last
10232 from the history list and displays or edits and re-executes them.
10233 .I First
10234 and
10235 .I last
10236 may be specified as a string (to locate the last command beginning
10237 with that string) or as a number (an index into the history list,
10238 where a negative number is used as an offset from the current
10239 command number).
10240 .IP
10241 When listing, a \fIfirst\fP or \fIlast\fP of 0 is equivalent to \-1
10242 and \-0 is equivalent to the current command
10243 (usually the \fBfc\fP command);
10244 otherwise 0 is equivalent to \-1 and \-0 is invalid.
10245 If
10246 .I last
10247 is not specified, it is set to
10248 the current command for listing (so that
10249 .QN "fc \-l \-10"
10250 prints the last 10 commands) and to
10251 .I first
10252 otherwise.
10253 If
10254 .I first
10255 is not specified, it is set to the previous
10256 command for editing and \-16 for listing.
10257 .IP
10258 If the
10259 .B \-l
10260 option is supplied, the commands are listed on the standard output.
10261 The
10262 .B \-n
10263 option suppresses
10264 the command numbers when listing.
10265 The
10266 .B \-r
10267 option reverses the order of
10268 the commands.
10269 .IP
10270 Otherwise, \fBfc\fP invokes the editor named by
10271 .I ename
10272 on a file containing those commands.
10273 If
10274 .I ename
10275 is not supplied, \fBfc\fP uses the value of the
10276 .SM
10277 .B FCEDIT
10278 variable, and
10279 the value of
10280 .SM
10281 .B EDITOR
10282 if
10283 .SM
10284 .B FCEDIT
10285 is not set.
10286 If neither variable is set, \fBfc\fP uses
10287 .FN vi.
10288 When editing is complete, \fBfc\fP reads the file containing
10289 the edited commands and echoes and executes them.
10290 .IP
10291 In the second form, \fBfc\fP re-executes \fIcommand\fP
10292 after replacing each instance of \fIpat\fP with \fIrep\fP.
10293 \fICommand\fP is interpreted the same as \fIfirst\fP above.
10294 .IP
10295 A useful alias to use with \fBfc\fP is
10296 .Q "r=\*"fc \-s\*"" ,
10297 so that typing
10298 .Q "r cc"
10299 runs the last command beginning with
10300 .Q cc
10301 and typing
10302 .Q r
10303 re-executes the last command.
10304 .IP
10305 If the first form is used, the return value is zero unless an invalid
10306 option is encountered or
10307 .I first
10308 or
10309 .I last
10310 specify history lines out of range.
10311 When editing and re-executing a file of commands,
10312 the return value is the value of the last command executed
10313 or failure if an error occurs with the temporary file.
10314 If the second form is used, the return status
10315 is that of the re-executed command, unless
10316 .I cmd
10317 does not specify a valid history entry, in which case
10318 .B fc
10319 returns a non-zero status.
10320 .TP
10321 \fBfg\fP [\fIjobspec\fP]
10322 Resume
10323 .I jobspec
10324 in the foreground, and make it the current job.
10325 If
10326 .I jobspec
10327 is not present, \fBfg\fP uses the shell's notion of the \fIcurrent job\fP.
10328 The return value is that of the command placed into the foreground,
10329 or failure if run when job control is disabled or, when run with
10330 job control enabled, if
10331 .I jobspec
10332 does not specify a valid job or
10333 .I jobspec
10334 specifies a job that was started without job control.
10335 .TP
10336 \fBgetopts\fP \fIoptstring\fP \fIname\fP [\fIarg\fP .\|.\|.]
10337 .B getopts
10338 is used by shell scripts and functions to parse positional parameters
10339 and obtain options and their arguments.
10340 .I optstring
10341 contains the option characters to be recognized; if a character
10342 is followed by a colon, the option is expected to have an
10343 argument, which should be separated from it by white space.
10344 The colon and question mark characters may not be used as
10345 option characters.
10346 .IP
10347 Each time it is invoked,
10348 .B getopts
10349 places the next option in the shell variable
10350 .IR name ,
10351 initializing
10352 .I name
10353 if it does not exist,
10354 and the index of the next argument to be processed into the
10355 variable
10356 .SM
10357 .BR OPTIND .
10358 .SM
10359 .B OPTIND
10360 is initialized to 1 each time the shell or a shell script
10361 is invoked.
10362 When an option requires an argument,
10363 .B getopts
10364 places that argument into the variable
10365 .SM
10366 .BR OPTARG .
10367 .IP
10368 The shell does not reset
10369 .SM
10370 .B OPTIND
10371 automatically; it must be manually reset between multiple
10372 calls to
10373 .B getopts
10374 within the same shell invocation to use a new set of parameters.
10375 .IP
10376 When it reaches the end of options, \fBgetopts\fP exits with a
10377 return value greater than zero.
10378 .SM
10379 .B OPTIND
10380 is set to the index of the first non-option argument,
10381 and \fIname\fP is set to ?.
10382 .IP
10383 .B getopts
10384 normally parses the positional parameters, but if more arguments are
10385 supplied as
10386 .I arg
10387 values,
10388 .B getopts
10389 parses those instead.
10390 .IP
10391 .B getopts
10392 can report errors in two ways.
10393 If the first character of
10394 .I optstring
10395 is a colon, \fBgetopts\fP uses
10396 .I silent
10397 error reporting.
10398 In normal operation, \fBgetopts\fP prints diagnostic messages
10399 when it encounters invalid options or missing option arguments.
10400 If the variable
10401 .SM
10402 .B OPTERR
10403 is set to 0,
10404 .B getopts
10405 does not display any error messages,
10406 even if the first character of
10407 .I optstring
10408 is not a colon.
10409 .IP
10410 If
10411 .B getopts
10412 detects an invalid option, it places ? into
10413 .I name
10414 and, if not silent,
10415 prints an error message and unsets
10416 .SM
10417 .BR OPTARG .
10418 If
10419 .B getopts
10420 is silent, it assigns the option character found to
10421 .SM
10422 .B OPTARG
10423 and does not print a diagnostic message.
10424 .IP
10425 If a required argument is not found, and
10426 .B getopts
10427 is not silent, it sets the value of \fIname\fP to
10428 a question mark (\^\fB?\fP\^), unsets
10429 .SM
10430 .BR OPTARG ,
10431 and prints a diagnostic message.
10432 If
10433 .B getopts
10434 is silent, it sets the value of \fIname\fP to a colon (\^\fB:\fP\^)
10435 and sets
10436 .SM
10437 .B OPTARG
10438 to the option character found.
10439 .IP
10440 .B getopts
10441 returns true if an option, specified or unspecified, is found.
10442 It returns false if the end of options is encountered or an
10443 error occurs.
10444 .TP
10445 \fBhash\fP [\fB\-lr\fP] [\fB\-p\fP \fIfilename\fP] [\fB\-dt\fP] [\fIname\fP]
10446 Each time \fBhash\fP is invoked, it remembers
10447 the full pathname of the command
10448 .I name
10449 as determined by searching
10450 the directories in
10451 .BR $PATH .
10452 Any previously-remembered pathname associated with \fIname\fP is discarded.
10453 If the
10454 .B \-p
10455 option is supplied, \fBhash\fP uses
10456 .I filename
10457 as the full pathname of the command.
10458 .IP
10459 The
10460 .B \-r
10461 option causes the shell to forget all
10462 remembered locations.
10463 Assigning to the \fBPATH\fP variable also clears all hashed filenames.
10464 The
10465 .B \-d
10466 option causes the shell to forget the remembered location of each \fIname\fP.
10467 .IP
10468 If the
10469 .B \-t
10470 option is supplied, \fBhash\fP prints the full pathname corresponding to
10471 each \fIname\fP.
10472 If multiple \fIname\fP arguments are supplied with \fB\-t\fP,
10473 \fBhash\fP prints the \fIname\fP before the corresponding hashed
10474 full pathname.
10475 The
10476 .B \-l
10477 option displays output in a format that may be reused as input.
10478 .IP
10479 If no arguments are given, or if only \fB\-l\fP is supplied,
10480 \fBhash\fP prints information about remembered commands.
10481 The \fB\-t\fP, \fB\-d\fP, and \fB\-p\fP options (the options that
10482 act on the \fIname\fP arguments) are mutually exclusive.
10483 Only one will be active.
10484 If more than one is supplied, \fB\-t\fP has higher priority than
10485 \fB\-p\fP, and both have higher priority than \fB\-d\fP.
10486 .IP
10487 The return status is zero unless a
10488 .I name
10489 is not found or an invalid option is supplied.
10490 .TP
10491 \fBhelp\fP [\fB\-dms\fP] [\fIpattern\fP]
10492 Display helpful information about builtin commands.
10493 If
10494 .I pattern
10495 is specified,
10496 .B help
10497 gives detailed help on all commands matching
10498 .I pattern
10499 as described below;
10500 otherwise it displays a list of
10501 all the builtins and shell compound commands.
10502 .IP
10503 Options, if supplied, have the follow meanings:
10504 .RS
10505 .TP
10506 .PD 0
10507 .B \-d
10508 Display a short description of each \fIpattern\fP
10509 .TP
10510 .B \-m
10511 Display the description of each \fIpattern\fP in a manpage-like format
10512 .TP
10513 .B \-s
10514 Display only a short usage synopsis for each \fIpattern\fP
10515 .PD
10516 .RE
10517 .IP
10518 If \fIpattern\fP contains pattern matching characters
10519 (see
10520 .SM
10521 .B "Pattern Matching"
10522 above)
10523 it's treated as a shell pattern and
10524 \fBhelp\fP prints the description of each
10525 help topic matching \fIpattern\fP.
10526 .IP
10527 If not, and \fIpattern\fP exactly matches the name of a help topic,
10528 \fBhelp\fP prints the description
10529 associated with that topic.
10530 Otherwise, \fBhelp\fP performs prefix matching and
10531 prints the descriptions of all matching help topics.
10532 .IP
10533 The return status is 0 unless no command matches
10534 .IR pattern .
10535 .TP
10536 \fBhistory [\fIn\fP]
10537 .PD 0
10538 .TP
10539 \fBhistory\fP \fB\-c\fP
10540 .TP
10541 \fBhistory \-d\fP \fIoffset\fP
10542 .TP
10543 \fBhistory \-d\fP \fIstart\fP-\fIend\fP
10544 .TP
10545 \fBhistory\fP \fB\-anrw\fP [\fIfilename\fP]
10546 .TP
10547 \fBhistory\fP \fB\-p\fP \fIarg\fP [\fIarg\fP .\|.\|.]
10548 .TP
10549 \fBhistory\fP \fB\-s\fP \fIarg\fP [\fIarg\fP .\|.\|.]
10550 .PD
10551 With no options, display the command history list with numbers.
10552 Entries prefixed with a
10553 .B *
10554 have been modified.
10555 An argument of
10556 .I n
10557 lists only the last
10558 .I n
10559 entries.
10560 If the shell variable
10561 .SM
10562 .B HISTTIMEFORMAT
10563 is set and not null,
10564 it is used as a format string for
10565 .IR strftime (3)
10566 to display the time stamp associated with each displayed history entry.
10567 If
10568 .B history
10569 uses
10570 .SM
10571 .BR HISTTIMEFORMAT ,
10572 it does not print an intervening space between the formatted time stamp
10573 and the history entry.
10574 .IP
10575 If \fIfilename\fP is supplied, \fBhistory\fP uses it as the
10576 name of the history file; if not, it uses the value of
10577 .SM
10578 .BR HISTFILE .
10579 If \fIfilename\fP is not supplied and
10580 .SM
10581 .B HISTFILE
10582 is unset or null, the \fB\-a, \-n, \-r,\fP and \fB\-w\fP options
10583 have no effect.
10584 .IP
10585 Options, if supplied, have the following meanings:
10586 .RS
10587 .PD 0
10588 .TP
10589 .B \-c
10590 Clear the history list by deleting all the entries.
10591 This can be used with the other options to replace the history list.
10592 .TP
10593 \fB\-d\fP \fIoffset\fP
10594 Delete the history entry at position \fIoffset\fP.
10595 If \fIoffset\fP is negative, it is interpreted as relative to one greater
10596 than the last history position, so negative indices count back from the
10597 end of the history, and an index of \-1 refers to the current
10598 \fBhistory \-d\fP command.
10599 .TP
10600 \fB\-d\fP \fIstart\fP\-\fIend\fP
10601 Delete the range of history entries between positions \fIstart\fP and
10602 \fIend\fP, inclusive.
10603 Positive and negative values for \fIstart\fP and \fIend\fP
10604 are interpreted as described above.
10605 .TP
10606 .B \-a
10607 Append the
10608 .Q new
10609 history lines to the history file.
10610 These are history lines entered since the beginning of the current
10611 \fBbash\fP session, but not already appended to the history file.
10612 .TP
10613 .B \-n
10614 Read the history lines not already read from the history file
10615 and add them to the current history list.
10616 These are lines appended to the history file since the beginning of the
10617 current \fBbash\fP session.
10618 .TP
10619 .B \-r
10620 Read the history file and append its contents to the current history list.
10621 .TP
10622 .B \-w
10623 Write the current history list to the history file, overwriting
10624 the history file.
10625 .TP
10626 .B \-p
10627 Perform history substitution on the following \fIargs\fP and display
10628 the result on the standard output,
10629 without storing the results in the history list.
10630 Each \fIarg\fP must be quoted to disable normal history expansion.
10631 .TP
10632 .B \-s
10633 Store the
10634 .I args
10635 in the history list as a single entry.
10636 The last command in the
10637 history list is removed before adding the
10638 .IR args .
10639 .PD
10640 .RE
10641 .IP
10642 If the
10643 .SM
10644 .B HISTTIMEFORMAT
10645 variable is set, \fBhistory\fP writes the time stamp information
10646 associated with each history entry to the history file,
10647 marked with the history comment character as described above.
10648 When the history file is read, lines beginning with the history
10649 comment character followed immediately by a digit are interpreted
10650 as timestamps for the following history entry.
10651 .IP
10652 The return value is 0 unless an invalid option is encountered, an
10653 error occurs while reading or writing the history file, an invalid
10654 \fIoffset\fP or range is supplied as an argument to \fB\-d\fP, or the
10655 history expansion supplied as an argument to \fB\-p\fP fails.
10656 .TP
10657 \fBjobs\fP [\fB\-lnprs\fP] [ \fIjobspec\fP .\|.\|. ]
10658 .PD 0
10659 .TP
10660 \fBjobs\fP \fB\-x\fP \fIcommand\fP [ \fIargs\fP .\|.\|. ]
10661 .PD
10662 The first form lists the active jobs.
10663 The options have the following meanings:
10664 .RS
10665 .PD 0
10666 .TP
10667 .B \-l
10668 List process IDs in addition to the normal information.
10669 .TP
10670 .B \-n
10671 Display information only about jobs that have changed status since
10672 the user was last notified of their status.
10673 .TP
10674 .B \-p
10675 List only the process ID of the job's process group leader.
10676 .TP
10677 .B \-r
10678 Display only running jobs.
10679 .TP
10680 .B \-s
10681 Display only stopped jobs.
10682 .PD
10683 .RE
10684 .IP
10685 If
10686 .I jobspec
10687 is supplied, \fBjobs\fP restricts output to information about that job.
10688 The return status is 0 unless an invalid option is encountered
10689 or an invalid
10690 .I jobspec
10691 is supplied.
10692 .IP
10693 If the
10694 .B \-x
10695 option is supplied,
10696 .B jobs
10697 replaces any
10698 .I jobspec
10699 found in
10700 .I command
10701 or
10702 .I args
10703 with the corresponding process group ID, and executes
10704 .IR command ,
10705 passing it
10706 .IR args ,
10707 returning its exit status.
10708 .TP
10709 \fBkill\fP [\fB\-s\fP \fIsigspec\fP | \fB\-n\fP \fIsignum\fP | \fB\-\fP\fIsigspec\fP] \
10710 \fIid\fP [ .\|.\|. ]
10711 .PD 0
10712 .TP
10713 \fBkill\fP \fB\-l\fP|\fB\-L\fP [\fIsigspec\fP | \fIexit_status\fP]
10714 .PD
10715 Send the signal specified by
10716 .I sigspec
10717 or
10718 .I signum
10719 to the processes named by each
10720 .IR id .
10721 Each
10722 .I id
10723 may be a job specification \fIjobspec\fP
10724 or a process ID \fIpid\fP.
10725 .I sigspec
10726 is either a case-insensitive signal name such as
10727 .SM
10728 .B SIGKILL
10729 (with or without the
10730 .SM
10731 .B SIG
10732 prefix) or a signal number;
10733 .I signum
10734 is a signal number.
10735 If
10736 .I sigspec
10737 is not supplied, then
10738 .B kill
10739 sends
10740 .SM
10741 .BR SIGTERM .
10742 .IP
10743 The
10744 .B \-l
10745 option lists the signal names.
10746 If any arguments are supplied when
10747 .B \-l
10748 is given,
10749 .B kill
10750 lists the names of the signals corresponding to the arguments,
10751 and the return status is 0.
10752 The \fIexit_status\fP argument to
10753 .B \-l
10754 is a number specifying either a signal number or the exit status of
10755 a process terminated by a signal;
10756 if it is supplied, \fBkill\fP prints the name of the signal that caused
10757 the process to terminate.
10758 \fBkill\fP assumes that process exit statuses are greater than 128;
10759 anything less than that is a signal number.
10760 The
10761 .B \-L
10762 option is equivalent to \fB\-l\fP.
10763 .IP
10764 .B kill
10765 returns true if at least one signal was successfully sent, or false
10766 if an error occurs or an invalid option is encountered.
10767 .TP
10768 \fBlet\fP \fIarg\fP [\fIarg\fP .\|.\|.]
10769 Each
10770 .I arg
10771 is evaluated as an arithmetic expression (see
10772 .SM
10773 .B "ARITHMETIC EVALUATION"
10774 .ie \n(zZ=1 in \fIbash\fP(1)).
10775 .el above).
10776 If the last
10777 .I arg
10778 evaluates to 0,
10779 .B let
10780 returns 1; otherwise
10781 .B let
10782 returns 0.
10783 .TP
10784 \fBlocal\fP [\fIoption\fP] [\fIname\fP[=\fIvalue\fP] .\|.\|. | \- ]
10785 For each argument, create a local variable named
10786 .I name
10787 and assign it
10788 .IR value .
10789 The \fIoption\fP can be any of the options accepted by \fBdeclare\fP.
10790 When
10791 .B local
10792 is used within a function, it causes the variable
10793 .I name
10794 to have a visible scope restricted to that function and its children.
10795 It is an error to use
10796 .B local
10797 when not within a function.
10798 .IP
10799 If \fIname\fP is \-, it makes the set of shell options
10800 local to the function in which \fBlocal\fP is invoked:
10801 any shell options changed using the \fBset\fP builtin inside
10802 the function after the call to \fBlocal\fP are restored to their
10803 original values when the function returns.
10804 The restore is performed as if a series of \fBset\fP commands were
10805 executed to restore the values that were in place before the function.
10806 .IP
10807 With no operands,
10808 .B local
10809 writes a list of local variables to the standard output.
10810 .IP
10811 The return status is 0 unless
10812 .B local
10813 is used outside a function, an invalid
10814 .I name
10815 is supplied, or
10816 \fIname\fP is a readonly variable.
10817 .TP
10818 .B logout [\fIn\fP]
10819 Exit a login shell,
10820 returning a status of \fIn\fP to the shell's parent.
10821 .TP
10822 \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]
10823 .PD 0
10824 .TP
10825 \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]
10826 .PD
10827 Read lines from the standard input,
10828 or from file descriptor
10829 .I fd
10830 if the
10831 .B \-u
10832 option is supplied,
10833 into the indexed array variable
10834 .IR array .
10835 The variable
10836 .SM
10837 .B MAPFILE
10838 is the default \fIarray\fP.
10839 Options, if supplied, have the following meanings:
10840 .RS
10841 .PD 0
10842 .TP
10843 .B \-d
10844 Use the first character of \fIdelim\fP to terminate each input line,
10845 rather than newline.
10846 If \fIdelim\fP is the empty string, \fBmapfile\fP will terminate a line
10847 when it reads a NUL character.
10848 .TP
10849 .B \-n
10850 Copy at most
10851 .I count
10852 lines.
10853 If \fIcount\fP is 0, copy all lines.
10854 .TP
10855 .B \-O
10856 Begin assigning to
10857 .I array
10858 at index
10859 .IR origin .
10860 The default index is 0.
10861 .TP
10862 .B \-s
10863 Discard the first \fIcount\fP lines read.
10864 .TP
10865 .B \-t
10866 Remove a trailing \fIdelim\fP (default newline) from each line read.
10867 .TP
10868 .B \-u
10869 Read lines from file descriptor \fIfd\fP instead of the standard input.
10870 .TP
10871 .B \-C
10872 Evaluate
10873 .I callback
10874 each time \fIquantum\fP lines are read.
10875 The \fB\-c\fP option specifies
10876 .IR quantum .
10877 .TP
10878 .B \-c
10879 Specify the number of lines read between each call to
10880 .IR callback .
10881 .PD
10882 .RE
10883 .IP
10884 If
10885 .B \-C
10886 is specified without
10887 .BR \-c ,
10888 the default quantum is 5000.
10889 When \fIcallback\fP is evaluated, it is supplied the index of the next
10890 array element to be assigned and the line to be assigned to that element
10891 as additional arguments.
10892 \fIcallback\fP is evaluated after the line is read but before the
10893 array element is assigned.
10894 .IP
10895 If not supplied with an explicit origin, \fBmapfile\fP will clear \fIarray\fP
10896 before assigning to it.
10897 .IP
10898 \fBmapfile\fP returns zero unless an invalid option or option
10899 argument is supplied, \fIarray\fP is invalid or unassignable, or if
10900 \fIarray\fP is not an indexed array.
10901 .TP
10902 \fBpopd\fP [\-\fBn\fP] [+\fIn\fP] [\-\fIn\fP]
10903 Remove entries from the directory stack.
10904 The elements are numbered from 0 starting at the first directory
10905 listed by \fBdirs\fP, so \fBpopd\fP is equivalent to
10906 .Q "popd +0."
10907 With no arguments, \fBpopd\fP removes the top directory from the stack,
10908 and changes to the new top directory.
10909 Arguments, if supplied, have the following meanings:
10910 .RS
10911 .PD 0
10912 .TP
10913 .B \-n
10914 Suppress the normal change of directory when removing directories
10915 from the stack, only manipulate the stack.
10916 .TP
10917 \fB+\fP\fIn\fP
10918 Remove the \fIn\fPth entry counting from the left of the list
10919 shown by
10920 .BR dirs ,
10921 starting with zero, from the stack.
10922 For example:
10923 .Q "popd +0"
10924 removes the first directory,
10925 .Q "popd +1"
10926 the second.
10927 .TP
10928 \fB\-\fP\fIn\fP
10929 Remove the \fIn\fPth entry counting from the right of the list
10930 shown by
10931 .BR dirs ,
10932 starting with zero. For example:
10933 .Q "popd \-0"
10934 removes the last directory,
10935 .Q "popd \-1"
10936 the next to last.
10937 .PD
10938 .RE
10939 .IP
10940 If the top element of the directory stack is modified, and
10941 the \fI\-n\fP option was not supplied, \fBpopd\fP uses the \fBcd\fP
10942 builtin to change to the directory at the top of the stack.
10943 If the \fBcd\fP fails, \fBpopd\fP returns a non-zero value.
10944 .IP
10945 Otherwise,
10946 .B popd
10947 returns false if an invalid option is supplied, the directory stack
10948 is empty, or \fIn\fP specifies a non-existent directory stack entry.
10949 .IP
10950 If the
10951 .B popd
10952 command is successful,
10953 \fBbash\fP runs
10954 .B dirs
10955 to show the final contents of the directory stack,
10956 and the return status is 0.
10957 .TP
10958 \fBprintf\fP [\fB\-v\fP \fIvar\fP] \fIformat\fP [\fIarguments\fP]
10959 Write the formatted \fIarguments\fP to the standard output under the
10960 control of the \fIformat\fP.
10961 The \fB\-v\fP option assigns the output to the variable
10962 \fIvar\fP rather than printing it to the standard output.
10963 .IP
10964 The \fIformat\fP is a character string which contains three types of objects:
10965 plain characters, which are simply copied to standard output, character
10966 escape sequences, which are converted and copied to the standard output, and
10967 format specifications, each of which causes printing of the next successive
10968 \fIargument\fP.
10969 In addition to the standard
10970 .IR printf (3)
10971 format characters
10972 .BR cCsSndiouxXeEfFgGaA ,
10973 \fBprintf\fP interprets the following additional format specifiers:
10974 .RS
10975 .PD 0
10976 .TP
10977 .B %b
10978 causes
10979 \fBprintf\fP to expand backslash escape sequences in the corresponding
10980 \fIargument\fP
10981 in the same way as \fBecho \-e\fP.
10982 .TP
10983 .B %q
10984 causes \fBprintf\fP to output the corresponding
10985 \fIargument\fP in a format that can be reused as shell input.
10986 \fB%q\fP and \fB%Q\fP use the \fB$\*'\*'\fP quoting style if any characters
10987 in the argument string require it, and backslash quoting otherwise.
10988 If the format string uses the \fIprintf\fP alternate form, these two
10989 formats quote the argument string using single quotes.
10990 .TP
10991 .B %Q
10992 like \fB%q\fP, but applies any supplied precision to the \fIargument\fP
10993 before quoting it.
10994 .TP
10995 .B %(\fIdatefmt\fP)T
10996 causes \fBprintf\fP to output the date-time string resulting from using
10997 \fIdatefmt\fP as a format string for
10998 .IR strftime (3).
10999 The corresponding \fIargument\fP is an integer representing the number of
11000 seconds since the epoch.
11001 This format specifier recognizes two special argument values:
11002 \-1 represents the current time,
11003 and \-2 represents the time the shell was invoked.
11004 If no argument is specified, conversion behaves as if \-1 had been supplied.
11005 This is an exception to the usual \fBprintf\fP behavior.
11006 .PD
11007 .RE
11008 .IP
11009 The %b, %q, and %T format specifiers all use the field width and precision
11010 arguments from the format specification and write that many bytes from
11011 (or use that wide a field for) the expanded argument, which usually
11012 contains more characters than the original.
11013 .IP
11014 The %n format specifier accepts a corresponding argument that is treated
11015 as a shell variable name.
11016 .IP
11017 The %s and %c format specifiers accept an l (long) modifier, which forces
11018 them to convert the argument string to a wide-character string and apply
11019 any supplied field width and precision in terms of characters, not bytes.
11020 The %S and %C format specifiers are equivalent to %ls and %lc, respectively.
11021 .\" .IP
11022 .\" The %s format specifier understands the "altform" flag (#) and behaves
11023 .\" identically to the %b format specifier if it's supplied.
11024 .IP
11025 Arguments to non-string format specifiers are treated as C constants,
11026 except that a leading plus or minus sign is allowed, and if the leading
11027 character is a single or double quote, the value is the numeric value of
11028 the following character, using the current locale.
11029 .IP
11030 The \fIformat\fP is reused as necessary to consume all of the \fIarguments\fP.
11031 If the \fIformat\fP requires more \fIarguments\fP than are supplied, the
11032 extra format specifications behave as if a zero value or null string, as
11033 appropriate, had been supplied.
11034 The return value is zero on success,
11035 non-zero if an invalid option is supplied or a write or assignment error
11036 occurs.
11037 .TP
11038 \fBpushd\fP [\fB\-n\fP] [+\fIn\fP] [\-\fIn\fP]
11039 .PD 0
11040 .TP
11041 \fBpushd\fP [\fB\-n\fP] [\fIdir\fP]
11042 .PD
11043 Add a directory to the top of the directory stack, or rotate
11044 the stack, making the new top of the stack the current working
11045 directory.
11046 With no arguments, \fBpushd\fP exchanges the top two elements of
11047 the directory stack.
11048 Arguments, if supplied, have the following meanings:
11049 .RS
11050 .PD 0
11051 .TP
11052 .B \-n
11053 Suppress the normal change of directory when rotating or
11054 adding directories to the stack, only manipulate the stack.
11055 .TP
11056 \fB+\fP\fIn\fP
11057 Rotate the stack so that the \fIn\fPth directory
11058 (counting from the left of the list shown by
11059 .BR dirs ,
11060 starting with zero)
11061 is at the top.
11062 .TP
11063 \fB\-\fP\fIn\fP
11064 Rotates the stack so that the \fIn\fPth directory
11065 (counting from the right of the list shown by
11066 .BR dirs ,
11067 starting with zero) is at the top.
11068 .TP
11069 .I dir
11070 Adds
11071 .I dir
11072 to the directory stack at the top.
11073 .PD
11074 .RE
11075 .IP
11076 After the stack has been modified, if the \fB\-n\fP option was not
11077 supplied, \fBpushd\fP uses the \fBcd\fP builtin to change to the
11078 directory at the top of the stack.
11079 If the \fBcd\fP fails, \fBpushd\fP returns a non-zero value.
11080 .IP
11081 Otherwise, if no arguments are supplied,
11082 .B pushd
11083 returns zero unless the directory stack is empty.
11084 When rotating the directory stack,
11085 .B pushd
11086 returns zero unless the directory stack is empty or
11087 \fIn\fP specifies a non-existent directory stack element.
11088 .IP
11089 If the
11090 .B pushd
11091 command is successful,
11092 \fBbash\fP runs
11093 .B dirs
11094 to show the final contents of the directory stack.
11095 .TP
11096 \fBpwd\fP [\fB\-LP\fP]
11097 Print the absolute pathname of the current working directory.
11098 The pathname printed contains no symbolic links if the
11099 .B \-P
11100 option is supplied or the
11101 .B \-o physical
11102 option to the
11103 .B set
11104 builtin command is enabled.
11105 If the
11106 .B \-L
11107 option is used, the pathname printed may contain symbolic links.
11108 The return status is 0 unless an error occurs while
11109 reading the name of the current directory or an
11110 invalid option is supplied.
11111 .TP
11112 \fBread\fP [\fB\-Eers\fP] [\fB\-a\fP \fIaname\fP] \
11113 [\fB\-d\fP \fIdelim\fP] [\fB\-i\fP \fItext\fP] \
11114 [\fB\-n\fP \fInchars\fP] [\fB\-N\fP \fInchars\fP] \
11115 [\fB\-p\fP \fIprompt\fP] [\fB\-t\fP \fItimeout\fP] \
11116 [\fB\-u\fP \fIfd\fP] [\fIname\fP .\|.\|.]
11117 Read one line from the standard input, or from the file descriptor
11118 \fIfd\fP supplied as an argument to the \fB\-u\fP option,
11119 split it into words as described
11120 .ie \n(zZ=1 in \fIbash\fP (1)
11121 .el above
11122 under \fBWord Splitting\fP,
11123 and assign the first word to the first
11124 .IR name ,
11125 the second word to the second
11126 .IR name ,
11127 and so on.
11128 If there are more words than names, the remaining words and their
11129 intervening delimiters are assigned to the last
11130 .IR name .
11131 If there are fewer words read from the input stream than names,
11132 the remaining names are assigned empty values.
11133 The characters in the value of the
11134 .SM
11135 .B IFS
11136 variable
11137 are used to split the line into words using the same rules the shell
11138 uses for expansion (described
11139 .ie \n(zZ=1 in \fIbash\fP (1)
11140 .el above
11141 under \fBWord Splitting\fP).
11142 The backslash character (\fB\e\fP) removes any special
11143 meaning for the next character read and is used for line continuation.
11144 .IP
11145 Options, if supplied, have the following meanings:
11146 .RS
11147 .PD 0
11148 .TP
11149 .B \-a \fIaname\fP
11150 The words are assigned to sequential indices of the array variable
11151 .IR aname ,
11152 starting at 0.
11153 .I aname
11154 is unset before any new values are assigned.
11155 Other \fIname\fP arguments are ignored.
11156 .TP
11157 .B \-d \fIdelim\fP
11158 The first character of \fIdelim\fP terminates the input line,
11159 rather than newline.
11160 If \fIdelim\fP is the empty string, \fBread\fP will terminate a line
11161 when it reads a NUL character.
11162 .TP
11163 .B \-e
11164 If the standard input is coming from a terminal,
11165 \fBread\fP uses
11166 .B readline
11167 (see
11168 .SM
11169 .B READLINE
11170 .ie \n(zZ=1 in \fIbash\fP(1))
11171 .el above)
11172 to obtain the line.
11173 \fBReadline\fP uses the current
11174 (or default, if line editing was not previously active)
11175 editing settings, but uses \fBreadline\fP's default filename completion.
11176 .TP
11177 .B \-E
11178 If the standard input is coming from a terminal,
11179 \fBread\fP uses
11180 .B readline
11181 (see
11182 .SM
11183 .B READLINE
11184 .ie \n(zZ=1 in \fIbash\fP(1))
11185 .el above)
11186 to obtain the line.
11187 .B Readline
11188 uses the current (or default, if line editing was not previously
11189 active) editing settings, but uses bash's default completion, including
11190 programmable completion.
11191 .TP
11192 .B \-i \fItext\fP
11193 If
11194 .B readline
11195 is being used to read the line, \fBread\fP places \fItext\fP into
11196 the editing buffer before editing begins.
11197 .TP
11198 .B \-n \fInchars\fP
11199 \fBread\fP returns after reading \fInchars\fP characters rather than
11200 waiting for a complete line of input,
11201 unless it encounters EOF or \fBread\fP times out,
11202 but honors a delimiter if it reads fewer
11203 than \fInchars\fP characters before the delimiter.
11204 .TP
11205 .B \-N \fInchars\fP
11206 \fBread\fP returns after reading exactly \fInchars\fP characters rather
11207 than waiting for a complete line of input,
11208 unless it encounters EOF or \fBread\fP times out.
11209 Any delimiter characters in the input are
11210 not treated specially and do not cause \fBread\fP to return until
11211 it has read \fInchars\fP characters.
11212 The result is not split on the characters in \fBIFS\fP; the intent is
11213 that the variable is assigned exactly the characters read
11214 (with the exception of backslash; see the \fB\-r\fP option below).
11215 .TP
11216 .B \-p \fIprompt\fP
11217 Display \fIprompt\fP on standard error, without a
11218 trailing newline, before attempting to read any input, but
11219 only if input is coming from a terminal.
11220 .TP
11221 .B \-r
11222 Backslash does not act as an escape character.
11223 The backslash is considered to be part of the line.
11224 In particular, a backslash-newline pair may not then be used as a line
11225 continuation.
11226 .TP
11227 .B \-s
11228 Silent mode.
11229 If input is coming from a terminal, characters are not echoed.
11230 .TP
11231 .B \-t \fItimeout\fP
11232 Cause \fBread\fP to time out and return failure if it does not read
11233 a complete line of input (or a specified number of characters)
11234 within \fItimeout\fP seconds.
11235 \fItimeout\fP may be a decimal number with a fractional portion following
11236 the decimal point.
11237 This option is only effective if \fBread\fP is reading input from a
11238 terminal, pipe, or other special file; it has no effect when reading
11239 from regular files.
11240 If \fBread\fP times out, it saves any partial input read into
11241 the specified variable \fIname\fP, and the exit status is greater than 128.
11242 If \fItimeout\fP is 0, \fBread\fP returns immediately, without trying to
11243 read any data.
11244 In this case, the exit status is 0 if input is available on the specified
11245 file descriptor, or the read will return EOF, non-zero otherwise.
11246 .TP
11247 .B \-u \fIfd\fP
11248 Read input from file descriptor \fIfd\fP instead of the standard input.
11249 .PD
11250 .RE
11251 .IP
11252 Other than the case where \fIdelim\fP is the empty string, \fBread\fP
11253 ignores any NUL characters in the input.
11254 .IP
11255 If no
11256 .I names
11257 are supplied, \fBread\fP assigns the line read,
11258 without the ending delimiter but otherwise unmodified,
11259 to the variable
11260 .SM
11261 .BR REPLY .
11262 .IP
11263 The exit status is zero, unless end-of-file is encountered, \fBread\fP
11264 times out (in which case the status is greater than 128),
11265 a variable assignment error (such as assigning to a readonly variable) occurs,
11266 or an invalid file descriptor is supplied as the argument to \fB\-u\fP.
11267 .TP
11268 \fBreadonly\fP [\fB\-aAf\fP] [\fB\-p\fP] [\fIname\fP[=\fIword\fP] .\|.\|.]
11269 .PD
11270 The given
11271 \fInames\fP are marked readonly; the values of these
11272 .I names
11273 may not be changed by subsequent assignment or unset.
11274 If the
11275 .B \-f
11276 option is supplied, each \fIname\fP refers to a shell function.
11277 The
11278 .B \-a
11279 option restricts the variables to indexed arrays; the
11280 .B \-A
11281 option restricts the variables to associative arrays.
11282 If both options are supplied,
11283 .B \-A
11284 takes precedence.
11285 If no
11286 .I name
11287 arguments are supplied, or if the
11288 .B \-p
11289 option is supplied, print a list of all readonly names.
11290 The other options may be used to restrict the output to a subset of
11291 the set of readonly names.
11292 The
11293 .B \-p
11294 option displays output in a format that may be reused as input.
11295 .IP
11296 \fBreadonly\fP allows the value of a variable to be set at the same time
11297 the readonly attribute is changed by following the variable name with
11298 =\fIvalue\fP.
11299 This sets the value of the variable is to \fIvalue\fP while modifying
11300 the readonly attribute.
11301 .IP
11302 The return status is 0 unless an invalid option is encountered,
11303 one of the
11304 .I names
11305 is not a valid shell variable name, or
11306 .B \-f
11307 is supplied with a
11308 .I name
11309 that is not a function.
11310 .TP
11311 \fBreturn\fP [\fIn\fP]
11312 Stop executing a shell function or sourced file and return the value
11313 specified by
11314 .I n
11315 to its caller.
11316 If
11317 .I n
11318 is omitted, the return status is that of the last command
11319 executed.
11320 If \fBreturn\fP is executed by a trap handler, the last command used to
11321 determine the status is the last command executed before the trap handler.
11322 If \fBreturn\fP is executed during a \fBDEBUG\fP trap, the last command
11323 used to determine the status is the last command executed by the trap
11324 handler before \fBreturn\fP was invoked.
11325 .IP
11326 When
11327 .B return
11328 is used to terminate execution of a script being executed by the
11329 .B .
11330 (\fBsource\fP) command, it causes the shell to stop executing
11331 that script and return either
11332 .I n
11333 or the exit status of the last command executed within the
11334 script as the exit status of the script.
11335 If \fIn\fP is supplied, the return value is its least significant
11336 8 bits.
11337 .IP
11338 Any command associated with the \fBRETURN\fP trap is executed
11339 before execution resumes after the function or script.
11340 .IP
11341 The return status is non-zero if
11342 .B return
11343 is supplied a non-numeric argument, or is used outside a
11344 function and not during execution of a script by \fB.\fP\^ or \fBsource\fP.
11345 .TP
11346 \fBset\fP [\fB\-abefhkmnptuvxBCEHPT\fP] [\fB\-o\fP \fIoption\-name\fP] \
11347 [\fB\-\-\fP] [\fB\-\fP] [\fIarg\fP .\|.\|.]
11348 .PD 0
11349 .TP
11350 \fBset\fP [\fB+abefhkmnptuvxBCEHPT\fP] [\fB+o\fP \fIoption\-name\fP] \
11351 [\fB\-\-\fP] [\fB\-\fP] [\fIarg\fP .\|.\|.]
11352 .TP
11353 \fBset \-o\fP
11354 .TP
11355 \fBset +o\fP
11356 .PD
11357 Without options, display the name and value of each shell variable
11358 in a format that can be reused as input
11359 for setting or resetting the currently-set variables.
11360 Read-only variables cannot be reset.
11361 In posix mode, only shell variables are listed.
11362 The output is sorted according to the current locale.
11363 When options are specified, they set or unset shell attributes.
11364 Any arguments remaining after option processing are treated
11365 as values for the positional parameters and are assigned, in order, to
11366 .BR $1 ,
11367 .BR $2 ,
11368 \&.\|.\|.,
11369 .BR $\fIn\fP .
11370 Options, if specified, have the following meanings:
11371 .RS
11372 .PD 0
11373 .TP 8
11374 .B \-a
11375 Each variable or function that is created or modified is given the
11376 export attribute and marked for export to the environment of
11377 subsequent commands.
11378 .TP 8
11379 .B \-b
11380 Report the status of terminated background jobs
11381 immediately, rather than before the next primary prompt or after a
11382 foreground command terminates.
11383 This is effective only when job control is enabled.
11384 .TP 8
11385 .B \-e
11386 .PD
11387 Exit immediately if a
11388 \fIpipeline\fP (which may consist of a single \fIsimple command\fP),
11389 a \fIlist\fP,
11390 or a \fIcompound command\fP
11391 (see
11392 .SM
11393 .B "SHELL GRAMMAR"
11394 .ie \n(zZ=1 in \fIbash\fP(1)),
11395 .el above),
11396 exits with a non-zero status.
11397 The shell does not exit if the
11398 command that fails is part of the command list immediately following a
11399 .B while
11400 or
11401 .B until
11402 reserved word,
11403 part of the test following the
11404 .B if
11405 or
11406 .B elif
11407 reserved words, part of any command executed in a
11408 .B &&
11409 or
11410 .B ||
11411 list except the command following the final \fB&&\fP or \fB||\fP,
11412 any command in a pipeline but the last
11413 (subject to the state of the \fBpipefail\fP shell option),
11414 or if the command's return value is
11415 being inverted with
11416 .BR ! .
11417 If a compound command other than a subshell
11418 returns a non-zero status because a command failed
11419 while \fB\-e\fP was being ignored, the shell does not exit.
11420 A trap on \fBERR\fP, if set, is executed before the shell exits.
11421 This option applies to the shell environment and each subshell environment
11422 separately (see
11423 .SM
11424 .B "COMMAND EXECUTION ENVIRONMENT"
11425 .ie \n(zZ=1 in \fIbash\fP(1)),
11426 .el above),
11427 and may cause
11428 subshells to exit before executing all the commands in the subshell.
11429 .IP
11430 If a compound command or shell function executes in a context
11431 where \fB\-e\fP is being ignored,
11432 none of the commands executed within the compound command or function body
11433 will be affected by the \fB\-e\fP setting, even if \fB\-e\fP is set
11434 and a command returns a failure status.
11435 If a compound command or shell function sets \fB\-e\fP while executing in
11436 a context where \fB\-e\fP is ignored, that setting will not have any
11437 effect until the compound command or the command containing the function
11438 call completes.
11439 .PD 0
11440 .TP 8
11441 .B \-f
11442 Disable pathname expansion.
11443 .TP 8
11444 .B \-h
11445 Remember the location of commands as they are looked up for execution.
11446 This is enabled by default.
11447 .TP 8
11448 .B \-k
11449 All arguments in the form of assignment statements
11450 are placed in the environment for a command, not just
11451 those that precede the command name.
11452 .TP 8
11453 .B \-m
11454 Monitor mode.
11455 Job control is enabled.
11456 This option is on by default for interactive shells on systems
11457 that support it (see
11458 .SM
11459 .B "JOB CONTROL"
11460 .ie \n(zZ=1 in \fIbash\fP(1)).
11461 .el above).
11462 All processes run in a separate process group.
11463 When a background job completes, the shell prints a line
11464 containing its exit status.
11465 .TP 8
11466 .B \-n
11467 Read commands but do not execute them.
11468 This may be used to check a shell script for syntax errors.
11469 This is ignored by interactive shells.
11470 .TP 8
11471 .B \-o \fIoption\-name\fP
11472 The \fIoption\-name\fP can be one of the following:
11473 .RS
11474 .TP 8
11475 .B allexport
11476 Same as
11477 .BR \-a .
11478 .TP 8
11479 .B braceexpand
11480 Same as
11481 .BR \-B .
11482 .TP 8
11483 .B emacs
11484 Use an emacs-style command line editing interface. This is enabled
11485 by default when the shell is interactive, unless the shell is started
11486 with the
11487 .B \-\-noediting
11488 option.
11489 This also affects the editing interface used for \fBread \-e\fP.
11490 .TP 8
11491 .B errexit
11492 Same as
11493 .BR \-e .
11494 .TP 8
11495 .B errtrace
11496 Same as
11497 .BR \-E .
11498 .TP 8
11499 .B functrace
11500 Same as
11501 .BR \-T .
11502 .TP 8
11503 .B hashall
11504 Same as
11505 .BR \-h .
11506 .TP 8
11507 .B histexpand
11508 Same as
11509 .BR \-H .
11510 .TP 8
11511 .B history
11512 Enable command history, as described
11513 .ie \n(zZ=1 in \fIbash\fP(1)
11514 .el above
11515 under
11516 .SM
11517 .BR HISTORY .
11518 This option is on by default in interactive shells.
11519 .TP 8
11520 .B ignoreeof
11521 The effect is as if the shell command
11522 .QN "IGNOREEOF=10"
11523 had been executed
11524 (see
11525 .B "Shell Variables"
11526 .ie \n(zZ=1 in \fIbash\fP(1)).
11527 .el above).
11528 .TP 8
11529 .B keyword
11530 Same as
11531 .BR \-k .
11532 .TP 8
11533 .B monitor
11534 Same as
11535 .BR \-m .
11536 .TP 8
11537 .B noclobber
11538 Same as
11539 .BR \-C .
11540 .TP 8
11541 .B noexec
11542 Same as
11543 .BR \-n .
11544 .TP 8
11545 .B noglob
11546 Same as
11547 .BR \-f .
11548 .TP 8
11549 .B nolog
11550 Currently ignored.
11551 .TP 8
11552 .B notify
11553 Same as
11554 .BR \-b .
11555 .TP 8
11556 .B nounset
11557 Same as
11558 .BR \-u .
11559 .TP 8
11560 .B onecmd
11561 Same as
11562 .BR \-t .
11563 .TP 8
11564 .B physical
11565 Same as
11566 .BR \-P .
11567 .TP 8
11568 .B pipefail
11569 If set, the return value of a pipeline is the value of the last
11570 (rightmost) command to exit with a non-zero status, or zero if all
11571 commands in the pipeline exit successfully.
11572 This option is disabled by default.
11573 .TP 8
11574 .B posix
11575 Enable posix mode;
11576 change the behavior of
11577 .B bash
11578 where the default operation differs
11579 from the
11580 .SM POSIX
11581 standard to match the standard.
11582 See
11583 .SM
11584 .B "SEE ALSO"
11585 .ie \n(zZ=1 in \fIbash\fP(1)
11586 .el below
11587 for a reference to a document that details how posix mode affects
11588 bash's behavior.
11589 .TP 8
11590 .B privileged
11591 Same as
11592 .BR \-p .
11593 .TP 8
11594 .B verbose
11595 Same as
11596 .BR \-v .
11597 .TP 8
11598 .B vi
11599 Use a vi-style command line editing interface.
11600 This also affects the editing interface used for \fBread \-e\fP.
11601 .TP 8
11602 .B xtrace
11603 Same as
11604 .BR \-x .
11605 .PP
11606 If
11607 .B \-o
11608 is supplied with no \fIoption\-name\fP,
11609 \fBset\fP prints the current shell option settings.
11610 If
11611 .B +o
11612 is supplied with no \fIoption\-name\fP,
11613 \fBset\fP prints a series of
11614 .B set
11615 commands to recreate the current option settings
11616 on the standard output.
11617 .RE
11618 .TP 8
11619 .B \-p
11620 Turn on
11621 .I privileged
11622 mode. In this mode, the shell does not read the
11623 .SM
11624 .B $ENV
11625 and
11626 .SM
11627 .B $BASH_ENV
11628 files, shell functions are not inherited from the
11629 environment, and the
11630 .SM
11631 .BR SHELLOPTS ,
11632 .SM
11633 .BR BASHOPTS ,
11634 .SM
11635 .BR CDPATH ,
11636 and
11637 .SM
11638 .B GLOBIGNORE
11639 variables, if they appear in the environment, are ignored.
11640 If the shell is started with the effective user (group) id not equal to the
11641 real user (group) id, and the \fB\-p\fP option is not supplied, these actions
11642 are taken and the effective user id is set to the real user id.
11643 If the \fB\-p\fP option is supplied at startup, the effective user id is
11644 not reset.
11645 Turning this option off causes the effective user
11646 and group ids to be set to the real user and group ids.
11647 .TP 8
11648 .B \-r
11649 Enable restricted shell mode.
11650 This option cannot be unset once it has been set.
11651 .TP 8
11652 .B \-t
11653 Exit after reading and executing one command.
11654 .TP 8
11655 .B \-u
11656 Treat unset variables and parameters other than the special
11657 parameters
11658 .Q @
11659 and
11660 .Q * ,
11661 or array variables subscripted with
11662 .Q @
11663 or
11664 .Q * ,
11665 as an error when performing parameter expansion.
11666 If expansion is attempted on an unset variable or parameter,
11667 the shell prints an error message, and,
11668 if not interactive, exits with a non-zero status.
11669 .TP 8
11670 .B \-v
11671 Print shell input lines as they are read.
11672 .TP 8
11673 .B \-x
11674 After expanding each \fIsimple command\fP,
11675 \fBfor\fP command, \fBcase\fP command, \fBselect\fP command, or
11676 arithmetic \fBfor\fP command, display the expanded value of
11677 .SM
11678 .BR PS4 ,
11679 followed by the command and its expanded arguments
11680 or associated word list, to the standard error.
11681 .TP 8
11682 .B \-B
11683 The shell performs brace expansion (see
11684 .B "Brace Expansion"
11685 .ie \n(zZ=1 in \fIbash\fP(1)).
11686 .el above).
11687 This is on by default.
11688 .TP 8
11689 .B \-C
11690 If set,
11691 .B bash
11692 does not overwrite an existing file with the
11693 .BR > ,
11694 .BR >& ,
11695 and
11696 .B <>
11697 redirection operators.
11698 Using the redirection operator
11699 .B >|
11700 instead of
11701 .B >
11702 will override this and force the creation of an output file.
11703 .TP 8
11704 .B \-E
11705 If set, any trap on \fBERR\fP is inherited by shell functions, command
11706 substitutions, and commands executed in a subshell environment.
11707 The \fBERR\fP trap is normally not inherited in such cases.
11708 .TP 8
11709 .B \-H
11710 Enable
11711 .B !
11712 style history substitution.
11713 This option is on by default when the shell is interactive.
11714 .TP 8
11715 .B \-P
11716 If set, the shell does not resolve symbolic links when executing
11717 commands such as
11718 .B cd
11719 that change the current working directory.
11720 It uses the physical directory structure instead.
11721 By default,
11722 .B bash
11723 follows the logical chain of directories when performing commands
11724 which change the current directory.
11725 .TP 8
11726 .B \-T
11727 If set, any traps on \fBDEBUG\fP and \fBRETURN\fP are inherited by shell
11728 functions, command substitutions, and commands executed in a
11729 subshell environment.
11730 The \fBDEBUG\fP and \fBRETURN\fP traps are normally not inherited
11731 in such cases.
11732 .TP 8
11733 .B \-\-
11734 If no arguments follow this option, unset the positional parameters.
11735 Otherwise, set the positional parameters to the
11736 \fIarg\fPs, even if some of them begin with a
11737 .BR \- .
11738 .TP 8
11739 .B \-
11740 Signal the end of options, and assign all remaining \fIarg\fPs to
11741 the positional parameters.
11742 The
11743 .B \-x
11744 and
11745 .B \-v
11746 options are turned off.
11747 If there are no \fIarg\fPs, the positional parameters remain unchanged.
11748 .PD
11749 .PP
11750 The options are off by default unless otherwise noted.
11751 Using + rather than \- causes these options to be turned off.
11752 The options can also be specified as arguments to an invocation of
11753 the shell.
11754 The current set of options may be found in
11755 .BR $\- .
11756 The return status is always zero unless an invalid option is encountered.
11757 .RE
11758 .TP
11759 \fBshift\fP [\fIn\fP]
11760 Rename positional parameters from \fIn\fP+1 .\|.\|.\& to
11761 .B $1
11762 .B .\|.\|..
11763 Parameters represented by the numbers \fB$#\fP
11764 down to \fB$#\fP\-\fIn\fP+1 are unset.
11765 .I n
11766 must be a non-negative number less than or equal to \fB$#\fP.
11767 If
11768 .I n
11769 is 0, no parameters are changed.
11770 If
11771 .I n
11772 is not given, it is assumed to be 1.
11773 If
11774 .I n
11775 is greater than \fB$#\fP, the positional parameters are not changed.
11776 The return status is greater than zero if
11777 .I n
11778 is greater than
11779 .B $#
11780 or less than zero; otherwise 0.
11781 .TP
11782 \fBshopt\fP [\fB\-pqsu\fP] [\fB\-o\fP] [\fIoptname\fP .\|.\|.]
11783 Toggle the values of settings controlling optional shell behavior.
11784 The settings can be either those listed below, or, if the
11785 .B \-o
11786 option is used, those available with the
11787 .B \-o
11788 option to the \fBset\fP builtin command.
11789 .IP
11790 With no options, or with the
11791 .B \-p
11792 option, display a list of all settable options, with
11793 an indication of whether or not each is set;
11794 if any \fIoptnames\fP are supplied, the output is restricted to those options.
11795 The \fB\-p\fP option displays output in a form that
11796 may be reused as input.
11797 .IP
11798 Other options have the following meanings:
11799 .RS
11800 .PD 0
11801 .TP
11802 .B \-s
11803 Enable (set) each \fIoptname\fP.
11804 .TP
11805 .B \-u
11806 Disable (unset) each \fIoptname\fP.
11807 .TP
11808 .B \-q
11809 Suppresses normal output (quiet mode); the return status indicates
11810 whether the \fIoptname\fP is set or unset.
11811 If multiple \fIoptname\fP arguments are supplied with
11812 .BR \-q ,
11813 the return status is zero if all \fIoptnames\fP are enabled; non-zero
11814 otherwise.
11815 .TP
11816 .B \-o
11817 Restricts the values of \fIoptname\fP to be those defined for the
11818 .B \-o
11819 option to the
11820 .B set
11821 builtin.
11822 .PD
11823 .PP
11824 If either
11825 .B \-s
11826 or
11827 .B \-u
11828 is used with no \fIoptname\fP arguments,
11829 .B shopt
11830 shows only those options which are set or unset, respectively.
11831 Unless otherwise noted, the \fBshopt\fP options are disabled (unset)
11832 by default.
11833 .PP
11834 The return status when listing options is zero if all \fIoptnames\fP
11835 are enabled, non-zero otherwise. When setting or unsetting options,
11836 the return status is zero unless an \fIoptname\fP is not a valid shell
11837 option.
11838 .PP
11839 The list of \fBshopt\fP options is:
11840 .PP
11841 .PD 0
11842 .TP 8
11843 .B array_expand_once
11844 If set, the shell suppresses multiple evaluation of
11845 associative and indexed array subscripts
11846 during arithmetic expression evaluation, while executing
11847 builtins that can perform variable assignments,
11848 and while executing builtins that perform array dereferencing.
11849 .TP 8
11850 .B assoc_expand_once
11851 Deprecated; a synonym for \fBarray_expand_once\fP.
11852 .TP 8
11853 .B autocd
11854 If set, a command name that is the name of a directory is executed as if
11855 it were the argument to the \fBcd\fP command.
11856 This option is only used by interactive shells.
11857 .TP 8
11858 .B bash_source_fullpath
11859 If set, filenames added to the \fBBASH_SOURCE\fP array variable are
11860 converted to full pathnames (see \fBShell Variables\fP above).
11861 .TP 8
11862 .B cdable_vars
11863 If set, an argument to the
11864 .B cd
11865 builtin command that
11866 is not a directory is assumed to be the name of a variable whose
11867 value is the directory to change to.
11868 .TP 8
11869 .B cdspell
11870 If set, the
11871 .B cd
11872 command attempts to correct
11873 minor errors in the spelling of a directory component.
11874 Minor errors include transposed characters,
11875 a missing character, and one extra character.
11876 If \fBcd\fP corrects the directory name, it prints the corrected filename,
11877 and the command proceeds.
11878 This option is only used by interactive shells.
11879 .TP 8
11880 .B checkhash
11881 If set, \fBbash\fP checks that a command found in the hash
11882 table exists before trying to execute it.
11883 If a hashed command no longer exists, \fBbash\fP performs a normal path search.
11884 .TP 8
11885 .B checkjobs
11886 If set, \fBbash\fP lists the status of any stopped and running jobs before
11887 exiting an interactive shell.
11888 If any jobs are running, \fBbash\fP defers the exit until a second
11889 exit is attempted without an intervening command (see
11890 .SM
11891 .B "JOB CONTROL"
11892 .ie \n(zZ=1 in \fIbash\fP(1)).
11893 .el above).
11894 The shell always postpones exiting if any jobs are stopped.
11895 .TP 8
11896 .B checkwinsize
11897 If set, \fBbash\fP checks the window size after each external (non-builtin)
11898 command
11899 and, if necessary, updates the values of
11900 .SM
11901 .B LINES
11902 and
11903 .SM
11904 .BR COLUMNS ,
11905 using the file descriptor associated with the standard error
11906 if it is a terminal.
11907 This option is enabled by default.
11908 .TP 8
11909 .B cmdhist
11910 If set,
11911 .B bash
11912 attempts to save all lines of a multiple-line
11913 command in the same history entry.
11914 This allows easy re-editing of multi-line commands.
11915 This option is enabled by default, but only has an effect if command
11916 history is enabled, as described
11917 .ie \n(zZ=1 in \fIbash\fP(1)
11918 .el above
11919 under
11920 .SM
11921 .BR HISTORY .
11922 .PD 0
11923 .TP 8
11924 .B compat31
11925 .TP 8
11926 .B compat32
11927 .TP 8
11928 .B compat40
11929 .TP 8
11930 .B compat41
11931 .TP 8
11932 .B compat42
11933 .TP 8
11934 .B compat43
11935 .TP 8
11936 .B compat44
11937 .PD
11938 These control aspects of the shell's compatibility mode
11939 (see
11940 .SM
11941 .B "SHELL COMPATIBILITY MODE"
11942 .ie \n(zZ=1 in \fIbash\fP(1)).
11943 .el below).
11944 .PD 0
11945 .TP 8
11946 .B complete_fullquote
11947 If set,
11948 .B bash
11949 quotes all shell metacharacters in filenames and directory names when
11950 performing completion.
11951 If not set,
11952 .B bash
11953 removes metacharacters such as the dollar sign from the set of
11954 characters that will be quoted in completed filenames
11955 when these metacharacters appear in shell variable references in words to be
11956 completed.
11957 This means that dollar signs in variable names that expand to directories
11958 will not be quoted;
11959 however, any dollar signs appearing in filenames will not be quoted, either.
11960 This is active only when bash is using backslashes to quote completed
11961 filenames.
11962 This variable is set by default, which is the default bash behavior in
11963 versions through 4.2.
11964 .TP 8
11965 .B direxpand
11966 If set,
11967 .B bash
11968 replaces directory names with the results of word expansion when performing
11969 filename completion.
11970 This changes the contents of the \fBreadline\fP editing buffer.
11971 If not set,
11972 .B bash
11973 attempts to preserve what the user typed.
11974 .TP 8
11975 .B dirspell
11976 If set,
11977 .B bash
11978 attempts spelling correction on directory names during word completion
11979 if the directory name initially supplied does not exist.
11980 .TP 8
11981 .B dotglob
11982 If set,
11983 .B bash
11984 includes filenames beginning with a
11985 .Q .\&
11986 in the results of pathname expansion.
11987 The filenames
11988 .FN .\&
11989 and
11990 .FN ..\&
11991 must always be matched explicitly, even if
11992 .B dotglob
11993 is set.
11994 .TP 8
11995 .B execfail
11996 If set, a non-interactive shell will not exit if
11997 it cannot execute the file specified as an argument to the
11998 .B exec
11999 builtin.
12000 An interactive shell does not exit if
12001 .B exec
12002 fails.
12003 .TP 8
12004 .B expand_aliases
12005 If set, aliases are expanded as described
12006 .ie \n(zZ=1 in \fIbash\fP(1)
12007 .el above
12008 under
12009 .SM
12010 .BR ALIASES .
12011 This option is enabled by default for interactive shells.
12012 .TP 8
12013 .B extdebug
12014 If set at shell invocation, or in a shell startup file,
12015 arrange to execute the debugger profile
12016 before the shell starts, identical to the \fB\-\-debugger\fP option.
12017 If set after invocation, behavior intended for use by debuggers is enabled:
12018 .RS
12019 .TP
12020 .B 1.
12021 The \fB\-F\fP option to the \fBdeclare\fP builtin displays the source
12022 file name and line number corresponding to each function name supplied
12023 as an argument.
12024 .TP
12025 .B 2.
12026 If the command run by the \fBDEBUG\fP trap returns a non-zero value, the
12027 next command is skipped and not executed.
12028 .TP
12029 .B 3.
12030 If the command run by the \fBDEBUG\fP trap returns a value of 2, and the
12031 shell is executing in a subroutine (a shell function or a shell script
12032 executed by the \fB.\fP or \fBsource\fP builtins), the shell simulates
12033 a call to \fBreturn\fP.
12034 .TP
12035 .B 4.
12036 .SM
12037 .B BASH_ARGC
12038 and
12039 .SM
12040 .B BASH_ARGV
12041 are updated as described in their descriptions
12042 .ie \n(zZ=1 in \fIbash\fP(1)).
12043 .el above).
12044 .TP
12045 .B 5.
12046 Function tracing is enabled: command substitution, shell functions, and
12047 subshells invoked with \fB(\fP \fIcommand\fP \fB)\fP inherit the
12048 \fBDEBUG\fP and \fBRETURN\fP traps.
12049 .TP
12050 .B 6.
12051 Error tracing is enabled: command substitution, shell functions, and
12052 subshells invoked with \fB(\fP \fIcommand\fP \fB)\fP inherit the
12053 \fBERR\fP trap.
12054 .RE
12055 .TP 8
12056 .B extglob
12057 If set, enable the extended pattern matching features described
12058 .ie \n(zZ=1 in \fIbash\fP(1)
12059 .el above
12060 under
12061 \fBPathname Expansion\fP.
12062 .TP 8
12063 .B extquote
12064 If set, \fB$\fP\*'\fIstring\fP\*' and \fB$\fP\*"\fIstring\fP\*" quoting is
12065 performed within \fB${\fP\fIparameter\fP\fB}\fP expansions
12066 enclosed in double quotes.
12067 This option is enabled by default.
12068 .TP 8
12069 .B failglob
12070 If set, patterns which fail to match filenames during pathname expansion
12071 result in an expansion error.
12072 .TP 8
12073 .B force_fignore
12074 If set, the suffixes specified by the
12075 .SM
12076 .B FIGNORE
12077 shell variable
12078 cause words to be ignored when performing word completion even if
12079 the ignored words are the only possible completions.
12080 See
12081 .B "Shell Variables"
12082 .ie \n(zZ=1 in \fIbash\fP(1)
12083 .el above
12084 for a description of
12085 .SM
12086 .BR FIGNORE .
12087 This option is enabled by default.
12088 .TP 8
12089 .B globasciiranges
12090 If set, range expressions used in pattern matching bracket expressions (see
12091 .SM
12092 .B "Pattern Matching"
12093 .ie \n(zZ=1 in \fIbash\fP(1))
12094 .el above)
12095 behave as if in the traditional C locale when performing comparisons.
12096 That is, pattern matching does not take
12097 the current locale's collating sequence into account, so
12098 .B b
12099 will not collate between
12100 .B A
12101 and
12102 .BR B ,
12103 and upper-case and lower-case ASCII characters will collate together.
12104 .TP 8
12105 .B globskipdots
12106 If set, pathname expansion will never match the filenames
12107 .FN .\&
12108 and
12109 .FN ..\& ,
12110 even if the pattern begins with a
12111 .Q .\& .
12112 This option is enabled by default.
12113 .TP 8
12114 .B globstar
12115 If set, the pattern \fB**\fP used in a pathname expansion context will
12116 match all files and zero or more directories and subdirectories.
12117 If the pattern is followed by a \fB/\fP, only directories and
12118 subdirectories match.
12119 .TP 8
12120 .B gnu_errfmt
12121 If set, shell error messages are written in the standard GNU error
12122 message format.
12123 .TP 8
12124 .B histappend
12125 If set, the history list is appended to the file named by the value
12126 of the
12127 .SM
12128 .B HISTFILE
12129 variable when the shell exits, rather than overwriting the file.
12130 .TP 8
12131 .B histreedit
12132 If set, and
12133 .B readline
12134 is being used, the user is given the opportunity to re-edit a
12135 failed history substitution.
12136 .TP 8
12137 .B histverify
12138 If set, and
12139 .B readline
12140 is being used, the results of history substitution are not immediately
12141 passed to the shell parser.
12142 Instead, the resulting line is loaded into the \fBreadline\fP editing buffer,
12143 allowing further modification.
12144 .TP 8
12145 .B hostcomplete
12146 If set, and
12147 .B readline
12148 is being used, \fBbash\fP will attempt to perform hostname completion when a
12149 word containing a \fB@\fP is being completed (see
12150 .B Completing
12151 under
12152 .SM
12153 .B READLINE
12154 .ie \n(zZ=1 in \fIbash\fP(1)).
12155 .el above).
12156 This is enabled by default.
12157 .TP 8
12158 .B huponexit
12159 If set, \fBbash\fP will send
12160 .SM
12161 .B SIGHUP
12162 to all jobs when an interactive login shell exits.
12163 .TP 8
12164 .B inherit_errexit
12165 If set, command substitution inherits the value of the \fBerrexit\fP option,
12166 instead of unsetting it in the subshell environment.
12167 This option is enabled when posix mode is enabled.
12168 .TP 8
12169 .B interactive_comments
12170 In an interactive shell, a word beginning with \fB#\fP
12171 causes that word and all remaining characters on that
12172 line to be ignored, as in a non-interactive shell
12173 (see
12174 .SM
12175 .B COMMENTS
12176 .ie \n(zZ=1 in \fIbash\fP(1)).
12177 .el above).
12178 This option is enabled by default.
12179 .TP 8
12180 .B lastpipe
12181 If set, and job control is not active, the shell runs the last command of
12182 a pipeline not executed in the background in the current shell environment.
12183 .TP 8
12184 .B lithist
12185 If set, and the
12186 .B cmdhist
12187 option is enabled, multi-line commands are saved to the history with
12188 embedded newlines rather than using semicolon separators where possible.
12189 .TP 8
12190 .B localvar_inherit
12191 If set, local variables inherit the value and attributes of a variable of
12192 the same name that exists at a previous scope before any new value is
12193 assigned.
12194 The nameref attribute is not inherited.
12195 .TP 8
12196 .B localvar_unset
12197 If set, calling \fBunset\fP on local variables in previous function scopes
12198 marks them so subsequent lookups find them unset until that function
12199 returns.
12200 This is identical to the behavior of unsetting local variables at the
12201 current function scope.
12202 .TP 8
12203 .B login_shell
12204 The shell sets this option if it is started as a login shell (see
12205 .SM
12206 .B "INVOCATION"
12207 .ie \n(zZ=1 in \fIbash\fP(1)).
12208 .el above).
12209 The value may not be changed.
12210 .TP 8
12211 .B mailwarn
12212 If set, and a file that \fBbash\fP is checking for mail has been
12213 accessed since the last time it was checked,
12214 \fBbash\fP displays the message
12215 .Q "The mail in \fImailfile\fP has been read" .
12216 .TP 8
12217 .B no_empty_cmd_completion
12218 If set, and
12219 .B readline
12220 is being used,
12221 .B bash
12222 does not search
12223 .SM
12224 .B PATH
12225 for possible completions when completion is attempted on an empty line.
12226 .TP 8
12227 .B nocaseglob
12228 If set,
12229 .B bash
12230 matches filenames in a case\-insensitive fashion when performing pathname
12231 expansion (see
12232 .B "Pathname Expansion"
12233 .ie \n(zZ=1 in \fIbash\fP(1)).
12234 .el above).
12235 .TP 8
12236 .B nocasematch
12237 If set,
12238 .B bash
12239 matches patterns in a case\-insensitive fashion when performing matching
12240 while executing \fBcase\fP or \fB[[\fP conditional commands,
12241 when performing pattern substitution word expansions,
12242 or when filtering possible completions as part of programmable completion.
12243 .TP 8
12244 .B noexpand_translation
12245 If set,
12246 .B bash
12247 encloses the translated results of
12248 .BR $\*" .\|.\|.\& \*"
12249 quoting in single quotes instead of double quotes.
12250 If the string is not translated, this has no effect.
12251 .TP 8
12252 .B nullglob
12253 If set, pathname expansion patterns which match no files
12254 (see
12255 .B "Pathname Expansion"
12256 .ie \n(zZ=1 in \fIbash\fP(1))
12257 .el above)
12258 expand to nothing and are removed, rather than expanding to themselves.
12259 .TP 8
12260 .B patsub_replacement
12261 If set, \fBbash\fP
12262 expands occurrences of \fB&\fP in the replacement string of pattern
12263 substitution to the text matched by the pattern, as described
12264 under \fBParameter Expansion\fP
12265 .ie \n(zZ=1 in \fIbash\fP(1).
12266 .el above.
12267 This option is enabled by default.
12268 .TP 8
12269 .B progcomp
12270 If set, enable the programmable completion facilities (see
12271 \fBProgrammable Completion\fP
12272 .ie \n(zZ=1 in \fIbash\fP(1)).
12273 .el above).
12274 This option is enabled by default.
12275 .TP 8
12276 .B progcomp_alias
12277 If set, and programmable completion is enabled, \fBbash\fP treats a command
12278 name that doesn't have any completions as a possible alias and attempts
12279 alias expansion.
12280 If it has an alias, \fBbash\fP attempts programmable
12281 completion using the command word resulting from the expanded alias.
12282 .TP 8
12283 .B promptvars
12284 If set, prompt strings undergo
12285 parameter expansion, command substitution, arithmetic
12286 expansion, and quote removal after being expanded as described in
12287 .SM
12288 .B PROMPTING
12289 .ie \n(zZ=1 in \fIbash\fP(1).
12290 .el above.
12291 This option is enabled by default.
12292 .TP 8
12293 .B restricted_shell
12294 The shell sets this option if it is started in restricted mode
12295 (see
12296 .SM
12297 .B "RESTRICTED SHELL"
12298 .ie \n(zZ=1 in \fIbash\fP(1)).
12299 .el below).
12300 The value may not be changed.
12301 This is not reset when the startup files are executed, allowing
12302 the startup files to discover whether or not a shell is restricted.
12303 .TP 8
12304 .B shift_verbose
12305 If set, the
12306 .B shift
12307 builtin prints an error message when the shift count exceeds the
12308 number of positional parameters.
12309 .TP 8
12310 .B sourcepath
12311 If set, the
12312 \fB.\fP (\fBsource\fP) builtin uses the value of
12313 .SM
12314 .B PATH
12315 to find the directory containing the file supplied as an argument when
12316 the \fB\-p\fP option is not supplied.
12317 This option is enabled by default.
12318 .TP 8
12319 .B varredir_close
12320 If set, the shell automatically closes file descriptors assigned using the
12321 \fI{varname}\fP redirection syntax (see
12322 .SM
12323 .B REDIRECTION
12324 .ie \n(zZ=1 in \fIbash\fP(1))
12325 .el above)
12326 instead of leaving them open when the command completes.
12327 .TP 8
12328 .B xpg_echo
12329 If set, the \fBecho\fP builtin expands backslash-escape sequences
12330 by default.
12331 If the \fBposix\fP shell option is also enabled, \fBecho\fP does not
12332 interpret any options.
12333 .RE
12334 .PD
12335 .TP
12336 \fBsuspend\fP [\fB\-f\fP]
12337 Suspend the execution of this shell until it receives a
12338 .SM
12339 .B SIGCONT
12340 signal.
12341 A login shell, or a shell without job control enabled,
12342 cannot be suspended; the
12343 .B \-f
12344 option will override this and force the suspension.
12345 The return status is 0 unless the shell is a login shell
12346 or job control is not enabled
12347 and
12348 .B \-f
12349 is not supplied.
12350 .TP
12351 \fBtest\fP \fIexpr\fP
12352 .PD 0
12353 .TP
12354 \fB[\fP \fIexpr\fP \fB]\fP
12355 .PD
12356 Return a status of 0 (true) or 1 (false) depending on
12357 the evaluation of the conditional expression
12358 .IR expr .
12359 Each operator and operand must be a separate argument.
12360 Expressions are composed of the primaries described
12361 .ie \n(zZ=1 in \fIbash\fP(1)
12362 .el above
12363 under
12364 .SM
12365 .BR "CONDITIONAL EXPRESSIONS" .
12366 \fBtest\fP does not accept any options, nor does it accept and ignore
12367 an argument of \fB\-\-\fP as signifying the end of options.
12368 .IP
12369 Expressions may be combined using the following operators, listed
12370 in decreasing order of precedence.
12371 The evaluation depends on the number of arguments; see below.
12372 \fBtest\fP uses operator precedence when there are five or more arguments.
12373 .RS
12374 .PD 0
12375 .TP
12376 .B ! \fIexpr\fP
12377 True if
12378 .I expr
12379 is false.
12380 .TP
12381 .B ( \fIexpr\fP )
12382 Returns the value of \fIexpr\fP.
12383 This may be used to override normal operator precedence.
12384 .TP
12385 \fIexpr1\fP \-\fBa\fP \fIexpr2\fP
12386 True if both
12387 .I expr1
12388 and
12389 .I expr2
12390 are true.
12391 .TP
12392 \fIexpr1\fP \-\fBo\fP \fIexpr2\fP
12393 True if either
12394 .I expr1
12395 or
12396 .I expr2
12397 is true.
12398 .PD
12399 .PP
12400 \fBtest\fP and \fB[\fP evaluate conditional
12401 expressions using a set of rules based on the number of arguments.
12402 .PP
12403 .PD 0
12404 .TP
12405 0 arguments
12406 The expression is false.
12407 .TP
12408 1 argument
12409 The expression is true if and only if the argument is not null.
12410 .TP
12411 2 arguments
12412 If the first argument is \fB!\fP, the expression is true if and
12413 only if the second argument is null.
12414 If the first argument is one of the unary conditional operators listed
12415 .ie \n(zZ=1 in \fIbash\fP(1)
12416 .el above
12417 under
12418 .SM
12419 .BR "CONDITIONAL EXPRESSIONS" ,
12420 the expression is true if the unary test is true.
12421 If the first argument is not a valid unary conditional operator, the expression
12422 is false.
12423 .TP
12424 3 arguments
12425 The following conditions are applied in the order listed.
12426 If the second argument is one of the binary conditional operators listed
12427 .ie \n(zZ=1 in \fIbash\fP(1)
12428 .el above
12429 under
12430 .SM
12431 .BR "CONDITIONAL EXPRESSIONS" ,
12432 the result of the expression is the result of the binary test using
12433 the first and third arguments as operands.
12434 The \fB\-a\fP and \fB\-o\fP operators are considered binary operators
12435 when there are three arguments.
12436 If the first argument is \fB!\fP, the value is the negation of
12437 the two-argument test using the second and third arguments.
12438 If the first argument is exactly \fB(\fP and the third argument is
12439 exactly \fB)\fP, the result is the one-argument test of the second
12440 argument.
12441 Otherwise, the expression is false.
12442 .TP
12443 4 arguments
12444 The following conditions are applied in the order listed.
12445 If the first argument is \fB!\fP, the result is the negation of
12446 the three-argument expression composed of the remaining arguments.
12447 If the first argument is exactly \fB(\fP and the fourth argument is
12448 exactly \fB)\fP, the result is the two-argument test of the second
12449 and third arguments.
12450 Otherwise, the expression is parsed and evaluated according to
12451 precedence using the rules listed above.
12452 .TP
12453 5 or more arguments
12454 The expression is parsed and evaluated according to precedence
12455 using the rules listed above.
12456 .PD
12457 .PP
12458 When the shell is in posix mode, or if the expression is part
12459 of the \fB[[\fP command,
12460 the \fB<\fP and \fB>\fP operators sort using the
12461 current locale.
12462 If the shell is not in posix mode, the \fBtest\fP and \fB[\fP
12463 commands sort lexicographically using ASCII ordering.
12464 .PP
12465 The historical operator-precedence parsing with 4 or more arguments can
12466 lead to ambiguities when it encounters strings that look like primaries.
12467 The
12468 .SM POSIX
12469 standard has deprecated the \fB\-a\fP and \fB\-o\fP
12470 primaries and enclosing expressions within parentheses.
12471 Scripts should no longer use them.
12472 It's much more reliable to restrict test invocations to a single primary,
12473 and to replace uses of \fB\-a\fP and \fB\-o\fP with the shell's
12474 \fB&&\fP and \fB||\fP list operators.
12475 .RE
12476 .TP
12477 .B times
12478 Print the accumulated user and system times for the shell and
12479 for processes run from the shell.
12480 The return status is 0.
12481 .TP
12482 \fBtrap\fP [\fB\-lpP\fP] [[\fIaction\fP] \fIsigspec\fP .\|.\|.]
12483 The
12484 .I action
12485 is a command that is read and executed when the shell receives
12486 any of the signals
12487 .IR sigspec .
12488 If
12489 .I action
12490 is absent (and there is a single \fIsigspec\fP) or
12491 .BR \- ,
12492 each specified \fIsigspec\fP is
12493 reset to the value it had when the shell was started.
12494 If
12495 .I action
12496 is the null string the signal specified by each
12497 .I sigspec
12498 is ignored by the shell and by the commands it invokes.
12499 .IP
12500 If no arguments are supplied,
12501 .B trap
12502 displays the actions associated with each trapped signal
12503 as a set of \fBtrap\fP commands
12504 that can be reused as shell input to
12505 restore the current signal dispositions.
12506 If
12507 .B \-p
12508 is given,
12509 and
12510 .I action
12511 is not present,
12512 then \fBtrap\fP displays the actions associated with each
12513 .I sigspec
12514 or, if none are supplied, for all trapped signals,
12515 as a set of \fBtrap\fP commands
12516 that can be reused as shell input to
12517 restore the current signal dispositions.
12518 The
12519 .B \-P
12520 option behaves similarly, but displays only the actions
12521 associated with each \fIsigspec\fP argument.
12522 .B \-P
12523 requires at least one \fIsigspec\fP argument.
12524 The \fB\-P\fP or \fB\-p\fP options may be used
12525 in a subshell environment (e.g., command substitution) and, as
12526 long as they are used before \fBtrap\fP is used to change a signal's
12527 handling, will display the state of its parent's traps.
12528 .IP
12529 The
12530 .B \-l
12531 option prints a list of signal names and
12532 their corresponding numbers.
12533 Each
12534 .I sigspec
12535 is either
12536 a signal name defined in <\fIsignal.h\fP>, or a signal number.
12537 Signal names are case insensitive and the
12538 .SM
12539 .B SIG
12540 prefix is optional.
12541 If \fB\-l\fP is supplied with no \fIsigspec\fP arguments, it prints a
12542 list of valid signal names.
12543 .IP
12544 If a
12545 .I sigspec
12546 is
12547 .SM
12548 .B EXIT
12549 (0),
12550 .I action
12551 is executed on exit from the shell.
12552 If a
12553 .I sigspec
12554 is
12555 .SM
12556 .BR DEBUG ,
12557 .I action
12558 is executed before every \fIsimple command\fP, \fIfor\fP command,
12559 \fIcase\fP command, \fIselect\fP command, (( arithmetic command,
12560 [[ conditional command,
12561 arithmetic \fIfor\fP command, and before the first command executes
12562 in a shell function (see
12563 .SM
12564 .B "SHELL GRAMMAR"
12565 .ie \n(zZ=1 in \fIbash\fP(1)).
12566 .el above).
12567 Refer to the description of the \fBextdebug\fP shell option
12568 (see
12569 .B shopt
12570 .ie \n(zZ=1 in \fIbash\fP(1))
12571 .el above)
12572 for details of its effect on the \fBDEBUG\fP trap.
12573 If a
12574 .I sigspec
12575 is
12576 .SM
12577 .BR RETURN ,
12578 .I action
12579 is executed each time a shell function or a script executed with
12580 the \fB.\fP or \fBsource\fP builtins finishes executing.
12581 .IP
12582 If a
12583 .I sigspec
12584 is
12585 .SM
12586 .BR ERR ,
12587 .I action
12588 is executed whenever
12589 a pipeline (which may consist of a single simple
12590 command), a list, or a compound command returns a
12591 non\-zero exit status,
12592 subject to the following conditions.
12593 The
12594 .SM
12595 .B ERR
12596 trap is not executed if the failed
12597 command is part of the command list immediately following a
12598 .B while
12599 or
12600 .B until
12601 reserved word,
12602 part of the test in an
12603 .I if
12604 statement, part of a command executed in a
12605 .B &&
12606 or
12607 .B ||
12608 list except the command following the final \fB&&\fP or \fB||\fP,
12609 any command in a pipeline but the last
12610 (subject to the state of the \fBpipefail\fP shell option),
12611 or if the command's return value is
12612 being inverted using
12613 .BR ! .
12614 These are the same conditions obeyed by the \fBerrexit\fP (\fB\-e\fP) option.
12615 .IP
12616 When the shell is not interactive,
12617 signals ignored upon entry to the shell cannot be trapped or reset.
12618 Interactive shells permit trapping signals ignored on entry.
12619 Trapped signals that are not being ignored are reset to their original
12620 values in a subshell or subshell environment when one is created.
12621 The return status is false if any
12622 .I sigspec
12623 is invalid; otherwise
12624 .B trap
12625 returns true.
12626 .TP
12627 \fBtrue\fP
12628 Does nothing, returns a 0 status.
12629 .TP
12630 \fBtype\fP [\fB\-aftpP\fP] \fIname\fP [\fIname\fP .\|.\|.]
12631 Indicate how each
12632 .I name
12633 would be interpreted if used as a command name.
12634 .IP
12635 If the
12636 .B \-t
12637 option is used,
12638 .B type
12639 prints a string which is one of
12640 .IR alias ,
12641 .IR keyword ,
12642 .IR function ,
12643 .IR builtin ,
12644 or
12645 .I file
12646 if
12647 .I name
12648 is an alias, shell reserved word, function, builtin, or executable file,
12649 respectively.
12650 If the
12651 .I name
12652 is not found, \fBtype\fP prints nothing and returns a non-zero exit status.
12653 .IP
12654 If the
12655 .B \-p
12656 option is used,
12657 .B type
12658 either returns the pathname of the executable file
12659 that would be found by searching
12660 .B $PATH
12661 for
12662 .I name
12663 or nothing if
12664 .Q "type \-t name"
12665 would not return
12666 .IR file .
12667 The
12668 .B \-P
12669 option forces a
12670 .SM
12671 .B PATH
12672 search for each \fIname\fP, even if
12673 .Q "type \-t name"
12674 would not return
12675 .IR file .
12676 If \fIname\fP is present in the table of hashed commands,
12677 .B \-p
12678 and
12679 .B \-P
12680 print the hashed value, which is not necessarily the file that appears
12681 first in
12682 .SM
12683 .BR PATH .
12684 .IP
12685 If the
12686 .B \-a
12687 option is used,
12688 .B type
12689 prints all of the places that contain a command named
12690 .IR name .
12691 This includes aliases, reserved words, functions, and builtins,
12692 but the path search options (\fB\-p\fP and \fB\-P\fP)
12693 can be supplied to restrict the output to executable files.
12694 \fBtype\fP does not consult the table of hashed commands
12695 when using
12696 .B \-a
12697 with
12698 .BR \-p ,
12699 and only performs a
12700 .SM
12701 .B PATH
12702 search for \fIname\fP.
12703 .IP
12704 The
12705 .B \-f
12706 option suppresses shell function lookup, as with the \fBcommand\fP builtin.
12707 .B type
12708 returns true if all of the arguments are found, false if
12709 any are not found.
12710 .TP
12711 \fBulimit\fP [\fB\-HS\fP] \fB\-a\fP
12712 .PD 0
12713 .TP
12714 \fBulimit\fP [\fB\-HS\fP] [\fB\-bcdefiklmnpqrstuvxPRT\fP [\fIlimit\fP]]
12715 .PD
12716 Provides control over the resources available to the shell and to
12717 processes it starts, on systems that allow such control.
12718 .IP
12719 The \fB\-H\fP and \fB\-S\fP options specify whether
12720 the hard or soft limit is set for the given resource.
12721 A hard limit cannot be increased by a non-root user once it is set;
12722 a soft limit may be increased up to the value of the hard limit.
12723 If neither \fB\-H\fP nor \fB\-S\fP is specified,
12724 \fBulimit\fP sets both the soft and hard limits.
12725 .IP
12726 The value of
12727 .I limit
12728 can be a number in the unit specified for the resource
12729 or one of the special values
12730 .BR hard ,
12731 .BR soft ,
12732 or
12733 .BR unlimited ,
12734 which stand for the current hard limit, the current soft limit, and
12735 no limit, respectively.
12736 If
12737 .I limit
12738 is omitted, \fBulimit\fP prints the current value of the soft limit of
12739 the resource, unless the \fB\-H\fP option is given.
12740 When more than one resource is specified, the limit name and unit,
12741 if appropriate, are printed before the value.
12742 Other options are interpreted as follows:
12743 .RS
12744 .PD 0
12745 .TP
12746 .B \-a
12747 Report all current limits; no limits are set.
12748 .TP
12749 .B \-b
12750 The maximum socket buffer size.
12751 .TP
12752 .B \-c
12753 The maximum size of core files created.
12754 .TP
12755 .B \-d
12756 The maximum size of a process's data segment.
12757 .TP
12758 .B \-e
12759 The maximum scheduling priority (\c
12760 .Q nice ).
12761 .TP
12762 .B \-f
12763 The maximum size of files written by the shell and its children.
12764 .TP
12765 .B \-i
12766 The maximum number of pending signals.
12767 .TP
12768 .B \-k
12769 The maximum number of kqueues that may be allocated.
12770 .TP
12771 .B \-l
12772 The maximum size that may be locked into memory.
12773 .TP
12774 .B \-m
12775 The maximum resident set size (many systems do not honor this limit).
12776 .TP
12777 .B \-n
12778 The maximum number of open file descriptors (most systems do not
12779 allow this value to be set).
12780 .TP
12781 .B \-p
12782 The pipe size in 512-byte blocks (this may not be set).
12783 .TP
12784 .B \-q
12785 The maximum number of bytes in
12786 .SM POSIX
12787 message queues.
12788 .TP
12789 .B \-r
12790 The maximum real-time scheduling priority.
12791 .TP
12792 .B \-s
12793 The maximum stack size.
12794 .TP
12795 .B \-t
12796 The maximum amount of cpu time in seconds.
12797 .TP
12798 .B \-u
12799 The maximum number of processes available to a single user.
12800 .TP
12801 .B \-v
12802 The maximum amount of virtual memory available to the shell and, on
12803 some systems, to its children.
12804 .TP
12805 .B \-x
12806 The maximum number of file locks.
12807 .TP
12808 .B \-P
12809 The maximum number of pseudoterminals.
12810 .TP
12811 .B \-R
12812 The maximum time a real-time process can run before blocking, in microseconds.
12813 .TP
12814 .B \-T
12815 The maximum number of threads.
12816 .PD
12817 .PP
12818 If
12819 .I limit
12820 is supplied, and the
12821 .B \-a
12822 option is not used,
12823 \fIlimit\fP is the new value of the specified resource.
12824 If no option is supplied, then
12825 .B \-f
12826 is assumed.
12827 .PP
12828 Values are in 1024-byte increments, except for
12829 .BR \-t ,
12830 which is in seconds;
12831 .BR \-R ,
12832 which is in microseconds;
12833 .BR \-p ,
12834 which is in units of 512-byte blocks;
12835 .BR \-P ,
12836 .BR \-T ,
12837 .BR \-b ,
12838 .BR \-k ,
12839 .BR \-n ,
12840 and
12841 .BR \-u ,
12842 which are unscaled values;
12843 and, when in posix mode,
12844 .B \-c
12845 and
12846 .BR \-f ,
12847 which are in 512-byte increments.
12848 The return status is 0 unless an invalid option or argument is supplied,
12849 or an error occurs while setting a new limit.
12850 .RE
12851 .TP
12852 \fBumask\fP [\fB\-p\fP] [\fB\-S\fP] [\fImode\fP]
12853 Set the user file-creation mask to
12854 .IR mode .
12855 If
12856 .I mode
12857 begins with a digit, it is interpreted as an octal number;
12858 otherwise it is interpreted as a symbolic mode mask similar
12859 to that accepted by
12860 .IR chmod (1).
12861 If
12862 .I mode
12863 is omitted, \fBumask\fP prints the current value of the mask.
12864 The
12865 .B \-S
12866 option without a \fImode\fP argument
12867 prints the mask in a symbolic format;
12868 the default output is an octal number.
12869 If the
12870 .B \-p
12871 option is supplied, and
12872 .I mode
12873 is omitted, the output is in a form that may be reused as input.
12874 The return status is zero if the mode was successfully changed or
12875 if no \fImode\fP argument was supplied, and non-zero otherwise.
12876 .TP
12877 \fBunalias\fP [\-\fBa\fP] [\fIname\fP .\|.\|.]
12878 Remove each \fIname\fP from the list of defined aliases.
12879 If
12880 .B \-a
12881 is supplied, remove all alias definitions.
12882 The return value is true unless a supplied
12883 .I name
12884 is not a defined alias.
12885 .TP
12886 \fBunset\fP [\-\fBfv\fP] [\-\fBn\fP] [\fIname\fP .\|.\|.]
12887 For each
12888 .IR name ,
12889 remove the corresponding variable or function.
12890 If the
12891 .B \-v
12892 option is given, each
12893 .I name
12894 refers to a shell variable, and that variable is removed.
12895 If
12896 .B \-f
12897 is specified, each
12898 .I name
12899 refers to a shell function, and the function definition
12900 is removed.
12901 If the
12902 .B \-n
12903 option is supplied, and \fIname\fP is a variable with the \fInameref\fP
12904 attribute, \fIname\fP will be unset rather than the variable it
12905 references.
12906 \fB\-n\fP has no effect if the \fB\-f\fP option is supplied.
12907 Read-only variables and functions may not be unset.
12908 When variables or functions are removed, they are also removed
12909 from the environment passed to subsequent commands.
12910 If no options are supplied, each \fIname\fP refers to a variable; if
12911 there is no variable by that name, a function with that name, if any, is
12912 unset.
12913 Some shell variables may not be unset.
12914 If any of
12915 .SM
12916 .BR BASH_ALIASES ,
12917 .SM
12918 .BR BASH_ARGV0 ,
12919 .SM
12920 .BR BASH_CMDS ,
12921 .SM
12922 .BR BASH_COMMAND ,
12923 .SM
12924 .BR BASH_SUBSHELL ,
12925 .SM
12926 .BR BASHPID ,
12927 .SM
12928 .BR COMP_WORDBREAKS ,
12929 .SM
12930 .BR DIRSTACK ,
12931 .SM
12932 .BR EPOCHREALTIME ,
12933 .SM
12934 .BR EPOCHSECONDS ,
12935 .SM
12936 .BR FUNCNAME ,
12937 .SM
12938 .BR GROUPS ,
12939 .SM
12940 .BR HISTCMD ,
12941 .SM
12942 .BR LINENO ,
12943 .SM
12944 .BR RANDOM ,
12945 .SM
12946 .BR SECONDS ,
12947 or
12948 .SM
12949 .B SRANDOM
12950 are unset, they lose their special properties, even if they are
12951 subsequently reset.
12952 The exit status is true unless a
12953 .I name
12954 is readonly or may not be unset.
12955 .TP
12956 \fBwait\fP [\fB\-fn\fP] [\fP\-p\fP \fIvarname\fP] [\fIid\fP .\|.\|.]
12957 Wait for each specified child process \fIid\fP and return the
12958 termination status of the last \fIid\fP.
12959 Each \fIid\fP may be a process ID \fIpid\fP
12960 or a job specification \fIjobspec\fP;
12961 if a jobspec is supplied, \fBwait\fP waits for all processes in the job.
12962 .IP
12963 If no options or \fIid\fPs are supplied,
12964 \fBwait\fP waits for all running background jobs and
12965 the last-executed process substitution,
12966 if its process id is the same as \fB$!\fP,
12967 and the return status is zero.
12968 .IP
12969 If the \fB\-n\fP option is supplied, \fBwait\fP waits for any one of
12970 the given \fIid\fPs or,
12971 if no \fIid\fPs are supplied, any job or process substitution,
12972 to complete and returns its exit status.
12973 If none of the supplied \fIid\fPs is a child of the shell,
12974 or if no \fIid\fPs are supplied and the shell has no unwaited-for children,
12975 the exit status is 127.
12976 .IP
12977 If the \fB\-p\fP option is supplied, \fBwait\fP assigns
12978 the process or job identifier of the job
12979 for which the exit status is returned to the
12980 variable \fIvarname\fP named by the option argument.
12981 The variable,
12982 which cannot be readonly,
12983 will be unset initially, before any assignment.
12984 This is useful only when used with the \fB\-n\fP option.
12985 .IP
12986 Supplying the \fB\-f\fP option, when job control is enabled,
12987 forces \fBwait\fP to wait for each \fIid\fP to terminate before
12988 returning its status, instead of returning when it changes status.
12989 .IP
12990 If none of the \fIid\fPs specify one of the shell's active child
12991 processes, the return status is 127.
12992 If \fBwait\fP is interrupted by a signal,
12993 any \fIvarname\fP will remain unset,
12994 and the return status will be greater
12995 than 128, as described under
12996 .B SIGNALS
12997 .ie \n(zZ=1 in \fIbash\fP(1).
12998 .el above.
12999 Otherwise, the return status is the exit status of the last \fIid\fP.
13000 .SH "SHELL COMPATIBILITY MODE"
13001 Bash-4.0 introduced the concept of a \fIshell compatibility level\fP,
13002 specified as a set of options to the shopt builtin (\c
13003 .BR compat31 ,
13004 .BR compat32 ,
13005 .BR compat40 ,
13006 .BR compat41 ,
13007 and so on).
13008 There is only one current
13009 compatibility level \(em each option is mutually exclusive.
13010 The compatibility level is intended to allow users to select behavior
13011 from previous versions that is incompatible with newer versions
13012 while they migrate scripts to use current features and behavior.
13013 It's intended to be a temporary solution.
13014 .PP
13015 This section does not mention behavior that is standard for a particular
13016 version (e.g., setting \fBcompat32\fP means that quoting the right hand
13017 side of the regexp
13018 matching operator quotes special regexp characters in the word, which is
13019 default behavior in bash-3.2 and subsequent versions).
13020 .PP
13021 If a user enables, say, \fBcompat32\fP, it may affect the behavior of other
13022 compatibility levels up to and including the current compatibility level.
13023 The idea is that each compatibility level controls behavior that changed
13024 in that version of \fBbash\fP,
13025 but that behavior may have been present in earlier versions.
13026 For instance, the change to use locale-based comparisons with the \fB[[\fP
13027 command came in bash-4.1, and earlier versions used ASCII-based comparisons,
13028 so enabling \fBcompat32\fP will enable ASCII-based comparisons as well.
13029 That granularity may not be sufficient for
13030 all uses, and as a result users should employ compatibility levels carefully.
13031 Read the documentation for a particular feature to find out the
13032 current behavior.
13033 .PP
13034 Bash-4.3 introduced a new shell variable:
13035 .SM
13036 .BR BASH_COMPAT .
13037 The value assigned
13038 to this variable (a decimal version number like 4.2, or an integer
13039 corresponding to the \fBcompat\fP\fINN\fP option, like 42) determines the
13040 compatibility level.
13041 .PP
13042 Starting with bash-4.4, \fBbash\fP began deprecating older compatibility
13043 levels.
13044 Eventually, the options will be removed in favor of
13045 .SM
13046 .BR BASH_COMPAT .
13047 .PP
13048 Bash-5.0 was the final version for which there was an individual shopt
13049 option for the previous version.
13050 .SM
13051 .B BASH_COMPAT
13052 is the only mechanism to control the compatibility level
13053 in versions newer than bash-5.0.
13054 .PP
13055 The following table describes the behavior changes controlled by each
13056 compatibility level setting.
13057 The \fBcompat\fP\fINN\fP tag is used as shorthand for setting the
13058 compatibility level
13059 to \fINN\fP using one of the following mechanisms.
13060 For versions prior to bash-5.0, the compatibility level may be set using
13061 the corresponding \fBcompat\fP\fINN\fP shopt option.
13062 For bash-4.3 and later versions, the
13063 .SM
13064 .B BASH_COMPAT
13065 variable is preferred,
13066 and it is required for bash-5.1 and later versions.
13067 .TP
13068 \fBcompat31\fP
13069 .PD 0
13070 .RS
13071 .IP \(bu
13072 Quoting the rhs of the \fB[[\fP command's regexp matching operator (=\*~)
13073 has no special effect.
13074 .RE
13075 .PD
13076 .TP
13077 \fBcompat32\fP
13078 .PD 0
13079 .RS
13080 .IP \(bu
13081 The \fB<\fP and \fB>\fP operators to the \fB[[\fP command do not
13082 consider the current locale when comparing strings; they use ASCII
13083 ordering.
13084 .RE
13085 .PD
13086 .TP
13087 \fBcompat40\fP
13088 .PD 0
13089 .RS
13090 .IP \(bu
13091 The \fB<\fP and \fB>\fP operators to the \fB[[\fP command do not
13092 consider the current locale when comparing strings; they use ASCII
13093 ordering.
13094 \fBBash\fP versions prior to bash-4.1 use ASCII collation and
13095 .IR strcmp (3);
13096 bash-4.1 and later use the current locale's collation sequence and
13097 .IR strcoll (3).
13098 .RE
13099 .PD
13100 .TP
13101 \fBcompat41\fP
13102 .PD 0
13103 .RS
13104 .IP \(bu
13105 In posix mode, \fBtime\fP may be followed by options and still be
13106 recognized as a reserved word (this is
13107 .SM POSIX
13108 interpretation 267).
13109 .IP \(bu
13110 In \fIposix\fP mode, the parser requires that an even number of single
13111 quotes occur in the \fIword\fP portion of a double-quoted
13112 parameter expansion and treats them specially, so that characters within
13113 the single quotes are considered quoted
13114 (this is
13115 .SM POSIX
13116 interpretation 221).
13117 .RE
13118 .PD
13119 .TP
13120 \fBcompat42\fP
13121 .PD 0
13122 .RS
13123 .IP \(bu
13124 The replacement string in double-quoted pattern substitution does not
13125 undergo quote removal, as it does in versions after bash-4.2.
13126 .IP \(bu
13127 In posix mode, single quotes are considered special when expanding
13128 the \fIword\fP portion of a double-quoted parameter expansion
13129 and can be used to quote a closing brace or other special character
13130 (this is part of
13131 .SM POSIX
13132 interpretation 221);
13133 in later versions, single quotes
13134 are not special within double-quoted word expansions.
13135 .RE
13136 .PD
13137 .TP
13138 \fBcompat43\fP
13139 .PD 0
13140 .RS
13141 .IP \(bu
13142 Word expansion errors are considered non-fatal errors that cause the
13143 current command to fail, even in posix mode
13144 (the default behavior is to make them fatal errors that cause the shell
13145 to exit).
13146 .IP \(bu
13147 When executing a shell function, the loop state (while/until/etc.)
13148 is not reset, so \fBbreak\fP or \fBcontinue\fP in that function will break
13149 or continue loops in the calling context.
13150 Bash-4.4 and later reset the loop state to prevent this.
13151 .RE
13152 .PD
13153 .TP
13154 \fBcompat44\fP
13155 .PD 0
13156 .RS
13157 .IP \(bu
13158 The shell sets up the values used by
13159 .SM
13160 .B BASH_ARGV
13161 and
13162 .SM
13163 .B BASH_ARGC
13164 so they can expand to the shell's positional parameters even if extended
13165 debugging mode is not enabled.
13166 .IP \(bu
13167 A subshell inherits loops from its parent context, so \fBbreak\fP
13168 or \fBcontinue\fP will cause the subshell to exit.
13169 Bash-5.0 and later reset the loop state to prevent the exit
13170 .IP \(bu
13171 Variable assignments preceding builtins like \fBexport\fP and \fBreadonly\fP
13172 that set attributes continue to affect variables with the same
13173 name in the calling environment even if the shell is not in posix
13174 mode.
13175 .RE
13176 .PD
13177 .TP
13178 \fBcompat50\fP
13179 .PD 0
13180 .RS
13181 .IP \(bu
13182 Bash-5.1 changed the way
13183 .SM
13184 .B $RANDOM
13185 is generated to introduce slightly more randomness.
13186 If the shell compatibility level is set to 50 or
13187 lower, it reverts to the method from bash-5.0 and previous versions,
13188 so seeding the random number generator by assigning a value to
13189 .SM
13190 .B RANDOM
13191 will produce the same sequence as in bash-5.0.
13192 .IP \(bu
13193 If the command hash table is empty, bash versions prior to bash-5.1
13194 printed an informational message to that effect, even when producing
13195 output that can be reused as input.
13196 Bash-5.1 suppresses that message
13197 when the \fB\-l\fP option is supplied.
13198 .RE
13199 .PD
13200 .TP
13201 \fBcompat51\fP
13202 .PD 0
13203 .RS
13204 .IP \(bu
13205 The \fBunset\fP builtin treats attempts to unset array subscripts \fB@\fP
13206 and \fB*\fP differently depending on whether the array is indexed or
13207 associative, and differently than in previous versions.
13208 .IP \(bu
13209 Arithmetic commands (
13210 .BR (( .\|.\|.\& ))
13211 ) and the expressions in an arithmetic for
13212 statement can be expanded more than once.
13213 .IP \(bu
13214 Expressions used as arguments to arithmetic operators in the \fB[[\fP
13215 conditional command can be expanded more than once.
13216 .IP \(bu
13217 The expressions in substring parameter brace expansion can be
13218 expanded more than once.
13219 .IP \(bu
13220 The expressions in the
13221 .BR $(( .\|.\|.\& ))
13222 word expansion can be expanded more than once.
13223 .IP \(bu
13224 Arithmetic expressions used as indexed array subscripts can be
13225 expanded more than once.
13226 .IP \(bu
13227 \fBtest \-v\fP, when given an argument of \fBA[@]\fP, where \fBA\fP is
13228 an existing associative array, will return true if the array has any set
13229 elements.
13230 Bash-5.2 will look for and report on a key named \fB@\fP.
13231 .IP \(bu
13232 The ${\fIparameter\fP\fB[:]=\fP\fIvalue\fP} word expansion will return
13233 \fIvalue\fP, before any variable-specific transformations have been
13234 performed (e.g., converting to lowercase).
13235 Bash-5.2 will return the final value assigned to the variable.
13236 .IP \(bu
13237 Parsing command substitutions will behave as if extended globbing
13238 (see the description of the
13239 .B shopt
13240 builtin above)
13241 is enabled, so that parsing a command substitution containing an extglob
13242 pattern (say, as part of a shell function) will not fail.
13243 This assumes the intent is to enable extglob before the command is executed
13244 and word expansions are performed.
13245 It will fail at word expansion time if extglob hasn't been
13246 enabled by the time the command is executed.
13247 .RE
13248 .PD
13249 .TP
13250 \fBcompat52\fP
13251 .PD 0
13252 .RS
13253 .IP \(bu
13254 The \fBtest\fP builtin uses its historical algorithm to parse parenthesized
13255 subexpressions when given five or more arguments.
13256 .IP \(bu
13257 If the \fB\-p\fP or \fB\-P\fP option is supplied to the \fBbind\fP builtin,
13258 \fBbind\fP treats any arguments remaining after option processing
13259 as bindable command names, and
13260 displays any key sequences bound to those commands, instead of treating
13261 the arguments as key sequences to bind.
13262 .RE
13263 .PD
13264 .\" bash_builtins
13265 .if \n(zZ=1 .ig zZ
13266 .SH "RESTRICTED SHELL"
13267 .\" rbash.1
13268 .zY
13269 .PP
13270 If
13271 .B bash
13272 is started with the name
13273 .BR rbash ,
13274 or the
13275 .B \-r
13276 option is supplied at invocation, the shell becomes \fIrestricted\fP.
13277 A restricted shell is used to
13278 set up an environment more controlled than the standard shell.
13279 It behaves identically to
13280 .B bash
13281 with the exception that the following are disallowed or not performed:
13282 .IP \(bu
13283 Changing directories with \fBcd\fP.
13284 .IP \(bu
13285 Setting or unsetting the values of
13286 .SM
13287 .BR SHELL ,
13288 .SM
13289 .BR PATH ,
13290 .SM
13291 .BR HISTFILE ,
13292 .SM
13293 .BR ENV ,
13294 or
13295 .SM
13296 .BR BASH_ENV .
13297 .IP \(bu
13298 Specifying command names containing
13299 .BR / .
13300 .IP \(bu
13301 Specifying a filename containing a
13302 .B /
13303 as an argument to the
13304 .B .
13305 builtin command.
13306 .IP \(bu
13307 Using the \fB\-p\fP option to the
13308 .B .
13309 builtin command to specify a search path.
13310 .IP \(bu
13311 Specifying a filename containing a slash as an argument to the
13312 .B history
13313 builtin command.
13314 .IP \(bu
13315 Specifying a filename containing a slash as an argument to the
13316 .B \-p
13317 option to the
13318 .B hash
13319 builtin command.
13320 .IP \(bu
13321 Importing function definitions from the shell environment at startup.
13322 .IP \(bu
13323 Parsing the values of
13324 .SM
13325 .B BASHOPTS
13326 and
13327 .SM
13328 .B SHELLOPTS
13329 from the shell environment at startup.
13330 .IP \(bu
13331 Redirecting output using the >, >|, <>, >&, &>, and >> redirection operators.
13332 .IP \(bu
13333 Using the
13334 .B exec
13335 builtin command to replace the shell with another command.
13336 .IP \(bu
13337 Adding or deleting builtin commands with the
13338 .B \-f
13339 and
13340 .B \-d
13341 options to the
13342 .B enable
13343 builtin command.
13344 .IP \(bu
13345 Using the \fBenable\fP builtin command to enable disabled shell builtins.
13346 .IP \(bu
13347 Specifying the
13348 .B \-p
13349 option to the
13350 .B command
13351 builtin command.
13352 .IP \(bu
13353 Turning off restricted mode with
13354 \fBset +r\fP or \fBshopt \-u restricted_shell\fP.
13355 .PP
13356 These restrictions are enforced after any startup files are read.
13357 .PP
13358 .ie \n(zY=1 When a command that is found to be a shell script is executed,
13359 .el \{ When a command that is found to be a shell script is executed
13360 (see
13361 .SM
13362 .B "COMMAND EXECUTION"
13363 above),
13364 .\}
13365 .B rbash
13366 turns off any restrictions in the shell spawned to execute the
13367 script.
13368 .\" end of rbash.1
13369 .if \n(zY=1 .ig zY
13370 .SH "SEE ALSO"
13371 .PD 0
13372 .TP
13373 \fIBash Reference Manual\fP, Brian Fox and Chet Ramey
13374 .TP
13375 \fIThe Gnu Readline Library\fP, Brian Fox and Chet Ramey
13376 .TP
13377 \fIThe Gnu History Library\fP, Brian Fox and Chet Ramey
13378 .TP
13379 \fIPortable Operating System Interface (POSIX) Part 2: Shell and Utilities\fP, IEEE \(em
13380 http://pubs.opengroup.org/onlinepubs/9799919799/
13381 .TP
13382 http://tiswww.case.edu/\*~chet/bash/POSIX \(em a description of posix mode
13383 .TP
13384 \fIsh\fP(1), \fIksh\fP(1), \fIcsh\fP(1)
13385 .TP
13386 \fIemacs\fP(1), \fIvi\fP(1)
13387 .TP
13388 \fIreadline\fP(3)
13389 .PD
13390 .SH FILES
13391 .PD 0
13392 .TP
13393 .FN /bin/bash
13394 The \fBbash\fP executable
13395 .TP
13396 .FN /etc/profile
13397 The systemwide initialization file, executed for login shells
13398 .TP
13399 .FN \*~/.bash_profile
13400 The personal initialization file, executed for login shells
13401 .TP
13402 .FN \*~/.bashrc
13403 The individual per-interactive-shell startup file
13404 .TP
13405 .FN \*~/.bash_logout
13406 The individual login shell cleanup file, executed when a login shell exits
13407 .TP
13408 .FN \*~/.bash_history
13409 The default value of \fBHISTFILE\fP, the file in which bash saves the
13410 command history
13411 .TP
13412 .FN \*~/.inputrc
13413 Individual \fIreadline\fP initialization file
13414 .PD
13415 .SH AUTHORS
13416 Brian Fox, Free Software Foundation
13417 .br
13418 [email protected]
13419 .PP
13420 Chet Ramey, Case Western Reserve University
13421 .br
13422 [email protected]
13423 .SH BUG REPORTS
13424 If you find a bug in
13425 .BR bash ,
13426 you should report it. But first, you should
13427 make sure that it really is a bug, and that it appears in the latest
13428 version of
13429 .BR bash .
13430 The latest version is always available from
13431 \fIftp://ftp.gnu.org/pub/gnu/bash/\fP and
13432 \fIhttp://git.savannah.gnu.org/cgit/bash.git/snapshot/bash-master.tar.gz\fP.
13433 .PP
13434 Once you have determined that a bug actually exists, use the
13435 .I bashbug
13436 command to submit a bug report.
13437 If you have a fix, you are encouraged to mail that as well!
13438 You may send suggestions and
13439 .Q philosophical
13440 bug reports to \[email protected]\fP or post them to the Usenet
13441 newsgroup
13442 .BR gnu.bash.bug .
13443 .PP
13444 ALL bug reports should include:
13445 .PP
13446 .PD 0
13447 .TP 20
13448 The version number of \fBbash\fP
13449 .TP
13450 The hardware and operating system
13451 .TP
13452 The compiler used to compile
13453 .TP
13454 A description of the bug behavior
13455 .TP
13456 A short script or \c
13457 .Q recipe " \c"
13458 which exercises the bug
13459 .PD
13460 .PP
13461 .I bashbug
13462 inserts the first three items automatically into the template
13463 it provides for filing a bug report.
13464 .PP
13465 Comments and bug reports concerning
13466 this manual page should be directed to
13467 .IR [email protected] .
13468 .SH BUGS
13469 It's too big and too slow.
13470 .PP
13471 There are some subtle differences between
13472 .B bash
13473 and traditional versions of
13474 .BR sh ,
13475 mostly because of the
13476 .SM POSIX
13477 specification.
13478 .PP
13479 Aliases are confusing in some uses.
13480 .PP
13481 Shell builtin commands and functions are not stoppable/restartable.
13482 .PP
13483 Compound commands and command lists of the form
13484 .Q "a ; b ; c"
13485 are not handled gracefully when combined with process suspension.
13486 When a process is stopped, the shell immediately executes the next
13487 command in the list or breaks out of any existing loops.
13488 It suffices to enclose the command in parentheses to
13489 force it into a subshell, which may be stopped as a unit,
13490 or to start the command in the background and immediately
13491 bring it into the foreground.
13492 .PP
13493 Array variables may not (yet) be exported.
13494 .zZ
13495 .zY