Debian Codegraph @

upstream/fedora-44/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 \-\-rpm-requires
280 Produce the list of files that are required for the
281 shell script to run. This implies '-n' and is subject
282 to the same limitations as compile time error checking checking;
283 Command substitutions, Conditional expressions and
284 .BR eval
285 builtin are not parsed so some dependencies may be missed.
286 .TP
287 .B \-\-verbose
288 Equivalent to \fB\-v\fP.
289 .TP
290 .B \-\-version
291 Show version information for this instance of
292 .B bash
293 on the standard output and exit successfully.
294 .SH ARGUMENTS
295 If arguments remain after option processing, and neither the
296 .B \-c
297 nor the
298 .B \-s
299 option has been supplied, the first argument is treated as
300 the name of a file containing shell commands (a \fIshell script\fP).
301 When
302 .B bash
303 is invoked in this fashion,
304 .B $0
305 is set to the name of the file, and the positional parameters
306 are set to the remaining arguments.
307 .B Bash
308 reads and executes commands from this file, then exits.
309 \fBBash\fP's exit status is the exit status of the last command
310 executed in the script.
311 If no commands are executed, the exit status is 0.
312 .B Bash
313 first attempts to open the file in the current directory,
314 and, if no file is found, searches the directories in
315 .SM
316 .B PATH
317 for the script.
318 .SH INVOCATION
319 A \fIlogin shell\fP is one whose first character of argument zero is a
320 .BR \- ,
321 or one started with the
322 .B \-\-login
323 option.
324 .PP
325 An \fIinteractive shell\fP is one started without non-option arguments
326 (unless \fB\-s\fP is specified)
327 and without the
328 .B \-c
329 option,
330 and whose standard input and standard error are
331 both connected to terminals (as determined by
332 .IR isatty (3)),
333 or one started with the
334 .B \-i
335 option.
336 .B Bash
337 sets
338 .SM
339 .B PS1
340 and
341 .B $\-
342 includes
343 .B i
344 if the shell is interactive,
345 so a shell script or a startup file can test this state.
346 .PP
347 The following paragraphs describe how
348 .B bash
349 executes its startup files.
350 If any of the files exist but cannot be read,
351 .B bash
352 reports an error.
353 Tildes are expanded in filenames as described below under
354 .B "Tilde Expansion"
355 in the
356 .SM
357 .B EXPANSION
358 section.
359 .PP
360 When
361 .B bash
362 is invoked as an interactive login shell, or as a non-interactive shell
363 with the \fB\-\-login\fP option, it first reads and
364 executes commands from the file
365 .FN /etc/profile ,
366 if that file exists.
367 After reading that file, it looks for
368 .FN \*~/.bash_profile ,
369 .FN \*~/.bash_login ,
370 and
371 .FN \*~/.profile ,
372 in that order, and reads
373 and executes commands from the first one that exists and is readable.
374 The
375 .B \-\-noprofile
376 option may be used when the shell is started to inhibit this behavior.
377 .PP
378 When an interactive login shell exits,
379 or a non-interactive login shell executes the \fBexit\fP builtin command,
380 .B bash
381 reads and executes commands from the files \fI~/.bash_logout\fP
382 and \fI/etc/bash.bash_logout\fP, if the files exists.
383 .PP
384 When an interactive shell that is not a login shell is started,
385 .B bash
386 reads and executes commands from
387 .FN \*~/.bashrc ,
388 if that file exists.
389 The
390 .B \-\-norc
391 option inhibits this behavior.
392 The \fB\-\-rcfile\fP \fIfile\fP option causes
393 .B bash
394 to use \fIfile\fP instead of
395 .FN \*~/.bashrc .
396 .PP
397 When
398 .B bash
399 is started non-interactively, to run a shell script, for example, it
400 looks for the variable
401 .SM
402 .B BASH_ENV
403 in the environment, expands its value if it appears there, and uses the
404 expanded value as the name of a file to read and execute.
405 .B Bash
406 behaves as if the following command were executed:
407 .PP
408 .RS
409 .EX
410 if [ \-n \*"$BASH_ENV\*" ]; then . \*"$BASH_ENV\*"; fi
411 .EE
412 .RE
413 .PP
414 but does not use the value of the
415 .SM
416 .B PATH
417 variable to search for the filename.
418 .PP
419 If
420 .B bash
421 is invoked with the name
422 .BR sh ,
423 it tries to mimic the startup behavior of historical versions of
424 .B sh
425 as closely as possible,
426 while conforming to the
427 .SM POSIX
428 standard as well.
429 When invoked as an interactive login shell, or a non-interactive
430 shell with the \fB\-\-login\fP option, it first attempts to read
431 and execute commands from
432 .FN /etc/profile
433 and
434 .FN \*~/.profile ,
435 in that order.
436 The
437 .B \-\-noprofile
438 option inhibits this behavior.
439 When invoked as an interactive shell with the name
440 .BR sh ,
441 .B bash
442 looks for the variable
443 .SM
444 .BR ENV ,
445 expands its value if it is defined, and uses the
446 expanded value as the name of a file to read and execute.
447 Since a shell invoked as
448 .B sh
449 does not attempt to read and execute commands from any other startup
450 files, the
451 .B \-\-rcfile
452 option has no effect.
453 A non-interactive shell invoked with the name
454 .B sh
455 does not attempt to read any other startup files.
456 .PP
457 When invoked as
458 .BR sh ,
459 .B bash
460 enters posix mode after reading the startup files.
461 .PP
462 When
463 .B bash
464 is started in posix mode, as with the
465 .B \-\-posix
466 command line option, it follows the
467 .SM POSIX
468 standard for startup files.
469 In this mode, interactive shells expand the
470 .SM
471 .B ENV
472 variable and read and execute commands from the file
473 whose name is the expanded value.
474 No other startup files are read.
475 .PP
476 .B Bash
477 attempts to determine when it is being run with its standard input
478 connected to a network connection, as when executed by
479 the historical and rarely-seen remote shell daemon, usually \fIrshd\fP,
480 or the secure shell daemon \fIsshd\fP.
481 If
482 .B bash
483 determines it is being run non-interactively in this fashion,
484 it reads and executes commands from
485 .FN \*~/.bashrc ,
486 if that file exists and is readable.
487 .B Bash
488 does not read this file if invoked as \fBsh\fP.
489 The
490 .B \-\-norc
491 option inhibits this behavior, and the
492 .B \-\-rcfile
493 option makes \fBbash\fP use a different file instead of
494 .FN \*~/.bashrc ,
495 but neither
496 \fIrshd\fP nor \fIsshd\fP generally invoke the shell with those options
497 or allow them to be specified.
498 .PP
499 If the shell is started with the effective user (group) id not equal to the
500 real user (group) id, and the \fB\-p\fP option is not supplied, no startup
501 files are read, shell functions are not inherited from the environment, the
502 .SM
503 .BR SHELLOPTS ,
504 .SM
505 .BR BASHOPTS ,
506 .SM
507 .BR CDPATH ,
508 and
509 .SM
510 .B GLOBIGNORE
511 variables, if they appear in the environment, are ignored,
512 and the effective user id is set to the real user id.
513 If the \fB\-p\fP option is supplied at invocation, the startup behavior is
514 the same, but the effective user id is not reset.
515 .SH DEFINITIONS
516 The following definitions are used throughout the rest of this
517 document.
518 .PD 0
519 .TP
520 .B blank
521 A space or tab.
522 .TP
523 .B whitespace
524 A character belonging to the \fBspace\fP character class in the
525 current locale, or for which \fIisspace\fP(3) returns true.
526 .TP
527 .B word
528 A sequence of characters considered as a single unit by the shell.
529 Also known as a
530 .BR token .
531 .TP
532 .B name
533 A
534 .I word
535 consisting only of alphanumeric characters and underscores, and
536 beginning with an alphabetic character or an underscore. Also
537 referred to as an
538 .BR identifier .
539 .TP
540 .B metacharacter
541 A character that, when unquoted, separates words.
542 One of the following:
543 .br
544 .RS
545 .PP
546 .if t \fB| & ; ( ) < > space tab newline\fP
547 .if n \fB| & ; ( ) < > space tab newline\fP
548 .RE
549 .TP
550 .B "control operator"
551 A \fItoken\fP that performs a control function.
552 It is one of the following symbols:
553 .RS
554 .PP
555 .if t \fB|| & && ; ;; ;& ;;& ( ) | |& <newline>\fP
556 .if n \fB|| & && ; ;; ;& ;;& ( ) | |& <newline>\fP
557 .RE
558 .PD
559 .SH "RESERVED WORDS"
560 \fIReserved words\fP are words that have a special meaning to the shell.
561 The following words are recognized as reserved when unquoted and either
562 the first word of a command (see
563 .SM
564 .B "SHELL GRAMMAR"
565 below), the third word of a
566 .B case
567 or
568 .B select
569 command
570 (only \fBin\fP is valid), or the third word of a
571 .B for
572 command (only \fBin\fP and \fBdo\fP are valid):
573 .if t .RS
574 .PP
575 .B
576 .if n ! case coproc do done elif else esac fi for function if in select \
577 then until while { } time [[ ]]
578 .if t ! case coproc do done elif else esac fi for function if in select then until while { } time [[ ]]
579 .if t .RE
580 .SH "SHELL GRAMMAR"
581 This section describes the syntax of the various forms of shell commands.
582 .SS Simple Commands
583 A \fIsimple command\fP is a sequence of optional variable assignments
584 followed by \fBblank\fP-separated words and redirections, and
585 terminated by a \fIcontrol operator\fP.
586 The first word
587 specifies the command to be executed, and is passed as argument zero.
588 The remaining words are passed as arguments to the invoked command.
589 .PP
590 The return value of a \fIsimple command\fP is its exit status, or
591 128+\fIn\^\fP if the command is terminated by signal
592 .IR n .
593 .SS Pipelines
594 A \fIpipeline\fP is a sequence of one or more commands separated by
595 one of the control operators
596 .B |
597 or \fB|&\fP.
598 The format for a pipeline is:
599 .RS
600 .PP
601 [\fBtime\fP [\fB\-p\fP]] [ ! ] \fIcommand1\fP [ [\fB|\fP\(bv\fB|&\fP] \fIcommand2\fP .\|.\|.\& ]
602 .RE
603 .PP
604 The standard output of
605 .I command1
606 is connected via a pipe to the standard input of
607 .IR command2 .
608 This connection is performed before any redirections specified by the
609 .IR command1 (see
610 .SM
611 .B REDIRECTION
612 below).
613 If \fB|&\fP is the pipeline operator,
614 \fIcommand1\fP's standard error, in addition to its
615 standard output, is connected to
616 \fIcommand2\fP's standard input through the pipe;
617 it is shorthand for \fB2>&1 |\fP.
618 This implicit redirection of the standard error to the standard output is
619 performed after any redirections specified by \fIcommand1\fP.
620 .PP
621 The return status of a pipeline is the exit status of the last
622 command, unless the \fBpipefail\fP option is enabled.
623 If \fBpipefail\fP is enabled, the pipeline's return status is the
624 value of the last (rightmost) command to exit with a non-zero status,
625 or zero if all commands exit successfully.
626 If the reserved word
627 .B !
628 precedes a pipeline, the exit status of that pipeline is the logical
629 negation of the exit status as described above.
630 If a pipeline is executed synchronously,
631 the shell waits for all commands in the pipeline to
632 terminate before returning a value.
633 .PP
634 If the
635 .B time
636 reserved word precedes a pipeline, the shell reports the
637 elapsed as well as user and system time consumed by its execution
638 when the pipeline terminates.
639 The \fB\-p\fP option changes the output format to that specified by
640 .SM POSIX\c
641 \&.
642 When the shell is in posix mode, it does not recognize
643 \fBtime\fP as a reserved word if the next token begins with a
644 .Q \- .
645 The value of the
646 .SM
647 .B TIMEFORMAT
648 variable is a format string that specifies how the timing
649 information should be displayed; see the description of
650 .SM
651 .B TIMEFORMAT
652 below under
653 .BR "Shell Variables" .
654 .PP
655 When the shell is in posix mode, \fBtime\fP
656 may appear by itself as the only word in a simple command.
657 In this case, the shell displays the
658 total user and system time consumed by the shell and its children.
659 The
660 .SM
661 .B TIMEFORMAT
662 variable specifies the format of the time information.
663 .PP
664 Each command in a multi-command pipeline,
665 where pipes are created,
666 is executed in a \fIsubshell\fP, which is a
667 separate process.
668 See
669 .SM
670 .B "COMMAND EXECUTION ENVIRONMENT"
671 for a description of subshells and a subshell environment.
672 If the \fBlastpipe\fP option is enabled using the \fBshopt\fP builtin
673 (see the description of \fBshopt\fP below),
674 and job control is not active,
675 the last element of a pipeline may be run by the shell process.
676 .SS Lists
677 A \fIlist\fP is a sequence of one or more pipelines separated by one
678 of the operators
679 .BR ; ,
680 .BR & ,
681 .BR && ,
682 or
683 .BR || ,
684 and optionally terminated by one of
685 .BR ; ,
686 .BR & ,
687 or
688 .BR <newline> .
689 .PP
690 Of these list operators,
691 .B &&
692 and
693 .B ||
694 have equal precedence, followed by
695 .B ;
696 and
697 .BR & ,
698 which have equal precedence.
699 .PP
700 A sequence of one or more newlines may appear in a \fIlist\fP instead
701 of a semicolon to delimit commands.
702 .PP
703 If a command is terminated by the control operator
704 .BR & ,
705 the shell executes the command in the \fIbackground\fP
706 in a subshell.
707 The shell does not wait for the command to
708 finish, and the return status is 0.
709 These are referred to as \fIasynchronous\fP commands.
710 Commands separated by a
711 .B ;
712 are executed sequentially; the shell waits for each
713 command to terminate in turn.
714 The return status is the exit status of the last command executed.
715 .PP
716 AND and OR lists are sequences of one or more pipelines separated by the
717 \fB&&\fP and \fB||\fP control operators, respectively.
718 AND and OR lists are executed with left associativity.
719 An AND list has the form
720 .RS
721 .PP
722 \fIcommand1\fP \fB&&\fP \fIcommand2\fP
723 .RE
724 .PP
725 .I command2
726 is executed if, and only if,
727 .I command1
728 returns an exit status of zero (success).
729 .PP
730 An OR list has the form
731 .RS
732 .PP
733 \fIcommand1\fP \fB||\fP \fIcommand2\fP
734 .RE
735 .PP
736 .I command2
737 is executed if, and only if,
738 .I command1
739 returns a non-zero exit status.
740 The return status of
741 AND and OR lists is the exit status of the last command
742 executed in the list.
743 .SS Compound Commands
744 A \fIcompound command\fP is one of the following.
745 In most cases a \fIlist\fP in a command's description may be separated from
746 the rest of the command by one or more newlines, and may be followed by a
747 newline in place of a semicolon.
748 .TP
749 (\fIlist\fP)
750 \fIlist\fP is executed in a subshell (see
751 .SM
752 .B "COMMAND EXECUTION ENVIRONMENT"
753 below for a description of a subshell environment).
754 Variable assignments and builtin
755 commands that affect the shell's environment do not remain in effect
756 after the command completes.
757 The return status is the exit status of \fIlist\fP.
758 .TP
759 { \fIlist\fP; }
760 \fIlist\fP is executed in the current shell environment.
761 \fIlist\fP must be terminated with a newline or semicolon.
762 This is known as a \fIgroup command\fP.
763 The return status is the exit status of \fIlist\fP.
764 .IP
765 Note that unlike the metacharacters \fB(\fP and \fB)\fP, \fB{\fP and
766 \fB}\fP are \fIreserved words\fP and must occur where a reserved
767 word is permitted to be recognized.
768 Since they do not cause a word break, they must be separated from
769 \fIlist\fP by whitespace or another shell metacharacter.
770 .TP
771 ((\fIexpression\fP))
772 The arithmetic \fIexpression\fP is evaluated according to the rules
773 described below under
774 .SM
775 .BR "ARITHMETIC EVALUATION" .
776 If the value of the expression is non-zero, the return status is 0;
777 otherwise the return status is 1.
778 The \fIexpression\fP
779 undergoes the same expansions
780 as if it were within double quotes,
781 but unescaped double quote characters
782 in \fIexpression\fP are not treated
783 specially and are removed.
784 Since this can potentially result in empty strings, this command treats
785 those as expressions that evaluate to 0.
786 .TP
787 \fB[[\fP \fIexpression\fP \fB]]\fP
788 .PD
789 Evaluate the conditional expression \fIexpression\fP
790 and return a status of zero (true) or non-zero (false).
791 Expressions are composed of the primaries described below under
792 .SM
793 .BR "CONDITIONAL EXPRESSIONS" .
794 The words between the \fB[[\fP and \fB]]\fP do not undergo word splitting
795 and pathname expansion.
796 The shell performs tilde expansion, parameter and
797 variable expansion, arithmetic expansion, command substitution, process
798 substitution, and quote removal on those words.
799 Conditional operators such as \fB\-f\fP must be unquoted to be recognized
800 as primaries.
801 .IP
802 When used with \fB[[\fP, the \fB<\fP and \fB>\fP operators sort
803 lexicographically using the current locale.
804 .IP
805 When the \fB==\fP and \fB!=\fP operators are used, the string to the
806 right of the operator is considered a pattern and matched according
807 to the rules described below under \fBPattern Matching\fP,
808 as if the \fBextglob\fP shell option were enabled.
809 The \fB=\fP operator is equivalent to \fB==\fP.
810 If the
811 .B nocasematch
812 shell option is enabled, the match is performed without regard to the case
813 of alphabetic characters.
814 The return value is 0 if the string matches (\fB==\fP) or does not match
815 (\fB!=\fP) the pattern, and 1 otherwise.
816 If any part of the pattern is quoted, the quoted portion is matched
817 as a string: every character in the quoted portion matches itself,
818 instead of having any special pattern matching meaning.
819 .IP
820 An additional binary operator, \fB=\*~\fP, is available, with the same
821 precedence as \fB==\fP and \fB!=\fP.
822 When it is used, the string to the right of the operator is considered
823 a
824 .SM POSIX
825 extended regular expression and matched accordingly
826 (using the
827 .SM POSIX
828 \fIregcomp\fP and \fIregexec\fP interfaces
829 usually described in
830 .IR regex (3)).
831 The return value is 0 if the string matches
832 the pattern, and 1 otherwise.
833 If the regular expression is syntactically incorrect, the conditional
834 expression's return value is 2.
835 If the
836 .B nocasematch
837 shell option is enabled, the match is performed without regard to the case
838 of alphabetic characters.
839 .IP
840 If any part of the pattern is quoted, the quoted portion is matched literally,
841 as above.
842 If the pattern is stored in a shell variable, quoting the variable
843 expansion forces the entire pattern to be matched literally.
844 Treat bracket expressions in regular expressions carefully,
845 since normal quoting and pattern characters lose their meanings
846 between brackets.
847 .IP
848 The match succeeds if the pattern matches any part of the string.
849 Anchor the pattern using the \fB\*^\fP and \fB$\fP regular expression
850 operators to force it to match the entire string.
851 .IP
852 The array variable
853 .SM
854 .B BASH_REMATCH
855 records which parts of the string matched the pattern.
856 The element of
857 .SM
858 .B BASH_REMATCH
859 with index 0 contains the portion of
860 the string matching the entire regular expression.
861 Substrings matched by parenthesized subexpressions within the regular
862 expression are saved in the remaining
863 .SM
864 .B BASH_REMATCH
865 indices.
866 The element of
867 .SM
868 .B BASH_REMATCH
869 with index \fIn\fP is the portion of the
870 string matching the \fIn\fPth parenthesized subexpression.
871 \fBBash\fP sets
872 .SM
873 .B BASH_REMATCH
874 in the global scope; declaring it as a local variable will lead to
875 unexpected results.
876 .IP
877 Expressions may be combined using the following operators, listed
878 in decreasing order of precedence:
879 .IP
880 .RS
881 .PD 0
882 .TP
883 .B ( \fIexpression\fP )
884 Returns the value of \fIexpression\fP.
885 This may be used to override the normal precedence of operators.
886 .TP
887 .B ! \fIexpression\fP
888 True if
889 .I expression
890 is false.
891 .TP
892 \fIexpression1\fP \fB&&\fP \fIexpression2\fP
893 True if both
894 .I expression1
895 and
896 .I expression2
897 are true.
898 .TP
899 \fIexpression1\fP \fB||\fP \fIexpression2\fP
900 True if either
901 .I expression1
902 or
903 .I expression2
904 is true.
905 .PD
906 .LP
907 The \fB&&\fP and \fB||\fP
908 operators do not evaluate \fIexpression2\fP if the value of
909 \fIexpression1\fP is sufficient to determine the return value of
910 the entire conditional expression.
911 .RE
912 .TP
913 \fBfor\fP \fIname\fP [ [ \fBin\fP \fIword .\|.\|.\&\fP ] ; ] \fBdo\fP \fIlist\fP ; \fBdone\fP
914 First, expand The list of words following \fBin\fP, generating a list
915 of items.
916 Then, the variable \fIname\fP is set to each element of this list
917 in turn, and \fIlist\fP is executed each time.
918 If the \fBin\fP \fIword\fP is omitted, the \fBfor\fP command executes
919 \fIlist\fP once for each positional parameter that is set (see
920 .SM
921 .B PARAMETERS
922 below).
923 The return status is the exit status of the last command that executes.
924 If the expansion of the items following \fBin\fP results in an empty
925 list, no commands are executed, and the return status is 0.
926 .TP
927 \fBfor\fP (( \fIexpr1\fP ; \fIexpr2\fP ; \fIexpr3\fP )) [;] \fBdo\fP \fIlist\fP ; \fBdone\fP
928 First, evaluate the arithmetic expression \fIexpr1\fP according
929 to the rules described below under
930 .SM
931 .BR "ARITHMETIC EVALUATION" .
932 Then, repeatedly evaluate the arithmetic expression \fIexpr2\fP
933 until it evaluates to zero.
934 Each time \fIexpr2\fP evaluates to a non-zero value,
935 execute \fIlist\fP
936 and evaluate the arithmetic expression \fIexpr3\fP.
937 If any expression is omitted, it behaves as if it evaluates to 1.
938 The return value is the exit status of the last command in \fIlist\fP
939 that is executed, or non-zero if any of the expressions is invalid.
940 .IP
941 Use the \fBbreak\fP and \fPcontinue\fP builtins
942 (see
943 .SM
944 .B "SHELL BUILTIN COMMANDS"
945 below)
946 to control loop execution.
947 .TP
948 \fBselect\fP \fIname\fP [ \fBin\fP \fIword\fP ] ; \fBdo\fP \fIlist\fP ; \fBdone\fP
949 First, expand the list of words following \fBin\fP,
950 generating a list of items, and print the set of expanded words
951 the standard error, each preceded by a number.
952 If the \fBin\fP
953 \fIword\fP is omitted, print the positional parameters (see
954 .SM
955 .B PARAMETERS
956 below).
957 .B select
958 then displays the
959 .SM
960 .B PS3
961 prompt and reads a line from the standard input.
962 If the line consists of a number corresponding to one of
963 the displayed words, then \fBselect\fP sets the value of
964 .I name
965 to that word.
966 If the line is empty, \fBselect\fP displays the words and prompt again.
967 If EOF is read, \fBselect\fP completes and returns 1.
968 Any other value sets
969 .I name
970 to null.
971 The line read is saved in the variable
972 .SM
973 .BR REPLY .
974 The
975 .I list
976 is executed after each selection until a
977 .B break
978 command is executed.
979 The exit status of
980 .B select
981 is the exit status of the last command executed in
982 .IR list ,
983 or zero if no commands were executed.
984 .TP
985 \fBcase\fP \fIword\fP \fBin\fP [ [(] \fIpattern\fP [ \fB|\fP \fIpattern\fP ] \
986 .\|.\|.\& ) \fIlist\fP ;; ] .\|.\|.\& \
987 \fBesac\fP
988 A \fBcase\fP command first expands \fIword\fP, and tries to match
989 it against each \fIpattern\fP in turn,
990 proceeding from first to last,
991 using the matching rules
992 described under
993 .B "Pattern Matching"
994 below.
995 A pattern list is a set of one or more patterns separated by \|,
996 and the ) operator terminates the pattern list.
997 The \fIword\fP is expanded using tilde
998 expansion, parameter and variable expansion, arithmetic expansion,
999 command substitution, process substitution and quote removal.
1000 Each \fIpattern\fP examined is expanded using tilde
1001 expansion, parameter and variable expansion, arithmetic expansion,
1002 command substitution, process substitution, and quote removal.
1003 If the
1004 .B nocasematch
1005 shell option is enabled, the match is performed without regard to the case
1006 of alphabetic characters.
1007 A \fIclause\fP is a pattern list and an associated \fIlist\fP.
1008 .IP
1009 When a match is found, \fBcase\fP executes the corresponding \fIlist\fP.
1010 If the \fB;;\fP operator terminates the case clause, the \fBcase\fP
1011 command completes after the first match.
1012 Using \fB;&\fP in place of \fB;;\fP causes execution to continue with
1013 the \fIlist\fP associated with the next pattern list.
1014 Using \fB;;&\fP in place of \fB;;\fP causes the shell to test the next
1015 pattern list in the statement, if any, and execute any associated \fIlist\fP
1016 if the match succeeds,
1017 continuing the case statement execution as if the pattern list had not matched.
1018 The exit status is zero if no pattern matches.
1019 .IP
1020 Otherwise, it is the exit status of the
1021 last command executed in the last \fIlist\fP executed.
1022 .TP
1023 \fBif\fP \fIlist\fP; \fBthen\fP \fIlist\fP; \
1024 [ \fBelif\fP \fIlist\fP; \fBthen\fP \fIlist\fP; ] .\|.\|.\& \
1025 [ \fBelse\fP \fIlist\fP; ] \fBfi\fP
1026 The
1027 .B if
1028 .I list
1029 is executed.
1030 If its exit status is zero, the
1031 \fBthen\fP \fIlist\fP is executed.
1032 Otherwise, each \fBelif\fP \fIlist\fP is executed in turn,
1033 and if its exit status is zero, the corresponding \fBthen\fP \fIlist\fP
1034 is executed and the command completes.
1035 Otherwise, the \fBelse\fP \fIlist\fP is executed, if present.
1036 The exit status is the exit status of the
1037 last command executed, or zero if no condition tested true.
1038 .TP
1039 \fBwhile\fP \fIlist-1\fP; \fBdo\fP \fIlist-2\fP; \fBdone\fP
1040 .PD 0
1041 .TP
1042 \fBuntil\fP \fIlist-1\fP; \fBdo\fP \fIlist-2\fP; \fBdone\fP
1043 .PD
1044 The \fBwhile\fP command continuously executes the list
1045 \fIlist-2\fP as long as the last command in the list \fIlist-1\fP returns
1046 an exit status of zero.
1047 The \fBuntil\fP command is identical
1048 to the \fBwhile\fP command, except that the test is negated:
1049 .I list-2
1050 is executed as long as the last command in
1051 .I list-1
1052 returns a non-zero exit status.
1053 The exit status of the \fBwhile\fP and \fBuntil\fP commands
1054 is the exit status
1055 of the last command executed in \fIlist-2\fP, or zero if
1056 none was executed.
1057 .SS Coprocesses
1058 A \fIcoprocess\fP is a shell command preceded by the \fBcoproc\fP reserved
1059 word.
1060 A coprocess is executed asynchronously in a subshell, as if the command
1061 had been terminated with the \fB&\fP control operator, with a two-way pipe
1062 established between the executing shell and the coprocess.
1063 .PP
1064 The syntax for a coprocess is:
1065 .RS
1066 .PP
1067 \fBcoproc\fP [\fINAME\fP] \fIcommand\fP [\fIredirections\fP]
1068 .RE
1069 .PP
1070 This creates a coprocess named \fINAME\fP.
1071 \fIcommand\fP may be either a simple command or a compound
1072 command (see above).
1073 \fINAME\fP is a shell variable name.
1074 If \fINAME\fP is not supplied, the default name is \fBCOPROC\fP.
1075 .PP
1076 The recommended form to use for a coprocess is
1077 .RS
1078 .PP
1079 \fBcoproc\fP \fINAME\fP { \fIcommand\fP [\fIredirections\fP]; }
1080 .RE
1081 .PP
1082 This form is preferred because simple commands result in the coprocess
1083 always being named \fBCOPROC\fP, and it is simpler to use and more complete
1084 than the other compound commands.
1085 .PP
1086 If \fIcommand\fP is a compound command, \fINAME\fP is optional. The
1087 word following \fBcoproc\fP determines whether that word is interpreted
1088 as a variable name: it is interpreted as \fINAME\fP if it is not a
1089 reserved word that introduces a compound command.
1090 If \fIcommand\fP is a simple command, \fINAME\fP is not allowed; this
1091 is to avoid confusion between \fINAME\fP and the first word of the simple
1092 command.
1093 .PP
1094 When the coprocess is executed, the shell creates an array variable (see
1095 .B Arrays
1096 below) named \fINAME\fP in the context of the executing shell.
1097 The standard output of
1098 .I command
1099 is connected via a pipe to a file descriptor in the executing shell,
1100 and that file descriptor is assigned to \fINAME\fP[0].
1101 The standard input of
1102 .I command
1103 is connected via a pipe to a file descriptor in the executing shell,
1104 and that file descriptor is assigned to \fINAME\fP[1].
1105 This pipe is established before any redirections specified by the
1106 command (see
1107 .SM
1108 .B REDIRECTION
1109 below).
1110 The file descriptors can be utilized as arguments to shell commands
1111 and redirections using standard word expansions.
1112 Other than those created to execute command and process substitutions,
1113 the file descriptors are not available in subshells.
1114 .PP
1115 The process ID of the shell spawned to execute the coprocess is
1116 available as the value of the variable \fINAME\fP_PID.
1117 The \fBwait\fP
1118 builtin may be used to wait for the coprocess to terminate.
1119 .PP
1120 Since the coprocess is created as an asynchronous command,
1121 the \fBcoproc\fP command always returns success.
1122 The return status of a coprocess is the exit status of \fIcommand\fP.
1123 .SS Shell Function Definitions
1124 A shell function is an object that is called like a simple command and
1125 executes a compound command with a new set of positional parameters.
1126 Shell functions are declared as follows:
1127 .TP
1128 \fIfname\fP () \fIcompound\-command\fP [\fIredirection\fP]
1129 .PD 0
1130 .TP
1131 \fBfunction\fP \fIfname\fP [()] \fIcompound\-command\fP [\fIredirection\fP]
1132 .PD
1133 This defines a function named \fIfname\fP.
1134 The reserved word \fBfunction\fP is optional.
1135 If the \fBfunction\fP reserved word is supplied, the parentheses are optional.
1136 The \fIbody\fP of the function is the compound command
1137 .I compound\-command
1138 (see \fBCompound Commands\fP above).
1139 That command is usually a \fIlist\fP of commands between { and }, but
1140 may be any command listed under \fBCompound Commands\fP above.
1141 If the \fBfunction\fP reserved word is used, but the
1142 parentheses are not supplied, the braces are recommended.
1143 \fIcompound\-command\fP is executed whenever \fIfname\fP is specified as the
1144 name of a simple command.
1145 When in posix mode, \fIfname\fP must be a valid shell \fIname\fP
1146 and may not be the name of one of the
1147 .SM POSIX
1148 \fIspecial builtins\fP.
1149 In default mode, a function name can be any unquoted shell word that does
1150 not contain \fB$\fP.
1151 .PP
1152 Any redirections (see
1153 .SM
1154 .B REDIRECTION
1155 below) specified when a function is defined are performed
1156 when the function is executed.
1157 .PP
1158 The exit status of a function definition is zero unless a syntax error
1159 occurs or a readonly function with the same name already exists.
1160 When executed, the exit status of a function is the exit status of the
1161 last command executed in the body. (See
1162 .SM
1163 .B FUNCTIONS
1164 below.)
1165 .SH COMMENTS
1166 In a non-interactive shell, or an interactive shell in which the
1167 .B interactive_comments
1168 option to the
1169 .B shopt
1170 builtin is enabled (see
1171 .SM
1172 .B "SHELL BUILTIN COMMANDS"
1173 below), a word beginning with
1174 .B #
1175 introduces a comment.
1176 A word begins at the beginning of a line, after unquoted whitespace, or
1177 after an operator.
1178 The comment causes that word and all remaining characters on that line to
1179 be ignored.
1180 An interactive shell without the
1181 .B interactive_comments
1182 option enabled does not allow comments.
1183 The
1184 .B interactive_comments
1185 option is enabled by default in interactive shells.
1186 .SH QUOTING
1187 \fIQuoting\fP is used to remove the special meaning of certain
1188 characters or words to the shell.
1189 Quoting can be used to
1190 disable special treatment for special characters, to prevent
1191 reserved words from being recognized as such, and to prevent
1192 parameter expansion.
1193 .PP
1194 Each of the \fImetacharacters\fP listed above under
1195 .SM
1196 .B DEFINITIONS
1197 has special meaning to the shell and must be quoted if it is to
1198 represent itself.
1199 .PP
1200 When the command history expansion facilities are being used
1201 (see
1202 .SM
1203 .B "HISTORY EXPANSION"
1204 below), the
1205 \fIhistory expansion\fP character, usually \fB!\fP, must be quoted
1206 to prevent history expansion.
1207 .PP
1208 There are four quoting mechanisms: the
1209 .IR "escape character" ,
1210 single quotes, double quotes,
1211 and dollar-single quotes.
1212 .PP
1213 A non-quoted backslash (\fB\e\fP) is the
1214 .IR "escape character" .
1215 It preserves the literal value of the next character that follows,
1216 removing any special meaning it has,
1217 with the exception of <newline>.
1218 If a \fB\e\fP<newline> pair appears, and the backslash is not itself quoted,
1219 the \fB\e\fP<newline> is treated as a line continuation (that is, it is
1220 removed from the input stream and effectively ignored).
1221 .PP
1222 Enclosing characters in single quotes preserves the literal value
1223 of each character within the quotes.
1224 A single quote may not occur
1225 between single quotes, even when preceded by a backslash.
1226 .PP
1227 Enclosing characters in double quotes preserves the literal value
1228 of all characters within the quotes, with the exception of
1229 .BR $ ,
1230 .BR \` ,
1231 .BR \e ,
1232 and, when history expansion is enabled,
1233 .BR ! .
1234 When the shell is in posix mode,
1235 the \fB!\fP has no special meaning
1236 within double quotes, even when history expansion is enabled.
1237 The characters
1238 .B $
1239 and
1240 .B \`
1241 retain their special meaning within double quotes.
1242 The backslash retains its special meaning only when followed by one of
1243 the following characters:
1244 .BR $ ,
1245 .BR \` ,
1246 \^\fB\*"\fP\^,
1247 .BR \e ,
1248 or
1249 .BR <newline> .
1250 Backslashes preceding characters without a
1251 special meaning are left unmodified.
1252 .PP
1253 A double quote may be quoted within double quotes by preceding it with
1254 a backslash.
1255 If enabled, history expansion will be performed unless an
1256 .B !
1257 appearing in double quotes is escaped using a backslash.
1258 The backslash preceding the
1259 .B !
1260 is not removed.
1261 .PP
1262 The special parameters
1263 .B *
1264 and
1265 .B @
1266 have special meaning when in double quotes
1267 (see
1268 .SM
1269 .B PARAMETERS
1270 below).
1271 .PP
1272 Character sequences of the form \fB$\fP\*'\fIstring\fP\*' are treated
1273 as a special variant of single quotes.
1274 The sequence expands to \fIstring\fP, with backslash-escaped characters
1275 in \fIstring\fP replaced as specified by the ANSI C standard.
1276 Backslash escape sequences, if present, are decoded as follows:
1277 .RS
1278 .PD 0
1279 .TP
1280 .B \ea
1281 alert (bell)
1282 .TP
1283 .B \eb
1284 backspace
1285 .TP
1286 .B \ee
1287 .TP
1288 .B \eE
1289 an escape character
1290 .TP
1291 .B \ef
1292 form feed
1293 .TP
1294 .B \en
1295 new line
1296 .TP
1297 .B \er
1298 carriage return
1299 .TP
1300 .B \et
1301 horizontal tab
1302 .TP
1303 .B \ev
1304 vertical tab
1305 .TP
1306 .B \e\e
1307 backslash
1308 .TP
1309 .B \e\*'
1310 single quote
1311 .TP
1312 .B \e\*"
1313 double quote
1314 .TP
1315 .B \e?
1316 question mark
1317 .TP
1318 .B \e\fInnn\fP
1319 The eight-bit character whose value is the octal value \fInnn\fP
1320 (one to three octal digits).
1321 .TP
1322 .B \ex\fIHH\fP
1323 The eight-bit character whose value is the hexadecimal value \fIHH\fP
1324 (one or two hex digits).
1325 .TP
1326 .B \eu\fIHHHH\fP
1327 The Unicode (ISO/IEC 10646) character whose value is the hexadecimal value
1328 \fIHHHH\fP (one to four hex digits).
1329 .TP
1330 .B \eU\fIHHHHHHHH\fP
1331 The Unicode (ISO/IEC 10646) character whose value is the hexadecimal value
1332 \fIHHHHHHHH\fP (one to eight hex digits).
1333 .TP
1334 .B \ec\fIx\fP
1335 A control-\fIx\fP character.
1336 .PD
1337 .RE
1338 .LP
1339 The expanded result is single-quoted, as if the dollar sign had
1340 not been present.
1341 .SS "Translating Strings"
1342 A double-quoted string preceded by a dollar sign (\fB$\fP\*"\fIstring\fP\*")
1343 causes the string to be translated according to the current locale.
1344 The \fIgettext\fP infrastructure performs the lookup and
1345 translation, using the \fBLC_MESSAGES\fP, \fBTEXTDOMAINDIR\fP,
1346 and \fBTEXTDOMAIN\fP shell variables.
1347 If the current locale is \fBC\fP or \fBPOSIX\fP,
1348 if there are no translations available,
1349 or if the string is not translated, the dollar sign is ignored,
1350 and the string is treated as double-quoted as described above.
1351 This is a form of double quoting, so the string remains double-quoted
1352 by default, whether or not it is translated and replaced.
1353 If the \fBnoexpand_translation\fP option is enabled
1354 using the \fBshopt\fP builtin,
1355 translated strings are single-quoted instead of double-quoted.
1356 See the description of
1357 .B shopt
1358 below under
1359 .SM
1360 .BR "SHELL BUILTIN COMMANDS" .
1361 .SH PARAMETERS
1362 A
1363 .I parameter
1364 is an entity that stores values.
1365 It can be a
1366 .IR name ,
1367 a number, or one of the special characters listed below under
1368 .BR "Special Parameters" .
1369 A
1370 .I variable
1371 is a parameter denoted by a
1372 .IR name .
1373 A variable has a \fIvalue\fP and zero or more \fIattributes\fP.
1374 Attributes are assigned using the
1375 .B declare
1376 builtin command (see
1377 .B declare
1378 below in
1379 .SM
1380 .BR "SHELL BUILTIN COMMANDS" ).
1381 The \fBexport\fP and \fBreadonly\fP builtins assign specific attributes.
1382 .PP
1383 A parameter is set if it has been assigned a value.
1384 The null string is a valid value.
1385 Once a variable is set, it may be unset only by using the
1386 .B unset
1387 builtin command (see
1388 .SM
1389 .B "SHELL BUILTIN COMMANDS"
1390 below).
1391 .PP
1392 A
1393 .I variable
1394 is assigned to using a statement of the form
1395 .RS
1396 .PP
1397 \fIname\fP=[\fIvalue\fP]
1398 .RE
1399 .PP
1400 If
1401 .I value
1402 is not given, the variable is assigned the null string.
1403 All
1404 .I values
1405 undergo tilde expansion, parameter and variable expansion,
1406 command substitution, arithmetic expansion, and quote
1407 removal (see
1408 .SM
1409 .B EXPANSION
1410 below).
1411 If the variable has its
1412 .B integer
1413 attribute set, then
1414 .I value
1415 is evaluated as an arithmetic expression even if the
1416 .BR $(( .\|.\|.\& ))
1417 expansion is not used (see
1418 .B "Arithmetic Expansion"
1419 below).
1420 Word splitting and pathname expansion are not performed.
1421 Assignment statements may also appear as arguments to the
1422 .BR alias ,
1423 .BR declare ,
1424 .BR typeset ,
1425 .BR \%export ,
1426 .BR readonly ,
1427 and
1428 .B local
1429 builtin commands (\fIdeclaration\fP commands).
1430 When in posix mode, these builtins may appear in a command after
1431 one or more instances of the \fBcommand\fP builtin and retain these
1432 assignment statement properties.
1433 .PP
1434 In the context where an assignment statement is assigning a value
1435 to a shell variable or array index, the
1436 .Q +=
1437 operator appends to or adds to
1438 the variable's previous value.
1439 This includes arguments to \fIdeclaration\fP commands such as
1440 .B \%declare
1441 that accept assignment statements.
1442 When
1443 .Q +=
1444 is applied to a variable for which the
1445 .B \%integer
1446 attribute has been set,
1447 the variable's current value and \fIvalue\fP are each evaluated as
1448 arithmetic expressions,
1449 and the sum of the results is assigned as the variable's value.
1450 The current value is usually an integer constant, but may be an expression.
1451 When
1452 .Q +=
1453 is applied to an array variable using compound assignment
1454 (see
1455 .B Arrays
1456 below),
1457 the variable's value is not unset
1458 (as it is when using
1459 .Q = ),
1460 and new values are appended to the array
1461 beginning at one greater than the array's maximum index (for indexed arrays)
1462 or added as additional key\-value pairs in an associative array.
1463 When applied to a string-valued variable, \fIvalue\fP is expanded and
1464 appended to the variable's value.
1465 .PP
1466 A variable can be assigned the \fInameref\fP attribute using the
1467 \fB\-n\fP option to the \fBdeclare\fP or \fBlocal\fP builtin commands
1468 (see the descriptions of \fBdeclare\fP and \fBlocal\fP below)
1469 to create a \fInameref\fP, or a reference to another variable.
1470 This allows variables to be manipulated indirectly.
1471 Whenever the nameref variable is referenced, assigned to, unset, or has
1472 its attributes modified (other than using or changing the \fInameref\fP
1473 attribute itself), the
1474 operation is actually performed on the variable specified by the nameref
1475 variable's value.
1476 A nameref is commonly used within shell functions to refer to a variable
1477 whose name is passed as an argument to the function.
1478 For instance, if a variable name is passed to a shell function as its first
1479 argument, running
1480 .PP
1481 .RS
1482 .EX
1483 declare \-n ref=$1
1484 .EE
1485 .RE
1486 .PP
1487 inside the function creates a local nameref variable \fBref\fP whose value
1488 is the variable name passed as the first argument.
1489 References and assignments to \fBref\fP, and changes to its attributes,
1490 are treated as references, assignments, and attribute modifications
1491 to the variable whose name was passed as \fB$1\fP.
1492 If the control variable in a \fBfor\fP loop has the nameref attribute,
1493 the list of words can be a list of shell variables, and a name reference
1494 is established for each word in the list, in turn, when the loop is
1495 executed.
1496 Array variables cannot be given the \fBnameref\fP attribute.
1497 However, nameref variables can reference array variables and subscripted
1498 array variables.
1499 Namerefs can be unset using the \fB\-n\fP option to the \fBunset\fP builtin.
1500 Otherwise, if \fBunset\fP is executed with the name of a nameref variable
1501 as an argument, the variable referenced by the nameref variable is unset.
1502 .PP
1503 When the shell starts, it reads its environment and creates a shell
1504 variable from each environment variable that has a valid name,
1505 as described below
1506 (see
1507 .SM
1508 .BR ENVIRONMENT ).
1509 .SS Positional Parameters
1510 A
1511 .I positional parameter
1512 is a parameter denoted by one or more
1513 digits, other than the single digit 0.
1514 Positional parameters are
1515 assigned from the shell's arguments when it is invoked,
1516 and may be reassigned using the
1517 .B set
1518 builtin command.
1519 Positional parameters may not be assigned to
1520 with assignment statements.
1521 The positional parameters are
1522 temporarily replaced when a shell function is executed (see
1523 .SM
1524 .B FUNCTIONS
1525 below).
1526 .PP
1527 When a positional parameter consisting of more than a single
1528 digit is expanded, it must be enclosed in braces (see
1529 .SM
1530 .B EXPANSION
1531 below).
1532 Without braces, a digit following $ can only refer to
1533 one of the first nine positional parameters (\fB$1\-$9\fP) or the
1534 special parameter \fB$0\fP (see the next section).
1535 .SS Special Parameters
1536 The shell treats several parameters specially.
1537 These parameters may only be referenced; assignment to them is
1538 not allowed.
1539 Special parameters are denoted by one of the following characters.
1540 .TP
1541 .PD 0
1542 .B *
1543 (\fB$*\fP) Expands to the positional parameters, starting from one.
1544 When the expansion is not within double quotes, each positional parameter
1545 expands to a separate word.
1546 In contexts where word expansions are performed, those words
1547 are subject to further word splitting and pathname expansion.
1548 When the expansion occurs within double quotes, it expands to a
1549 single word with the value of each parameter separated by the first
1550 character of the
1551 .SM
1552 .B IFS
1553 variable.
1554 That is,
1555 .B \*"$*\*"
1556 is equivalent to
1557 .BR \*"$1\fIc\fP$2\fIc\fP.\|.\|.\*" ,
1558 where
1559 .I c
1560 is the first character of the value of the
1561 .SM
1562 .B IFS
1563 variable.
1564 If
1565 .SM
1566 .B IFS
1567 is unset, the parameters are separated by spaces.
1568 If
1569 .SM
1570 .B IFS
1571 is null, the parameters are joined without intervening separators.
1572 .TP
1573 .B @
1574 (\fB$@\fP) Expands to the positional parameters, starting from one.
1575 In contexts where word splitting is performed, this expands each
1576 positional parameter to a separate word; if not within double
1577 quotes, these words are subject to word splitting.
1578 In contexts where word splitting is not performed,
1579 such as the value portion of an assignment statement,
1580 this expands to a single word
1581 with each positional parameter separated by a space.
1582 When the expansion occurs within double quotes,
1583 and word splitting is performed,
1584 each parameter expands to a separate word.
1585 That is,
1586 .B \&\*"$@\*"
1587 is equivalent to
1588 .B \&\*"\&$1\&\*"\ \*"$2\*"\ .\|.\|.
1589 If the double-quoted expansion occurs within a word, the expansion of
1590 the first parameter is joined with the expansion of the
1591 beginning part of the original word,
1592 and the expansion of the last parameter is joined with the
1593 expansion of the last part of the original word.
1594 When there are no positional parameters,
1595 .B \&\*"$@\*"
1596 and
1597 .B $@
1598 expand to nothing (i.e., they are removed).
1599 .TP
1600 .B #
1601 (\fB$#\fP) Expands to the number of positional parameters in decimal.
1602 .TP
1603 .B ?
1604 (\fB$?\fP) Expands to the exit status of the most recently executed command.
1605 .TP
1606 .B \-
1607 (\fB$\-\fP) Expands to the current option flags as specified upon invocation,
1608 by the
1609 .B set
1610 builtin command, or those set by the shell itself
1611 (such as the
1612 .B \-i
1613 option).
1614 .TP
1615 .B $
1616 (\fB$$\fP) Expands to the process ID of the shell.
1617 In a subshell, it expands to the process ID of the parent shell,
1618 not the subshell.
1619 .TP
1620 .B !
1621 (\fB$!\fP)Expands to the process ID of the job most recently placed into the
1622 background, whether executed as an asynchronous command or using
1623 the \fBbg\fP builtin (see
1624 .SM
1625 .B "JOB CONTROL"
1626 below).
1627 .TP
1628 .B 0
1629 (\fB$0\fP) Expands to the name of the shell or shell script.
1630 This is set at shell initialization.
1631 If \fBbash\fP is invoked with a file of commands,
1632 .B $0
1633 is set to the name of that file.
1634 If \fBbash\fP is started with the
1635 .B \-c
1636 option, then
1637 .B $0
1638 is set to the first argument after the string to be
1639 executed, if one is present.
1640 Otherwise, it is set to the filename used to invoke
1641 .BR bash ,
1642 as given by argument zero.
1643 .PD
1644 .SS "Shell Variables"
1645 The shell sets following variables:
1646 .PP
1647 .PD 0
1648 .TP
1649 .B _
1650 (\fB$_\fP, an underscore)
1651 This has a number of meanings depending on context.
1652 At shell startup, \fB_\fP is set to the pathname used to invoke the
1653 shell or shell script being executed as passed in the environment
1654 or argument list.
1655 Subsequently, it expands to the last argument to the previous simple
1656 command executed in the foreground, after expansion.
1657 It is also set to the full pathname used to invoke each command executed
1658 and placed in the environment exported to that command.
1659 When checking mail, \fB$_\fP expands to the name of the mail file
1660 currently being checked.
1661 .TP
1662 .B BASH
1663 Expands to the full filename used to invoke this instance of
1664 .BR bash .
1665 .TP
1666 .B BASHOPTS
1667 A colon-separated list of enabled shell options. Each word in
1668 the list is a valid argument for the
1669 .B \-s
1670 option to the
1671 .B shopt
1672 builtin command (see
1673 .SM
1674 .B "SHELL BUILTIN COMMANDS"
1675 below).
1676 The options appearing in
1677 .SM
1678 .B BASHOPTS
1679 are those reported as
1680 .I on
1681 by \fBshopt\fP.
1682 If this variable is in the environment when
1683 .B bash
1684 starts up, the shell enables each option in the list before
1685 reading any startup files.
1686 If this variable is exported, child shells will enable each option
1687 in the list.
1688 This variable is read-only.
1689 .TP
1690 .B BASHPID
1691 Expands to the process ID of the current \fBbash\fP process.
1692 This differs from \fB$$\fP under certain circumstances, such as subshells
1693 that do not require \fBbash\fP to be re-initialized.
1694 Assignments to
1695 .SM
1696 .B BASHPID
1697 have no effect.
1698 If
1699 .SM
1700 .B BASHPID
1701 is unset, it loses its special properties, even if it is
1702 subsequently reset.
1703 .TP
1704 .B BASH_ALIASES
1705 An associative array variable whose members correspond to the internal
1706 list of aliases as maintained by the \fBalias\fP builtin.
1707 Elements added to this array appear in the alias list; however,
1708 unsetting array elements currently does not remove aliases
1709 from the alias list.
1710 If
1711 .SM
1712 .B BASH_ALIASES
1713 is unset, it loses its special properties, even if it is
1714 subsequently reset.
1715 .TP
1716 .B BASH_ARGC
1717 An array variable whose values are the number of parameters in each
1718 frame of the current \fBbash\fP execution call stack.
1719 The number of parameters to the current subroutine (shell function or
1720 script executed with \fB.\fP or \fBsource\fP) is at the top of the stack.
1721 When a subroutine is executed, the number of parameters passed is pushed onto
1722 .SM
1723 .BR BASH_ARGC .
1724 The shell sets
1725 .SM
1726 .B BASH_ARGC
1727 only when in extended debugging mode (see the description of the
1728 .B extdebug
1729 option to the
1730 .B shopt
1731 builtin below).
1732 Setting \fBextdebug\fP after the shell has started to execute a script,
1733 or referencing this variable when \fBextdebug\fP is not set,
1734 may result in inconsistent values.
1735 Assignments to
1736 .SM
1737 .B BASH_ARGC
1738 have no effect, and it may not be unset.
1739 .TP
1740 .B BASH_ARGV
1741 An array variable containing all of the parameters in the current \fBbash\fP
1742 execution call stack.
1743 The final parameter of the last subroutine call is at the top of the stack;
1744 the first parameter of the initial call is at the bottom.
1745 When a subroutine is executed, the shell pushes the supplied parameters onto
1746 .SM
1747 .BR BASH_ARGV .
1748 The shell sets
1749 .SM
1750 .B BASH_ARGV
1751 only when in extended debugging mode
1752 (see the description of the
1753 .B extdebug
1754 option to the
1755 .B shopt
1756 builtin below).
1757 Setting \fBextdebug\fP after the shell has started to execute a script,
1758 or referencing this variable when \fBextdebug\fP is not set,
1759 may result in inconsistent values.
1760 Assignments to
1761 .SM
1762 .B BASH_ARGV
1763 have no effect, and it may not be unset.
1764 .TP
1765 .B BASH_ARGV0
1766 When referenced, this variable expands to the name of the shell or shell
1767 script (identical to
1768 .BR $0 ;
1769 see the description of special parameter 0 above).
1770 Assigning a value to
1771 .SM
1772 .B BASH_ARGV0
1773 sets \fB$0\fP to the same value.
1774 If
1775 .SM
1776 .B BASH_ARGV0
1777 is unset, it loses its special properties, even if it is
1778 subsequently reset.
1779 .TP
1780 .B BASH_CMDS
1781 An associative array variable whose members correspond to the internal
1782 hash table of commands as maintained by the \fBhash\fP builtin.
1783 Adding elements to this array makes them appear in the hash table; however,
1784 unsetting array elements currently does not remove command names
1785 from the hash table.
1786 If
1787 .SM
1788 .B BASH_CMDS
1789 is unset, it loses its special properties, even if it is
1790 subsequently reset.
1791 .TP
1792 .B BASH_COMMAND
1793 Expands to the command currently being executed or about to be executed,
1794 unless the shell is executing a command as the result of a trap,
1795 in which case it is the command executing at the time of the trap.
1796 If
1797 .SM
1798 .B BASH_COMMAND
1799 is unset, it loses its special properties, even if it is
1800 subsequently reset.
1801 .TP
1802 .B BASH_EXECUTION_STRING
1803 The command argument to the \fB\-c\fP invocation option.
1804 .TP
1805 .B BASH_LINENO
1806 An array variable whose members are the line numbers in source files
1807 where each corresponding member of
1808 .SM
1809 .B FUNCNAME
1810 was invoked.
1811 \fB${BASH_LINENO[\fP\fI$i\fP\fB]}\fP
1812 is the line number in the source file
1813 (\fB${BASH_SOURCE[\fP\fI$i+1\fP\fB]}\fP)
1814 where
1815 \fB${FUNCNAME[\fP\fI$i\fP\fB]}\fP
1816 was called
1817 (or \fB${BASH_LINENO[\fP\fI$i\-1\fP\fB]}\fP if referenced within another
1818 shell function).
1819 Use
1820 .SM
1821 .B LINENO
1822 to obtain the current line number.
1823 Assignments to
1824 .SM
1825 .B BASH_LINENO
1826 have no effect, and it may not be unset.
1827 .TP
1828 .B BASH_LOADABLES_PATH
1829 A colon-separated list of directories in which the
1830 .B enable
1831 command
1832 looks for
1833 dynamically loadable builtins.
1834 .TP
1835 .B BASH_MONOSECONDS
1836 Each time this variable is referenced, it expands to the value returned
1837 by the system's monotonic clock, if one is available.
1838 If there is no monotonic clock, this is equivalent to \fBEPOCHSECONDS\fP.
1839 If
1840 .SM
1841 .B BASH_MONOSECONDS
1842 is unset, it loses its special properties, even if it is
1843 subsequently reset.
1844 .TP
1845 .B BASH_REMATCH
1846 An array variable whose members are assigned by the \fB=\*~\fP binary
1847 operator to the \fB[[\fP conditional command.
1848 The element with index 0 is the portion of the string
1849 matching the entire regular expression.
1850 The element with index \fIn\fP is the portion of the
1851 string matching the \fIn\fPth parenthesized subexpression.
1852 .TP
1853 .B BASH_SOURCE
1854 An array variable whose members are the source filenames
1855 where the corresponding shell function names in the
1856 .SM
1857 .B FUNCNAME
1858 array variable are defined.
1859 The shell function
1860 \fB${FUNCNAME[\fP\fI$i\fP\fB]}\fP is defined in the file
1861 \fB${BASH_SOURCE[\fP\fI$i\fP\fB]}\fP and called from
1862 \fB${BASH_SOURCE[\fP\fI$i+1\fP\fB]}\fP.
1863 Assignments to
1864 .SM
1865 .B BASH_SOURCE
1866 have no effect, and it may not be unset.
1867 .TP
1868 .B BASH_SUBSHELL
1869 Incremented by one within each subshell or subshell environment when
1870 the shell begins executing in that environment.
1871 The initial value is 0.
1872 If
1873 .SM
1874 .B BASH_SUBSHELL
1875 is unset, it loses its special properties, even if it is
1876 subsequently reset.
1877 .TP
1878 .B BASH_TRAPSIG
1879 Set to the signal number corresponding to the trap action being executed
1880 during its execution.
1881 See the description of \fBtrap\fP under
1882 .SM
1883 .B "SHELL BUILTIN COMMANDS"
1884 below for information about signal numbers and trap execution.
1885 .TP
1886 .B BASH_VERSINFO
1887 A readonly array variable whose members hold version information for
1888 this instance of
1889 .BR bash .
1890 The values assigned to the array members are as follows:
1891 .PP
1892 .RS
1893 .TP 24
1894 .B BASH_VERSINFO[\fR0\fP]
1895 The major version number (the \fIrelease\fP).
1896 .TP
1897 .B BASH_VERSINFO[\fR1\fP]
1898 The minor version number (the \fIversion\fP).
1899 .TP
1900 .B BASH_VERSINFO[\fR2\fP]
1901 The patch level.
1902 .TP
1903 .B BASH_VERSINFO[\fR3\fP]
1904 The build version.
1905 .TP
1906 .B BASH_VERSINFO[\fR4\fP]
1907 The release status (e.g., \fIbeta\fP).
1908 .TP
1909 .B BASH_VERSINFO[\fR5\fP]
1910 The value of
1911 .SM
1912 .BR MACHTYPE .
1913 .RE
1914 .TP
1915 .B BASH_VERSION
1916 Expands to a string describing the version of this instance of
1917 .B bash
1918 (e.g., 5.2.37(3)-release).
1919 .TP
1920 .B COMP_CWORD
1921 An index into \fB${COMP_WORDS}\fP of the word containing the current
1922 cursor position.
1923 This variable is available only in shell functions invoked by the
1924 programmable completion facilities (see \fBProgrammable Completion\fP
1925 below).
1926 .TP
1927 .B COMP_KEY
1928 The key (or final key of a key sequence) used to invoke the current
1929 completion function.
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_LINE
1936 The current command line.
1937 This variable is available only in shell functions and external
1938 commands invoked by the
1939 programmable completion facilities (see \fBProgrammable Completion\fP
1940 below).
1941 .TP
1942 .B COMP_POINT
1943 The index of the current cursor position relative to the beginning of
1944 the current command.
1945 If the current cursor position is at the end of the current command,
1946 the value of this variable is equal to \fB${#COMP_LINE}\fP.
1947 This variable is available only in shell functions and external
1948 commands invoked by the
1949 programmable completion facilities (see \fBProgrammable Completion\fP
1950 below).
1951 .TP
1952 .B COMP_TYPE
1953 Set to an integer value corresponding to the type of attempted completion
1954 that caused a completion function to be called:
1955 \fITAB\fP, for normal completion,
1956 \fI?\fP, for listing completions after successive tabs,
1957 \fI!\fP, for listing alternatives on partial word completion,
1958 \fI@\fP, to list completions if the word is not unmodified,
1959 or
1960 \fI%\fP, for menu completion.
1961 This variable is available only in shell functions and external
1962 commands invoked by the
1963 programmable completion facilities (see \fBProgrammable Completion\fP
1964 below).
1965 .TP
1966 .B COMP_WORDBREAKS
1967 The set of characters that the \fBreadline\fP library treats as word
1968 separators when performing word completion.
1969 If
1970 .SM
1971 .B COMP_WORDBREAKS
1972 is unset, it loses its special properties, even if it is
1973 subsequently reset.
1974 .TP
1975 .B COMP_WORDS
1976 An array variable (see \fBArrays\fP below) consisting of the individual
1977 words in the current command line.
1978 The line is split into words as \fBreadline\fP would split it, using
1979 .SM
1980 .B COMP_WORDBREAKS
1981 as described above.
1982 This variable is available only in shell functions invoked by the
1983 programmable completion facilities (see \fBProgrammable Completion\fP
1984 below).
1985 .TP
1986 .B COPROC
1987 An array variable (see \fBArrays\fP below) created to hold the file descriptors
1988 for output from and input to an unnamed coprocess (see \fBCoprocesses\fP
1989 above).
1990 .TP
1991 .B DIRSTACK
1992 An array variable (see
1993 .B Arrays
1994 below) containing the current contents of the directory stack.
1995 Directories appear in the stack in the order they are displayed by the
1996 .B dirs
1997 builtin.
1998 Assigning to members of this array variable may be used to modify
1999 directories already in the stack, but the
2000 .B pushd
2001 and
2002 .B popd
2003 builtins must be used to add and remove directories.
2004 Assigning to this variable does not change the current directory.
2005 If
2006 .SM
2007 .B DIRSTACK
2008 is unset, it loses its special properties, even if it is
2009 subsequently reset.
2010 .TP
2011 .B EPOCHREALTIME
2012 Each time this parameter is referenced, it expands to the number of seconds
2013 since the Unix Epoch (see
2014 .IR time (3))
2015 as a floating-point value with micro-second granularity.
2016 Assignments to
2017 .SM
2018 .B EPOCHREALTIME
2019 are ignored.
2020 If
2021 .SM
2022 .B EPOCHREALTIME
2023 is unset, it loses its special properties, even if it is
2024 subsequently reset.
2025 .TP
2026 .B EPOCHSECONDS
2027 Each time this parameter is referenced, it expands to the number of seconds
2028 since the Unix Epoch (see
2029 .IR time (3)).
2030 Assignments to
2031 .SM
2032 .B EPOCHSECONDS
2033 are ignored.
2034 If
2035 .SM
2036 .B EPOCHSECONDS
2037 is unset, it loses its special properties, even if it is
2038 subsequently reset.
2039 .TP
2040 .B EUID
2041 Expands to the effective user ID of the current user, initialized at
2042 shell startup. This variable is readonly.
2043 .TP
2044 .B FUNCNAME
2045 .PD
2046 An array variable containing the names of all shell functions
2047 currently in the execution call stack.
2048 The element with index 0 is the name of any currently-executing
2049 shell function.
2050 The bottom-most element (the one with the highest index) is
2051 .Q main .
2052 This variable exists only when a shell function is executing.
2053 Assignments to
2054 .SM
2055 .B FUNCNAME
2056 have no effect.
2057 If
2058 .SM
2059 .B FUNCNAME
2060 is unset, it loses its special properties, even if it is
2061 subsequently reset.
2062 .IP
2063 This variable can be used with
2064 .SM
2065 .B BASH_LINENO
2066 and
2067 .SM
2068 .BR BASH_SOURCE .
2069 Each element of
2070 .SM
2071 .B \%FUNCNAME
2072 has corresponding elements in
2073 .SM
2074 .B BASH_LINENO
2075 and
2076 .SM
2077 .B BASH_SOURCE
2078 to describe the call stack.
2079 For instance,
2080 \fB\%${FUNCNAME[\fP\fI$i\fP\fB]}\fP
2081 was called from the file
2082 \fB${BASH_SOURCE[\fP\fI$i+1\fP\fB]}\fP
2083 at line number
2084 \fB${BASH_LINENO[\fP\fI$i\fP\fB]}\fP.
2085 The \fBcaller\fP builtin displays the current call stack using this
2086 information.
2087 .PD 0
2088 .TP
2089 .B GROUPS
2090 An array variable containing the list of groups of which the current
2091 user is a member.
2092 Assignments to
2093 .SM
2094 .B GROUPS
2095 have no effect.
2096 If
2097 .SM
2098 .B GROUPS
2099 is unset, it loses its special properties, even if it is
2100 subsequently reset.
2101 .TP
2102 .B HISTCMD
2103 The history number, or index in the history list, of the current
2104 command.
2105 Assignments to
2106 .SM
2107 .B HISTCMD
2108 have no effect.
2109 If
2110 .SM
2111 .B HISTCMD
2112 is unset, it loses its special properties, even if it is
2113 subsequently reset.
2114 .TP
2115 .B HOSTNAME
2116 Automatically set to the name of the current host.
2117 .TP
2118 .B HOSTTYPE
2119 Automatically set to a string that uniquely
2120 describes the type of machine on which
2121 .B bash
2122 is executing.
2123 The default is system-dependent.
2124 .TP
2125 .B LINENO
2126 Each time this parameter is referenced, the shell substitutes
2127 a decimal number representing the current sequential line number
2128 (starting with 1) within a script or function.
2129 When not in a script or function, the value substituted is not
2130 guaranteed to be meaningful.
2131 If
2132 .SM
2133 .B LINENO
2134 is unset, it loses its special properties, even if it is
2135 subsequently reset.
2136 .TP
2137 .B MACHTYPE
2138 Automatically set to a string that fully describes the system
2139 type on which
2140 .B bash
2141 is executing, in the standard GNU \fIcpu-company-system\fP format.
2142 The default is system-dependent.
2143 .TP
2144 .B MAPFILE
2145 An array variable (see \fBArrays\fP below) created to hold the text
2146 read by the \fBmapfile\fP builtin when no variable name is supplied.
2147 .TP
2148 .B OLDPWD
2149 The previous working directory as set by the
2150 .B cd
2151 command.
2152 .TP
2153 .B OPTARG
2154 The value of the last option argument processed by the
2155 .B getopts
2156 builtin command (see
2157 .SM
2158 .B "SHELL BUILTIN COMMANDS"
2159 below).
2160 .TP
2161 .B OPTIND
2162 The index of the next argument to be processed by the
2163 .B getopts
2164 builtin command (see
2165 .SM
2166 .B "SHELL BUILTIN COMMANDS"
2167 below).
2168 .TP
2169 .B OSTYPE
2170 Automatically set to a string that
2171 describes the operating system on which
2172 .B bash
2173 is executing.
2174 The default is system-dependent.
2175 .TP
2176 .B PIPESTATUS
2177 An array variable (see
2178 .B Arrays
2179 below) containing a list of exit status values from the commands
2180 in the most-recently-executed foreground pipeline, which may
2181 consist of only a simple command
2182 (see
2183 .SM
2184 .B "SHELL GRAMMAR"
2185 above).
2186 \fBBash\fP sets
2187 .SM
2188 .B PIPESTATUS
2189 after executing multi-element pipelines,
2190 timed and negated pipelines,
2191 simple commands,
2192 subshells created with the ( operator,
2193 the
2194 .B [[
2195 and
2196 .B ((
2197 compound commands, and
2198 after error conditions that result in the
2199 shell aborting command execution.
2200 .TP
2201 .B PPID
2202 The process ID of the shell's parent.
2203 This variable is readonly.
2204 .TP
2205 .B PWD
2206 The current working directory as set by the
2207 .B cd
2208 command.
2209 .TP
2210 .B RANDOM
2211 Each time this parameter is referenced, it expands to a random integer
2212 between 0 and 32767.
2213 Assigning a value to
2214 .SM
2215 .B RANDOM
2216 initializes (seeds) the sequence of random numbers.
2217 Seeding the random number generator with the same constant value
2218 produces the same sequence of values.
2219 If
2220 .SM
2221 .B RANDOM
2222 is unset, it loses its special properties, even if it is
2223 subsequently reset.
2224 .TP
2225 .B READLINE_ARGUMENT
2226 Any numeric argument given to a
2227 .B \%readline
2228 command that was defined using
2229 .Q "bind \-x"
2230 (see
2231 .SM
2232 .B "SHELL BUILTIN COMMANDS"
2233 below)
2234 when it was invoked.
2235 .TP
2236 .B READLINE_LINE
2237 The contents of the
2238 .B readline
2239 line buffer, for use with
2240 .Q "bind \-x"
2241 (see
2242 .SM
2243 .B "SHELL BUILTIN COMMANDS"
2244 below).
2245 .TP
2246 .B READLINE_MARK
2247 The position of the mark (saved insertion point) in the
2248 .B readline
2249 line buffer, for use with
2250 .Q "bind \-x"
2251 (see
2252 .SM
2253 .B "SHELL BUILTIN COMMANDS"
2254 below).
2255 The characters between the insertion point and the mark are often
2256 called the \fIregion\fP.
2257 .TP
2258 .B READLINE_POINT
2259 The position of the insertion point in the
2260 .B readline
2261 line buffer, for use with
2262 .Q "bind \-x"
2263 (see
2264 .SM
2265 .B "SHELL BUILTIN COMMANDS"
2266 below).
2267 .TP
2268 .B REPLY
2269 Set to the line of input read by the
2270 .B read
2271 builtin command when no arguments are supplied.
2272 .TP
2273 .B SECONDS
2274 Each time this parameter is
2275 referenced, it expands to the number of seconds since shell invocation.
2276 If a value is assigned to
2277 .SM
2278 .BR SECONDS ,
2279 the value returned upon subsequent
2280 references is
2281 the number of seconds since the assignment plus the value assigned.
2282 The number of seconds at shell invocation and the current time are always
2283 determined by querying the system clock at one-second resolution.
2284 If
2285 .SM
2286 .B SECONDS
2287 is unset, it loses its special properties, even if it is
2288 subsequently reset.
2289 .TP
2290 .B SHELLOPTS
2291 A colon-separated list of enabled shell options.
2292 Each word in the list is a valid argument for the
2293 .B \-o
2294 option to the
2295 .B set
2296 builtin command (see
2297 .SM
2298 .B "SHELL BUILTIN COMMANDS"
2299 below).
2300 The options appearing in
2301 .SM
2302 .B SHELLOPTS
2303 are those reported as
2304 .I on
2305 by \fBset \-o\fP.
2306 If this variable is in the environment when
2307 .B bash
2308 starts up, the shell enables each option in the list before
2309 reading any startup files.
2310 If this variable is exported, child shells will enable each option
2311 in the list.
2312 This variable is read-only.
2313 .TP
2314 .B SHLVL
2315 Incremented by one each time an instance of
2316 .B bash
2317 is started.
2318 .TP
2319 .B SRANDOM
2320 Each time it is referenced, this variable expands to a 32-bit pseudo-random
2321 number.
2322 The random number generator is not linear on systems that
2323 support
2324 .FN /dev/urandom
2325 or
2326 .IR arc4random (3),
2327 so each returned number
2328 has no relationship to the numbers preceding it.
2329 The random number generator cannot be seeded, so assignments to this
2330 variable have no effect.
2331 If
2332 .SM
2333 .B SRANDOM
2334 is unset, it loses its special properties,
2335 even if it is subsequently reset.
2336 .TP
2337 .B UID
2338 Expands to the user ID of the current user, initialized at shell startup.
2339 This variable is readonly.
2340 .PD
2341 .PP
2342 The shell uses the following variables. In some cases,
2343 .B bash
2344 assigns a default value to a variable; these cases are noted
2345 below.
2346 .PP
2347 .PD 0
2348 .TP
2349 .B BASH_COMPAT
2350 The value is used to set the shell's compatibility level.
2351 See
2352 .SM
2353 .B "SHELL COMPATIBILITY MODE"
2354 below for a description of the various compatibility
2355 levels and their effects.
2356 The value may be a decimal number (e.g., 4.2) or an integer (e.g., 42)
2357 corresponding to the desired compatibility level.
2358 If
2359 .SM
2360 .B BASH_COMPAT
2361 is unset or set to the empty string, the compatibility
2362 level is set to the default for the current version.
2363 If
2364 .SM
2365 .B BASH_COMPAT
2366 is set to a value that is not one of the valid
2367 compatibility levels, the shell prints an error message and sets the
2368 compatibility level to the default for the current version.
2369 A subset of the valid values correspond to the compatibility levels
2370 described below under
2371 .SM
2372 .BR "SHELL COMPATIBILITY MODE" .
2373 For example, 4.2 and 42 are valid values that correspond
2374 to the \fBcompat42\fP \fBshopt\fP option
2375 and set the compatibility level to 42.
2376 The current version is also a valid value.
2377 .TP
2378 .B BASH_ENV
2379 If this parameter is set when \fBbash\fP is executing a shell script,
2380 its expanded value is interpreted as a filename containing commands to
2381 initialize the shell before it reads and executes commands from the
2382 script.
2383 The value of
2384 .SM
2385 .B BASH_ENV
2386 is subjected to parameter expansion, command substitution, and arithmetic
2387 expansion before being interpreted as a filename.
2388 .SM
2389 .B PATH
2390 is not used to search for the resultant filename.
2391 .TP
2392 .B BASH_XTRACEFD
2393 If set to an integer corresponding to a valid file descriptor,
2394 \fBbash\fP writes the trace output generated when
2395 .Q "set \-x"
2396 is enabled to that file descriptor,
2397 instead of the standard error.
2398 The file descriptor is closed when
2399 .SM
2400 .B BASH_XTRACEFD
2401 is unset or assigned a new value.
2402 Unsetting
2403 .SM
2404 .B BASH_XTRACEFD
2405 or assigning it the empty string causes the
2406 trace output to be sent to the standard error.
2407 Note that setting
2408 .SM
2409 .B BASH_XTRACEFD
2410 to 2 (the standard error file
2411 descriptor) and then unsetting it will result in the standard error
2412 being closed.
2413 .TP
2414 .B CDPATH
2415 The search path for the
2416 .B cd
2417 command.
2418 This is a colon-separated list of directories where the shell looks for
2419 directories specified as arguments to the
2420 .B cd
2421 command.
2422 A sample value is
2423 .Q .:\*~:/usr .
2424 .TP
2425 .B CHILD_MAX
2426 Set the number of exited child status values for the shell to remember.
2427 \fBBash\fP will not allow this value to be decreased below a
2428 .SM POSIX\c
2429 -mandated minimum,
2430 and there is a maximum value (currently 8192) that this may not exceed.
2431 The minimum value is system-dependent.
2432 .TP
2433 .B COLUMNS
2434 Used by the \fBselect\fP compound command to determine the terminal width
2435 when printing selection lists.
2436 Automatically set if the
2437 .B checkwinsize
2438 option is enabled or in an interactive shell upon receipt of a
2439 .SM
2440 .BR SIGWINCH .
2441 .TP
2442 .B COMPREPLY
2443 An array variable from which \fBbash\fP reads the possible completions
2444 generated by a shell function invoked by the programmable completion
2445 facility (see \fBProgrammable Completion\fP below).
2446 Each array element contains one possible completion.
2447 .TP
2448 .B EMACS
2449 If \fBbash\fP finds this variable in the environment when the shell starts
2450 with value
2451 .Q t ,
2452 it assumes that the shell is running in an Emacs shell buffer and disables
2453 line editing.
2454 .TP
2455 .B ENV
2456 Expanded and executed similarly to
2457 .SM
2458 .B BASH_ENV
2459 (see
2460 .SM
2461 .B INVOCATION
2462 above) when an interactive shell is invoked in posix mode.
2463 .TP
2464 .B EXECIGNORE
2465 A colon-separated list of shell patterns (see \fBPattern Matching\fP)
2466 defining the set of filenames to be ignored by command search using
2467 .SM
2468 .BR PATH .
2469 Files whose full pathnames match one of these patterns are not considered
2470 executable files for the purposes of completion and command execution
2471 via
2472 .SM
2473 .B PATH
2474 lookup.
2475 This does not affect the behavior of the \fB[\fP, \fBtest\fP, and \fB[[\fP
2476 commands.
2477 Full pathnames in the command hash table are not subject to
2478 .SM
2479 .BR EXECIGNORE .
2480 Use this variable to ignore shared library files that have the executable
2481 bit set, but are not executable files.
2482 The pattern matching honors the setting of the \fBextglob\fP shell
2483 option.
2484 .TP
2485 .B FCEDIT
2486 The default editor for the
2487 .B fc
2488 builtin command.
2489 .TP
2490 .B FIGNORE
2491 A colon-separated list of suffixes to ignore when performing
2492 filename completion (see
2493 .SM
2494 .B READLINE
2495 below).
2496 A filename whose suffix matches one of the entries in
2497 .SM
2498 .B FIGNORE
2499 is excluded from the list of matched filenames.
2500 A sample value is
2501 .Q .o:\*~ .
2502 .TP
2503 .B FUNCNEST
2504 If set to a numeric value greater than 0, defines a maximum function
2505 nesting level.
2506 Function invocations that exceed this nesting level
2507 cause the current command to abort.
2508 .TP
2509 .B GLOBIGNORE
2510 A colon-separated list of patterns defining the set of file names to
2511 be ignored by pathname expansion.
2512 If a file name matched by a pathname expansion pattern also matches one
2513 of the patterns in
2514 .SM
2515 .BR GLOBIGNORE ,
2516 it is removed from the list of matches.
2517 The pattern matching honors the setting of the \fBextglob\fP shell
2518 option.
2519 .TP
2520 .B GLOBSORT
2521 .PD
2522 Controls how the results of pathname expansion are sorted.
2523 The value of this variable specifies the sort criteria and sort order for
2524 the results of pathname expansion.
2525 If this variable is unset or set to the null string, pathname expansion
2526 uses the historical behavior of sorting by name,
2527 in ascending lexicographic order as determined by the
2528 .SM
2529 .B \%LC_COLLATE
2530 shell variable.
2531 .IP
2532 If set, a valid value begins with an optional \fI+\fP, which is ignored,
2533 or \fI\-\fP, which reverses the sort order from ascending to descending,
2534 followed by a sort specifier.
2535 The valid sort specifiers are
2536 .IR name ,
2537 .IR \%numeric ,
2538 .IR size ,
2539 .IR mtime ,
2540 .IR atime ,
2541 .IR ctime ,
2542 and
2543 .IR blocks ,
2544 which sort the files on name,
2545 names in numeric rather than lexicographic order,
2546 file size, modification time, access time,
2547 inode change time, and number of blocks, respectively.
2548 If any of the non-name keys compare as equal (e.g., if two files are
2549 the same size), sorting uses the name as a secondary sort key.
2550 .IP
2551 For example, a value of \fI\-mtime\fP sorts the results in descending
2552 order by modification time (newest first).
2553 .IP
2554 The \fInumeric\fP specifier treats names consisting solely of digits as
2555 numbers and sorts them using their numeric value
2556 (so
2557 .Q 2
2558 sorts before
2559 .Q 10 ,
2560 for example).
2561 When using \fInumeric\fP, names containing non-digits sort after all
2562 the all-digit names and are sorted by name using the traditional behavior.
2563 .IP
2564 A sort specifier of \fInosort\fP disables sorting completely;
2565 .B bash
2566 returns the results
2567 in the order they are read from the file system,
2568 ignoring any leading \fI\-\fP.
2569 .IP
2570 If the sort specifier is missing, it defaults to \fIname\fP,
2571 so a value of \fI+\fP is equivalent to the null string,
2572 and a value of \fI-\fP sorts by name in descending order.
2573 Any invalid value restores the historical sorting behavior.
2574 .PD 0
2575 .TP
2576 .B HISTCONTROL
2577 A colon-separated list of values controlling how commands are saved on
2578 the history list.
2579 If the list of values includes
2580 .IR ignorespace ,
2581 lines which begin with a
2582 .B space
2583 character are not saved in the history list.
2584 A value of
2585 .I ignoredups
2586 causes lines matching the previous history entry not to be saved.
2587 A value of
2588 .I ignoreboth
2589 is shorthand for \fIignorespace\fP and \fIignoredups\fP.
2590 A value of
2591 .I erasedups
2592 causes all previous lines matching the current line to be removed from
2593 the history list before that line is saved.
2594 Any value not in the above list is ignored.
2595 If
2596 .SM
2597 .B HISTCONTROL
2598 is unset, or does not include a valid value,
2599 \fBbash\fP saves all lines read by the shell parser on the history list,
2600 subject to the value of
2601 .SM
2602 .BR HISTIGNORE .
2603 If the first line of a multi-line compound command was saved,
2604 the second and subsequent lines are not tested,
2605 and are added to the history regardless of the value of
2606 .SM
2607 .BR HISTCONTROL .
2608 If the first line was not saved, the second and subsequent lines of
2609 the command are not saved either.
2610 .TP
2611 .B HISTFILE
2612 The name of the file in which command history is saved (see
2613 .SM
2614 .B HISTORY
2615 below).
2616 \fBBash\fP assigns a default value of
2617 .FN \*~/.bash_history .
2618 If
2619 .SM
2620 .B HISTFILE
2621 is unset or null,
2622 the shell does not save the command history when it exits.
2623 .TP
2624 .B HISTFILESIZE
2625 The maximum number of lines contained in the history file.
2626 When this variable is assigned a value, the history file is truncated,
2627 if necessary, to contain no more than
2628 the number of history entries
2629 that total no more than that number of lines
2630 by removing the oldest entries.
2631 If the history list contains multi-line entries,
2632 the history file may contain more lines than this maximum
2633 to avoid leaving partial history entries.
2634 The history file is also truncated to this size after
2635 writing it when a shell exits or by the
2636 .B \%history
2637 builtin.
2638 If the value is 0, the history file is truncated to zero size.
2639 Non-numeric values and numeric values less than zero inhibit truncation.
2640 The shell sets the default value to the value of
2641 .SM
2642 .B HISTSIZE
2643 after reading any startup files.
2644 .TP
2645 .B HISTIGNORE
2646 A colon-separated list of patterns used to decide which command lines
2647 should be saved on the history list.
2648 If a command line matches one of the patterns in the value of
2649 .SM
2650 .BR HISTIGNORE ,
2651 it is not saved on the history list.
2652 Each pattern is anchored at the
2653 beginning of the line and must match the complete line
2654 (\fBbash\fP does not implicitly append a
2655 .Q \fB*\fP ).
2656 Each pattern is tested against the line
2657 after the checks specified by
2658 .SM
2659 .B HISTCONTROL
2660 are applied.
2661 In addition to the normal shell pattern matching characters,
2662 .Q \fB&\fP
2663 matches the previous history line.
2664 A backslash escapes the
2665 .Q \fB&\fP ;
2666 the backslash is removed before attempting a match.
2667 If the first line of a multi-line compound command was saved,
2668 the second and subsequent lines are not tested,
2669 and are added to the history regardless of the value of
2670 .SM
2671 .BR HISTIGNORE .
2672 If the first line was not saved, the second and subsequent lines of
2673 the command are not saved either.
2674 The pattern matching honors the setting of the
2675 .B \%extglob
2676 shell option.
2677 .IP
2678 .SM
2679 .B HISTIGNORE
2680 subsumes some of the function of
2681 .SM
2682 .BR HISTCONTROL .
2683 A pattern of
2684 .Q &
2685 is identical to
2686 .Q \%ignoredups ,
2687 and a pattern of
2688 .Q "[ ]*"
2689 is identical to
2690 .Q \%ignorespace .
2691 Combining these two patterns, separating them with a colon,
2692 provides the functionality of
2693 .Q \%ignoreboth .
2694 .TP
2695 .B HISTSIZE
2696 The number of commands to remember in the command history (see
2697 .SM
2698 .B HISTORY
2699 below).
2700 If the value is 0, commands are not saved in the history list.
2701 Numeric values less than zero result in every command being saved
2702 on the history list (there is no limit).
2703 The shell sets the default value to 500 after reading any startup files.
2704 .TP
2705 .B HISTTIMEFORMAT
2706 If this variable is set and not null, its value is used as a format string
2707 for
2708 .IR strftime (3)
2709 to print the time stamp associated with each history
2710 entry displayed by the \fBhistory\fP builtin.
2711 If this variable is set, the shell writes time stamps to the history file so
2712 they may be preserved across shell sessions.
2713 This uses the history comment character to distinguish timestamps from
2714 other history lines.
2715 .TP
2716 .B HOME
2717 The home directory of the current user; the default argument for the
2718 \fBcd\fP builtin command.
2719 The value of this variable is also used when performing tilde expansion.
2720 .TP
2721 .B HOSTFILE
2722 Contains the name of a file in the same format as
2723 .FN /etc/hosts
2724 that should be read when the shell needs to complete a
2725 hostname.
2726 The list of possible hostname completions may be changed while the
2727 shell is running;
2728 the next time hostname completion is attempted after the
2729 value is changed,
2730 .B bash
2731 adds the contents of the new file to the existing list.
2732 If
2733 .SM
2734 .B HOSTFILE
2735 is set, but has no value, or does not name a readable file,
2736 \fBbash\fP attempts to read
2737 .FN /etc/hosts
2738 to obtain the list of possible hostname completions.
2739 When
2740 .SM
2741 .B HOSTFILE
2742 is unset, \fBbash\fP clears the hostname list.
2743 .TP
2744 .B IFS
2745 The
2746 .I Internal Field Separator
2747 that is used
2748 for word splitting after expansion and to
2749 split lines into words with the
2750 .B read
2751 builtin command.
2752 Word splitting is described below under
2753 .SM
2754 .BR EXPANSION .
2755 The default value is
2756 .Q <space><tab><newline> .
2757 .TP
2758 .B IGNOREEOF
2759 Controls the
2760 action of an interactive shell on receipt of an
2761 .SM
2762 .B EOF
2763 character as the sole input.
2764 If set, the value is the number of consecutive
2765 .SM
2766 .B EOF
2767 characters which must be
2768 typed as the first characters on an input line before
2769 .B bash
2770 exits.
2771 If the variable is set but does not have a numeric value,
2772 or the value is null,
2773 the default value is 10.
2774 If it is unset,
2775 .SM
2776 .B EOF
2777 signifies the end of input to the shell.
2778 .TP
2779 .B INPUTRC
2780 The filename for the
2781 .B readline
2782 startup file, overriding the default of
2783 .FN \*~/.inputrc
2784 (see
2785 .SM
2786 .B READLINE
2787 below).
2788 .TP
2789 .B INSIDE_EMACS
2790 If this variable appears in the environment when the shell starts,
2791 \fBbash\fP assumes that it is running inside an Emacs shell buffer
2792 and may disable line editing, depending on the value of
2793 .SM
2794 .BR TERM .
2795 .TP
2796 .B LANG
2797 Used to determine the locale category for any category not specifically
2798 selected with a variable starting with \fBLC_\fP.
2799 .TP
2800 .B LC_ALL
2801 This variable overrides the value of
2802 .SM
2803 .B LANG
2804 and any other
2805 \fBLC_\fP variable specifying a locale category.
2806 .TP
2807 .B LC_COLLATE
2808 This variable determines the collation order used when sorting the
2809 results of pathname expansion, and determines the behavior of range
2810 expressions, equivalence classes, and collating sequences within
2811 pathname expansion and pattern matching.
2812 .TP
2813 .B LC_CTYPE
2814 This variable determines the interpretation of characters and the
2815 behavior of character classes within pathname expansion and pattern
2816 matching.
2817 .TP
2818 .B LC_MESSAGES
2819 This variable determines the locale used to translate double-quoted
2820 strings preceded by a \fB$\fP.
2821 .TP
2822 .B LC_NUMERIC
2823 This variable determines the locale category used for number formatting.
2824 .TP
2825 .B LC_TIME
2826 This variable determines the locale category used for data and time
2827 formatting.
2828 .TP
2829 .B LINES
2830 Used by the \fBselect\fP compound command to determine the column length
2831 for printing selection lists.
2832 Automatically set if the
2833 .B checkwinsize
2834 option is enabled or in an interactive shell upon receipt of a
2835 .SM
2836 .BR SIGWINCH .
2837 .TP
2838 .B MAIL
2839 If the value is set to a file or directory name and the
2840 .SM
2841 .B MAILPATH
2842 variable is not set,
2843 .B bash
2844 informs the user of the arrival of mail in the specified file or
2845 Maildir-format directory.
2846 .TP
2847 .B MAILCHECK
2848 Specifies how
2849 often (in seconds)
2850 .B bash
2851 checks for mail.
2852 The default is 60 seconds.
2853 When it is time to check for mail,
2854 the shell does so before displaying the primary prompt.
2855 If this variable is unset, or set to a value that is not a number
2856 greater than or equal to zero, the shell disables mail checking.
2857 .TP
2858 .B MAILPATH
2859 A colon-separated list of filenames to be checked for mail.
2860 The message to be printed when mail arrives in a particular file
2861 may be specified by separating the filename from the message with a
2862 .Q ? .
2863 When used in the text of the message, \fB$_\fP expands to the name of
2864 the current mailfile.
2865 For example:
2866 .RS
2867 .PP
2868 .EX
2869 \fBMAILPATH\fP=\*'/var/mail/bfox?\*"You have mail\*":\*~/shell\-mail?\*"$_ has mail!\*"\*'
2870 .EE
2871 .PP
2872 .B Bash
2873 can be configured to supply
2874 a default value for this variable (there is no value by default),
2875 but the location of the user
2876 mail files that it uses is system dependent (e.g., /var/mail/\fB$USER\fP).
2877 .RE
2878 .TP
2879 .B OPTERR
2880 If set to the value 1,
2881 .B bash
2882 displays error messages generated by the
2883 .B getopts
2884 builtin command (see
2885 .SM
2886 .B "SHELL BUILTIN COMMANDS"
2887 below).
2888 .SM
2889 .B OPTERR
2890 is initialized to 1 each time the shell is invoked or a shell
2891 script is executed.
2892 .TP
2893 .B PATH
2894 The search path for commands.
2895 It is a colon-separated list of directories in which
2896 the shell looks for commands (see
2897 .SM
2898 .B "COMMAND EXECUTION"
2899 below).
2900 A zero-length (null) directory name in the value of
2901 .SM
2902 .B PATH
2903 indicates the current directory.
2904 A null directory name may appear as two adjacent colons, or as an initial
2905 or trailing colon.
2906 The default path is system-dependent,
2907 and is set by the administrator who installs
2908 .BR bash .
2909 A common value is
2910 .RS
2911 .RS 5n
2912 .EX
2913 /usr/local/bin:/usr/local/sbin:\c
2914 .if \n(LL<78n .br
2915 /usr/bin:/usr/sbin:/bin:/sbin
2916 .EE
2917 .RE
2918 .RE
2919 .TP
2920 .B POSIXLY_CORRECT
2921 If this variable is in the environment when \fBbash\fP starts, the shell
2922 enters posix mode before reading the startup files, as if the
2923 .B \-\-posix
2924 invocation option had been supplied.
2925 If it is set while the shell is
2926 running, \fBbash\fP enables posix mode, as if the command
2927 .Q "set \-o posix"
2928 had been executed.
2929 When the shell enters posix mode, it sets this variable if it was
2930 not already set.
2931 .TP
2932 .B PROMPT_COMMAND
2933 If this variable is set, and is an array,
2934 the value of each set element is executed as a command
2935 prior to issuing each primary prompt.
2936 If this is set but not an array variable,
2937 its value is used as a command to execute instead.
2938 .TP
2939 .B PROMPT_DIRTRIM
2940 If set to a number greater than zero, the value is used as the number of
2941 trailing directory components to retain when expanding the \fB\ew\fP and
2942 \fB\eW\fP prompt string escapes (see
2943 .SM
2944 .B PROMPTING
2945 below).
2946 Characters removed are replaced with an ellipsis.
2947 .TP
2948 .B PS0
2949 The value of this parameter is expanded (see
2950 .SM
2951 .B PROMPTING
2952 below) and displayed by interactive shells after reading a command
2953 and before the command is executed.
2954 .TP
2955 .B PS1
2956 The value of this parameter is expanded (see
2957 .SM
2958 .B PROMPTING
2959 below) and used as the primary prompt string.
2960 The default value is
2961 .Q \es\-\ev\e$\ .
2962 .TP
2963 .B PS2
2964 The value of this parameter is expanded as with
2965 .SM
2966 .B PS1
2967 and used as the secondary prompt string.
2968 The default is
2969 .Q >\ .
2970 .TP
2971 .B PS3
2972 The value of this parameter is used as the prompt for the
2973 .B select
2974 command (see
2975 .SM
2976 .B "SHELL GRAMMAR"
2977 above).
2978 .TP
2979 .B PS4
2980 The value of this parameter is expanded as with
2981 .SM
2982 .B PS1
2983 and the value is printed before each command
2984 .B bash
2985 displays during an execution trace.
2986 The first character of the expanded value of
2987 .SM
2988 .B PS4
2989 is replicated multiple times, as necessary, to indicate multiple
2990 levels of indirection.
2991 The default is
2992 .Q +\ .
2993 .TP
2994 .B SHELL
2995 This variable expands to the full pathname to the shell.
2996 If it is not set when the shell starts,
2997 .B bash
2998 assigns to it the full pathname of the current user's login shell.
2999 .TP
3000 .B TIMEFORMAT
3001 The value of this parameter is used as a format string specifying
3002 how the timing information for pipelines prefixed with the
3003 .B time
3004 reserved word should be displayed.
3005 The \fB%\fP character introduces an escape sequence that is
3006 expanded to a time value or other information.
3007 The escape sequences and their meanings are as follows; the
3008 brackets denote optional portions.
3009 .PP
3010 .RS
3011 .PD 0
3012 .TP 10
3013 .B %%
3014 A literal \fB%\fP.
3015 .TP
3016 .B %[\fIp\fP][l]R
3017 The elapsed time in seconds.
3018 .TP
3019 .B %[\fIp\fP][l]U
3020 The number of CPU seconds spent in user mode.
3021 .TP
3022 .B %[\fIp\fP][l]S
3023 The number of CPU seconds spent in system mode.
3024 .TP
3025 .B %P
3026 The CPU percentage, computed as (%U + %S) / %R.
3027 .PD
3028 .RE
3029 .IP
3030 The optional \fIp\fP is a digit specifying the \fIprecision\fP,
3031 the number of fractional digits after a decimal point.
3032 A value of 0 causes no decimal point or fraction to be output.
3033 \fBtime\fP prints at most six digits after the decimal point;
3034 values of \fIp\fP greater than 6 are changed to 6.
3035 If \fIp\fP is not specified,
3036 \fBtime\fP prints three digits after the decimal point.
3037 .IP
3038 The optional \fBl\fP specifies a longer format, including
3039 minutes, of the form \fIMM\fPm\fISS\fP.\fIFF\fPs.
3040 The value of \fIp\fP determines whether or not the fraction is
3041 included.
3042 .IP
3043 If this variable is not set, \fBbash\fP acts as if it had the
3044 value \fB$\*'\enreal\et%3lR\enuser\et%3lU\ensys\et%3lS\*'\fP.
3045 If the value is null, \fBbash\fP does not display any timing information.
3046 A trailing newline is added when the format string is displayed.
3047 .PD 0
3048 .TP
3049 .B TMOUT
3050 If set to a value greater than zero,
3051 the \fBread\fP builtin uses the value as its
3052 default timeout.
3053 The \fBselect\fP command terminates if input does not arrive
3054 after
3055 .SM
3056 .B TMOUT
3057 seconds when input is coming from a terminal.
3058 In an interactive shell, the value is interpreted as the
3059 number of seconds to wait for a line of input after issuing the
3060 primary prompt.
3061 .B Bash
3062 terminates after waiting for that number of seconds if a
3063 complete line of input does not arrive.
3064 .TP
3065 .B TMPDIR
3066 If set, \fBbash\fP uses its value as the name of a directory in which
3067 \fBbash\fP creates temporary files for the shell's use.
3068 .TP
3069 .B auto_resume
3070 This variable controls how the shell interacts with the user and
3071 job control.
3072 If this variable is set, simple commands
3073 consisting of only a single word,
3074 without redirections, are treated as candidates for resumption
3075 of an existing stopped job.
3076 There is no ambiguity allowed; if there is more than one job
3077 beginning with or containing
3078 the word, this selects the most recently accessed job.
3079 The
3080 .I name
3081 of a stopped job, in this context, is the command line used to
3082 start it, as displayed by \fBjobs\fP.
3083 If set to the value
3084 .IR exact ,
3085 the word must match the name of a stopped job exactly;
3086 if set to
3087 .IR substring ,
3088 the word needs to match a substring of the name of a stopped job.
3089 The
3090 .I substring
3091 value provides functionality analogous to the
3092 .B %?
3093 job identifier (see
3094 .SM
3095 .B "JOB CONTROL"
3096 below).
3097 If set to any other value (e.g.,
3098 .IR prefix ),
3099 the word must be a prefix of a stopped job's name;
3100 this provides functionality analogous to the \fB%\fP\fIstring\fP job identifier.
3101 .TP
3102 .B histchars
3103 The two or three characters which control history expansion,
3104 quick substitution, and tokenization
3105 (see
3106 .SM
3107 .B "HISTORY EXPANSION"
3108 below).
3109 The first character is the \fIhistory expansion\fP character,
3110 the character which begins a history expansion, normally
3111 .Q \fB!\fP .
3112 The second character is the \fIquick substitution\fP character, normally
3113 .Q \fB\*^\fP .
3114 When it appears as the first character on the line,
3115 history substitution repeats the previous command,
3116 replacing one string with another.
3117 The optional third character is the
3118 \fIhistory comment\fP
3119 character, normally
3120 .Q \fB#\fP ,
3121 which indicates
3122 that the remainder of the line is a comment
3123 when it appears as the first character of a word.
3124 The history comment character disables history substitution
3125 for the remaining words on the line.
3126 It does not necessarily cause the shell parser to treat the rest of the
3127 line as a comment.
3128 .PD
3129 .SS Arrays
3130 .B Bash
3131 provides one-dimensional indexed and associative array variables.
3132 Any variable may be used as an indexed array; the
3133 .B declare
3134 builtin explicitly declares an array.
3135 There is no maximum
3136 limit on the size of an array, nor any requirement that members
3137 be indexed or assigned contiguously.
3138 Indexed arrays are referenced using arithmetic expressions
3139 that must expand to an integer
3140 (see
3141 .SM
3142 .B
3143 ARITHMETIC EVALUATION
3144 below)
3145 and are zero-based;
3146 associative arrays are referenced using arbitrary strings.
3147 Unless otherwise noted, indexed array indices must be non-negative integers.
3148 .PP
3149 The shell performs
3150 parameter and variable expansion, arithmetic expansion,
3151 command substitution, and quote removal
3152 on indexed array subscripts.
3153 Since this
3154 can potentially result in empty strings,
3155 subscript indexing treats
3156 those as expressions that evaluate to 0.
3157 .PP
3158 The shell performs
3159 tilde expansion,
3160 parameter and variable expansion, arithmetic expansion,
3161 command substitution, and quote removal
3162 on associative array subscripts.
3163 Empty strings cannot be used as associative array keys.
3164 .PP
3165 \fBBash\fP automatically creates an indexed array
3166 if any variable is assigned to using the syntax
3167 .RS
3168 \fIname\fP[\fIsubscript\fP]=\fIvalue\fP
3169 \&.
3170 .RE
3171 The
3172 .I subscript
3173 is treated as an arithmetic expression that must evaluate to a number
3174 greater than or equal to zero.
3175 To explicitly declare an indexed array, use
3176 .RS
3177 .BI "declare \-a\ " name
3178 .RE
3179 (see
3180 .SM
3181 .B "SHELL BUILTIN COMMANDS"
3182 below).
3183 .RS
3184 \fBdeclare \-a\fP \fIname\fP[\fIsubscript\fP]
3185 .RE
3186 is also accepted; the \fIsubscript\fP is ignored.
3187 .PP
3188 Associative arrays are created using
3189 .RS
3190 .BI "declare \-A\ " name
3191 .RE
3192 \&.
3193 .PP
3194 Attributes may be specified for an array variable using the
3195 .B \%declare
3196 and
3197 .B \%readonly
3198 builtins.
3199 Each attribute applies to all members of an array.
3200 .PP
3201 Arrays are assigned using compound assignments of the form
3202 \fIname\fP=\fB(\fPvalue\fI1\fP .\|.\|.\& value\fIn\fP\fB)\fP, where each
3203 \fIvalue\fP may be of the form [\fIsubscript\fP]=\fIstring\fP.
3204 Indexed array assignments do not require anything but \fIstring\fP.
3205 Each \fIvalue\fP in the list is expanded using the shell expansions
3206 described below under
3207 .SM
3208 .BR EXPANSION ,
3209 but \fIvalue\fPs that are valid variable assignments
3210 including the brackets and subscript do not undergo
3211 brace expansion and word splitting, as with individual
3212 variable assignments.
3213 .PP
3214 When assigning to indexed arrays, if the optional brackets and subscript
3215 are supplied, that index is assigned to;
3216 otherwise the index of the element assigned is the last index assigned
3217 to by the statement plus one.
3218 Indexing starts at zero.
3219 .PP
3220 When assigning to an associative array, the words in a compound assignment
3221 may be either assignment statements, for which the subscript is required,
3222 or a list of words that is interpreted as a sequence of alternating keys
3223 and values:
3224 \fIname\fP=\fB( \fP\fIkey1 value1 key2 value2\fP .\|.\|.\&\fB)\fP.
3225 These are treated identically to
3226 \fIname\fP=\fB(\fP [\fIkey1\fP]=\fIvalue1\fP [\fIkey2\fP]=\fIvalue2\fP
3227 \&.\|.\|.\&\fB)\fP.
3228 The first word in the list determines how the remaining words
3229 are interpreted; all assignments in a list must be of the same type.
3230 When using key/value pairs, the keys may not be missing or empty;
3231 a final missing value is treated like the empty string.
3232 .PP
3233 This syntax is also accepted by the
3234 .B declare
3235 builtin.
3236 Individual array elements may be assigned to using the
3237 \fIname\fP[\fIsubscript\fP]=\fIvalue\fP syntax introduced above.
3238 .PP
3239 When assigning to an indexed array, if
3240 .I name
3241 is subscripted by a negative number, that number is
3242 interpreted as relative to one greater than the maximum index of
3243 \fIname\fP, so negative indices count back from the end of the
3244 array, and an index of \-1 references the last element.
3245 .PP
3246 The
3247 .Q +=
3248 operator appends to an array variable when assigning
3249 using the compound assignment syntax; see
3250 .SM
3251 .B PARAMETERS
3252 above.
3253 .PP
3254 An array element is referenced using
3255 ${\fIname\fP[\fIsubscript\fP]}.
3256 The braces are required to avoid conflicts with pathname expansion.
3257 If \fIsubscript\fP is \fB@\fP or \fB*\fP, the word expands to
3258 all members of \fIname\fP,
3259 unless noted in the description of a builtin or word expansion.
3260 These subscripts differ only when the
3261 word appears within double quotes.
3262 If the word is double-quoted, ${\fIname\fP[*]} expands to a single
3263 word with the value of each array member separated by the first
3264 character of the
3265 .SM
3266 .B IFS
3267 special variable, and ${\fIname\fP[@]} expands each element of
3268 \fIname\fP to a separate word.
3269 When there are no array members, ${\fIname\fP[@]} expands to nothing.
3270 If the double-quoted expansion occurs within a word, the expansion of
3271 the first parameter is joined with the beginning part of the
3272 expansion of the original word,
3273 and the expansion of the last parameter is joined with the last
3274 part of the
3275 expansion of the original word.
3276 This is analogous to the expansion
3277 of the special parameters \fB*\fP and \fB@\fP (see
3278 .B "Special Parameters"
3279 above).
3280 .PP
3281 ${#\fIname\fP[\fIsubscript\fP]} expands to the length of
3282 ${\fIname\fP[\fIsubscript\fP]}.
3283 If \fIsubscript\fP is \fB*\fP or \fB@\fP,
3284 the expansion is the number of elements in the array.
3285 .PP
3286 If the
3287 .I subscript
3288 used to reference an element of an indexed array
3289 evaluates to a number less than zero, it is
3290 interpreted as relative to one greater than the maximum index of the array,
3291 so negative indices count back from the end of the
3292 array, and an index of \-1 references the last element.
3293 .PP
3294 Referencing an array variable without a subscript is equivalent to
3295 referencing the array with a subscript of 0.
3296 Any reference to a variable using a valid subscript is valid;
3297 .B bash
3298 creates an array if necessary.
3299 .PP
3300 An array variable is considered set if a subscript has been assigned a
3301 value.
3302 The null string is a valid value.
3303 .PP
3304 It is possible to obtain the keys (indices) of an array as well as the values.
3305 ${\fB!\fP\fIname\fP[\fI@\fP]} and ${\fB!\fP\fIname\fP[\fI*\fP]}
3306 expand to the indices assigned in array variable \fIname\fP.
3307 The treatment when in double quotes is similar to the expansion of the
3308 special parameters \fI@\fP and \fI*\fP within double quotes.
3309 .PP
3310 The
3311 .B unset
3312 builtin is used to destroy arrays.
3313 \fBunset\fP \fIname\fP[\fIsubscript\fP]
3314 unsets the array element at index \fIsubscript\fP,
3315 for both indexed and associative arrays.
3316 Negative subscripts to indexed arrays are interpreted as described above.
3317 Unsetting the last element of an array variable does not unset the variable.
3318 \fBunset\fP \fIname\fP, where \fIname\fP is an array,
3319 removes the entire array.
3320 \fBunset\fP \fIname\fP[\fIsubscript\fP]
3321 behaves differently depending on
3322 whether \fIname\fP is an indexed or associative array
3323 when \fIsubscript\fP is \fB*\fP or \fB@\fP.
3324 If \fIname\fP is an associative array, this unsets the element with
3325 subscript \fB*\fP or \fB@\fP.
3326 If \fIname\fP is an indexed array, unset removes all of the elements but
3327 does not remove the array itself.
3328 .PP
3329 When using a variable name with a subscript as an argument to a command,
3330 such as with \fBunset\fP, without using the word expansion syntax
3331 described above,
3332 (e.g., unset a[4]),
3333 the argument is subject to pathname expansion.
3334 Quote the argument if pathname expansion is not desired
3335 (e.g., unset \*'a[4]\*').
3336 .PP
3337 The
3338 .BR declare ,
3339 .BR local ,
3340 and
3341 .B readonly
3342 builtins each accept a
3343 .B \-a
3344 option to specify an indexed array and a
3345 .B \-A
3346 option to specify an associative array.
3347 If both options are supplied,
3348 .B \-A
3349 takes precedence.
3350 The
3351 .B read
3352 builtin accepts a
3353 .B \-a
3354 option to assign a list of words read from the standard input
3355 to an array.
3356 The
3357 .B set
3358 and
3359 .B declare
3360 builtins display array values in a way that allows them to be
3361 reused as assignments.
3362 Other builtins accept array name arguments as well
3363 (e.g., \fBmapfile\fP); see the descriptions
3364 of individual builtins below for details.
3365 The shell provides a number of builtin array variables.
3366 .SH EXPANSION
3367 Expansion is performed on the command line after it has been split into
3368 words. The shell performs these expansions:
3369 .IR "brace expansion" ,
3370 .IR "tilde expansion" ,
3371 .IR "parameter and variable expansion" ,
3372 .IR "command substitution" ,
3373 .IR "arithmetic expansion" ,
3374 .IR "word splitting" ,
3375 .IR "pathname expansion" ,
3376 and
3377 .IR "quote removal" .
3378 .PP
3379 The order of expansions is:
3380 brace expansion;
3381 tilde expansion, parameter and variable expansion, arithmetic expansion,
3382 and command substitution (done in a left-to-right fashion);
3383 word splitting;
3384 pathname expansion;
3385 and quote removal.
3386 .PP
3387 On systems that can support it, there is an additional expansion
3388 available: \fIprocess substitution\fP.
3389 This is performed at the
3390 same time as tilde, parameter, variable, and arithmetic expansion and
3391 command substitution.
3392 .PP
3393 \fIQuote removal\fP is always performed last.
3394 It removes quote characters present in the original word,
3395 not ones resulting from one of the other expansions,
3396 unless they have been quoted themselves.
3397 .PP
3398 Only brace expansion, word splitting, and pathname expansion
3399 can increase the number of words of the expansion; other expansions
3400 expand a single word to a single word.
3401 The only exceptions to this are the expansions of
3402 .B \&\*"$@\*"
3403 and
3404 .B \&\*"${\fIname\fP[@]}\*"\c \" keep leading \& for AT&T troff
3405 .BR \& , \" .BR + \& + \*" doesn't work with AT&T troff
3406 and, in most cases, \fB$*\fP and \fB${\fP\fIname\fP\fB[*]}\fP
3407 as explained above (see
3408 .SM
3409 .BR PARAMETERS ).
3410 .SS Brace Expansion
3411 .I "Brace expansion"
3412 is a mechanism to generate arbitrary strings
3413 sharing a common prefix and suffix, either of which can be empty.
3414 This mechanism is similar to
3415 \fIpathname expansion\fP, but the filenames generated
3416 need not exist.
3417 Patterns to be brace expanded are formed from an optional
3418 .IR preamble ,
3419 followed by either a series of comma-separated strings or
3420 a sequence expression between a pair of braces,
3421 followed by an optional
3422 .IR postscript .
3423 The preamble is prefixed to each string contained within the braces,
3424 and the postscript is then appended to each resulting string,
3425 expanding left to right.
3426 .PP
3427 Brace expansions may be nested.
3428 The results of each expanded string are not sorted;
3429 brace expansion preserves left to right order.
3430 For example, a\fB{\fPd,c,b\fB}\fPe expands into
3431 .Q "ade ace abe" .
3432 .PP
3433 A sequence expression takes the form
3434 \fIx\fP\fB..\fP\fIy\fP\fB[..\fP\fIincr\fP\fB]\fP,
3435 where \fIx\fP and \fIy\fP are either integers or single letters,
3436 and \fIincr\fP, an optional increment, is an integer.
3437 When integers are supplied, the expression expands to each number between
3438 \fIx\fP and \fIy\fP, inclusive.
3439 If either \fIx\fP or \fIy\fP begins with a zero,
3440 each generated term will contain the same number of digits,
3441 zero-padding where necessary.
3442 When letters are supplied, the expression expands to each character
3443 lexicographically between \fIx\fP and \fIy\fP, inclusive,
3444 using the C locale.
3445 Note that both \fIx\fP and \fIy\fP must be of the same type
3446 (integer or letter).
3447 When the increment is supplied, it is used as the difference between
3448 each term.
3449 The default increment is 1 or \-1 as appropriate.
3450 .PP
3451 Brace expansion is performed before any other expansions,
3452 and any characters special to other expansions are preserved
3453 in the result.
3454 It is strictly textual.
3455 .B Bash
3456 does not apply any syntactic interpretation to the context of the
3457 expansion or the text between the braces.
3458 .PP
3459 A correctly-formed brace expansion must contain unquoted opening
3460 and closing braces, and at least one unquoted comma or a valid
3461 sequence expression.
3462 Any incorrectly formed brace expansion is left unchanged.
3463 .PP
3464 A
3465 .Q {
3466 or
3467 Q ,
3468 may be quoted with a backslash to prevent its
3469 being considered part of a brace expression.
3470 To avoid conflicts with parameter expansion, the string
3471 .Q ${
3472 is not considered eligible for brace expansion,
3473 and inhibits brace expansion until the closing
3474 .Q } .
3475 .PP
3476 This construct is typically used as shorthand when the common
3477 prefix of the strings to be generated is longer than in the
3478 above example:
3479 .PP
3480 .RS
3481 .EX
3482 mkdir /usr/local/src/bash/{old,new,dist,bugs}
3483 .EE
3484 .RE
3485 or
3486 .RS
3487 .EX
3488 chown root /usr/{ucb/{ex,edit},lib/{ex?.?*,how_ex}}
3489 .EE
3490 .RE
3491 .PP
3492 Brace expansion introduces a slight incompatibility with
3493 historical versions of
3494 .BR sh .
3495 .B sh
3496 does not treat opening or closing braces specially when they
3497 appear as part of a word, and preserves them in the output.
3498 .B Bash
3499 removes braces from words as a consequence of brace expansion.
3500 For example, a word entered to
3501 .B sh
3502 as
3503 .Q file{1,2}
3504 appears identically in the output.
3505 .B Bash
3506 outputs that word as
3507 .Q "file1 file2"
3508 after brace expansion.
3509 Start
3510 .B bash
3511 with the
3512 .B +B
3513 option or disable brace expansion with the
3514 .B +B
3515 option to the
3516 .B set
3517 command (see
3518 .SM
3519 .B "SHELL BUILTIN COMMANDS"
3520 below) for strict \fBsh\fP compatibility.
3521 .SS Tilde Expansion
3522 If a word begins with an unquoted tilde character (\c
3523 .Q \fB\*~\fP ),
3524 all of
3525 the characters preceding the first unquoted slash (or all characters,
3526 if there is no unquoted slash) are considered a \fItilde-prefix\fP.
3527 If none of the characters in the tilde-prefix are quoted, the
3528 characters in the tilde-prefix following the tilde are treated as a
3529 possible \fIlogin name\fP.
3530 If this login name is the null string, the tilde is replaced with the
3531 value of the shell parameter
3532 .SM
3533 .BR HOME .
3534 If
3535 .SM
3536 .B HOME
3537 is unset, the tilde expands to
3538 the home directory of the user executing the shell instead.
3539 Otherwise, the tilde-prefix is replaced with the home directory
3540 associated with the specified login name.
3541 .PP
3542 If the tilde-prefix is a
3543 .Q \*~+ ,
3544 the value of the shell variable
3545 .SM
3546 .B PWD
3547 replaces the tilde-prefix.
3548 If the tilde-prefix is a
3549 .Q \*~\- ,
3550 the shell substitutes the value of the shell variable
3551 .SM
3552 .BR OLDPWD ,
3553 if it is set.
3554 If the characters following the tilde in the tilde-prefix consist
3555 of a number \fIN\fP, optionally prefixed
3556 by a
3557 .Q +
3558 or a
3559 .Q \- ,
3560 the tilde-prefix is replaced with the corresponding
3561 element from the directory stack, as it would be displayed by the
3562 .B dirs
3563 builtin invoked with the characters following the tilde in the
3564 tilde-prefix as an argument.
3565 If the characters following the tilde in the tilde-prefix consist of a
3566 number without a leading
3567 .Q +
3568 or
3569 .Q \- ,
3570 tilde expansion assumes
3571 .Q + .
3572 .PP
3573 The results of tilde expansion are treated as if they were quoted, so
3574 the replacement is not subject to word splitting and pathname expansion.
3575 .PP
3576 If the login name is invalid, or the tilde expansion fails, the
3577 tilde-prefix is unchanged.
3578 .PP
3579 \fBBash\fP checks each variable assignment
3580 for unquoted tilde-prefixes immediately
3581 following a
3582 .B :
3583 or the first
3584 .BR = ,
3585 and performs tilde expansion in these cases.
3586 Consequently, one may use filenames with tildes in assignments to
3587 .SM
3588 .BR PATH ,
3589 .SM
3590 .BR MAILPATH ,
3591 and
3592 .SM
3593 .BR CDPATH ,
3594 and the shell assigns the expanded value.
3595 .PP
3596 \fBBash\fP also performs tilde expansion on words satisfying the conditions
3597 of variable assignments (as described above under
3598 .SM
3599 .BR PARAMETERS )
3600 when they appear as arguments to simple commands.
3601 \fBBash\fP does not do this,
3602 except for the \fIdeclaration\fP commands listed above,
3603 when in posix mode.
3604 .SS Parameter Expansion
3605 The
3606 .Q \fB$\fP
3607 character introduces parameter expansion,
3608 command substitution, or arithmetic expansion.
3609 The parameter name
3610 or symbol to be expanded may be enclosed in braces, which
3611 are optional but serve to protect the variable to be expanded from
3612 characters immediately following it which could be
3613 interpreted as part of the name.
3614 .PP
3615 When braces are used, the matching ending brace is the first
3616 .Q \fB}\fP
3617 not escaped by a backslash or within a quoted string, and not within an
3618 embedded arithmetic expansion, command substitution, or parameter
3619 expansion.
3620 .PP
3621 The basic form of parameter expansion is
3622 .PP
3623 ${\fIparameter\fP}
3624 .LP
3625 which substitutes the value of \fIparameter\fP.
3626 The braces are required
3627 when
3628 .I parameter
3629 is a positional parameter with more than one digit,
3630 or when
3631 .I parameter
3632 is followed by a character which is not to be
3633 interpreted as part of its name.
3634 The \fIparameter\fP is a shell parameter as described above
3635 \fBPARAMETERS\fP) or an array reference (\fBArrays\fP).
3636 .PD
3637 .PP
3638 If the first character of \fIparameter\fP is an exclamation point (\fB!\fP),
3639 and \fIparameter\fP is not a \fInameref\fP,
3640 it introduces a level of indirection.
3641 \fBBash\fP uses the value formed by expanding the rest of
3642 \fIparameter\fP as the new \fIparameter\fP;
3643 this new parameter is then expanded and that value is used
3644 in the rest of the expansion, rather
3645 than the expansion of the original \fIparameter\fP.
3646 This is known as \fIindirect expansion\fP.
3647 The value is subject to tilde expansion,
3648 parameter expansion, command substitution, and arithmetic expansion.
3649 If \fIparameter\fP is a nameref, this expands to the name of the
3650 parameter referenced by \fIparameter\fP instead of performing the
3651 complete indirect expansion, for compatibility.
3652 The exceptions to this are the expansions of ${\fB!\fP\fIprefix\fP\fB*\fP} and
3653 ${\fB!\fP\fIname\fP[\fI@\fP]} described below.
3654 The exclamation point must immediately follow the left brace in order to
3655 introduce indirection.
3656 .PP
3657 In each of the cases below, \fIword\fP is subject to tilde expansion,
3658 parameter expansion, command substitution, and arithmetic expansion.
3659 .PP
3660 When not performing substring expansion, using the forms documented below
3661 (e.g., \fB:-\fP),
3662 \fBbash\fP tests for a parameter that is unset or null.
3663 Omitting the colon tests only for a parameter that is unset.
3664 .PP
3665 .TP
3666 ${\fIparameter\fP\fB:\-\fP\fIword\fP}
3667 \fBUse Default Values\fP. If
3668 .I parameter
3669 is unset or null, the expansion of
3670 .I word
3671 is substituted.
3672 Otherwise, the value of
3673 .I parameter
3674 is substituted.
3675 .TP
3676 ${\fIparameter\fP\fB:=\fP\fIword\fP}
3677 \fBAssign Default Values\fP.
3678 If
3679 .I parameter
3680 is unset or null, the expansion of
3681 .I word
3682 is assigned to
3683 .IR parameter ,
3684 and the expansion is the final value of
3685 .IR parameter .
3686 Positional parameters and special parameters may
3687 not be assigned in this way.
3688 .TP
3689 ${\fIparameter\fP\fB:?\fP\fIword\fP}
3690 \fBDisplay Error if Null or Unset\fP.
3691 If
3692 .I parameter
3693 is null or unset, the shell writes
3694 the expansion of \fIword\fP (or a message to that effect
3695 if
3696 .I word
3697 is not present) to the standard error and, if it
3698 is not interactive, exits with a non-zero status.
3699 An interactive shell does not exit, but does not execute the command
3700 associated with the expansion.
3701 Otherwise, the value of \fIparameter\fP is substituted.
3702 .TP
3703 ${\fIparameter\fP\fB:+\fP\fIword\fP}
3704 \fBUse Alternate Value\fP.
3705 If
3706 .I parameter
3707 is null or unset, nothing is substituted, otherwise the expansion of
3708 .I word
3709 is substituted.
3710 The value of \fIparameter\fP is not used.
3711 .TP
3712 .PD 0
3713 ${\fIparameter\fP\fB:\fP\fIoffset\fP}
3714 .TP
3715 .PD
3716 ${\fIparameter\fP\fB:\fP\fIoffset\fP\fB:\fP\fIlength\fP}
3717 \fBSubstring Expansion\fP.
3718 Expands to up to \fIlength\fP characters of the value of \fIparameter\fP
3719 starting at the character specified by \fIoffset\fP.
3720 If \fIparameter\fP is \fB@\fP or \fB*\fP, an indexed array subscripted by
3721 \fB@\fP or \fB*\fP, or an associative array name, the results differ as
3722 described below.
3723 If \fB:\fP\fIlength\fP is omitted (the first form above), this
3724 expands to the substring of the value of
3725 \fIparameter\fP starting at the character specified by \fIoffset\fP
3726 and extending to the end of the value.
3727 If \fIoffset\fP is omitted,
3728 it is treated as 0.
3729 If \fIlength\fP is omitted,
3730 but the colon after \fIoffset\fP is present,
3731 it is treated as 0.
3732 \fIlength\fP and \fIoffset\fP are arithmetic expressions (see
3733 .SM
3734 .B
3735 ARITHMETIC EVALUATION
3736 below).
3737 .IP
3738 If \fIoffset\fP evaluates to a number less than zero, the value
3739 is used as an offset in characters
3740 from the end of the value of \fIparameter\fP.
3741 If \fIlength\fP evaluates to a number less than zero,
3742 it is interpreted as an offset in characters
3743 from the end of the value of \fIparameter\fP rather than
3744 a number of characters, and the expansion is the characters between
3745 \fIoffset\fP and that result.
3746 Note that a negative offset must be separated from the colon by at least
3747 one space to avoid being confused with the \fB:-\fP expansion.
3748 .IP
3749 If \fIparameter\fP is \fB@\fP or \fB*\fP, the result is \fIlength\fP
3750 positional parameters beginning at \fIoffset\fP.
3751 A negative \fIoffset\fP is taken relative to one greater than the greatest
3752 positional parameter, so an offset of \-1 evaluates to the last positional
3753 parameter (or 0 if there are no positional parameters).
3754 It is an expansion error if \fIlength\fP evaluates to a number less than
3755 zero.
3756 .IP
3757 If \fIparameter\fP is an indexed array name subscripted by @ or *,
3758 the result is the \fIlength\fP
3759 members of the array beginning with ${\fIparameter\fP[\fIoffset\fP]}.
3760 A negative \fIoffset\fP is taken relative to one greater than the maximum
3761 index of the specified array.
3762 It is an expansion error if \fIlength\fP evaluates to a number less than
3763 zero.
3764 .IP
3765 Substring expansion applied to an associative array produces undefined
3766 results.
3767 .IP
3768 Substring indexing is zero-based unless the positional parameters
3769 are used, in which case the indexing starts at 1 by default.
3770 If \fIoffset\fP is 0, and the positional parameters are used, \fB$0\fP is
3771 prefixed to the list.
3772 .TP
3773 .PD 0
3774 ${\fB!\fP\fIprefix\fP\fB*\fP}
3775 .TP
3776 ${\fB!\fP\fIprefix\fP\fB@\fP}
3777 .PD
3778 \fBNames matching prefix\fP.
3779 Expands to the names of variables whose names begin with \fIprefix\fP,
3780 separated by the first character of the
3781 .SM
3782 .B IFS
3783 special variable.
3784 When \fI@\fP is used and the expansion appears within double quotes, each
3785 variable name expands to a separate word.
3786 .TP
3787 .PD 0
3788 ${\fB!\fP\fIname\fP[\fI@\fP]}
3789 .TP
3790 ${\fB!\fP\fIname\fP[\fI*\fP]}
3791 .PD
3792 \fBList of array keys\fP.
3793 If \fIname\fP is an array variable, expands to the list of array indices
3794 (keys) assigned in \fIname\fP.
3795 If \fIname\fP is not an array, expands to 0 if \fIname\fP is set and null
3796 otherwise.
3797 When \fI@\fP is used and the expansion appears within double quotes, each
3798 key expands to a separate word.
3799 .TP
3800 ${\fB#\fP\fIparameter\fP}
3801 \fBParameter length\fP.
3802 Substitutes the length in characters of the expanded value of \fIparameter\fP.
3803 If
3804 .I parameter
3805 is
3806 .B *
3807 or
3808 .BR @ ,
3809 the value substituted is the number of positional parameters.
3810 If
3811 .I parameter
3812 is an array name subscripted by
3813 .B *
3814 or
3815 .BR @ ,
3816 the value substituted is the number of elements in the array.
3817 If
3818 .I parameter
3819 is an indexed array name subscripted by a negative number, that number is
3820 interpreted as relative to one greater than the maximum index of
3821 \fIparameter\fP, so negative indices count back from the end of the
3822 array, and an index of \-1 references the last element.
3823 .TP
3824 .PD 0
3825 ${\fIparameter\fP\fB#\fP\fIword\fP}
3826 .TP
3827 ${\fIparameter\fP\fB##\fP\fIword\fP}
3828 .PD
3829 \fBRemove matching prefix pattern\fP.
3830 The
3831 .I word
3832 is expanded to produce a pattern just as in pathname
3833 expansion, and matched against the expanded value of
3834 .I parameter
3835 using the rules described under
3836 .B "Pattern Matching"
3837 below.
3838 If the pattern matches the beginning of
3839 the value of
3840 .IR parameter ,
3841 then the result of the expansion is the expanded value of
3842 .I parameter
3843 with the shortest matching pattern (the
3844 .Q #
3845 case) or the longest matching pattern (the
3846 .Q ##
3847 case) deleted.
3848 If
3849 .I parameter
3850 is
3851 .B @
3852 or
3853 .BR * ,
3854 the pattern removal operation is applied to each positional
3855 parameter in turn, and the expansion is the resultant list.
3856 If
3857 .I parameter
3858 is an array variable subscripted with
3859 .B @
3860 or
3861 .BR * ,
3862 the pattern removal operation is applied to each member of the
3863 array in turn, and the expansion is the resultant list.
3864 .TP
3865 .PD 0
3866 ${\fIparameter\fP\fB%\fP\fIword\fP}
3867 .TP
3868 ${\fIparameter\fP\fB%%\fP\fIword\fP}
3869 .PD
3870 \fBRemove matching suffix pattern\fP.
3871 The \fIword\fP is expanded to produce a pattern just as in
3872 pathname expansion, and matched against the expanded value of
3873 .I parameter
3874 using the rules described under
3875 .B "Pattern Matching"
3876 below.
3877 If the pattern matches a trailing portion of the expanded value of
3878 .IR parameter ,
3879 then the result of the expansion is the expanded value of
3880 .I parameter
3881 with the shortest matching pattern (the
3882 .Q %
3883 case) or the longest matching pattern (the
3884 .Q %%
3885 case) deleted.
3886 If
3887 .I parameter
3888 is
3889 .B @
3890 or
3891 .BR * ,
3892 the pattern removal operation is applied to each positional
3893 parameter in turn, and the expansion is the resultant list.
3894 If
3895 .I parameter
3896 is an array variable subscripted with
3897 .B @
3898 or
3899 .BR * ,
3900 the pattern removal operation is applied to each member of the
3901 array in turn, and the expansion is the resultant list.
3902 .TP
3903 .PD 0
3904 ${\fIparameter\fP\fB/\fP\fIpattern\fP\fB/\fP\fIstring\fP}
3905 .TP
3906 ${\fIparameter\fP\fB//\fP\fIpattern\fP\fB/\fP\fIstring\fP}
3907 .TP
3908 ${\fIparameter\fP\fB/#\fP\fIpattern\fP\fB/\fP\fIstring\fP}
3909 .TP
3910 ${\fIparameter\fP\fB/%\fP\fIpattern\fP\fB/\fP\fIstring\fP}
3911 .PD
3912 \fBPattern substitution\fP.
3913 The \fIpattern\fP is expanded to produce a pattern
3914 and matched against the expanded value of \fIparameter\fP
3915 as described under
3916 .B "Pattern Matching"
3917 below.
3918 The longest match of \fIpattern\fP
3919 in the expanded value is replaced with \fIstring\fP.
3920 \fIstring\fP undergoes tilde expansion, parameter and variable expansion,
3921 arithmetic expansion, command and process substitution, and quote removal.
3922 .IP
3923 In the first form above, only the first match is replaced.
3924 If there are two slashes separating \fIparameter\fP and \fIpattern\fP
3925 (the second form above), all matches of \fIpattern\fP are
3926 replaced with \fIstring\fP.
3927 If \fIpattern\fP is preceded by \fB#\fP (the third form above),
3928 it must match at the beginning of the expanded value of \fIparameter\fP.
3929 If \fIpattern\fP is preceded by \fB%\fP (the fourth form above),
3930 it must match at the end of the expanded value of \fIparameter\fP.
3931 .IP
3932 If the expansion of \fIstring\fP is null,
3933 matches of \fIpattern\fP are deleted
3934 and the \fB/\fP following \fIpattern\fP may be omitted.
3935 .IP
3936 If the \fBpatsub_replacement\fP shell option is enabled using \fBshopt\fP,
3937 any unquoted instances of \fB&\fP in \fIstring\fP are replaced with the
3938 matching portion of \fIpattern\fP.
3939 .IP
3940 Quoting any part of \fIstring\fP inhibits replacement in the
3941 expansion of the quoted portion, including replacement strings stored
3942 in shell variables.
3943 Backslash escapes \fB&\fP in \fIstring\fP; the backslash is removed
3944 in order to permit a literal \fB&\fP in the replacement string.
3945 Backslash can also be used to escape a backslash; \fB\e\e\fP results in
3946 a literal backslash in the replacement.
3947 Users should take care if \fIstring\fP is double-quoted to avoid
3948 unwanted interactions between the backslash and double-quoting, since
3949 backslash has special meaning within double quotes.
3950 Pattern substitution performs the check for unquoted \fB&\fP after
3951 expanding \fIstring\fP;
3952 shell programmers should quote any occurrences of \fB&\fP
3953 they want to be taken literally in the replacement
3954 and ensure any instances of \fB&\fP they want to be replaced are unquoted.
3955 .IP
3956 Like the pattern removal operators, double quotes surrounding the
3957 replacement string quote the expanded characters, while double quotes
3958 enclosing the entire parameter substitution do not, since
3959 the expansion is performed in a
3960 context that doesn't take any enclosing double quotes into account.
3961 .IP
3962 If the
3963 .B nocasematch
3964 shell option is enabled, the match is performed without regard to the case
3965 of alphabetic characters.
3966 .IP
3967 If
3968 .I parameter
3969 is
3970 .B @
3971 or
3972 .BR * ,
3973 the substitution operation is applied to each positional
3974 parameter in turn, and the expansion is the resultant list.
3975 If
3976 .I parameter
3977 is an array variable subscripted with
3978 .B @
3979 or
3980 .BR * ,
3981 the substitution operation is applied to each member of the
3982 array in turn, and the expansion is the resultant list.
3983 .TP
3984 .PD 0
3985 ${\fIparameter\fP\fB\*^\fP\fIpattern\fP}
3986 .TP
3987 ${\fIparameter\fP\fB\*^\*^\fP\fIpattern\fP}
3988 .TP
3989 ${\fIparameter\fP\fB,\fP\fIpattern\fP}
3990 .TP
3991 ${\fIparameter\fP\fB,,\fP\fIpattern\fP}
3992 .PD
3993 \fBCase modification\fP.
3994 This expansion modifies the case of alphabetic characters in \fIparameter\fP.
3995 First, the \fIpattern\fP is expanded to produce a pattern
3996 as described below under
3997 .SM
3998 .BR "Pattern Matching" .
3999 .B Bash
4000 then examines characters in the expanded value of \fIparameter\fP
4001 against \fIpattern\fP as described below.
4002 If a character matches the pattern, its case is converted.
4003 The pattern should not attempt to match more than one character.
4004 .IP
4005 Using
4006 .Q \*^
4007 converts lowercase letters matching \fIpattern\fP to uppercase;
4008 .Q ,
4009 converts matching uppercase letters to lowercase.
4010 The
4011 \fB\*^\fP and \fB,\fP variants
4012 examine the first character in the expanded value
4013 and convert its case if it matches \fIpattern\fP;
4014 the
4015 \fB\*^\*^\fP and \fB,,\fP variants
4016 examine all characters in the expanded value
4017 and convert each one that matches \fIpattern\fP.
4018 If \fIpattern\fP is omitted, it is treated like a \fB?\fP, which matches
4019 every character.
4020 .IP
4021 If
4022 .I parameter
4023 is
4024 .B @
4025 or
4026 .BR * ,
4027 the case modification operation is applied to each positional
4028 parameter in turn, and the expansion is the resultant list.
4029 If
4030 .I parameter
4031 is an array variable subscripted with
4032 .B @
4033 or
4034 .BR * ,
4035 the case modification operation is applied to each member of the
4036 array in turn, and the expansion is the resultant list.
4037 .TP
4038 .PD 0
4039 ${\fIparameter\fP\fB@\fP\fIoperator\fP}
4040 \fBParameter transformation\fP.
4041 The expansion is either a transformation of the value of \fIparameter\fP
4042 or information about \fIparameter\fP itself, depending on the value of
4043 \fIoperator\fP. Each \fIoperator\fP is a single letter:
4044 .PP
4045 .RS
4046 .TP
4047 .B U
4048 The expansion is a string that is the value of \fIparameter\fP with lowercase
4049 alphabetic characters converted to uppercase.
4050 .TP
4051 .B u
4052 The expansion is a string that is the value of \fIparameter\fP with the first
4053 character converted to uppercase, if it is alphabetic.
4054 .TP
4055 .B L
4056 The expansion is a string that is the value of \fIparameter\fP with uppercase
4057 alphabetic characters converted to lowercase.
4058 .TP
4059 .B Q
4060 The expansion is a string that is the value of \fIparameter\fP quoted in a
4061 format that can be reused as input.
4062 .TP
4063 .B E
4064 The expansion is a string that is the value of \fIparameter\fP with backslash
4065 escape sequences expanded as with the \fB$\*'\fP.\|.\|.\%\fB\*'\fP
4066 quoting mechanism.
4067 .TP
4068 .B P
4069 The expansion is a string that is the result of expanding the value of
4070 \fIparameter\fP as if it were a prompt string (see \fBPROMPTING\fP below).
4071 .TP
4072 .B A
4073 The expansion is a string in the form of
4074 an assignment statement or \fBdeclare\fP command that, if
4075 evaluated, recreates \fIparameter\fP with its attributes and value.
4076 .TP
4077 .B K
4078 Produces a possibly-quoted version of the value of \fIparameter\fP,
4079 except that it prints the values of
4080 indexed and associative arrays as a sequence of quoted key-value pairs
4081 (see \fBArrays\fP above).
4082 The keys and values are quoted in a format that can be reused as input.
4083 .TP
4084 .B a
4085 The expansion is a string consisting of flag values representing
4086 \fIparameter\fP's attributes.
4087 .TP
4088 .B k
4089 Like the K transformation, but expands the keys and values of
4090 indexed and associative arrays to separate words after word splitting.
4091 .PD
4092 .PP
4093 If
4094 .I parameter
4095 is
4096 .B @
4097 or
4098 .BR * ,
4099 the operation is applied to each positional
4100 parameter in turn, and the expansion is the resultant list.
4101 If
4102 .I parameter
4103 is an array variable subscripted with
4104 .B @
4105 or
4106 .BR * ,
4107 the operation is applied to each member of the
4108 array in turn, and the expansion is the resultant list.
4109 .PP
4110 The result of the expansion is subject to word splitting and pathname
4111 expansion as described below.
4112 .RE
4113 .SS Command Substitution
4114 \fICommand substitution\fP allows the output of a command to replace
4115 the command itself.
4116 There are two standard forms:
4117 .RS
4118 .PP
4119 \fB$(\fP\fIcommand\fP\|\fB)\fP
4120 .RE
4121 or (deprecated)
4122 .RS
4123 \fB\`\fP\fIcommand\fP\fB\`\fP.
4124 .RE
4125 .PP
4126 .B Bash
4127 performs the expansion by executing \fIcommand\fP in a subshell environment
4128 and replacing the command substitution with the standard output of the
4129 command, with any trailing newlines deleted.
4130 Embedded newlines are not deleted, but they may be removed during
4131 word splitting.
4132 The command substitution \fB$(cat \fIfile\fP)\fR can be replaced by
4133 the equivalent but faster \fB$(< \fIfile\fP)\fR.
4134 .PP
4135 With the old-style backquote form of substitution,
4136 backslash retains its literal meaning except when followed by
4137 .BR $ ,
4138 .BR \` ,
4139 or
4140 .BR \e .
4141 The first backquote not preceded by a backslash terminates the
4142 command substitution.
4143 When using the $(\^\fIcommand\fP\|) form, all characters between the
4144 parentheses make up the command; none are treated specially.
4145 .PP
4146 There is an alternate form of command substitution:
4147 .RS
4148 .PP
4149 \fB${\fP\fIc\fP \fIcommand\fP\fB;\fP\|\fB}\fP
4150 .RE
4151 .PP
4152 which executes \fIcommand\fP in the current execution environment
4153 and captures its output, again with trailing newlines removed.
4154 .PP
4155 The character \fIc\fP following the open brace must be a space, tab,
4156 newline, or \fB|\fP, and the close brace must be in a position
4157 where a reserved word may appear (i.e., preceded by a command terminator
4158 such as semicolon).
4159 \fBBash\fP allows the close brace to be joined to the remaining characters in
4160 the word without being followed by a shell metacharacter as a reserved
4161 word would usually require.
4162 .PP
4163 Any side effects of \fIcommand\fP take effect immediately
4164 in the current execution environment and persist in the current
4165 environment after the command completes (e.g., the \fBexit\fP builtin
4166 exits the shell).
4167 .PP
4168 This type of command substitution superficially resembles executing an
4169 unnamed shell function: local variables are created as when a shell
4170 function is executing, and the \fBreturn\fP builtin forces
4171 \fIcommand\fP to complete;
4172 however, the rest of the execution environment,
4173 including the positional parameters, is shared with the caller.
4174 .PP
4175 If the first character following the open brace
4176 is a \fB|\fP, the construct expands to the
4177 value of the \fBREPLY\fP shell variable after \fIcommand\fP executes,
4178 without removing any trailing newlines,
4179 and the standard output of \fIcommand\fP remains the same as in the
4180 calling shell.
4181 \fBBash\fP creates \fBREPLY\fP as an initially-unset local variable when
4182 \fIcommand\fP executes, and restores \fBREPLY\fP to the value it had
4183 before the command substitution after \fIcommand\fP completes,
4184 as with any local variable.
4185 .PP
4186 Command substitutions may be nested. To nest when using the backquoted form,
4187 escape the inner backquotes with backslashes.
4188 .PP
4189 If the substitution appears within double quotes, \fBbash\fP does not perform
4190 word splitting and pathname expansion on the results.
4191 .SS Arithmetic Expansion
4192 Arithmetic expansion evaluates an arithmetic expression
4193 and substitutes the result.
4194 The format for arithmetic expansion is:
4195 .RS
4196 .PP
4197 \fB$((\fP\fIexpression\fP\fB))\fP
4198 .RE
4199 .PP
4200 The
4201 .I expression
4202 undergoes the same expansions
4203 as if it were within double quotes,
4204 but unescaped double quote characters
4205 in \fIexpression\fP are not treated
4206 specially and are removed.
4207 All tokens in the expression undergo parameter and variable expansion,
4208 command substitution, and quote removal.
4209 The result is treated as the arithmetic expression to be evaluated.
4210 Since the way Bash handles double quotes
4211 can potentially result in empty strings,
4212 arithmetic expansion treats
4213 those as expressions that evaluate to 0.
4214 Arithmetic expansions may be nested.
4215 .PP
4216 The evaluation is performed according to the rules listed below under
4217 .SM
4218 .BR "ARITHMETIC EVALUATION" .
4219 If
4220 .I expression
4221 is invalid,
4222 .B bash
4223 prints a message to standard error indicating failure,
4224 does not perform the substitution,
4225 and does not execute the command associated with the expansion.
4226 .SS Process Substitution
4227 \fIProcess substitution\fP allows a process's input or output to be
4228 referred to using a filename.
4229 It takes the form of
4230 \fB<(\fP\fIlist\^\fP\fB)\fP
4231 or
4232 \fB>(\fP\fIlist\^\fP\fB)\fP.
4233 The process \fIlist\fP is run asynchronously, and its input or output
4234 appears as a filename.
4235 This filename is
4236 passed as an argument to the current command as the result of the
4237 expansion.
4238 .PP
4239 If the
4240 \fB>(\fP\fIlist\^\fP\fB)\fP form is used, writing to
4241 the file provides input for \fIlist\fP.
4242 If the
4243 \fB<(\fP\fIlist\^\fP\fB)\fP form is used, reading the file
4244 obtains the output of \fIlist\fP.
4245 No space may appear between the \fB<\fP or \fB>\fP
4246 and the left parenthesis, otherwise the construct would be interpreted
4247 as a redirection.
4248 .PP
4249 Process substitution is supported on systems that support named
4250 pipes (\fIFIFOs\fP) or the \fI/dev/fd\fP method of naming open files.
4251 .PP
4252 When available, process substitution is performed
4253 simultaneously with parameter and variable expansion,
4254 command substitution,
4255 and arithmetic expansion.
4256 .SS Word Splitting
4257 The shell scans the results of
4258 parameter expansion,
4259 command substitution,
4260 and
4261 arithmetic expansion
4262 that did not occur within double quotes for
4263 .IR "word splitting" .
4264 Words that were not expanded are not split.
4265 .PP
4266 The shell treats each character of
4267 .SM
4268 .B IFS
4269 as a delimiter,
4270 and splits the results of the other expansions into words
4271 using these characters as field terminators.
4272 .PP
4273 An \fIIFS whitespace\fP character is whitespace as defined above
4274 (see \fBDefinitions\fP) that appears in the value of
4275 .SM
4276 .BR IFS .
4277 Space, tab, and newline are always considered IFS whitespace, even
4278 if they don't appear in the locale's \fBspace\fP category.
4279 .PP
4280 If
4281 .SM
4282 .B IFS
4283 is unset, field splitting acts as if its value were
4284 .BR <space><tab><newline> ,
4285 and treats these characters as IFS whitespace.
4286 If the value of
4287 .SM
4288 .B IFS
4289 is null, no word splitting occurs,
4290 but implicit null arguments (see below) are still removed.
4291 .PP
4292 Word splitting begins by removing sequences of IFS whitespace characters
4293 from the beginning and end of the results of the previous expansions,
4294 then splits the remaining words.
4295 .PP
4296 If the value of
4297 .SM
4298 .B IFS
4299 consists solely of IFS whitespace,
4300 any sequence of IFS whitespace characters delimits a field,
4301 so a field consists of characters that are not unquoted IFS
4302 whitespace, and null fields result only from quoting.
4303 .PP
4304 If
4305 .SM
4306 .B IFS
4307 contains a non-whitespace character, then any character in
4308 the value of
4309 .SM
4310 .B IFS
4311 that is not IFS whitespace,
4312 along with any adjacent IFS whitespace characters, delimits a field.
4313 This means that adjacent non-IFS-whitespace delimiters produce a
4314 null field.
4315 A sequence of IFS whitespace characters also delimits a field.
4316 .PP
4317 Explicit null arguments (\^\fB\*"\^\*"\fP or
4318 \^\fB\*'\^\*'\fP\^) are retained
4319 and passed to commands as empty strings.
4320 Unquoted implicit null arguments, resulting from the expansion of
4321 parameters that have no values, are removed.
4322 Expanding a parameter with no value within double quotes
4323 produces a null field,
4324 which is retained and passed to a command as an empty string.
4325 .PP
4326 When a quoted null argument appears as part of a word whose expansion is
4327 non-null, word splitting removes the null argument portion,
4328 leaving the non-null expansion.
4329 That is, the word
4330 .Q "\-d\*'\^\*'"
4331 becomes
4332 .Q \-d
4333 after word splitting and null argument removal.
4334 .SS "Pathname Expansion"
4335 After word splitting,
4336 unless the
4337 .B \-f
4338 option has been set,
4339 .B bash
4340 scans each word for the characters
4341 .BR * ,
4342 .BR ? ,
4343 and
4344 .BR [ .
4345 If one of these characters appears, and is not quoted, then the word is
4346 regarded as a
4347 .IR pattern ,
4348 and replaced with a sorted list of filenames matching the pattern
4349 (see
4350 .SM
4351 .B "Pattern Matching"
4352 below)
4353 subject to the value of the \fBGLOBSORT\fP shell variable.
4354 .PP
4355 If no matching filenames are found,
4356 and the shell option
4357 .B nullglob
4358 is not enabled, the word is left unchanged.
4359 If the
4360 .B nullglob
4361 option is set, and no matches are found,
4362 the word is removed.
4363 If the
4364 .B failglob
4365 shell option is set, and no matches are found,
4366 \fBbash\fP prints an error message and does not execute the command.
4367 If the shell option
4368 .B nocaseglob
4369 is enabled, the match is performed without regard to the case
4370 of alphabetic characters.
4371 .PP
4372 When a pattern is used for pathname expansion,
4373 the character
4374 .Q .\&
4375 at the start of a name or immediately following a slash
4376 must be matched explicitly, unless the shell option
4377 .B dotglob
4378 is set.
4379 In order to match the filenames
4380 .FN .\&
4381 and
4382 .FN ..\& ,
4383 the pattern must begin with
4384 .Q .\&
4385 (for example,
4386 .Q .?\& ),
4387 even if
4388 .B dotglob
4389 is set.
4390 If the
4391 .B globskipdots
4392 shell option is enabled, the filenames
4393 .FN .\&
4394 and
4395 .FN ..\&
4396 never match, even if the pattern begins with a
4397 .Q .\& .
4398 When not matching pathnames, the
4399 .Q .\&
4400 character is not treated specially.
4401 .PP
4402 When matching a pathname, the slash character must always be
4403 matched explicitly by a slash in the pattern, but in other matching
4404 contexts it can be matched by a special pattern character as described
4405 below under
4406 .SM
4407 .BR "Pattern Matching" .
4408 .PP
4409 See the description of
4410 .B shopt
4411 below under
4412 .SM
4413 .B "SHELL BUILTIN COMMANDS"
4414 for a description of the
4415 .BR nocaseglob ,
4416 .BR nullglob ,
4417 .BR globskipdots ,
4418 .BR failglob ,
4419 and
4420 .B dotglob
4421 shell options.
4422 .PP
4423 The
4424 .SM
4425 .B GLOBIGNORE
4426 shell variable may be used to restrict the set of file names matching a
4427 .IR pattern .
4428 If
4429 .SM
4430 .B GLOBIGNORE
4431 is set, each matching file name that also matches one of the patterns in
4432 .SM
4433 .B GLOBIGNORE
4434 is removed from the list of matches.
4435 If the \fBnocaseglob\fP option is set, the matching against the patterns in
4436 .SM
4437 .B GLOBIGNORE
4438 is performed without regard to case.
4439 The filenames
4440 .FN .\&
4441 and
4442 .FN ..\&
4443 are always ignored when
4444 .SM
4445 .B GLOBIGNORE
4446 is set and not null.
4447 However, setting
4448 .SM
4449 .B GLOBIGNORE
4450 to a non-null value has the effect of enabling the
4451 .B dotglob
4452 shell option, so all other filenames beginning with a
4453 .Q .\&
4454 match.
4455 To get the old behavior of ignoring filenames beginning with a
4456 .Q .\& ,
4457 make
4458 .Q .*
4459 one of the patterns in
4460 .SM
4461 .B GLOBIGNORE\c
4462 \&.
4463 The
4464 .B dotglob
4465 option is disabled when
4466 .SM
4467 .B GLOBIGNORE
4468 is unset.
4469 The
4470 .B GLOBIGNORE
4471 pattern matching honors the setting of the \fBextglob\fP shell
4472 option.
4473 .PP
4474 The value of the
4475 .SM
4476 .B GLOBSORT
4477 shell variable controls how the results of pathname expansion are sorted,
4478 as described above under
4479 .BR "Shell Variables" .
4480 .PP
4481 .B "Pattern Matching"
4482 .PP
4483 Any character that appears in a pattern, other than the special pattern
4484 characters described below, matches itself.
4485 The NUL character may not occur in a pattern.
4486 A backslash escapes the following character; the escaping backslash is
4487 discarded when matching.
4488 The special pattern characters must be quoted if
4489 they are to be matched literally.
4490 .PP
4491 The special pattern characters have the following meanings:
4492 .PP
4493 .PD 0
4494 .RS
4495 .TP
4496 .B *
4497 Matches any string, including the null string.
4498 When the \fBglobstar\fP shell option is enabled, and \fB*\fP is used in
4499 a pathname expansion context, two adjacent \fB*\fPs used as a single
4500 pattern match all files and zero or more directories and
4501 subdirectories.
4502 If followed by a \fB/\fP, two adjacent \fB*\fPs match only directories
4503 and subdirectories.
4504 .TP
4505 .B ?
4506 Matches any single character.
4507 .TP
4508 .BR [ .\|.\|. ]
4509 .PD
4510 Matches any one of the characters enclosed between the brackets.
4511 This is known as a \fIbracket expression\fP
4512 and matches a single character.
4513 A pair of characters separated by a hyphen denotes a
4514 \fIrange expression\fP;
4515 any character that falls between those two characters, inclusive,
4516 using the current locale's collating sequence and character set, matches.
4517 If the first character following the
4518 .B [
4519 is a
4520 .B !
4521 or a
4522 .B \*^
4523 then any character not within the range matches.
4524 To match a
4525 .BR \- ,
4526 include it as the first or last character in the set.
4527 To match a
4528 .BR ] ,
4529 include it as the first character in the set.
4530 .IP
4531 The sorting order of characters in range expressions,
4532 and the characters included in the range,
4533 are determined by the current locale and the values of the
4534 .SM
4535 .B LC_COLLATE
4536 or
4537 .SM
4538 .B LC_ALL
4539 shell variables, if set.
4540 To obtain the traditional interpretation of range expressions, where
4541 .B [a\-d]
4542 is equivalent to
4543 .BR [abcd] ,
4544 set the value of the
4545 .B LC_COLLATE
4546 or
4547 .B LC_ALL
4548 shell variables to
4549 .BR C ,
4550 or enable the
4551 .B globasciiranges
4552 shell option.
4553 .IP
4554 Within a bracket expression,
4555 \fIcharacter classes\fP can be specified using the syntax
4556 \fB[:\fP\fIclass\fP\fB:]\fP, where \fIclass\fP is one of the
4557 following classes defined in the
4558 .SM POSIX
4559 standard:
4560 .IP
4561 .RS
4562 .B
4563 .if n alnum alpha ascii blank cntrl digit graph lower print punct space \
4564 upper word xdigit
4565 .if t alnum alpha ascii blank cntrl digit graph lower \
4566 print punct space upper word xdigit
4567 .RE
4568 .IP
4569 A character class matches any character belonging to that class.
4570 The \fBword\fP character class matches letters, digits, and the character _.
4571 .IP
4572 Within a bracket expression,
4573 an \fIequivalence class\fP can be specified using the syntax
4574 \fB[=\fP\fIc\fP\fB=]\fP, which matches all characters with the
4575 same collation weight (as defined by the current locale) as
4576 the character \fIc\fP.
4577 .IP
4578 Within a bracket expression,
4579 the syntax \fB[.\fP\fIsymbol\fP\fB.]\fP matches the collating symbol
4580 \fIsymbol\fP.
4581 .RE
4582 .PP
4583 If the \fBextglob\fP shell option is enabled using the \fBshopt\fP
4584 builtin, the shell recognizes several extended pattern matching operators.
4585 In the following description, a \fIpattern-list\fP is a list of one
4586 or more patterns separated by a \fB|\fP.
4587 Composite patterns may be formed using one or more of the following
4588 sub-patterns:
4589 .PP
4590 .PD 0
4591 .RS
4592 .TP
4593 \fB?(\fP\^\fIpattern-list\^\fP\fB)\fP
4594 Matches zero or one occurrence of the given patterns.
4595 .TP
4596 \fB*(\fP\^\fIpattern-list\^\fP\fB)\fP
4597 Matches zero or more occurrences of the given patterns.
4598 .TP
4599 \fB+(\fP\^\fIpattern-list\^\fP\fB)\fP
4600 Matches one or more occurrences of the given patterns.
4601 .TP
4602 \fB@(\fP\^\fIpattern-list\^\fP\fB)\fP
4603 Matches one of the given patterns.
4604 .TP
4605 \fB!(\fP\^\fIpattern-list\^\fP\fB)\fP
4606 Matches anything except one of the given patterns.
4607 .RE
4608 .PD
4609 .PP
4610 The \fBextglob\fP option changes the behavior of the parser, since the
4611 parentheses are normally treated as operators with syntactic meaning.
4612 To ensure that extended matching patterns are parsed correctly, make sure
4613 that \fBextglob\fP is enabled before parsing constructs containing the
4614 patterns, including shell functions and command substitutions.
4615 .PP
4616 When matching filenames, the \fBdotglob\fP shell option determines
4617 the set of filenames that are tested:
4618 when \fBdotglob\fP is enabled, the set of filenames includes all files
4619 beginning with
4620 .Q .\& ,
4621 but
4622 .FN .\&
4623 and
4624 .FN ..\&
4625 must be matched by a pattern or sub-pattern that begins with a dot;
4626 when it is disabled, the set does not
4627 include any filenames beginning with
4628 .Q .\&
4629 unless the pattern or sub-pattern begins with a
4630 .Q .\& .
4631 If the
4632 .B globskipdots
4633 shell option is enabled, the filenames
4634 .FN .\&
4635 and
4636 .FN ..\&
4637 never appear in the set.
4638 As above,
4639 .Q .\&
4640 only has a special meaning when matching filenames.
4641 .PP
4642 Complicated extended pattern matching against long strings is slow,
4643 especially when the patterns contain alternations and the strings
4644 contain multiple matches.
4645 Using separate matches against shorter strings, or using arrays of
4646 strings instead of a single long string, may be faster.
4647 .SS Quote Removal
4648 After the preceding expansions, all unquoted occurrences of the
4649 characters
4650 .BR \e ,
4651 .BR \*' ,
4652 and \^\fB\*"\fP\^ that did not result from one of the above
4653 expansions are removed.
4654 .SH REDIRECTION
4655 Before a command is executed, its input and output may be
4656 .I redirected
4657 using a special notation interpreted by the shell.
4658 \fIRedirection\fP allows commands' file handles to be
4659 duplicated, opened, closed,
4660 made to refer to different files,
4661 and can change the files the command reads from and writes to.
4662 When used with the \fBexec\fP builtin,
4663 redirections modify file handles in the current shell execution environment.
4664 The following redirection
4665 operators may precede or appear anywhere within a
4666 .I simple command
4667 or may follow a
4668 .IR command .
4669 Redirections are processed in the order they appear, from
4670 left to right.
4671 .PP
4672 Each redirection that may be preceded by a file descriptor number
4673 may instead be preceded by a word of the form {\fIvarname\fP}.
4674 In this case, for each redirection operator except
4675 .B >&\-
4676 and
4677 .BR <&\- ,
4678 the shell allocates a file descriptor greater
4679 than or equal to 10 and assigns it to \fIvarname\fP.
4680 If {\fIvarname\fP} precedes
4681 .B >&\-
4682 or
4683 .BR <&\- ,
4684 the value of \fIvarname\fP defines the file descriptor to close.
4685 If {\fIvarname\fP} is supplied, the redirection persists beyond
4686 the scope of the command, which allows the shell programmer to
4687 manage the file descriptor's lifetime manually without using
4688 the \fBexec\fP builtin.
4689 The \fBvarredir_close\fP shell option manages this behavior.
4690 .PP
4691 In the following descriptions, if the file descriptor number is
4692 omitted, and the first character of the redirection operator is
4693 .Q < ,
4694 the redirection refers to the standard input (file descriptor 0).
4695 If the first character of the redirection operator is
4696 .Q > ,
4697 the redirection refers to the standard output (file descriptor 1).
4698 .PP
4699 The \fIword\fP following the redirection operator in the following
4700 descriptions, unless otherwise noted, is subjected to
4701 brace expansion,
4702 tilde expansion,
4703 parameter and variable expansion,
4704 command substitution,
4705 arithmetic expansion,
4706 quote removal,
4707 pathname expansion,
4708 and word splitting.
4709 If it expands to more than one word,
4710 .B bash
4711 reports an error.
4712 .PP
4713 The order of redirections is significant.
4714 For example,
4715 the command
4716 .RS
4717 .PP
4718 ls \fB>\fP dirlist 2\fB>&\fP1
4719 .RE
4720 .PP
4721 directs both standard output and standard error to the file
4722 .IR dirlist ,
4723 while the command
4724 .RS
4725 .PP
4726 ls 2\fB>&\fP1 \fB>\fP dirlist
4727 .RE
4728 .PP
4729 directs only the standard output to file
4730 .IR dirlist ,
4731 because the standard error was directed to the standard output
4732 before the standard output was redirected to
4733 .IR dirlist .
4734 .PP
4735 \fBBash\fP handles several filenames specially when they are used in
4736 redirections, as described in the following table.
4737 If the operating system on which \fBbash\fP is running provides these
4738 special files, \fBbash\fP uses them; otherwise it emulates them
4739 internally with the behavior described below.
4740 .RS
4741 .PP
4742 .PD 0
4743 .TP
4744 .B /dev/fd/\fIfd\fP
4745 If \fIfd\fP is a valid integer, duplicate file descriptor \fIfd\fP.
4746 .TP
4747 .B /dev/stdin
4748 File descriptor 0 is duplicated.
4749 .TP
4750 .B /dev/stdout
4751 File descriptor 1 is duplicated.
4752 .TP
4753 .B /dev/stderr
4754 File descriptor 2 is duplicated.
4755 .TP
4756 .B /dev/tcp/\fIhost\fP/\fIport\fP
4757 If \fIhost\fP is a valid hostname or Internet address, and \fIport\fP
4758 is an integer port number or service name, \fBbash\fP attempts to open
4759 the corresponding TCP socket.
4760 .TP
4761 .B /dev/udp/\fIhost\fP/\fIport\fP
4762 If \fIhost\fP is a valid hostname or Internet address, and \fIport\fP
4763 is an integer port number or service name, \fBbash\fP attempts to open
4764 the corresponding UDP socket.
4765 .PD
4766 .RE
4767 .PP
4768 A failure to open or create a file causes the redirection to fail.
4769 .PP
4770 Redirections using file descriptors greater than 9 should be used with
4771 care, as they may conflict with file descriptors the shell uses
4772 internally.
4773 .SS Redirecting Input
4774 Redirecting input opens the file whose name results from
4775 the expansion of
4776 .I word
4777 for reading on file descriptor
4778 .IR n ,
4779 or the standard input (file descriptor 0) if
4780 .I n
4781 is not specified.
4782 .PP
4783 The general format for redirecting input is:
4784 .RS
4785 .PP
4786 [\fIn\fP]\fB<\fP\fIword\fP
4787 .RE
4788 .SS Redirecting Output
4789 Redirecting output opens the file whose name results from
4790 the expansion of
4791 .I word
4792 for writing on file descriptor
4793 .IR n ,
4794 or the standard output (file descriptor 1) if
4795 .I n
4796 is not specified.
4797 If the file does not exist it is created;
4798 if it does exist it is truncated to zero size.
4799 .PP
4800 The general format for redirecting output is:
4801 .RS
4802 .PP
4803 [\fIn\fP]\fB>\fP\fIword\fP
4804 .RE
4805 .PP
4806 If the redirection operator is
4807 .BR > ,
4808 and the
4809 .B noclobber
4810 option to the
4811 .B set
4812 builtin command has been enabled, the redirection fails if the file
4813 whose name results from the expansion of \fIword\fP exists and is
4814 a regular file.
4815 If the redirection operator is
4816 .BR >| ,
4817 or the redirection operator is
4818 .B >
4819 and the
4820 .B noclobber
4821 option to the
4822 .B set
4823 builtin is not enabled,
4824 \fBbash\fP attempts the redirection
4825 even if the file named by \fIword\fP exists.
4826 .SS Appending Redirected Output
4827 Redirecting output in this fashion opens
4828 the file whose name results from the expansion of
4829 .I word
4830 for appending on file descriptor
4831 .IR n ,
4832 or the standard output (file descriptor 1) if
4833 .I n
4834 is not specified.
4835 If the file does not exist it is created.
4836 .PP
4837 The general format for appending output is:
4838 .RS
4839 .PP
4840 [\fIn\fP]\fB>>\fP\fIword\fP
4841 .RE
4842 .SS Redirecting Standard Output and Standard Error
4843 This construct redirects both the
4844 standard output (file descriptor 1) and
4845 the standard error output (file descriptor 2)
4846 to the file whose name is the expansion of
4847 .IR word .
4848 .PP
4849 There are two formats for redirecting standard output and
4850 standard error:
4851 .RS
4852 .PP
4853 \fB&>\fP\fIword\fP
4854 .RE
4855 and
4856 .RS
4857 \fB>&\fP\fIword\fP
4858 .RE
4859 .PP
4860 Of the two forms, the first is preferred.
4861 This is semantically equivalent to
4862 .RS
4863 .PP
4864 \fB>\fP\fIword\fP 2\fB>&\fP1
4865 .RE
4866 .PP
4867 When using the second form, \fIword\fP may not expand to a number or
4868 \fB\-\fP.
4869 If it does, other redirection operators apply
4870 (see \fBDuplicating File Descriptors\fP below) for compatibility
4871 reasons.
4872 .SS Appending Standard Output and Standard Error
4873 This construct appends both the
4874 standard output (file descriptor 1) and
4875 the standard error output (file descriptor 2)
4876 to the file whose name is the expansion of
4877 .IR word .
4878 .PP
4879 The format for appending standard output and standard error is:
4880 .RS
4881 .PP
4882 \fB&>>\fP\fIword\fP
4883 .RE
4884 .PP
4885 This is semantically equivalent to
4886 .RS
4887 .PP
4888 \fB>>\fP\fIword\fP 2\fB>&\fP1
4889 .RE
4890 .PP
4891 (see \fBDuplicating File Descriptors\fP below).
4892 .SS Here Documents
4893 This type of redirection instructs the shell to read input from the
4894 current source until it reads a line containing only
4895 .I delimiter
4896 (with no trailing blanks).
4897 All of the lines read up to that point then become the standard
4898 input (or file descriptor \fIn\fP if \fIn\fP is specified) for a command.
4899 .PP
4900 The format of here-documents is:
4901 .RS
4902 .PP
4903 .nf
4904 [\fIn\fP]\fB<<\fP[\fB\-\fP]\fIword\fP
4905 \fIhere-document\fP
4906 \fIdelimiter\fP
4907 .fi
4908 .RE
4909 .PP
4910 The shell does not perform
4911 parameter and variable expansion, command substitution,
4912 arithmetic expansion, or pathname expansion on
4913 .IR word .
4914 .PP
4915 If any part of
4916 .I word
4917 is quoted, the
4918 .I delimiter
4919 is the result of quote removal on
4920 .IR word ,
4921 and the lines in the here-document are not expanded.
4922 If \fIword\fP is unquoted, the
4923 .I delimiter
4924 is \fIword\fP itself,
4925 and the here-document text is treated similarly to a double-quoted string:
4926 all lines of the here-document are subjected to
4927 parameter expansion, command substitution, and arithmetic expansion,
4928 the character sequence
4929 .B \e<newline>
4930 is treated literally, and
4931 .B \e
4932 must be used to quote the characters
4933 .BR \e ,
4934 .BR $ ,
4935 and
4936 .BR \` ;
4937 however, double quote characters have no special meaning.
4938 .PP
4939 If the redirection operator is
4940 .BR <<\- ,
4941 then the shell strips all leading tab characters from input lines
4942 and the line containing
4943 .IR delimiter .
4944 This allows
4945 here-documents within shell scripts to be indented in a
4946 natural fashion.
4947 .PP
4948 If the delimiter is not quoted, the
4949 .B \e<newline>
4950 sequence is treated as a line continuation: the two lines are joined
4951 and the backslash-newline is removed.
4952 This happens while reading the here-document, before the check for
4953 the ending delimiter, so joined lines can form the end delimiter.
4954 .SS "Here Strings"
4955 A variant of here documents, the format is:
4956 .RS
4957 .PP
4958 .nf
4959 [\fIn\fP]\fB<<<\fP\fIword\fP
4960 .fi
4961 .RE
4962 .PP
4963 The \fIword\fP undergoes
4964 tilde expansion, parameter and variable expansion,
4965 command substitution, arithmetic expansion, and quote removal.
4966 Pathname expansion and word splitting are not performed.
4967 The result is supplied as a single string, with a newline appended,
4968 to the command on its
4969 standard input (or file descriptor \fIn\fP if \fIn\fP is specified).
4970 .SS "Duplicating File Descriptors"
4971 The redirection operator
4972 .RS
4973 .PP
4974 [\fIn\fP]\fB<&\fP\fIword\fP
4975 .RE
4976 .PP
4977 is used to duplicate input file descriptors.
4978 If
4979 .I word
4980 expands to one or more digits, file descriptor
4981 .I n
4982 is made to be a copy of that file descriptor.
4983 It is a redirection error if the digits in
4984 .I word
4985 do not specify a file descriptor open for input.
4986 If
4987 .I word
4988 evaluates to
4989 .BR \- ,
4990 file descriptor
4991 .I n
4992 is closed.
4993 If
4994 .I n
4995 is not specified, this uses the standard input (file descriptor 0).
4996 .PP
4997 The operator
4998 .RS
4999 .PP
5000 [\fIn\fP]\fB>&\fP\fIword\fP
5001 .RE
5002 .PP
5003 is used similarly to duplicate output file descriptors.
5004 If
5005 .I n
5006 is not specified, this uses the standard output (file descriptor 1).
5007 It is a redirection error if the digits in
5008 .I word
5009 do not specify a file descriptor open for output.
5010 If
5011 .I word
5012 evaluates to
5013 .BR \- ,
5014 file descriptor
5015 .I n
5016 is closed.
5017 As a special case, if \fIn\fP is omitted,
5018 and \fIword\fP does not expand to one or more digits or \fB\-\fP,
5019 this redirects the standard output and standard error as described
5020 previously.
5021 .SS "Moving File Descriptors"
5022 The redirection operator
5023 .RS
5024 .PP
5025 [\fIn\fP]\fB<&\fP\fIdigit\fP\fB\-\fP
5026 .RE
5027 .PP
5028 moves the file descriptor \fIdigit\fP to file descriptor
5029 .IR n ,
5030 or the standard input (file descriptor 0) if \fIn\fP is not specified.
5031 \fIdigit\fP is closed after being duplicated to \fIn\fP.
5032 .PP
5033 Similarly, the redirection operator
5034 .RS
5035 .PP
5036 [\fIn\fP]\fB>&\fP\fIdigit\fP\fB\-\fP
5037 .RE
5038 .PP
5039 moves the file descriptor \fIdigit\fP to file descriptor
5040 .IR n ,
5041 or the standard output (file descriptor 1) if \fIn\fP is not specified.
5042 .SS "Opening File Descriptors for Reading and Writing"
5043 The redirection operator
5044 .RS
5045 .PP
5046 [\fIn\fP]\fB<>\fP\fIword\fP
5047 .RE
5048 .PP
5049 opens the file whose name is the expansion of
5050 .I word
5051 for both reading and writing on file descriptor
5052 .IR n ,
5053 or on file descriptor 0 if
5054 .I n
5055 is not specified.
5056 If the file does not exist, it is created.
5057 .SH ALIASES
5058 \fIAliases\fP allow a string to be substituted for a word that is in
5059 a position in the input where it can be the first word of a simple
5060 command.
5061 Aliases have names and corresponding values that are set
5062 and unset using the \fBalias\fP and \fBunalias\fP builtin commands
5063 (see
5064 .SM
5065 .B "SHELL BUILTIN COMMANDS"
5066 below).
5067 .PP
5068 If the shell reads an unquoted word in the right position, it checks
5069 the word to see if it matches an alias name.
5070 If it matches, the shell
5071 replaces the word with the alias value, and reads that value as if it
5072 had been read instead of the word.
5073 The shell doesn't look at any characters following the word before
5074 attempting alias substitution.
5075 .PP
5076 The characters \fB/\fP, \fB$\fP, \fB\`\fP, and \fB=\fP and
5077 any of the shell \fImetacharacters\fP or quoting characters
5078 listed above may not appear in an alias name.
5079 The replacement text may contain any valid shell input,
5080 including shell metacharacters.
5081 The first word of the replacement text is tested
5082 for aliases, but a word that is identical to an alias being expanded
5083 is not expanded a second time.
5084 This means that one may alias
5085 .B ls
5086 to
5087 .BR "ls \-F" ,
5088 for instance, and
5089 .B bash
5090 does not try to recursively expand the replacement text.
5091 .PP
5092 If the last character of the alias value is a
5093 .IR blank ,
5094 the shell checks the next command
5095 word following the alias for alias expansion.
5096 .PP
5097 Aliases are created and listed with the
5098 .B alias
5099 command, and removed with the
5100 .B unalias
5101 command.
5102 .PP
5103 There is no mechanism for using arguments in the replacement text.
5104 If arguments are needed, use a shell function (see
5105 .SM
5106 .B FUNCTIONS
5107 below) instead.
5108 .PP
5109 Aliases are not expanded when the shell is not interactive, unless
5110 the
5111 .B expand_aliases
5112 shell option is set using
5113 .B shopt
5114 (see the description of
5115 .B shopt
5116 under
5117 .SM
5118 .B "SHELL BUILTIN COMMANDS"
5119 below).
5120 .PP
5121 The rules concerning the definition and use of aliases are
5122 somewhat confusing.
5123 .B Bash
5124 always reads at least one complete line of input,
5125 and all lines that make up a compound command,
5126 before executing any of the commands on that line or the compound command.
5127 Aliases are expanded when a command is read, not when it is executed.
5128 Therefore, an
5129 alias definition appearing on the same line as another
5130 command does not take effect until the shell reads the next line of input,
5131 and an alias definition in a compound command does not take
5132 effect until the shell parses and executes the entire compound command.
5133 The commands following the alias definition
5134 on that line,
5135 or in the rest of a compound command,
5136 are not affected by the new alias.
5137 This behavior is also an issue when functions are executed.
5138 Aliases are expanded when a function definition is read,
5139 not when the function is executed, because a function definition
5140 is itself a command.
5141 As a consequence, aliases
5142 defined in a function are not available until after that
5143 function is executed.
5144 To be safe, always put
5145 alias definitions on a separate line, and do not use
5146 .B alias
5147 in compound commands.
5148 .PP
5149 For almost every purpose, shell functions are preferable to aliases.
5150 .SH FUNCTIONS
5151 A shell function, defined as described above under
5152 .SM
5153 .BR "SHELL GRAMMAR" ,
5154 stores a series of commands for later execution.
5155 When the name of a shell function is used as a simple command name,
5156 the shell executes
5157 the list of commands associated with that function name.
5158 Functions are executed in the context of the
5159 calling shell; there is no new process created to interpret
5160 them (contrast this with the execution of a shell script).
5161 .PP
5162 When a function is executed, the arguments to the
5163 function become the positional parameters
5164 during its execution.
5165 The special parameter
5166 .B #
5167 is updated to reflect the new positional parameters.
5168 Special parameter \fB0\fP is unchanged.
5169 The first element of the
5170 .SM
5171 .B FUNCNAME
5172 variable is set to the name of the function while the function
5173 is executing.
5174 .PP
5175 All other aspects of the shell execution
5176 environment are identical between a function and its caller
5177 with these exceptions: the
5178 .SM
5179 .B DEBUG
5180 and
5181 .B RETURN
5182 traps (see the description of the
5183 .B trap
5184 builtin under
5185 .SM
5186 .B "SHELL BUILTIN COMMANDS"
5187 below) are not inherited unless the function has been given the
5188 \fBtrace\fP attribute (see the description of the
5189 .SM
5190 .B declare
5191 builtin below) or the
5192 \fB\-o functrace\fP shell option has been enabled with
5193 the \fBset\fP builtin
5194 (in which case all functions inherit the \fBDEBUG\fP and \fBRETURN\fP traps),
5195 and the
5196 .SM
5197 .B ERR
5198 trap is not inherited unless the \fB\-o errtrace\fP shell option has
5199 been enabled.
5200 .PP
5201 Variables local to the function are declared with the
5202 .B local
5203 builtin command (\fIlocal variables\fP).
5204 Ordinarily, variables and their values
5205 are shared between the function and its caller.
5206 If a variable is declared \fBlocal\fP, the variable's visible scope
5207 is restricted to that function and its children (including the functions
5208 it calls).
5209 .PP
5210 In the following description, the \fIcurrent scope\fP is a currently-
5211 executing function.
5212 Previous scopes consist of that function's caller and so on,
5213 back to the
5214 .Q global
5215 scope, where the shell is not executing any shell function.
5216 A local variable at the current scope is a variable
5217 declared using the \fBlocal\fP or \fBdeclare\fP builtins in the
5218 function that is currently executing.
5219 .PP
5220 Local variables
5221 .Q shadow
5222 variables with the same name declared at previous scopes.
5223 For instance, a local variable declared in a function
5224 hides variables with the same name declared at previous scopes,
5225 including global variables: references and assignments
5226 refer to the local variable, leaving the variables
5227 at previous scopes unmodified.
5228 When the function returns, the global variable is once again visible.
5229 .PP
5230 The shell uses \fIdynamic scoping\fP to control a variable's visibility
5231 within functions.
5232 With dynamic scoping, visible variables and their values
5233 are a result of the sequence of function calls that caused execution
5234 to reach the current function.
5235 The value of a variable that a function sees depends
5236 on its value within its caller, if any, whether that caller is
5237 the global
5238 scope or another shell function.
5239 This is also the value that a local variable
5240 declaration shadows,
5241 and the value that is restored when the function returns.
5242 .PP
5243 For example, if a variable \fIvar\fP is declared as local in function
5244 \fIfunc1\fP, and \fIfunc1\fP calls another function \fIfunc2\fP,
5245 references to \fIvar\fP made from within \fIfunc2\fP resolve to the
5246 local variable \fIvar\fP from \fIfunc1\fP, shadowing any global variable
5247 named \fIvar\fP.
5248 .PP
5249 The \fBunset\fP builtin also acts using the same dynamic scope: if a
5250 variable is local to the current scope, \fBunset\fP unsets it;
5251 otherwise the unset will refer to the variable found in any calling scope
5252 as described above.
5253 If a variable at the current local scope is unset, it remains so
5254 (appearing as unset)
5255 until it is reset in that scope or until the function returns.
5256 Once the function returns, any instance of the variable at a previous
5257 scope becomes visible.
5258 If the unset acts on a variable at a previous scope, any instance of a
5259 variable with that name that had been shadowed becomes visible
5260 (see below how the \fBlocalvar_unset\fP shell option changes this behavior).
5261 .PP
5262 The
5263 .SM
5264 .B FUNCNEST
5265 variable, if set to a numeric value greater
5266 than 0, defines a maximum function nesting level.
5267 Function invocations that exceed the limit cause the entire command to
5268 abort.
5269 .PP
5270 If the builtin command
5271 .B return
5272 is executed in a function, the function completes and
5273 execution resumes with the next command after the function
5274 call.
5275 If \fBreturn\fP is supplied a numeric argument,
5276 that is the function's return status; otherwise the function's
5277 return status is the exit status of the last command executed
5278 before the \fBreturn\fP.
5279 Any command associated with the \fBRETURN\fP trap is executed
5280 before execution resumes.
5281 When a function completes, the values of the
5282 positional parameters and the special parameter
5283 .B #
5284 are restored to the values they had prior to the function's
5285 execution.
5286 .PP
5287 The
5288 .B \-f
5289 option to the
5290 .B declare
5291 or
5292 .B typeset
5293 builtin commands
5294 lists function names and definitions.
5295 The
5296 .B \-F
5297 option to
5298 .B declare
5299 or
5300 .B typeset
5301 lists the function names only
5302 (and optionally the source file and line number, if the \fBextdebug\fP
5303 shell option is enabled).
5304 Functions may be exported so that child shell processes
5305 (those created when executing a separate shell invocation)
5306 automatically have them defined with the
5307 .B \-f
5308 option to the
5309 .B export
5310 builtin.
5311 The \fB\-f\fP option to
5312 the
5313 .B unset
5314 builtin deletes a function definition.
5315 .PP
5316 Functions may be recursive.
5317 The \fBFUNCNEST\fP variable may be used to limit the depth of the
5318 function call stack and restrict the number of function invocations.
5319 By default, \fBbash\fP imposes no limit on the number of recursive calls.
5320 .SH "ARITHMETIC EVALUATION"
5321 The shell allows arithmetic expressions to be evaluated, under
5322 certain circumstances
5323 (see the \fBlet\fP and \fBdeclare\fP builtin commands,
5324 the \fB((\fP compound command,
5325 the arithmetic \fBfor\fP command,
5326 the \fB[[\fP conditional command,
5327 and \fBArithmetic Expansion\fP).
5328 .PP
5329 Evaluation is done in the largest fixed-width integers available,
5330 with no check for overflow,
5331 though division by 0 is trapped and flagged as an error.
5332 The operators and their precedence, associativity, and values
5333 are the same as in the C language.
5334 The following list of operators is grouped into levels of
5335 equal-precedence operators.
5336 The levels are listed in order of decreasing precedence.
5337 .PP
5338 .PD 0
5339 .TP
5340 .B \fIid\fP++ \fIid\fP\-\-
5341 variable post-increment and post-decrement
5342 .TP
5343 .B ++\fIid\fP \-\-\fIid\fP
5344 variable pre-increment and pre-decrement
5345 .TP
5346 .B \- +
5347 unary minus and plus
5348 .TP
5349 .B ! \*~
5350 logical and bitwise negation
5351 .TP
5352 .B **
5353 exponentiation
5354 .TP
5355 .B * / %
5356 multiplication, division, remainder
5357 .TP
5358 .B + \-
5359 addition, subtraction
5360 .TP
5361 .B << >>
5362 left and right bitwise shifts
5363 .TP
5364 .B <= >= < >
5365 comparison
5366 .TP
5367 .B == !=
5368 equality and inequality
5369 .TP
5370 .B &
5371 bitwise AND
5372 .TP
5373 .B \*^
5374 bitwise exclusive OR
5375 .TP
5376 .B |
5377 bitwise OR
5378 .TP
5379 .B &&
5380 logical AND
5381 .TP
5382 .B ||
5383 logical OR
5384 .TP
5385 .B \fIexpr\fP?\fIexpr\fP:\fIexpr\fP
5386 conditional operator
5387 .TP
5388 .B "= *= /= %= += \-= <<= >>= &= \*^= |="
5389 assignment
5390 .TP
5391 .B \fIexpr1\fP , \fIexpr2\fP
5392 comma
5393 .PD
5394 .PP
5395 Shell variables are allowed as operands; parameter expansion is
5396 performed before the expression is evaluated.
5397 Within an expression, shell variables may also be referenced by name
5398 without using the parameter expansion syntax.
5399 This means you can use "x", where \fIx\fP is a shell variable name,
5400 in an arithmetic expression, and the shell will evaluate its value as
5401 an expression and use the result.
5402 A shell variable that is null or unset evaluates to 0 when referenced
5403 by name in an expression.
5404 .PP
5405 The value of a variable is evaluated as an arithmetic expression
5406 when it is referenced, or when a variable which has been given the
5407 \fIinteger\fP attribute using \fBdeclare \-i\fP is assigned a value.
5408 A null value evaluates to 0.
5409 A shell variable need not have its \fIinteger\fP attribute
5410 turned on to be used in an expression.
5411 .PP
5412 Integer constants follow the C language definition, without suffixes or
5413 character constants.
5414 Constants with a leading 0 are interpreted as octal numbers.
5415 A leading 0x or 0X denotes hexadecimal.
5416 Otherwise, numbers take the form [\fIbase#\fP]n, where the optional \fIbase\fP
5417 is a decimal number between 2 and 64 representing the arithmetic
5418 base, and \fIn\fP is a number in that base.
5419 If \fIbase#\fP is omitted, then base 10 is used.
5420 When specifying \fIn\fP,
5421 if a non-digit is required,
5422 the digits greater than 9 are represented by the lowercase letters,
5423 the uppercase letters, @, and _, in that order.
5424 If \fIbase\fP is less than or equal to 36, lowercase and uppercase
5425 letters may be used interchangeably to represent numbers between 10
5426 and 35.
5427 .PP
5428 Operators are evaluated in precedence order.
5429 Sub-expressions in parentheses are evaluated first
5430 and may override the precedence rules above.
5431 .SH "CONDITIONAL EXPRESSIONS"
5432 Conditional expressions are used by the \fB[[\fP compound command and
5433 the \fBtest\fP and \fB[\fP builtin commands to test file attributes
5434 and perform string and arithmetic comparisons.
5435 The \fBtest\fP and \fB[\fP commands determine their behavior based on
5436 the number of arguments; see the descriptions of those commands for any
5437 other command-specific actions.
5438 .PP
5439 Expressions are formed from the unary or binary primaries listed below.
5440 Unary expressions are often used to examine the status of a file
5441 or shell variable.
5442 Binary operators are used for string, numeric, and file attribute
5443 comparisons.
5444 .PP
5445 \fBBash\fP handles several filenames specially when they are used in
5446 expressions.
5447 If the operating system on which \fBbash\fP is running provides these
5448 special files, bash will use them; otherwise it will emulate them
5449 internally with this behavior:
5450 If any \fIfile\fP argument to one of the primaries is of the form
5451 .FN /dev/fd/n ,
5452 then \fBbash\fP checks file descriptor \fIn\fP.
5453 If the \fIfile\fP argument to one of the primaries is one of
5454 .FN /dev/stdin ,
5455 .FN /dev/stdout ,
5456 or
5457 .FN /dev/stderr ,
5458 \fBbash\fP checks file descriptor 0, 1, or 2, respectively.
5459 .PP
5460 Unless otherwise specified, primaries that operate on files follow symbolic
5461 links and operate on the target of the link, rather than the link itself.
5462 .PP
5463 When used with \fB[[\fP,
5464 or when the shell is in posix mode,
5465 the \fB<\fP and \fB>\fP operators sort
5466 lexicographically using the current locale.
5467 When the shell is not in posix mode,
5468 the \fBtest\fP command sorts using ASCII ordering.
5469 .PP
5470 .PD 0
5471 .TP
5472 .B \-a \fIfile\fP
5473 True if \fIfile\fP exists.
5474 .TP
5475 .B \-b \fIfile\fP
5476 True if \fIfile\fP exists and is a block special file.
5477 .TP
5478 .B \-c \fIfile\fP
5479 True if \fIfile\fP exists and is a character special file.
5480 .TP
5481 .B \-d \fIfile\fP
5482 True if \fIfile\fP exists and is a directory.
5483 .TP
5484 .B \-e \fIfile\fP
5485 True if \fIfile\fP exists.
5486 .TP
5487 .B \-f \fIfile\fP
5488 True if \fIfile\fP exists and is a regular file.
5489 .TP
5490 .B \-g \fIfile\fP
5491 True if \fIfile\fP exists and is set-group-id.
5492 .TP
5493 .B \-h \fIfile\fP
5494 True if \fIfile\fP exists and is a symbolic link.
5495 .TP
5496 .B \-k \fIfile\fP
5497 True if \fIfile\fP exists and its
5498 .Q sticky
5499 bit is set.
5500 .TP
5501 .B \-p \fIfile\fP
5502 True if \fIfile\fP exists and is a named pipe (FIFO).
5503 .TP
5504 .B \-r \fIfile\fP
5505 True if \fIfile\fP exists and is readable.
5506 .TP
5507 .B \-s \fIfile\fP
5508 True if \fIfile\fP exists and has a size greater than zero.
5509 .TP
5510 .B \-t \fIfd\fP
5511 True if file descriptor
5512 .I fd
5513 is open and refers to a terminal.
5514 .TP
5515 .B \-u \fIfile\fP
5516 True if \fIfile\fP exists and its set-user-id bit is set.
5517 .TP
5518 .B \-w \fIfile\fP
5519 True if \fIfile\fP exists and is writable.
5520 .TP
5521 .B \-x \fIfile\fP
5522 True if \fIfile\fP exists and is executable.
5523 .TP
5524 .B \-G \fIfile\fP
5525 True if \fIfile\fP exists and is owned by the effective group id.
5526 .TP
5527 .B \-L \fIfile\fP
5528 True if \fIfile\fP exists and is a symbolic link.
5529 .TP
5530 .B \-N \fIfile\fP
5531 True if \fIfile\fP exists and has been modified since it was last
5532 accessed.
5533 .TP
5534 .B \-O \fIfile\fP
5535 True if \fIfile\fP exists and is owned by the effective user id.
5536 .TP
5537 .B \-S \fIfile\fP
5538 True if \fIfile\fP exists and is a socket.
5539 .TP
5540 .B \-o \fIoptname\fP
5541 True if the shell option
5542 .I optname
5543 is enabled.
5544 See the list of options under the description of the
5545 .B \-o
5546 option to the
5547 .B set
5548 builtin below.
5549 .TP
5550 .B \-v \fIvarname\fP
5551 True if the shell variable
5552 .I varname
5553 is set (has been assigned a value).
5554 If \fIvarname\fP is an indexed
5555 array variable name subscripted by \fI@\fP or \fI*\fP,
5556 this returns true if the array has any set elements.
5557 If \fIvarname\fP is an associative
5558 array variable name subscripted by \fI@\fP or \fI*\fP,
5559 this returns true if an element with that key is set.
5560 .TP
5561 .B \-R \fIvarname\fP
5562 True if the shell variable
5563 .I varname
5564 is set and is a name reference.
5565 .TP
5566 .B \-z \fIstring\fP
5567 True if the length of \fIstring\fP is zero.
5568 .TP
5569 \fIstring\fP
5570 .TP
5571 .B \-n \fIstring\fP
5572 True if the length of
5573 .I string
5574 is non-zero.
5575 .PD
5576 .TP
5577 \fIstring1\fP \fB==\fP \fIstring2\fP
5578 .PD 0
5579 .TP
5580 \fIstring1\fP \fB=\fP \fIstring2\fP
5581 True if the strings are equal.
5582 \fB=\fP should be used with the \fBtest\fP command for
5583 .SM POSIX
5584 conformance.
5585 When used with the \fB[[\fP command, this performs pattern matching as
5586 described above (\fBCompound Commands\fP).
5587 .TP
5588 \fIstring1\fP \fB!=\fP \fIstring2\fP
5589 True if the strings are not equal.
5590 .TP
5591 \fIstring1\fP \fB<\fP \fIstring2\fP
5592 True if \fIstring1\fP sorts before \fIstring2\fP lexicographically.
5593 .TP
5594 \fIstring1\fP \fB>\fP \fIstring2\fP
5595 True if \fIstring1\fP sorts after \fIstring2\fP lexicographically.
5596 .PD
5597 .TP
5598 .PD 0
5599 \fIfile1\fP \fB\-ef\fP \fIfile2\fP
5600 True if \fIfile1\fP and \fIfile2\fP refer to the same device and
5601 inode numbers.
5602 .TP
5603 \fIfile1\fP \-\fBnt\fP \fIfile2\fP
5604 True if \fIfile1\fP is newer (according to modification date) than \fIfile2\fP,
5605 or if \fIfile1\fP exists and \fPfile2\fP does not.
5606 .TP
5607 \fIfile1\fP \-\fBot\fP \fIfile2\fP
5608 True if \fIfile1\fP is older than \fIfile2\fP, or if \fIfile2\fP exists
5609 and \fIfile1\fP does not.
5610 .PD
5611 .TP
5612 .I \fIarg1\fP \fBOP\fP \fIarg2\fP
5613 .SM
5614 .B OP
5615 is one of
5616 .BR \-eq ,
5617 .BR \-ne ,
5618 .BR \-lt ,
5619 .BR \-le ,
5620 .BR \-gt ,
5621 or
5622 .BR \-ge .
5623 These arithmetic binary operators return true if \fIarg1\fP
5624 is equal to, not equal to, less than, less than or equal to,
5625 greater than, or greater than or equal to \fIarg2\fP, respectively.
5626 .I arg1
5627 and
5628 .I arg2
5629 may be positive or negative integers.
5630 When used with the \fB[[\fP command,
5631 .I arg1
5632 and
5633 .I arg2
5634 are evaluated as arithmetic expressions (see
5635 .SM
5636 .B "ARITHMETIC EVALUATION"
5637 above).
5638 Since the expansions the \fB[[\fP command performs on
5639 .I arg1
5640 and
5641 .I arg2
5642 can potentially result in empty strings,
5643 arithmetic expression evaluation treats
5644 those as expressions that evaluate to 0.
5645 .PD
5646 .SH "SIMPLE COMMAND EXPANSION"
5647 When the shell executes a simple command, it performs the following
5648 expansions, assignments, and redirections, from left to right, in
5649 the following order.
5650 .IP 1.
5651 The words that the parser has marked as variable assignments (those
5652 preceding the command name) and redirections are saved for later
5653 processing.
5654 .IP 2.
5655 The words that are not variable assignments or redirections are
5656 expanded.
5657 If any words remain after expansion, the first word
5658 is taken to be the name of the command and the remaining words are
5659 the arguments.
5660 .IP 3.
5661 Redirections are performed as described above under
5662 .SM
5663 .BR REDIRECTION .
5664 .IP 4.
5665 The text after the \fB=\fP in each variable assignment undergoes tilde
5666 expansion, parameter expansion, command substitution, arithmetic expansion,
5667 and quote removal before being assigned to the variable.
5668 .PP
5669 If no command name results, the variable assignments affect the current
5670 shell environment.
5671 In the case of such a command (one that consists only of assignment
5672 statements and redirections), assignment statements are performed before
5673 redirections.
5674 Otherwise, the variables are added to the environment
5675 of the executed command and do not affect the current shell environment.
5676 If any of the assignments attempts to assign a value to a readonly variable,
5677 an error occurs, and the command exits with a non-zero status.
5678 .PP
5679 If no command name results, redirections are performed, but do not
5680 affect the current shell environment.
5681 A redirection error causes the command to exit with a non-zero status.
5682 .PP
5683 If there is a command name left after expansion, execution proceeds as
5684 described below.
5685 Otherwise, the command exits.
5686 If one of the expansions contained a command substitution,
5687 the exit status of the command is the exit status of
5688 the last command substitution performed.
5689 If there were no command substitutions,
5690 the command exits with a zero status.
5691 .SH "COMMAND EXECUTION"
5692 After a command has been split into words, if it results in a
5693 simple command and an optional list of arguments, the shell performs
5694 the following actions.
5695 .PP
5696 If the command name contains no slashes, the shell attempts to
5697 locate it.
5698 If there exists a shell function by that name, that function is
5699 invoked as described above in
5700 .SM
5701 .BR FUNCTIONS .
5702 If the name does not match a function, the shell searches for
5703 it in the list of shell builtins.
5704 If a match is found, that builtin is invoked.
5705 .PP
5706 If the name is neither a shell function nor a builtin,
5707 and contains no slashes,
5708 .B bash
5709 searches each element of the
5710 .SM
5711 .B PATH
5712 for a directory containing an executable file by that name.
5713 .B Bash
5714 uses a hash table to remember the full pathnames of executable
5715 files (see
5716 .B hash
5717 under
5718 .SM
5719 .B "SHELL BUILTIN COMMANDS"
5720 below).
5721 Bash performs a full search of the directories in
5722 .SM
5723 .B PATH
5724 only if the command is not found in the hash table.
5725 If the search is unsuccessful, the shell searches for a defined shell
5726 function named \fBcommand_not_found_handle\fP.
5727 If that function exists, it is invoked in a separate execution environment
5728 with the original command and
5729 the original command's arguments as its arguments, and the function's
5730 exit status becomes the exit status of that subshell.
5731 If that function is not defined, the shell prints an error
5732 message and returns an exit status of 127.
5733 .PP
5734 If the search is successful, or if the command name contains
5735 one or more slashes, the shell executes the named program in a
5736 separate execution environment.
5737 Argument 0 is set to the name given, and the remaining arguments
5738 to the command are set to the arguments given, if any.
5739 .PP
5740 If this execution fails because the file is not in executable
5741 format, and the file is not a directory, it is assumed to be
5742 a \fIshell script\fP, a file containing shell commands,
5743 and the shell creates a new instance of itself to execute it.
5744 Bash tries to determine whether the file is a text file or a binary,
5745 and will not execute files it determines to be binaries.
5746 This subshell reinitializes itself, so
5747 that the effect is as if a new shell had been invoked
5748 to handle the script, with the exception that the locations of
5749 commands remembered by the parent (see
5750 .B hash
5751 below under
5752 .SM
5753 .B "SHELL BUILTIN COMMANDS"
5754 are retained by the child.
5755 .PP
5756 If the program is a file beginning with
5757 .BR #! ,
5758 the remainder of the first line specifies an interpreter
5759 for the program.
5760 The shell executes the
5761 specified interpreter on operating systems that do not
5762 handle this executable format themselves.
5763 The arguments to the
5764 interpreter consist of a single optional argument following the
5765 interpreter name on the first line of the program, followed
5766 by the name of the program, followed by the command
5767 arguments, if any.
5768 .SH "COMMAND EXECUTION ENVIRONMENT"
5769 The shell has an \fIexecution environment\fP, which consists of the
5770 following:
5771 .IP \(bu
5772 Open files inherited by the shell at invocation, as modified by
5773 redirections supplied to the \fBexec\fP builtin.
5774 .IP \(bu
5775 The current working directory as set by \fBcd\fP, \fBpushd\fP, or
5776 \fBpopd\fP, or inherited by the shell at invocation.
5777 .IP \(bu
5778 The file creation mode mask as set by \fBumask\fP or inherited from
5779 the shell's parent.
5780 .IP \(bu
5781 Current traps set by \fBtrap\fP.
5782 .IP \(bu
5783 Shell parameters that are set by variable assignment or with \fBset\fP
5784 or inherited from the shell's parent in the environment.
5785 .IP \(bu
5786 Shell functions defined during execution or inherited from the shell's
5787 parent in the environment.
5788 .IP \(bu
5789 Options enabled at invocation (either by default or with command-line
5790 arguments) or by \fBset\fP.
5791 .IP \(bu
5792 Options enabled by \fBshopt\fP.
5793 .IP \(bu
5794 Shell aliases defined with \fBalias\fP.
5795 .IP \(bu
5796 Various process IDs, including those of background jobs, the value
5797 of \fB$$\fP, and the value of
5798 .SM
5799 .BR PPID .
5800 .PP
5801 When a simple command other than a builtin or shell function
5802 is to be executed, it
5803 is invoked in a separate execution environment that consists of
5804 the following.
5805 Unless otherwise noted, the values are inherited from the shell.
5806 .IP \(bu
5807 The shell's open files, plus any modifications and additions specified
5808 by redirections to the command.
5809 .IP \(bu
5810 The current working directory.
5811 .IP \(bu
5812 The file creation mode mask.
5813 .IP \(bu
5814 Shell variables and functions marked for export, along with variables
5815 exported for the command, passed in the environment.
5816 .IP \(bu
5817 Traps caught by the shell are reset to the values inherited from the
5818 shell's parent, and traps ignored by the shell are ignored.
5819 .PP
5820 A command invoked in this separate environment cannot affect the
5821 shell's execution environment.
5822 .PP
5823 A \fIsubshell\fP is a copy of the shell process.
5824 .PP
5825 Command substitution, commands grouped with parentheses,
5826 and asynchronous commands are invoked in a
5827 subshell environment that is a duplicate of the shell environment,
5828 except that traps caught by the shell are reset to the values
5829 that the shell inherited from its parent at invocation.
5830 Builtin commands that are invoked as part of a pipeline,
5831 except possibly in the last element depending on the value of the
5832 \fBlastpipe\fP shell option,
5833 are also executed in a subshell environment.
5834 Changes made to the subshell environment
5835 cannot affect the shell's execution environment.
5836 .PP
5837 When the shell is in posix mode,
5838 subshells spawned to execute command substitutions inherit the value of
5839 the \fB\-e\fP option from their parent shell.
5840 When not in posix mode,
5841 \fBbash\fP clears the \fB\-e\fP option in such subshells.
5842 See the
5843 description of the \fBinherit_errexit\fP shell option below
5844 for how to control this behavior when not in posix mode.
5845 .PP
5846 If a command is followed by a \fB&\fP and job control is not active, the
5847 default standard input for the command is the empty file
5848 .FN /dev/null .
5849 Otherwise, the invoked command inherits the file descriptors of the calling
5850 shell as modified by redirections.
5851 .SH ENVIRONMENT
5852 When a program is invoked it is given an array of strings
5853 called the
5854 .IR environment .
5855 This is a list of
5856 \fIname\fP\-\fIvalue\fP pairs, of the form
5857 .IR "name\fR=\fPvalue" .
5858 .PP
5859 The shell provides several ways to manipulate the environment.
5860 On invocation, the shell scans its own environment and
5861 creates a parameter for each name found, automatically marking
5862 it for
5863 .I export
5864 to child processes.
5865 Executed commands inherit the environment.
5866 The
5867 .BR export ,
5868 .BR "declare \-x" ,
5869 and
5870 .B unset
5871 commands modify the environment by
5872 adding and deleting parameters and functions.
5873 If the value of a parameter
5874 in the environment is modified, the new value automatically
5875 becomes part of the environment, replacing the old.
5876 The environment
5877 inherited by any executed command consists of the shell's
5878 initial environment, whose values may be modified in the shell,
5879 less any pairs removed by the
5880 .B unset
5881 or
5882 .B "export \-n"
5883 commands, plus any additions via the
5884 .B export
5885 and
5886 .B "declare \-x"
5887 commands.
5888 .PP
5889 If any parameter assignments, as described above in
5890 .SM
5891 .BR PARAMETERS ,
5892 appear before a
5893 .IR "simple command" ,
5894 the variable assignments are part of that command's environment
5895 for as long as it executes.
5896 These assignment statements affect only the environment seen
5897 by that command.
5898 If these assignments precede a call to a shell function, the variables
5899 are local to the function and exported to that function's children.
5900 .PP
5901 If the
5902 .B \-k
5903 option is set (see the
5904 .B set
5905 builtin command below), then
5906 .I all
5907 parameter assignments are placed in the environment for a command,
5908 not just those that precede the command name.
5909 .PP
5910 When
5911 .B bash
5912 invokes an external command, the variable
5913 .B _
5914 is set to the full pathname of the command and passed to that
5915 command in its environment.
5916 .SH "EXIT STATUS"
5917 The exit status of an executed command is the value returned by the
5918 \fIwaitpid\fP system call or equivalent function.
5919 Exit statuses fall between 0 and 255, though, as explained below,
5920 the shell may use values above 125 specially.
5921 Exit statuses from shell builtins and compound commands are also
5922 limited to this range.
5923 Under certain circumstances, the shell will use special values to
5924 indicate specific failure modes.
5925 .PP
5926 For the shell's purposes, a command which exits with a
5927 zero exit status has succeeded.
5928 So while an exit status of zero indicates success, a non-zero
5929 exit status indicates failure.
5930 .PP
5931 When a command terminates on a fatal signal \fIN\fP, \fBbash\fP uses
5932 the value of 128+\fIN\fP as the exit status.
5933 .PP
5934 If a command is not found, the child process created to
5935 execute it returns a status of 127. If a command is found
5936 but is not executable, the return status is 126.
5937 .PP
5938 If a command fails because of an error during expansion or redirection,
5939 the exit status is greater than zero.
5940 .PP
5941 Shell builtin commands return a status of 0 (\fItrue\fP) if
5942 successful, and non-zero (\fIfalse\fP) if an error occurs
5943 while they execute.
5944 All builtins return an exit status of 2 to indicate incorrect usage,
5945 generally invalid options or missing arguments.
5946 .PP
5947 The exit status of the last command is available in the special
5948 parameter $?.
5949 .PP
5950 \fBBash\fP itself returns the exit status of the last command
5951 executed, unless a syntax error occurs, in which case it exits
5952 with a non-zero value.
5953 See also the \fBexit\fP builtin command below.
5954 .SH SIGNALS
5955 When \fBbash\fP is interactive, in the absence of any traps, it ignores
5956 .SM
5957 .B SIGTERM
5958 (so that \fBkill 0\fP does not kill an interactive shell),
5959 and catches and handles
5960 .SM
5961 .B SIGINT
5962 (so that the \fBwait\fP builtin is interruptible).
5963 When \fBbash\fP receives
5964 .SM
5965 .BR SIGINT ,
5966 it breaks out of any executing loops.
5967 In all cases, \fBbash\fP ignores
5968 .SM
5969 .BR SIGQUIT .
5970 If job control is in effect,
5971 .B bash
5972 ignores
5973 .SM
5974 .BR SIGTTIN ,
5975 .SM
5976 .BR SIGTTOU ,
5977 and
5978 .SM
5979 .BR SIGTSTP .
5980 .PP
5981 The \fBtrap\fP builtin modifies the shell's signal handling, as
5982 described below.
5983 .PP
5984 Non-builtin commands \fBbash\fP executes have signal handlers
5985 set to the values inherited by the shell from its parent,
5986 unless \fBtrap\fP sets them to be ignored, in which case the child
5987 process will ignore them as well.
5988 When job control is not in effect, asynchronous commands
5989 ignore
5990 .SM
5991 .B SIGINT
5992 and
5993 .SM
5994 .B SIGQUIT
5995 in addition to these inherited handlers.
5996 Commands run as a result of command substitution ignore the
5997 keyboard-generated job control signals
5998 .SM
5999 .BR SIGTTIN ,
6000 .SM
6001 .BR SIGTTOU ,
6002 and
6003 .SM
6004 .BR SIGTSTP .
6005 .PP
6006 The shell exits by default upon receipt of a
6007 .SM
6008 .BR SIGHUP .
6009 Before exiting, an interactive shell resends the
6010 .SM
6011 .B SIGHUP
6012 to all jobs, running or stopped.
6013 The shell sends
6014 .SM
6015 .B SIGCONT
6016 to stopped jobs to ensure that they receive the
6017 .SM
6018 .B SIGHUP
6019 (see
6020 .SM
6021 .B "JOB CONTROL"
6022 below for more information about running and stopped jobs).
6023 To prevent the shell from
6024 sending the signal to a particular job, remove it from the
6025 jobs table with the
6026 .B disown
6027 builtin (see
6028 .SM
6029 .B "SHELL BUILTIN COMMANDS"
6030 below) or mark it not to receive
6031 .SM
6032 .B SIGHUP
6033 using
6034 .BR "disown \-h" .
6035 .PP
6036 If the
6037 .B huponexit
6038 shell option has been set using
6039 .BR shopt ,
6040 .B bash
6041 sends a
6042 .SM
6043 .B SIGHUP
6044 to all jobs when an interactive login shell exits.
6045 .PP
6046 If \fBbash\fP is waiting for a command to complete and receives a signal
6047 for which a trap has been set,
6048 it will not execute the trap until the command completes.
6049 If \fBbash\fP is waiting for an asynchronous command via the \fBwait\fP
6050 builtin,
6051 and it receives a signal for which a trap has been set,
6052 the \fBwait\fP builtin will return immediately with an exit status
6053 greater than 128, immediately after which the shell executes the trap.
6054 .PP
6055 When job control is not enabled, and \fBbash\fP is waiting for a foreground
6056 command to complete, the shell receives keyboard-generated signals
6057 such as
6058 .SM
6059 .B SIGINT
6060 (usually generated by \fB\*^C\fP) that users commonly intend to send
6061 to that command.
6062 This happens because the shell and the command are in the
6063 same process group as the terminal, and \fB\*^C\fP sends
6064 .SM
6065 .B SIGINT
6066 to all processes in that process group.
6067 Since \fBbash\fP does not enable job control by default when the
6068 shell is not interactive,
6069 this scenario is most common in non-interactive shells.
6070 .PP
6071 When job control is enabled, and \fBbash\fP is waiting for a foreground
6072 command to complete, the shell does not receive keyboard-generated
6073 signals, because it is not in the same process group as the terminal.
6074 This scenario is most common in interactive shells, where \fBbash\fP
6075 attempts to enable job control by default.
6076 See
6077 .SM
6078 .B "JOB CONTROL"
6079 below for more information about process groups.
6080 .PP
6081 When job control is not enabled, and \fBbash\fP receives
6082 .SM
6083 .B SIGINT
6084 while waiting for a foreground command, it waits until that foreground
6085 command terminates and then decides what to do about the
6086 .SM
6087 .BR SIGINT :
6088 .IP 1.
6089 If the command terminates due to the
6090 .SM
6091 .BR SIGINT ,
6092 \fBbash\fP concludes
6093 that the user meant to send the
6094 .SM
6095 .B SIGINT
6096 to the shell as well, and acts on the
6097 .SM
6098 .B SIGINT
6099 (e.g., by running a
6100 .SM
6101 .B SIGINT
6102 trap,
6103 exiting a non-interactive shell,
6104 or returning to the top level to read a new command).
6105 .IP 2.
6106 If the command does not terminate due to
6107 .SM
6108 .BR SIGINT ,
6109 the program handled the
6110 .SM
6111 .B SIGINT
6112 itself and did not treat it as a fatal signal.
6113 In that case, \fBbash\fP does not treat
6114 .SM
6115 .B SIGINT
6116 as a fatal signal, either, instead assuming that the
6117 .SM
6118 .B SIGINT
6119 was used as part of the program's normal operation
6120 (e.g., emacs uses it to abort editing
6121 commands) or deliberately discarded.
6122 However, \fBbash\fP will run any
6123 trap set on
6124 .SM
6125 .BR SIGINT ,
6126 as it does with any other trapped signal it
6127 receives while it is waiting for the foreground command to
6128 complete, for compatibility.
6129 .PP
6130 When job control is enabled, \fBbash\fP does not receive keyboard-generated
6131 signals such as
6132 .SM
6133 .B SIGINT
6134 while it is waiting for a foreground command.
6135 An interactive shell does not pay attention to the
6136 .SM
6137 .BR SIGINT ,
6138 even if the foreground command terminates as a result, other than noting
6139 its exit status.
6140 If the shell is not interactive, and
6141 the foreground command terminates due to the
6142 .SM
6143 .BR SIGINT ,
6144 \fBbash\fP pretends it received the
6145 .SM
6146 .B SIGINT
6147 itself (scenario 1 above), for compatibility.
6148 .SH "JOB CONTROL"
6149 .I Job control
6150 refers to the ability to selectively stop (\fIsuspend\fP)
6151 the execution of processes and continue (\fIresume\fP)
6152 their execution at a later point.
6153 A user typically employs
6154 this facility via an interactive interface supplied jointly
6155 by the operating system kernel's terminal driver and
6156 .BR bash .
6157 .PP
6158 The shell associates a
6159 .I job
6160 with each pipeline.
6161 It keeps a table of currently executing
6162 jobs, which the
6163 .B jobs
6164 command will display.
6165 Each job has a \fIjob number\fP, which \fBjobs\fP displays between brackets.
6166 Job numbers start at 1.
6167 When
6168 .B bash
6169 starts a job asynchronously (in the
6170 .IR background ),
6171 it prints a line that looks like:
6172 .RS
6173 .PP
6174 [1] 25647
6175 .RE
6176 .PP
6177 indicating that this job is job number 1 and that the process ID
6178 of the last process in the pipeline associated with this job is 25647.
6179 All of the processes in a single pipeline are members of the same job.
6180 .B Bash
6181 uses the
6182 .I job
6183 abstraction as the basis for job control.
6184 .PP
6185 To facilitate the implementation of the user interface to job control,
6186 each process has a \fIprocess group ID\fP, and
6187 the operating system maintains the notion of a \fIcurrent terminal
6188 process group ID\fP.
6189 This terminal process group ID is associated with the
6190 \fIcontrolling terminal\fP.
6191 .PP
6192 Processes that have the same process group ID are said to be part of
6193 the same \fIprocess group\fP.
6194 Members of the \fIforeground\fP process group (processes whose
6195 process group ID is equal to the current terminal process group ID)
6196 receive keyboard-generated signals such as
6197 .SM
6198 .BR SIGINT .
6199 Processes in the foreground process group are said to be
6200 .I foreground
6201 processes.
6202 .I Background
6203 processes are those whose process group ID differs from the
6204 controlling terminal's;
6205 such processes are immune to keyboard-generated signals.
6206 Only foreground processes are allowed to read from or,
6207 if the user so specifies with
6208 .Q "stty tostop" ,
6209 write to the controlling terminal.
6210 The system sends a
6211 .SM
6212 .B "SIGTTIN (SIGTTOU)"
6213 signal to background processes which attempt to
6214 read from (write to when
6215 .Q tostop
6216 is in effect)
6217 the terminal,
6218 which, unless caught, suspends the process.
6219 .PP
6220 If the operating system on which
6221 .B bash
6222 is running supports
6223 job control,
6224 .B bash
6225 contains facilities to use it.
6226 Typing the
6227 .I suspend
6228 character (typically
6229 .BR \*^Z ,
6230 Control-Z) while a process is running
6231 stops that process and returns control to
6232 .BR bash .
6233 Typing the
6234 .I "delayed suspend"
6235 character (typically
6236 .BR \*^Y ,
6237 Control-Y) causes the process stop when it
6238 attempts to read input from the terminal, and returns control to
6239 .BR bash .
6240 The user then manipulates the state of this job, using the
6241 .B bg
6242 command to continue it in the background, the
6243 .B fg
6244 command to continue it in the foreground, or the
6245 .B kill
6246 command to kill it.
6247 The suspend character takes effect immediately,
6248 and has the additional side effect of discarding any pending output
6249 and typeahead.
6250 To force a background process to stop, or stop a process
6251 that's not associated with the current terminal session,
6252 send it the
6253 .SM
6254 .B SIGSTOP
6255 signal using \fBkill\fP.
6256 .PP
6257 There are a number of ways to refer to a job in the shell.
6258 The
6259 .B %
6260 character introduces a job specification (jobspec).
6261 .PP
6262 Job number
6263 .I n
6264 may be referred to as
6265 .BR %n .
6266 A job may also be referred to using a prefix of the name used to
6267 start it, or using a substring that appears in its command line.
6268 For example,
6269 .B %ce
6270 refers to a job whose command name begins with
6271 .BR ce .
6272 Using
6273 .BR %?ce ,
6274 on the other hand, refers to any job containing the string
6275 .B ce
6276 in its command line.
6277 If the prefix or substring matches more than one job,
6278 .B bash
6279 reports an error.
6280 .PP
6281 The symbols
6282 .B %%
6283 and
6284 .B %+
6285 refer to the shell's notion of the
6286 .IR "current job" .
6287 A single % (with no accompanying job specification) also refers to the
6288 current job.
6289 .B %\-
6290 refers to the
6291 .IR "previous job" .
6292 When a job starts in the background,
6293 a job stops while in the foreground,
6294 or a job is resumed in the background,
6295 it becomes the current job.
6296 The job that was the current job becomes the previous job.
6297 When the current job terminates, the previous job becomes the
6298 current job.
6299 If there is only a single job, \fB%+\fP and \fB%\-\fP can both be used
6300 to refer to that job.
6301 In output pertaining to jobs (e.g., the output of the
6302 .B jobs
6303 command), the current job is always marked with a
6304 .BR + ,
6305 and the previous job with a
6306 .BR \- .
6307 .PP
6308 Simply naming a job can be used to bring it into the foreground:
6309 .B %1
6310 is a synonym for
6311 .Q "fg %1" ,
6312 bringing job 1 from the background into the foreground.
6313 Similarly,
6314 .Q "%1 &"
6315 resumes job 1 in the background, equivalent to
6316 .Q "bg %1" .
6317 .PP
6318 The shell learns immediately whenever a job changes state.
6319 Normally,
6320 .B bash
6321 waits until it is about to print a prompt before
6322 notifying the user about
6323 changes in a job's status so as to not interrupt
6324 any other output,
6325 though it will notify of changes in a job's status after a
6326 foreground command in
6327 a list completes, before executing the next command in the list.
6328 If the
6329 .B \-b
6330 option to the
6331 .B set
6332 builtin command
6333 is enabled,
6334 .B bash
6335 reports status changes immediately.
6336 \fBBash\fP executes any trap on
6337 .SM
6338 .B SIGCHLD
6339 for each child that terminates.
6340 .PP
6341 When a job terminates and \fBbash\fP notifies the user about it,
6342 \fBbash\fP removes the job from the table.
6343 It will not appear in \fBjobs\fP output, but \fBwait\fP will
6344 report its exit status, as long as it's supplied the process ID
6345 associated with the job as an argument.
6346 When the table is empty, job numbers start over at 1.
6347 .PP
6348 If a user attempts to exit
6349 .B bash
6350 while jobs are stopped (or, if the \fBcheckjobs\fP shell option has
6351 been enabled using the \fBshopt\fP builtin, running), the shell prints a
6352 warning message, and, if the \fBcheckjobs\fP option is enabled, lists the
6353 jobs and their statuses.
6354 The
6355 .B jobs
6356 command may then be used to inspect their status.
6357 If the user immediately attempts to exit again,
6358 without an intervening command,
6359 \fBbash\fP does not print another warning, and
6360 terminates any stopped jobs.
6361 .PP
6362 When the shell is waiting for a job or process using the \fBwait\fP
6363 builtin, and job control is enabled, \fBwait\fP will return when the
6364 job changes state.
6365 The \fB\-f\fP option causes \fBwait\fP to wait
6366 until the job or process terminates before returning.
6367 .SH PROMPTING
6368 When executing interactively,
6369 .B bash
6370 displays the primary prompt
6371 .SM
6372 .B PS1
6373 when it is ready to read a command, and the secondary prompt
6374 .SM
6375 .B PS2
6376 when it needs more input to complete a command.
6377 .PP
6378 .B Bash
6379 examines the value of the array variable \fBPROMPT_COMMAND\fP just before
6380 printing each primary prompt.
6381 If any elements in \fBPROMPT_COMMAND\fP are set and non-null, Bash
6382 executes each value, in numeric order,
6383 just as if it had been typed on the command line.
6384 .B Bash
6385 displays
6386 .SM
6387 .B PS0
6388 after it reads a command but before executing it.
6389 .PP
6390 .B Bash
6391 displays
6392 .SM
6393 .B PS4
6394 as described above
6395 before tracing each command when the \fB\-x\fP option is enabled.
6396 .PP
6397 .B Bash
6398 allows the prompt strings
6399 \fBPS0\fP, \fBPS1\fP, \fBPS2\fP, and \fBPS4\fP,
6400 to be customized by inserting a number of
6401 backslash-escaped special characters that are decoded as follows:
6402 .RS
6403 .TP
6404 .B \ea
6405 An ASCII bell character (07).
6406 .PD 0
6407 .TP
6408 .B \ed
6409 The date in
6410 .Q "Weekday Month Date"
6411 format (e.g.,
6412 .Q "Tue May 26" ).
6413 .TP
6414 .B \eD{\fIformat\fP}
6415 The \fIformat\fP is passed to
6416 .IR strftime (3)
6417 and the result is inserted
6418 into the prompt string; an empty \fIformat\fP results in a locale-specific
6419 time representation.
6420 The braces are required.
6421 .TP
6422 .B \ee
6423 An ASCII escape character (033).
6424 .TP
6425 .B \eh
6426 The hostname up to the first
6427 .Q . .
6428 .TP
6429 .B \eH
6430 The hostname.
6431 .TP
6432 .B \ej
6433 The number of jobs currently managed by the shell.
6434 .TP
6435 .B \el
6436 The basename of the shell's terminal device name (e.g.,
6437 .Q ttys0 ).
6438 .TP
6439 .B \en
6440 A newline.
6441 .TP
6442 .B \er
6443 A carriage return.
6444 .TP
6445 .B \es
6446 The name of the shell: the basename of
6447 .B $0
6448 (the portion following the final slash).
6449 .TP
6450 .B \et
6451 The current time in 24-hour HH:MM:SS format.
6452 .TP
6453 .B \eT
6454 The current time in 12-hour HH:MM:SS format.
6455 .TP
6456 .B \e@
6457 The current time in 12-hour am/pm format.
6458 .TP
6459 .B \eA
6460 The current time in 24-hour HH:MM format.
6461 .TP
6462 .B \eu
6463 The username of the current user.
6464 .TP
6465 .B \ev
6466 The \fBbash\fP version (e.g., 2.00).
6467 .TP
6468 .B \eV
6469 The \fBbash\fP release, version + patch level (e.g., 2.00.0)
6470 .TP
6471 .B \ew
6472 The value of the \fBPWD\fP shell variable (\fB$PWD\fP),
6473 with
6474 .SM
6475 .B $HOME
6476 abbreviated with a tilde
6477 (uses the value of the
6478 .SM
6479 .B PROMPT_DIRTRIM
6480 variable).
6481 .TP
6482 .B \eW
6483 The basename of \fB$PWD\fP,
6484 with
6485 .SM
6486 .B $HOME
6487 abbreviated with a tilde.
6488 .TP
6489 .B \e!
6490 The history number of this command.
6491 .TP
6492 .B \e#
6493 The command number of this command.
6494 .TP
6495 .B \e$
6496 If the effective UID is 0, a
6497 .BR # ,
6498 otherwise a
6499 .BR $ .
6500 .TP
6501 .B \e\fInnn\fP
6502 The character corresponding to the octal number \fInnn\fP.
6503 .TP
6504 .B \e\e
6505 A backslash.
6506 .TP
6507 .B \e[
6508 Begin a sequence of non-printing characters, which could be used to
6509 embed a terminal control sequence into the prompt.
6510 .TP
6511 .B \e]
6512 End a sequence of non-printing characters.
6513 .PD
6514 .RE
6515 .PP
6516 The command number and the history number are usually different:
6517 the history number of a command is its position in the history
6518 list, which may include commands restored from the history file
6519 (see
6520 .SM
6521 .B HISTORY
6522 below), while the command number is the position in the sequence
6523 of commands executed during the current shell session.
6524 After the string is decoded, it is expanded via
6525 parameter expansion, command substitution, arithmetic
6526 expansion, and quote removal, subject to the value of the
6527 .B promptvars
6528 shell option (see the description of the
6529 .B shopt
6530 command under
6531 .SM
6532 .B "SHELL BUILTIN COMMANDS"
6533 below).
6534 This can have unwanted side effects if escaped portions of the string
6535 appear within command substitution or contain characters special to
6536 word expansion.
6537 .SH READLINE
6538 This is the library that handles reading input when using an interactive
6539 shell, unless the
6540 .B \-\-noediting
6541 option is supplied at shell invocation.
6542 Line editing is also used when using the \fB\-e\fP option to the
6543 \fBread\fP builtin.
6544 By default, the line editing commands are similar to those of emacs;
6545 a vi-style line editing interface is also available.
6546 Line editing can be enabled at any time using the
6547 .B \-o emacs
6548 or
6549 .B \-o vi
6550 options to the
6551 .B set
6552 builtin (see
6553 .SM
6554 .B "SHELL BUILTIN COMMANDS"
6555 below).
6556 To turn off line editing after the shell is running, use the
6557 .B +o emacs
6558 or
6559 .B +o vi
6560 options to the
6561 .B set
6562 builtin.
6563 .SS "Readline Notation"
6564 This section uses Emacs-style editing concepts and uses its
6565 notation for keystrokes.
6566 Control keys are denoted by C\-\fIkey\fP, e.g., C\-n means Control\-N.
6567 Similarly,
6568 .I meta
6569 keys are denoted by M\-\fIkey\fP, so M\-x means Meta\-X.
6570 The Meta key is often labeled
6571 .Q Alt
6572 or
6573 .Q Option .
6574 .PP
6575 On keyboards without a
6576 .I Meta
6577 key, M\-\fIx\fP means ESC \fIx\fP,
6578 i.e., press and release the Escape key,
6579 then press and release the
6580 .I x
6581 key, in sequence.
6582 This makes ESC the \fImeta prefix\fP.
6583 The combination M\-C\-\fIx\fP means ESC Control\-\fIx\fP:
6584 press and release the Escape key,
6585 then press and hold the Control key while pressing the
6586 .I x
6587 key, then release both.
6588 .PP
6589 On some keyboards, the Meta key modifier produces characters with
6590 the eighth bit (0200) set.
6591 You can use the \fBenable\-meta\-key\fP variable
6592 to control whether or not it does this, if the keyboard allows it.
6593 On many others, the terminal or terminal emulator converts the metafied
6594 key to a key sequence beginning with ESC as described in the
6595 preceding paragraph.
6596 .PP
6597 If your \fIMeta\fP key produces a key sequence with the ESC meta prefix,
6598 you can make M-\fIkey\fP key bindings you specify (see
6599 .B "Readline Key Bindings"
6600 below) do the same thing by setting the \fBforce\-meta\-prefix\fP variable.
6601 .PP
6602 .B Readline
6603 commands may be given numeric
6604 .IR arguments ,
6605 which normally act as a repeat count.
6606 Sometimes, however, it is the sign of the argument that is significant.
6607 Passing a negative argument
6608 to a command that acts in the forward direction (e.g., \fBkill\-line\fP)
6609 makes that command act in a backward direction.
6610 Commands whose behavior with arguments deviates from this are noted
6611 below.
6612 .PP
6613 The \fIpoint\fP is the current cursor position, and \fImark\fP refers
6614 to a saved cursor position.
6615 The text between the point and mark is referred to as the \fIregion\fP.
6616 \fBReadline\fP has the concept of an \fIactive region\fP:
6617 when the region is active, \fBreadline\fP redisplay
6618 highlights the region using the
6619 value of the \fBactive-region-start-color\fP variable.
6620 The \fBenable\-active\-region\fP variable turns this on and off.
6621 Several commands set the region to active; those are noted below.
6622 .PP
6623 When a command is described as \fIkilling\fP text, the text
6624 deleted is saved for possible future retrieval
6625 (\fIyanking\fP).
6626 The killed text is saved in a \fIkill ring\fP.
6627 Consecutive kills accumulate the deleted text
6628 into one unit, which can be yanked all at once.
6629 Commands which do not kill text separate the chunks of text
6630 on the kill ring.
6631 .SS "Readline Initialization"
6632 .B Readline
6633 is customized by putting commands in an initialization
6634 file (the \fIinputrc\fP file).
6635 The name of this file is taken from the value of the
6636 .SM
6637 .B \%INPUTRC
6638 shell variable.
6639 If that variable is unset, the default is
6640 .FN \*~/.inputrc .
6641 If that file does not exist or cannot be read, \fBreadline\fP looks for
6642 .FN /etc/inputrc .
6643 When a program that uses the \fBreadline\fP library starts up,
6644 \fBreadline\fP reads the initialization file
6645 and sets the key bindings and variables found there,
6646 before reading any user input.
6647 .PP
6648 There are only a few basic constructs allowed in the inputrc file.
6649 Blank lines are ignored.
6650 Lines beginning with a \fB#\fP are comments.
6651 Lines beginning with a \fB$\fP indicate conditional constructs.
6652 Other lines denote key bindings and variable settings.
6653 .PP
6654 The default key-bindings in this section
6655 may be changed using key binding commands in the
6656 .I inputrc
6657 file.
6658 Programs that use the \fBreadline\fP library, including \fBbash\fP,
6659 may add their own commands and bindings.
6660 .PP
6661 For example, placing
6662 .RS
6663 .PP
6664 M\-Control\-u: universal\-argument
6665 .RE
6666 or
6667 .RS
6668 C\-Meta\-u: universal\-argument
6669 .RE
6670 .LP
6671 into the
6672 .I inputrc
6673 would make M\-C\-u execute the \fBreadline\fP command
6674 .IR universal\-argument .
6675 .PP
6676 Key bindings may contain the following symbolic character names:
6677 .IR DEL ,
6678 .IR ESC ,
6679 .IR ESCAPE ,
6680 .IR LFD ,
6681 .IR NEWLINE ,
6682 .IR RET ,
6683 .IR RETURN ,
6684 .I RUBOUT
6685 (a destructive backspace),
6686 .IR SPACE ,
6687 .IR SPC ,
6688 and
6689 .IR TAB .
6690 .PP
6691 In addition to command names, \fBreadline\fP allows keys to be bound
6692 to a string that is inserted when the key is pressed (a \fImacro\fP).
6693 The difference between a macro and a command is that a macro is
6694 enclosed in single or double quotes.
6695 .SS "Readline Key Bindings"
6696 The syntax for controlling key bindings in the
6697 .I inputrc
6698 file is simple.
6699 All that is required is the name of the command or the text of a macro
6700 and a key sequence to which it should be bound.
6701 The key sequence may be specified in one of two ways:
6702 as a symbolic key name,
6703 possibly with \fIMeta\-\fP or \fIControl\-\fP prefixes,
6704 or as a key sequence composed of one or more characters
6705 enclosed in double quotes.
6706 The key sequence and name are separated by a colon.
6707 There can be no whitespace between the name and the colon.
6708 .PP
6709 When using the form \fBkeyname\fP:\^\fIfunction\-name\fP or \fImacro\fP,
6710 .I keyname
6711 is the name of a key spelled out in English. For example:
6712 .PP
6713 .RS
6714 .EX
6715 .nf
6716 Control-u: universal\-argument
6717 Meta-Rubout: backward\-kill\-word
6718 Control-o: \*"> output\*"
6719 .fi
6720 .EE
6721 .RE
6722 .LP
6723 In the above example,
6724 .I C\-u
6725 is bound to the function
6726 .BR universal\-argument ,
6727 .I M\-DEL
6728 is bound to the function
6729 .BR backward\-kill\-word ,
6730 and
6731 .I C\-o
6732 is bound to run the macro
6733 expressed on the right hand side (that is, to insert the text
6734 .Q "> output"
6735 into the line).
6736 .PP
6737 In the second form,
6738 \fB\*"keyseq\*"\fP:\^\fIfunction\-name\fP or \fImacro\fP,
6739 .B keyseq
6740 differs from
6741 .B keyname
6742 above in that strings denoting
6743 an entire key sequence may be specified by placing the sequence
6744 within double quotes.
6745 Some GNU Emacs style key escapes can be
6746 used, as in the following example, but none of
6747 the symbolic character names are recognized.
6748 .PP
6749 .RS
6750 .EX
6751 .nf
6752 \*"\eC\-u\*": universal\-argument
6753 \*"\eC\-x\eC\-r\*": re\-read\-init\-file
6754 \*"\ee[11\*~\*": \*"Function Key 1\*"
6755 .fi
6756 .EE
6757 .RE
6758 .PP
6759 In this example,
6760 .I C\-u
6761 is again bound to the function
6762 .BR universal\-argument .
6763 .I "C\-x C\-r"
6764 is bound to the function
6765 .BR re\-read\-init\-file ,
6766 and
6767 .I "ESC [ 1 1 \*~"
6768 is bound to insert the text
6769 .Q "Function Key 1" .
6770 .PP
6771 The full set of GNU Emacs style escape sequences available when specifying
6772 key sequences is
6773 .RS
6774 .PD 0
6775 .TP
6776 .B \eC\-
6777 A control prefix.
6778 .TP
6779 .B \eM\-
6780 Adding the meta prefix or converting the following character to a meta
6781 character, as described below under \fBforce-meta-prefix\fP.
6782 .TP
6783 .B \ee
6784 An escape character.
6785 .TP
6786 .B \e\e
6787 Backslash.
6788 .TP
6789 .B \e\*"
6790 Literal \*", a double quote.
6791 .TP
6792 .B \e\*'
6793 Literal \*', a single quote.
6794 .RE
6795 .PD
6796 .PP
6797 In addition to the GNU Emacs style escape sequences, a second
6798 set of backslash escapes is available:
6799 .RS
6800 .PD 0
6801 .TP
6802 .B \ea
6803 alert (bell)
6804 .TP
6805 .B \eb
6806 backspace
6807 .TP
6808 .B \ed
6809 delete
6810 .TP
6811 .B \ef
6812 form feed
6813 .TP
6814 .B \en
6815 newline
6816 .TP
6817 .B \er
6818 carriage return
6819 .TP
6820 .B \et
6821 horizontal tab
6822 .TP
6823 .B \ev
6824 vertical tab
6825 .TP
6826 .B \e\fInnn\fP
6827 The eight-bit character whose value is the octal value \fInnn\fP
6828 (one to three digits).
6829 .TP
6830 .B \ex\fIHH\fP
6831 The eight-bit character whose value is the hexadecimal value \fIHH\fP
6832 (one or two hex digits).
6833 .RE
6834 .PD
6835 .PP
6836 When entering the text of a macro, single or double quotes must
6837 be used to indicate a macro definition.
6838 Unquoted text is assumed to be a function name.
6839 The backslash escapes described above are expanded
6840 in the macro body.
6841 Backslash quotes any other character in the macro text,
6842 including \*" and \*'.
6843 .PP
6844 .B Bash
6845 will display or modify the current \fBreadline\fP key bindings with the
6846 .B bind
6847 builtin command.
6848 The
6849 .B \-o emacs
6850 or
6851 .B \-o vi
6852 options to the
6853 .B set
6854 builtin
6855 (see
6856 .SM
6857 .B "SHELL BUILTIN COMMANDS"
6858 below)
6859 change the editing mode during interactive use.
6860 .SS "Readline Variables"
6861 \fBReadline\fP has variables that can be used to further customize its
6862 behavior.
6863 A variable may be set in the
6864 .I inputrc
6865 file with a statement of the form
6866 .RS
6867 .PP
6868 \fBset\fP \fIvariable\-name\fP \fIvalue\fP
6869 .RE
6870 or using the \fBbind\fP builtin command (see
6871 .SM
6872 .B "SHELL BUILTIN COMMANDS"
6873 below).
6874 .PP
6875 Except where noted, \fBreadline\fP variables can take the values
6876 .B On
6877 or
6878 .B Off
6879 (without regard to case).
6880 Unrecognized variable names are ignored.
6881 When \fBreadline\fP reads a variable value, empty or null values,
6882 .Q "on"
6883 (case-insensitive), and
6884 .Q 1
6885 are equivalent to \fBOn\fP.
6886 All other values are equivalent to
6887 \fBOff\fP.
6888 .PP
6889 The \fBbind \-V\fP command lists the current \fBreadline\fP variable names
6890 and values (see
6891 .SM
6892 .B "SHELL BUILTIN COMMANDS"
6893 below).
6894 .PP
6895 The variables and their default values are:
6896 .PP
6897 .PD 0
6898 .TP
6899 .B active\-region\-start\-color
6900 A string variable that controls the text color and background when displaying
6901 the text in the active region (see the description of
6902 \fBenable\-active\-region\fP below).
6903 This string must not take up any physical character positions on the display,
6904 so it should consist only of terminal escape sequences.
6905 It is output to the terminal before displaying the text in the active region.
6906 This variable is reset to the default value whenever the terminal type changes.
6907 The default value is the string that puts the terminal in standout mode,
6908 as obtained from the terminal's terminfo description.
6909 A sample value might be
6910 .Q \ee[01;33m .
6911 .TP
6912 .B active\-region\-end\-color
6913 A string variable that
6914 .Q undoes
6915 the effects of \fBactive\-region\-start\-color\fP
6916 and restores
6917 .Q normal
6918 terminal display appearance after displaying text in the active region.
6919 This string must not take up any physical character positions on the display,
6920 so it should consist only of terminal escape sequences.
6921 It is output to the terminal after displaying the text in the active region.
6922 This variable is reset to the default value whenever the terminal type changes.
6923 The default value is the string that restores the terminal from standout mode,
6924 as obtained from the terminal's terminfo description.
6925 A sample value might be
6926 .Q \ee[0m .
6927 .TP
6928 .B bell\-style (audible)
6929 Controls what happens when \fBreadline\fP wants to ring the terminal bell.
6930 If set to \fBnone\fP, \fBreadline\fP never rings the bell.
6931 If set to \fBvisible\fP, \fBreadline\fP uses a visible bell if one is available.
6932 If set to \fBaudible\fP, \fBreadline\fP attempts to ring the terminal's bell.
6933 .TP
6934 .B bind\-tty\-special\-chars (On)
6935 If set to \fBOn\fP, \fBreadline\fP attempts to bind
6936 the control characters that are treated specially by the kernel's
6937 terminal driver to their \fBreadline\fP equivalents.
6938 These override the default \fBreadline\fP bindings described here.
6939 Type
6940 .Q "stty \-a"
6941 at a \fBbash\fP prompt to see your current terminal settings,
6942 including the special control characters (usually \fBcchars\fP).
6943 .TP
6944 .B blink\-matching\-paren (Off)
6945 If set to \fBOn\fP, \fBreadline\fP attempts to briefly move the cursor to an
6946 opening parenthesis when a closing parenthesis is inserted.
6947 .TP
6948 .B colored\-completion\-prefix (Off)
6949 If set to \fBOn\fP, when listing completions, \fBreadline\fP displays the
6950 common prefix of the set of possible completions using a different color.
6951 The color definitions are taken from the value of the \fBLS_COLORS\fP
6952 environment variable.
6953 If there is a color definition in \fB$LS_COLORS\fP for the custom suffix
6954 .Q .readline-colored-completion-prefix ,
6955 \fBreadline\fP uses this color for
6956 the common prefix instead of its default.
6957 .TP
6958 .B colored\-stats (Off)
6959 If set to \fBOn\fP, \fBreadline\fP displays possible completions using different
6960 colors to indicate their file type.
6961 The color definitions are taken from the value of the \fBLS_COLORS\fP
6962 environment variable.
6963 .\" Tucking multiple macro calls into a paragraph tag requires some
6964 .\" finesse. We require `\c`, and while the single-font macros don't
6965 .\" honor input trap continuation, the font alternation macros do.
6966 .TP
6967 .BR comment\-begin\ ( \c
6968 .Q \fB#\fP \fB)\fP
6969 The string that the \fBreadline\fP
6970 .B insert\-comment
6971 command inserts.
6972 This command is bound to
6973 .B M\-#
6974 in emacs mode and to
6975 .B #
6976 in vi command mode.
6977 .TP
6978 .B completion\-display\-width (\-1)
6979 The number of screen columns used to display possible matches
6980 when performing completion.
6981 The value is ignored if it is less than 0 or greater than the terminal
6982 screen width.
6983 A value of 0 causes matches to be displayed one per line.
6984 The default value is \-1.
6985 .TP
6986 .B completion\-ignore\-case (Off)
6987 If set to \fBOn\fP, \fBreadline\fP performs filename matching and completion
6988 in a case\-insensitive fashion.
6989 .TP
6990 .B completion\-map\-case (Off)
6991 If set to \fBOn\fP, and \fBcompletion\-ignore\-case\fP is enabled,
6992 .B readline
6993 treats hyphens (\fI\-\fP) and underscores (\fI_\fP) as equivalent when
6994 performing case\-insensitive filename matching and completion.
6995 .TP
6996 .B completion\-prefix\-display\-length (0)
6997 The maximum
6998 length in characters of the common prefix of a list of possible
6999 completions that is displayed without modification.
7000 When set to a value greater than zero, \fBreadline\fP
7001 replaces common prefixes longer than this value
7002 with an ellipsis when displaying possible completions.
7003 If a completion begins with a period,
7004 and \fBeadline\fP is completing filenames,
7005 it uses three underscores instead of an ellipsis.
7006 .TP
7007 .B completion\-query\-items (100)
7008 This determines when the user is queried about viewing
7009 the number of possible completions
7010 generated by the \fBpossible\-completions\fP command.
7011 It may be set to any integer value greater than or equal to zero.
7012 If the number of possible completions is greater than
7013 or equal to the value of this variable,
7014 \fBreadline\fP asks whether or not the user wishes to view them;
7015 otherwise \fBreadline\fP simply lists them on the terminal.
7016 A zero value means \fBreadline\fP should never ask; negative values are
7017 treated as zero.
7018 .TP
7019 .B convert\-meta (On)
7020 If set to \fBOn\fP, \fBreadline\fP converts characters it reads
7021 that have the eighth bit set to an ASCII key sequence by
7022 clearing the eighth bit and prefixing it with an escape character
7023 (converting the character to have the meta prefix).
7024 The default is \fIOn\fP, but \fBreadline\fP sets it to \fIOff\fP
7025 if the locale contains
7026 characters whose encodings may include bytes with the eighth bit set.
7027 This variable is dependent on the \fBLC_CTYPE\fP locale category, and
7028 may change if the locale changes.
7029 This variable also affects key bindings; see the description of
7030 \fBforce\-meta\-prefix\fP below.
7031 .TP
7032 .B disable\-completion (Off)
7033 If set to \fBOn\fP, \fBreadline\fP inhibits word completion.
7034 Completion characters are inserted into the line as if they
7035 had been mapped to \fBself-insert\fP.
7036 .TP
7037 .B echo\-control\-characters (On)
7038 When set to \fBOn\fP, on operating systems that indicate they support it,
7039 \fBreadline\fP echoes a character corresponding to a signal generated from the
7040 keyboard.
7041 .TP
7042 .B editing\-mode (emacs)
7043 Controls whether \fBreadline\fP uses a set of key bindings similar
7044 to \fIEmacs\fP or \fIvi\fP.
7045 .B editing\-mode
7046 can be set to either
7047 .B emacs
7048 or
7049 .BR vi .
7050 .TP
7051 .B emacs\-mode\-string (@)
7052 If the \fIshow\-mode\-in\-prompt\fP variable is enabled,
7053 this string is displayed immediately before the last line of the
7054 primary prompt when emacs editing mode is active.
7055 The value is expanded like a
7056 key binding, so the standard set of meta- and control- prefixes and
7057 backslash escape sequences is available.
7058 The \e1 and \e2 escapes begin and end sequences of
7059 non-printing characters, which can be used to embed a terminal control
7060 sequence into the mode string.
7061 .TP
7062 .B enable\-active\-region (On)
7063 When this variable is set to \fIOn\fP, \fBreadline\fP allows certain commands
7064 to designate the region as \fIactive\fP.
7065 When the region is active, \fBreadline\fP
7066 highlights the text in the region using the value of the
7067 .B active\-region\-start\-color
7068 variable, which defaults to the string that enables
7069 the terminal's standout mode.
7070 The active region shows the text inserted by bracketed-paste and any
7071 matching text found by incremental and non-incremental history searches.
7072 .TP
7073 .B enable\-bracketed\-paste (On)
7074 When set to \fBOn\fP, \fBreadline\fP configures the terminal to insert each
7075 paste into the editing buffer as a single string of characters, instead
7076 of treating each character as if it had been read from the keyboard.
7077 This is called \fIbracketed\-paste mode\fP;
7078 it prevents \fBreadline\fP from executing any editing commands bound to key
7079 sequences appearing in the pasted text.
7080 .TP
7081 .B enable\-keypad (Off)
7082 When set to \fBOn\fP, \fBreadline\fP tries to enable the application
7083 keypad when it is called.
7084 Some systems need this to enable the arrow keys.
7085 .TP
7086 .B enable\-meta\-key (On)
7087 When set to \fBOn\fP, \fBreadline\fP tries to enable any meta modifier
7088 key the terminal claims to support.
7089 On many terminals, the Meta key is used to send eight-bit characters;
7090 this variable checks for the terminal capability that indicates the
7091 terminal can enable and disable a mode that sets the eighth bit of a
7092 character (0200) if the Meta key is held down when the character is
7093 typed (a meta character).
7094 .TP
7095 .B expand\-tilde (Off)
7096 If set to \fBOn\fP, \fBreadline\fP performs tilde expansion when it
7097 attempts word completion.
7098 .TP
7099 .B force\-meta\-prefix (Off)
7100 If set to \fBOn\fP, \fBreadline\fP modifies its behavior when binding key
7101 sequences containing \eM- or Meta-
7102 (see \fBKey Bindings\fP above) by converting a key sequence of the form
7103 \eM\-\fIC\fP or Meta\-\fIC\fP to the two-character sequence
7104 \fBESC\fP \fIC\fP (adding the meta prefix).
7105 If
7106 .B force\-meta\-prefix
7107 is set to \fBOff\fP (the default),
7108 \fBreadline\fP uses the value of the
7109 .B convert\-meta
7110 variable to determine whether to perform this conversion:
7111 if \fBconvert\-meta\fP is \fBOn\fP,
7112 \fBreadline\fP performs the conversion described above;
7113 if it is \fBOff\fP, \fBreadline\fP converts \fIC\fP to a meta character by
7114 setting the eighth bit (0200).
7115 .TP
7116 .B history\-preserve\-point (Off)
7117 If set to \fBOn\fP, the history code attempts to place point at the
7118 same location on each history line retrieved with \fBprevious-history\fP
7119 or \fBnext-history\fP.
7120 .TP
7121 .B history\-size (unset)
7122 Set the maximum number of history entries saved in the history list.
7123 If set to zero, any existing history entries are deleted and no new entries
7124 are saved.
7125 If set to a value less than zero, the number of history entries is not
7126 limited.
7127 By default, \fBbash\fP sets the maximum number of history entries to
7128 the value of the \fBHISTSIZE\fP shell variable.
7129 Setting \fIhistory\-size\fP to a non-numeric value will set
7130 the maximum number of history entries to 500.
7131 .TP
7132 .B horizontal\-scroll\-mode (Off)
7133 Setting this variable to \fBOn\fP makes \fBreadline\fP use a single line
7134 for display, scrolling the input horizontally on a single screen line
7135 when it becomes longer than the screen width rather than wrapping to
7136 a new line.
7137 This setting is automatically enabled for terminals of height 1.
7138 .TP
7139 .B input\-meta (Off)
7140 If set to \fBOn\fP, \fBreadline\fP enables eight-bit input (that is, it
7141 does not clear the eighth bit in the characters it reads),
7142 regardless of what the terminal claims it can support.
7143 The default is \fIOff\fP, but \fBreadline\fP sets it to \fIOn\fP
7144 if the locale contains characters whose encodings may include bytes
7145 with the eighth bit set.
7146 This variable is dependent on the \fBLC_CTYPE\fP locale category, and
7147 its value may change if the locale changes.
7148 The name \fBmeta\-flag\fP is a synonym for \fBinput\-meta\fP.
7149 .TP
7150 .BR isearch\-terminators\ ( \c
7151 .Q \fBC\-[C\-j\fP \fB)\fP
7152 The string of characters that should terminate an incremental
7153 search without subsequently executing the character as a command.
7154 If this variable has not been given a value, the characters
7155 \fIESC\fP and \fBC\-j\fP terminate an incremental search.
7156 .TP
7157 .B keymap (emacs)
7158 Set the current \fBreadline\fP keymap.
7159 The set of valid keymap names is
7160 \fIemacs, emacs\-standard, emacs\-meta, emacs\-ctlx, vi,
7161 vi\-command\fP, and
7162 .IR vi\-insert .
7163 \fIvi\fP is equivalent to \fIvi\-command\fP;
7164 \fIemacs\fP is equivalent to \fIemacs\-standard\fP.
7165 The default value is \fIemacs\fP;
7166 the value of
7167 .B editing\-mode
7168 also affects the default keymap.
7169 .TP
7170 .B keyseq\-timeout (500)
7171 Specifies the duration \fBreadline\fP will wait for a character when
7172 reading an ambiguous key sequence
7173 (one that can form a complete key sequence using the input read so far,
7174 or can take additional input to complete a longer key sequence).
7175 If \fBreadline\fP does not receive any input within the timeout,
7176 it uses the shorter but complete key sequence.
7177 The value is specified in milliseconds, so a value of 1000 means that
7178 \fBreadline\fP will wait one second for additional input.
7179 If this variable is set to a value less than or equal to zero, or to a
7180 non-numeric value, \fBreadline\fP waits until another key is pressed to
7181 decide which key sequence to complete.
7182 .TP
7183 .B mark\-directories (On)
7184 If set to \fBOn\fP, completed directory names have a slash appended.
7185 .TP
7186 .B mark\-modified\-lines (Off)
7187 If set to \fBOn\fP, \fBreadline\fP displays history lines
7188 that have been modified
7189 with a preceding asterisk (\fB*\fP).
7190 .TP
7191 .B mark\-symlinked\-directories (Off)
7192 If set to \fBOn\fP, completed names which are symbolic links to directories
7193 have a slash appended, subject to the value of \fBmark\-directories\fP.
7194 .TP
7195 .B match\-hidden\-files (On)
7196 This variable, when set to \fBOn\fP, forces \fBreadline\fP to match files whose
7197 names begin with a
7198 .Q .
7199 (hidden files) when performing filename completion.
7200 If set to \fBOff\fP, the user must include the leading
7201 .Q .
7202 in the filename to be completed.
7203 .TP
7204 .B menu\-complete\-display\-prefix (Off)
7205 If set to \fBOn\fP, menu completion displays the common prefix of the
7206 list of possible completions (which may be empty) before cycling through
7207 the list.
7208 .TP
7209 .B output\-meta (Off)
7210 If set to \fBOn\fP, \fBreadline\fP displays characters with the
7211 eighth bit set directly rather than as a meta-prefixed escape
7212 sequence.
7213 The default is \fIOff\fP, but \fBreadline\fP sets it to \fIOn\fP
7214 if the locale contains characters whose encodings may include
7215 bytes with the eighth bit set.
7216 This variable is dependent on the \fBLC_CTYPE\fP locale category, and
7217 its value may change if the locale changes.
7218 .TP
7219 .B page\-completions (On)
7220 If set to \fBOn\fP, \fBreadline\fP uses an internal pager resembling
7221 .IR more (1)
7222 to display a screenful of possible completions at a time.
7223 .TP
7224 .B prefer\-visible\-bell
7225 See \fBbell\-style\fP.
7226 .TP
7227 .B print\-completions\-horizontally (Off)
7228 If set to \fBOn\fP, \fBreadline\fP displays completions with matches
7229 sorted horizontally in alphabetical order, rather than down the screen.
7230 .TP
7231 .B revert\-all\-at\-newline (Off)
7232 If set to \fBOn\fP, \fBreadline\fP will undo all changes to history lines
7233 before returning when executing \fBaccept\-line\fP.
7234 By default,
7235 history lines may be modified and retain individual undo lists across
7236 calls to \fBreadline\fP.
7237 .TP
7238 .B search\-ignore\-case (Off)
7239 If set to \fBOn\fP, \fBreadline\fP performs incremental and non-incremental
7240 history list searches in a case\-insensitive fashion.
7241 .TP
7242 .B show\-all\-if\-ambiguous (Off)
7243 This alters the default behavior of the completion functions.
7244 If set to
7245 .BR On ,
7246 words which have more than one possible completion cause the
7247 matches to be listed immediately instead of ringing the bell.
7248 .TP
7249 .B show\-all\-if\-unmodified (Off)
7250 This alters the default behavior of the completion functions in
7251 a fashion similar to \fBshow\-all\-if\-ambiguous\fP.
7252 If set to
7253 .BR On ,
7254 words which have more than one possible completion without any
7255 possible partial completion (the possible completions don't share
7256 a common prefix) cause the matches to be listed immediately instead
7257 of ringing the bell.
7258 .TP
7259 .B show\-mode\-in\-prompt (Off)
7260 If set to \fBOn\fP, add a string to the beginning of the prompt
7261 indicating the editing mode: emacs, vi command, or vi insertion.
7262 The mode strings are user-settable (e.g., \fIemacs\-mode\-string\fP).
7263 .TP
7264 .B skip\-completed\-text (Off)
7265 If set to \fBOn\fP, this alters the default completion behavior when
7266 inserting a single match into the line.
7267 It's only active when performing completion in the middle of a word.
7268 If enabled, \fBreadline\fP does not insert characters from the completion
7269 that match characters after point in the word being completed,
7270 so portions of the word following the cursor are not duplicated.
7271 .TP
7272 .B vi\-cmd\-mode\-string ((cmd))
7273 If the \fIshow\-mode\-in\-prompt\fP variable is enabled,
7274 this string is displayed immediately before the last line of the primary
7275 prompt when vi editing mode is active and in command mode.
7276 The value is expanded like a key binding, so the standard set of
7277 meta- and control- prefixes and backslash escape sequences is available.
7278 The \e1 and \e2 escapes begin and end sequences of
7279 non-printing characters, which can be used to embed a terminal control
7280 sequence into the mode string.
7281 .TP
7282 .B vi\-ins\-mode\-string ((ins))
7283 If the \fIshow\-mode\-in\-prompt\fP variable is enabled,
7284 this string is displayed immediately before the last line of the primary
7285 prompt when vi editing mode is active and in insertion mode.
7286 The value is expanded like a key binding, so the standard set of
7287 meta- and control- prefixes and backslash escape sequences is available.
7288 The \e1 and \e2 escapes begin and end sequences of
7289 non-printing characters, which can be used to embed a terminal control
7290 sequence into the mode string.
7291 .TP
7292 .B visible\-stats (Off)
7293 If set to \fBOn\fP, a character denoting a file's type as reported
7294 by \fIstat\fP(2) is appended to the filename when listing possible
7295 completions.
7296 .PD
7297 .SS "Readline Conditional Constructs"
7298 .B Readline
7299 implements a facility similar in spirit to the conditional
7300 compilation features of the C preprocessor which allows key
7301 bindings and variable settings to be performed as the result
7302 of tests.
7303 There are four parser directives available.
7304 .TP
7305 .B $if
7306 The
7307 .B $if
7308 construct allows bindings to be made based on the
7309 editing mode, the terminal being used, or the application using
7310 \fBreadline\fP.
7311 The text of the test, after any comparison operator,
7312 extends to the end of the line;
7313 unless otherwise noted, no characters are required to isolate it.
7314 .RS
7315 .TP
7316 .B mode
7317 The \fBmode=\fP form of the \fB$if\fP directive is used to test
7318 whether \fBreadline\fP is in emacs or vi mode.
7319 This may be used in conjunction
7320 with the \fBset keymap\fP command, for instance, to set bindings in
7321 the \fIemacs\-standard\fP and \fIemacs\-ctlx\fP keymaps only if
7322 \fBreadline\fP is starting out in emacs mode.
7323 .TP
7324 .B term
7325 The \fBterm=\fP form may be used to include terminal-specific
7326 key bindings, perhaps to bind the key sequences output by the
7327 terminal's function keys.
7328 The word on the right side of the
7329 .B =
7330 is tested against both the full name of the terminal and the portion
7331 of the terminal name before the first \fB\-\fP.
7332 This allows
7333 .I xterm
7334 to match both
7335 .I xterm
7336 and
7337 .IR xterm\-256color ,
7338 for instance.
7339 .TP
7340 .B version
7341 The \fBversion\fP test may be used to perform comparisons against
7342 specific \fBreadline\fP versions.
7343 The \fBversion\fP expands to the current \fBreadline\fP version.
7344 The set of comparison operators includes
7345 .BR = ,
7346 (and
7347 .BR == ),
7348 .BR != ,
7349 .BR <= ,
7350 .BR >= ,
7351 .BR < ,
7352 and
7353 .BR > .
7354 The version number supplied on the right side of the operator consists
7355 of a major version number, an optional decimal point, and an optional
7356 minor version (e.g., \fB7.1\fP).
7357 If the minor version is omitted, it
7358 defaults to \fB0\fP.
7359 The operator may be separated from the string \fBversion\fP
7360 and from the version number argument by whitespace.
7361 .TP
7362 .I application
7363 The \fIapplication\fP construct is used to include
7364 application-specific settings.
7365 Each program using the \fBreadline\fP
7366 library sets the \fIapplication name\fP, and an initialization
7367 file can test for a particular value.
7368 This could be used to bind key sequences to functions useful for
7369 a specific program.
7370 For instance, the following command adds a
7371 key sequence that quotes the current or previous word in \fBbash\fP:
7372 .PP
7373 .RS
7374 .EX
7375 .nf
7376 \fB$if\fP Bash
7377 # Quote the current or previous word
7378 \*"\eC-xq\*": \*"\eeb\e\*"\eef\e\*"\*"
7379 \fB$endif\fP
7380 .fi
7381 .EE
7382 .RE
7383 .TP
7384 .I variable
7385 The \fIvariable\fP construct provides simple equality tests for \fBreadline\fP
7386 variables and values.
7387 The permitted comparison operators are \fI=\fP, \fI==\fP, and \fI!=\fP.
7388 The variable name must be separated from the comparison operator by
7389 whitespace; the operator may be separated from the value on the right hand
7390 side by whitespace.
7391 String and boolean variables may be tested.
7392 Boolean variables must be
7393 tested against the values \fIon\fP and \fIoff\fP.
7394 .RE
7395 .TP
7396 .B $else
7397 Commands in this branch of the \fB$if\fP directive are executed if
7398 the test fails.
7399 .TP
7400 .B $endif
7401 This command, as seen in the previous example, terminates an
7402 \fB$if\fP command.
7403 .TP
7404 .B $include
7405 This directive takes a single filename as an argument and reads commands
7406 and key bindings from that file.
7407 For example, the following directive would read
7408 .FN /etc/inputrc :
7409 .PP
7410 .RS
7411 .nf
7412 \fB$include\fP \^ \fI/etc/inputrc\fP
7413 .fi
7414 .RE
7415 .SS Searching
7416 .B Readline
7417 provides commands for searching through the command history (see
7418 .SM
7419 .B HISTORY
7420 below)
7421 for lines containing a specified string.
7422 There are two search modes:
7423 .I incremental
7424 and
7425 .IR non-incremental .
7426 .PP
7427 Incremental searches begin before the user has finished typing the
7428 search string.
7429 As each character of the search string is typed, \fBreadline\fP displays
7430 the next entry from the history matching the string typed so far.
7431 An incremental search requires only as many characters as needed to
7432 find the desired history entry.
7433 When using emacs editing mode, type \fBC\-r\fP to
7434 search backward in the history for a particular string.
7435 Typing \fBC\-s\fP searches forward through the history.
7436 The characters present in the value of the \fBisearch-terminators\fP
7437 variable are used to terminate an incremental search.
7438 If that variable has not been assigned a value,
7439 \fIESC\fP and \fBC\-j\fP terminate an incremental search.
7440 \fBC\-g\fP aborts an incremental search and restores the original line.
7441 When the search is terminated, the history entry containing the
7442 search string becomes the current line.
7443 .PP
7444 To find other matching entries in the history list, type \fBC\-r\fP or
7445 \fBC\-s\fP as appropriate.
7446 This searches backward or forward in the history for the next
7447 entry matching the search string typed so far.
7448 Any other key sequence bound to a \fBreadline\fP command terminates
7449 the search and executes that command.
7450 For instance, a newline terminates the search and accepts
7451 the line, thereby executing the command from the history list.
7452 A movement command will terminate the search, make the last line found
7453 the current line, and begin editing.
7454 .PP
7455 .B Readline
7456 remembers the last incremental search string.
7457 If two \fBC\-r\fPs are typed without any intervening characters defining
7458 a new search string, \fBreadline\fP uses any remembered search string.
7459 .PP
7460 Non-incremental searches read the entire search string before starting
7461 to search for matching history entries.
7462 The search string may be
7463 typed by the user or be part of the contents of the current line.
7464 .SS "Readline Command Names"
7465 The following is a list of the names of the commands and the default
7466 key sequences to which they are bound.
7467 Command names without an accompanying key sequence are unbound by default.
7468 .PP
7469 In the following descriptions, \fIpoint\fP refers to the current cursor
7470 position, and \fImark\fP refers to a cursor position saved by the
7471 \fBset\-mark\fP command.
7472 The text between the point and mark is referred to as the \fIregion\fP.
7473 .B Readline
7474 has the concept of an \fIactive region\fP:
7475 when the region is active, \fBreadline\fP redisplay
7476 highlights the region using the value of the
7477 .B active\-region\-start\-color
7478 variable.
7479 The \fBenable\-active\-region\fP \fBreadline\fP variable turns this on and off.
7480 Several commands set the region to active; those are noted below.
7481 .SS Commands for Moving
7482 .PD 0
7483 .TP
7484 .B beginning\-of\-line (C\-a)
7485 Move to the start of the current line.
7486 This may also be bound to the Home key on some keyboards.
7487 .TP
7488 .B end\-of\-line (C\-e)
7489 Move to the end of the line.
7490 This may also be bound to the End key on some keyboards.
7491 .TP
7492 .B forward\-char (C\-f)
7493 Move forward a character.
7494 This may also be bound to the right arrow key on some keyboards.
7495 .TP
7496 .B backward\-char (C\-b)
7497 Move back a character.
7498 This may also be bound to the left arrow key on some keyboards.
7499 .TP
7500 .B forward\-word (M\-f)
7501 Move forward to the end of the next word.
7502 Words are composed of alphanumeric characters (letters and digits).
7503 .TP
7504 .B backward\-word (M\-b)
7505 Move back to the start of the current or previous word.
7506 Words are composed of alphanumeric characters (letters and digits).
7507 .TP
7508 .B shell\-forward\-word (M\-C\-f)
7509 Move forward to the end of the next word.
7510 Words are delimited by non-quoted shell metacharacters.
7511 .TP
7512 .B shell\-backward\-word (M\-C\-b)
7513 Move back to the start of the current or previous word.
7514 Words are delimited by non-quoted shell metacharacters.
7515 .TP
7516 .B previous\-screen\-line
7517 Attempt to move point to the same physical screen column on the previous
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 point is not greater than the length of the prompt plus the screen width.
7522 .TP
7523 .B next\-screen\-line
7524 Attempt to move point to the same physical screen column on the next
7525 physical screen line.
7526 This will not have the desired effect if the current
7527 \fBreadline\fP line does not take up more than one physical line or if
7528 the length of the current \fBreadline\fP line is
7529 not greater than the length of the prompt
7530 plus the screen width.
7531 .TP
7532 .B clear\-display (M\-C\-l)
7533 Clear the screen and, if possible, the terminal's scrollback buffer,
7534 then redraw the current line,
7535 leaving the current line at the top of the screen.
7536 .TP
7537 .B clear\-screen (C\-l)
7538 Clear the screen,
7539 then redraw the current line,
7540 leaving the current line at the top of the screen.
7541 With a numeric argument, refresh the current line without clearing the
7542 screen.
7543 .TP
7544 .B redraw\-current\-line
7545 Refresh the current line.
7546 .PD
7547 .SS Commands for Manipulating the History
7548 .PD 0
7549 .TP
7550 .B accept\-line (Newline, Return)
7551 Accept the line regardless of where the cursor is.
7552 If this line is non-empty, add it to the history list according to the
7553 state of the
7554 .SM
7555 .B HISTCONTROL
7556 and
7557 .B HISTIGNORE
7558 variables.
7559 If the line is a modified history line,
7560 restore the history line to its original state.
7561 .TP
7562 .B previous\-history (C\-p)
7563 Fetch the previous command from the history list, moving back in
7564 the list.
7565 This may also be bound to the up arrow key on some keyboards.
7566 .TP
7567 .B next\-history (C\-n)
7568 Fetch the next command from the history list, moving forward in the
7569 list.
7570 This may also be bound to the down arrow key on some keyboards.
7571 .TP
7572 .B beginning\-of\-history (M\-<)
7573 Move to the first line in the history.
7574 .TP
7575 .B end\-of\-history (M\->)
7576 Move to the end of the input history, i.e., the line currently being
7577 entered.
7578 .TP
7579 .B operate\-and\-get\-next (C\-o)
7580 Accept the current line for execution as if a
7581 newline had been entered,
7582 and fetch the next line relative to the current line from the history
7583 for editing.
7584 A numeric argument, if supplied, specifies the history entry to use instead
7585 of the current line.
7586 .TP
7587 .B
7588 fetch\-history
7589 With a numeric argument, fetch that entry from the history list
7590 and make it the current line.
7591 Without an argument, move back to the first entry in the history list.
7592 .TP
7593 .B reverse\-search\-history (C\-r)
7594 Search backward starting at the current line and moving
7595 .Q up
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 forward\-search\-history (C\-s)
7601 Search forward starting at the current line and moving
7602 .Q down
7603 through the history as necessary.
7604 This is an incremental search.
7605 This command sets the region to the matched text and activates the region.
7606 .TP
7607 .B non\-incremental\-reverse\-search\-history (M\-p)
7608 Search backward through the history starting at the current line
7609 using a non-incremental search for a string supplied by the user.
7610 The search string may match anywhere in a history line.
7611 .TP
7612 .B non\-incremental\-forward\-search\-history (M\-n)
7613 Search forward through the history using a non-incremental search
7614 for a string supplied by the user.
7615 The search string may match anywhere in a history line.
7616 .TP
7617 .B history\-search\-backward
7618 Search backward 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 Up key on some keyboards.
7623 .TP
7624 .B history\-search\-forward
7625 Search forward through the history for the string of characters
7626 between the start of the current line and the point.
7627 The search string must match at the beginning of a history line.
7628 This is a non-incremental search.
7629 This may be bound to the Page Down key on some keyboards.
7630 .TP
7631 .B history\-substring\-search\-backward
7632 Search backward through the history for the string of characters
7633 between the start of the current line and the point.
7634 The search string may match anywhere in a history line.
7635 This is a non-incremental search.
7636 .TP
7637 .B history\-substring\-search\-forward
7638 Search forward through the history for the string of characters
7639 between the start of the current line and the point.
7640 The search string may match anywhere in a history line.
7641 This is a non-incremental search.
7642 .TP
7643 .B yank\-nth\-arg (M\-C\-y)
7644 Insert the first argument to the previous command (usually
7645 the second word on the previous line) at point.
7646 With an argument
7647 .IR n ,
7648 insert the \fIn\fPth word from the previous command (the words
7649 in the previous command begin with word 0).
7650 A negative argument inserts the \fIn\fPth word from the end of
7651 the previous command.
7652 Once the argument \fIn\fP is computed,
7653 this uses the history expansion facilities to extract the
7654 \fIn\fPth word, as if the
7655 .Q !\fIn\fP
7656 history expansion had been specified.
7657 .TP
7658 .B
7659 yank\-last\-arg (M\-.\^, M\-_\^)
7660 Insert the last argument to the previous command (the last word of
7661 the previous history entry).
7662 With a numeric argument, behave exactly like \fByank\-nth\-arg\fP.
7663 Successive calls to \fByank\-last\-arg\fP move back through the history
7664 list, inserting the last word (or the word specified by the argument to
7665 the first call) of each line in turn.
7666 Any numeric argument supplied to these successive calls determines
7667 the direction to move through the history.
7668 A negative argument switches the direction through the history
7669 (back or forward).
7670 This uses the history expansion facilities to extract the
7671 last word, as if the
7672 .Q !$
7673 history expansion had been specified.
7674 .TP
7675 .B shell\-expand\-line (M\-C\-e)
7676 Expand the line by performing shell word expansions.
7677 This performs alias and history expansion,
7678 \fB$\fP\*'\fIstring\fP\*' and \fB$\fP\*"\fIstring\fP\*" quoting,
7679 tilde expansion, parameter and variable expansion, arithmetic expansion,
7680 command and process substitution,
7681 word splitting, and quote removal.
7682 An explicit argument suppresses command and process substitution.
7683 See
7684 .SM
7685 .B "HISTORY EXPANSION"
7686 below for a description of history expansion.
7687 .TP
7688 .B history\-expand\-line (M\-\*^)
7689 Perform history expansion on the current line.
7690 See
7691 .SM
7692 .B "HISTORY EXPANSION"
7693 below for a description of history expansion.
7694 .TP
7695 .B magic\-space
7696 Perform history expansion on the current line and insert a space.
7697 See
7698 .SM
7699 .B "HISTORY EXPANSION"
7700 below for a description of history expansion.
7701 .TP
7702 .B alias\-expand\-line
7703 Perform alias expansion on the current line.
7704 See
7705 .SM
7706 .B ALIASES
7707 above for a description of alias expansion.
7708 .TP
7709 .B history\-and\-alias\-expand\-line
7710 Perform history and alias expansion on the current line.
7711 .TP
7712 .B insert\-last\-argument (M\-.\^, M\-_\^)
7713 A synonym for \fByank\-last\-arg\fP.
7714 .TP
7715 .B edit\-and\-execute\-command (C\-x C\-e)
7716 Invoke an editor on the current command line, and execute the result as shell
7717 commands.
7718 \fBBash\fP attempts to invoke
7719 .SM
7720 .BR $VISUAL ,
7721 .SM
7722 .BR $EDITOR ,
7723 and \fIemacs\fP as the editor, in that order.
7724 .PD
7725 .SS Commands for Changing Text
7726 .PD 0
7727 .TP
7728 .B \fIend\-of\-file\fP (usually C\-d)
7729 The character indicating end-of-file as set, for example, by
7730 .IR stty (1).
7731 If this character is read when there are no characters
7732 on the line, and point is at the beginning of the line, \fBreadline\fP
7733 interprets it as the end of input and returns
7734 .SM
7735 .BR EOF .
7736 .TP
7737 .B delete\-char (C\-d)
7738 Delete the character at point.
7739 If this function is bound to the
7740 same character as the tty \fBEOF\fP character, as \fBC\-d\fP
7741 commonly is, see above for the effects.
7742 This may also be bound to the Delete key on some keyboards.
7743 .TP
7744 .B backward\-delete\-char (Rubout)
7745 Delete the character behind the cursor.
7746 When given a numeric argument,
7747 save the deleted text on the kill ring.
7748 .TP
7749 .B forward\-backward\-delete\-char
7750 Delete the character under the cursor, unless the cursor is at the
7751 end of the line, in which case the character behind the cursor is
7752 deleted.
7753 .TP
7754 .B quoted\-insert (C\-q, C\-v)
7755 Add the next character typed to the line verbatim.
7756 This is how to insert characters like \fBC\-q\fP, for example.
7757 .TP
7758 .B tab\-insert (C\-v TAB)
7759 Insert a tab character.
7760 .TP
7761 .B "self\-insert (a, b, A, 1, !, \fR.\|.\|.\fP)"
7762 Insert the character typed.
7763 .TP
7764 .B bracketed\-paste\-begin
7765 This function is intended to be bound to the
7766 .Q "bracketed paste"
7767 escape
7768 sequence sent by some terminals, and such a binding is assigned by default.
7769 It allows \fBreadline\fP to insert the pasted text as a single unit
7770 without treating each character as if it had been read from the keyboard.
7771 The pasted characters
7772 are inserted as if each one was bound to \fBself\-insert\fP instead of
7773 executing any editing commands.
7774 .IP
7775 Bracketed paste sets the region to the inserted text and activates the region.
7776 .TP
7777 .B transpose\-chars (C\-t)
7778 Drag the character before point forward over the character at point,
7779 moving point forward as well.
7780 If point is at the end of the line, then this transposes
7781 the two characters before point.
7782 Negative arguments have no effect.
7783 .TP
7784 .B transpose\-words (M\-t)
7785 Drag the word before point past the word after point,
7786 moving point past that word as well.
7787 If point is at the end of the line, this transposes
7788 the last two words on the line.
7789 .TP
7790 .B shell\-transpose\-words (M-C-t)
7791 Drag the word before point past the word after point,
7792 moving point past that word as well.
7793 If the insertion point is at the end of the line, this transposes
7794 the last two words on the line.
7795 Word boundaries are the same as \fBshell\-forward\-word\fP and
7796 \fBshell\-backward\-word\fP.
7797 .TP
7798 .B upcase\-word (M\-u)
7799 Uppercase the current (or following) word.
7800 With a negative argument,
7801 uppercase the previous word, but do not move point.
7802 .TP
7803 .B downcase\-word (M\-l)
7804 Lowercase the current (or following) word.
7805 With a negative argument,
7806 lowercase the previous word, but do not move point.
7807 .TP
7808 .B capitalize\-word (M\-c)
7809 Capitalize the current (or following) word.
7810 With a negative argument,
7811 capitalize the previous word, but do not move point.
7812 .TP
7813 .B overwrite\-mode
7814 Toggle overwrite mode.
7815 With an explicit positive numeric argument, switches to overwrite mode.
7816 With an explicit non-positive numeric argument, switches to insert mode.
7817 This command affects only \fBemacs\fP mode;
7818 \fBvi\fP mode does overwrite differently.
7819 Each call to \fIreadline()\fP starts in insert mode.
7820 .IP
7821 In overwrite mode, characters bound to \fBself\-insert\fP replace
7822 the text at point rather than pushing the text to the right.
7823 Characters bound to \fBbackward\-delete\-char\fP replace the character
7824 before point with a space.
7825 By default, this command is unbound,
7826 but may be bound to the Insert key on some keyboards.
7827 .PD
7828 .SS Killing and Yanking
7829 .PD 0
7830 .TP
7831 .B kill\-line (C\-k)
7832 Kill the text from point to the end of the current line.
7833 With a negative numeric argument, kill backward from the cursor to the
7834 beginning of the line.
7835 .TP
7836 .B backward\-kill\-line (C\-x Rubout)
7837 Kill backward to the beginning of the current line.
7838 With a negative numeric argument, kill forward from the cursor to the
7839 end of the line.
7840 .TP
7841 .B unix\-line\-discard (C\-u)
7842 Kill backward from point to the beginning of the line,
7843 saving the killed text on the kill-ring.
7844 .\" There is no real difference between this and backward-kill-line
7845 .TP
7846 .B kill\-whole\-line
7847 Kill all characters on the current line, no matter where point is.
7848 .TP
7849 .B kill\-word (M\-d)
7850 Kill from point to the end of the current word, or if between
7851 words, to the end of the next word.
7852 Word boundaries are the same as those used by \fBforward\-word\fP.
7853 .TP
7854 .B backward\-kill\-word (M\-Rubout)
7855 Kill the word behind point.
7856 Word boundaries are the same as those used by \fBbackward\-word\fP.
7857 .TP
7858 .B shell\-kill\-word (M\-C\-d)
7859 Kill from point to the end of the current word, or if between
7860 words, to the end of the next word.
7861 Word boundaries are the same as those used by \fBshell\-forward\-word\fP.
7862 .TP
7863 .B shell\-backward\-kill\-word
7864 Kill the word behind point.
7865 Word boundaries are the same as those used by \fBshell\-backward\-word\fP.
7866 .TP
7867 .B unix\-word\-rubout (C\-w)
7868 Kill the word behind point, using white space as a word boundary,
7869 saving the killed text on the kill-ring.
7870 .TP
7871 .B unix\-filename\-rubout
7872 Kill the word behind point, using white space and the slash character
7873 as the word boundaries,
7874 saving the killed text on the kill-ring.
7875 .TP
7876 .B delete\-horizontal\-space (M\-\e)
7877 Delete all spaces and tabs around point.
7878 .TP
7879 .B kill\-region
7880 Kill the text in the current region.
7881 .TP
7882 .B copy\-region\-as\-kill
7883 Copy the text in the region to the kill buffer,
7884 so it can be yanked immediately.
7885 .TP
7886 .B copy\-backward\-word
7887 Copy the word before point to the kill buffer.
7888 The word boundaries are the same as \fBbackward\-word\fP.
7889 .TP
7890 .B copy\-forward\-word
7891 Copy the word following point to the kill buffer.
7892 The word boundaries are the same as \fBforward\-word\fP.
7893 .TP
7894 .B yank (C\-y)
7895 Yank the top of the kill ring into the buffer at point.
7896 .TP
7897 .B yank\-pop (M\-y)
7898 Rotate the kill ring, and yank the new top.
7899 Only works following
7900 .B yank
7901 or
7902 .BR yank\-pop .
7903 .PD
7904 .SS Numeric Arguments
7905 .PD 0
7906 .TP
7907 .B digit\-argument (M\-0, M\-1, \fR.\|.\|.\fP, M\-\-)
7908 Add this digit to the argument already accumulating, or start a new
7909 argument.
7910 M\-\- starts a negative argument.
7911 .TP
7912 .B universal\-argument
7913 This is another way to specify an argument.
7914 If this command is followed by one or more digits, optionally with a
7915 leading minus sign, those digits define the argument.
7916 If the command is followed by digits, executing
7917 .B universal\-argument
7918 again ends the numeric argument, but is otherwise ignored.
7919 As a special case, if this command is immediately followed by a
7920 character that is neither a digit nor minus sign,
7921 the argument count for the next command is multiplied by four.
7922 The argument count is initially one, so executing this function the
7923 first time makes the argument count four, a second time makes the
7924 argument count sixteen, and so on.
7925 .PD
7926 .SS Completing
7927 .PD 0
7928 .TP
7929 .B complete (TAB)
7930 Attempt to perform completion on the text before point.
7931 .B Bash
7932 attempts completion by first checking for any programmable
7933 completions for the command word (see \fBProgrammable Completion\fP below),
7934 otherwise treating the text as a
7935 variable (if the text begins with \fB$\fP),
7936 username (if the text begins with \fB\*~\fP),
7937 hostname (if the text begins with \fB@\fP), or
7938 command (including aliases, functions, and builtins) in turn.
7939 If none of these produces a match, it falls back to filename completion.
7940 .TP
7941 .B possible\-completions (M\-?)
7942 List the possible completions of the text before point.
7943 When displaying completions, \fBreadline\fP sets the number of columns used
7944 for display to the value of \fBcompletion-display-width\fP, the value of
7945 the shell variable
7946 .SM
7947 .BR COLUMNS ,
7948 or the screen width, in that order.
7949 .TP
7950 .B insert\-completions (M\-*)
7951 Insert all completions of the text before point
7952 that would have been generated by
7953 \fBpossible\-completions\fP,
7954 separated by a space.
7955 .TP
7956 .B menu\-complete
7957 Similar to \fBcomplete\fP, but replaces the word to be completed
7958 with a single match from the list of possible completions.
7959 Repeatedly executing \fBmenu\-complete\fP steps through the list
7960 of possible completions, inserting each match in turn.
7961 At the end of the list of completions,
7962 \fBmenu\-complete\fP rings the bell
7963 (subject to the setting of \fBbell\-style\fP)
7964 and restores the original text.
7965 An argument of \fIn\fP moves \fIn\fP positions forward in the list
7966 of matches; a negative argument moves backward through the list.
7967 This command is intended to be bound to \fBTAB\fP, but is unbound
7968 by default.
7969 .TP
7970 .B menu\-complete\-backward
7971 Identical to \fBmenu\-complete\fP, but moves backward through the list
7972 of possible completions, as if \fBmenu\-complete\fP had been given a
7973 negative argument.
7974 This command is unbound by default.
7975 .TP
7976 .B export\-completions
7977 Perform completion on the word before point as described above
7978 and write the list of possible completions to \fBreadline\fP's output
7979 stream using the following format, writing information on separate lines:
7980 .RS
7981 .PD
7982 .IP \(bu
7983 .PD 0
7984 the number of matches \fIN\fP;
7985 .IP \(bu
7986 the word being completed;
7987 .IP \(bu
7988 \fIS\fP:\fIE\fP,
7989 where \fIS\fP and \fIE\fP are the start and end offsets of the word
7990 in the \fBreadline\fP line buffer; then
7991 .IP \(bu
7992 each match, one per line
7993 .RE
7994 .PD
7995 .IP
7996 If there are no matches, the first line will be
7997 .Q 0 ,
7998 and this command does not print any output after the \fIS\fP:\fIE\fP.
7999 If there is only a single match, this prints a single line containing it.
8000 If there is more than one match, this prints the common prefix of the
8001 matches, which may be empty, on the first line after the \fIS\fP:\fIE\fP,
8002 then the matches on subsequent lines.
8003 In this case, \fIN\fP will include the first line with the common prefix.
8004 .IP
8005 The user or application
8006 should be able to accommodate the possibility of a blank line.
8007 The intent is that the user or application reads \fIN\fP lines after
8008 the line containing \fIS\fP:\fIE\fP to obtain the match list.
8009 This command is unbound by default.
8010 .TP
8011 .B delete\-char\-or\-list
8012 Deletes the character under the cursor if not at the beginning or
8013 end of the line (like \fBdelete\-char\fP).
8014 At the end of the line, it behaves identically to \fBpossible\-completions\fP.
8015 This command is unbound by default.
8016 .TP
8017 .B complete\-filename (M\-/)
8018 Attempt filename completion on the text before point.
8019 .TP
8020 .B possible\-filename\-completions (C\-x /)
8021 List the possible completions of the text before point,
8022 treating it as a filename.
8023 .TP
8024 .B complete\-username (M\-\*~)
8025 Attempt completion on the text before point, treating
8026 it as a username.
8027 .TP
8028 .B possible\-username\-completions (C\-x \*~)
8029 List the possible completions of the text before point,
8030 treating it as a username.
8031 .TP
8032 .B complete\-variable (M\-$)
8033 Attempt completion on the text before point, treating
8034 it as a shell variable.
8035 .TP
8036 .B possible\-variable\-completions (C\-x $)
8037 List the possible completions of the text before point,
8038 treating it as a shell variable.
8039 .TP
8040 .B complete\-hostname (M\-@)
8041 Attempt completion on the text before point, treating
8042 it as a hostname.
8043 .TP
8044 .B possible\-hostname\-completions (C\-x @)
8045 List the possible completions of the text before point,
8046 treating it as a hostname.
8047 .TP
8048 .B complete\-command (M\-!)
8049 Attempt completion on the text before point, treating
8050 it as a command name.
8051 Command completion attempts to
8052 match the text against aliases, reserved words, shell
8053 functions, shell builtins, and finally executable filenames,
8054 in that order.
8055 .TP
8056 .B possible\-command\-completions (C\-x !)
8057 List the possible completions of the text before point,
8058 treating it as a command name.
8059 .TP
8060 .B dynamic\-complete\-history (M\-TAB)
8061 Attempt completion on the text before point, comparing
8062 the text against history list entries for possible
8063 completion matches.
8064 .TP
8065 .B dabbrev\-expand
8066 Attempt menu completion on the text before point, comparing
8067 the text against lines from the history list for possible
8068 completion matches.
8069 .TP
8070 .B complete\-into\-braces (M\-{)
8071 Perform filename completion and insert the list of possible completions
8072 enclosed within braces so the list is available to the shell (see
8073 .B "Brace Expansion"
8074 above).
8075 .PD
8076 .SS "Keyboard Macros"
8077 .PD 0
8078 .TP
8079 .B start\-kbd\-macro (C\-x (\^)
8080 Begin saving the characters typed into the current keyboard macro.
8081 .TP
8082 .B end\-kbd\-macro (C\-x )\^)
8083 Stop saving the characters typed into the current keyboard macro
8084 and store the definition.
8085 .TP
8086 .B call\-last\-kbd\-macro (C\-x e)
8087 Re-execute the last keyboard macro defined, by making the characters
8088 in the macro appear as if typed at the keyboard.
8089 .TP
8090 .B print\-last\-kbd\-macro ()
8091 Print the last keyboard macro defined in a format suitable for the
8092 \fIinputrc\fP file.
8093 .PD
8094 .SS Miscellaneous
8095 .PD 0
8096 .TP
8097 .B re\-read\-init\-file (C\-x C\-r)
8098 Read in the contents of the \fIinputrc\fP file, and incorporate
8099 any bindings or variable assignments found there.
8100 .TP
8101 .B abort (C\-g)
8102 Abort the current editing command and
8103 ring the terminal's bell (subject to the setting of
8104 .BR bell\-style ).
8105 .TP
8106 .B do\-lowercase\-version (M\-A, M\-B, M\-\fIx\fP, \fR.\|.\|.\fP)
8107 If the metafied character \fIx\fP is uppercase, run the command
8108 that is bound to the corresponding metafied lowercase character.
8109 The behavior is undefined if \fIx\fP is already lowercase.
8110 .TP
8111 .B prefix\-meta (ESC)
8112 Metafy the next character typed.
8113 .SM
8114 .B ESC
8115 .B f
8116 is equivalent to
8117 .BR Meta\-f .
8118 .TP
8119 .B undo (C\-_, C\-x C\-u)
8120 Incremental undo, separately remembered for each line.
8121 .TP
8122 .B revert\-line (M\-r)
8123 Undo all changes made to this line.
8124 This is like executing the
8125 .B undo
8126 command enough times to return the line to its initial state.
8127 .TP
8128 .B tilde\-expand (M\-&)
8129 Perform tilde expansion on the current word.
8130 .TP
8131 .B set\-mark (C\-@, M\-<space>)
8132 Set the mark to the point.
8133 If a numeric argument is supplied, set the mark to that position.
8134 .TP
8135 .B exchange\-point\-and\-mark (C\-x C\-x)
8136 Swap the point with the mark.
8137 Set the current cursor position to the saved position,
8138 then set the mark to the old cursor position.
8139 .TP
8140 .B character\-search (C\-])
8141 Read a character and move point to the next occurrence of that character.
8142 A negative argument searches for previous occurrences.
8143 .TP
8144 .B character\-search\-backward (M\-C\-])
8145 Read a character and move point to the previous occurrence of that character.
8146 A negative argument searches for subsequent occurrences.
8147 .TP
8148 .B skip\-csi\-sequence
8149 Read enough characters to consume a multi-key sequence such as those
8150 defined for keys like Home and End.
8151 CSI sequences begin with a Control Sequence Indicator (CSI), usually
8152 .IR "ESC [" .
8153 If this sequence is bound to
8154 .Q \ee[ ,
8155 keys producing CSI sequences have no effect
8156 unless explicitly bound to a \fBreadline\fP command,
8157 instead of inserting stray characters into the editing buffer.
8158 This is unbound by default, but usually bound to
8159 .IR "ESC [" .
8160 .TP
8161 .B insert\-comment (M\-#)
8162 Without a numeric argument, insert the value of the \fBreadline\fP
8163 .B comment\-begin
8164 variable at the beginning of the current line.
8165 If a numeric argument is supplied, this command acts as a toggle: if
8166 the characters at the beginning of the line do not match the value
8167 of \fBcomment\-begin\fP, insert the value; otherwise delete
8168 the characters in \fBcomment-begin\fP from the beginning of the line.
8169 In either case, the line is accepted as if a newline had been typed.
8170 The default value of
8171 \fBcomment\-begin\fP causes this command to make the current line
8172 a shell comment.
8173 If a numeric argument causes the comment character to be removed, the line
8174 will be executed by the shell.
8175 .TP
8176 .B spell\-correct\-word (C\-x s)
8177 Perform spelling correction on the current word, treating it as a directory
8178 or filename, in the same way as the \fBcdspell\fP shell option.
8179 Word boundaries are the same as those used by \fBshell\-forward\-word\fP.
8180 .TP
8181 .B glob\-complete\-word (M\-g)
8182 Treat the word before point as a pattern for pathname expansion,
8183 with an asterisk implicitly appended, then use the pattern to
8184 generate a list of matching file names for possible completions.
8185 .TP
8186 .B glob\-expand\-word (C\-x *)
8187 Treat the word before point as a pattern for pathname expansion,
8188 and insert the list of matching file names, replacing the word.
8189 If a numeric argument is supplied, append a \fB*\fP before
8190 pathname expansion.
8191 .TP
8192 .B glob\-list\-expansions (C\-x g)
8193 Display the list of expansions that would have been generated by
8194 .B glob\-expand\-word
8195 and redisplay the line.
8196 If a numeric argument is supplied, append a \fB*\fP before
8197 pathname expansion.
8198 .TP
8199 .B dump\-functions
8200 Print all of the functions and their key bindings
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\-variables
8207 Print all of the settable \fBreadline\fP variables and their values
8208 to the \fBreadline\fP output stream.
8209 If a numeric argument is supplied,
8210 the output is formatted in such a way that it can be made part
8211 of an \fIinputrc\fP file.
8212 .TP
8213 .B dump\-macros
8214 Print all of the \fBreadline\fP key sequences bound to macros and the
8215 strings they output
8216 to the \fBreadline\fP output stream.
8217 If a numeric argument is supplied,
8218 the output is formatted in such a way that it can be made part
8219 of an \fIinputrc\fP file.
8220 .TP
8221 .B execute\-named\-command (M-x)
8222 Read a bindable \fBreadline\fP command name from the input and execute the
8223 function to which it's bound, as if the key sequence to which it was
8224 bound appeared in the input.
8225 If this function is supplied with a numeric argument, it passes that
8226 argument to the function it executes.
8227 .TP
8228 .B display\-shell\-version (C\-x C\-v)
8229 Display version information about the current instance of
8230 .BR bash .
8231 .PD
8232 .SS "Programmable Completion"
8233 When a user attempts word completion
8234 for a command or an argument to a command for
8235 which a completion specification (a \fIcompspec\fP) has been defined
8236 using the \fBcomplete\fP builtin
8237 (see
8238 .SM
8239 .B "SHELL BUILTIN COMMANDS"
8240 below),
8241 \fBreadline\fP invokes the programmable completion facilities.
8242 .PP
8243 First, \fBbash\fP identifies the command name.
8244 If a compspec has been defined for that command, the
8245 compspec is used to generate the list of possible completions for the word.
8246 If the command word is the empty string (completion attempted at the
8247 beginning of an empty line), \fBbash\fP uses any compspec defined with
8248 the \fB\-E\fP option to \fBcomplete\fP.
8249 The \fB\-I\fP option to \fBcomplete\fP
8250 indicates that the command word is the first non-assignment word
8251 on the line, or after a command delimiter such as
8252 \fB;\fP or \fB|\fP.
8253 This usually indicates command name completion.
8254 .PP
8255 If the command word is a full pathname, \fBbash\fP
8256 searches for a compspec for the full pathname first.
8257 If there is no compspec for the full pathname, \fBbash\fP attempts to
8258 find a compspec for the portion following the final slash.
8259 If those searches do not result in a compspec,
8260 or if there is no compspec for the command word,
8261 \fBbash\fP uses any compspec defined with
8262 the \fB\-D\fP option to \fBcomplete\fP as the default.
8263 If there is no default compspec, \fBbash\fP performs alias expansion
8264 on the command word as a final resort,
8265 and attempts to find a compspec for the command word
8266 resulting from any successful expansion.
8267 .PP
8268 If a compspec is not found, \fBbash\fP performs its default completion as
8269 described above under \fBCompleting\fP.
8270 Otherwise, once a compspec has been found, \fBbash\fP uses it to generate
8271 the list of matching words.
8272 .PP
8273 First, \fBbash\fP performs the \fIactions\fP specified by the compspec.
8274 This only returns matches which are prefixes
8275 of the word being completed.
8276 When the
8277 .B \-f
8278 or
8279 .B \-d
8280 option is used for filename or directory name completion,
8281 \fBbash\fP uses the shell variable
8282 .SM
8283 .B FIGNORE
8284 to filter the matches.
8285 .PP
8286 Next, programmable completion generates matches
8287 specified by a pathname expansion pattern
8288 supplied as an argument to the
8289 \fB\-G\fP option.
8290 The words generated by the pattern need not match the word
8291 being completed.
8292 \fBBash\fP
8293 uses the
8294 .SM
8295 .B FIGNORE
8296 variable to filter the matches, but does not use the
8297 .SM
8298 .B GLOBIGNORE
8299 shell variable.
8300 .PP
8301 Next, completion considers
8302 the string specified as the argument to the \fB\-W\fP option.
8303 The string is first split using the characters in the
8304 .SM
8305 .B IFS
8306 special variable as delimiters.
8307 This honors shell quoting within the string, in order to provide a
8308 mechanism for the words to contain shell metacharacters or characters
8309 in the value of
8310 .SM
8311 .BR IFS .
8312 Each word is then expanded using
8313 brace expansion, tilde expansion, parameter and variable expansion,
8314 command substitution, and arithmetic expansion,
8315 as described above under
8316 .SM
8317 .BR EXPANSION .
8318 The results are split using the rules described above under
8319 \fBWord Splitting\fP.
8320 The results of the expansion are prefix-matched against the word being
8321 completed, and the matching words become possible completions.
8322 .PP
8323 After these matches have been generated,
8324 \fBbash\fP executes any shell function or command
8325 specified with the \fB\-F\fP and \fB\-C\fP options.
8326 When the command or function is invoked, \fBbash\fP
8327 assigns values to the
8328 .SM
8329 .BR COMP_LINE ,
8330 .SM
8331 .BR COMP_POINT ,
8332 .SM
8333 .BR COMP_KEY ,
8334 and
8335 .SM
8336 .B COMP_TYPE
8337 variables as described above
8338 under \fBShell Variables\fP.
8339 If a shell function is being invoked, \fBbash\fP
8340 also sets the
8341 .SM
8342 .B COMP_WORDS
8343 and
8344 .SM
8345 .B COMP_CWORD
8346 variables.
8347 When the function or command is invoked,
8348 the first argument (\fB$1\fP) is the name of the command whose arguments
8349 are being completed,
8350 the second argument (\fB$2\fP) is the word being completed,
8351 and the third argument (\fB$3\fP) is the word preceding the word being
8352 completed on the current command line.
8353 There is no filtering of the generated completions against the
8354 word being completed;
8355 the function or command has complete freedom in generating the matches
8356 and they do not need to match a prefix of the word.
8357 .PP
8358 Any function specified with \fB\-F\fP is invoked first.
8359 The function may use any of the shell facilities, including the
8360 \fBcompgen\fP and \fBcompopt\fP
8361 builtins described below, to generate the matches.
8362 It must put the possible completions in the
8363 .SM
8364 .B COMPREPLY
8365 array variable, one per array element.
8366 .PP
8367 Next, any command specified with the \fB\-C\fP option is invoked
8368 in an environment equivalent to command substitution.
8369 It should print a list of completions, one per line, to the
8370 standard output.
8371 Backslash will escape a newline, if necessary.
8372 These are added to the set of possible completions.
8373 .PP
8374 After generating all of the possible completions,
8375 \fBbash\fP applies any filter
8376 specified with the \fB\-X\fP option to the completions in the list.
8377 The filter is a pattern as used for pathname expansion; a \fB&\fP
8378 in the pattern is replaced with the text of the word being completed.
8379 A literal \fB&\fP may be escaped with a backslash; the backslash
8380 is removed before attempting a match.
8381 Any completion that matches the pattern is removed from the list.
8382 A leading \fB!\fP negates the pattern;
8383 in this case \fBbash\fP removes
8384 any completion that does not match the pattern.
8385 If the
8386 .B nocasematch
8387 shell option is enabled,
8388 \fBbash\fP performs the match without regard to the case
8389 of alphabetic characters.
8390 .PP
8391 Finally, programmable completion adds
8392 any prefix and suffix specified with the
8393 \fB\-P\fP and \fB\-S\fP
8394 options, respectively, to each completion,
8395 and returns the result
8396 to \fBreadline\fP as the list of possible completions.
8397 .PP
8398 If the previously-applied actions do not generate any matches, and the
8399 \fB\-o dirnames\fP option was supplied to \fBcomplete\fP when the
8400 compspec was defined, \fBbash\fP attempts directory name completion.
8401 .PP
8402 If the \fB\-o plusdirs\fP option was supplied to \fBcomplete\fP when the
8403 compspec was defined, \fBbash\fP attempts directory name completion and
8404 adds any matches to the set of possible completions.
8405 .PP
8406 By default, if a compspec is found, whatever it generates is returned
8407 to the completion code as the full set of possible completions.
8408 The default \fBbash\fP completions and the \fBreadline\fP
8409 default of filename completion are disabled.
8410 If the \fB\-o bashdefault\fP option was supplied to \fBcomplete\fP when
8411 the compspec was defined,
8412 and the compspec generates no matches,
8413 \fBbash\fP attempts its default completions.
8414 If the compspec and, if attempted, the default \fBbash\fP completions
8415 generate no matches,
8416 and the \fB\-o default\fP option was supplied to
8417 \fBcomplete\fP when the compspec was defined,
8418 programmable completion performs \fBreadline\fP's default completion.
8419 .PP
8420 The options supplied to \fBcomplete\fP and \fBcompopt\fP
8421 can control how \fBreadline\fP treats the completions.
8422 For instance, the \fI\-o fullquote\fP option tells \fBreadline\fP
8423 to quote the matches as if they were filenames.
8424 See the description of \fBcomplete\fP below
8425 for details.
8426 .PP
8427 When a compspec indicates that it wants directory name completion,
8428 the programmable completion functions force \fBreadline\fP
8429 to append a slash to completed names which are symbolic links
8430 to directories, subject to the value of the
8431 \fBmark\-directories\fP \fBreadline\fP variable,
8432 regardless of the setting of the
8433 \fBmark-symlinked\-directories\fP \fBreadline\fP variable.
8434 .PP
8435 There is some support for dynamically modifying completions.
8436 This is most useful when used in combination with a default completion
8437 specified with \fBcomplete \-D\fP.
8438 It's possible for shell functions executed as completion functions
8439 to indicate that completion should be retried by returning an
8440 exit status of 124.
8441 If a shell function returns 124, and changes
8442 the compspec associated with the command on which completion is being
8443 attempted (supplied as the first argument when the function is executed),
8444 programmable completion restarts from the beginning, with an
8445 attempt to find a new compspec for that command.
8446 This can be used to build a set of completions dynamically
8447 as completion is attempted, rather than loading them all at once.
8448 .PP
8449 For instance, assuming that there is a library of compspecs, each kept in a
8450 file corresponding to the name of the command, the following default
8451 completion function would load completions dynamically:
8452 .RS
8453 .EX
8454 .nf
8455 _completion_loader()
8456 {
8457 . \*"/etc/bash_completion.d/$1.sh\*" \c
8458 .if \n(LL<80n \{\
8459 \e
8460 .br
8461 .ti +4n
8462 .\}
8463 >/dev/null 2>&1 && return 124
8464 }
8465 complete \-D \-F _completion_loader \c
8466 .if \n(LL<80n \{\
8467 \e
8468 .br
8469 .ti +4n
8470 .\}
8471 \-o bashdefault \-o default
8472 .fi
8473 .EE
8474 .RE
8475 .SH HISTORY
8476 When the
8477 .B \-o history
8478 option to the
8479 .B set
8480 builtin is enabled, the shell provides access to the
8481 \fIcommand history\fP,
8482 the list of commands previously typed.
8483 The value of the
8484 .SM
8485 .B HISTSIZE
8486 variable is used as the
8487 number of commands to save in a history list:
8488 the shell saves the text of the last
8489 .SM
8490 .B HISTSIZE
8491 commands (default 500).
8492 The shell stores each command in the history list prior to
8493 parameter and variable expansion (see
8494 .SM
8495 .B EXPANSION
8496 above) but after history expansion is performed, subject to the
8497 values of the shell variables
8498 .SM
8499 .B HISTIGNORE
8500 and
8501 .SM
8502 .BR HISTCONTROL .
8503 .PP
8504 On startup, \fBbash\fP initializes the history list
8505 by reading history entries from the
8506 file named by the
8507 .SM
8508 .B HISTFILE
8509 variable (default
8510 .FN \*~/.bash_history ).
8511 That file is referred to as the \fIhistory file\fP.
8512 The history file is truncated, if necessary,
8513 to contain no more than the number of history entries
8514 specified by the value of the
8515 .SM
8516 .B HISTFILESIZE
8517 variable.
8518 If
8519 .SM
8520 .B HISTFILESIZE
8521 is unset, or set to null, a non-numeric value,
8522 or a numeric value less than zero, the history file is not truncated.
8523 .PP
8524 When the history file is read,
8525 lines beginning with the history comment character followed immediately
8526 by a digit are interpreted as timestamps for the following history line.
8527 These timestamps are optionally displayed depending on the value of the
8528 .SM
8529 .B HISTTIMEFORMAT
8530 variable.
8531 When present, history timestamps delimit history entries, making
8532 multi-line entries possible.
8533 .PP
8534 When a shell with history enabled exits, \fBbash\fP copies the last
8535 .SM
8536 .B $HISTSIZE
8537 entries from the history list to
8538 .SM
8539 .BR $HISTFILE .
8540 If the
8541 .B histappend
8542 shell option is enabled
8543 (see the description of
8544 .B shopt
8545 under
8546 .SM
8547 .B "SHELL BUILTIN COMMANDS"
8548 below), \fBbash\fP appends the entries to the history file,
8549 otherwise it overwrites the history file.
8550 If
8551 .SM
8552 .B HISTFILE
8553 is unset or null,
8554 or if the history file is unwritable, the history is not saved.
8555 After saving the history, \fBbash\fP truncates the history file
8556 to contain no more than
8557 .SM
8558 .B HISTFILESIZE
8559 lines as described above.
8560 .PP
8561 If the
8562 .SM
8563 .B HISTTIMEFORMAT
8564 variable is set, the shell writes
8565 the timestamp information
8566 associated with each history entry to the history file,
8567 marked with the history comment character, so
8568 timestamps are preserved across shell sessions.
8569 This uses the history comment character to distinguish timestamps from
8570 other history lines.
8571 As above, when using
8572 .SM
8573 .BR HISTTIMEFORMAT ,
8574 the timestamps delimit multi-line history entries.
8575 .PP
8576 The
8577 .B fc
8578 builtin command (see
8579 .SM
8580 .B "SHELL BUILTIN COMMANDS"
8581 below) will list or edit and re-execute a portion of the history list.
8582 The
8583 .B history
8584 builtin can display or modify the history list and
8585 manipulate the history file.
8586 When using command-line editing, search commands
8587 are available in each editing mode that provide access to the
8588 history list.
8589 .PP
8590 The shell allows control over which commands are saved on the history list.
8591 The
8592 .SM
8593 .B HISTCONTROL
8594 and
8595 .SM
8596 .B HISTIGNORE
8597 variables are used to save only a subset of the commands entered.
8598 If the
8599 .B cmdhist
8600 shell option is enabled, the shell attempts to save each
8601 line of a multi-line command in the same history entry, adding
8602 semicolons where necessary to preserve syntactic correctness.
8603 The
8604 .B lithist
8605 shell option modifies \fBcmdhist\fP by saving
8606 the command with embedded newlines instead of semicolons.
8607 See the description of the
8608 .B shopt
8609 builtin below under
8610 .SM
8611 .B "SHELL BUILTIN COMMANDS"
8612 for information on setting and unsetting shell options.
8613 .SH "HISTORY EXPANSION"
8614 The shell supports a history expansion feature that
8615 is similar to the history expansion in
8616 .BR csh .
8617 This section describes what syntax features are available.
8618 .PP
8619 History expansion is enabled by default for interactive shells,
8620 and can be disabled using the
8621 .B +H
8622 option to the
8623 .B set
8624 builtin command (see
8625 .SM
8626 .B "SHELL BUILTIN COMMANDS"
8627 below).
8628 Non-interactive shells do not perform history expansion by default,
8629 but it can be enabled with
8630 .Q "set -H" .
8631 .PP
8632 History expansions introduce words from the history list into
8633 the input stream, making it easy to repeat commands, insert the
8634 arguments to a previous command into the current input line, or
8635 fix errors in previous commands quickly.
8636 .PP
8637 History expansion is performed immediately after a complete line
8638 is read, before the shell breaks it into words, and is performed
8639 on each line individually.
8640 The shell attempts to inform the history
8641 expansion functions about quoting still in effect from previous lines.
8642 .PP
8643 It takes place in two parts.
8644 The first is to determine which history list entry
8645 to use during substitution.
8646 The second is to select portions of that entry to include into
8647 the current one.
8648 .PP
8649 The entry selected from the history is the \fIevent\fP,
8650 and the portions of that entry that are acted upon are \fIwords\fP.
8651 Various \fImodifiers\fP are available to manipulate the selected words.
8652 The entry is split into words in the same fashion as when reading input,
8653 so that several \fImetacharacter\fP-separated words surrounded by
8654 quotes are considered one word.
8655 The \fIevent designator\fP selects the event, the optional
8656 \fIword designator\fP selects words from the event, and
8657 various optional \fImodifiers\fP are available to manipulate the
8658 selected words.
8659 .PP
8660 History expansions are introduced by the appearance of the
8661 history expansion character, which is \^\fB!\fP\^ by default.
8662 History expansions may appear anywhere in the input, but do not nest.
8663 .PP
8664 Only backslash (\^\fB\e\fP\^) and single quotes can quote
8665 the history expansion character, but the history expansion character is
8666 also treated as quoted if it immediately precedes the closing double quote
8667 in a double-quoted string.
8668 .PP
8669 Several characters inhibit history expansion if found immediately
8670 following the history expansion character, even if it is unquoted:
8671 space, tab, newline, carriage return, \fB=\fP,
8672 and the other shell metacharacters defined above.
8673 .PP
8674 There is a special abbreviation for substitution, active when the
8675 \fIquick substitution\fP character (described above under
8676 .BR histchars )
8677 is the first character on the line.
8678 It selects the previous history list entry, using an event designator
8679 equivalent to \fB!!\fP,
8680 and substitutes one string for another in that entry.
8681 It is described below under \fBEvent Designators\fP.
8682 This is the only history expansion that does not begin with the history
8683 expansion character.
8684 .PP
8685 Several shell options settable with the
8686 .B shopt
8687 builtin will modify history expansion behavior
8688 (see the description of the
8689 .B shopt
8690 builtin below).and
8691 If the
8692 .B histverify
8693 shell option is enabled, and
8694 .B readline
8695 is being used, history substitutions are not immediately passed to
8696 the shell parser.
8697 Instead, the expanded line is reloaded into the
8698 .B readline
8699 editing buffer for further modification.
8700 If
8701 .B readline
8702 is being used, and the
8703 .B histreedit
8704 shell option is enabled, a failed history substitution is reloaded
8705 into the
8706 .B readline
8707 editing buffer for correction.
8708 .PP
8709 The
8710 .B \-p
8711 option to the
8712 .B history
8713 builtin command shows what a history expansion will
8714 do before using it.
8715 The
8716 .B \-s
8717 option to the
8718 .B history
8719 builtin will add commands to the end of the history list
8720 without actually executing them, so that they are available for
8721 subsequent recall.
8722 .PP
8723 The shell allows control of the various characters used by the
8724 history expansion mechanism (see the description of
8725 .B histchars
8726 above under
8727 .BR "Shell Variables" ).
8728 The shell uses
8729 the history comment character to mark history timestamps when
8730 writing the history file.
8731 .SS Event Designators
8732 An event designator is a reference to an entry in the history list.
8733 The event designator
8734 consists of the portion of the word beginning with the history
8735 expansion character and ending with the word designator if present,
8736 or the end of the word.
8737 Unless the reference is absolute, events are relative to the current
8738 position in the history list.
8739 .PP
8740 .PD 0
8741 .TP
8742 .B !
8743 Start a history substitution, except when followed by a
8744 .BR blank ,
8745 newline, carriage return, =,
8746 or, when the \fBextglob\fP shell option is enabled using
8747 the \fBshopt\fP builtin, (.
8748 .TP
8749 .B !\fIn\fP
8750 Refer to history list entry
8751 .IR n .
8752 .TP
8753 .B !\-\fIn\fP
8754 Refer to the current entry minus
8755 .IR n .
8756 .TP
8757 .B !!
8758 Refer to the previous entry.
8759 This is a synonym for
8760 .Q !\-1 .
8761 .TP
8762 .B !\fIstring\fP
8763 Refer to the most recent command preceding the current position in the
8764 history list starting with
8765 .IR string .
8766 .TP
8767 .B !?\fIstring\fR\fB[?]\fP
8768 Refer to the most recent command preceding the current position in the
8769 history list containing
8770 .IR string .
8771 The trailing \fB?\fP may be omitted if
8772 .I string
8773 is followed immediately by a newline.
8774 If \fIstring\fP is missing, this uses
8775 the string from the most recent search;
8776 it is an error if there is no previous search string.
8777 .TP
8778 .B \d\s+2\*^\s-2\u\fIstring1\fP\d\s+2\*^\s-2\u\fIstring2\fP\d\s+2\*^\s-2\u
8779 Quick substitution.
8780 Repeat the previous command, replacing
8781 .I string1
8782 with
8783 .IR string2 .
8784 Equivalent to
8785 .Q !!:s\d\s+2\*^\s-2\u\fIstring1\fP\d\s+2\*^\s-2\u\fIstring2\fP\d\s+2\*^\s-2\u
8786 (see \fBModifiers\fP below).
8787 .TP
8788 .B !#
8789 The entire command line typed so far.
8790 .PD
8791 .SS Word Designators
8792 Word designators are used to select desired words from the event.
8793 They are optional; if the word designator isn't supplied, the history
8794 expansion uses the entire event.
8795 A
8796 .B :
8797 separates the event specification from the word designator.
8798 It may be omitted if the word designator begins with a
8799 .BR \*^ ,
8800 .BR $ ,
8801 .BR * ,
8802 .BR \- ,
8803 or
8804 .BR % .
8805 Words are numbered from the beginning of the line,
8806 with the first word being denoted by 0 (zero).
8807 Words are inserted into the current line separated by single spaces.
8808 .PP
8809 .PD 0
8810 .TP
8811 .B 0 (zero)
8812 The zeroth word.
8813 For the shell, this is the command word.
8814 .TP
8815 .I n
8816 The \fIn\fPth word.
8817 .TP
8818 .B \*^
8819 The first argument: word 1.
8820 .TP
8821 .B $
8822 The last word.
8823 This is usually the last argument, but will expand to the
8824 zeroth word if there is only one word in the line.
8825 .TP
8826 .B %
8827 The first word matched by the most recent
8828 .Q ?\fIstring\fP?
8829 search,
8830 if the search string begins with a character that is part of a word.
8831 By default, searches begin at the end of each line and proceed to the
8832 beginning, so the first word matched is the one closest to the end of
8833 the line.
8834 .TP
8835 .I x\fB\-\fPy
8836 A range of words;
8837 .Q \-\fIy\fP
8838 abbreviates
8839 .Q 0\-\fIy\fP .
8840 .TP
8841 .B *
8842 All of the words but the zeroth.
8843 This is a synonym for
8844 .Q \fI1\-$\fP .
8845 It is not an error to use
8846 .B *
8847 if there is just one word in the event;
8848 it expands to the empty string in that case.
8849 .TP
8850 .B x*
8851 Abbreviates \fIx\-$\fP.
8852 .TP
8853 .B x\-
8854 Abbreviates \fIx\-$\fP like \fBx*\fP, but omits the last word.
8855 If \fBx\fP is missing, it defaults to 0.
8856 .PD
8857 .PP
8858 If a word designator is supplied without an event specification, the
8859 previous command is used as the event, equivalent to \fB!!\fP.
8860 .SS Modifiers
8861 After the optional word designator, the expansion may include a
8862 sequence of one or more of the following modifiers, each preceded by a
8863 .Q : .
8864 These modify, or edit, the word or words selected from the history event.
8865 .PP
8866 .PD 0
8867 .TP
8868 .B h
8869 Remove a trailing pathname component, leaving only the head.
8870 .TP
8871 .B t
8872 Remove all leading pathname components, leaving the tail.
8873 .TP
8874 .B r
8875 Remove a trailing suffix of the form \fI.xxx\fP, leaving the
8876 basename.
8877 .TP
8878 .B e
8879 Remove all but the trailing suffix.
8880 .TP
8881 .B p
8882 Print the new command but do not execute it.
8883 .TP
8884 .B q
8885 Quote the substituted words, escaping further substitutions.
8886 .TP
8887 .B x
8888 Quote the substituted words as with
8889 .BR q ,
8890 but break into words at
8891 .B blanks
8892 and newlines.
8893 The \fBq\fP and \fBx\fP modifiers are mutually exclusive;
8894 expansion uses the last one supplied.
8895 .TP
8896 .B s/\fIold\fP/\fInew\fP/
8897 Substitute
8898 .I new
8899 for the first occurrence of
8900 .I old
8901 in the event line.
8902 Any character may be used as the delimiter in place of /.
8903 The final delimiter is optional if it is the last character of the
8904 event line.
8905 A single backslash quotes the delimiter in
8906 .I old
8907 and
8908 .IR new .
8909 If & appears in
8910 .IR new ,
8911 it is replaced with
8912 .IR old .
8913 A single backslash quotes the &.
8914 If
8915 .I old
8916 is null, it is set to the last
8917 .I old
8918 substituted, or, if no previous history substitutions took place,
8919 the last
8920 .I string
8921 in a
8922 .B !?\fIstring\fP[?]
8923 search.
8924 If
8925 .I new
8926 is null, each matching
8927 .I old
8928 is deleted.
8929 .TP
8930 .B &
8931 Repeat the previous substitution.
8932 .TP
8933 .B g
8934 Cause changes to be applied over the entire event line.
8935 This is used in conjunction with
8936 .Q \fB:s\fP
8937 (e.g.,
8938 .Q \fB:gs/\fIold\fP/\fInew\fP/\fR )
8939 or
8940 .Q \fB:&\fP .
8941 If used with
8942 .Q \fB:s\fP ,
8943 any delimiter can be used in place of /,
8944 and the final delimiter is optional
8945 if it is the last character of the event line.
8946 An \fBa\fP may be used as a synonym for \fBg\fP.
8947 .TP
8948 .B G
8949 Apply the following
8950 .Q \fBs\fP
8951 or
8952 .Q \fB&\fP
8953 modifier once to each word in the event line.
8954 .PD
8955 .SH "SHELL BUILTIN COMMANDS"
8956 .\" start of bash_builtins
8957 .zZ
8958 .PP
8959 Unless otherwise noted, each builtin command documented in this
8960 section as accepting options preceded by
8961 .B \-
8962 accepts
8963 .B \-\-
8964 to signify the end of the options.
8965 The \fB:\fP, \fBtrue\fP, \fBfalse\fP, and \fBtest\fP/\fB[\fP builtins
8966 do not accept options and do not treat \fB\-\-\fP specially.
8967 The \fBexit\fP, \fBlogout\fP, \fBreturn\fP,
8968 \fBbreak\fP, \fBcontinue\fP, \fBlet\fP,
8969 and \fBshift\fP builtins accept and process arguments beginning with
8970 \fB\-\fP without requiring \fB\-\-\fP.
8971 Other builtins that accept arguments but are not specified as accepting
8972 options interpret arguments beginning with \fB\-\fP as invalid options and
8973 require \fB\-\-\fP to prevent this interpretation.
8974 .PP
8975 .PD 0
8976 .TP
8977 \fB:\fP [\fIarguments\fP]
8978 .PD
8979 No effect; the command does nothing beyond expanding
8980 .I arguments
8981 and performing any specified
8982 redirections.
8983 The return status is zero.
8984 .TP
8985 \fB\&.\&\fP [\fB\-p\fP \fIpath\fP] \fIfilename\fP [\fIarguments\fP]
8986 .PD 0
8987 .TP
8988 \fBsource\fP [\fB\-p\fP \fIpath\fP] \fIfilename\fP [\fIarguments\fP]
8989 .PD
8990 The \fB\&.\&\fP command (\fBsource\fP) reads and execute commands from
8991 .I filename
8992 in the current shell environment and returns the exit status of the
8993 last command executed from
8994 .IR filename .
8995 .IP
8996 If \fIfilename\fP does not contain a slash, \fB\&.\&\fP searches for it.
8997 If the \fB\-p\fP option is supplied, \fB\&.\&\fP treats \fIpath\fP
8998 as a colon-separated list of directories in which to find \fIfilename\fP;
8999 otherwise, \fB\&.\&\fP uses the entries in
9000 .SM
9001 .B PATH
9002 to find the directory containing
9003 .IR filename .
9004 \fIfilename\fP does not need to be executable.
9005 When \fBbash\fP is not in posix mode, it searches
9006 the current directory if \fIfilename\fP is not found in
9007 .SM
9008 .BR PATH ,
9009 but does not search the current directory if \fB\-p\fP is supplied.
9010 If the
9011 .B sourcepath
9012 option to the
9013 .B shopt
9014 builtin command is turned off, \fB\&.\&\fP does not search
9015 .SM
9016 .BR PATH .
9017 .IP
9018 If any \fIarguments\fP are supplied, they become the positional
9019 parameters when \fIfilename\fP is executed.
9020 Otherwise the positional parameters are unchanged.
9021 .IP
9022 If the \fB\-T\fP option is enabled, \fB.\fP inherits any trap on
9023 \fBDEBUG\fP; if it is not, any \fBDEBUG\fP trap string is saved and
9024 restored around the call to \fB.\fP, and \fB.\fP unsets the
9025 \fBDEBUG\fP trap while it executes.
9026 If \fB\-T\fP is not set, and the sourced file changes
9027 the \fBDEBUG\fP trap, the new value persists after \fB.\fP completes.
9028 The return status is the status of the last command executed from
9029 \fIfilename\fP (0 if no commands are executed), and non-zero if
9030 .I filename
9031 is not found or cannot be read.
9032 .TP
9033 \fBalias\fP [\fB\-p\fP] [\fIname\fP[=\fIvalue\fP] .\|.\|.]
9034 With no arguments or with the
9035 .B \-p
9036 option, \fBalias\fP prints the list of aliases in the form
9037 \fBalias\fP \fIname\fP=\fIvalue\fP on standard output.
9038 When arguments are supplied, define an alias for
9039 each \fIname\fP whose \fIvalue\fP is given.
9040 A trailing space in \fIvalue\fP causes the next word to be
9041 checked for alias substitution when the alias is expanded
9042 during command parsing.
9043 For each \fIname\fP in the argument list for which no \fIvalue\fP
9044 is supplied, print the name and value of the alias \fIname\fP.
9045 \fBalias\fP returns true unless a \fIname\fP is given
9046 (without a corresponding =\fIvalue\fP)
9047 for which no alias has been defined.
9048 .TP
9049 \fBbg\fP [\fIjobspec\fP .\|.\|.]
9050 Resume each suspended job \fIjobspec\fP in the background, as if it
9051 had been started with
9052 .BR & .
9053 If
9054 .I jobspec
9055 is not present, the shell uses its notion of the \fIcurrent job\fP.
9056 .B bg
9057 .I jobspec
9058 returns 0 unless run when job control is disabled or, when run with
9059 job control enabled, any specified \fIjobspec\fP was not found
9060 or was started without job control.
9061 .TP
9062 \fBbind\fP [\fB\-m\fP \fIkeymap\fP] [\fB\-lsvSVX\fP]
9063 .PD 0
9064 .TP
9065 \fBbind\fP [\fB\-m\fP \fIkeymap\fP] [\fB\-q\fP \fIfunction\fP] [\fB\-u\fP \fIfunction\fP] [\fB\-r\fP \fIkeyseq\fP]
9066 .TP
9067 \fBbind\fP [\fB\-m\fP \fIkeymap\fP] \fB\-f\fP \fIfilename\fP
9068 .TP
9069 \fBbind\fP [\fB\-m\fP \fIkeymap\fP] \fB\-x\fP \fIkeyseq\fP[:] \fIshell\-command\fP
9070 .TP
9071 \fBbind\fP [\fB\-m\fP \fIkeymap\fP] \fIkeyseq\fP:\fIfunction\-name\fP
9072 .TP
9073 \fBbind\fP [\fB\-m\fP \fIkeymap\fP] \fB\-p\fP|\fB\-P\fP [\fIreadline\-command\fP]
9074 .TP
9075 \fBbind\fP [\fB\-m\fP \fIkeymap\fP] \fIkeyseq\fP:\fIreadline\-command\fP
9076 .TP
9077 \fBbind\fP \fIreadline-command-line\fP
9078 .PD
9079 Display current
9080 .B readline
9081 key and function bindings, bind a key sequence to a
9082 .B readline
9083 function or macro
9084 or to a shell command, or set a
9085 .B readline
9086 variable.
9087 Each non-option argument is a key binding or command as it would appear in a
9088 .B readline
9089 initialization file such as
9090 .IR .inputrc ,
9091 but each binding or command must be passed as a separate argument;
9092 e.g., \*'\*"\eC\-x\eC\-r\*": re\-read\-init\-file\*'.
9093 In the following descriptions, output available to be re-read is formatted
9094 as commands that would appear in a
9095 .B readline
9096 initialization file or that would be supplied as individual arguments to a
9097 .B bind
9098 command.
9099 Options, if supplied, have the following meanings:
9100 .RS
9101 .PD 0
9102 .TP
9103 .B \-m \fIkeymap\fP
9104 Use
9105 .I keymap
9106 as the keymap to be affected by the subsequent bindings.
9107 Acceptable
9108 .I keymap
9109 names are
9110 \fIemacs, emacs\-standard, emacs\-meta, emacs\-ctlx, vi,
9111 vi\-move, vi\-command\fP, and
9112 .IR vi\-insert .
9113 \fIvi\fP is equivalent to \fIvi\-command\fP
9114 (\fIvi\-move\fP is also a synonym);
9115 \fIemacs\fP is equivalent to \fIemacs\-standard\fP.
9116 .TP
9117 .B \-l
9118 List the names of all \fBreadline\fP functions.
9119 .TP
9120 .B \-p
9121 Display \fBreadline\fP function names and bindings in such a way
9122 that they can be
9123 used as an argument to a subsequent
9124 \fBbind\fP command or in a \fBreadline\fP initialization file.
9125 If arguments remain after option processing, \fBbind\fP treats
9126 them as \fBreadline\fP command names and restricts output to those names.
9127 .TP
9128 .B \-P
9129 List current \fBreadline\fP function names and bindings.
9130 If arguments remain after option processing, \fBbind\fP treats
9131 them as \fBreadline\fP command names and restricts output to those names.
9132 .TP
9133 .B \-s
9134 Display \fBreadline\fP key sequences bound to macros and the strings
9135 they output in such a way that they can be used
9136 as an argument to a subsequent \fBbind\fP command
9137 or in a \fBreadline\fP initialization file.
9138 .TP
9139 .B \-S
9140 Display \fBreadline\fP key sequences bound to macros and the strings
9141 they output.
9142 .TP
9143 .B \-v
9144 Display \fBreadline\fP variable names and values in such a way that they
9145 can be
9146 used as an argument to a subsequent
9147 \fBbind\fP command or in a \fBreadline\fP initialization file.
9148 .TP
9149 .B \-V
9150 List current \fBreadline\fP variable names and values.
9151 .TP
9152 .B \-f \fIfilename\fP
9153 Read key bindings from \fIfilename\fP.
9154 .TP
9155 .B \-q \fIfunction\fP
9156 Display key sequences that invoke the named \fBreadline\fP \fIfunction\fP.
9157 .TP
9158 .B \-u \fIfunction\fP
9159 Unbind all key sequences bound to the named \fBreadline\fP \fIfunction\fP.
9160 .TP
9161 .B \-r \fIkeyseq\fP
9162 Remove any current binding for \fIkeyseq\fP.
9163 .TP
9164 .B \-x \fIkeyseq\fP[: ]\fIshell\-command\fP
9165 Cause \fIshell\-command\fP to be executed whenever \fIkeyseq\fP is
9166 entered.
9167 The separator between \fIkeyseq\fP and \fIshell\-command\fP is either
9168 whitespace or a colon optionally followed by whitespace.
9169 If the separator is whitespace, \fIshell\-command\fP
9170 must be enclosed in double quotes and \fBreadline\fP expands any of its
9171 special backslash-escapes in \fIshell\-command\fP before saving it.
9172 If the separator is a colon, any enclosing double quotes are optional, and
9173 \fBreadline\fP does not expand the command string before saving it.
9174 Since the entire key binding expression must be a single argument, it
9175 should be enclosed in single quotes.
9176 When \fIshell\-command\fP is executed, the shell sets the
9177 .SM
9178 .B READLINE_LINE
9179 variable to the contents of the \fBreadline\fP line buffer and the
9180 .SM
9181 .B READLINE_POINT
9182 and
9183 .SM
9184 .B READLINE_MARK
9185 variables to the current location of the insertion point and the saved
9186 insertion point (the mark), respectively.
9187 The shell assigns any numeric argument the user supplied to the
9188 .SM
9189 .B READLINE_ARGUMENT
9190 variable.
9191 If there was no argument, that variable is not set.
9192 If the executed command changes the value of any of
9193 .SM
9194 .BR READLINE_LINE ,
9195 .SM
9196 .BR READLINE_POINT ,
9197 or
9198 .SM
9199 .BR READLINE_MARK ,
9200 those new values will be reflected in the editing state.
9201 .TP
9202 .B \-X
9203 List all key sequences bound to shell commands and the associated commands
9204 in a format that can be reused as
9205 an argument to a subsequent \fBbind\fP command.
9206 .PD
9207 .PP
9208 The return value is 0 unless an unrecognized option is supplied or an
9209 error occurred.
9210 .RE
9211 .TP
9212 \fBbreak\fP [\fIn\fP]
9213 Exit from within a
9214 .BR for ,
9215 .BR while ,
9216 .BR until ,
9217 or
9218 .B select
9219 loop.
9220 If \fIn\fP is specified, \fBbreak\fP exits \fIn\fP enclosing loops.
9221 .I n
9222 must be \(>= 1. If
9223 .I n
9224 is greater than the number of enclosing loops, all enclosing loops
9225 are exited.
9226 The return value is 0 unless \fIn\fP is not greater than or equal to 1.
9227 .TP
9228 \fBbuiltin\fP \fIshell\-builtin\fP [\fIarguments\fP]
9229 Execute the specified shell builtin \fIshell\-builtin\fP, passing it
9230 .IR arguments ,
9231 and return its exit status.
9232 This is useful when defining a
9233 function whose name is the same as a shell builtin,
9234 retaining the functionality of the builtin within the function.
9235 The \fBcd\fP builtin is commonly redefined this way.
9236 The return status is false if
9237 .I shell\-builtin
9238 is not a shell builtin command.
9239 .TP
9240 \fBcaller\fP [\fIexpr\fP]
9241 Returns the context of any active subroutine call (a shell function or
9242 a script executed with the \fB.\fP or \fBsource\fP builtins).
9243 .IP
9244 Without \fIexpr\fP, \fBcaller\fP displays the line number and source
9245 filename of the current subroutine call.
9246 If a non-negative integer is supplied as \fIexpr\fP, \fBcaller\fP
9247 displays the line number, subroutine name, and source file corresponding
9248 to that position in the current execution call stack.
9249 This extra information may be used, for example, to print a stack trace.
9250 The current frame is frame 0.
9251 .IP
9252 The return value is 0 unless the shell is not executing a subroutine
9253 call or \fIexpr\fP does not correspond to a valid position in the
9254 call stack.
9255 .TP
9256 .PD 0
9257 \fBcd\fP [\fB\-L\fP] [\fB\-@\fP] [\fIdir\fP]
9258 .TP
9259 \fBcd\fP \fB\-P\fP [\fB\-e\fP] [\fB\-@\fP] [\fIdir\fP]
9260 .PD
9261 Change the current directory to \fIdir\fP.
9262 if \fIdir\fP is not supplied, the value of the
9263 .SM
9264 .B HOME
9265 shell variable is used as \fIdir\fP.
9266 The variable
9267 .SM
9268 .B CDPATH
9269 exists,
9270 and \fIdir\fP does not begin with a slash (/),
9271 \fBcd\fP uses it as a search path:
9272 the shell searches each directory name in
9273 .SM
9274 .B CDPATH
9275 for \fIdir\fP.
9276 Alternative directory names in
9277 .SM
9278 .B CDPATH
9279 are separated by a colon (:).
9280 A null directory name in
9281 .SM
9282 .B CDPATH
9283 is the same as the current directory, i.e.,
9284 .Q .\& .
9285 .IP
9286 The
9287 .B \-P
9288 option causes \fBcd\fP to use the physical directory structure
9289 by resolving symbolic links while traversing \fIdir\fP and
9290 before processing instances of
9291 .FN .\|.\&
9292 in \fIdir\fP (see also the
9293 .B \-P
9294 option to the
9295 .B set
9296 builtin command).
9297 .IP
9298 The
9299 .B \-L
9300 option forces \fBcd\fP to follow symbolic links by resolving the link
9301 after processing instances of
9302 .FN .\|.\&
9303 in \fIdir\fP.
9304 If
9305 .FN .\|.\&
9306 appears in \fIdir\fP, \fBcd\fP processes it by removing the
9307 immediately previous pathname component from \fIdir\fP, back to a slash
9308 or the beginning of \fIdir\fP,
9309 and verifying that the portion of \fIdir\fP it has processed to
9310 that point is still a valid directory name after removing the pathname
9311 component.
9312 If it is not a valid directory name, \fBcd\fP returns a non-zero status.
9313 If neither
9314 .B \-L
9315 nor
9316 .B \-P
9317 is supplied,
9318 .B cd
9319 behaves as if
9320 .B \-L
9321 had been supplied.
9322 .IP
9323 If the
9324 .B \-e
9325 option is supplied with
9326 .BR \-P ,
9327 and \fBcd\fP cannot successfully determine the current working directory
9328 after a successful directory change, it returns a non-zero status.
9329 .IP
9330 On systems that support it, the \fB\-@\fP option presents the extended
9331 attributes associated with a file as a directory.
9332 .IP
9333 An argument of
9334 .B \-
9335 is converted to
9336 .SM
9337 .B $OLDPWD
9338 before attempting the directory change.
9339 .IP
9340 If \fBcd\fP uses a non-empty directory name from
9341 .SM
9342 .BR CDPATH ,
9343 or if \fB\-\fP is the first argument, and the directory change is
9344 successful, \fBcd\fP writes the absolute pathname of the new
9345 working directory to the standard output.
9346 .IP
9347 If the directory change is successful, \fBcd\fP sets the value of the
9348 \fBPWD\fP environment variable to the new directory name, and sets the
9349 \fBOLDPWD\fP environment variable to the value of the current working
9350 directory before the change.
9351 .IP
9352 The return value is true if the directory was successfully changed;
9353 false otherwise.
9354 .TP
9355 \fBcommand\fP [\fB\-pVv\fP] \fIcommand\fP [\fIarg\fP .\|.\|.]
9356 The \fBcommand\fP builtin runs
9357 .I command
9358 with
9359 .I args
9360 suppressing the normal shell function lookup for \fIcommand\fP.
9361 Only builtin commands or commands found in the
9362 .SM
9363 .B PATH
9364 named \fIcommand\fP are executed.
9365 If the
9366 .B \-p
9367 option is supplied, the search for
9368 .I command
9369 is performed using a default value for
9370 .SM
9371 .B PATH
9372 that is guaranteed to find all of the standard utilities.
9373 .IP
9374 If either the
9375 .B \-V
9376 or
9377 .B \-v
9378 option is supplied, \fBcommand\fP prints a description of
9379 .IR command .
9380 The
9381 .B \-v
9382 option displays a single word indicating the command or filename
9383 used to invoke
9384 .IR command ;
9385 the
9386 .B \-V
9387 option produces a more verbose description.
9388 .IP
9389 If the
9390 .B \-V
9391 or
9392 .B \-v
9393 option is supplied, the exit status is zero if
9394 .I command
9395 was found, and non-zero if not.
9396 If neither option is supplied and an error occurred or
9397 .I command
9398 cannot be found, the exit status is 127.
9399 Otherwise, the exit status of the
9400 .B command
9401 builtin is the exit status of
9402 .IR command .
9403 .TP
9404 \fBcompgen\fP [\fB\-V\fP \fIvarname\fP] [\fIoption\fP] [\fIword\fP]
9405 Generate possible completion matches for \fIword\fP according to
9406 the \fIoption\fPs, which may be any option accepted by the
9407 .B complete
9408 builtin with the exceptions of
9409 .BR \-p ,
9410 .BR \-r ,
9411 .BR \-D ,
9412 .BR \-E ,
9413 and
9414 .BR \-I ,
9415 and write the matches to the standard output.
9416 .IP
9417 If the \fB\-V\fP option is supplied, \fBcompgen\fP stores the generated
9418 completions into the indexed array variable \fIvarname\fP instead of writing
9419 them to the standard output.
9420 .IP
9421 When using the \fB\-F\fP or \fB\-C\fP options, the various shell variables
9422 set by the programmable completion facilities, while available, will not
9423 have useful values.
9424 .IP
9425 The matches will be generated in the same way as if the programmable
9426 completion code had generated them directly from a completion specification
9427 with the same flags.
9428 If \fIword\fP is specified, only those completions matching \fIword\fP
9429 will be displayed or stored.
9430 .IP
9431 The return value is true unless an invalid option is supplied, or no
9432 matches were generated.
9433 .TP
9434 \fBcomplete\fP [\fB\-abcdefgjksuv\fP] [\fB\-o\fP \fIcomp-option\fP] [\fB\-DEI\fP] [\fB\-A\fP \fIaction\fP]
9435 .br
9436 [\fB\-G\fP \fIglobpat\fP] [\fB\-W\fP \fIwordlist\fP] [\fB\-F\fP \fIfunction\fP] [\fB\-C\fP \fIcommand\fP]
9437 .br
9438 [\fB\-X\fP \fIfilterpat\fP] [\fB\-P\fP \fIprefix\fP] \
9439 [\fB\-S\fP \fIsuffix\fP] \fIname\fP [\fIname\fP .\|.\|.]
9440 .PD 0
9441 .TP
9442 \fBcomplete\fP \fB\-pr\fP [\fB\-DEI\fP] [\fIname\fP .\|.\|.]
9443 .PD
9444 Specify how arguments to each \fIname\fP should be completed.
9445 .IP
9446 If the \fB\-p\fP option is supplied, or if no options or \fIname\fPs
9447 are supplied, print existing completion specifications
9448 in a way that allows them to be reused as input.
9449 The \fB\-r\fP option removes a completion specification for
9450 each \fIname\fP, or, if no \fIname\fPs are supplied, all
9451 completion specifications.
9452 .IP
9453 The \fB\-D\fP option indicates that other supplied options and actions should
9454 apply to the
9455 .Q default
9456 command completion; that is, completion attempted
9457 on a command for which no completion has previously been defined.
9458 The \fB\-E\fP option indicates that other supplied options and actions should
9459 apply to
9460 .Q empty
9461 command completion; that is, completion attempted on a
9462 blank line.
9463 The \fB\-I\fP option indicates that other supplied options and actions should
9464 apply to completion on the initial non-assignment word on the line, or after
9465 a command delimiter such as \fB;\fP or \fB|\fP, which is usually command
9466 name completion.
9467 If multiple options are supplied, the \fB\-D\fP option takes precedence
9468 over \fB\-E\fP, and both take precedence over \fB\-I\fP.
9469 If any of \fB\-D\fP, \fB\-E\fP, or \fB\-I\fP are supplied, any other
9470 \fIname\fP arguments are ignored; these completions only apply to the case
9471 specified by the option.
9472 .IP
9473 The process of applying these completion specifications when
9474 attempting word completion is described
9475 .ie \n(zZ=1 in \fIbash\fP(1).
9476 .el above under \fBProgrammable Completion\fP.
9477 .IP
9478 Other options, if specified, have the following meanings.
9479 The arguments to the \fB\-G\fP, \fB\-W\fP, and \fB\-X\fP options
9480 (and, if necessary, the \fB\-P\fP and \fB\-S\fP options)
9481 should be quoted to protect them from expansion before the
9482 .B complete
9483 builtin is invoked.
9484 .IP
9485 .RS
9486 .PD 0
9487 .TP 8
9488 \fB\-o\fP \fIcomp-option\fP
9489 The \fIcomp-option\fP controls several aspects of the compspec's behavior
9490 beyond the simple generation of completions.
9491 \fIcomp-option\fP may be one of:
9492 .RS
9493 .TP 8
9494 .B bashdefault
9495 Perform the rest of the default \fBbash\fP completions if the compspec
9496 generates no matches.
9497 .TP 8
9498 .B default
9499 Use \fBreadline\fP's default filename completion if the compspec generates
9500 no matches.
9501 .TP 8
9502 .B dirnames
9503 Perform directory name completion if the compspec generates no matches.
9504 .TP 8
9505 .B filenames
9506 Tell \fBreadline\fP that the compspec generates filenames, so it can perform
9507 any filename\-specific processing (such as adding a slash to directory names,
9508 quoting special characters, or suppressing trailing spaces).
9509 This is intended to be used with shell functions.
9510 .TP 8
9511 .B fullquote
9512 Tell \fBreadline\fP to quote all the completed words even if they are not
9513 filenames.
9514 .TP 8
9515 .B noquote
9516 Tell \fBreadline\fP not to quote the completed words if they are filenames
9517 (quoting filenames is the default).
9518 .TP 8
9519 .B nosort
9520 Tell \fBreadline\fP not to sort the list of possible completions
9521 alphabetically.
9522 .TP 8
9523 .B nospace
9524 Tell \fBreadline\fP not to append a space (the default) to words completed
9525 at the end of the line.
9526 .TP 8
9527 .B plusdirs
9528 After generating any matches defined by the compspec,
9529 attempt directory name completion and add any
9530 matches to the results of the other actions.
9531 .RE
9532 .TP 8
9533 \fB\-A\fP \fIaction\fP
9534 The \fIaction\fP may be one of the following to generate a list of possible
9535 completions:
9536 .RS
9537 .TP 8
9538 .B alias
9539 Alias names.
9540 May also be specified as \fB\-a\fP.
9541 .TP 8
9542 .B arrayvar
9543 Array variable names.
9544 .TP 8
9545 .B binding
9546 \fBReadline\fP key binding names.
9547 .TP 8
9548 .B builtin
9549 Names of shell builtin commands.
9550 May also be specified as \fB\-b\fP.
9551 .TP 8
9552 .B command
9553 Command names.
9554 May also be specified as \fB\-c\fP.
9555 .TP 8
9556 .B directory
9557 Directory names.
9558 May also be specified as \fB\-d\fP.
9559 .TP 8
9560 .B disabled
9561 Names of disabled shell builtins.
9562 .TP 8
9563 .B enabled
9564 Names of enabled shell builtins.
9565 .TP 8
9566 .B export
9567 Names of exported shell variables.
9568 May also be specified as \fB\-e\fP.
9569 .TP 8
9570 .B file
9571 File and directory names, similar to \fBreadline\fP's filename completion.
9572 May also be specified as \fB\-f\fP.
9573 .TP 8
9574 .B function
9575 Names of shell functions.
9576 .TP 8
9577 .B group
9578 Group names.
9579 May also be specified as \fB\-g\fP.
9580 .TP 8
9581 .B helptopic
9582 Help topics as accepted by the \fBhelp\fP builtin.
9583 .TP 8
9584 .B hostname
9585 Hostnames, as taken from the file specified by the
9586 .SM
9587 .B HOSTFILE
9588 shell variable.
9589 .TP 8
9590 .B job
9591 Job names, if job control is active.
9592 May also be specified as \fB\-j\fP.
9593 .TP 8
9594 .B keyword
9595 Shell reserved words.
9596 May also be specified as \fB\-k\fP.
9597 .TP 8
9598 .B running
9599 Names of running jobs, if job control is active.
9600 .TP 8
9601 .B service
9602 Service names.
9603 May also be specified as \fB\-s\fP.
9604 .TP 8
9605 .B setopt
9606 Valid arguments for the \fB\-o\fP option to the \fBset\fP builtin.
9607 .TP 8
9608 .B shopt
9609 Shell option names as accepted by the \fBshopt\fP builtin.
9610 .TP 8
9611 .B signal
9612 Signal names.
9613 .TP 8
9614 .B stopped
9615 Names of stopped jobs, if job control is active.
9616 .TP 8
9617 .B user
9618 User names.
9619 May also be specified as \fB\-u\fP.
9620 .TP 8
9621 .B variable
9622 Names of all shell variables.
9623 May also be specified as \fB\-v\fP.
9624 .RE
9625 .TP 8
9626 \fB\-C\fP \fIcommand\fP
9627 \fIcommand\fP is executed in a subshell environment, and its output is
9628 used as the possible completions.
9629 Arguments are passed as with the \fB\-F\fP option.
9630 .TP 8
9631 \fB\-F\fP \fIfunction\fP
9632 The shell function \fIfunction\fP is executed in the current shell
9633 environment.
9634 When the function is executed,
9635 the first argument (\fB$1\fP) is the name of the command whose arguments are
9636 being completed,
9637 the second argument (\fB$2\fP) is the word being completed, and
9638 the third argument (\fB$3\fP) is the word preceding the word being
9639 completed on the current command line.
9640 When \fIfunction\fP finishes,
9641 programmable completion retrieves
9642 the possible completions from the value of the
9643 .SM
9644 .B COMPREPLY
9645 array variable.
9646 .TP 8
9647 \fB\-G\fP \fIglobpat\fP
9648 Expand the pathname expansion pattern \fIglobpat\fP to generate
9649 the possible completions.
9650 .TP 8
9651 \fB\-P\fP \fIprefix\fP
9652 Add \fIprefix\fP to the beginning of each possible completion
9653 after all other options have been applied.
9654 .TP 8
9655 \fB\-S\fP \fIsuffix\fP
9656 Append \fIsuffix\fP to each possible completion
9657 after all other options have been applied.
9658 .TP 8
9659 \fB\-W\fP \fIwordlist\fP
9660 Split the \fIwordlist\fP using the characters in the
9661 .SM
9662 .B IFS
9663 special variable as delimiters, and expand each resulting word.
9664 Shell quoting is honored within \fIwordlist\fP,
9665 in order to provide a
9666 mechanism for the words to contain shell metacharacters or characters
9667 in the value of
9668 .SM
9669 .BR IFS .
9670 The possible completions are the members of the resultant list which
9671 match a prefix of the word being completed.
9672 .TP 8
9673 \fB\-X\fP \fIfilterpat\fP
9674 \fIfilterpat\fP is a pattern as used for pathname expansion.
9675 It is applied to the list of possible completions generated by the
9676 preceding options and arguments, and each completion matching
9677 \fIfilterpat\fP is removed from the list.
9678 A leading \fB!\fP in \fIfilterpat\fP negates the pattern; in this
9679 case, any completion not matching \fIfilterpat\fP is removed.
9680 .PD
9681 .PP
9682 The return value is true unless an invalid option is supplied, an option
9683 other than
9684 .BR \-p ,
9685 .BR \-r ,
9686 .BR \-D ,
9687 .BR \-E ,
9688 or
9689 .B \-I
9690 is supplied without a \fIname\fP
9691 argument, an attempt is made to remove a completion specification for
9692 a \fIname\fP for which no specification exists, or
9693 an error occurs adding a completion specification.
9694 .RE
9695 .TP
9696 \fBcompopt\fP [\fB\-o\fP \fIoption\fP] [\fB\-DEI\fP] [\fB+o\fP \fIoption\fP] [\fIname\fP]
9697 Modify completion options for each \fIname\fP according to the
9698 \fIoption\fPs, or for the
9699 currently-executing completion if no \fIname\fPs are supplied.
9700 If no \fIoption\fPs are supplied, display the completion options for each
9701 \fIname\fP or the current completion.
9702 The possible values of \fIoption\fP are those valid for the \fBcomplete\fP
9703 builtin described above.
9704 .IP
9705 The \fB\-D\fP option indicates that other supplied options should
9706 apply to the
9707 .Q default
9708 command completion;
9709 the \fB\-E\fP option indicates that other supplied options should
9710 apply to
9711 .Q empty
9712 command completion; and
9713 the \fB\-I\fP option indicates that other supplied options should
9714 apply to completion on the initial word on the line.
9715 These are determined in the same way as the \fBcomplete\fP builtin.
9716 .IP
9717 If multiple options are supplied, the \fB\-D\fP option takes precedence
9718 over \fB\-E\fP, and both take precedence over \fB\-I\fP.
9719 .IP
9720 The return value is true unless an invalid option is supplied, an attempt
9721 is made to modify the options for a \fIname\fP for which no completion
9722 specification exists, or an output error occurs.
9723 .TP
9724 \fBcontinue\fP [\fIn\fP]
9725 \fBcontinue\fP resumes the next iteration of the enclosing
9726 .BR for ,
9727 .BR while ,
9728 .BR until ,
9729 or
9730 .B select
9731 loop.
9732 If
9733 .I n
9734 is specified, \fBbash\fP resumes the \fIn\fPth enclosing loop.
9735 .I n
9736 must be \(>= 1.
9737 If
9738 .I n
9739 is greater than the number of enclosing loops, the shell resumes
9740 the last enclosing loop
9741 (the
9742 .Q top-level
9743 loop).
9744 The return value is 0 unless \fIn\fP is not greater than or equal to 1.
9745 .TP
9746 \fBdeclare\fP [\fB\-aAfFgiIlnrtux\fP] [\fB\-p\fP] \
9747 [\fIname\fP[=\fIvalue\fP] .\|.\|.]
9748 .PD 0
9749 .TP
9750 \fBtypeset\fP [\fB\-aAfFgiIlnrtux\fP] [\fB\-p\fP] \
9751 [\fIname\fP[=\fIvalue\fP] .\|.\|.]
9752 .PD
9753 Declare variables and/or give them attributes.
9754 If no \fIname\fPs are given then display the values of variables
9755 or functions.
9756 The
9757 .B \-p
9758 option will display the attributes and values of each
9759 .IR name .
9760 When
9761 .B \-p
9762 is used with \fIname\fP arguments, additional options,
9763 other than \fB\-f\fP and \fB\-F\fP, are ignored.
9764 .IP
9765 When
9766 .B \-p
9767 is supplied without \fIname\fP arguments,
9768 \fBdeclare\fP will display the attributes and values
9769 of all variables having the attributes specified by the additional options.
9770 If no other options are supplied with \fB\-p\fP, \fBdeclare\fP will
9771 display the attributes and values of all shell variables.
9772 The \fB\-f\fP option restricts the display to shell functions.
9773 .IP
9774 The
9775 .B \-F
9776 option inhibits the display of function definitions; only the
9777 function name and attributes are printed.
9778 If the \fBextdebug\fP shell option is enabled using \fBshopt\fP,
9779 the source file name and line number where each \fIname\fP
9780 is defined are displayed as well.
9781 The
9782 .B \-F
9783 option implies
9784 .BR \-f .
9785 .IP
9786 The
9787 .B \-g
9788 option forces variables to be created or modified at the global scope,
9789 even when \fBdeclare\fP is executed in a shell function.
9790 It is ignored when \fBdeclare\fP is not executed in a shell function.
9791 .IP
9792 The
9793 .B \-I
9794 option causes local variables to inherit the attributes
9795 (except the \fInameref\fP attribute)
9796 and value of any existing variable with the same
9797 \fIname\fP at a surrounding scope.
9798 If there is no existing variable, the local variable is initially unset.
9799 .IP
9800 The following options can
9801 be used to restrict output to variables with the specified attribute or
9802 to give variables attributes:
9803 .RS
9804 .PD 0
9805 .TP
9806 .B \-a
9807 Each \fIname\fP is an indexed array variable (see
9808 .B Arrays
9809 .ie \n(zZ=1 in \fIbash\fP(1)).
9810 .el above).
9811 .TP
9812 .B \-A
9813 Each \fIname\fP is an associative array variable (see
9814 .B Arrays
9815 .ie \n(zZ=1 in \fIbash\fP(1)).
9816 .el above).
9817 .TP
9818 .B \-f
9819 Each \fIname\fP refers to a shell function.
9820 .TP
9821 .B \-i
9822 The variable is treated as an integer;
9823 arithmetic evaluation (see
9824 .SM
9825 .B "ARITHMETIC EVALUATION"
9826 .ie \n(zZ=1 in \fIbash\fP(1))
9827 .el above)
9828 is performed when the variable is assigned a value.
9829 .TP
9830 .B \-l
9831 When the variable is assigned a value, all upper-case characters are
9832 converted to lower-case.
9833 The upper-case attribute is disabled.
9834 .TP
9835 .B \-n
9836 Give each \fIname\fP the \fInameref\fP attribute, making
9837 it a name reference to another variable.
9838 That other variable is defined by the value of \fIname\fP.
9839 All references, assignments, and attribute modifications
9840 to \fIname\fP, except those using or changing the
9841 \fB\-n\fP attribute itself, are performed on the variable referenced by
9842 \fIname\fP's value.
9843 The nameref attribute cannot be applied to array variables.
9844 .TP
9845 .B \-r
9846 Make \fIname\fPs readonly.
9847 These names cannot then be assigned values
9848 by subsequent assignment statements or unset.
9849 .TP
9850 .B \-t
9851 Give each \fIname\fP the \fItrace\fP attribute.
9852 Traced functions inherit the \fBDEBUG\fP and \fBRETURN\fP traps from
9853 the calling shell.
9854 The trace attribute has no special meaning for variables.
9855 .TP
9856 .B \-u
9857 When the variable is assigned a value, all lower-case characters are
9858 converted to upper-case.
9859 The lower-case attribute is disabled.
9860 .TP
9861 .B \-x
9862 Mark each \fIname\fP for export to subsequent commands via the environment.
9863 .PD
9864 .PP
9865 Using
9866 .Q +
9867 instead of
9868 .Q \-
9869 turns off the specified
9870 attribute instead, with the exceptions that \fB+a\fP and \fB+A\fP
9871 may not be used to destroy array variables and \fB+r\fP will not
9872 remove the readonly attribute.
9873 .PP
9874 When used in a function,
9875 .B declare
9876 and
9877 .B typeset
9878 make each
9879 \fIname\fP local, as with the
9880 .B local
9881 command,
9882 unless the \fB\-g\fP option is supplied.
9883 If a variable name is followed by =\fIvalue\fP, the value of
9884 the variable is set to \fIvalue\fP.
9885 When using \fB\-a\fP or \fB\-A\fP and the compound assignment syntax to
9886 create array variables, additional attributes do not take effect until
9887 subsequent assignments.
9888 .PP
9889 The return value is 0 unless an invalid option is encountered,
9890 an attempt is made to define a function using
9891 .Q "\-f foo=bar" ,
9892 an attempt is made to assign a value to a readonly variable,
9893 an attempt is made to assign a value to an array variable without
9894 using the compound assignment syntax (see
9895 .B Arrays
9896 .ie \n(zZ=1 in \fIbash\fP(1)),
9897 .el above),
9898 one of the \fInames\fP is not a valid shell variable name,
9899 an attempt is made to turn off readonly status for a readonly variable,
9900 an attempt is made to turn off array status for an array variable,
9901 or an attempt is made to display a non-existent function with \fB\-f\fP.
9902 .RE
9903 .TP
9904 .B dirs [\fB\-clpv\fP] [+\fIn\fP] [\-\fIn\fP]
9905 Without options, display the list of currently remembered directories.
9906 The default display is on a single line with directory names separated
9907 by spaces.
9908 Directories are added to the list with the
9909 .B pushd
9910 command; the
9911 .B popd
9912 command removes entries from the list.
9913 The current directory is always the first directory in the stack.
9914 .IP
9915 Options, if supplied, have the following meanings:
9916 .RS
9917 .PD 0
9918 .TP
9919 .B \-c
9920 Clears the directory stack by deleting all of the entries.
9921 .TP
9922 .B \-l
9923 Produces a listing using full pathnames;
9924 the default listing format uses a tilde to denote the home directory.
9925 .TP
9926 .B \-p
9927 Print the directory stack with one entry per line.
9928 .TP
9929 .B \-v
9930 Print the directory stack with one entry per line,
9931 prefixing each entry with its index in the stack.
9932 .TP
9933 \fB+\fP\fIn\fP
9934 Displays the \fIn\fPth entry counting from the left of the list
9935 shown by
9936 .B dirs
9937 when invoked without options, starting with zero.
9938 .TP
9939 \fB\-\fP\fIn\fP
9940 Displays the \fIn\fPth entry counting from the right of the list
9941 shown by
9942 .B dirs
9943 when invoked without options, starting with zero.
9944 .PD
9945 .PP
9946 The return value is 0 unless an
9947 invalid option is supplied or \fIn\fP indexes beyond the end
9948 of the directory stack.
9949 .RE
9950 .TP
9951 \fBdisown\fP [\fB\-ar\fP] [\fB\-h\fP] [\fIid\fP .\|.\|.]
9952 Without options, remove each
9953 .I id
9954 from the table of active jobs.
9955 Each \fIid\fP may be a job specification \fIjobspec\fP
9956 or a process ID \fIpid\fP;
9957 if \fIid\fP is a \fIpid\fP,
9958 \fBdisown\fP uses the job containing \fIpid\fP as \fIjobspec\fP.
9959 .IP
9960 If the \fB\-h\fP option is supplied,
9961 \fBdisown\fP does not remove the jobs corresponding to each
9962 .I id
9963 from the jobs table,
9964 but rather marks them so the shell does not send
9965 .SM
9966 .B SIGHUP
9967 to the job if the shell receives a
9968 .SM
9969 .BR SIGHUP .
9970 .IP
9971 If no
9972 .I id
9973 is supplied, the
9974 .B \-a
9975 option means to remove or mark all jobs; the
9976 .B \-r
9977 option without an
9978 .I id
9979 argument removes or marks running jobs.
9980 If no
9981 .I id
9982 is supplied, and neither the \fB\-a\fP nor the \fB\-r\fP option
9983 is supplied, \fBdisown\fP removes or marks the current job.
9984 .IP
9985 The return value is 0 unless an
9986 .I id
9987 does not specify a valid job.
9988 .TP
9989 \fBecho\fP [\fB\-neE\fP] [\fIarg\fP .\|.\|.]
9990 Output the \fIarg\fPs, separated by spaces, followed by a newline.
9991 The return status is 0 unless a write error occurs.
9992 If \fB\-n\fP is specified, the trailing newline is not printed.
9993 .IP
9994 If the \fB\-e\fP option is given, \fBecho\fP interprets
9995 the following backslash-escaped characters.
9996 The
9997 .B \-E
9998 option disables interpretation of these escape characters,
9999 even on systems where they are interpreted by default.
10000 The \fBxpg_echo\fP shell option determines
10001 whether or not \fBecho\fP interprets any options
10002 and expands these escape characters.
10003 .B echo
10004 does not interpret \fB\-\-\fP to mean the end of options.
10005 .IP
10006 .B echo
10007 interprets the following escape sequences:
10008 .RS
10009 .PD 0
10010 .TP
10011 .B \ea
10012 alert (bell)
10013 .TP
10014 .B \eb
10015 backspace
10016 .TP
10017 .B \ec
10018 suppress further output
10019 .TP
10020 .B \ee
10021 .TP
10022 .B \eE
10023 an escape character
10024 .TP
10025 .B \ef
10026 form feed
10027 .TP
10028 .B \en
10029 new line
10030 .TP
10031 .B \er
10032 carriage return
10033 .TP
10034 .B \et
10035 horizontal tab
10036 .TP
10037 .B \ev
10038 vertical tab
10039 .TP
10040 .B \e\e
10041 backslash
10042 .TP
10043 .B \e0\fInnn\fP
10044 The eight-bit character whose value is the octal value \fInnn\fP
10045 (zero to three octal digits).
10046 .TP
10047 .B \ex\fIHH\fP
10048 The eight-bit character whose value is the hexadecimal value \fIHH\fP
10049 (one or two hex digits).
10050 .TP
10051 .B \eu\fIHHHH\fP
10052 The Unicode (ISO/IEC 10646) character whose value is the hexadecimal value
10053 \fIHHHH\fP (one to four hex digits).
10054 .TP
10055 .B \eU\fIHHHHHHHH\fP
10056 The Unicode (ISO/IEC 10646) character whose value is the hexadecimal value
10057 \fIHHHHHHHH\fP (one to eight hex digits).
10058 .PD
10059 .PP
10060 \fBecho\fP writes any unrecognized backslash-escaped characters unchanged.
10061 .RE
10062 .TP
10063 \fBenable\fP [\fB\-a\fP] [\fB\-dnps\fP] [\fB\-f\fP \fIfilename\fP] \
10064 [\fIname\fP .\|.\|.]
10065 Enable and disable builtin shell commands.
10066 Disabling a builtin allows an executable file which has the same name
10067 as a shell builtin to be executed without specifying a full pathname,
10068 even though the shell normally searches for builtins before files.
10069 .IP
10070 If \fB\-n\fP is supplied, each \fIname\fP is disabled; otherwise,
10071 \fIname\fPs are enabled.
10072 For example, to use the
10073 .B test
10074 binary found using
10075 .SM
10076 .B PATH
10077 instead of the shell builtin version, run
10078 .QN "enable \-n test" .
10079 .IP
10080 If no \fIname\fP arguments are supplied, or if the
10081 .B \-p
10082 option is supplied, print a list of shell builtins.
10083 With no other option arguments, the list consists of all enabled
10084 shell builtins.
10085 If \fB\-n\fP is supplied, print only disabled builtins.
10086 If \fB\-a\fP is supplied, the list printed includes all builtins, with an
10087 indication of whether or not each is enabled.
10088 The \fB\-s\fP option means to restrict the output to the
10089 .SM POSIX
10090 \fIspecial\fP builtins.
10091 .IP
10092 The
10093 .B \-f
10094 option means to load the new builtin command
10095 .I name
10096 from shared object
10097 .IR filename ,
10098 on systems that support dynamic loading.
10099 If \fIfilename\fP does not contain a slash,
10100 \fBBash\fP will use the value of the \fBBASH_LOADABLES_PATH\fP variable as a
10101 colon-separated list of directories in which to search for \fIfilename\fP.
10102 The default for \fBBASH_LOADABLES_PATH\fP is system-dependent,
10103 and may include
10104 .Q .\&
10105 to force a search of the current directory.
10106 The
10107 .B \-d
10108 option will delete a builtin previously loaded with \fB\-f\fP.
10109 If \fI\-s\fP is used with \fI\-f\fP, the new builtin becomes a
10110 .SM POSIX
10111 special builtin.
10112 .IP
10113 If no options are supplied and a \fIname\fP is not a shell builtin,
10114 \fBenable\fP will attempt to load \fIname\fP from a shared
10115 object named \fIname\fP, as if the command were
10116 .QN "enable \-f \fIname name\fP" .
10117 .IP
10118 The return value is 0 unless a
10119 .I name
10120 is not a shell builtin or there is an error loading a new builtin
10121 from a shared object.
10122 .TP
10123 \fBeval\fP [\fIarg\fP .\|.\|.]
10124 Concatenate the \fIarg\fPs together into a single command, separating
10125 them with spaces.
10126 \fBBash\fP then reads and execute this command, and returns its exit status
10127 as the return status of \fBeval\fP.
10128 If there are no
10129 .IR args ,
10130 or only null arguments,
10131 .B eval
10132 returns 0.
10133 .TP
10134 \fBexec\fP [\fB\-cl\fP] [\fB\-a\fP \fIname\fP] [\fIcommand\fP [\fIarguments\fP]]
10135 If
10136 .I command
10137 is specified, it replaces the shell without creating a new process.
10138 \fIcommand\fP cannot be a shell builtin or function.
10139 The
10140 .I arguments
10141 become the arguments to \fIcommand\fP.
10142 If the
10143 .B \-l
10144 option is supplied,
10145 the shell places a dash at the beginning of the zeroth argument passed to
10146 .IR command .
10147 This is what
10148 .IR login (1)
10149 does. The
10150 .B \-c
10151 option causes
10152 .I command
10153 to be executed with an empty environment.
10154 If
10155 .B \-a
10156 is supplied, the shell passes
10157 .I name
10158 as the zeroth argument to the executed command.
10159 .IP
10160 If
10161 .I command
10162 cannot be executed for some reason, a non-interactive shell exits,
10163 unless the
10164 .B execfail
10165 shell option is enabled.
10166 In that case, it returns a non-zero status.
10167 An interactive shell returns a non-zero status if the file cannot be executed.
10168 A subshell exits unconditionally if \fBexec\fP fails.
10169 .IP
10170 If
10171 .I command
10172 is not specified, any redirections take effect in the current shell,
10173 and the return status is 0. If there is a redirection error, the
10174 return status is 1.
10175 .TP
10176 \fBexit\fP [\fIn\fP]
10177 Cause the shell to exit with a status of \fIn\fP.
10178 If
10179 .I n
10180 is omitted, the exit status is that of the last command executed.
10181 Any trap on
10182 .SM
10183 .B EXIT
10184 is executed before the shell terminates.
10185 .TP
10186 \fBexport\fP [\fB\-fn\fP\^] [\fIname\fP[=\fIvalue\fP]] .\|.\|.
10187 .PD 0
10188 .TP
10189 .B export \-p [\fB\-f\fP\^]
10190 .PD
10191 The supplied
10192 .I names
10193 are marked for automatic export to the environment of
10194 subsequently executed commands.
10195 If the
10196 .B \-f
10197 option is given, the
10198 .I names
10199 refer to functions.
10200 .IP
10201 The
10202 .B \-n
10203 option unexports, or removes the export attribute, from each \fIname\fP.
10204 If no
10205 .I names
10206 are given, or if only the
10207 .B \-p
10208 option is supplied,
10209 \fBexport\fP displays a list of names of all exported
10210 variables on the standard output.
10211 Using \fB\-p\fP and \fB\-f\fP together displays exported functions.
10212 The \fB\-p\fP option displays output in a form that may be reused as input.
10213 .IP
10214 \fBexport\fP allows the value of a variable to be set when it is exported
10215 or unexported by following the variable name with =\fIvalue\fP.
10216 This sets the value of the variable to \fIvalue\fP while modifying the
10217 export attribute.
10218 .B export
10219 returns an exit status of 0 unless an invalid option is
10220 encountered,
10221 one of the \fInames\fP is not a valid shell variable name, or
10222 .B \-f
10223 is supplied with a
10224 .I name
10225 that is not a function.
10226 .TP
10227 \fBfalse\fP
10228 Does nothing; returns a non-zero status.
10229 .TP
10230 \fBfc\fP [\fB\-e\fP \fIename\fP] [\fB\-lnr\fP] [\fIfirst\fP] [\fIlast\fP]
10231 .PD 0
10232 .TP
10233 \fBfc\fP \fB\-s\fP [\fIpat\fP=\fIrep\fP] [\fIcmd\fP]
10234 .PD
10235 The first form selects a range of commands from
10236 .I first
10237 to
10238 .I last
10239 from the history list and displays or edits and re-executes them.
10240 .I First
10241 and
10242 .I last
10243 may be specified as a string (to locate the last command beginning
10244 with that string) or as a number (an index into the history list,
10245 where a negative number is used as an offset from the current
10246 command number).
10247 .IP
10248 When listing, a \fIfirst\fP or \fIlast\fP of 0 is equivalent to \-1
10249 and \-0 is equivalent to the current command
10250 (usually the \fBfc\fP command);
10251 otherwise 0 is equivalent to \-1 and \-0 is invalid.
10252 If
10253 .I last
10254 is not specified, it is set to
10255 the current command for listing (so that
10256 .QN "fc \-l \-10"
10257 prints the last 10 commands) and to
10258 .I first
10259 otherwise.
10260 If
10261 .I first
10262 is not specified, it is set to the previous
10263 command for editing and \-16 for listing.
10264 .IP
10265 If the
10266 .B \-l
10267 option is supplied, the commands are listed on the standard output.
10268 The
10269 .B \-n
10270 option suppresses
10271 the command numbers when listing.
10272 The
10273 .B \-r
10274 option reverses the order of
10275 the commands.
10276 .IP
10277 Otherwise, \fBfc\fP invokes the editor named by
10278 .I ename
10279 on a file containing those commands.
10280 If
10281 .I ename
10282 is not supplied, \fBfc\fP uses the value of the
10283 .SM
10284 .B FCEDIT
10285 variable, and
10286 the value of
10287 .SM
10288 .B EDITOR
10289 if
10290 .SM
10291 .B FCEDIT
10292 is not set.
10293 If neither variable is set, \fBfc\fP uses
10294 .FN vi.
10295 When editing is complete, \fBfc\fP reads the file containing
10296 the edited commands and echoes and executes them.
10297 .IP
10298 In the second form, \fBfc\fP re-executes \fIcommand\fP
10299 after replacing each instance of \fIpat\fP with \fIrep\fP.
10300 \fICommand\fP is interpreted the same as \fIfirst\fP above.
10301 .IP
10302 A useful alias to use with \fBfc\fP is
10303 .Q "r=\*"fc \-s\*"" ,
10304 so that typing
10305 .Q "r cc"
10306 runs the last command beginning with
10307 .Q cc
10308 and typing
10309 .Q r
10310 re-executes the last command.
10311 .IP
10312 If the first form is used, the return value is zero unless an invalid
10313 option is encountered or
10314 .I first
10315 or
10316 .I last
10317 specify history lines out of range.
10318 When editing and re-executing a file of commands,
10319 the return value is the value of the last command executed
10320 or failure if an error occurs with the temporary file.
10321 If the second form is used, the return status
10322 is that of the re-executed command, unless
10323 .I cmd
10324 does not specify a valid history entry, in which case
10325 .B fc
10326 returns a non-zero status.
10327 .TP
10328 \fBfg\fP [\fIjobspec\fP]
10329 Resume
10330 .I jobspec
10331 in the foreground, and make it the current job.
10332 If
10333 .I jobspec
10334 is not present, \fBfg\fP uses the shell's notion of the \fIcurrent job\fP.
10335 The return value is that of the command placed into the foreground,
10336 or failure if run when job control is disabled or, when run with
10337 job control enabled, if
10338 .I jobspec
10339 does not specify a valid job or
10340 .I jobspec
10341 specifies a job that was started without job control.
10342 .TP
10343 \fBgetopts\fP \fIoptstring\fP \fIname\fP [\fIarg\fP .\|.\|.]
10344 .B getopts
10345 is used by shell scripts and functions to parse positional parameters
10346 and obtain options and their arguments.
10347 .I optstring
10348 contains the option characters to be recognized; if a character
10349 is followed by a colon, the option is expected to have an
10350 argument, which should be separated from it by white space.
10351 The colon and question mark characters may not be used as
10352 option characters.
10353 .IP
10354 Each time it is invoked,
10355 .B getopts
10356 places the next option in the shell variable
10357 .IR name ,
10358 initializing
10359 .I name
10360 if it does not exist,
10361 and the index of the next argument to be processed into the
10362 variable
10363 .SM
10364 .BR OPTIND .
10365 .SM
10366 .B OPTIND
10367 is initialized to 1 each time the shell or a shell script
10368 is invoked.
10369 When an option requires an argument,
10370 .B getopts
10371 places that argument into the variable
10372 .SM
10373 .BR OPTARG .
10374 .IP
10375 The shell does not reset
10376 .SM
10377 .B OPTIND
10378 automatically; it must be manually reset between multiple
10379 calls to
10380 .B getopts
10381 within the same shell invocation to use a new set of parameters.
10382 .IP
10383 When it reaches the end of options, \fBgetopts\fP exits with a
10384 return value greater than zero.
10385 .SM
10386 .B OPTIND
10387 is set to the index of the first non-option argument,
10388 and \fIname\fP is set to ?.
10389 .IP
10390 .B getopts
10391 normally parses the positional parameters, but if more arguments are
10392 supplied as
10393 .I arg
10394 values,
10395 .B getopts
10396 parses those instead.
10397 .IP
10398 .B getopts
10399 can report errors in two ways.
10400 If the first character of
10401 .I optstring
10402 is a colon, \fBgetopts\fP uses
10403 .I silent
10404 error reporting.
10405 In normal operation, \fBgetopts\fP prints diagnostic messages
10406 when it encounters invalid options or missing option arguments.
10407 If the variable
10408 .SM
10409 .B OPTERR
10410 is set to 0,
10411 .B getopts
10412 does not display any error messages,
10413 even if the first character of
10414 .I optstring
10415 is not a colon.
10416 .IP
10417 If
10418 .B getopts
10419 detects an invalid option, it places ? into
10420 .I name
10421 and, if not silent,
10422 prints an error message and unsets
10423 .SM
10424 .BR OPTARG .
10425 If
10426 .B getopts
10427 is silent, it assigns the option character found to
10428 .SM
10429 .B OPTARG
10430 and does not print a diagnostic message.
10431 .IP
10432 If a required argument is not found, and
10433 .B getopts
10434 is not silent, it sets the value of \fIname\fP to
10435 a question mark (\^\fB?\fP\^), unsets
10436 .SM
10437 .BR OPTARG ,
10438 and prints a diagnostic message.
10439 If
10440 .B getopts
10441 is silent, it sets the value of \fIname\fP to a colon (\^\fB:\fP\^)
10442 and sets
10443 .SM
10444 .B OPTARG
10445 to the option character found.
10446 .IP
10447 .B getopts
10448 returns true if an option, specified or unspecified, is found.
10449 It returns false if the end of options is encountered or an
10450 error occurs.
10451 .TP
10452 \fBhash\fP [\fB\-lr\fP] [\fB\-p\fP \fIfilename\fP] [\fB\-dt\fP] [\fIname\fP]
10453 Each time \fBhash\fP is invoked, it remembers
10454 the full pathname of the command
10455 .I name
10456 as determined by searching
10457 the directories in
10458 .BR $PATH .
10459 Any previously-remembered pathname associated with \fIname\fP is discarded.
10460 If the
10461 .B \-p
10462 option is supplied, \fBhash\fP uses
10463 .I filename
10464 as the full pathname of the command.
10465 .IP
10466 The
10467 .B \-r
10468 option causes the shell to forget all
10469 remembered locations.
10470 Assigning to the \fBPATH\fP variable also clears all hashed filenames.
10471 The
10472 .B \-d
10473 option causes the shell to forget the remembered location of each \fIname\fP.
10474 .IP
10475 If the
10476 .B \-t
10477 option is supplied, \fBhash\fP prints the full pathname corresponding to
10478 each \fIname\fP.
10479 If multiple \fIname\fP arguments are supplied with \fB\-t\fP,
10480 \fBhash\fP prints the \fIname\fP before the corresponding hashed
10481 full pathname.
10482 The
10483 .B \-l
10484 option displays output in a format that may be reused as input.
10485 .IP
10486 If no arguments are given, or if only \fB\-l\fP is supplied,
10487 \fBhash\fP prints information about remembered commands.
10488 The \fB\-t\fP, \fB\-d\fP, and \fB\-p\fP options (the options that
10489 act on the \fIname\fP arguments) are mutually exclusive.
10490 Only one will be active.
10491 If more than one is supplied, \fB\-t\fP has higher priority than
10492 \fB\-p\fP, and both have higher priority than \fB\-d\fP.
10493 .IP
10494 The return status is zero unless a
10495 .I name
10496 is not found or an invalid option is supplied.
10497 .TP
10498 \fBhelp\fP [\fB\-dms\fP] [\fIpattern\fP]
10499 Display helpful information about builtin commands.
10500 If
10501 .I pattern
10502 is specified,
10503 .B help
10504 gives detailed help on all commands matching
10505 .I pattern
10506 as described below;
10507 otherwise it displays a list of
10508 all the builtins and shell compound commands.
10509 .IP
10510 Options, if supplied, have the follow meanings:
10511 .RS
10512 .TP
10513 .PD 0
10514 .B \-d
10515 Display a short description of each \fIpattern\fP
10516 .TP
10517 .B \-m
10518 Display the description of each \fIpattern\fP in a manpage-like format
10519 .TP
10520 .B \-s
10521 Display only a short usage synopsis for each \fIpattern\fP
10522 .PD
10523 .RE
10524 .IP
10525 If \fIpattern\fP contains pattern matching characters
10526 (see
10527 .SM
10528 .B "Pattern Matching"
10529 above)
10530 it's treated as a shell pattern and
10531 \fBhelp\fP prints the description of each
10532 help topic matching \fIpattern\fP.
10533 .IP
10534 If not, and \fIpattern\fP exactly matches the name of a help topic,
10535 \fBhelp\fP prints the description
10536 associated with that topic.
10537 Otherwise, \fBhelp\fP performs prefix matching and
10538 prints the descriptions of all matching help topics.
10539 .IP
10540 The return status is 0 unless no command matches
10541 .IR pattern .
10542 .TP
10543 \fBhistory [\fIn\fP]
10544 .PD 0
10545 .TP
10546 \fBhistory\fP \fB\-c\fP
10547 .TP
10548 \fBhistory \-d\fP \fIoffset\fP
10549 .TP
10550 \fBhistory \-d\fP \fIstart\fP-\fIend\fP
10551 .TP
10552 \fBhistory\fP \fB\-anrw\fP [\fIfilename\fP]
10553 .TP
10554 \fBhistory\fP \fB\-p\fP \fIarg\fP [\fIarg\fP .\|.\|.]
10555 .TP
10556 \fBhistory\fP \fB\-s\fP \fIarg\fP [\fIarg\fP .\|.\|.]
10557 .PD
10558 With no options, display the command history list with numbers.
10559 Entries prefixed with a
10560 .B *
10561 have been modified.
10562 An argument of
10563 .I n
10564 lists only the last
10565 .I n
10566 entries.
10567 If the shell variable
10568 .SM
10569 .B HISTTIMEFORMAT
10570 is set and not null,
10571 it is used as a format string for
10572 .IR strftime (3)
10573 to display the time stamp associated with each displayed history entry.
10574 If
10575 .B history
10576 uses
10577 .SM
10578 .BR HISTTIMEFORMAT ,
10579 it does not print an intervening space between the formatted time stamp
10580 and the history entry.
10581 .IP
10582 If \fIfilename\fP is supplied, \fBhistory\fP uses it as the
10583 name of the history file; if not, it uses the value of
10584 .SM
10585 .BR HISTFILE .
10586 If \fIfilename\fP is not supplied and
10587 .SM
10588 .B HISTFILE
10589 is unset or null, the \fB\-a, \-n, \-r,\fP and \fB\-w\fP options
10590 have no effect.
10591 .IP
10592 Options, if supplied, have the following meanings:
10593 .RS
10594 .PD 0
10595 .TP
10596 .B \-c
10597 Clear the history list by deleting all the entries.
10598 This can be used with the other options to replace the history list.
10599 .TP
10600 \fB\-d\fP \fIoffset\fP
10601 Delete the history entry at position \fIoffset\fP.
10602 If \fIoffset\fP is negative, it is interpreted as relative to one greater
10603 than the last history position, so negative indices count back from the
10604 end of the history, and an index of \-1 refers to the current
10605 \fBhistory \-d\fP command.
10606 .TP
10607 \fB\-d\fP \fIstart\fP\-\fIend\fP
10608 Delete the range of history entries between positions \fIstart\fP and
10609 \fIend\fP, inclusive.
10610 Positive and negative values for \fIstart\fP and \fIend\fP
10611 are interpreted as described above.
10612 .TP
10613 .B \-a
10614 Append the
10615 .Q new
10616 history lines to the history file.
10617 These are history lines entered since the beginning of the current
10618 \fBbash\fP session, but not already appended to the history file.
10619 .TP
10620 .B \-n
10621 Read the history lines not already read from the history file
10622 and add them to the current history list.
10623 These are lines appended to the history file since the beginning of the
10624 current \fBbash\fP session.
10625 .TP
10626 .B \-r
10627 Read the history file and append its contents to the current history list.
10628 .TP
10629 .B \-w
10630 Write the current history list to the history file, overwriting
10631 the history file.
10632 .TP
10633 .B \-p
10634 Perform history substitution on the following \fIargs\fP and display
10635 the result on the standard output,
10636 without storing the results in the history list.
10637 Each \fIarg\fP must be quoted to disable normal history expansion.
10638 .TP
10639 .B \-s
10640 Store the
10641 .I args
10642 in the history list as a single entry.
10643 The last command in the
10644 history list is removed before adding the
10645 .IR args .
10646 .PD
10647 .RE
10648 .IP
10649 If the
10650 .SM
10651 .B HISTTIMEFORMAT
10652 variable is set, \fBhistory\fP writes the time stamp information
10653 associated with each history entry to the history file,
10654 marked with the history comment character as described above.
10655 When the history file is read, lines beginning with the history
10656 comment character followed immediately by a digit are interpreted
10657 as timestamps for the following history entry.
10658 .IP
10659 The return value is 0 unless an invalid option is encountered, an
10660 error occurs while reading or writing the history file, an invalid
10661 \fIoffset\fP or range is supplied as an argument to \fB\-d\fP, or the
10662 history expansion supplied as an argument to \fB\-p\fP fails.
10663 .TP
10664 \fBjobs\fP [\fB\-lnprs\fP] [ \fIjobspec\fP .\|.\|. ]
10665 .PD 0
10666 .TP
10667 \fBjobs\fP \fB\-x\fP \fIcommand\fP [ \fIargs\fP .\|.\|. ]
10668 .PD
10669 The first form lists the active jobs.
10670 The options have the following meanings:
10671 .RS
10672 .PD 0
10673 .TP
10674 .B \-l
10675 List process IDs in addition to the normal information.
10676 .TP
10677 .B \-n
10678 Display information only about jobs that have changed status since
10679 the user was last notified of their status.
10680 .TP
10681 .B \-p
10682 List only the process ID of the job's process group leader.
10683 .TP
10684 .B \-r
10685 Display only running jobs.
10686 .TP
10687 .B \-s
10688 Display only stopped jobs.
10689 .PD
10690 .RE
10691 .IP
10692 If
10693 .I jobspec
10694 is supplied, \fBjobs\fP restricts output to information about that job.
10695 The return status is 0 unless an invalid option is encountered
10696 or an invalid
10697 .I jobspec
10698 is supplied.
10699 .IP
10700 If the
10701 .B \-x
10702 option is supplied,
10703 .B jobs
10704 replaces any
10705 .I jobspec
10706 found in
10707 .I command
10708 or
10709 .I args
10710 with the corresponding process group ID, and executes
10711 .IR command ,
10712 passing it
10713 .IR args ,
10714 returning its exit status.
10715 .TP
10716 \fBkill\fP [\fB\-s\fP \fIsigspec\fP | \fB\-n\fP \fIsignum\fP | \fB\-\fP\fIsigspec\fP] \
10717 \fIid\fP [ .\|.\|. ]
10718 .PD 0
10719 .TP
10720 \fBkill\fP \fB\-l\fP|\fB\-L\fP [\fIsigspec\fP | \fIexit_status\fP]
10721 .PD
10722 Send the signal specified by
10723 .I sigspec
10724 or
10725 .I signum
10726 to the processes named by each
10727 .IR id .
10728 Each
10729 .I id
10730 may be a job specification \fIjobspec\fP
10731 or a process ID \fIpid\fP.
10732 .I sigspec
10733 is either a case-insensitive signal name such as
10734 .SM
10735 .B SIGKILL
10736 (with or without the
10737 .SM
10738 .B SIG
10739 prefix) or a signal number;
10740 .I signum
10741 is a signal number.
10742 If
10743 .I sigspec
10744 is not supplied, then
10745 .B kill
10746 sends
10747 .SM
10748 .BR SIGTERM .
10749 .IP
10750 The
10751 .B \-l
10752 option lists the signal names.
10753 If any arguments are supplied when
10754 .B \-l
10755 is given,
10756 .B kill
10757 lists the names of the signals corresponding to the arguments,
10758 and the return status is 0.
10759 The \fIexit_status\fP argument to
10760 .B \-l
10761 is a number specifying either a signal number or the exit status of
10762 a process terminated by a signal;
10763 if it is supplied, \fBkill\fP prints the name of the signal that caused
10764 the process to terminate.
10765 \fBkill\fP assumes that process exit statuses are greater than 128;
10766 anything less than that is a signal number.
10767 The
10768 .B \-L
10769 option is equivalent to \fB\-l\fP.
10770 .IP
10771 .B kill
10772 returns true if at least one signal was successfully sent, or false
10773 if an error occurs or an invalid option is encountered.
10774 .TP
10775 \fBlet\fP \fIarg\fP [\fIarg\fP .\|.\|.]
10776 Each
10777 .I arg
10778 is evaluated as an arithmetic expression (see
10779 .SM
10780 .B "ARITHMETIC EVALUATION"
10781 .ie \n(zZ=1 in \fIbash\fP(1)).
10782 .el above).
10783 If the last
10784 .I arg
10785 evaluates to 0,
10786 .B let
10787 returns 1; otherwise
10788 .B let
10789 returns 0.
10790 .TP
10791 \fBlocal\fP [\fIoption\fP] [\fIname\fP[=\fIvalue\fP] .\|.\|. | \- ]
10792 For each argument, create a local variable named
10793 .I name
10794 and assign it
10795 .IR value .
10796 The \fIoption\fP can be any of the options accepted by \fBdeclare\fP.
10797 When
10798 .B local
10799 is used within a function, it causes the variable
10800 .I name
10801 to have a visible scope restricted to that function and its children.
10802 It is an error to use
10803 .B local
10804 when not within a function.
10805 .IP
10806 If \fIname\fP is \-, it makes the set of shell options
10807 local to the function in which \fBlocal\fP is invoked:
10808 any shell options changed using the \fBset\fP builtin inside
10809 the function after the call to \fBlocal\fP are restored to their
10810 original values when the function returns.
10811 The restore is performed as if a series of \fBset\fP commands were
10812 executed to restore the values that were in place before the function.
10813 .IP
10814 With no operands,
10815 .B local
10816 writes a list of local variables to the standard output.
10817 .IP
10818 The return status is 0 unless
10819 .B local
10820 is used outside a function, an invalid
10821 .I name
10822 is supplied, or
10823 \fIname\fP is a readonly variable.
10824 .TP
10825 .B logout [\fIn\fP]
10826 Exit a login shell,
10827 returning a status of \fIn\fP to the shell's parent.
10828 .TP
10829 \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]
10830 .PD 0
10831 .TP
10832 \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]
10833 .PD
10834 Read lines from the standard input,
10835 or from file descriptor
10836 .I fd
10837 if the
10838 .B \-u
10839 option is supplied,
10840 into the indexed array variable
10841 .IR array .
10842 The variable
10843 .SM
10844 .B MAPFILE
10845 is the default \fIarray\fP.
10846 Options, if supplied, have the following meanings:
10847 .RS
10848 .PD 0
10849 .TP
10850 .B \-d
10851 Use the first character of \fIdelim\fP to terminate each input line,
10852 rather than newline.
10853 If \fIdelim\fP is the empty string, \fBmapfile\fP will terminate a line
10854 when it reads a NUL character.
10855 .TP
10856 .B \-n
10857 Copy at most
10858 .I count
10859 lines.
10860 If \fIcount\fP is 0, copy all lines.
10861 .TP
10862 .B \-O
10863 Begin assigning to
10864 .I array
10865 at index
10866 .IR origin .
10867 The default index is 0.
10868 .TP
10869 .B \-s
10870 Discard the first \fIcount\fP lines read.
10871 .TP
10872 .B \-t
10873 Remove a trailing \fIdelim\fP (default newline) from each line read.
10874 .TP
10875 .B \-u
10876 Read lines from file descriptor \fIfd\fP instead of the standard input.
10877 .TP
10878 .B \-C
10879 Evaluate
10880 .I callback
10881 each time \fIquantum\fP lines are read.
10882 The \fB\-c\fP option specifies
10883 .IR quantum .
10884 .TP
10885 .B \-c
10886 Specify the number of lines read between each call to
10887 .IR callback .
10888 .PD
10889 .RE
10890 .IP
10891 If
10892 .B \-C
10893 is specified without
10894 .BR \-c ,
10895 the default quantum is 5000.
10896 When \fIcallback\fP is evaluated, it is supplied the index of the next
10897 array element to be assigned and the line to be assigned to that element
10898 as additional arguments.
10899 \fIcallback\fP is evaluated after the line is read but before the
10900 array element is assigned.
10901 .IP
10902 If not supplied with an explicit origin, \fBmapfile\fP will clear \fIarray\fP
10903 before assigning to it.
10904 .IP
10905 \fBmapfile\fP returns zero unless an invalid option or option
10906 argument is supplied, \fIarray\fP is invalid or unassignable, or if
10907 \fIarray\fP is not an indexed array.
10908 .TP
10909 \fBpopd\fP [\-\fBn\fP] [+\fIn\fP] [\-\fIn\fP]
10910 Remove entries from the directory stack.
10911 The elements are numbered from 0 starting at the first directory
10912 listed by \fBdirs\fP, so \fBpopd\fP is equivalent to
10913 .Q "popd +0."
10914 With no arguments, \fBpopd\fP removes the top directory from the stack,
10915 and changes to the new top directory.
10916 Arguments, if supplied, have the following meanings:
10917 .RS
10918 .PD 0
10919 .TP
10920 .B \-n
10921 Suppress the normal change of directory when removing directories
10922 from the stack, only manipulate the stack.
10923 .TP
10924 \fB+\fP\fIn\fP
10925 Remove the \fIn\fPth entry counting from the left of the list
10926 shown by
10927 .BR dirs ,
10928 starting with zero, from the stack.
10929 For example:
10930 .Q "popd +0"
10931 removes the first directory,
10932 .Q "popd +1"
10933 the second.
10934 .TP
10935 \fB\-\fP\fIn\fP
10936 Remove the \fIn\fPth entry counting from the right of the list
10937 shown by
10938 .BR dirs ,
10939 starting with zero. For example:
10940 .Q "popd \-0"
10941 removes the last directory,
10942 .Q "popd \-1"
10943 the next to last.
10944 .PD
10945 .RE
10946 .IP
10947 If the top element of the directory stack is modified, and
10948 the \fI\-n\fP option was not supplied, \fBpopd\fP uses the \fBcd\fP
10949 builtin to change to the directory at the top of the stack.
10950 If the \fBcd\fP fails, \fBpopd\fP returns a non-zero value.
10951 .IP
10952 Otherwise,
10953 .B popd
10954 returns false if an invalid option is supplied, the directory stack
10955 is empty, or \fIn\fP specifies a non-existent directory stack entry.
10956 .IP
10957 If the
10958 .B popd
10959 command is successful,
10960 \fBbash\fP runs
10961 .B dirs
10962 to show the final contents of the directory stack,
10963 and the return status is 0.
10964 .TP
10965 \fBprintf\fP [\fB\-v\fP \fIvar\fP] \fIformat\fP [\fIarguments\fP]
10966 Write the formatted \fIarguments\fP to the standard output under the
10967 control of the \fIformat\fP.
10968 The \fB\-v\fP option assigns the output to the variable
10969 \fIvar\fP rather than printing it to the standard output.
10970 .IP
10971 The \fIformat\fP is a character string which contains three types of objects:
10972 plain characters, which are simply copied to standard output, character
10973 escape sequences, which are converted and copied to the standard output, and
10974 format specifications, each of which causes printing of the next successive
10975 \fIargument\fP.
10976 In addition to the standard
10977 .IR printf (3)
10978 format characters
10979 .BR cCsSndiouxXeEfFgGaA ,
10980 \fBprintf\fP interprets the following additional format specifiers:
10981 .RS
10982 .PD 0
10983 .TP
10984 .B %b
10985 causes
10986 \fBprintf\fP to expand backslash escape sequences in the corresponding
10987 \fIargument\fP
10988 in the same way as \fBecho \-e\fP.
10989 .TP
10990 .B %q
10991 causes \fBprintf\fP to output the corresponding
10992 \fIargument\fP in a format that can be reused as shell input.
10993 \fB%q\fP and \fB%Q\fP use the \fB$\*'\*'\fP quoting style if any characters
10994 in the argument string require it, and backslash quoting otherwise.
10995 If the format string uses the \fIprintf\fP alternate form, these two
10996 formats quote the argument string using single quotes.
10997 .TP
10998 .B %Q
10999 like \fB%q\fP, but applies any supplied precision to the \fIargument\fP
11000 before quoting it.
11001 .TP
11002 .B %(\fIdatefmt\fP)T
11003 causes \fBprintf\fP to output the date-time string resulting from using
11004 \fIdatefmt\fP as a format string for
11005 .IR strftime (3).
11006 The corresponding \fIargument\fP is an integer representing the number of
11007 seconds since the epoch.
11008 This format specifier recognizes two special argument values:
11009 \-1 represents the current time,
11010 and \-2 represents the time the shell was invoked.
11011 If no argument is specified, conversion behaves as if \-1 had been supplied.
11012 This is an exception to the usual \fBprintf\fP behavior.
11013 .PD
11014 .RE
11015 .IP
11016 The %b, %q, and %T format specifiers all use the field width and precision
11017 arguments from the format specification and write that many bytes from
11018 (or use that wide a field for) the expanded argument, which usually
11019 contains more characters than the original.
11020 .IP
11021 The %n format specifier accepts a corresponding argument that is treated
11022 as a shell variable name.
11023 .IP
11024 The %s and %c format specifiers accept an l (long) modifier, which forces
11025 them to convert the argument string to a wide-character string and apply
11026 any supplied field width and precision in terms of characters, not bytes.
11027 The %S and %C format specifiers are equivalent to %ls and %lc, respectively.
11028 .\" .IP
11029 .\" The %s format specifier understands the "altform" flag (#) and behaves
11030 .\" identically to the %b format specifier if it's supplied.
11031 .IP
11032 Arguments to non-string format specifiers are treated as C constants,
11033 except that a leading plus or minus sign is allowed, and if the leading
11034 character is a single or double quote, the value is the numeric value of
11035 the following character, using the current locale.
11036 .IP
11037 The \fIformat\fP is reused as necessary to consume all of the \fIarguments\fP.
11038 If the \fIformat\fP requires more \fIarguments\fP than are supplied, the
11039 extra format specifications behave as if a zero value or null string, as
11040 appropriate, had been supplied.
11041 The return value is zero on success,
11042 non-zero if an invalid option is supplied or a write or assignment error
11043 occurs.
11044 .TP
11045 \fBpushd\fP [\fB\-n\fP] [+\fIn\fP] [\-\fIn\fP]
11046 .PD 0
11047 .TP
11048 \fBpushd\fP [\fB\-n\fP] [\fIdir\fP]
11049 .PD
11050 Add a directory to the top of the directory stack, or rotate
11051 the stack, making the new top of the stack the current working
11052 directory.
11053 With no arguments, \fBpushd\fP exchanges the top two elements of
11054 the directory stack.
11055 Arguments, if supplied, have the following meanings:
11056 .RS
11057 .PD 0
11058 .TP
11059 .B \-n
11060 Suppress the normal change of directory when rotating or
11061 adding directories to the stack, only manipulate the stack.
11062 .TP
11063 \fB+\fP\fIn\fP
11064 Rotate the stack so that the \fIn\fPth directory
11065 (counting from the left of the list shown by
11066 .BR dirs ,
11067 starting with zero)
11068 is at the top.
11069 .TP
11070 \fB\-\fP\fIn\fP
11071 Rotates the stack so that the \fIn\fPth directory
11072 (counting from the right of the list shown by
11073 .BR dirs ,
11074 starting with zero) is at the top.
11075 .TP
11076 .I dir
11077 Adds
11078 .I dir
11079 to the directory stack at the top.
11080 .PD
11081 .RE
11082 .IP
11083 After the stack has been modified, if the \fB\-n\fP option was not
11084 supplied, \fBpushd\fP uses the \fBcd\fP builtin to change to the
11085 directory at the top of the stack.
11086 If the \fBcd\fP fails, \fBpushd\fP returns a non-zero value.
11087 .IP
11088 Otherwise, if no arguments are supplied,
11089 .B pushd
11090 returns zero unless the directory stack is empty.
11091 When rotating the directory stack,
11092 .B pushd
11093 returns zero unless the directory stack is empty or
11094 \fIn\fP specifies a non-existent directory stack element.
11095 .IP
11096 If the
11097 .B pushd
11098 command is successful,
11099 \fBbash\fP runs
11100 .B dirs
11101 to show the final contents of the directory stack.
11102 .TP
11103 \fBpwd\fP [\fB\-LP\fP]
11104 Print the absolute pathname of the current working directory.
11105 The pathname printed contains no symbolic links if the
11106 .B \-P
11107 option is supplied or the
11108 .B \-o physical
11109 option to the
11110 .B set
11111 builtin command is enabled.
11112 If the
11113 .B \-L
11114 option is used, the pathname printed may contain symbolic links.
11115 The return status is 0 unless an error occurs while
11116 reading the name of the current directory or an
11117 invalid option is supplied.
11118 .TP
11119 \fBread\fP [\fB\-Eers\fP] [\fB\-a\fP \fIaname\fP] \
11120 [\fB\-d\fP \fIdelim\fP] [\fB\-i\fP \fItext\fP] \
11121 [\fB\-n\fP \fInchars\fP] [\fB\-N\fP \fInchars\fP] \
11122 [\fB\-p\fP \fIprompt\fP] [\fB\-t\fP \fItimeout\fP] \
11123 [\fB\-u\fP \fIfd\fP] [\fIname\fP .\|.\|.]
11124 Read one line from the standard input, or from the file descriptor
11125 \fIfd\fP supplied as an argument to the \fB\-u\fP option,
11126 split it into words as described
11127 .ie \n(zZ=1 in \fIbash\fP (1)
11128 .el above
11129 under \fBWord Splitting\fP,
11130 and assign the first word to the first
11131 .IR name ,
11132 the second word to the second
11133 .IR name ,
11134 and so on.
11135 If there are more words than names, the remaining words and their
11136 intervening delimiters are assigned to the last
11137 .IR name .
11138 If there are fewer words read from the input stream than names,
11139 the remaining names are assigned empty values.
11140 The characters in the value of the
11141 .SM
11142 .B IFS
11143 variable
11144 are used to split the line into words using the same rules the shell
11145 uses for expansion (described
11146 .ie \n(zZ=1 in \fIbash\fP (1)
11147 .el above
11148 under \fBWord Splitting\fP).
11149 The backslash character (\fB\e\fP) removes any special
11150 meaning for the next character read and is used for line continuation.
11151 .IP
11152 Options, if supplied, have the following meanings:
11153 .RS
11154 .PD 0
11155 .TP
11156 .B \-a \fIaname\fP
11157 The words are assigned to sequential indices of the array variable
11158 .IR aname ,
11159 starting at 0.
11160 .I aname
11161 is unset before any new values are assigned.
11162 Other \fIname\fP arguments are ignored.
11163 .TP
11164 .B \-d \fIdelim\fP
11165 The first character of \fIdelim\fP terminates the input line,
11166 rather than newline.
11167 If \fIdelim\fP is the empty string, \fBread\fP will terminate a line
11168 when it reads a NUL character.
11169 .TP
11170 .B \-e
11171 If the standard input is coming from a terminal,
11172 \fBread\fP uses
11173 .B readline
11174 (see
11175 .SM
11176 .B READLINE
11177 .ie \n(zZ=1 in \fIbash\fP(1))
11178 .el above)
11179 to obtain the line.
11180 \fBReadline\fP uses the current
11181 (or default, if line editing was not previously active)
11182 editing settings, but uses \fBreadline\fP's default filename completion.
11183 .TP
11184 .B \-E
11185 If the standard input is coming from a terminal,
11186 \fBread\fP uses
11187 .B readline
11188 (see
11189 .SM
11190 .B READLINE
11191 .ie \n(zZ=1 in \fIbash\fP(1))
11192 .el above)
11193 to obtain the line.
11194 .B Readline
11195 uses the current (or default, if line editing was not previously
11196 active) editing settings, but uses bash's default completion, including
11197 programmable completion.
11198 .TP
11199 .B \-i \fItext\fP
11200 If
11201 .B readline
11202 is being used to read the line, \fBread\fP places \fItext\fP into
11203 the editing buffer before editing begins.
11204 .TP
11205 .B \-n \fInchars\fP
11206 \fBread\fP returns after reading \fInchars\fP characters rather than
11207 waiting for a complete line of input,
11208 unless it encounters EOF or \fBread\fP times out,
11209 but honors a delimiter if it reads fewer
11210 than \fInchars\fP characters before the delimiter.
11211 .TP
11212 .B \-N \fInchars\fP
11213 \fBread\fP returns after reading exactly \fInchars\fP characters rather
11214 than waiting for a complete line of input,
11215 unless it encounters EOF or \fBread\fP times out.
11216 Any delimiter characters in the input are
11217 not treated specially and do not cause \fBread\fP to return until
11218 it has read \fInchars\fP characters.
11219 The result is not split on the characters in \fBIFS\fP; the intent is
11220 that the variable is assigned exactly the characters read
11221 (with the exception of backslash; see the \fB\-r\fP option below).
11222 .TP
11223 .B \-p \fIprompt\fP
11224 Display \fIprompt\fP on standard error, without a
11225 trailing newline, before attempting to read any input, but
11226 only if input is coming from a terminal.
11227 .TP
11228 .B \-r
11229 Backslash does not act as an escape character.
11230 The backslash is considered to be part of the line.
11231 In particular, a backslash-newline pair may not then be used as a line
11232 continuation.
11233 .TP
11234 .B \-s
11235 Silent mode.
11236 If input is coming from a terminal, characters are not echoed.
11237 .TP
11238 .B \-t \fItimeout\fP
11239 Cause \fBread\fP to time out and return failure if it does not read
11240 a complete line of input (or a specified number of characters)
11241 within \fItimeout\fP seconds.
11242 \fItimeout\fP may be a decimal number with a fractional portion following
11243 the decimal point.
11244 This option is only effective if \fBread\fP is reading input from a
11245 terminal, pipe, or other special file; it has no effect when reading
11246 from regular files.
11247 If \fBread\fP times out, it saves any partial input read into
11248 the specified variable \fIname\fP, and the exit status is greater than 128.
11249 If \fItimeout\fP is 0, \fBread\fP returns immediately, without trying to
11250 read any data.
11251 In this case, the exit status is 0 if input is available on the specified
11252 file descriptor, or the read will return EOF, non-zero otherwise.
11253 .TP
11254 .B \-u \fIfd\fP
11255 Read input from file descriptor \fIfd\fP instead of the standard input.
11256 .PD
11257 .RE
11258 .IP
11259 Other than the case where \fIdelim\fP is the empty string, \fBread\fP
11260 ignores any NUL characters in the input.
11261 .IP
11262 If no
11263 .I names
11264 are supplied, \fBread\fP assigns the line read,
11265 without the ending delimiter but otherwise unmodified,
11266 to the variable
11267 .SM
11268 .BR REPLY .
11269 .IP
11270 The exit status is zero, unless end-of-file is encountered, \fBread\fP
11271 times out (in which case the status is greater than 128),
11272 a variable assignment error (such as assigning to a readonly variable) occurs,
11273 or an invalid file descriptor is supplied as the argument to \fB\-u\fP.
11274 .TP
11275 \fBreadonly\fP [\fB\-aAf\fP] [\fB\-p\fP] [\fIname\fP[=\fIword\fP] .\|.\|.]
11276 .PD
11277 The given
11278 \fInames\fP are marked readonly; the values of these
11279 .I names
11280 may not be changed by subsequent assignment or unset.
11281 If the
11282 .B \-f
11283 option is supplied, each \fIname\fP refers to a shell function.
11284 The
11285 .B \-a
11286 option restricts the variables to indexed arrays; the
11287 .B \-A
11288 option restricts the variables to associative arrays.
11289 If both options are supplied,
11290 .B \-A
11291 takes precedence.
11292 If no
11293 .I name
11294 arguments are supplied, or if the
11295 .B \-p
11296 option is supplied, print a list of all readonly names.
11297 The other options may be used to restrict the output to a subset of
11298 the set of readonly names.
11299 The
11300 .B \-p
11301 option displays output in a format that may be reused as input.
11302 .IP
11303 \fBreadonly\fP allows the value of a variable to be set at the same time
11304 the readonly attribute is changed by following the variable name with
11305 =\fIvalue\fP.
11306 This sets the value of the variable is to \fIvalue\fP while modifying
11307 the readonly attribute.
11308 .IP
11309 The return status is 0 unless an invalid option is encountered,
11310 one of the
11311 .I names
11312 is not a valid shell variable name, or
11313 .B \-f
11314 is supplied with a
11315 .I name
11316 that is not a function.
11317 .TP
11318 \fBreturn\fP [\fIn\fP]
11319 Stop executing a shell function or sourced file and return the value
11320 specified by
11321 .I n
11322 to its caller.
11323 If
11324 .I n
11325 is omitted, the return status is that of the last command
11326 executed.
11327 If \fBreturn\fP is executed by a trap handler, the last command used to
11328 determine the status is the last command executed before the trap handler.
11329 If \fBreturn\fP is executed during a \fBDEBUG\fP trap, the last command
11330 used to determine the status is the last command executed by the trap
11331 handler before \fBreturn\fP was invoked.
11332 .IP
11333 When
11334 .B return
11335 is used to terminate execution of a script being executed by the
11336 .B .
11337 (\fBsource\fP) command, it causes the shell to stop executing
11338 that script and return either
11339 .I n
11340 or the exit status of the last command executed within the
11341 script as the exit status of the script.
11342 If \fIn\fP is supplied, the return value is its least significant
11343 8 bits.
11344 .IP
11345 Any command associated with the \fBRETURN\fP trap is executed
11346 before execution resumes after the function or script.
11347 .IP
11348 The return status is non-zero if
11349 .B return
11350 is supplied a non-numeric argument, or is used outside a
11351 function and not during execution of a script by \fB.\fP\^ or \fBsource\fP.
11352 .TP
11353 \fBset\fP [\fB\-abefhkmnptuvxBCEHPT\fP] [\fB\-o\fP \fIoption\-name\fP] \
11354 [\fB\-\-\fP] [\fB\-\fP] [\fIarg\fP .\|.\|.]
11355 .PD 0
11356 .TP
11357 \fBset\fP [\fB+abefhkmnptuvxBCEHPT\fP] [\fB+o\fP \fIoption\-name\fP] \
11358 [\fB\-\-\fP] [\fB\-\fP] [\fIarg\fP .\|.\|.]
11359 .TP
11360 \fBset \-o\fP
11361 .TP
11362 \fBset +o\fP
11363 .PD
11364 Without options, display the name and value of each shell variable
11365 in a format that can be reused as input
11366 for setting or resetting the currently-set variables.
11367 Read-only variables cannot be reset.
11368 In posix mode, only shell variables are listed.
11369 The output is sorted according to the current locale.
11370 When options are specified, they set or unset shell attributes.
11371 Any arguments remaining after option processing are treated
11372 as values for the positional parameters and are assigned, in order, to
11373 .BR $1 ,
11374 .BR $2 ,
11375 \&.\|.\|.,
11376 .BR $\fIn\fP .
11377 Options, if specified, have the following meanings:
11378 .RS
11379 .PD 0
11380 .TP 8
11381 .B \-a
11382 Each variable or function that is created or modified is given the
11383 export attribute and marked for export to the environment of
11384 subsequent commands.
11385 .TP 8
11386 .B \-b
11387 Report the status of terminated background jobs
11388 immediately, rather than before the next primary prompt or after a
11389 foreground command terminates.
11390 This is effective only when job control is enabled.
11391 .TP 8
11392 .B \-e
11393 .PD
11394 Exit immediately if a
11395 \fIpipeline\fP (which may consist of a single \fIsimple command\fP),
11396 a \fIlist\fP,
11397 or a \fIcompound command\fP
11398 (see
11399 .SM
11400 .B "SHELL GRAMMAR"
11401 .ie \n(zZ=1 in \fIbash\fP(1)),
11402 .el above),
11403 exits with a non-zero status.
11404 The shell does not exit if the
11405 command that fails is part of the command list immediately following a
11406 .B while
11407 or
11408 .B until
11409 reserved word,
11410 part of the test following the
11411 .B if
11412 or
11413 .B elif
11414 reserved words, part of any command executed in a
11415 .B &&
11416 or
11417 .B ||
11418 list except the command following the final \fB&&\fP or \fB||\fP,
11419 any command in a pipeline but the last
11420 (subject to the state of the \fBpipefail\fP shell option),
11421 or if the command's return value is
11422 being inverted with
11423 .BR ! .
11424 If a compound command other than a subshell
11425 returns a non-zero status because a command failed
11426 while \fB\-e\fP was being ignored, the shell does not exit.
11427 A trap on \fBERR\fP, if set, is executed before the shell exits.
11428 This option applies to the shell environment and each subshell environment
11429 separately (see
11430 .SM
11431 .B "COMMAND EXECUTION ENVIRONMENT"
11432 .ie \n(zZ=1 in \fIbash\fP(1)),
11433 .el above),
11434 and may cause
11435 subshells to exit before executing all the commands in the subshell.
11436 .IP
11437 If a compound command or shell function executes in a context
11438 where \fB\-e\fP is being ignored,
11439 none of the commands executed within the compound command or function body
11440 will be affected by the \fB\-e\fP setting, even if \fB\-e\fP is set
11441 and a command returns a failure status.
11442 If a compound command or shell function sets \fB\-e\fP while executing in
11443 a context where \fB\-e\fP is ignored, that setting will not have any
11444 effect until the compound command or the command containing the function
11445 call completes.
11446 .PD 0
11447 .TP 8
11448 .B \-f
11449 Disable pathname expansion.
11450 .TP 8
11451 .B \-h
11452 Remember the location of commands as they are looked up for execution.
11453 This is enabled by default.
11454 .TP 8
11455 .B \-k
11456 All arguments in the form of assignment statements
11457 are placed in the environment for a command, not just
11458 those that precede the command name.
11459 .TP 8
11460 .B \-m
11461 Monitor mode.
11462 Job control is enabled.
11463 This option is on by default for interactive shells on systems
11464 that support it (see
11465 .SM
11466 .B "JOB CONTROL"
11467 .ie \n(zZ=1 in \fIbash\fP(1)).
11468 .el above).
11469 All processes run in a separate process group.
11470 When a background job completes, the shell prints a line
11471 containing its exit status.
11472 .TP 8
11473 .B \-n
11474 Read commands but do not execute them.
11475 This may be used to check a shell script for syntax errors.
11476 This is ignored by interactive shells.
11477 .TP 8
11478 .B \-o \fIoption\-name\fP
11479 The \fIoption\-name\fP can be one of the following:
11480 .RS
11481 .TP 8
11482 .B allexport
11483 Same as
11484 .BR \-a .
11485 .TP 8
11486 .B braceexpand
11487 Same as
11488 .BR \-B .
11489 .TP 8
11490 .B emacs
11491 Use an emacs-style command line editing interface. This is enabled
11492 by default when the shell is interactive, unless the shell is started
11493 with the
11494 .B \-\-noediting
11495 option.
11496 This also affects the editing interface used for \fBread \-e\fP.
11497 .TP 8
11498 .B errexit
11499 Same as
11500 .BR \-e .
11501 .TP 8
11502 .B errtrace
11503 Same as
11504 .BR \-E .
11505 .TP 8
11506 .B functrace
11507 Same as
11508 .BR \-T .
11509 .TP 8
11510 .B hashall
11511 Same as
11512 .BR \-h .
11513 .TP 8
11514 .B histexpand
11515 Same as
11516 .BR \-H .
11517 .TP 8
11518 .B history
11519 Enable command history, as described
11520 .ie \n(zZ=1 in \fIbash\fP(1)
11521 .el above
11522 under
11523 .SM
11524 .BR HISTORY .
11525 This option is on by default in interactive shells.
11526 .TP 8
11527 .B ignoreeof
11528 The effect is as if the shell command
11529 .QN "IGNOREEOF=10"
11530 had been executed
11531 (see
11532 .B "Shell Variables"
11533 .ie \n(zZ=1 in \fIbash\fP(1)).
11534 .el above).
11535 .TP 8
11536 .B keyword
11537 Same as
11538 .BR \-k .
11539 .TP 8
11540 .B monitor
11541 Same as
11542 .BR \-m .
11543 .TP 8
11544 .B noclobber
11545 Same as
11546 .BR \-C .
11547 .TP 8
11548 .B noexec
11549 Same as
11550 .BR \-n .
11551 .TP 8
11552 .B noglob
11553 Same as
11554 .BR \-f .
11555 .TP 8
11556 .B nolog
11557 Currently ignored.
11558 .TP 8
11559 .B notify
11560 Same as
11561 .BR \-b .
11562 .TP 8
11563 .B nounset
11564 Same as
11565 .BR \-u .
11566 .TP 8
11567 .B onecmd
11568 Same as
11569 .BR \-t .
11570 .TP 8
11571 .B physical
11572 Same as
11573 .BR \-P .
11574 .TP 8
11575 .B pipefail
11576 If set, the return value of a pipeline is the value of the last
11577 (rightmost) command to exit with a non-zero status, or zero if all
11578 commands in the pipeline exit successfully.
11579 This option is disabled by default.
11580 .TP 8
11581 .B posix
11582 Enable posix mode;
11583 change the behavior of
11584 .B bash
11585 where the default operation differs
11586 from the
11587 .SM POSIX
11588 standard to match the standard.
11589 See
11590 .SM
11591 .B "SEE ALSO"
11592 .ie \n(zZ=1 in \fIbash\fP(1)
11593 .el below
11594 for a reference to a document that details how posix mode affects
11595 bash's behavior.
11596 .TP 8
11597 .B privileged
11598 Same as
11599 .BR \-p .
11600 .TP 8
11601 .B verbose
11602 Same as
11603 .BR \-v .
11604 .TP 8
11605 .B vi
11606 Use a vi-style command line editing interface.
11607 This also affects the editing interface used for \fBread \-e\fP.
11608 .TP 8
11609 .B xtrace
11610 Same as
11611 .BR \-x .
11612 .PP
11613 If
11614 .B \-o
11615 is supplied with no \fIoption\-name\fP,
11616 \fBset\fP prints the current shell option settings.
11617 If
11618 .B +o
11619 is supplied with no \fIoption\-name\fP,
11620 \fBset\fP prints a series of
11621 .B set
11622 commands to recreate the current option settings
11623 on the standard output.
11624 .RE
11625 .TP 8
11626 .B \-p
11627 Turn on
11628 .I privileged
11629 mode. In this mode, the shell does not read the
11630 .SM
11631 .B $ENV
11632 and
11633 .SM
11634 .B $BASH_ENV
11635 files, shell functions are not inherited from the
11636 environment, and the
11637 .SM
11638 .BR SHELLOPTS ,
11639 .SM
11640 .BR BASHOPTS ,
11641 .SM
11642 .BR CDPATH ,
11643 and
11644 .SM
11645 .B GLOBIGNORE
11646 variables, if they appear in the environment, are ignored.
11647 If the shell is started with the effective user (group) id not equal to the
11648 real user (group) id, and the \fB\-p\fP option is not supplied, these actions
11649 are taken and the effective user id is set to the real user id.
11650 If the \fB\-p\fP option is supplied at startup, the effective user id is
11651 not reset.
11652 Turning this option off causes the effective user
11653 and group ids to be set to the real user and group ids.
11654 .TP 8
11655 .B \-r
11656 Enable restricted shell mode.
11657 This option cannot be unset once it has been set.
11658 .TP 8
11659 .B \-t
11660 Exit after reading and executing one command.
11661 .TP 8
11662 .B \-u
11663 Treat unset variables and parameters other than the special
11664 parameters
11665 .Q @
11666 and
11667 .Q * ,
11668 or array variables subscripted with
11669 .Q @
11670 or
11671 .Q * ,
11672 as an error when performing parameter expansion.
11673 If expansion is attempted on an unset variable or parameter,
11674 the shell prints an error message, and,
11675 if not interactive, exits with a non-zero status.
11676 .TP 8
11677 .B \-v
11678 Print shell input lines as they are read.
11679 .TP 8
11680 .B \-x
11681 After expanding each \fIsimple command\fP,
11682 \fBfor\fP command, \fBcase\fP command, \fBselect\fP command, or
11683 arithmetic \fBfor\fP command, display the expanded value of
11684 .SM
11685 .BR PS4 ,
11686 followed by the command and its expanded arguments
11687 or associated word list, to the standard error.
11688 .TP 8
11689 .B \-B
11690 The shell performs brace expansion (see
11691 .B "Brace Expansion"
11692 .ie \n(zZ=1 in \fIbash\fP(1)).
11693 .el above).
11694 This is on by default.
11695 .TP 8
11696 .B \-C
11697 If set,
11698 .B bash
11699 does not overwrite an existing file with the
11700 .BR > ,
11701 .BR >& ,
11702 and
11703 .B <>
11704 redirection operators.
11705 Using the redirection operator
11706 .B >|
11707 instead of
11708 .B >
11709 will override this and force the creation of an output file.
11710 .TP 8
11711 .B \-E
11712 If set, any trap on \fBERR\fP is inherited by shell functions, command
11713 substitutions, and commands executed in a subshell environment.
11714 The \fBERR\fP trap is normally not inherited in such cases.
11715 .TP 8
11716 .B \-H
11717 Enable
11718 .B !
11719 style history substitution.
11720 This option is on by default when the shell is interactive.
11721 .TP 8
11722 .B \-P
11723 If set, the shell does not resolve symbolic links when executing
11724 commands such as
11725 .B cd
11726 that change the current working directory.
11727 It uses the physical directory structure instead.
11728 By default,
11729 .B bash
11730 follows the logical chain of directories when performing commands
11731 which change the current directory.
11732 .TP 8
11733 .B \-T
11734 If set, any traps on \fBDEBUG\fP and \fBRETURN\fP are inherited by shell
11735 functions, command substitutions, and commands executed in a
11736 subshell environment.
11737 The \fBDEBUG\fP and \fBRETURN\fP traps are normally not inherited
11738 in such cases.
11739 .TP 8
11740 .B \-\-
11741 If no arguments follow this option, unset the positional parameters.
11742 Otherwise, set the positional parameters to the
11743 \fIarg\fPs, even if some of them begin with a
11744 .BR \- .
11745 .TP 8
11746 .B \-
11747 Signal the end of options, and assign all remaining \fIarg\fPs to
11748 the positional parameters.
11749 The
11750 .B \-x
11751 and
11752 .B \-v
11753 options are turned off.
11754 If there are no \fIarg\fPs, the positional parameters remain unchanged.
11755 .PD
11756 .PP
11757 The options are off by default unless otherwise noted.
11758 Using + rather than \- causes these options to be turned off.
11759 The options can also be specified as arguments to an invocation of
11760 the shell.
11761 The current set of options may be found in
11762 .BR $\- .
11763 The return status is always zero unless an invalid option is encountered.
11764 .RE
11765 .TP
11766 \fBshift\fP [\fIn\fP]
11767 Rename positional parameters from \fIn\fP+1 .\|.\|.\& to
11768 .B $1
11769 .B .\|.\|..
11770 Parameters represented by the numbers \fB$#\fP
11771 down to \fB$#\fP\-\fIn\fP+1 are unset.
11772 .I n
11773 must be a non-negative number less than or equal to \fB$#\fP.
11774 If
11775 .I n
11776 is 0, no parameters are changed.
11777 If
11778 .I n
11779 is not given, it is assumed to be 1.
11780 If
11781 .I n
11782 is greater than \fB$#\fP, the positional parameters are not changed.
11783 The return status is greater than zero if
11784 .I n
11785 is greater than
11786 .B $#
11787 or less than zero; otherwise 0.
11788 .TP
11789 \fBshopt\fP [\fB\-pqsu\fP] [\fB\-o\fP] [\fIoptname\fP .\|.\|.]
11790 Toggle the values of settings controlling optional shell behavior.
11791 The settings can be either those listed below, or, if the
11792 .B \-o
11793 option is used, those available with the
11794 .B \-o
11795 option to the \fBset\fP builtin command.
11796 .IP
11797 With no options, or with the
11798 .B \-p
11799 option, display a list of all settable options, with
11800 an indication of whether or not each is set;
11801 if any \fIoptnames\fP are supplied, the output is restricted to those options.
11802 The \fB\-p\fP option displays output in a form that
11803 may be reused as input.
11804 .IP
11805 Other options have the following meanings:
11806 .RS
11807 .PD 0
11808 .TP
11809 .B \-s
11810 Enable (set) each \fIoptname\fP.
11811 .TP
11812 .B \-u
11813 Disable (unset) each \fIoptname\fP.
11814 .TP
11815 .B \-q
11816 Suppresses normal output (quiet mode); the return status indicates
11817 whether the \fIoptname\fP is set or unset.
11818 If multiple \fIoptname\fP arguments are supplied with
11819 .BR \-q ,
11820 the return status is zero if all \fIoptnames\fP are enabled; non-zero
11821 otherwise.
11822 .TP
11823 .B \-o
11824 Restricts the values of \fIoptname\fP to be those defined for the
11825 .B \-o
11826 option to the
11827 .B set
11828 builtin.
11829 .PD
11830 .PP
11831 If either
11832 .B \-s
11833 or
11834 .B \-u
11835 is used with no \fIoptname\fP arguments,
11836 .B shopt
11837 shows only those options which are set or unset, respectively.
11838 Unless otherwise noted, the \fBshopt\fP options are disabled (unset)
11839 by default.
11840 .PP
11841 The return status when listing options is zero if all \fIoptnames\fP
11842 are enabled, non-zero otherwise. When setting or unsetting options,
11843 the return status is zero unless an \fIoptname\fP is not a valid shell
11844 option.
11845 .PP
11846 The list of \fBshopt\fP options is:
11847 .PP
11848 .PD 0
11849 .TP 8
11850 .B array_expand_once
11851 If set, the shell suppresses multiple evaluation of
11852 associative and indexed array subscripts
11853 during arithmetic expression evaluation, while executing
11854 builtins that can perform variable assignments,
11855 and while executing builtins that perform array dereferencing.
11856 .TP 8
11857 .B assoc_expand_once
11858 Deprecated; a synonym for \fBarray_expand_once\fP.
11859 .TP 8
11860 .B autocd
11861 If set, a command name that is the name of a directory is executed as if
11862 it were the argument to the \fBcd\fP command.
11863 This option is only used by interactive shells.
11864 .TP 8
11865 .B bash_source_fullpath
11866 If set, filenames added to the \fBBASH_SOURCE\fP array variable are
11867 converted to full pathnames (see \fBShell Variables\fP above).
11868 .TP 8
11869 .B cdable_vars
11870 If set, an argument to the
11871 .B cd
11872 builtin command that
11873 is not a directory is assumed to be the name of a variable whose
11874 value is the directory to change to.
11875 .TP 8
11876 .B cdspell
11877 If set, the
11878 .B cd
11879 command attempts to correct
11880 minor errors in the spelling of a directory component.
11881 Minor errors include transposed characters,
11882 a missing character, and one extra character.
11883 If \fBcd\fP corrects the directory name, it prints the corrected filename,
11884 and the command proceeds.
11885 This option is only used by interactive shells.
11886 .TP 8
11887 .B checkhash
11888 If set, \fBbash\fP checks that a command found in the hash
11889 table exists before trying to execute it.
11890 If a hashed command no longer exists, \fBbash\fP performs a normal path search.
11891 .TP 8
11892 .B checkjobs
11893 If set, \fBbash\fP lists the status of any stopped and running jobs before
11894 exiting an interactive shell.
11895 If any jobs are running, \fBbash\fP defers the exit until a second
11896 exit is attempted without an intervening command (see
11897 .SM
11898 .B "JOB CONTROL"
11899 .ie \n(zZ=1 in \fIbash\fP(1)).
11900 .el above).
11901 The shell always postpones exiting if any jobs are stopped.
11902 .TP 8
11903 .B checkwinsize
11904 If set, \fBbash\fP checks the window size after each external (non-builtin)
11905 command
11906 and, if necessary, updates the values of
11907 .SM
11908 .B LINES
11909 and
11910 .SM
11911 .BR COLUMNS ,
11912 using the file descriptor associated with the standard error
11913 if it is a terminal.
11914 This option is enabled by default.
11915 .TP 8
11916 .B cmdhist
11917 If set,
11918 .B bash
11919 attempts to save all lines of a multiple-line
11920 command in the same history entry.
11921 This allows easy re-editing of multi-line commands.
11922 This option is enabled by default, but only has an effect if command
11923 history is enabled, as described
11924 .ie \n(zZ=1 in \fIbash\fP(1)
11925 .el above
11926 under
11927 .SM
11928 .BR HISTORY .
11929 .PD 0
11930 .TP 8
11931 .B compat31
11932 .TP 8
11933 .B compat32
11934 .TP 8
11935 .B compat40
11936 .TP 8
11937 .B compat41
11938 .TP 8
11939 .B compat42
11940 .TP 8
11941 .B compat43
11942 .TP 8
11943 .B compat44
11944 .PD
11945 These control aspects of the shell's compatibility mode
11946 (see
11947 .SM
11948 .B "SHELL COMPATIBILITY MODE"
11949 .ie \n(zZ=1 in \fIbash\fP(1)).
11950 .el below).
11951 .PD 0
11952 .TP 8
11953 .B complete_fullquote
11954 If set,
11955 .B bash
11956 quotes all shell metacharacters in filenames and directory names when
11957 performing completion.
11958 If not set,
11959 .B bash
11960 removes metacharacters such as the dollar sign from the set of
11961 characters that will be quoted in completed filenames
11962 when these metacharacters appear in shell variable references in words to be
11963 completed.
11964 This means that dollar signs in variable names that expand to directories
11965 will not be quoted;
11966 however, any dollar signs appearing in filenames will not be quoted, either.
11967 This is active only when bash is using backslashes to quote completed
11968 filenames.
11969 This variable is set by default, which is the default bash behavior in
11970 versions through 4.2.
11971 .TP 8
11972 .B direxpand
11973 If set,
11974 .B bash
11975 replaces directory names with the results of word expansion when performing
11976 filename completion.
11977 This changes the contents of the \fBreadline\fP editing buffer.
11978 If not set,
11979 .B bash
11980 attempts to preserve what the user typed.
11981 .TP 8
11982 .B dirspell
11983 If set,
11984 .B bash
11985 attempts spelling correction on directory names during word completion
11986 if the directory name initially supplied does not exist.
11987 .TP 8
11988 .B dotglob
11989 If set,
11990 .B bash
11991 includes filenames beginning with a
11992 .Q .\&
11993 in the results of pathname expansion.
11994 The filenames
11995 .FN .\&
11996 and
11997 .FN ..\&
11998 must always be matched explicitly, even if
11999 .B dotglob
12000 is set.
12001 .TP 8
12002 .B execfail
12003 If set, a non-interactive shell will not exit if
12004 it cannot execute the file specified as an argument to the
12005 .B exec
12006 builtin.
12007 An interactive shell does not exit if
12008 .B exec
12009 fails.
12010 .TP 8
12011 .B expand_aliases
12012 If set, aliases are expanded as described
12013 .ie \n(zZ=1 in \fIbash\fP(1)
12014 .el above
12015 under
12016 .SM
12017 .BR ALIASES .
12018 This option is enabled by default for interactive shells.
12019 .TP 8
12020 .B extdebug
12021 If set at shell invocation, or in a shell startup file,
12022 arrange to execute the debugger profile
12023 before the shell starts, identical to the \fB\-\-debugger\fP option.
12024 If set after invocation, behavior intended for use by debuggers is enabled:
12025 .RS
12026 .TP
12027 .B 1.
12028 The \fB\-F\fP option to the \fBdeclare\fP builtin displays the source
12029 file name and line number corresponding to each function name supplied
12030 as an argument.
12031 .TP
12032 .B 2.
12033 If the command run by the \fBDEBUG\fP trap returns a non-zero value, the
12034 next command is skipped and not executed.
12035 .TP
12036 .B 3.
12037 If the command run by the \fBDEBUG\fP trap returns a value of 2, and the
12038 shell is executing in a subroutine (a shell function or a shell script
12039 executed by the \fB.\fP or \fBsource\fP builtins), the shell simulates
12040 a call to \fBreturn\fP.
12041 .TP
12042 .B 4.
12043 .SM
12044 .B BASH_ARGC
12045 and
12046 .SM
12047 .B BASH_ARGV
12048 are updated as described in their descriptions
12049 .ie \n(zZ=1 in \fIbash\fP(1)).
12050 .el above).
12051 .TP
12052 .B 5.
12053 Function tracing is enabled: command substitution, shell functions, and
12054 subshells invoked with \fB(\fP \fIcommand\fP \fB)\fP inherit the
12055 \fBDEBUG\fP and \fBRETURN\fP traps.
12056 .TP
12057 .B 6.
12058 Error tracing is enabled: command substitution, shell functions, and
12059 subshells invoked with \fB(\fP \fIcommand\fP \fB)\fP inherit the
12060 \fBERR\fP trap.
12061 .RE
12062 .TP 8
12063 .B extglob
12064 If set, enable the extended pattern matching features described
12065 .ie \n(zZ=1 in \fIbash\fP(1)
12066 .el above
12067 under
12068 \fBPathname Expansion\fP.
12069 .TP 8
12070 .B extquote
12071 If set, \fB$\fP\*'\fIstring\fP\*' and \fB$\fP\*"\fIstring\fP\*" quoting is
12072 performed within \fB${\fP\fIparameter\fP\fB}\fP expansions
12073 enclosed in double quotes.
12074 This option is enabled by default.
12075 .TP 8
12076 .B failglob
12077 If set, patterns which fail to match filenames during pathname expansion
12078 result in an expansion error.
12079 .TP 8
12080 .B force_fignore
12081 If set, the suffixes specified by the
12082 .SM
12083 .B FIGNORE
12084 shell variable
12085 cause words to be ignored when performing word completion even if
12086 the ignored words are the only possible completions.
12087 See
12088 .B "Shell Variables"
12089 .ie \n(zZ=1 in \fIbash\fP(1)
12090 .el above
12091 for a description of
12092 .SM
12093 .BR FIGNORE .
12094 This option is enabled by default.
12095 .TP 8
12096 .B globasciiranges
12097 If set, range expressions used in pattern matching bracket expressions (see
12098 .SM
12099 .B "Pattern Matching"
12100 .ie \n(zZ=1 in \fIbash\fP(1))
12101 .el above)
12102 behave as if in the traditional C locale when performing comparisons.
12103 That is, pattern matching does not take
12104 the current locale's collating sequence into account, so
12105 .B b
12106 will not collate between
12107 .B A
12108 and
12109 .BR B ,
12110 and upper-case and lower-case ASCII characters will collate together.
12111 .TP 8
12112 .B globskipdots
12113 If set, pathname expansion will never match the filenames
12114 .FN .\&
12115 and
12116 .FN ..\& ,
12117 even if the pattern begins with a
12118 .Q .\& .
12119 This option is enabled by default.
12120 .TP 8
12121 .B globstar
12122 If set, the pattern \fB**\fP used in a pathname expansion context will
12123 match all files and zero or more directories and subdirectories.
12124 If the pattern is followed by a \fB/\fP, only directories and
12125 subdirectories match.
12126 .TP 8
12127 .B gnu_errfmt
12128 If set, shell error messages are written in the standard GNU error
12129 message format.
12130 .TP 8
12131 .B histappend
12132 If set, the history list is appended to the file named by the value
12133 of the
12134 .SM
12135 .B HISTFILE
12136 variable when the shell exits, rather than overwriting the file.
12137 .TP 8
12138 .B histreedit
12139 If set, and
12140 .B readline
12141 is being used, the user is given the opportunity to re-edit a
12142 failed history substitution.
12143 .TP 8
12144 .B histverify
12145 If set, and
12146 .B readline
12147 is being used, the results of history substitution are not immediately
12148 passed to the shell parser.
12149 Instead, the resulting line is loaded into the \fBreadline\fP editing buffer,
12150 allowing further modification.
12151 .TP 8
12152 .B hostcomplete
12153 If set, and
12154 .B readline
12155 is being used, \fBbash\fP will attempt to perform hostname completion when a
12156 word containing a \fB@\fP is being completed (see
12157 .B Completing
12158 under
12159 .SM
12160 .B READLINE
12161 .ie \n(zZ=1 in \fIbash\fP(1)).
12162 .el above).
12163 This is enabled by default.
12164 .TP 8
12165 .B huponexit
12166 If set, \fBbash\fP will send
12167 .SM
12168 .B SIGHUP
12169 to all jobs when an interactive login shell exits.
12170 .TP 8
12171 .B inherit_errexit
12172 If set, command substitution inherits the value of the \fBerrexit\fP option,
12173 instead of unsetting it in the subshell environment.
12174 This option is enabled when posix mode is enabled.
12175 .TP 8
12176 .B interactive_comments
12177 In an interactive shell, a word beginning with \fB#\fP
12178 causes that word and all remaining characters on that
12179 line to be ignored, as in a non-interactive shell
12180 (see
12181 .SM
12182 .B COMMENTS
12183 .ie \n(zZ=1 in \fIbash\fP(1)).
12184 .el above).
12185 This option is enabled by default.
12186 .TP 8
12187 .B lastpipe
12188 If set, and job control is not active, the shell runs the last command of
12189 a pipeline not executed in the background in the current shell environment.
12190 .TP 8
12191 .B lithist
12192 If set, and the
12193 .B cmdhist
12194 option is enabled, multi-line commands are saved to the history with
12195 embedded newlines rather than using semicolon separators where possible.
12196 .TP 8
12197 .B localvar_inherit
12198 If set, local variables inherit the value and attributes of a variable of
12199 the same name that exists at a previous scope before any new value is
12200 assigned.
12201 The nameref attribute is not inherited.
12202 .TP 8
12203 .B localvar_unset
12204 If set, calling \fBunset\fP on local variables in previous function scopes
12205 marks them so subsequent lookups find them unset until that function
12206 returns.
12207 This is identical to the behavior of unsetting local variables at the
12208 current function scope.
12209 .TP 8
12210 .B login_shell
12211 The shell sets this option if it is started as a login shell (see
12212 .SM
12213 .B "INVOCATION"
12214 .ie \n(zZ=1 in \fIbash\fP(1)).
12215 .el above).
12216 The value may not be changed.
12217 .TP 8
12218 .B mailwarn
12219 If set, and a file that \fBbash\fP is checking for mail has been
12220 accessed since the last time it was checked,
12221 \fBbash\fP displays the message
12222 .Q "The mail in \fImailfile\fP has been read" .
12223 .TP 8
12224 .B no_empty_cmd_completion
12225 If set, and
12226 .B readline
12227 is being used,
12228 .B bash
12229 does not search
12230 .SM
12231 .B PATH
12232 for possible completions when completion is attempted on an empty line.
12233 .TP 8
12234 .B nocaseglob
12235 If set,
12236 .B bash
12237 matches filenames in a case\-insensitive fashion when performing pathname
12238 expansion (see
12239 .B "Pathname Expansion"
12240 .ie \n(zZ=1 in \fIbash\fP(1)).
12241 .el above).
12242 .TP 8
12243 .B nocasematch
12244 If set,
12245 .B bash
12246 matches patterns in a case\-insensitive fashion when performing matching
12247 while executing \fBcase\fP or \fB[[\fP conditional commands,
12248 when performing pattern substitution word expansions,
12249 or when filtering possible completions as part of programmable completion.
12250 .TP 8
12251 .B noexpand_translation
12252 If set,
12253 .B bash
12254 encloses the translated results of
12255 .BR $\*" .\|.\|.\& \*"
12256 quoting in single quotes instead of double quotes.
12257 If the string is not translated, this has no effect.
12258 .TP 8
12259 .B nullglob
12260 If set, pathname expansion patterns which match no files
12261 (see
12262 .B "Pathname Expansion"
12263 .ie \n(zZ=1 in \fIbash\fP(1))
12264 .el above)
12265 expand to nothing and are removed, rather than expanding to themselves.
12266 .TP 8
12267 .B patsub_replacement
12268 If set, \fBbash\fP
12269 expands occurrences of \fB&\fP in the replacement string of pattern
12270 substitution to the text matched by the pattern, as described
12271 under \fBParameter Expansion\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
12277 If set, enable the programmable completion facilities (see
12278 \fBProgrammable Completion\fP
12279 .ie \n(zZ=1 in \fIbash\fP(1)).
12280 .el above).
12281 This option is enabled by default.
12282 .TP 8
12283 .B progcomp_alias
12284 If set, and programmable completion is enabled, \fBbash\fP treats a command
12285 name that doesn't have any completions as a possible alias and attempts
12286 alias expansion.
12287 If it has an alias, \fBbash\fP attempts programmable
12288 completion using the command word resulting from the expanded alias.
12289 .TP 8
12290 .B promptvars
12291 If set, prompt strings undergo
12292 parameter expansion, command substitution, arithmetic
12293 expansion, and quote removal after being expanded as described in
12294 .SM
12295 .B PROMPTING
12296 .ie \n(zZ=1 in \fIbash\fP(1).
12297 .el above.
12298 This option is enabled by default.
12299 .TP 8
12300 .B restricted_shell
12301 The shell sets this option if it is started in restricted mode
12302 (see
12303 .SM
12304 .B "RESTRICTED SHELL"
12305 .ie \n(zZ=1 in \fIbash\fP(1)).
12306 .el below).
12307 The value may not be changed.
12308 This is not reset when the startup files are executed, allowing
12309 the startup files to discover whether or not a shell is restricted.
12310 .TP 8
12311 .B shift_verbose
12312 If set, the
12313 .B shift
12314 builtin prints an error message when the shift count exceeds the
12315 number of positional parameters.
12316 .TP 8
12317 .B sourcepath
12318 If set, the
12319 \fB.\fP (\fBsource\fP) builtin uses the value of
12320 .SM
12321 .B PATH
12322 to find the directory containing the file supplied as an argument when
12323 the \fB\-p\fP option is not supplied.
12324 This option is enabled by default.
12325 .TP 8
12326 .B varredir_close
12327 If set, the shell automatically closes file descriptors assigned using the
12328 \fI{varname}\fP redirection syntax (see
12329 .SM
12330 .B REDIRECTION
12331 .ie \n(zZ=1 in \fIbash\fP(1))
12332 .el above)
12333 instead of leaving them open when the command completes.
12334 .TP 8
12335 .B syslog_history
12336 If set, command history is logged to syslog.
12337 .TP 8
12338 .B xpg_echo
12339 If set, the \fBecho\fP builtin expands backslash-escape sequences
12340 by default.
12341 If the \fBposix\fP shell option is also enabled, \fBecho\fP does not
12342 interpret any options.
12343 .RE
12344 .PD
12345 .TP
12346 \fBsuspend\fP [\fB\-f\fP]
12347 Suspend the execution of this shell until it receives a
12348 .SM
12349 .B SIGCONT
12350 signal.
12351 A login shell, or a shell without job control enabled,
12352 cannot be suspended; the
12353 .B \-f
12354 option will override this and force the suspension.
12355 The return status is 0 unless the shell is a login shell
12356 or job control is not enabled
12357 and
12358 .B \-f
12359 is not supplied.
12360 .TP
12361 \fBtest\fP \fIexpr\fP
12362 .PD 0
12363 .TP
12364 \fB[\fP \fIexpr\fP \fB]\fP
12365 .PD
12366 Return a status of 0 (true) or 1 (false) depending on
12367 the evaluation of the conditional expression
12368 .IR expr .
12369 Each operator and operand must be a separate argument.
12370 Expressions are composed of the primaries described
12371 .ie \n(zZ=1 in \fIbash\fP(1)
12372 .el above
12373 under
12374 .SM
12375 .BR "CONDITIONAL EXPRESSIONS" .
12376 \fBtest\fP does not accept any options, nor does it accept and ignore
12377 an argument of \fB\-\-\fP as signifying the end of options.
12378 .IP
12379 Expressions may be combined using the following operators, listed
12380 in decreasing order of precedence.
12381 The evaluation depends on the number of arguments; see below.
12382 \fBtest\fP uses operator precedence when there are five or more arguments.
12383 .RS
12384 .PD 0
12385 .TP
12386 .B ! \fIexpr\fP
12387 True if
12388 .I expr
12389 is false.
12390 .TP
12391 .B ( \fIexpr\fP )
12392 Returns the value of \fIexpr\fP.
12393 This may be used to override normal operator precedence.
12394 .TP
12395 \fIexpr1\fP \-\fBa\fP \fIexpr2\fP
12396 True if both
12397 .I expr1
12398 and
12399 .I expr2
12400 are true.
12401 .TP
12402 \fIexpr1\fP \-\fBo\fP \fIexpr2\fP
12403 True if either
12404 .I expr1
12405 or
12406 .I expr2
12407 is true.
12408 .PD
12409 .PP
12410 \fBtest\fP and \fB[\fP evaluate conditional
12411 expressions using a set of rules based on the number of arguments.
12412 .PP
12413 .PD 0
12414 .TP
12415 0 arguments
12416 The expression is false.
12417 .TP
12418 1 argument
12419 The expression is true if and only if the argument is not null.
12420 .TP
12421 2 arguments
12422 If the first argument is \fB!\fP, the expression is true if and
12423 only if the second argument is null.
12424 If the first argument is one of the unary conditional operators listed
12425 .ie \n(zZ=1 in \fIbash\fP(1)
12426 .el above
12427 under
12428 .SM
12429 .BR "CONDITIONAL EXPRESSIONS" ,
12430 the expression is true if the unary test is true.
12431 If the first argument is not a valid unary conditional operator, the expression
12432 is false.
12433 .TP
12434 3 arguments
12435 The following conditions are applied in the order listed.
12436 If the second argument is one of the binary conditional operators listed
12437 .ie \n(zZ=1 in \fIbash\fP(1)
12438 .el above
12439 under
12440 .SM
12441 .BR "CONDITIONAL EXPRESSIONS" ,
12442 the result of the expression is the result of the binary test using
12443 the first and third arguments as operands.
12444 The \fB\-a\fP and \fB\-o\fP operators are considered binary operators
12445 when there are three arguments.
12446 If the first argument is \fB!\fP, the value is the negation of
12447 the two-argument test using the second and third arguments.
12448 If the first argument is exactly \fB(\fP and the third argument is
12449 exactly \fB)\fP, the result is the one-argument test of the second
12450 argument.
12451 Otherwise, the expression is false.
12452 .TP
12453 4 arguments
12454 The following conditions are applied in the order listed.
12455 If the first argument is \fB!\fP, the result is the negation of
12456 the three-argument expression composed of the remaining arguments.
12457 If the first argument is exactly \fB(\fP and the fourth argument is
12458 exactly \fB)\fP, the result is the two-argument test of the second
12459 and third arguments.
12460 Otherwise, the expression is parsed and evaluated according to
12461 precedence using the rules listed above.
12462 .TP
12463 5 or more arguments
12464 The expression is parsed and evaluated according to precedence
12465 using the rules listed above.
12466 .PD
12467 .PP
12468 When the shell is in posix mode, or if the expression is part
12469 of the \fB[[\fP command,
12470 the \fB<\fP and \fB>\fP operators sort using the
12471 current locale.
12472 If the shell is not in posix mode, the \fBtest\fP and \fB[\fP
12473 commands sort lexicographically using ASCII ordering.
12474 .PP
12475 The historical operator-precedence parsing with 4 or more arguments can
12476 lead to ambiguities when it encounters strings that look like primaries.
12477 The
12478 .SM POSIX
12479 standard has deprecated the \fB\-a\fP and \fB\-o\fP
12480 primaries and enclosing expressions within parentheses.
12481 Scripts should no longer use them.
12482 It's much more reliable to restrict test invocations to a single primary,
12483 and to replace uses of \fB\-a\fP and \fB\-o\fP with the shell's
12484 \fB&&\fP and \fB||\fP list operators.
12485 .RE
12486 .TP
12487 .B times
12488 Print the accumulated user and system times for the shell and
12489 for processes run from the shell.
12490 The return status is 0.
12491 .TP
12492 \fBtrap\fP [\fB\-lpP\fP] [[\fIaction\fP] \fIsigspec\fP .\|.\|.]
12493 The
12494 .I action
12495 is a command that is read and executed when the shell receives
12496 any of the signals
12497 .IR sigspec .
12498 If
12499 .I action
12500 is absent (and there is a single \fIsigspec\fP) or
12501 .BR \- ,
12502 each specified \fIsigspec\fP is
12503 reset to the value it had when the shell was started.
12504 If
12505 .I action
12506 is the null string the signal specified by each
12507 .I sigspec
12508 is ignored by the shell and by the commands it invokes.
12509 .IP
12510 If no arguments are supplied,
12511 .B trap
12512 displays the actions associated with each trapped signal
12513 as a set of \fBtrap\fP commands
12514 that can be reused as shell input to
12515 restore the current signal dispositions.
12516 If
12517 .B \-p
12518 is given,
12519 and
12520 .I action
12521 is not present,
12522 then \fBtrap\fP displays the actions associated with each
12523 .I sigspec
12524 or, if none are supplied, for all trapped signals,
12525 as a set of \fBtrap\fP commands
12526 that can be reused as shell input to
12527 restore the current signal dispositions.
12528 The
12529 .B \-P
12530 option behaves similarly, but displays only the actions
12531 associated with each \fIsigspec\fP argument.
12532 .B \-P
12533 requires at least one \fIsigspec\fP argument.
12534 The \fB\-P\fP or \fB\-p\fP options may be used
12535 in a subshell environment (e.g., command substitution) and, as
12536 long as they are used before \fBtrap\fP is used to change a signal's
12537 handling, will display the state of its parent's traps.
12538 .IP
12539 The
12540 .B \-l
12541 option prints a list of signal names and
12542 their corresponding numbers.
12543 Each
12544 .I sigspec
12545 is either
12546 a signal name defined in <\fIsignal.h\fP>, or a signal number.
12547 Signal names are case insensitive and the
12548 .SM
12549 .B SIG
12550 prefix is optional.
12551 If \fB\-l\fP is supplied with no \fIsigspec\fP arguments, it prints a
12552 list of valid signal names.
12553 .IP
12554 If a
12555 .I sigspec
12556 is
12557 .SM
12558 .B EXIT
12559 (0),
12560 .I action
12561 is executed on exit from the shell.
12562 If a
12563 .I sigspec
12564 is
12565 .SM
12566 .BR DEBUG ,
12567 .I action
12568 is executed before every \fIsimple command\fP, \fIfor\fP command,
12569 \fIcase\fP command, \fIselect\fP command, (( arithmetic command,
12570 [[ conditional command,
12571 arithmetic \fIfor\fP command, and before the first command executes
12572 in a shell function (see
12573 .SM
12574 .B "SHELL GRAMMAR"
12575 .ie \n(zZ=1 in \fIbash\fP(1)).
12576 .el above).
12577 Refer to the description of the \fBextdebug\fP shell option
12578 (see
12579 .B shopt
12580 .ie \n(zZ=1 in \fIbash\fP(1))
12581 .el above)
12582 for details of its effect on the \fBDEBUG\fP trap.
12583 If a
12584 .I sigspec
12585 is
12586 .SM
12587 .BR RETURN ,
12588 .I action
12589 is executed each time a shell function or a script executed with
12590 the \fB.\fP or \fBsource\fP builtins finishes executing.
12591 .IP
12592 If a
12593 .I sigspec
12594 is
12595 .SM
12596 .BR ERR ,
12597 .I action
12598 is executed whenever
12599 a pipeline (which may consist of a single simple
12600 command), a list, or a compound command returns a
12601 non\-zero exit status,
12602 subject to the following conditions.
12603 The
12604 .SM
12605 .B ERR
12606 trap is not executed if the failed
12607 command is part of the command list immediately following a
12608 .B while
12609 or
12610 .B until
12611 reserved word,
12612 part of the test in an
12613 .I if
12614 statement, part of a command executed in a
12615 .B &&
12616 or
12617 .B ||
12618 list except the command following the final \fB&&\fP or \fB||\fP,
12619 any command in a pipeline but the last
12620 (subject to the state of the \fBpipefail\fP shell option),
12621 or if the command's return value is
12622 being inverted using
12623 .BR ! .
12624 These are the same conditions obeyed by the \fBerrexit\fP (\fB\-e\fP) option.
12625 .IP
12626 When the shell is not interactive,
12627 signals ignored upon entry to the shell cannot be trapped, reset or listed.
12628 Interactive shells permit trapping signals ignored on entry.
12629 Trapped signals that are not being ignored are reset to their original
12630 values in a subshell or subshell environment when one is created.
12631 The return status is false if any
12632 .I sigspec
12633 is invalid; otherwise
12634 .B trap
12635 returns true.
12636 .TP
12637 \fBtrue\fP
12638 Does nothing, returns a 0 status.
12639 .TP
12640 \fBtype\fP [\fB\-aftpP\fP] \fIname\fP [\fIname\fP .\|.\|.]
12641 Indicate how each
12642 .I name
12643 would be interpreted if used as a command name.
12644 .IP
12645 If the
12646 .B \-t
12647 option is used,
12648 .B type
12649 prints a string which is one of
12650 .IR alias ,
12651 .IR keyword ,
12652 .IR function ,
12653 .IR builtin ,
12654 or
12655 .I file
12656 if
12657 .I name
12658 is an alias, shell reserved word, function, builtin, or executable file,
12659 respectively.
12660 If the
12661 .I name
12662 is not found, \fBtype\fP prints nothing and returns a non-zero exit status.
12663 .IP
12664 If the
12665 .B \-p
12666 option is used,
12667 .B type
12668 either returns the pathname of the executable file
12669 that would be found by searching
12670 .B $PATH
12671 for
12672 .I name
12673 or nothing if
12674 .Q "type \-t name"
12675 would not return
12676 .IR file .
12677 The
12678 .B \-P
12679 option forces a
12680 .SM
12681 .B PATH
12682 search for each \fIname\fP, even if
12683 .Q "type \-t name"
12684 would not return
12685 .IR file .
12686 If \fIname\fP is present in the table of hashed commands,
12687 .B \-p
12688 and
12689 .B \-P
12690 print the hashed value, which is not necessarily the file that appears
12691 first in
12692 .SM
12693 .BR PATH .
12694 .IP
12695 If the
12696 .B \-a
12697 option is used,
12698 .B type
12699 prints all of the places that contain a command named
12700 .IR name .
12701 This includes aliases, reserved words, functions, and builtins,
12702 but the path search options (\fB\-p\fP and \fB\-P\fP)
12703 can be supplied to restrict the output to executable files.
12704 \fBtype\fP does not consult the table of hashed commands
12705 when using
12706 .B \-a
12707 with
12708 .BR \-p ,
12709 and only performs a
12710 .SM
12711 .B PATH
12712 search for \fIname\fP.
12713 .IP
12714 The
12715 .B \-f
12716 option suppresses shell function lookup, as with the \fBcommand\fP builtin.
12717 .B type
12718 returns true if all of the arguments are found, false if
12719 any are not found.
12720 .TP
12721 \fBulimit\fP [\fB\-HS\fP] \fB\-a\fP
12722 .PD 0
12723 .TP
12724 \fBulimit\fP [\fB\-HS\fP] [\fB\-bcdefiklmnpqrstuvxPRT\fP [\fIlimit\fP]]
12725 .PD
12726 Provides control over the resources available to the shell and to
12727 processes it starts, on systems that allow such control.
12728 .IP
12729 The \fB\-H\fP and \fB\-S\fP options specify whether
12730 the hard or soft limit is set for the given resource.
12731 A hard limit cannot be increased by a non-root user once it is set;
12732 a soft limit may be increased up to the value of the hard limit.
12733 If neither \fB\-H\fP nor \fB\-S\fP is specified,
12734 \fBulimit\fP sets both the soft and hard limits.
12735 .IP
12736 The value of
12737 .I limit
12738 can be a number in the unit specified for the resource
12739 or one of the special values
12740 .BR hard ,
12741 .BR soft ,
12742 or
12743 .BR unlimited ,
12744 which stand for the current hard limit, the current soft limit, and
12745 no limit, respectively.
12746 If
12747 .I limit
12748 is omitted, \fBulimit\fP prints the current value of the soft limit of
12749 the resource, unless the \fB\-H\fP option is given.
12750 When more than one resource is specified, the limit name and unit,
12751 if appropriate, are printed before the value.
12752 Other options are interpreted as follows:
12753 .RS
12754 .PD 0
12755 .TP
12756 .B \-a
12757 Report all current limits; no limits are set.
12758 .TP
12759 .B \-b
12760 The maximum socket buffer size.
12761 .TP
12762 .B \-c
12763 The maximum size of core files created.
12764 .TP
12765 .B \-d
12766 The maximum size of a process's data segment.
12767 .TP
12768 .B \-e
12769 The maximum scheduling priority (\c
12770 .Q nice ).
12771 .TP
12772 .B \-f
12773 The maximum size of files written by the shell and its children.
12774 .TP
12775 .B \-i
12776 The maximum number of pending signals.
12777 .TP
12778 .B \-k
12779 The maximum number of kqueues that may be allocated.
12780 .TP
12781 .B \-l
12782 The maximum size that may be locked into memory.
12783 .TP
12784 .B \-m
12785 The maximum resident set size (many systems do not honor this limit).
12786 .TP
12787 .B \-n
12788 The maximum number of open file descriptors (most systems do not
12789 allow this value to be set).
12790 .TP
12791 .B \-p
12792 The pipe size in 512-byte blocks (this may not be set).
12793 .TP
12794 .B \-q
12795 The maximum number of bytes in
12796 .SM POSIX
12797 message queues.
12798 .TP
12799 .B \-r
12800 The maximum real-time scheduling priority.
12801 .TP
12802 .B \-s
12803 The maximum stack size.
12804 .TP
12805 .B \-t
12806 The maximum amount of cpu time in seconds.
12807 .TP
12808 .B \-u
12809 The maximum number of processes available to a single user.
12810 .TP
12811 .B \-v
12812 The maximum amount of virtual memory available to the shell and, on
12813 some systems, to its children.
12814 .TP
12815 .B \-x
12816 The maximum number of file locks.
12817 .TP
12818 .B \-P
12819 The maximum number of pseudoterminals.
12820 .TP
12821 .B \-R
12822 The maximum time a real-time process can run before blocking, in microseconds.
12823 .TP
12824 .B \-T
12825 The maximum number of threads.
12826 .PD
12827 .PP
12828 If
12829 .I limit
12830 is supplied, and the
12831 .B \-a
12832 option is not used,
12833 \fIlimit\fP is the new value of the specified resource.
12834 If no option is supplied, then
12835 .B \-f
12836 is assumed.
12837 .PP
12838 Values are in 1024-byte increments, except for
12839 .BR \-t ,
12840 which is in seconds;
12841 .BR \-R ,
12842 which is in microseconds;
12843 .BR \-p ,
12844 which is in units of 512-byte blocks;
12845 .BR \-P ,
12846 .BR \-T ,
12847 .BR \-b ,
12848 .BR \-k ,
12849 .BR \-n ,
12850 and
12851 .BR \-u ,
12852 which are unscaled values;
12853 and, when in posix mode,
12854 .B \-c
12855 and
12856 .BR \-f ,
12857 which are in 512-byte increments.
12858 The return status is 0 unless an invalid option or argument is supplied,
12859 or an error occurs while setting a new limit.
12860 In POSIX Mode 512-byte blocks are used for the `-c' and `-f' options.
12861 .RE
12862 .TP
12863 \fBumask\fP [\fB\-p\fP] [\fB\-S\fP] [\fImode\fP]
12864 Set the user file-creation mask to
12865 .IR mode .
12866 If
12867 .I mode
12868 begins with a digit, it is interpreted as an octal number;
12869 otherwise it is interpreted as a symbolic mode mask similar
12870 to that accepted by
12871 .IR chmod (1).
12872 If
12873 .I mode
12874 is omitted, \fBumask\fP prints the current value of the mask.
12875 The
12876 .B \-S
12877 option without a \fImode\fP argument
12878 prints the mask in a symbolic format;
12879 the default output is an octal number.
12880 If the
12881 .B \-p
12882 option is supplied, and
12883 .I mode
12884 is omitted, the output is in a form that may be reused as input.
12885 The return status is zero if the mode was successfully changed or
12886 if no \fImode\fP argument was supplied, and non-zero otherwise.
12887 .TP
12888 \fBunalias\fP [\-\fBa\fP] [\fIname\fP .\|.\|.]
12889 Remove each \fIname\fP from the list of defined aliases.
12890 If
12891 .B \-a
12892 is supplied, remove all alias definitions.
12893 The return value is true unless a supplied
12894 .I name
12895 is not a defined alias.
12896 .TP
12897 \fBunset\fP [\-\fBfv\fP] [\-\fBn\fP] [\fIname\fP .\|.\|.]
12898 For each
12899 .IR name ,
12900 remove the corresponding variable or function.
12901 If the
12902 .B \-v
12903 option is given, each
12904 .I name
12905 refers to a shell variable, and that variable is removed.
12906 If
12907 .B \-f
12908 is specified, each
12909 .I name
12910 refers to a shell function, and the function definition
12911 is removed.
12912 If the
12913 .B \-n
12914 option is supplied, and \fIname\fP is a variable with the \fInameref\fP
12915 attribute, \fIname\fP will be unset rather than the variable it
12916 references.
12917 \fB\-n\fP has no effect if the \fB\-f\fP option is supplied.
12918 Read-only variables and functions may not be unset.
12919 When variables or functions are removed, they are also removed
12920 from the environment passed to subsequent commands.
12921 If no options are supplied, each \fIname\fP refers to a variable; if
12922 there is no variable by that name, a function with that name, if any, is
12923 unset.
12924 Some shell variables may not be unset.
12925 If any of
12926 .SM
12927 .BR BASH_ALIASES ,
12928 .SM
12929 .BR BASH_ARGV0 ,
12930 .SM
12931 .BR BASH_CMDS ,
12932 .SM
12933 .BR BASH_COMMAND ,
12934 .SM
12935 .BR BASH_SUBSHELL ,
12936 .SM
12937 .BR BASHPID ,
12938 .SM
12939 .BR COMP_WORDBREAKS ,
12940 .SM
12941 .BR DIRSTACK ,
12942 .SM
12943 .BR EPOCHREALTIME ,
12944 .SM
12945 .BR EPOCHSECONDS ,
12946 .SM
12947 .BR FUNCNAME ,
12948 .SM
12949 .BR GROUPS ,
12950 .SM
12951 .BR HISTCMD ,
12952 .SM
12953 .BR LINENO ,
12954 .SM
12955 .BR RANDOM ,
12956 .SM
12957 .BR SECONDS ,
12958 or
12959 .SM
12960 .B SRANDOM
12961 are unset, they lose their special properties, even if they are
12962 subsequently reset.
12963 The exit status is true unless a
12964 .I name
12965 is readonly or may not be unset.
12966 .TP
12967 \fBwait\fP [\fB\-fn\fP] [\fP\-p\fP \fIvarname\fP] [\fIid\fP .\|.\|.]
12968 Wait for each specified child process \fIid\fP and return the
12969 termination status of the last \fIid\fP.
12970 Each \fIid\fP may be a process ID \fIpid\fP
12971 or a job specification \fIjobspec\fP;
12972 if a jobspec is supplied, \fBwait\fP waits for all processes in the job.
12973 .IP
12974 If no options or \fIid\fPs are supplied,
12975 \fBwait\fP waits for all running background jobs and
12976 the last-executed process substitution,
12977 if its process id is the same as \fB$!\fP,
12978 and the return status is zero.
12979 .IP
12980 If the \fB\-n\fP option is supplied, \fBwait\fP waits for any one of
12981 the given \fIid\fPs or,
12982 if no \fIid\fPs are supplied, any job or process substitution,
12983 to complete and returns its exit status.
12984 If none of the supplied \fIid\fPs is a child of the shell,
12985 or if no \fIid\fPs are supplied and the shell has no unwaited-for children,
12986 the exit status is 127.
12987 .IP
12988 If the \fB\-p\fP option is supplied, \fBwait\fP assigns
12989 the process or job identifier of the job
12990 for which the exit status is returned to the
12991 variable \fIvarname\fP named by the option argument.
12992 The variable,
12993 which cannot be readonly,
12994 will be unset initially, before any assignment.
12995 This is useful only when used with the \fB\-n\fP option.
12996 .IP
12997 Supplying the \fB\-f\fP option, when job control is enabled,
12998 forces \fBwait\fP to wait for each \fIid\fP to terminate before
12999 returning its status, instead of returning when it changes status.
13000 .IP
13001 If none of the \fIid\fPs specify one of the shell's active child
13002 processes, the return status is 127.
13003 If \fBwait\fP is interrupted by a signal,
13004 any \fIvarname\fP will remain unset,
13005 and the return status will be greater
13006 than 128, as described under
13007 .B SIGNALS
13008 .ie \n(zZ=1 in \fIbash\fP(1).
13009 .el above.
13010 Otherwise, the return status is the exit status of the last \fIid\fP.
13011 .SH "SHELL COMPATIBILITY MODE"
13012 Bash-4.0 introduced the concept of a \fIshell compatibility level\fP,
13013 specified as a set of options to the shopt builtin (\c
13014 .BR compat31 ,
13015 .BR compat32 ,
13016 .BR compat40 ,
13017 .BR compat41 ,
13018 and so on).
13019 There is only one current
13020 compatibility level \(em each option is mutually exclusive.
13021 The compatibility level is intended to allow users to select behavior
13022 from previous versions that is incompatible with newer versions
13023 while they migrate scripts to use current features and behavior.
13024 It's intended to be a temporary solution.
13025 .PP
13026 This section does not mention behavior that is standard for a particular
13027 version (e.g., setting \fBcompat32\fP means that quoting the right hand
13028 side of the regexp
13029 matching operator quotes special regexp characters in the word, which is
13030 default behavior in bash-3.2 and subsequent versions).
13031 .PP
13032 If a user enables, say, \fBcompat32\fP, it may affect the behavior of other
13033 compatibility levels up to and including the current compatibility level.
13034 The idea is that each compatibility level controls behavior that changed
13035 in that version of \fBbash\fP,
13036 but that behavior may have been present in earlier versions.
13037 For instance, the change to use locale-based comparisons with the \fB[[\fP
13038 command came in bash-4.1, and earlier versions used ASCII-based comparisons,
13039 so enabling \fBcompat32\fP will enable ASCII-based comparisons as well.
13040 That granularity may not be sufficient for
13041 all uses, and as a result users should employ compatibility levels carefully.
13042 Read the documentation for a particular feature to find out the
13043 current behavior.
13044 .PP
13045 Bash-4.3 introduced a new shell variable:
13046 .SM
13047 .BR BASH_COMPAT .
13048 The value assigned
13049 to this variable (a decimal version number like 4.2, or an integer
13050 corresponding to the \fBcompat\fP\fINN\fP option, like 42) determines the
13051 compatibility level.
13052 .PP
13053 Starting with bash-4.4, \fBbash\fP began deprecating older compatibility
13054 levels.
13055 Eventually, the options will be removed in favor of
13056 .SM
13057 .BR BASH_COMPAT .
13058 .PP
13059 Bash-5.0 was the final version for which there was an individual shopt
13060 option for the previous version.
13061 .SM
13062 .B BASH_COMPAT
13063 is the only mechanism to control the compatibility level
13064 in versions newer than bash-5.0.
13065 .PP
13066 The following table describes the behavior changes controlled by each
13067 compatibility level setting.
13068 The \fBcompat\fP\fINN\fP tag is used as shorthand for setting the
13069 compatibility level
13070 to \fINN\fP using one of the following mechanisms.
13071 For versions prior to bash-5.0, the compatibility level may be set using
13072 the corresponding \fBcompat\fP\fINN\fP shopt option.
13073 For bash-4.3 and later versions, the
13074 .SM
13075 .B BASH_COMPAT
13076 variable is preferred,
13077 and it is required for bash-5.1 and later versions.
13078 .TP
13079 \fBcompat31\fP
13080 .PD 0
13081 .RS
13082 .IP \(bu
13083 Quoting the rhs of the \fB[[\fP command's regexp matching operator (=\*~)
13084 has no special effect.
13085 .RE
13086 .PD
13087 .TP
13088 \fBcompat32\fP
13089 .PD 0
13090 .RS
13091 .IP \(bu
13092 The \fB<\fP and \fB>\fP operators to the \fB[[\fP command do not
13093 consider the current locale when comparing strings; they use ASCII
13094 ordering.
13095 .RE
13096 .PD
13097 .TP
13098 \fBcompat40\fP
13099 .PD 0
13100 .RS
13101 .IP \(bu
13102 The \fB<\fP and \fB>\fP operators to the \fB[[\fP command do not
13103 consider the current locale when comparing strings; they use ASCII
13104 ordering.
13105 \fBBash\fP versions prior to bash-4.1 use ASCII collation and
13106 .IR strcmp (3);
13107 bash-4.1 and later use the current locale's collation sequence and
13108 .IR strcoll (3).
13109 .RE
13110 .PD
13111 .TP
13112 \fBcompat41\fP
13113 .PD 0
13114 .RS
13115 .IP \(bu
13116 In posix mode, \fBtime\fP may be followed by options and still be
13117 recognized as a reserved word (this is
13118 .SM POSIX
13119 interpretation 267).
13120 .IP \(bu
13121 In \fIposix\fP mode, the parser requires that an even number of single
13122 quotes occur in the \fIword\fP portion of a double-quoted
13123 parameter expansion and treats them specially, so that characters within
13124 the single quotes are considered quoted
13125 (this is
13126 .SM POSIX
13127 interpretation 221).
13128 .RE
13129 .PD
13130 .TP
13131 \fBcompat42\fP
13132 .PD 0
13133 .RS
13134 .IP \(bu
13135 The replacement string in double-quoted pattern substitution does not
13136 undergo quote removal, as it does in versions after bash-4.2.
13137 .IP \(bu
13138 In posix mode, single quotes are considered special when expanding
13139 the \fIword\fP portion of a double-quoted parameter expansion
13140 and can be used to quote a closing brace or other special character
13141 (this is part of
13142 .SM POSIX
13143 interpretation 221);
13144 in later versions, single quotes
13145 are not special within double-quoted word expansions.
13146 .RE
13147 .PD
13148 .TP
13149 \fBcompat43\fP
13150 .PD 0
13151 .RS
13152 .IP \(bu
13153 Word expansion errors are considered non-fatal errors that cause the
13154 current command to fail, even in posix mode
13155 (the default behavior is to make them fatal errors that cause the shell
13156 to exit).
13157 .IP \(bu
13158 When executing a shell function, the loop state (while/until/etc.)
13159 is not reset, so \fBbreak\fP or \fBcontinue\fP in that function will break
13160 or continue loops in the calling context.
13161 Bash-4.4 and later reset the loop state to prevent this.
13162 .RE
13163 .PD
13164 .TP
13165 \fBcompat44\fP
13166 .PD 0
13167 .RS
13168 .IP \(bu
13169 The shell sets up the values used by
13170 .SM
13171 .B BASH_ARGV
13172 and
13173 .SM
13174 .B BASH_ARGC
13175 so they can expand to the shell's positional parameters even if extended
13176 debugging mode is not enabled.
13177 .IP \(bu
13178 A subshell inherits loops from its parent context, so \fBbreak\fP
13179 or \fBcontinue\fP will cause the subshell to exit.
13180 Bash-5.0 and later reset the loop state to prevent the exit
13181 .IP \(bu
13182 Variable assignments preceding builtins like \fBexport\fP and \fBreadonly\fP
13183 that set attributes continue to affect variables with the same
13184 name in the calling environment even if the shell is not in posix
13185 mode.
13186 .RE
13187 .PD
13188 .TP
13189 \fBcompat50\fP
13190 .PD 0
13191 .RS
13192 .IP \(bu
13193 Bash-5.1 changed the way
13194 .SM
13195 .B $RANDOM
13196 is generated to introduce slightly more randomness.
13197 If the shell compatibility level is set to 50 or
13198 lower, it reverts to the method from bash-5.0 and previous versions,
13199 so seeding the random number generator by assigning a value to
13200 .SM
13201 .B RANDOM
13202 will produce the same sequence as in bash-5.0.
13203 .IP \(bu
13204 If the command hash table is empty, bash versions prior to bash-5.1
13205 printed an informational message to that effect, even when producing
13206 output that can be reused as input.
13207 Bash-5.1 suppresses that message
13208 when the \fB\-l\fP option is supplied.
13209 .RE
13210 .PD
13211 .TP
13212 \fBcompat51\fP
13213 .PD 0
13214 .RS
13215 .IP \(bu
13216 The \fBunset\fP builtin treats attempts to unset array subscripts \fB@\fP
13217 and \fB*\fP differently depending on whether the array is indexed or
13218 associative, and differently than in previous versions.
13219 .IP \(bu
13220 Arithmetic commands (
13221 .BR (( .\|.\|.\& ))
13222 ) and the expressions in an arithmetic for
13223 statement can be expanded more than once.
13224 .IP \(bu
13225 Expressions used as arguments to arithmetic operators in the \fB[[\fP
13226 conditional command can be expanded more than once.
13227 .IP \(bu
13228 The expressions in substring parameter brace expansion can be
13229 expanded more than once.
13230 .IP \(bu
13231 The expressions in the
13232 .BR $(( .\|.\|.\& ))
13233 word expansion can be expanded more than once.
13234 .IP \(bu
13235 Arithmetic expressions used as indexed array subscripts can be
13236 expanded more than once.
13237 .IP \(bu
13238 \fBtest \-v\fP, when given an argument of \fBA[@]\fP, where \fBA\fP is
13239 an existing associative array, will return true if the array has any set
13240 elements.
13241 Bash-5.2 will look for and report on a key named \fB@\fP.
13242 .IP \(bu
13243 The ${\fIparameter\fP\fB[:]=\fP\fIvalue\fP} word expansion will return
13244 \fIvalue\fP, before any variable-specific transformations have been
13245 performed (e.g., converting to lowercase).
13246 Bash-5.2 will return the final value assigned to the variable.
13247 .IP \(bu
13248 Parsing command substitutions will behave as if extended globbing
13249 (see the description of the
13250 .B shopt
13251 builtin above)
13252 is enabled, so that parsing a command substitution containing an extglob
13253 pattern (say, as part of a shell function) will not fail.
13254 This assumes the intent is to enable extglob before the command is executed
13255 and word expansions are performed.
13256 It will fail at word expansion time if extglob hasn't been
13257 enabled by the time the command is executed.
13258 .RE
13259 .PD
13260 .TP
13261 \fBcompat52\fP
13262 .PD 0
13263 .RS
13264 .IP \(bu
13265 The \fBtest\fP builtin uses its historical algorithm to parse parenthesized
13266 subexpressions when given five or more arguments.
13267 .IP \(bu
13268 If the \fB\-p\fP or \fB\-P\fP option is supplied to the \fBbind\fP builtin,
13269 \fBbind\fP treats any arguments remaining after option processing
13270 as bindable command names, and
13271 displays any key sequences bound to those commands, instead of treating
13272 the arguments as key sequences to bind.
13273 .RE
13274 .PD
13275 .\" bash_builtins
13276 .if \n(zZ=1 .ig zZ
13277 .SH "RESTRICTED SHELL"
13278 .\" rbash.1
13279 .zY
13280 .PP
13281 If
13282 .B bash
13283 is started with the name
13284 .BR rbash ,
13285 or the
13286 .B \-r
13287 option is supplied at invocation, the shell becomes \fIrestricted\fP.
13288 A restricted shell is used to
13289 set up an environment more controlled than the standard shell.
13290 It behaves identically to
13291 .B bash
13292 with the exception that the following are disallowed or not performed:
13293 .IP \(bu
13294 Changing directories with \fBcd\fP.
13295 .IP \(bu
13296 Setting or unsetting the values of
13297 .SM
13298 .BR SHELL ,
13299 .SM
13300 .BR PATH ,
13301 .SM
13302 .BR HISTFILE ,
13303 .SM
13304 .BR ENV ,
13305 or
13306 .SM
13307 .BR BASH_ENV .
13308 .IP \(bu
13309 Specifying command names containing
13310 .BR / .
13311 .IP \(bu
13312 Specifying a filename containing a
13313 .B /
13314 as an argument to the
13315 .B .
13316 builtin command.
13317 .IP \(bu
13318 Using the \fB\-p\fP option to the
13319 .B .
13320 builtin command to specify a search path.
13321 .IP \(bu
13322 Specifying a filename containing a slash as an argument to the
13323 .B history
13324 builtin command.
13325 .IP \(bu
13326 Specifying a filename containing a slash as an argument to the
13327 .B \-p
13328 option to the
13329 .B hash
13330 builtin command.
13331 .IP \(bu
13332 Importing function definitions from the shell environment at startup.
13333 .IP \(bu
13334 Parsing the values of
13335 .SM
13336 .B BASHOPTS
13337 and
13338 .SM
13339 .B SHELLOPTS
13340 from the shell environment at startup.
13341 .IP \(bu
13342 Redirecting output using the >, >|, <>, >&, &>, and >> redirection operators.
13343 .IP \(bu
13344 Using the
13345 .B exec
13346 builtin command to replace the shell with another command.
13347 .IP \(bu
13348 Adding or deleting builtin commands with the
13349 .B \-f
13350 and
13351 .B \-d
13352 options to the
13353 .B enable
13354 builtin command.
13355 .IP \(bu
13356 Using the \fBenable\fP builtin command to enable disabled shell builtins.
13357 .IP \(bu
13358 Specifying the
13359 .B \-p
13360 option to the
13361 .B command
13362 builtin command.
13363 .IP \(bu
13364 Turning off restricted mode with
13365 \fBset +r\fP or \fBshopt \-u restricted_shell\fP.
13366 .PP
13367 These restrictions are enforced after any startup files are read.
13368 .PP
13369 .ie \n(zY=1 When a command that is found to be a shell script is executed,
13370 .el \{ When a command that is found to be a shell script is executed
13371 (see
13372 .SM
13373 .B "COMMAND EXECUTION"
13374 above),
13375 .\}
13376 .B rbash
13377 turns off any restrictions in the shell spawned to execute the
13378 script.
13379 .\" end of rbash.1
13380 .if \n(zY=1 .ig zY
13381 .SH "SEE ALSO"
13382 .PD 0
13383 .TP
13384 \fIBash Reference Manual\fP, Brian Fox and Chet Ramey
13385 .TP
13386 \fIThe Gnu Readline Library\fP, Brian Fox and Chet Ramey
13387 .TP
13388 \fIThe Gnu History Library\fP, Brian Fox and Chet Ramey
13389 .TP
13390 \fIPortable Operating System Interface (POSIX) Part 2: Shell and Utilities\fP, IEEE \(em
13391 http://pubs.opengroup.org/onlinepubs/9799919799/
13392 .TP
13393 http://tiswww.case.edu/\*~chet/bash/POSIX \(em a description of posix mode
13394 .TP
13395 \fIsh\fP(1), \fIksh\fP(1), \fIcsh\fP(1)
13396 .TP
13397 \fIemacs\fP(1), \fIvi\fP(1)
13398 .TP
13399 \fIreadline\fP(3)
13400 .PD
13401 .SH FILES
13402 .PD 0
13403 .TP
13404 .FN /bin/bash
13405 The \fBbash\fP executable
13406 .TP
13407 .FN /etc/profile
13408 The systemwide initialization file, executed for login shells
13409 .TP
13410 .FN /etc/bash.bash_logout
13411 The systemwide login shell cleanup file, executed when a login shell exits
13412 .TP
13413 .FN \*~/.bash_profile
13414 The personal initialization file, executed for login shells
13415 .TP
13416 .FN \*~/.bashrc
13417 The individual per-interactive-shell startup file
13418 .TP
13419 .FN \*~/.bash_logout
13420 The individual login shell cleanup file, executed when a login shell exits
13421 .TP
13422 .FN \*~/.bash_history
13423 The default value of \fBHISTFILE\fP, the file in which bash saves the
13424 command history
13425 .TP
13426 .FN \*~/.inputrc
13427 Individual \fIreadline\fP initialization file
13428 .PD
13429 .SH AUTHORS
13430 Brian Fox, Free Software Foundation
13431 .br
13432 [email protected]
13433 .PP
13434 Chet Ramey, Case Western Reserve University
13435 .br
13436 [email protected]
13437 .SH BUG REPORTS
13438 If you find a bug in
13439 .BR bash ,
13440 you should report it. But first, you should
13441 make sure that it really is a bug, and that it appears in the latest
13442 version of
13443 .BR bash .
13444 The latest version is always available from
13445 \fIftp://ftp.gnu.org/pub/gnu/bash/\fP and
13446 \fIhttp://git.savannah.gnu.org/cgit/bash.git/snapshot/bash-master.tar.gz\fP.
13447 .PP
13448 Once you have determined that a bug actually exists, use the
13449 .I bashbug
13450 command to submit a bug report.
13451 If you have a fix, you are encouraged to mail that as well!
13452 You may send suggestions and
13453 .Q philosophical
13454 bug reports to \[email protected]\fP or post them to the Usenet
13455 newsgroup
13456 .BR gnu.bash.bug .
13457 .PP
13458 ALL bug reports should include:
13459 .PP
13460 .PD 0
13461 .TP 20
13462 The version number of \fBbash\fP
13463 .TP
13464 The hardware and operating system
13465 .TP
13466 The compiler used to compile
13467 .TP
13468 A description of the bug behavior
13469 .TP
13470 A short script or \c
13471 .Q recipe " \c"
13472 which exercises the bug
13473 .PD
13474 .PP
13475 .I bashbug
13476 inserts the first three items automatically into the template
13477 it provides for filing a bug report.
13478 .PP
13479 Comments and bug reports concerning
13480 this manual page should be directed to
13481 .IR [email protected] .
13482 .SH BUGS
13483 It's too big and too slow.
13484 .PP
13485 There are some subtle differences between
13486 .B bash
13487 and traditional versions of
13488 .BR sh ,
13489 mostly because of the
13490 .SM POSIX
13491 specification.
13492 .PP
13493 Aliases are confusing in some uses.
13494 .PP
13495 Shell builtin commands and functions are not stoppable/restartable.
13496 .PP
13497 Compound commands and command lists of the form
13498 .Q "a ; b ; c"
13499 are not handled gracefully when combined with process suspension.
13500 When a process is stopped, the shell immediately executes the next
13501 command in the list or breaks out of any existing loops.
13502 It suffices to enclose the command in parentheses to
13503 force it into a subshell, which may be stopped as a unit,
13504 or to start the command in the background and immediately
13505 bring it into the foreground.
13506 .PP
13507 Array variables may not (yet) be exported.
13508 .zZ
13509 .zY