Debian Codegraph @

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